z/OS Cryptographic Services System SSL Programming
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


gsk_secure_soc_init()

z/OS Cryptographic Services System SSL Programming
SC14-7495-00

Initializes a secure socket connection.

Format

   #include <gskssl.h>

   gsk_soc_data * gsk_secure_soc_init(
                                       gsk_soc_init_data *     init_data)

Parameters

init_data
Specifies the socket connection initialization data.

Results

The function return value will be 0 (GSK_OK) if no error is detected. Otherwise, it is one of the return codes listed in the gskssl.h include file. These are some possible errors:
[GSK_ERR_INIT_PARM_NOT_VALID]
A connection initialization parameter is not valid.
[GSK_ERROR_BAD_CERT]
A certificate is not valid.
[GSK_ERROR_BAD_DATE]
A certificate is not valid yet or is expired.
[GSK_ERROR_BAD_MAC]
Message verification failed.
[GSK_ERROR_BAD_MALLOC]
Insufficient storage is available.
[GSK_ERROR_BAD_MESSAGE]
Incorrectly-formatted message received from peer application.
[GSK_ERROR_BAD_PEER]
Peer application has violated the SSL protocol.
[GSK_ERROR_BAD_STATE]
The SSL environment has not been initialized.
[GSK_ERROR_CRYPTO]
Cryptographic error detected.
[GSK_ERROR_ICSF_CLEAR_KEY_SUPPORT_NOT_AVAILABLE]
ICSF clear key support not available.
[GSK_ERROR_ICSF_FIPS_DISABLED]
ICSF PKCS #11 services are disabled.
[GSK_ERROR_ICSF_NOT_AVAILABLE]
ICSF services are not available.
[GSK_ERROR_ICSF_NOT_FIPS]
ICSF PKCS #11 not operating in FIPS mode.
[GSK_ERROR_ICSF_SERVICE_FAILURE]
ICSF callable service returned an error.
[GSK_ERROR_INCOMPATIBLE_KEY]
The certificate key is not compatible with the negotiated cipher suite.
[GSK_ERROR_IO]
I/O error communicating with peer application.
[GSK_ERROR_LDAP]
An LDAP error is detected.
[GSK_ERROR_LDAP_NOT_AVAILABLE]
The LDAP server is not available.
[GSK_ERROR_NO_CIPHERS]
No cipher specifications.
[GSK_ERROR_NO_PRIVATE_KEY]
Certificate does not contain a private key or the private key is unusable.
[GSK_ERROR_RNG]
Error encountered when generating random bytes.
[GSK_ERROR_SELF_SIGNED]
A self-signed certificate cannot be validated.
[GSK_ERROR_SOCKET_CLOSED]
Socket connection closed by peer application.
[GSK_ERROR_UNKNOWN_CA]
A certification authority certificate is missing.
[GSK_ERROR_UNSUPPORTED_CERTIFICATE_TYPE]
The certificate type is not supported by System SSL.
[GSK_ERROR_VALIDATION]
Certificate validation error.
[GSK_KEYFILE_BAD_DNAME]
The specified key is not found in the key database or the key is not trusted.
[GSK_KEYFILE_BAD_LABEL]
The DName field of the gsk_soc_init_data structure is an empty string. If the default key is to be used, the DName field must be NULL.
[GSK_KEYFILE_DUPLICATE_NAME]
The key database contains multiple certificates with the same subject name as the distinguished name specified in the connection initialization data.
[GSK_SOC_BAD_V2_CIPHER]
SSL V2 cipher is not valid.
[GSK_SOC_BAD_V3_CIPHER]
SSL/TLS V3 cipher is not valid.
[GSK_SOC_NO_READ_FUNCTION]
No read function is specified in the connection initialization data.
[GSK_SOC_NO_WRITE_FUNCTION]
No write function is specified in the connection initialization data.

Usage

The gsk_secure_soc_init() routine initializes a secure socket connection. The gsk_initialize() routine must be called before any secure socket connections can be initialized. After the connection has been initialized, it can be used for secure data transmission using the gsk_secure_soc_read() and gsk_secure_soc_write() routines. The gsk_secure_soc_close() routine should be called to close the connection when it is no longer needed. The gsk_secure_soc_close() routine should not be called if an error is returned by the gsk_secure_soc_init() routine.

Before calling the gsk_secure_soc_init() routine, the application must create a connected socket. For a client, this means calling the socket() and connect() routines. For a server, this means calling the socket(), listen(), and accept() routines. However, SSL does not require the use of TCP/IP for the communications layer. The socket descriptor can be any integer value that is meaningful to the application. The application must provide its own socket routines if it is not using TCP/IP.

An SSL handshake is performed as part of the processing of the gsk_secure_soc_init() routine. This establishes the server identity and optionally the client identity. It also negotiates the cryptographic parameters to be used for the connection.

