RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Connection Status Functions

This section describes the functions that specify the status of the connection.

Functions

long SSL_add_explicit_cert_chain (SSL *ssl, SSLCERT *x509)
 Allows precise specification of the certificate chain to be sent in addition to the SSL's own certificate. More...

long SSL_clear_explicit_cert_chain (SSL *ssl)
 Removes all certificates in an explicit certificate chain attached to an ssl. More...

int R_CDECL SSL_set_cipher_list (SSL *ssl, char *str)
 Specifies the ciphers to be used by the SSL. More...

char* R_CDECL SSL_get_cipher_list (SSL *ssl, int idx)
 Returns the textual name for the cipher at the given index. More...

char* R_CDECL SSL_get_shared_ciphers (SSL *ssl, char *buffer, int len)
 Returns the names of the shared ciphers of the SSL on the server. More...

void R_CDECL SSL_set_connect_state (SSL *ssl)
 Sets the SSL flags and functions for a client-side connection. More...

void R_CDECL SSL_set_accept_state (SSL *ssl)
 Sets the SSL connection ssl in the accept state (that is, the server side of an SSL connection). More...

int R_CDECL SSL_get_peer_cert_chain_count (SSL *ssl)
 Returns the number of items in the certificate chain sent by the peer application for the SSL connection ssl. More...

SSLCERT* R_CDECL SSL_get_peer_cert_chain_item (SSL *ssl, int n)
 Returns a pointer to an element of the chain of certificate information sent by the peer application for the SSL connection ssl. More...

int R_CDECL SSL_get_ciphers_count (SSL *ssl)
 Returns the number of ciphers in the cipher list for the specified ssl. More...

SSL_CIPHER* R_CDECL SSL_get_ciphers_item (SSL *ssl, int n)
 Returns a specific cipher in the cipher list for the specified ssl. More...

int R_CDECL SSL_pending (SSL *ssl)
 Indicates additional buffered data is available internally for the application to read for the specified ssl. More...

char* R_CDECL SSL_get_version (SSL *ssl)
 Returns a string representation of the SSL protocol version of the SSL. More...

SSLCERT* R_CDECL SSL_get_certificate (SSL *ssl)
 Returns the current authenticating certificate of the SSL. More...

SSLCERT_PKEY* R_CDECL SSL_get_privatekey (SSL *ssl)
 Returns the currently active private key of the SSL. More...

SSLCERT* R_CDECL SSL_get_peer_certificate (SSL *ssl)
 Returns the peer certificate of an SSL. More...

int SSL_version (SSL *ssl)
 Returns the SSL version negotiated during the handshake. More...

Function Documentation

long SSL_add_explicit_cert_chain (  SSL *    ssl,
SSLCERT *    x509
)  ;
 

Allows precise specification of the certificate chain to be sent in addition to the SSL's own certificate. The function adds a single certificate to an existing or empty chain. The chain will be sent in the order that the certificates are added (that is, the first certificate added will be the first certificate sent after the SSL's own certificate).

Parameters:
ssl [In, Out] The SSL connection reference.
x509 [In] The next certificate structure in the certificate chain.
Returns:
1 indicates success.
0 indicates error.
note.gif
This functionality is only valid for SSLv3 and TLSv1 connections. Developers are responsible for ensuring that a valid certificate chain is specified.
See also:
SSL_clear_explicit_cert_chain().
Example:

#define MY_CERT_CHAIN_LENGTH 3

static unsigned char my_cert_binary[493]=
{
    /* ..... binary certificate
 */
};
static unsigned char cert_binary[493]=
{
    /* ..... binary certificate */
};
SSL *ssl;
SSLCERT *cert;
int ret, i, ok;
char *my_cert_filename = "this_is_me.pem";
char *my_ca_filename[MY_CERT_CHAIN_LENGTH] = {
        "my_ca.pem",
        "ca_ca.pem",
        "root_ca.pem"
};
unsigned char *data;
BIO *cert_bio;
int identity = 1;


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


/* Load a certificate for this SSL to use as identity */
data = my_cert_binary;
cert=SSLCERT_from_binary(NULL,&data,sizeof(my_cert_binary));
identity = SSL_use_certificate(ssl,cert);
if (identity == 0)
{
    /* Failed to load a certificate - cannot prove myself */
    printf("Failed to load my own certificate!!\n");
}

