gsk_secure_soc_init()--Negotiate a secure session

 #include <gskssl.h>

 int gsk_secure_soc_init(gsk_handle my_session_handle);

The gsk_secure_soc_init() function is used to negotiate a secure session, using the attributes set for the secure environment and session. This API does the TLS handshake to the remote peer; upon successful completion, you have a secure session established.

Parameters

my_session_handle (Input) 

The handle for this secure session that was obtained through the gsk_secure_soc_open() API call.

Authorities

Authorization of *R (allow access to the object) to the certificate store file and its associated files is required. Authorization of *X (allow use of the object) to each directory of the path name of the certificate store file and its associated files is required.

Return Value

gsk_secure_soc_init() returns an integer. Possible values are:

[GSK_OK]

gsk_secure_soc_init() was successful.

[GSK_INVALID_HANDLE]

The handle specified was not valid.

[GSK_KEYRING_OPEN_ERROR]

Certificate store file could not be opened.

[GSK_ERROR_BAD_KEYFILE_LABEL]

The specified certificate store label is not valid.

[GSK_ERROR_BAD_V3_CIPHER]

An SSLV3 or TLSV1 cipher suite was specified that is not valid.

[GSK_ERROR_NO_CIPHERS]

No ciphers available or no ciphers were specified.

[GSK_ERROR_NO_CERTIFICATE]

No certificate is available for TLS processing.

[GSK_ERROR_BAD_CERTIFICATE]

The certificate is bad.

[SSL_ERROR_NOT_TRUSTED_ROOT]

The certificate is not signed by a trusted certificate authority.

[GSK_KEYFILE_CERT_EXPIRED]

The validity time period of the certificate has expired.

[GSK_ERROR_UNSUPPORTED_CERTIFICATE_TYPE]

GSK_SSL_EXTN_SIGALG or the peer system's equivalent configuration does not allow for the signature algorithm used on the certificate.

[GSK_ERROR_BAD_MESSAGE]

A badly formatted message was received.

[GSK_ERROR_UNSUPPORTED]

Operation is not supported by TLS.

[GSK_ERROR_BAD_PEER]

The peer system is not recognized.

[GSK_ERROR_CLOSED]

The TLS session ended.

[GSK_ERROR_CERT_VALIDATION]

The certificate is not valid or was rejected by the GSK_CERT_VALIDATION_CALLBACK program.

[GSK_IBMI_ERROR_NO_INITIALIZE]

A successful gsk_environment_init() was not previously called with this handle.

[GSK_IBMI_ERROR_TIMED_OUT]

The value specified for the handshake timeout expired before the handshake completed.

[GSK_IBMI_ERROR_NOT_TCP]

The socket descriptor type is not SOCK_STREAM or the address family is not AF_INET or AF_INET6.

[GSK_IBMI_ERROR_ALREADY_SECURE]

The socket descriptor is already in use by another secure session.

[GSK_INSUFFICIENT_STORAGE]

Unable to allocate storage for the requested operation.

[GSK_IBMI_ERROR_INVALID_POINTER]

The my_session_handle pointer is not valid.

[GSK_INTERNAL_ERROR]

An unexpected error occurred during TLS processing.

[GSK_ERROR_NO_RI_INDICATION]

GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER or GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT was set to GSK_TRUE and the peer did not provide indication that it supports RFC 5746.

[GSK_ERROR_IO]

An error occurred in TLS processing, check errno value.

Error Conditions

When the gsk_secure_soc_init() API fails with return code [GSK_ERROR_IO], errno can be set to:

[EIO]

Input/output error.

[EINTR]

Interrupted function call.

[EDEADLK]

Resource deadlock avoided.

[ETERM]

Operation terminated.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Any errno that can be returned by send() or recv() can be returned by this API. See Sockets APIs for a description of the errno values they return.

If an errno is returned that is not in this list, see Errno Values for UNIX^®-Type Functions for a description of the errno.

Usage Notes

1. The gsk_secure_soc_init() function is valid only on sockets that have an address family of AF_INET or AF_INET6 and a socket type of SOCK_STREAM.
   
   
2. When doing the TLS handshake with a GSK_SESSION_TYPE value of GSK_SERVER_SESSION, GSK_SERVER_SESSION_WITH_CL_AUTH, or GSK_SERVER_SESSION_WITH_CL_AUTH_CRITICAL, the GSK_CONNECT_CIPHER_SPEC_EX value will be the first cipher found in GSK_TLSV13_CIPHER_SPECS_EX, GSK_TLSV12_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, and/or GSK_V3_CIPHER_SPECS_EX, based upon the protocol level agreed to that was also found in the cipher list provided by the client during the TLS handshake.
   
   
3. When doing the TLS handshake with a GSK_SESSION_TYPE value of GSK_CLIENT_SESSION, the cipher specification list will be sent to the server in the client hello in the order found in the GSK_TLSV13_CIPHER_SPECS_EX, GSK_TLSV12_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, and/or GSK_V3_CIPHER_SPECS_EX list, however the value from that list that is negotiated for GSK_CONNECT_CIPHER_SPEC_EX is determined by the server policy.
   
   
4. If gsk_secure_soc_init() fails, GSK_LAST_VALIDATION_ERROR may be set to provide additional information on the cause of the failure.
   
   
5. gsk_secure_soc_init() may result in one or more secondary external TCP connections being made if OCSP has been enabled or configured.
   

Error Messages

Related Information

• gsk_attribute_set_buffer()--Set character information for a secure session or environment.
  
  
• gsk_attribute_set_enum()--Set enumerated information for a secure session or environment.
  
  
• gsk_attribute_set_numeric_value()--Set numeric information for a secure session or environment
  
  
• gsk_secure_soc_close()--Close a secure session
  
  
• gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session
  
  
• gsk_secure_soc_open()--Get a handle for a secure session
  
  
• gsk_secure_soc_read()--Receive data on a secure session
  
  
• gsk_secure_soc_startInit()--Start asynchronous operation to negotiate a secure session
  
  
• gsk_secure_soc_write()--Send data on a secure session
  
  
• gsk_strerror()--Retrieve GSK runtime error message

API Introduced: V5R1