SIOCTTLSCTL (X'C038D90B')

The SIOCTTLSCTL ioctl provides an interface for the application to query and control AT-TLS for the connection. The following data items are returned by theSIOCTTLSCTL ioctl:

TTLSi_Stat_Policy

Indicates the level of AT-TLS enablement for the connection. Possible values include the following ones:

TTLS_POL_OFF (1): AT-TLS was not enabled on the stack when AT-TLS policy mapping was performed for the connection

TTLS_POL_NO_POLICY (2): No matching policy rule was found when AT-TLS policy mapping was performed for the connection. The application should issue a message, if appropriate, directing the system administrator to create a policy rule that matches this connection.

TTLS_POL_NOT_ENABLED (3): The policy rule that matches this connection indicates that AT-TLS should not be used. The application should issue a message, if appropriate, directing the system administrator to change the policy rule for this connection.

TTLS_POL_ENABLED (4): AT-TLS is enabled for this connection, but application control has not been granted. The application should issue a message, if appropriate, directing the system administrator to change the policy rule to enable application control for this connection.

TTLS_POL_APPLCNTRL (5): AT-TLS is enabled and is application controllable.

TTLSi_Stat_Conn

Indicates the current level of secure session on the connection.

TTLS_CONN_NOTSECURE (1): The connection does not have a secure session established.

TTLS_CONN_HS_INPROGRESS (2): Connection initial handshake in progress.

TTLS_CONN_SECURE (3): The connection has a secure session.

In addition to connection status and policy status, the SIOCTTLSCTL ioctl also provides the following connection information, when available:

TTLSi_Sec_Type

Indicates the security type for the connection if AT-TLS policy is defined for the connection. Valid values are:

TTLS_SEC_UNKNOWN (0): The connection does not have a secure session established.

TTLS_SEC_CLIENT (1): The security type is Client.

TTLS_SEC_SERVER (2): The security type is Server.

TTLS_SEC_SRV_CA_PASS (3): The security type is Server with Client Authentication. Client Authentication Type is PassThru.

TTLS_SEC_SRV_CA_FULL (4): The security type is Server with Client Authentication. Client Authentication Type is Full.

TTLS_SEC_SRV_CA_REQD (5): The security type is Server with Client Authentication. Client Authentication Type is Required.

TTLS_SEC_SRV_CA_SAFCHK (6): The security type is Server with Client Authentication. Client Authentication Type is SAFCheck.

TTLSi_SSL_Prot

Indicates the SSL protocol that is in use for the connection if the connection is secure. Valid values are:

TTLS_PROT_UNKNOWN (0x0000): The connection does not have a secure session established.

TTLS_PROT_SSLV2 (0x0200): SSL version 2 is in use.

TTLS_PROT_SSLV3 (0x0300): SSL version 3 is in use.

TTLS_PROT_TLSV1 (0x0301): TLS version 1.0 is in use.
TTLS_PROT_TLSV1_1 (0x0302): TLS version 1.1 is in use.
TTLS_PROT_TLSV1_2 (0x0303): TLS version 1.2 is in use.
TTLS_PROT_TLSV1_3 (0x0304): TLS version 1.3 is in use.

TTLSi_FIPS140

Indicates whether Federal Information Processing Standard (FIPS) 140 is in effect. Valid values are:

TTLS_FIPS140_OFF (0x00): FIPS 140 support is not in effect.
TTLS_FIPS140_ON (0x01): FIPS 140 On support is in effect.
TTLS_FIPS140_LEVEL1 (0x02): FIPS 140 Level1 support is in effect.
TTLS_FIPS140_LEVEL2 (0x03): FIPS 140 Level2 support is in effect.
TTLS_FIPS140_LEVEL3 (0x04): FIPS 140 Level3 support is in effect.

TTLSi_Neg_Cipher: Indicates the 2-character cipher in use for the connection if the connection is secure. If the first two characters of TTLSi_Neg_Cipher4 contain '00', this field is the same as the second two characters of TTLSi_Neg_Cipher4; otherwise, this field contains '4X'. For the list of cipher suites that are supported, see the gsk_environment_open() API information in z/OS Cryptographic Services System SSL Programming.

TTLSi_UserID/TTLSi_UserID_Len

TTLSi_UserID is a null terminated character string.

TTLSi_UserID_Len indicates the number of characters returned prior to the first null.

These fields are returned when the HandshakeRole parameter is specified as ServerWithClientAuth, the client provides a valid certificate, and the certificate is associated with a user ID in the DIGTCERT General Resource Class. See the RACF® and Digital Certificates topic in z/OS Security Server RACF Security Administrator's Guide for more information on associating user IDs with certificates.