/* Only try loading a chain if we have a certificate for the end of it */
if (identity)
{
    for (i=0; i<MY_CERT_CHAIN_LENGTH; i++)
    {
        /* Read an SSLCERT structure from the binary certificate */
        data = cert_binary;
        cert=SSLCERT_from_binary(NULL,&data,sizeof(cert_binary));
        
        /* Add the certificate to the SSL structure */
        if ((cert == NULL) || !SSL_add_explicit_cert_chain(ssl,cert))
        {
            /* Failed to get the cert - Check the error codes */
            printf("Failed to build my own certificate chain\n");
            
            /* This chain will be incomplete so there is
             * No valid way to stay in this simple loop.
             * Clear out this chain and leave the loop.
             */
            SSL_clear_explicit_cert_chain(ssl);
            break;
        }
        
        /* Close the file */
        BIO_free(cert_bio);
    }
}

/* Use the SSL */


/* Free the SSL (and free any explicit cert chain with it) */
SSL_free(ssl);

long SSL_clear_explicit_cert_chain (  SSL *    ssl )  ;
 

Removes all certificates in an explicit certificate chain attached to an ssl. The certificate structures are also freed by this operation.

Parameters:
ssl [In, Out] The SSL connection reference.
Returns:
1 indicates success.
0 indicates error.
See also:
SSL_add_explicit_cert_chain().

SSLCERT* R_CDECL SSL_get_certificate (  SSL *    ssl )  ;
 

Returns the current authenticating certificate of the SSL.

Parameters:
ssl [In] The SSL to query for a certificate.
Returns:
The certificate from the SSL.
NULL indicates the SSL does not have an authenticating certificate.
note.gif
The current certificate of the SSL is the one that was last loaded (if before a handshake) or the one that was used to authenticate the SSL (if after a handshake).
The returned value is a pointer to the value in the structure, so do not attempt to SSLCERT_free() this value.

char* R_CDECL SSL_get_cipher_list (  SSL *    ssl,
int    indx
)  ;
 

Returns the textual name for the cipher at the given index. Allows iterations on the list of the ciphers available for use for the specified ssl.

Parameters:
ssl [In] The SSL that holds the ciphers.
indx [In] The index of the cipher.
Returns:
The name of the cipher at position indx.
NULL indicates there is no cipher at that position.
note.gif
This function returns a pointer to an internal data structure. The caller should not free the memory associated with the returned pointer as this will corrupt the data stored in the internal library structures.
See also:
SSL_get_ciphers().
Example:

int i;
char *cipher_str;
SSL *ssl;

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

/* Either default ciphers exist from SSL_CTX */
/* or SSL_set_cipher_list(ssl,...);          */

for (i=0; 1; i++)
{
        c=SSL_get_cipher_list(ssl, i);
        if (c == NULL)
        {
                break;
        }

        printf("%s\n", c);
}

int R_CDECL SSL_get_ciphers_count (  SSL *    ssl )  ;
 

Returns the number of ciphers in the cipher list for the specified ssl.

Parameters:
ssl [In] The SSL connection reference.
Returns:
The number of ciphers.
See also:
SSL_get_ciphers() and SSL_get_ciphers_item().
Example:

int count;
SSL *ssl;

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

/* Either default ciphers exist from SSL_CTX */
/* or SSL_set_cipher_list(ssl,...);          */

count = SSL_get_ciphers_count(ssl);

SSL_CIPHER* R_CDECL SSL_get_ciphers_item (  SSL *    ssl,
int    indx
)  ;
 

Returns a specific cipher in the cipher list for the specified ssl.

Parameters:
ssl [In] The SSL connection reference.
indx [In] The index of the cipher. The ciphers are indexed from 0 up to (num-1).
Returns:
An SSL_CIPHER reference.
NULL indicates the specified index is out of range or there are no valid ciphers available for the SSL structure.
See also:
SSL_CIPHER_get_name(), SSL_CIPHER_get_bits() and SSL_get_ciphers_count().
Example:

int i, count;
SSL_CIPHER *ciph;
SSL *ssl;

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

/* Either default ciphers exist from SSL_CTX */
/* or SSL_set_cipher_list(ssl,...);          */

count = SSL_get_ciphers_count(ssl);

for (i=0; i<count; i++ )
{
        ciph = SSL_get_ciphers_item(ssl, i);
        printf("cipher[%d] = %s\n",i,SSL_CIPHER_get_name(ciph));
}

int R_CDECL SSL_get_peer_cert_chain_count (  SSL *    ssl )  ;
 

Returns the number of items in the certificate chain sent by the peer application for the SSL connection ssl. This function should be called after the handshake or re-negotiation finishes. It also contains valid values during the certificate verification process.

Parameters:
ssl [In] The SSL connection reference.
Returns:
The number of items in peer certificate chain.
0 indicates the SSL is invalid or has no peer certificates.
See also:
SSL_get_message_size() and SSL_get_peer_cert_chain_item().
Example:

SSL *ssl;
int count;

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

/* SSL_connect(ssl) */

count = SSL_get_peer_cert_chain_count(ssl);
if ( count == 0 )
{
        printf("No certificates received from the peer\n");
}
Samples:
p7ssl_client.c, and ssl_client.c.