The server certificate can use either RSA or DSA as the public/private key algorithm. In FIPS mode, the RSA or DSA key size must be at least 1024 bits. An RSA certificate can be used with an RSA, fixed Diffie-Hellman, or ephemeral Diffie-Hellman key exchange. A DSA certificate can be used with either a fixed or ephemeral Diffie-Hellman key exchange. In FIPS mode, the Diffie-Hellman key size must be at least 2048 bits. If the servers certificate contains a key usage extension during the SSL handshake, it must allow key usage as follows:
  • RSA certificates using export restricted ciphers (40-bit RC4 encryption and 40-bit RC2 encryption) with a public key size greater than 512 bits must allow digital signature. If operating in FIPS mode, export restricted ciphers cannot be selected.
  • RSA or DSA certificates using fixed Diffie-Hellman key exchange must allow key agreement.
  • Other RSA certificates must allow key encipherment.
  • DSA certificates using ephemeral Diffie-Hellman key exchange must allow digital signature.

System SSL does not accept Verisign Global Server ID certificates. When specified, System SSL uses these certificates as any other certificate when determining the encryption cipher to be used for the SSL session.

The client certificate must support digital signatures. This means the certificate key usage extension (if any) must allow digital signature. The key algorithm can be either the RSA encryption algorithm or the Digital Signature Standard algorithm (DSA).

The SSL server always provides its certificate to the SSL client as part of the handshake. Depending upon the server handshake type, the server may ask the client to provide its certificate. The key label that is stored in the connection is used to retrieve the certificate from the key database, key ring, or token. The default key will be used if no label is set. The key record must contain both an X.509 certificate and a private key.

These SSL V2 cipher specifications are supported in non-FIPS mode only:
  • "1" = 128-bit RC4 encryption with MD5 message authentication (128-bit secret key)
  • "2" = 128-bit RC4 export encryption with MD5 message authentication (40-bit secret key)
  • "3" = 128-bit RC2 encryption with MD5 message authentication (128-bit secret key)
  • "4" = 128-bit RC2 export encryption with MD5 message authentication (40-bit secret key)
  • "6" = 56-bit DES encryption with MD5 message authentication (56-bit secret key)
  • "7" = 168-bit Triple DES encryption with MD5 message authentication (168-bit secret key)
These SSL V3 cipher specifications are supported in non-FIPS mode only:
  • "00" = No encryption or message authentication and RSA key exchange
  • "01" = No encryption with MD5 message authentication and RSA key exchange
  • "02" = No encryption with SHA-1 message authentication and RSA key exchange
  • "03" = 40-bit RC4 encryption with MD5 message authentication and RSA key exchange
  • "04" = 128-bit RC4 encryption with MD5 message authentication and RSA key exchange
  • "05" = 128-bit RC4 encryption with SHA-1 message authentication and RSA key exchange
  • "06" = 40-bit RC2 encryption with MD5 message authentication and RSA key exchange
  • "09" = 56-bit DES encryption with SHA-1 message authentication and RSA key exchange
  • "0C" = 56-bit DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSA certificate
  • "0F" = 56-bit DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "12" = 56-bit DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSA certificate
  • "15" = 56-bit DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
These SSL V3 cipher specifications are supported in FIPS mode and non-FIPS mode:
  • "0A" = 168-bit Triple DES encryption with SHA-1 message authentication and RSA key exchange
  • "0D" = 168-bit Triple DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSA certificate
  • "10" = 168-bit Triple DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "13" = 168-bit Triple DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSA certificate
  • "16" = 168-bit Triple DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
  • "2F" = 128-bit AES encryption with SHA-1 message authentication and RSA key exchange
  • "30" = 128-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSA certificate
  • "31" = 128-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "32" = 128-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSA certificate
  • "33" = 128-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
  • "35" = 256-bit AES encryption with SHA-1 message authentication and RSA key exchange
  • "36" = 256-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSA certificate
  • "37" = 256-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "38" = 256-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSA certificate
  • "39" = 256-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate

The client sends a list of ciphers it supports during the SSL handshake. The server application uses this list, and the defined ciphers supported by the server, to determine the cipher to be used during the SSL handshake. This selection is done by looking through the servers cipher list for a match in the clients list. The first matching cipher is used.

Environment variables are processed along with the information passed in the gsk_init_data structure during environment initialization. Also during environment initialization, the key database, key ring or token is read.

The environment variables that are overridden by non-NULL values in the gsk_soc_init_data structure are:
  • GSK_KEY_LABEL
  • GSK_V2_CIPHER_SPECS
  • GSK_V3_CIPHER_SPECS
