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