SSLCERT* R_CDECL SSL_get_peer_cert_chain_item (  SSL *    ssl,
int    indx
)  ;
 

Returns a pointer to an element of the chain of certificate information sent by the peer application for the SSL connection ssl. The application uses this information to help verify the passed certificate. This function should be called after the handshake or re-negotiation finishes. It also contains valid values when called from verification callbacks.

Parameters:
ssl [In] The SSL connection reference.
indx [In] The index of the certificate in the chain.
Returns:
A reference of the SSLCERT certificate at index indx.
NULL indicates there are no peer certificates or that indx is out of range (that is, indx < 0 or indx > num_cert).
See also:
SSL_get_message_size() and SSL_get_peer_cert_chain_count().
Example:

SSL *ssl;
int count;
int i;
BIO *bio
SSLCERT *cert;

/* bio = BIO_new_fp(stdout,...) */

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

/* SSL_connect(ssl) */

count = SSL_get_peer_cert_chain_count(ssl);

/* Walk the chain and print the details. The first
 * certificate is the peer's certificate
 */
for (i = 0; i < count; i++)
{
        cert = SSL_get_peer_cert_chain_item(ssl,i);

        /* Use my own function to print certificate data */
        print_cert_info(bio,cert);
}

SSLCERT* R_CDECL SSL_get_peer_certificate (  SSL *    ssl )  ;
 

Returns the peer certificate of an SSL. After establishing the SSL connection ssl, this function indicates the certificate used by the peer. There is no peer certificate if the process is a server and is not performing client authentication.

Parameters:
ssl [In, Out] The SSL connection reference from which to retrieve the peer certificate.
Returns:
The peer certificate.
NULL indicates there is no certificate.
note.gif
The SSL must have a valid session to be able to return a peer certificate.
The peer certificate that is returned has its reference count incremented and must therefore be freed by the caller.
Example:

SSL *ssl;
SSLCERT *cert;

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

/* SSL_connect(ssl) */

cert = SSL_get_peer_certificate(ssl);

/* Process certificate in an application-dependent manner */

SSLCERT_free(cert);

SSLCERT_PKEY* R_CDECL SSL_get_privatekey (  SSL *    ssl )  ;
 

Returns the currently active private key of the SSL.

Parameters:
ssl [In] The SSL to query for a private key.
Returns:
The private key from the SSL.
NULL if the SSL does not have an private key.
note.gif
The current private key of the SSL is the one that was last loaded (if before a handshake) or the one that was used to authenticate the SSL (if after a handshake).
The private key is a reference to the actual key. It will only be valid for the lifetime of the SSL from which it has been obtained.

char* R_CDECL SSL_get_shared_ciphers (  SSL *    ssl,
char *    buf,
int    len
)  ;
 

Returns the names of the shared ciphers of the SSL on the server.

Parameters:
ssl [In, Out] The SSL connection reference from which to retrieve the shared ciphers. An SSL connection must be present so that shared ciphers exist.
buf [Out] The buffer to store the string of shared cipher names.
Must be large enough to hold the final string.
len [In] The length of the string buffer.
Returns:
The string of the shared cipher names.
NULL indicates there are no shared ciphers or the buffer is too small to hold any ciphers. The buffer may be missing some ciphers if it is not large enough to hold all ciphers.
This function returns NULL on the client.
note.gif
The client sends a server a list of its available ciphers. The server determines the shared ciphers from the client's available ciphers and its own ciphers. The server will choose the cipher the connection will use from the shared cipher list and send this to the client. The client is not aware of the server's available ciphers or the shared ciphers.
Example:

#define BUFSIZE 1024 

SSL *ssl;
char buf[BUFSIZE];
char *buf_ptr;

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

/* Make a successful SSLv2 connection */

buf_ptr = SSL_get_shared_ciphers(ssl,buf,BUFSIZE);