The gsk_soc_init_data structure contains these fields:
fd
Specifies the socket descriptor for the secure connection. The socket must remain open until after the gsk_secure_soc_close() routine has been called to close the secure connection.
hs_type
Specifies the intended handshake type as follows:
GSK_AS_CLIENT
Performs a client SSL handshake
GSK_AS_CLIENT_NO_AUTH
Performs a client SSL handshake but do not provide a client certificate to the SSL server
GSK_AS_SERVER
Performs a server SSL handshake
GSK_AS_SERVER_WITH_CLIENT_AUTH
Performs a server SSL handshake with client authentication
DName
Specifies either the distinguished name or the key label of the local certificate. Specify NULL to use the default key for the key database, key ring or token.
sec_type
Returns the selected security protocol as "SSLV2", "SSLV3", or "TLSV1". This is a static string and must not be modified or freed by the application.
cipher_specs
Specifies the SSL V2 cipher specifications as a null-terminated string consisting of 1 or more 1-character values. Specify NULL to use the default cipher specifications ("713642" if Security Level 3 FMID encryption is enabled and "642" otherwise). Valid cipher specifications that are not supported because of the installed cryptographic level will be skipped when the connection is initialized. The SSL V2 protocol can only be used when executing in non-FIPS mode.
v3cipher_specs
Specifies the SSL V3 cipher specifications as a null-terminated string consisting of 1 or more 2-character values. Specify NULL to use the default cipher specifications ("050435363738392F303132330A1613100D0915120F0C0306020100" if Security Level 3 FMID is installed and in non-FIPS mode, "35363738392F303132330A1613100D" if Security Level 3 FMID is installed and in FIPS mode, and "0915120F0C0306020100" otherwise). The SSL V3 cipher specifications are used for both the SSL V3 and TLS V1.0 protocols. Valid cipher specifications that are not supported because of the installed cryptographic level are skipped when the connection is initialized. The SSL V3 protocol can only be used when executing in non-FIPS mode.
skread
Specifies the address of the read routine used during the SSL handshake. See gsk_attribute_set_callback() for additional information about the I/O callback routines.
skwrite
Specifies the address of the write routine used during the SSL handshake. See gsk_attribute_set_callback() for additional information about the I/O callback routines.
cipherSelected
Returns the selected cipher for the SSL V2 protocol as a 3-byte binary value:
  • 0x010080 - 128-bit RC4 encryption with MD5 message authentication
  • 0x020080 = 128-bit RC4 export encryption with MD5 message authentication
  • 0x030080 = 128-bit RC2 encryption with MD5 message authentication
  • 0x040080 = 128-bit RC2 export encryption with MD5 message authentication
  • 0x060040 = 56-bit DES encryption with MD5 message authentication
  • 0x0700c0 = 168-bit Triple DES encryption with MD5 message authentication
v3cipherSelected
Returns the selected cipher for the SSL V3 or TLS V1.0 protocol as a 2-byte character value with no string delimiter:
  • "00" = No encryption or message authentication
  • "01" = No encryption with MD5 message authentication and RSA key exchange
  • "02" = No encryption with SHA-1 message authentication and RSA key exchange
  • "03" = 40-bit RC4 encryption with MD5 message authentication and RSA key exchange
  • "04" = 128-bit RC4 encryption with MD5 message authentication and RSA key exchange
  • "05" = 128-bit RC4 encryption with SHA-1 message authentication and RSA key exchange
  • "06" = 40-bit RC2 encryption with MD5 message authentication and RSA key exchange
  • "09" = 56-bit DES encryption with SHA-1 message authentication and RSA key exchange
  • "0A" = 168-bit Triple DES encryption with SHA-1 message authentication and RSA key exchange
  • "0C" = 56-bit DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate
  • "0D" = 168-bit Triple DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate
  • "0F" = 56-bit DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "10" = 168-bit Triple DES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "12" = 56-bit DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate
  • "13" = 168-bit Triple DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate
  • "15" = 56-bit DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
  • "16" = 168-bit Triple DES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
  • "2F" = 128-bit AES encryption with SHA-1 message authentication and RSA key exchange
  • "30" = 128-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate
  • "31" = 128-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "32" = 128-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate
  • "33" = 128-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
  • "35" = 256-bit AES encryption with SHA-1 message authentication and RSA key exchange
  • "36" = 256-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with a DSS certificate
  • "37" = 256-bit AES encryption with SHA-1 message authentication and fixed Diffie-Hellman key exchange signed with an RSA certificate
  • "38" = 256-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with a DSS certificate
  • "39" = 256-bit AES encryption with SHA-1 message authentication and ephemeral Diffie-Hellman key exchange signed with an RSA certificate
failureReasonCode
Returns the gsk_secure_soc_init() error code.
cert_info
Returns peer certificate information. The application must not modify or free this information.
gsk_data
This field is ignored. The key database information is set when gsk_initialize() is called.

Related Topics

gsk_get_cipher_info()

gsk_get_dn_by_label()

gsk_initialize()

gsk_secure_soc_close()

gsk_secure_soc_read()

gsk_secure_soc_reset()

gsk_secure_soc_write()

Parent topic: Deprecated Secure Socket Layer (SSL) APIs

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014