z/OS Cryptographic Services System SSL Programming
z/OS Cryptographic Services System SSL Programming
Previous topic |
Next topic |
Contents |
Contact z/OS |
Library |
PDF
gsk_secure_socket_init() z/OS Cryptographic Services System SSL Programming SC14-7495-00 |
|
Initializes a secure socket connection. FormatParameters
ResultsThe function return value will be
0 (GSK_OK) if no error is detected. Otherwise, it will be one
of the return codes listed in the gskssl.h include file. These
are some possible errors:
UsageThe gsk_secure_socket_init() routine initializes a secure socket connection created by the gsk_secure_socket_open() routine. After the connection has been initialized, it can be used for secure data transmission using the gsk_secure_socket_read() and gsk_secure_socket_write() routines. The gsk_secure_socket_close() routine should be called to close the connection when it is no longer needed. The gsk_secure_socket_close() routine should also be called if an error is returned by the gsk_secure_socket_init() routine. Before calling the gsk_secure_socket_init() routine, the application must create a connected socket and store the socket descriptor in the SSL connection by calling the gsk_attribute_set_numeric_value() routine. 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 which is meaningful to the application. The application must provide its own socket routines if it is not using TCP/IP by calling the gsk_attribute_set_callback() routine. The gsk_secure_socket_init() routine can return GSK_WOULD_BLOCK_READ or GSK_WOULD_BLOCK_WRITE if the socket is in non-blocking mode. The connection is not initialized in this case and the application must call gsk_secure_socket_init() again when the socket is ready to accept a read request (GSK_WOULD_BLOCK_READ) or a write request (GSK_WOULD_BLOCK_WRITE). The application must provide its own callback routine for io_setsocketoptions() to have the SSL handshake processed in non-blocking mode (the default io_setsocketoptions() routine places the socket into blocking mode during the handshake processing). In FIPS mode, only DSA certificates with domain parameters that conform to FIPS 186-3: Digital Signature Standard (DSS) are supported. In non-FIPS mode, if the key size is less than 1024 bits, then domain parameters that conform to FIPS 186-2 are supported. In non-FIPS mode, if the key size is greater than or equal to 1024 bits, the domain parameters must conform to FIPS 186-3, with the exception that parameters that have a prime modulus (p) of 2048 bits and a prime divisor (q) of 160 bits are also tolerated. Be sure a gsk_secure_socket_shutdown() call is issued before a gsk_secure_socket_close() call. Protocol
Selection An SSL handshake is performed as part of the processing
of the gsk_secure_socket_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 client
and server attempts to use the highest available protocol version
as determined by the intersection of the enabled protocol versions
for the client and the server and the compatible ciphers. Thus:
Note:
Cipher selection The client sends a list of ciphers it supports during the SSL handshake. The server application uses this list, and the defined ciphers that are supported by the server, to determine the cipher to be used during the SSL handshake. If the client is operating in FIPS mode, then the list provided only contains FIPS ciphers. A server executing in FIPS mode will only use FIPS ciphers. The cipher selection is done by looking through the servers cipher list for a match in the clients list. The first matching cipher is used. When building the
server's list of cipher suites for comparison with the list sent by
the client, the server might omit some ciphers from the list as follows:
Note:
Server certificate The server certificate can use either RSA, DSA, Diffie-Hellman, or ECDSA as the public/private key algorithm. In FIPS mode, the RSA or DSA key size must be at least 1024 bits, the Diffie-Hellman key size must be at least 2048 bits, and the ECC key size must be at least 192 bits and use a NIST-approved named curve. An RSA certificate can be used with an RSA, ephemeral Diffie-Hellman, or ephemeral ECDH key exchange. A DSA certificate can be used with an ephemeral Diffie-Hellman key exchange. A Diffie-Hellman certificate can be used in a fixed Diffie-Hellman key exchange. An ECDSA certificate can be used with a fixed ECDH or ephemeral ECDH key exchange. If
the servers certificate contains a key usage extension during the
SSL handshake, it must allow key usage as follows:
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. When using TLS V1.2 as the SSL session protocol, the client may pass to the server a list of signature algorithm pairs as part of the TLS handshake. The key algorithm and signature algorithm of the server certificate must be present in this list of signature algorithm pairs. In addition, any peer certificates in the server certificate chain must also be signed using a signature algorithm present in the list. The signature algorithm pair list under the TLS V1.2 protocol may allow some TLS ciphers to operate using certificates that were previously incompatible with the cipher specification. In previous versions of TLS, these ciphers (primarily ciphers that use a fixed Diffie-Hellman or fixed ECDH key exchange) required the server certificate to be signed with a specific signature key algorithm. Under TLS V1.2, the signature algorithm pairs list allows the cipher to be used if the signature algorithm is specified in the list. Client
certificate The SSL server always provides its certificate to the SSL client as part of the handshake. The client always performs server authentication using the certificate that is provided by the server. 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 is used if no label is set. The key record must contain both an X.509 certificate and a private key. See gsk_validate_certificate_mode() for a description of the steps that are performed during certificate validation. The
client certificate can use either RSA, Digital Signature Standard
algorithm (DSA), ECDSA, or Diffie-Hellman as the public/private key
algorithm. The type of client certificate that can be used depends
on the key exchange method being used for the session cipher that
is selected by the server, as detailed in the following list.
Client certificates that are used in a fixed Diffie-Hellman or fixed ECDH key exchange where the client certificate is used to send the client's public key to the server must support key agreement. This means the certificate key usage extension (if any) must allow key agreement. In all other cases the client certificate must support digital signatures. This means the certificate key usage extension (if any) must allow digital signature. Client certificates that are used with a fixed ECDH key exchange where the client private key is a secure key label in the TKDS are not supported. When using TLS V1.2 as the SSL session protocol, the server may pass to the client a list of signature algorithm pairs as part of the TLS handshake. The key algorithm and signature algorithm of the client certificate must be present in this list of signature algorithm pairs. In addition, any peer certificates in the client certificate chain must also be signed using a signature algorithm present in the list. 
|
 Copyright IBM Corporation 1990, 2014 |
