gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session

 #include <gskssl.h>

 int gsk_secure_soc_misc(gsk_handle my_session_handle,
                         GSK_MISC_ID miscID);

The gsk_secure_soc_misc() function is used to perform miscellaneous functions for a secure session.

Parameters

my_session_handle (Input) 

The handle for the secure session obtained from gsk_secure_soc_open() and after performing a gsk_secure_soc_init().

miscID (Input) 

One of the following operations:

• GSK_RESET_CIPHER (100) - Performs another SSL handshake for the SSL session identified by the my_session_handle parameter. If an SSL session's cache entry is still valid and both end points of the SSL session allow using a cache entry, an abbreviated SSL handshake may be performed. If the SSL cache entry for this session has expired or if the SSL session's cache entry has been reset with the GSK_RESET_SESSION function, or if one end point of the SSL session does not allow using the SSL session cache entry, then a full SSL handshake will be performed.
  
  
• GSK_RESET_CIPHER_WITHNEWSESSION (103) - This does the same thing as GSK_RESET_CIPHER, but will not do an abbreviated SSL handshake even if a valid SSL cache entry exists.
  
  
  
• GSK_RESET_SESSION (101) - Removes this set of SSL session attributes from the SSL session cache. Any new SSL session handshake requests to the peer end point will not use this set of attributes. In most cases, as result of this operation, a full SSL handshake will be performed for the next SSL handshake request between both end points.
  
  
• GSK_CLOSE_NOTIFY (102) - Sends a close-notify alert to the peer. Further SSL writes or gsk_secure_soc_misc() operations will be prevented. gsk_secure_soc_read() and gsk_secure_soc_startRecv() will continue to function until the peer sends a close-notify alert. gsk_secure_soc_close() still must be called for this session handle.
  

Authorities

No authorization is required.

Return Value

gsk_secure_soc_misc() returns an integer. Possible values are:

[GSK_OK]

gsk_secure_soc_misc() was successful.

[GSK_INVALID_HANDLE]

The handle specified was not valid.

[GSK_INVALID_STATE]

A gsk_secure_soc_init() has not been issued with this handle.

[GSK_ERROR_NOT_SSLV3]

SSLV3 or TLSV1 is required for this function.

[GSK_MISC_INVALID_ID]

The value specified for miscID is not valid.

[GSK_IBMI_ERROR_INVALID_POINTER]

The my_session_handle pointer is not valid.

[GSK_INTERNAL_ERROR]

An unexpected error occurred during SSL processing.

[GSK_ERROR_IO]

An error occurred in SSL processing; check the errno value.

[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_BAD_V2_CIPHER]

An SSLV2 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 SSL 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_BAD_MESSAGE]

A badly formatted message was received.

[GSK_ERROR_UNSUPPORTED]

Operation is not supported by SSL.

[GSK_ERROR_BAD_PEER]

The peer system is not recognized.

[GSK_ERROR_CLOSED]

The SSL session ended.

[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_ERROR_SSL_CLOSED]

A gsk_secure_soc_misc(GSK_CLOSE_NOTIFY) was previously performed on this secure session.

[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_SEQNUM_EXHAUSTED]

A secure connection using TLSv1.1 or higher protocol has sent or received more than 2⁶⁴-1 SSL records. To prevent this error perform a gsk_secure_soc_misc(GSK_RESET_CIPHER) operation before the record limit is reached. A general guideline would be once a day for long lived secure connections.

Error Conditions

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

[EINTR]

Interrupted function call.

[EDEADLK]

Resource deadlock avoided.

[ETERM]

Operation terminated.

[EIO]

Input/output error.

[EUNATCH]

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

Usage Notes

1. An SSL session's attributes that are negotiated as part of an SSL handshake may be cached by each end point involved in the SSL session and then reused as part of an abbreviated SSL handshake when allowed by both end points.

Error Messages

Related Information

• gsk_secure_soc_close()--Close a secure session
  
  
• gsk_secure_soc_init()--Negotiate a secure session
  
  
• gsk_secure_soc_open()--Get a handle for a secure session
  
  
• gsk_strerror()--Retrieve GSK runtime error message