gsk_secure_socket

Reads data using a secure socket connection.

Format

   #include <gskssl.h>

   gsk_status gsk_secure_socket_read (
                                       gsk_handle     soc_handle,
                                       char *         buffer,
                                       int            size,
                                       int *          length)

Parameters

soc_handle: Specifies the connection handle returned by the gsk_secure_socket_open() routine.
buffer: Specifies the buffer to receive the data read from the secure socket connection. The maximum amount of data returned by gsk_secure_socket_read() is 16384 (16K) bytes. If the SSL V2 protocol is used, then the maximum length is 16384 minus the length of the SSL protocol headers.
size: Specifies the size of the supplied buffer.
length: Returns the length of the data read into the supplied buffer.

Results

The function return value will be 0 (GSK_OK) if no error is detected. Otherwise, it will be one of the return codes listed in the gskssl.h include file. These are some possible errors:

[GSK_CONNECTION_ACTIVE]: A read request is already active for the connection.
[GSK_ERR_BAD_MAC]: Message verification failed.
[GSK_ERR_BAD_MESSAGE]: Incorrectly-formatted message received from peer application.
[GSK_ERR_BAD_PEER]: Peer application has violated the SSL protocol.
[GSK_ERR_CONNECTION_CLOSED]: Close notification received from peer application.
[GSK_ERR_CRYPTO]: Cryptographic error detected.
[GSK_ERR_ICSF_NOT_AVAILABLE]: ICSF services are not available.
[GSK_ERR_ICSF_NOT_FIPS]: ICSF PKCS #11 not operating in FIPS mode.
[GSK_ERR_ICSF_SERVICE_FAILURE]: ICSF callable service returned an error.
[GSK_ERR_IO]: I/O error communicating with peer application.
[GSK_ERR_NO_NEGOTIATION]: An attempt was made to renegotiate a session when renegotiation is disabled or the peer rejected an attempted session renegotiation.
[GSK_ERROR_RENEGOTIATION_INDICATION]: Peer did not signal support for TLS Renegotiation Indication.
[GSK_ERR_SOCKET_CLOSED]: Socket connection closed by peer application.
[GSK_INSUFFICIENT_STORAGE]: Insufficient storage is available.
[GSK_INVALID_BUFFER_SIZE]: The buffer address or buffer size is not valid.
[GSK_INVALID_HANDLE]: The connection handle is not valid.
[GSK_INVALID_STATE]: The connection is not in the initialized state.
[GSK_WOULD_BLOCK]: A complete SSL record is not available.
[GSK_WOULD_BLOCK_WRITE]: An SSL handshake is in progress but data cannot be written to the socket.

Usage

The gsk_secure_socket_read() routine reads data from a secure socket connection and returns it in the application buffer. SSL is a record-based protocol and a single call does not return more than a single SSL record. The maximum amount of data returned by gsk_secure_socket_read() is 16384 (16K) bytes. If the SSL V2 protocol is used, then the maximum length is 16384 minus the length of the SSL protocol headers. The application can read an entire SSL record in a single call by supplying a buffer large enough to contain the record. Otherwise, multiple calls will be required to retrieve the entire SSL record.

SSL supports multiple threads but only one thread at a time can call the gsk_secure_socket_read() routine for a given connection handle. Multiple concurrent threads can call gsk_secure_socket_read() if each thread has its own connection handle.

SSL supports sockets in blocking mode and in non-blocking mode. When a socket is in non-blocking mode and a complete SSL record is not available, gsk_secure_socket_read() will return with GSK_WOULD_BLOCK. No data will be returned in the application buffer when GSK_WOULD_BLOCK is returned. The application should call gsk_secure_socket_read() again when there is data available to be read from the socket.

The peer application can initiate an SSL handshake sequence after the connection is established. If this is done and the socket is in non-blocking mode, it is possible for gsk_secure_socket_read() to return with GSK_WOULD_BLOCK_WRITE. This indicates that an SSL handshake is in progress and the application should call gsk_secure_socket_read() again when data can be written to the socket. No data will be returned in the application buffer when GSK_WOULD_BLOCK_WRITE is returned.

The application should not read data directly from the socket since this can cause SSL protocol errors if the application inadvertently reads part of an SSL record. If the application must read data from the socket, it is responsible for synchronizing this activity with the peer application so that no SSL records are sent while the application is performing its own read operations.

Format

Parameters

Results

Usage

Related Topics