SSL_Destroy()--End SSL Support for the Specified SSL Session

 #include <qsossl.h>

 int SSL_Destroy(SSLHandle* handle)  

The SSL_Destroy() function is used by a program to end SSL support for the specified SSL session. The SSL session to be ended is identified by the handle parameter.

Parameters

SSLHandle* handle  (input) 

The pointer to an SSLHandle for an active SSL session, which is being ended. An SSLHandle is a typedef for a buffer of type struct SSLHandleStr. In <qsossl.h>, struct SSLHandleStr is defined as the following:

struct SSLHandleStr {                 /* SSLHandleStr                */
   int            fd;                 /* Socket descriptor           */
   int            createFlags;        /* SSL_Create flags value      */
   unsigned       protocol;           /* SSL protocol version        */
   unsigned       timeout;            /* Timeout value in seconds    */
   unsigned char  cipherKind[3];      /* Current 2.0 cipher suite*/
   unsigned short int cipherSuite;    /* Current 3.0 cipher suite    */
   unsigned short int* cipherSuiteList; /* List of cipher suites     */
   unsigned int        cipherSuiteListLen; /* Number of entries in
                                         the cipher suites list      */
   unsigned char* peerCert;           /* Peer certificate            */
   unsigned       peerCertLen;        /* Peer certificate length     */
   int            peerCertValidateRc; /* Return code from
                                         validation of certficate    */
   int            (*exitPgm)(struct SSLHandleStr* sslh);
                                      /* Authentication exit
                                         program called when a
                                         certificate is received
                                         during SSL handshake        */
};

Authorities

No authorization is required.

Return Value

The SSL_Destroy() API returns an integer. Possible values are:

Error Conditions

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

[EBADF]

Descriptor not valid.

[EFAULT]

Bad address.

The system detected an address that was not valid while attempting to access the handle parameter or a field within the structure pointed to by the handle parameter.

[EIO]

Input/output error.

[EINVAL]

Parameter not valid. This error code indicates one of the following:

• The socket_descriptor type is not SOCK_STREAM or address family is not AF_INET or AF_INET6.
• One of the parameters passed is not valid or is NULL.

[ENOTCONN]

Requested operation requires a connection.

This error code indicates that the socket_descriptor has not had SSL support enabled. This usually means that an SSL_Create() has not been completed for this socket_descriptor.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EPIPE]

Broken pipe.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

This error code indicates that the SSL_Destroy() was unable to successfully complete the removal of SSL support on this socket_descriptor.

[EUNATCH]

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

[EUNKNOWN]

Unknown system state.

Error Messages

Usage Notes

1. All storage referenced from any field within the structure pointed to by the handle parameter and the storage pointed to by the handle parameter itself will be freed upon a successful return.
   
   
2. Unpredictable results will occur if you attempt to use an SSL_Destroy() while sending or receiving data on the peer system.
   
   
3. If an SSL_Destroy() is not done, then the storage referenced by the handle parameter will not be freed until the job ends.

   Note: A job end might cause a Licensed Internal Code log entry or error log entry if the handle parameter storage is not freed before the job ended.

4. If an SSL_Destroy() is not done, the storage referenced by the handle parameter will not be freed. This will result in a memory leak. A memory leak is the loss of a piece of system memory because it is not allocated to any process on the system.

Related Information

• SSL_Create()--Enable SSL Support for the Specified Socket Descriptor
  
  
• SSL_Handshake()--Initiate the SSL Handshake Protocol
  
  
• SSL_Init()--Initialize the Current Job for SSL
  
  
• SSL_Read()--Receive Data from an SSL-Enabled Socket Descriptor
  
  
• SSL_Write()--Write Data to an SSL-Enabled Socket Descriptor