RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Information Functions

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

Functions

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

char* R_CDECL 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* R_CDECL SSL_state_string_long (SSL *ssl)
 Returns a descriptive message indicating the current SSL handshake state for the SSL connection ssl. More...

char* R_CDECL 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* R_CDECL SSL_alert_type_string_long (int value)
 Returns a textual description of the alert type in string form. More...

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

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

char* R_CDECL 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 current state of the SSL handshake by directly accessing the state field of the SSL structure. More...

int SSL_reuse (SSL *ssl)
 Indicates whether the SSL session identifier is being re-used on the SSL connection ssl. More...

Function Documentation

char* R_CDECL 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* R_CDECL 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* R_CDECL 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* R_CDECL 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 )  ;
 

Indicates whether the SSL session identifier is being re-used on the SSL connection ssl. Public-key encryption algorithms are very 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 the session identifier is not being reused.

char* R_CDECL 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* R_CDECL 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 current state of the SSL handshake by directly accessing the state field of the SSL structure. SSL_state() can be invoked from inside the information callback function returning information about the handshake.

    Parameters:
    ssl [In] The SSL structure.
    note.gif
    ssl is not NULL.
    Returns:
    The current (or last successful) handshake state. Refer to ssl3.h and tls1.h for a full list of states.
    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* R_CDECL 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* R_CDECL 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-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1