RSA BSAFE SSL-C

Security protocol components for C

Search

Information Functions

This section details the functions that provide information about the state of the SSL handshake.

Functions

char* SSL_state_string (SSL *ssl)
 Returns a short string indicating the current SSL handshake state for the specified ssl. More...

char* SSL_rstate_string (SSL *ssl)
 Returns a short string indicating the state of the read operation of an SSL record currently being performed by the SSL structure ssl. More...

char* SSL_state_string_long (SSL *ssl)
 Returns a descriptive message indicating the current SSL handshake state for the SSL connection ssl. More...

char* SSL_rstate_string_long (SSL *ssl)
 Returns the full string indicating the state of the read operation of an SSL record currently being performed by the SSL structure ssl. More...

char* SSL_alert_type_string_long (int value)
 Returns a textual description of the alert type in string form. More...

char* SSL_alert_type_string (int value)
 Returns a textual description of the alert type in a short string form. More...

char* SSL_alert_desc_string_long (int value)
 Returns a textual description of the alert value in string form. More...

char* SSL_alert_desc_string (int value)
 Returns a textual description of the alert value in a short string form. More...

int SSL_state (SSL *ssl)
 Returns the handshake state information for the SSL structure ssl.
The state information indicates whether the handshake is the client or server side. More...

int SSL_reuse (SSL *ssl)
 Determines if the current SSL session identifier is being reused on the SSL connection ssl. More...

Function Documentation

char* SSL_alert_desc_string (  int    value )  ;
 

Returns a textual description of the alert value in a short string form. The values are detailed in the Short Description column below. Alert values generated during the handshake are visible to SSL_INFO_CB_T if this callback has been implemented by the developer.

Parameters:
value [In] The alert value.
Returns:
The short textual form of a description for the alert value. One of:
Short Description Long Description
BC
Bad certificate.
BM
Bad record MAC.
CE
Certificate expired.
CN
Close notify.
CR
Certificate revoked.
CU
Certificate unknown.
DF
Decompression failure.
HF
Handshake failure.
IP
Illegal parameter.
NC
No certificate.
UC
Unsupported certificate.
UK
Unknown.
UM
Unexpected message.
note.gif
Alert values are only available in SSLv3 and TLSv1.
See also:
SSL_alert_desc_string_long(), SSL_INFO_CB_T and SSL_CTX_set_message_size().

char* SSL_alert_desc_string_long (  int    value )  ;
 

Returns a textual description of the alert value in string form. The values are detailed in the Long Description column below. Alert values generated during the handshake are visible to SSL_INFO_CB_T if this callback has been implemented by the developer.

Parameters:
value [In] The alert value.
Returns:
The long textual form of a description for the alert value. One of:
Short Description Long Description
BC Bad certificate.
BM Bad record MAC.
CE Certificate expired.
CN Close notify.
CR Certificate revoked.
CU Certificate unknown.
DF Decompression failure.
HF Handshake failure.
IP Illegal parameter.
NC No certificate.
UC Unsupported certificate.
UK Unknown.
UM Unexpected message.
note.gif
Alert values are only available in SSLv3 and TLSv1.
See also:
SSL_set_info_cb().
Example:

SSL *ssl;
int ret;

/* Create a new SSL structure */
/* ssl = SSL_new(...) */

/* Attach an info callback to the SSL structure */
SSL_set_info_cb(ssl,my_ssl_info_cb);

/* Make a connection. Handshake will activate the callback */

/* For example, at the start of handshake, where = SSL_CB_HANDSHAKE_START */

/* For example, if an out of order message arrives and triggers an alert to
 * send to the other party, where = SSL_CB_WRITE_ALERT
 */

/* See "ssl.h" for callback constants */


/* --- User defined callback function --- */

void my_ssl_info_cb(ssl,where,ret)
SSL *ssl;
int where;
int ret;
{
        BIO *output;    /* A log pointer */
        char *desc_str; /* The description string for alerts */
        char *level_str; /* The level string for alerts */
        int our_alert;  /* A flag: Did we generate the alert? */

        if ((where & SSL_CB_ALERT) != 0)
        {
                /* An alert has been sent in SSLv3 */

                /* Open an output BIO for logging */
                output = BIO_new_fp(stderr,BIO_NOCLOSE);

                /* Detect if we generated or received the alert */
                our_alert = where & SSL_CB_WRITE;

                /* Extract the type & description from the ret value */
                level_str = SSL_alert_type_string_long(ret);
                desc_str = SSL_alert_desc_string_long(ret);

                /* Log the problem with long version of strings */
                if (our_alert)
                {
                        BIO_printf(output,"ALERT: Alert generated\n");
                }
                else
                {
                        BIO_printf(output,"ALERT: Alert received\n");
                }

                BIO_printf(output,"ALERT: Level=%s Description=%s\n",
                                level_str,desc_str);
                BIO_free(output);
        }
        else
        {
                /* A handshake state message has been passed */

                /* Deal with state messages appropriately */
        }

        return ;
}

char* SSL_alert_type_string (  int    value )  ;
 

Returns a textual description of the alert type in a short string form. The values are detailed in the Short Description column below. Alert values generated during the handshake are visible to SSL_INFO_CB_T if this callback has been implemented by the developer.

Parameters:
value [In] The alert value.
Returns:
The short textual form of a description for the alert value. One of:
Short Description Long Description
F Fatal.
U Unknown.
W Warning.
note.gif
Alert values are only available in SSLv3 and TLSv1.
See also:
SSL_alert_type_string_long().

char* SSL_alert_type_string_long (  int    value )  ;
 

