gsk_secure_soc

Reads data using a secure socket connection.

Format

   #include <gskssl.h>

   int gsk_secure_soc_read(
                            gsk_soc_data *     soc_handle,
                            void *             buffer,
                            int                size)

Parameters

soc_handle: Specifies the connection handle returned by the gsk_secure_soc_init() routine.
buffer: Specifies the buffer to receive the data read from the secure socket connection. The maximum amount of data returned by gsk_secure_soc_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.

Results

The function return value will be the number of bytes read if no error is detected. Otherwise, it will be a negative value representing one of the return codes listed in the gskssl.h include file. These are some possible errors:

[GSK_ERROR_BAD_BUFFER_SIZE]: The buffer address or buffer size is not valid.
[GSK_ERROR_BAD_MAC]: Message verification failed.
[GSK_ERROR_BAD_MALLOC]: Insufficient storage is available.
[GSK_ERROR_BAD_MESSAGE]: Incorrectly-formatted message received from peer application.
[GSK_ERROR_BAD_PEER]: Peer application has violated the SSL protocol.
[GSK_ERROR_BAD_SSL_HANDLE]: The connection handle is not valid.
[GSK_ERROR_CONNECTION_ACTIVE]: A read request is already active for the connection.
[GSK_ERROR_CRYPTO]: Cryptographic error detected.
[GSK_ERROR_IO]: I/O error communicating with peer application.
[GSK_ERROR_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_ERROR_SOCKET_CLOSED]: Socket connection closed by peer application.
[GSK_ERROR_WOULD_BLOCK]: A complete SSL record is not available.
[GSK_ERROR_WOULD_BLOCK_WRITE]: An SSL handshake is in progress but data cannot be written to the socket.

Usage

The gsk_secure_soc_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 will never return more than a single SSL record. The maximum amount of data returned by gsk_secure_soc_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_soc_read() routine for a given connection handle. Multiple concurrent threads can call gsk_secure_soc_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_soc_read() will return with GSK_ERROR_WOULD_BLOCK. No data will be returned in the application buffer when GSK_ERROR_WOULD_BLOCK is returned. The application should call gsk_secure_soc_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_soc_read() to return with GSK_ERROR_WOULD_BLOCK_WRITE. This indicates that an SSL handshake is in progress and the application should call gsk_secure_soc_read() again when data can be written to the socket. No data will be returned in the application buffer when GSK_ERROR_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