SSL_Create()--Enable SSL Support for the Specified Socket Descriptor

 #include <qsossl.h>

 SSLHandle* SSL_Create(int socket_descriptor,  
                       int flags)

The SSL_Create() function is used by a program to enable SSL support for the specified socket descriptor.

Parameters

int socket_descriptor  (input) 

The descriptor of the socket to be used for the SSL session. The socket descriptor must have been created (using the socket() API) with a type of SOCK_STREAM and an address family of AF_INET or AF_INET6.

int flags  (input) 

A flag value that controls the use of SSL for the session. The flags value is either zero, or is obtained by the ORing of the following constant:

SSL_ENCRYPT (1<<0)	Encrypt the connection.
SSL_DONT_ENCRYPT (0)	Do not encrypt the connection.

Authorities

No authorization is required.

Return Value

The SSL_Create() API returns a pointer to an SSLHandle. A value of NULL is returned when SSL_Create() fails. 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        */
};

Note: A full explanation of each of the members of the above structure are defined in the SSL_Handshake() API description.

The SSLHandle structure returned will be initialized to hexadecimal zeros with the exception of the fd field, which will be initialized to the socket_descriptor input parameter and the createFlags field, which will be initialized to the flags input parameter.

Error Conditions

When the SSL_Create() API fails, errno can be set to:

[EALREADY]

Operation already in progress.

[EBADF]

Descriptor not valid.

[EFAULT]

Bad address.

[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.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EPIPE]

Broken pipe.

[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. The SSL_Create() function is only valid on sockets that have an address family of AF_INET or AF_INET6 and a socket type of SOCK_STREAM. If the descriptor pointed to by the socket_descriptor parameter does not have the correct address family and socket type, [SSL_ERROR_IO] is returned and the errno value is set to EINVAL.
   
   
2. If the flags parameter specifies a value that does not include the SSL_ENCRYPT flag, then the SSL protocol will not be used for the connection. Not using the SSL protocol has the following effects:
   
   
   • The SSL_Handshake() API will simply return successful without performing any function.
     
     
   • The SSL_Read() API will simply call the sockets read() API with the same set of input parameters.
     
     
   • The SSL_Write() API will simply call the sockets write() API with the same set of input parameters.
   
   
3. Any use of givedescriptor() and takedescriptor() APIs must be performed prior to issuing an SSL_Create().

Related Information

• SSL_Destroy()--End SSL Support for the Specified SSL Session
  
  
• 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