Returns a textual description of the alert type in string form. The values are detailed in the Long Description column below. Alert values generated during the handshake are visible to SSL_INFO_CB_T if this callback has been implemented by the developer.

Parameters:
value [In] The alert value.
Returns:
The long textual form of a description for the alert value. One of:
Short Description Long Description
F Fatal.
U Unknown.
W Warning.
note.gif
Alert values are only available in SSLv3 and TLSv1.

int SSL_reuse (  SSL *    ssl )  ;
 

Determines if the current SSL session identifier is being reused on the SSL connection ssl. Public-key encryption algorithms are slow. To improve performance, information exchanged during the handshake can be re-used. This process is called session identifier reuse.

Parameters:
ssl [In] The SSL connection reference where session reuse is checked.
Returns:
1 indicates the session identifier is being reused.
0 indicates otherwise.

char* SSL_rstate_string (  SSL *    ssl )  ;
 

Returns a short string indicating the state of the read operation of an SSL record currently being performed by the SSL structure ssl.

Parameters:
ssl [In] The SSL connection reference where the read state is stored.
Returns:
The state string. One of:
  • RB (SSL_ST_READ_BODY).
  • RD (SSL_ST_READ_DONE).
  • RH (SSL_ST_READ_HEADER).
    • note.gif
    Each string is a two letter mnemonic of the longer string returned by SSL_rstate_string_long().
    Example:

    BIO *log;
SSL *ssl;
char buf[BUFSIZE];
int bytes;

/* log = BIO_new_file(...) */

/* ssl = SSL_new(...) */

if ((bytes=SSL_read(ssl,buf,BUFSIZE)) < 0)
{
        /* Print a message about the read state of the SSL record */
        BIO_printf(log,"READ STATE : %s\n",SSL_rstate_string(ssl));

        /* Other processing */
}

    char* SSL_rstate_string_long (  SSL *    ssl )  ;
     

    Returns the full string indicating the state of the read operation of an SSL record currently being performed by the SSL structure ssl.

    Parameters:
    ssl [In] The SSL connection reference where the read state is stored.
    Returns:
    The state string. One of:
  • SSL_ST_READ_BODY.
  • SSL_ST_READ_DONE.
  • SSL_ST_READ_HEADER.
    • See also:
    SSL_rstate_string().
    Example:

    BIO *log;
SSL *ssl;
int ret;

/* log = BIO_new_file(...) */

/* ssl = SSL_new(...) */

/* Begin a server side accept */
if ((ret=SSL_accept()) < 0)
{
        err_code = SSL_get_error(ssl,ret);

        if (err_code == SSL_ERROR_WANT_READ)
        {
            /* Print a message of the read state of the SSL record */
            BIO_printf(log,"READ STATE : %s\n",
                SSL_rstate_string_long(ssl));
        }
        
        /* Other processing */
}

    int SSL_state (  SSL *    ssl )  ;
     

    Returns the handshake state information for the SSL structure ssl.
    The state information indicates whether the handshake is the client or server side. The state information is useful when the handshake returns from a non-blocking I/O operation, and is also used to determine the last successful completed state if a handshake error occurs. Can be invoked from inside the information callback.

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the current handshake state.
    Returns:
    The current (or last successful) handshake state.
    See also:
    SSL_state_string() and SSL_state_string_long().
    Example:

    SSL *ssl;
char buf[BUFLEN];
int bytes;

/* ssl = SSL_new(...) */

/* First write should trigger a client side handshake */
if ((bytes = SSL_write(ssl,buf,BUFLEN)) <= 0)
{
    
    /* An error occurred - let's check the state */
    state = SSL_state(ssl);
    
    if (state != SSL_ST_OK)
    {
        /* The error occurred during handshake */
        printf ("Last succesful handshake state = %s",
                SSL_state_string_long(state));
    }
    else
    {
        /* Handshake is ok, this is a write problem */
    }
}

    char* SSL_state_string (  SSL *    ssl )  ;
     

    Returns a short string indicating the current SSL handshake state for the specified ssl. The string is a six character mnemonic for the full string provided by SSL_state_string_long().

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the current handshake.
    Returns:
    The state string.
    See also:
    SSL_state() and SSL_state_string_long().
    Example:

    BIO *log;
SSL *ssl;

/* log = BIO_new_file(...) */

/* ssl = SSL_new(...) */

/* Begin a server side accept */
if (SSL_accept() <= 0)
{
    /* Print an error message */
    /* BIO_printf(log, ..) */
    
    /* Print a  log message of the handshake state */
    BIO_printf(log,"HANDSHAKE STATE : %s\n",SSL_state_string(ssl));
    
    /* Other processing */
}

    char* SSL_state_string_long (  SSL *    ssl )  ;
     

    Returns a descriptive message indicating the current SSL handshake state for the SSL connection ssl.

    Parameters:
    ssl [In] The SSL connection reference from which to retrieve the current handshake state.
    Returns:
    The state string.
    See also:
    SSL_state() and SSL_state_string().
    Example:

    SSL *ssl;
char buf[BUFLEN];
int bytes;

/* ssl = SSL_new(...) */

/* First write should trigger a client side handshake */
if ((bytes = SSL_write(ssl,buf,BUFLEN)) <= 0)
{
    
    if (SSL_state(ssl) != SSL_ST_OK)
    {
        /* The error occurred during handshake */
        printf ("Last successful handshake state = %s", 
                SSL_state_string_long(state));
        
        /* More processing */
    }
}

    Copyright (c) 1999-2004 RSA Security Inc. All rights reserved. 050-001001-2600-000-000 - 2.6