gsk_secure_socket

Writes data using a secure socket connection.

Format

   #include <gskssl.h>

   gsk_status gsk_secure_socket_write (
                                        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 containing the data to write to the secure socket connection.
size: Specifies the amount to write.
length: Returns the length of the data written.

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 write request is already active for the connection.
[GSK_ERR_CONNECTION_CLOSED]: A close notification alert has been sent for the connection.
[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_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]: The SSL record cannot be written to the socket because of an EWOULDBLOCK condition.

Usage

The gsk_secure_socket_write() routine writes data to a secure socket connection. SSL is a record-based protocol with a maximum record length of 16384 bytes. If the SSL V2 protocol is used, then the maximum length is 16384 minus the length of the SSL protocol headers. Application data larger than the size of an SSL record will be sent using multiple records.

SSL supports multiple threads but only one thread at a time can call the gsk_secure_socket_write() routine for a given connection handle. Multiple concurrent threads can call gsk_secure_socket_write() 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 the SSL record cannot be written to the socket, gsk_secure_socket_write() will return with GSK_WOULD_BLOCK. The application must call gsk_secure_socket_write() again when the socket is ready to accept more data, specifying the same buffer address and buffer size as the original request. A new write request must not be initiated until the pending write request has been completed as indicated by a return value of 0.

The application should not write data directly to the socket since this can cause SSL protocol errors if the application inadvertently intermixes its data with SSL protocol data. If the application must write data to the socket, it is responsible for synchronizing this activity with the peer application so that application data is not intermixed with SSL data.

To notify your partner application that you are done sending data on the secure connection, a call to gsk_secure_socket_shutdown() should be issued before the gsk_secure_socket_close() call.

Format

Parameters

Results

Usage

Related Topics