Listener Channel Configuration - XML Reference

<channel> element

Child of the <channels> element.

This is the parent element used to define a listener channel.

Syntax:

<channel name="channel-name" protocol="{TN3270 | MFBINP | HTTP | MQ | P2P | DCAS}
  port="port-number" enabled="{yes | no}" />

name attribute

A name that identifies the listener channel in console messages.

protocol attribute

The communication protocol of the listener channel.

port attribute

The port on which the channel listens.

enabled attribute

Specifies whether or not the listener is enabled.

The seelistener.exe.config file contains a <channel> element for TN3270, defined as follows:

<channel name="TN3270" protocol="tn3270" port="9023" enabled="yes">
</channel>

<ssl> element

Child of the <channel> element.

This element enables SSL and defines SSL client authorization, ELF configuration, and DCAS configuration by way of child elements.

<certificate> element

Child of the <ssl> element.

Defines the type of certificate storage, and is mandatory. If omitted, the channel is disabled and cannot be used.

Syntax:

<certificate {file="file-path" [passphrase="passphrase"] |
  store="{CurrentUser | LocalMachine} [name="X"]}" />

file attribute

Store certificates in a file. The value of this attribute is the full path to and file name of the certificate file.

Note: If the certificate file is secured by a private key, you must also specify the passphrase attribute.

passphrase attribute

Specifies the passphrase required to unlock a certificate file. Required only when the certificate file specified by the file attribute is secured by a private key.

store attribute

Store certificates in a Windows store. The value of this attribute can be either CurrentUser or LocalMachine (default)to specify, which type of Windows certificate store is used.

name attribute

The name on which to search the specified Windows certificate store for a matching certificate that is suitable for use as a server certificate. For more information, see the Microsoft .NET Framework documentation for the X509Store and X509Certificate2Collection classes.

<clientAuth> element

Child of the <ssl> element.

This element configures SSL client authorization.

Syntax:

<clientAuth certificateOption="{Allowed | Requested | Required}"
  [checkRevocation="{True | False}"] [checkUsage="{True | False}"]
   [matchHostname="{True | False}"] submitCertificateDetails="{True | False}" />

certificateOption attribute

Determines whether client certificates are allowed but not requested, requested but not required, or required. Valid values are:

Allowed

Default. Client certificates are allowed but not requested.

Requested

Client certificates are requested but not required.

Required

Client certificates are required.

Note: Some clients send a certificate only when the channel is configured to require, not merely allow, client certificates.

checkRevocation attribute

Check for client certificate revocation. Set to True or False (default).

checkUsage attribute

Check client certificate key-usage permissions. Set to True (default) or False.

matchHostname attribute

Specifies whether or not the client certificate name must match client host name. Set to True (default) or False.

<elf> element

Child of the <clientAuth> element.

This element enables ELF, and configures communications with DCAS.

Syntax:

<elf [applidTemplate="format-string"] [dcasUserid="user-id"] />

applidTemplate attribute

The applidTemplate attribute controls the APPLID passed in the DCAS request.

Default value

The default value sent for the applidTemplate attribute when it is not specified is an arbitrary APPLID sent by the client, or, if the client does not supply an APPLID, the value is the region name.

Consider omitting this attribute if your organization uses the same DCAS security rules for all regions. However, if you use different security values for different APPLIDs, you should explicitly set the applidTemplate attribute. This is important because DCAS uses the APPLID in its security check.

Note: Any APPLID string sent by the client is forced to conform to the syntax for an IBM VSAM name, meaning:

• Only English letters, digits, and the punctuation characters "@", "#", and "$" are allowed; all characters outside of these, if included, are removed from the string.
• Letters are folded to upper case.
• The string is truncated at eight characters.

format-string

When specified, the value of applidTemplate is a .NET composite formatting string with up to three replacement parameters, including one or more of the following values:

{0}

Replaced with the APPLID sent by the client.

{1}

Replaced with the region name, regardless of what is sent by the client.

{2}

Replaced with the database instance name.

For example, setting this attribute to {1} forces the APPLID in the DCAS request to be the region name, regardless of what the client sends.

As another example, if the value of applidTemplate is set to {0}-{1}, and:

• The client sends an APPLID of CICS
• The region name is ESDEMO

The APPLID sent to DCAS would be CICS-ESDEMO.

For more information, see the Composite Formatting topic in your Microsoft documentation.

dcasUserID attribute

The dcasUserID attribute specifies the user ID used to invoke the DCAS system transaction.

Default value

If you choose not to set this attribute, the DCAS request executes under the default CICS user ID.

user-id

Specify a user ID known to the region, such as SYSAD, or, as an additional security measure, you can set the dcasUserID attribute to restrict access to the DCAS system transaction by user name. To do this, set the value of this attribute to the name of a user with permission to execute the transaction, which has the hexadecimal name x'ffc4c3c1'.