	RSA BSAFE Micro Edition Suite	Streamlined security for mobile and embedded devices

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_in_init (SSL *ssl)
	Indicates whether the SSL handshake is in progress against ssl. More...
int	SSL_in_before (SSL *ssl)
	Indicates whether the SSL handshake is at a state before initialization against ssl. More...
int	SSL_in_connect_init (SSL *ssl)
	Indicates whether the SSL handshake is in client initialization state against ssl. More...
int	SSL_in_accept_init (SSL *ssl)
	Indicates whether the SSL handshake is in server initialization state against ssl. More...
int	SSL_want_nothing (SSL *ssl)
	Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_NOTHING. More...
int	SSL_want_read (SSL *ssl)
	Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_READING. More...
int	SSL_want_write (SSL *ssl)
	Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_WRITING. More...
int	SSL_want_x509_lookup (SSL *ssl)
	Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_X509_LOOKUP. More...
int R_CDECL	SSL_do_handshake (SSL *ssl)
	Performs the initialization sequence to set up an SSL connection for the specified SSL. More...
int R_CDECL	SSL_renegotiate (SSL *ssl)
	Sets a flag indicating a renegotiation should occur before any additional data is transmitted for the specified ssl. More...
int R_CDECL	SSL_shutdown (SSL *ssl)
	Shuts down the SSL protocol on a connection. More...
int R_CDECL	SSL_accept (SSL *ssl)
	Starts the read of a handshake by the server. More...
int R_CDECL	SSL_connect (SSL *ssl)
	Starts the read of the server handshake by the client (after the client has sent the first message). More...
int R_CDECL	SSL_read (SSL ssl, char buffer, int num)
	Reads the requested number of Bytes into the buffer buf through an SSL. More...
int R_CDECL	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 R_CDECL	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 R_CDECL 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 R_CDECL 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 R_CDECL 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:
p7ssl_client.c, and ssl_client.c.

int SSL_in_accept_init ( SSL * ssl ) ;

Indicates whether the SSL handshake is in server initialization state against ssl.
Parameters:

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

Returns:
The initialization state. One of:

0 indicates no initialization.
1 indicates the state is in server initialization.
See also:
SSL_do_handshake().

int SSL_in_before ( SSL * ssl ) ;

Indicates whether the SSL handshake is at a state before initialization against ssl.
Parameters:

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

Returns:
The initialization state. One of:

0 indicates the state is not before initialization.
1 indicates the state is before initialization.
See also:
SSL_do_handshake().

int SSL_in_connect_init ( SSL * ssl ) ;

Indicates whether the SSL handshake is in client initialization state against ssl.
Parameters:

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

Returns:
The initialization state. One of:

0 indicates the state is not in client initialization.
1 indicates the state is in client initialization.
See also:
SSL_do_handshake().

int SSL_in_init ( SSL * ssl ) ;

Indicates whether the SSL handshake is in progress against ssl.
Parameters:

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

Returns:
The initialization state. One of:

0 indicates initialization is not in progress.
1 indicates initialization is in progress.
See also:
SSL_do_handshake().

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 R_CDECL 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. Must be large enough to contain the number of Bytes requested.

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.

The data remains in the input stream and can be read again.

int R_CDECL 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.
Must be large enough to contain the number of Bytes requested.

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, p7ssl_client.c, p7ssl_server.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.

int R_CDECL 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 R_CDECL 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.
The behavior of this function is modified by the option ANYTIME_SHUTDOWN to allow a shut down during the handshake.

No new read or write requests will be performed after a connection has shut down.

See also:
SSL_set_anytime_shutdown(), SSL_CTX_set_anytime_shutdown() and SSL_CTX_get_anytime_shutdown().
Samples:
cache_server.c, p7ssl_client.c, p7ssl_server.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 operation. 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 a handshake sequence can set any of the above values. For example, after SSL_read(), SSL_want() could return SSL_WRITING.

int SSL_want_nothing ( SSL * ssl ) ;

Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_NOTHING.
Parameters:

ssl [In] The SSL reference from which to retrieve rwstate.

Returns:
1 indicates that the operation that was not completed during non-blocking I/O was SSL_NOTHING.
0 indicates that some other operation was not completed during non-blocking I/O.
See also:
SSL_want().

int SSL_want_read ( SSL * ssl ) ;

Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_READING.
Parameters:

ssl [In] The SSL reference from which to retrieve the rwstate.

Returns:
1 indicates that the operation that was not completed during non-blocking I/O was SSL_READING.
0 indicates that some other operation was not completed during non-blocking I/O.
See also:
SSL_want().

int SSL_want_write ( SSL * ssl ) ;

Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_WRITING.
Parameters:

ssl [In] The SSL reference from which to retrieve the rwstate.

Returns:
1 indicates that the operation that was not completed during non-blocking I/O was SSL_WRITING.
0 indicates that some other operation was not completed during non-blocking I/O.
See also:
SSL_want().

int SSL_want_x509_lookup ( SSL * ssl ) ;

Returns whether or not the type of operation that was not completed during a non-blocking I/O operation was SSL_X509_LOOKUP.
Parameters:

ssl [In] The SSL reference from which to retrieve rwstate.

Returns:
1 indicates that the operation that was not completed during non-blocking I/O was SSL_X509_LOOKUP.
0 indicates that some other operation was not completed during non-blocking I/O.
See also:
SSL_want().

int R_CDECL 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.
Must be valid.

buf [In] The buffer of data to write.
Must be valid.

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:
p7ssl_client.c, p7ssl_server.c, simple.c, sock_client.c, sock_server.c, ssl_client.c, and ssl_server.c.