TTLSi_Cert_Len: Indicates the size of the partner's certificate if the connection is secure and a certificate was supplied during negotiation.

TTLSi_Neg_Cipher 4: Indicates the 4-character cipher in use for the connection if the connection is secure. For the list of cipher suites that are supported, see the gsk_environment_open() API information in z/OS Cryptographic Services System SSL Programming.

TTLSi_Neg_KeyShare: Indicates the four-character negotiated key share in use for the connection. This is returned if the connection is secure and the protocol in use is TLS 1.3 or later.

If the TTLS_RETURN_CERTIFICATE request type is specified on the SIOCTTLSCTL ioctl and the partner certificate is known, the certificate is returned in the additional buffer provided (using fields TTLSi_BufferPtr and TTLSi_BufferLen) with the ioctl call. The length of the returned certificate is returned in TTLSi_Cert_Len. If the buffer provided is not large enough to hold the certificate, then the variable errno indicates the value ENOBUFS and the required buffer size is returned in TTLSi_Cert_Len.

The following optional behaviors can be requested on the SIOCTTLSCTL ioctl using the TTLSi_Req_Type field:

TTLS_QUERY_ONLY (0x0000): Query the connection status. If more advanced query information is required, use the optional buffer that includes the TTLSHeader control block.

Restriction: The TTLS_QUERY_ONLY option must be specified alone without any other request option.
TTLS_RETURN_CERTIFICATE (0x0001): Return the partner certificate used for authentication if it is available.

Restriction: This request is not valid with TTLS Version 2. For TTLS version 2, use the TTLSHeader structure to request the partner certificate.

TTLS_INIT_CONNECTION (0x0002): Initialize the secure SSL connection using the role defined by the HandshakeRole parameter.

Restriction: The connection must be application controlled to use this request.

TTLS_RESET_SESSION (0x0004): For TLSv1.2 and earlier versions, reset a session ID to avoid its reuse by another connection. For a TLSv1.3 connection, delete all session tickets for the session.

Restriction: The connection must be application controlled to use this request.

TTLS_RESET_CIPHER (0x0008): Reset the cipher used for the secure session, updating the encryption key. For TLSv1.2 and earlier versions, a renegotiation is done. If the session ID has timed out or has been reset, a full handshake is performed. Otherwise, a short handshake is performed.
For TLSv1.3, the encryption key is updated and a Key Update message is sent to the session partner. The message requests that the session partner also update its encryption key.

Restriction: The connection must be application controlled to use this request.

TTLS_RESET_WRITE_CIPHER (0x0040)

Reset the write cipher used for the secure session, updating the encryption key. The encryption key is updated and a Key Update message is sent to the session partner. The message does not request that the session partner update its encryption key.

Restriction:

The connection must be using TLSv1.3 or higher to use this request.
The connection must be application controlled to use this request.

TTLS_STOP_CONNECTION (0x0010)

Close the SSL connection. Data will no longer be encrypted or decrypted on the connection. The state of the TCP connection is unchanged.

Restrictions:

Before the TTLS_STOP_CONNECTION request is issued, the application must read all secure application data and all application write requests must complete. If there is outstanding application data on the connection, the TTLS_STOP_CONNECTION request fails.
The connection must be application-controlled to use this request.

TTLS_ALLOW_HSTIMEOUT (0x0020)

Allow the TCP connection to remain active if the SSL handshake fails because no data was received from the client. The timeout value is determined by the HandshakeTimeout value from the policy. The HandshakeTimeout must be a nonzero value. This option is valid only if the HandshakeRole value is Server or ServerWithClientAuth. Any non-SSL data received ends the handshake request and leaves the connection state nonsecure.

Restriction: The TTLS_INIT_CONNECTION option must be specified when the TTLS_ALLOW_HSTIMEOUT option is requested.

Tip: Use this option for servers that send the first application data to the client and must support SSL and non-SSL clients on the same port.

TTLS_SEND_SESSION_TICKET (0x0080)

Request that the server generate and send a session ticket to the client for use resuming the session later.

Restriction:

The connection must be using TLSv1.3 or higher to use this request.
The connection must be application controlled to use this request.
The server must be enabled to support session tickets but not enabled to automatically send session tickets to the client. The GSK_SESSION_TICKET_SERVER_ENABLE parameter must be set to On and the GSK_SESSION_TICKET_SERVER_COUNT parameter must be set to 0.