if (buf_ptr == NULL)
{
        printf('There are no shared ciphers\n");
}

char* R_CDECL SSL_get_version (  SSL *    ssl )  ;
 

Returns a string representation of the SSL protocol version of the SSL. This function should be called after the connection is established, and indicates whether SSLv2, SSLv3 or TLSv1 was negotiated as the communications protocol for the specified ssl.

Parameters:
ssl [In] The SSL connection reference from which to retrieve the SSL protocol version.
Must be a valid reference.
Returns:
A static string indicating the protocol version. One of:
  • "SSLv2".
  • "SSLv3".
  • "TLSv1".
  • "Unknown.
    • note.gif
    As the string is a static value do not attempt to free it.
    See also:
    SSL_version().
    Example:

    SSL *ssl;
char *version;

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

/* SSL_connect(ssl) */

version = SSL_get_version(ssl);

if (strcmp("unknown",version) == 0) 
{
        /* Deal with probable error condition */
}

    int R_CDECL SSL_pending (  SSL *    ssl )  ;
     

    Indicates additional buffered data is available internally for the application to read for the specified ssl. This results from the way the SSL protocol encrypts data in blocks, which have to be decrypted as a whole, but the application may only partly read the decrypted block. The remaining Bytes can be read from the internal decrypted data buffer without reading any more data from the peer. When using select system calls, SSL_pending() helps the application avoid waiting for data from the peer when it is already available (decrypted) in a local buffer.

    Parameters:
    ssl [In] The SSL connection reference requiring read buffer checking.
    Returns:
    The number of Bytes available for reading.
    Example:

    SSL *ssl;
int bytes;

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

/* bytes = SSL_read(ssl,...); ... */

/* Read the rest of the buffer */
while (SSL_pending(ssl) > 0)
{
        /* bytes = SSL_read(ssl,....); ... */
}

    void R_CDECL SSL_set_accept_state (  SSL *    ssl )  ;
     

    Sets the SSL connection ssl in the accept state (that is, the server side of an SSL connection). Therefore when an SSL_do_handshake() or an SSL_read() or SSL_write() is called, the server side of the SSL protocol is initiated. Resets all data in the SSL but does not perform a handshake.

    Parameters:
    ssl [In] The SSL connection reference against which to set the accept state.
    note.gif
    All SSL data is reset to an initial state and the handshake function is set to server accept.
    See also:
    SSL_set_connect_state() and SSL_accept().
    Example:

    SSL *ssl;

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

SSL_set_accept_state(ssl);

/* SSL_read(ssl,...) */
    Samples:
    cache_server.c, p7ssl_server.c, sock_server.c, and ssl_server.c.

    int R_CDECL SSL_set_cipher_list (  SSL *    ssl,
    char *    str
    )  ;
     

    Specifies the ciphers to be used by the SSL. Sets the ciphers available for use with the SSL connection ssl. The ciphers specified in str override the ciphers specified via SSL_CTX_set_cipher_list().

    Parameters:
    ssl [In, Out] The SSL connection reference against which to set the cipher list.
    str [In] The list of cipher suite names to load. The options are:
    • RC4-SHA
    • RC4-MD5
    • EXP-RC4-MD5
    • DES-CBC3-SHA
    • DES-CBC-SHA
    • EXP-DES-CBC-SHA
    • AES128-SHA
    • AES256-SHA
    • NULL-SHA
    • NULL-MD5
    Note that NULL-* cipher suites will not be used unless SSL_feature_set() is called with the argument SSL_FEATURE_ALLOW_ENULL.
    Returns:
    1 indicates success.
    0 indicates that the cipher list was not loaded.
    note.gif
    This function ignores any unrecognized cipher names. No error is displayed indicating the cipher was ignored.
    See also:
    SSL_get_cipher_list() and SSL_CTX_set_cipher_list().

    void R_CDECL SSL_set_connect_state (  SSL *    ssl )  ;
     

    Sets the SSL flags and functions for a client-side connection. Puts the SSL connection reference ssl in the connect state (that is, the client side of an SSL connection). Therefore when an SSL_do_handshake() or an SSL_read() or SSL_write() is called, the client side of the SSL protocol is initiated. Resets all data in the SSL but does not perform a handshake.

    Parameters:
    ssl [In] The SSL connection reference against which to set the connect state.
    note.gif
    All SSL data is reset to an initial state and the handshake function is set to client connect.
    See also:
    SSL_set_accept_state() and SSL_connect().
    Example:

    SSL *ssl;

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

SSL_set_connect_state(ssl);

/* if ( SSL_write(ssl,...) > 0 ) ... */
    Samples:
    p7ssl_client.c, simple.c, sock_client.c, and ssl_client.c.

    int SSL_version (  SSL *    ssl )  ;
     

    Returns the SSL version negotiated during the handshake. There are three options:

  • SSL2_VERSION.
  • SSL3_VERSION.
  • TLS1_VERSION (both TLSv1 and SSLv23).
    Parameters:
    ssl [In] The SSL structure.
    Returns:
    The ssl version negotiated during handshake.
    note.gif
    The SSL version is determined during the exchange of Hello messages at the start of the SSL handshake. Before the handshake, the version is an undefined value.
    ssl is not NULL.
    See also:
    SSL_get_version().
    Example:

    SSL *ssl;
int ret;

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

/* SSL_connect(ssl) */

ret = SSL_version(ssl);

if (ret == TLS1_VERSION)  
{
    /* Working with TLSv1 */
}
    Samples:
    simple.c.
    		•

    Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 072-001001-2100-001-000 - 2.1