	RSA BSAFE SSL-C	Security protocol components for C
		Search

Protocol Functions

This section describes the functions used to manage the SSL protocol.

Functions
int	SSL_is_init_finished (SSL *ssl)
	Indicates whether the SSL handshake has completed and the communications channel has been established for the specified ssl. More...
int	SSL_do_handshake (SSL *ssl)
	Performs the initialization sequence to set up an SSL connection for the specified SSL. More...
int	SSL_renegotiate (SSL *ssl)
	Sets a flag indicating a renegotiation should occur before any additional data is transmitted for the specified ssl. More...
int	SSL_shutdown (SSL *ssl)
	Shuts down the SSL protocol on a connection. More...
int	SSL_accept (SSL *ssl)
	Starts the read of a handshake by the server. More...
int	SSL_connect (SSL *ssl)
	Starts the read of the server handshake by the client (after the client has sent the first message). More...
int	SSL_read (SSL ssl, char buffer, int num)
	Reads the requested number of Bytes into the buffer buf through an SSL. More...
int	SSL_peek (SSL ssl, char buffer, int num)
	Copies the requested number of Bytes into the buffer buf from the input buffer of an SSL. More...
int	SSL_write (SSL ssl, char buffer, int num)
	Writes num Bytes from the buffer buf to the SSL connection associated with ssl. More...
int	SSL_want (SSL *ssl)
	Returns the read/write state value from the SSL. More...

Function Documentation

int SSL_accept ( SSL * ssl ) ;

Starts the read of a handshake by the server. This is required when establishing an SSL connection and is performed at the server end of the connection.
Parameters:

ssl [In] The SSL connection reference that accepts the connection.

Returns:
1 indicates success.
<=0 indicates error.

It is not necessary to call SSL_accept() as SSL_read() and SSL_write() trigger the handshake transparently.
Before performing an SSL_read() or SSL_write(), call SSL_set_accept_state() to indicate the server side of the protocol.
Use SSL_get_error() to interpret any errors.
See also:
SSL_connect() and SSL_set_accept_state().

int SSL_connect ( SSL * ssl ) ;

Starts the read of the server handshake by the client (after the client has sent the first message). This is required when establishing an SSL connection and is performed at the client end of the connection.
Parameters:

ssl [In] The SSL reference for connection.

Returns:
1 indicates success.
<= 0 indicates error.

It is not necessary to call SSL_connect() as SSL_read() and SSL_write() trigger the handshake transparently.
Before performing an SSL_read() or SSL_write(), call SSL_set_connect_state() to indicate the client side of the protocol.
Use SSL_get_error() to interpret any errors.
See also:
SSL_accept() and SSL_set_connect_state().

int SSL_do_handshake ( SSL * ssl ) ;

Performs the initialization sequence to set up an SSL connection for the specified SSL. The function passes the required messages between the client and the server.
Parameters:

ssl [In] The SSL connection reference with which to perform the handshake.

Returns:
1 indicates success.
<= 0 indicates error.

Use SSL_get_error() to interpret errors.
See also:
SSL_is_init_finished() and SSL_want().
Samples:
PKCS11Client.c, and ssl_client.c.

int SSL_is_init_finished ( SSL * ssl ) ;

Indicates whether the SSL handshake has completed and the communications channel has been established for the specified ssl.
Parameters:

ssl [In] The SSL connection reference against which to check the initialization state.

Returns:
0 indicates the initialization is not finished.
1 indicates the initialization is finished.
See also:
SSL_do_handshake().

int SSL_peek ( SSL * ssl,

char * buf,

int num

) ;

Copies the requested number of Bytes into the buffer buf from the input buffer of an SSL. Checks the read buffer from the last SSL connection reference to determine whether there is buffered data that was read from the underlying connection but not read by the application. Any buffered data is copied into the caller’s buffer. This is a non-destructive operation because the data remains in the buffer. All other connections remain unaltered.
Parameters:

