SSL_Create()--Enable SSL Support for the Specified Socket Descriptor
Syntax
#include <qsossl.h> SSLHandle* SSL_Create(int socket_descriptor, int flags)
Service Program Name: QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
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
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFA081 E | Unable to set return value or error code. |
Usage Notes
- 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.
- 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.
- The SSL_Handshake() API will simply return successful without
performing any function.
- 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
API introduced: V4R3