TCP/IP service definition attributes

The TCP/IP service definition attribute descriptions are:

Attachsec
specifies the level of attach-time security required for TCP/IP connections to CICS® Clients.
LOCAL
specifies that CICS does not require a user ID or password from clients.
VERIFY
specifies that incoming attach requests must specify a user identifier and a user password. Specify VERIFY when connecting systems are unidentified and cannot be trusted.
NOTAPPLIC
means that a value for PROTOCOL other than ECI has been specified.

Values other than NOTAPPLIC apply only when PROTOCOL(ECI) is specified.

Authenticate
specifies the authentication and identification scheme to be used for inbound TCP/IP connections for the HTTP and IIOP protocols. Each protocol supports a different set of authentication schemes. For the ECI protocol, this attribute is invalid.

When PROTOCOL(HTTP) is specified:

NO
The client is not required to send authentication or identification information. However, if the client sends a valid certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client.
BASIC
HTTP Basic authentication is used to obtain a user ID and password from the client. If an invalid user ID and password are supplied, the process is repeated until valid information is supplied, or until the end user cancels the connection.

When the end user has been successfully authenticated, the user ID supplied identifies the client.

CERTIFICATE
SSL client certificate authentication is used to authenticate and identify the client. The client must send a valid certificate which is already registered to the security manager, and associated with a user ID. If a valid certificate is not received, or the certificate is not associated with a user ID, the connection is rejected.

When the end user has been successfully authenticated, the user ID associated with the certificate identifies the client.

Note:
If you specify AUTHENTICATE(CERTIFICATE), you must also specify SSL(CLIENTAUTH).
AUTOREGISTER
SSL client certificate authentication is used to authenticate the client.
  • If the client sends a valid certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client.
  • If the client sends a valid certificate that is not registered to the security manager, then HTTP Basic authentication is used to obtain a user ID and password from the client. Provided that the password is valid, CICS registers the certificate with the security manager, and associates it with the user ID. The user ID identifies the client.
Note:
If you specify AUTHENTICATE(CERTIFICATE), you must also specify SSL(CLIENTAUTH).
AUTOMATIC
This combines the AUTOREGISTER and BASIC functions.
  • If the client sends a certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client.
  • If the client sends a certificate that is not registered to the security manager, then HTTP Basic authentication is used to obtain a user ID and password from the client. Provided that the password is valid, CICS registers the certificate with the security manager, and associates it with the user ID. The user ID identifies the client.
  • If the client does not send a certificate, then HTTP Basic authentication is used to obtain a user ID and password from the user. When the end user has been successfully authenticated, the user ID supplied identifies the client.
ASSERTED
Asserted identity authentication is used.

When PROTOCOL(IIOP) is specified:

NO
The client is not required to send authentication or identification information. However, if the client sends a valid certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client.
CERTIFICATE
SSL client certificate authentication is used to authenticate and identify the client. The client must send a valid certificate which is already registered to the security manager, and associated with a user ID. If a valid certificate is not received, or the certificate is not associated with a user ID, the connection is rejected.

When the end user has been successfully authenticated, the user ID associated with the certificate identifies the client.

Note:
If you specify AUTHENTICATE(CERTIFICATE), you must also specify SSL(CLIENTAUTH).
ASSERTED
Asserted identity authentication is used
Note:
For the HTTP protocol, the analyzer program may change the user ID supplied by the authentication process. If the authentication process does not supply a user ID, the analyzer program may supply one; if the analyzer program does not supply one, the default user ID is used.

For the IIOP protocol, the IIOP user-replaceable program may supply a user ID if the authentication process does not supply one; if the user-replaceable program does not supply one, the default user ID is used.

For more information, see CICS RACF® Security Guide.
Backlog
specifies the number of TCP/IP connections for this service which are queued in TCP/IP before TCP/IP starts to reject incoming client requests.
Certificate
specifies the label of an X.509 certificate that is used as a server certificate during the SSL handshake for the TCP/IP service. If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used.

Certificate labels can be up to 32 bytes long.

The certificate must be stored in a key ring in the external security manager's database. For more information, see CICS RACF Security Guide.

This attribute cannot be specified unless SSL(YES) or SSL(CLIENTAUTH) is also specified.

Start of changeCiphersEnd of change
Start of change(Optional) specifies a value up to 28 cipher suites, in the form of hexadecimal pairs. Any hexadecimal can be specified, but currently the only recognized values are 01, 02, 03, 04, 05, 06, 09, 0A, 2F, and 35. Additional values can be added at a later time. No separating characters are necessary between each pair.

The default is blank.

Ciphers is valid only on CICS Transaction Server 3.1 and later systems. More information is provided in the table showing the cipher suites supported by z/OS and CICS, see CICS RACF Security Guide.

End of change
Description
(Optional.) Specifies a 1- to 30-character description of the resource.
DNS Group
(Optional) Specifies the group name with which CICS will register to OS/390® workload manager, for connection optimization. The value may be up to 18 characters, and any trailing blanks are ignored. This parameter is referred to as group_name by the TCP/IP DNS documentation and is the name of a cluster of equivalent server applications in a sysplex. It is also the name within the sysplex domain that clients use to access the CICS TCP/IP service.