ssl [In] The SSL connection reference where the read buffer is checked.

buf [In] The buffer into which to read the data.

num [In] The number of Bytes to copy from the SSL input. The next num of Bytes in the buffer are copied here.

Returns:
The number of Bytes actually read. One of:

0 indicates the connection is shut down.
-1 indicates there is an error or non-blocking return.

int SSL_read ( SSL * ssl,

char * buf,

int num

) ;

Reads the requested number of Bytes into the buffer buf through an SSL.
Parameters:

ssl [In] The SSL connection reference that performs the read.

buf [In] The buffer into which to read the data.

num [In] The number of Bytes to read from the SSL.

Returns:
The number of Bytes actually read. One of:

0 indicates the connection is shutdown.
-1 indicates there is an error or non-blocking return.

Use SSL_get_error() to interpret any errors.
See also:
SSL_write() and SSL_want().
Samples:
cache_server.c, fips_client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

int SSL_renegotiate ( SSL * ssl ) ;

Sets a flag indicating a renegotiation should occur before any additional data is transmitted for the specified ssl. Renegotiation allows the cryptographic parameters of an existing SSL connection to be recalculated by performing a new handshake. This call can be made by either a client or server. This functionality is only available for SSLv3 and TLSv1. The call is ignored for SSLv2.
Parameters:

ssl [In] The SSL connection reference from which the regeneration is requested.

Returns:
1 indicates the renegotiation request was successfully set or if the SSL is already in a state to begin a handshake.
0 indicates otherwise.

SSLv2 always returns 1.
The renegotiation may occur at the next I/O operation, or it may be delayed until client or server buffers are flushed. The precise operation also depends on the state of the other side of the connection as a handshake is required to renegotiate.

int SSL_shutdown ( SSL * ssl ) ;

Shuts down the SSL protocol on a connection. This function should be called for the specified ssl before the socket is closed. The session identifier will not be re-used until a shutdown message is received.
Parameters:

ssl [In] The SSL connection reference to shut down.

Returns:
1 indicates the connection is successfully shut down or if the SSL is invalid.
<= 0 indicates the connection failed to shut down.
If a handshake is in progress, a call will return -1 because the shutdown is ignored. In most cases a connection will result.

The connection may fail to shut down because data is still in the process of being transmitted or because of non-blocking returns. Another call to this function may be required to complete the shutdown process.
On error, if the shutdown protocol has not finished, the error can be ignored or the application may perform alternate operations depending on the error. For example, if the peer has closed the socket, ignore the error. If a non-blocking read or write error occurs, recall SSL_shutdown() when the socket operation will not fail.
See also:
SSL_set_anytime_shutdown(), SSL_CTX_set_anytime_shutdown() and SSL_CTX_get_anytime_shutdown().
Samples:
cache_server.c, fips_client.c, PKCS11Client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

int SSL_want ( SSL * ssl ) ;

Returns the read/write state value from the SSL. The rwstate field stores the type of operation that was not completed during a non-blocking I/O attempt. The states returned by SSL_want() are defined in Non-Blocking Input/Output States.
Parameters:

ssl [In] The SSL reference from which to retrieve the non-blocking I/O operation.

Returns:
The operation that was not completed during non-blocking I/O.

An SSL_read() or SSL_write() that triggers an SSL handshake sequence can set any of the Non-Blocking Input/Output States values.

int SSL_write ( SSL * ssl,

char * buf,

int num

) ;

Writes num Bytes from the buffer buf to the SSL connection associated with ssl.
Parameters:

ssl [In] The SSL connection reference that performs the write.

buf [In] The buffer of data to write.

num [In] The number of Bytes to write.

Returns:
The number of Bytes actually written. One of:

0 indicates the connection is shut down.
-1 indicates there is an error or non-blocking return.

Use SSL_get_error() to interpret any errors.
See also:
SSL_read() and SSL_want().
Samples:
fips_client.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.