RSA BSAFE SSL-C

Security protocol components for C

Search

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_set_max_rsa_n_size (SSL *ssl, unsigned long size)
 Allows the server to set the maximum size of the client certificate public key modulus. More...

long SSL_set_max_rsa_e_size (SSL *ssl, unsigned long size)
 Allows the server to set the maximum size of the client certificate public key exponent. More...

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

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

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

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

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

void 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 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* 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 SSL_get_ciphers_count (SSL *ssl)
 Returns the number of ciphers in the cipher list for the specified ssl. More...

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

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

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

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

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

STACK* SSL_get_peer_cert_chain (SSL *ssl)
 Returns the certificate chain sent by the peer application for the SSL connection 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* 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 returned value is a pointer to the value in the structure, so do not attempt to SSLCERT_free() this value.

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

STACK* SSL_get_peer_cert_chain (  SSL *    ssl )  ;
 

Returns 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 from which to retrieve the certificate chain.
Returns:
The STACK reference containing the chain of peer certificates.
NULL indicates no certificate chain.
See also:
SSL_get_peer_cert_chain_count() and SSL_get_peer_cert_chain_item().

int 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:
PKCS11Client.c, and ssl_client.c.

SSLCERT* 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* 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.

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

Returns the names of the shared ciphers of the SSL.

Parameters:
ssl [In, Out] The SSL connection reference from which to retrieve the shared ciphers.
buf [Out] The buffer to store the string of shared cipher names.
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.

char* 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.
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 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 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.
    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, sock_server.c, and ssl_server.c.

    int 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 names to load.
    Returns:
    1 indicates success.
    0 indicates the cipher list was unable to be loaded.
    note.gif
    This function ignores any unrecognized cipher names and does not display any errors indicating the cipher was ignored. Any SSL cipher suites that are dependent on ciphers/digests not loaded via SSLC_library_new() are not available.
    The most common settings are:

    Setting Description
    EXP Only supports export ciphers. Export ciphers have up to 56-bit symmetric ciphers and 1024-bit public keys.
    ALL:!EXP Only supports strong (non-export) ciphers. Export ciphers have up to 56-bit symmetric ciphers and 1024-bit public keys.

    note.gif
    A full list of cipher suites is available via the sslc ciphers utility.
    Refer to Cipher List Formatting Rules in the Utilities Guide for further information.
    When operating in FIPS 140-enabled mode, no error is displayed while setting a non-FIPS 140 cipher suite. However, non-FIPS cipher suites are ignored during the handshake and an error displayed indicating there are no ciphers shared with the peer.

    See also:
    SSL_get_cipher_list() and SSL_CTX_set_cipher_list().
    Example:

    int ret;
char *cipher_str;
SSL *ssl;

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

cipher_str = "RC4:DES:!EXP";

ret = SSL_set_cipher_list(ssl,cipher_str);

if (ret == 0) 
{
    printf("Failed to add ciphers\n" );
}

    void 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.
    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:
    fips_client.c, PKCS11Client.c, simple.c, sock_client.c, and ssl_client.c.

    long SSL_set_max_rsa_e_size (  SSL *    ssl,
    unsigned long    size
    )  ;
     

    Allows the server to set the maximum size of the client certificate public key exponent. The length is specified in numbers of bits

    Parameters:
    ssl [In, Out] The SSL connection reference.
    size [In] The maximum size of the RSA public key exponent.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    This function enables the server to prevent denial of service as a result of the client passing very large keys.
    See also:
    SSL_set_max_rsa_n_size().

    long SSL_set_max_rsa_n_size (  SSL *    ssl,
    unsigned long    size
    )  ;
     

    Allows the server to set the maximum size of the client certificate public key modulus. The length is specified in numbers of bits.

    Parameters:
    ssl [In, Out] The SSL connection reference.
    size [In] The maximum size of the RSA public key modulus.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    This function enables the server to prevent denial of service as a result of the client passing very large keys.
    See also:
    SSL_set_max_rsa_e_size().

    int SSL_version (  SSL *    ssl )  ;
     

    Returns the SSL version negotiated during the handshake.

    Parameters:
    ssl [In] A reference to the SSL structure that negotiated the protocol version.
    Returns:
    The SSL protocol version negotiated during the handshake. One of:
  • SSL2_VERSION.
  • SSL3_VERSION.
  • TLS1_VERSION (both TLSv1 and SSLv23).
    • Example:

    SSL *ssl;
int ret;

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

/* SSL_connect(ssl) */

ret = SSL_version(ssl);

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

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