More than one TCP/IP service may specify the same group name. The register call is made to WLM when the first service with a specified group name is opened. Subsequent services with the same group name do not cause more register calls to be made. The deregister action is dictated by the GRP Critical attribute. It is also possible to explicitly deregister CICS from a group by issuing a master terminal or SPI command.

GRP Critical
(Optional) Marks the service as a critical member of the DNS group, meaning that this service closing or failing causes a deregister call to be made to WLM for this group name. The default is NO, allowing two or more services in the same group to fail independently and CICS still remains registered to the group. Only when the last service in a group is closed is the deregister call made to WLM, if it has not already been done so explicitly. Multiple services with the same group name can have different GRP Critical settings. The services specifying GRP Critical (NO) can be closed or fail without causing a deregister. If a service with GRP Critical (YES) is closed or fails, the group is deregistered from WLM.
NO
The group is not critical to the DNS group.
YES
The group is critical to the DNS group.
Name
Specify a 1- to 8-character name for the TCP/IP service definition.
Portnumber
specifies, in the range 1 through 65535, the decimal number of the port on which CICS is to listen for incoming client requests.

The well-known ports are those from 0 through 1023. It is advisable to use well known port numbers only for those services to which they are normally assigned. The well known ports for services supported by CICS are:

80
HTTP (non-SSL)
443
HTTP with SSL
683
IIOP (non-SSL)
684
IIOP with SSL
1435
ECI

You should take care to resolve conflicts with any other servers on the same MVS™ image that might use the well-known ports.

Port sharing has to be enabled for any port that you want to share across CICS systems within an MVS image. For more information, see CICS Performance Guide

Privacy
specifies the level of SSL encryption required for inbound IIOP connections to this service.

This attribute applies only when PROTOCOL(IIOP) is specified.

During the SSL handshake, the client and server advertise which cipher suites they support, and, from those they both support, select the suite that offers the most secure level of encryption. For more information about cipher suites, see CICS RACF Security Guide.

REQUIRED
Encryption must be used. During the SSL handshake, CICS advertises only supported cipher suites that provide encryption.
SUPPORTED
Encryption is used if both client and server support it. During the SSL handshake, CICS advertises all supported cipher suites.
NOTSUPPORTED
Encryption must not be used. During the SSL handshake, CICS advertises only supported cipher suites that do not provide encryption.
NOTAPPLIC
Encryption is not applicable if SSL is not used.
Protocol
specifies the application level protocol used on the TCP/IP port.
ECI
The CICS ECI protocol is used.
HTTP
HTTP protocol is used. HTTP protocol is handled by CICS Web support.
IIOP
IIOP protocol is used. Specify IIOP for TCPIPSERVICEs that are to accept inbound requests for enterprise beans.
NOTAPPLIC
NOTAPPLIC causes CICS to use the default, HTTP, which requires a URM to be specified.
RESGROUP
(Optional.) Specify the name of an existing resource group to which the definition is to be automatically added.
SocketClose
specifies if, and for how long, CICS should wait before closing the socket, after issuing a receive for incoming data on that socket.
No
The socket is left open until data is received, or until it is closed by the client. While the socket is open it is unavailable to other tasks, and its associated CICS task is suspended indefinitely.
Note:
If you specify PROTOCOL(ECI) you must also specify SOCKETCLOSE(NO).
0-240000
The period of time (in HHMMSS format) after which CICS is to close the socket. Specifying 000000 closes the socket immediately if no data is available for any RECEIVEs other than the first one.
SSL
specifies whether the TCP/IP service is to use the secure sockets layer (SSL) for encryption and authentication:
NO
SSL is not to be used.
YES
An SSL session is to be used; CICS will send a server certificate to the client.
CLIENTAUTH
An SSL session is to be used; CICS will send a server certificate to the client, and the client must send a client certificate to CICS.
Status
Indicates the initial status of the service after installation. Set it to OPEN if CICS is to begin listening for this service after installation. Set to CLOSE if CICS is not to listen on behalf of this service after installation.
Transaction
specifies the 4-character ID of the CICS transaction attached to process new requests received for this service.
TSQprefix
specifies the 6-character prefix of the temporary storage queue used to store inbound data and Web documents created by applications.
URM
specifies the name of a user-replaceable program to be invoked by this service. The name you specify depends upon the value of the PROTOCOL attribute:
User data
Three 8-character fields provided for any site-specific data related to the TCP/IP service. CICSPlex® SM makes no use of this user data.
Version
(Optional.) Specify an integer in the range 1 through 15. Specify 0 or leave blank for CICSPlex SM to assign the first available version id in the range 1 through 15.

Related concepts
TCP/IP service resource definitions
CICS Resource Definition Guide
Related tasks
Accessing BAS TCP/IP service definitions
Working with the TCPDEF view
Defining TCP/IP services using BAS
Installing a BAS TCP/IP service definition
[[ Contents Previous Page | Next Page Index ]]