SSL_Read()--Receive Data from an SSL-Enabled Socket Descriptor
Syntax
#include <qsossl.h> int SSL_Read(SSLHandle *handle, void *buffer, int buffer_length)
Service Program Name: QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
The SSL_Read() function is used by a program to receive data from an SSL-enabled socket descriptor.
Parameters
- SSLHandle* handle (input)
- The pointer to an SSLHandle for an SSL session.
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 */ };
- void *buffer (input)
- A pointer to the user-supplied buffer in which the data that is received on
the SSL session is to be stored.
- int buffer_length (input)
- The length of the buffer.
Authorities
No authorization is required.
Return Value
The SSL_Read() API returns an integer. Possible values are:
- [n]
-
Successful, where n is the number of bytes read.
- [SSL_ERROR_BAD_MESSAGE]
-
SSL received a badly formatted message.
- [SSL_ERROR_BAD_MAC]
-
A bad message authentication code was received.
- [SSL_ERROR_BAD_MALLOC]
-
Unable to allocate storage required for SSL processing.
- [SSL_ERROR_BAD_STATE]
-
SSL detected a bad state in the SSL session.
- [SSL_ERROR_CLOSED]
-
The SSL session ended.
- [SSL_ERROR_IO]
-
An error occurred in SSL processing; check the errno value.
- [SSL_ERROR_PERMISSION_DENIED]
-
Permission was denied to access object.
- [SSL_ERROR_UNKNOWN]
-
An unknown or unexpected error occurred during SSL processing.
- [SSL_ERROR_UNSUPPORTED_CERTIFICATE_TYPE]
-
IBM® i does not support the certificate's type.
Error Conditions
When the SSL_Read() API fails with return code [SSL_ERROR_IO], errno can be set to:
- [EBADF]
-
Descriptor not valid.
- [ECONNRESET]
-
A connection with a remote socket was reset by that socket.
- [EFAULT]
-
Bad address.
One of the following conditions occurred:
- The system detected an address that was not valid while attempting to access the buffer parameter.
- The system detected an address that was not valid while attempting to access the handle parameter or one of the address fields in the handle parameter.
- [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.
- The buffer_length parameter specifies a negative value.
- [EIO]
-
Input/output error.
- [ENOTCONN]
-
Requested operation requires a connection.
This error code indicates one of the following:
- The socket_descriptor is not for a socket that is in a connected state.
- 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.
- [ETIMEDOUT]
-
A remote host did not respond within the timeout period.
- [EUNATCH]
-
The protocol required to support the specified address family is not available at this time.
- [EUNKNOWN]
-
Unknown system state.
- [EWOULDBLOCK]
-
Operation would have caused the thread to be suspended.
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_Read() 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 handle structure parameter does not have the correct
address family and socket type, [SSL_ERROR_IO] is returned and the
errno value is set to EINVAL.
- The maximum length of data returned will not exceed 32 KB. This is due to
the fact that SSL is a record level protocol and the largest record allowed is
32 KB minus the necessary SSL record headers.
- If the createFlags field in the SSLHandle specifies a
value that does not include the SSL_ENCRYPT flag, this function will simply
call the sockets read() function.
- Unpredictable results will occur when attempting to mix invocations to
SSL_Read() and any of the sockets read functions (recv(),
read(), readv(), and so forth). It is strongly suggested that
you do not mix the SSL_Read() API with any of the sockets read
functions.
- Since SSL is a record-oriented protocol, SSL must receive an entire record
before it can be decrypted and any data returned to the application. Thus, a
select() may indicate that data is available to be read, but a
subsequent SSL_Read() may hang waiting for the remainder of the SSL
record to be received when using blocking I/O.
- A FIONREAD ioctl() cannot be used to determine the amount of data
available for reading by using SSL_Read().
- SSL will ignore the out of band (OOB) data indicator. OOB will not affect
the SSL application. OOB will just be data to the SSL protocol.
- For an SSL enabled socket, which must use a connection-oriented transport
service (that is, TCP), a returned value of zero indicates one of the
following:
- The partner program has issued a close() for the socket.
- The partner program has issued a shutdown() to disable writing to the socket.
- The connection is broken and the error was returned on a previously issued socket function.
- A shutdown() to disable reading was previously done on the socket.
- If an SSL_Read() is run on a socket that is set to non-blocking mode, and there is no data waiting to be read on the SSL enabled socket, the return value will be equal to -10 and the errno will be set to EWOULDBLOCK.
Related Information
- SSL_Create()--Enable SSL Support for the Specified
Socket Descriptor
- 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_Write()--Write Data to an SSL-Enabled Socket Descriptor
API introduced: V4R3