RSA BSAFE SSL-C

Security protocol components for C

Search

Certificate Management Functions

This section describes the certificate management functions used to store, retrieve and manipulate certificate-related information. Some applications require that both a certificate and matching private key are loaded. If either is missing, the SSL protocol cannot use the private key or certificate for negotiation.

Typedefs

typedef int SSL_CTX_CLIENT_CERT_CB_T (SSL *ssl, void **cpp, EVP_PKEY **kpp)
 The prototype for a user-defined client certificate callback function. More...


Functions

int SSL_CTX_use_certificate (SSL_CTX *ctx, SSLCERT *x509)
 Binds a certificate to an SSL_CTX structure. More...

int SSL_CTX_use_certificate_ASN1 (SSL_CTX *ctx, unsigned char *cert, long len)
 Binds a certificate in ASN.1 format to the SSL_CTX ctx. More...

int SSL_use_certificate (SSL *ssl, SSLCERT *x509)
 Binds a certificate x509 to the SSL connection ssl. More...

int SSL_use_certificate_ASN1 (SSL *ssl, unsigned char *buffer, long len)
 Binds a certificate data (in ASN.1 format) to the SSL connection ssl. More...

int SSL_use_certificate_file (SSL *ssl, char *file, int type)
 Binds a certificate stored in a specified file to an SSL. More...

int SSL_CTX_use_certificate_file (SSL_CTX *ctx, char *file, int type)
 Binds a certificate stored in a specified file, or hardware module, to an SSL_CTX. More...

int SSL_get_client_CA_list_count (SSL *ssl)
 Returns the number of acceptable Certification Authorities (CAs) for the SSL ssl. More...

SSLCERT_NAME* SSL_get_client_CA_list_item (SSL *ssl, int n)
 Returns the names of the Certification Authorities (CAs) that the server side of the SSL protocol deems acceptable for verification of a client certificate. More...

int SSL_CTX_get_client_CA_list_count (SSL_CTX *ctx)
 Returns the number of acceptable Certification Authorities (CAs) for the SSL_CTX ctx. More...

SSLCERT_NAME* SSL_CTX_get_client_CA_list_item (SSL_CTX *ctx, int n)
 Returns the names of the Certification Authorities (CAs) that the server side of the SSL protocol deems acceptable for verification of a client certificate. More...

void SSL_CTX_set_client_cert_cb (SSL_CTX *ctx, SSL_CTX_CLIENT_CERT_CB_T *cb)
 Sets the client certificate callback for the SSL_CTX ctx. More...

SSL_CTX_CLIENT_CERT_CB_T* SSL_CTX_get_client_cert_cb (SSL_CTX *ctx)
 Returns the application-supplied client certificate callback from the relevant ctx reference. More...

void SSLCERT_reference_inc (SSLCERT *cert)
 Increments the reference count for the specified certificate structure cert. More...

SSLCERT* SSLCERT_new (void)
 Creates a new SSLCERT structure or certificate. More...

void SSLCERT_free (SSLCERT *cert)
 Removes all allocated memory for the certificate cert. More...

void* SSLCERT_PEM_read_bio_SSLCERT (void *bp, SSLCERT **cert, PEM_PASSWORD_CB_T *cb)
 Converts a Privacy Enhanced Mail (PEM) encoded certificate read from a BIO into an SSLCERT structure. More...

int SSLCERT_to_binary (SSLCERT *cert, unsigned char **pp)
 Creates ASN.1 binary certificate data from the specified SSLCERT structure. More...

SSLCERT* SSLCERT_from_binary (SSLCERT **pcert, unsigned char **pp, long length)
 Creates an SSLCERT structure from the specified binary data in ASN.1 format indicated by pp with a length specified by length. More...

void* SSLCERT_from_binary_bio (void *bp, SSLCERT *cert)
 Converts a binary certificate read from a BIO into an SSLCERT structure. More...

Typedef Documentation

typedef int SSL_CTX_CLIENT_CERT_CB_T(SSL *ssl, void **cpp, EVP_PKEY **kpp)
 

The prototype for a user-defined client certificate callback function. The callback is used by the client when a server requests a client certificate. It is best used in situations where the user is required to select from various client certificates. If a certificate and private key are to be sent by the callback, they are returned via the argument list.

Parameters:
ssl [In] The SSL connection reference.
cpp [In] A pointer to the X.509 reference to update.
kpp [In] A pointer to the EVP_PKEY reference to update.
Returns:
-1 indicates re-try.
1 indicates use certificate and EVP_PKEY provided by callback.
0 indicates a client certificate should not be sent.
See also:
SSL_CTX_set_client_cert_cb() and SSL_CTX_get_client_cert_cb().

Function Documentation

int SSL_CTX_get_client_CA_list_count (  SSL_CTX *    ctx )  ;
 

Returns the number of acceptable Certification Authorities (CAs) for the SSL_CTX ctx. Certificates signed by these CAs are accepted by the server side of the SSL protocol.

Parameters:
ctx [In] The SSL_CTX reference where the CA list is stored.
Returns:
The number of CAs. One of:
  • >0 indicates the number of acceptable CAs.
  • 0 indicates there is no client CA list for the SSL_CTX.
    • note.gif
    The SSL_CTX list is the default list for each SSL session. This may be overridden by setting the SSL session to have a particular list.
    See also:
    SSL_CTX_add_client_CA() and SSL_CTX_get_client_CA_list_item().

    SSLCERT_NAME* SSL_CTX_get_client_CA_list_item (  SSL_CTX *    ctx,
    int    n
    )  ;
     

    Returns the names of the Certification Authorities (CAs) that the server side of the SSL protocol deems acceptable for verification of a client certificate.

    Parameters:
    ctx [In] The SSL_CTX reference where the CA list is stored.
    n [In] The index of the certificate in the CA list.
    Returns:
    The subject name of the certificate accessible via an SSLCERT reference.
    NULL indicates there is no client CA list or that n is out of range (that is, n < 0 or n >= max items in the list).
    See also:
    SSL_CTX_get_client_CA_list_count().

    SSL_CTX_CLIENT_CERT_CB_T* SSL_CTX_get_client_cert_cb (  SSL_CTX *    ctx )  ;
     

    Returns the application-supplied client certificate callback from the relevant ctx reference. The callback is best used in situations where the user is required to select from various client certificates.

    Parameters:
    ctx [In] The SSL_CTX reference from which to retrieve the callback.
    Returns:
    The client certificate callback if available.
    NULL indicates error.
    See also:
    SSL_CTX_set_client_cert_cb().

    void SSL_CTX_set_client_cert_cb (  SSL_CTX *    ctx,
    SSL_CTX_CLIENT_CERT_CB_T *    cb
    )  ;
     

    Sets the client certificate callback for the SSL_CTX ctx. This callback can be used to load a client certificate and key during the handshake. It is invoked if no client certificate or key has previously been loaded.

    Parameters:
    ctx [In, Out] The SSL_CTX against which to set the callback.
    cb [In] The client certificate callback.
    note.gif
    If the client_cert_cb is NULL, client certificates are not sent unless the certificate is already attached to the SSL structure.
    See also:
    SSL_CTX_get_client_cert_cb().

    int SSL_CTX_use_certificate (  SSL_CTX *    ctx,
    SSLCERT *    x509
    )  ;
     

    Binds a certificate to an SSL_CTX structure. A certificate must be bound before any additional certificate operations can be performed. This certificate becomes the default certificate used by all SSL connections created for the SSL_CTX.

    Parameters:
    ctx [In] The SSL_CTX reference against which to set the default certificate.
    x509 [In] The SSLCERT reference.
    Returns:
    1 indicates success.
    0 indicates error.
    See also:
    SSL_CTX_use_certificate_ASN1() and SSL_use_certificate().
    Samples:
    bio_server.c, cache_server.c, nbio_server.c, PKCS11Client.c, sock_server.c, and ssl_server.c.

    int SSL_CTX_use_certificate_ASN1 (  SSL_CTX *    ctx,
    unsigned char *    cert,
    long    len
    )  ;
     

    Binds a certificate in ASN.1 format to the SSL_CTX ctx.

    Parameters:
    ctx [In, Out] The SSL_CTX reference against which to set the certificate.
    cert [In] A buffer containing the certificate in ASN.1 format.
    len [In] The certificate buffer length.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    This is the default certificate for each SSL session if no certificate is bound to the SSL structure.
    See also:
    SSL_CTX_use_certificate() and SSL_use_certificate_ASN1().

    int SSL_CTX_use_certificate_file (  SSL_CTX *    ctx,
    char *    file,
    int    type
    )  ;
     

    Binds a certificate stored in a specified file, or hardware module, to an SSL_CTX. A certificate must be bound to either the SSL_CTX or SSL before any certificate operations can be performed.

    Parameters:
    ctx [In, Out] The SSL_CTX to which to bind the certificate.
    file [In] A reference to the file, or hardware module, where the certificate is stored. For hardware, the format of this parameter is:
    "[device_name=string:][slot_id=integer:] cert_id=string".
    type [In] The type of certificate being loaded.
    See Certificate Filetype Identifiers for valid values.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    If the file or hardware module contains multiple certificates, only the first certificate is loaded. Also, if using the file parameter to load a certificate from hardware, ensure there is no ambiguity as to where the certificate is located. This certificate becomes the default certificate for all future SSL connections.

    int SSL_get_client_CA_list_count (  SSL *    ssl )  ;
     

    Returns the number of acceptable Certification Authorities (CAs) for the SSL ssl. Certificates signed by these CAs are accepted by the server side of the SSL protocol.

    Parameters:
    ssl [In] The SSL reference where the CA list is stored.
    Returns:
    The number of CAs:
  • >0 indicates the number of acceptable CAs.
  • 0 indicates there is no client CA list for the SSL.
    • See also:
    SSL_add_client_CA() and SSL_get_client_CA_list_item().

    SSLCERT_NAME* SSL_get_client_CA_list_item (  SSL *    ssl,
    int    n
    )  ;
     

    Returns the names of the Certification Authorities (CAs) that the server side of the SSL protocol deems acceptable for verification of a client certificate.

    Parameters:
    ssl [In] The SSL reference where the CA list is stored.
    n [In] The index of the certificate in the CA list.
    Returns:
    The subject name of the certificate accessible via an SSLCERT reference.
    NULL indicates there is no client CA list or that n is out of range (that is, n < 0 or n >= max items in the list).
    See also:
    SSL_get_client_CA_list_count().

    int SSL_use_certificate (  SSL *    ssl,
    SSLCERT *    x509
    )  ;
     

    Binds a certificate x509 to the SSL connection ssl. A certificate loaded via this function is used to identify the owner of the SSL connection and must be loaded before the SSL connection can successfully respond to a certificate request.

    Parameters:
    ssl [In] The SSL connection reference against which to set the certificate.
    x509 [In] The SSLCERT reference.
    Returns:
    1 indicates success.
    <= 0 indicates error.
    See also:
    SSL_CTX_use_certificate().

    int SSL_use_certificate_ASN1 (  SSL *    ssl,
    unsigned char *    data,
    long    len
    )  ;
     

    Binds a certificate data (in ASN.1 format) to the SSL connection ssl. A certificate must be loaded before any additional certificate operations can be performed.

    Parameters:
    ssl [In, Out] The SSL connection reference against which to set a certificate.
    data [In] A buffer containing the certificate in ASN.1 format.
    len [In] The length of certificate buffer data.
    Returns:
    1 indicates success.
    <= 0 indicates error.
    See also:
    SSL_use_certificate() and SSL_CTX_use_certificate_ASN1().

    int SSL_use_certificate_file (  SSL *    ssl,
    char *    file,
    int    type
    )  ;
     

    Binds a certificate stored in a specified file to an SSL. A certificate must be bound to either the SSL or SSL_CTX before any certificate operations can be performed.

    Parameters:
    ssl [In, Out] The SSL to which to bind the certificate.
    file [In] A NULL terminated reference to the file where the certificate is stored.
    type [In] The type of certificate being loaded.
    See Certificate Filetype Identifiers for valid values.
    Returns:
    1 indicates success.
    0 indicates error.
    note.gif
    Only the first certificate is loaded if the file contains multiple certificates. This certificate becomes the default certificate for all future SSL connections.

    void SSLCERT_free (  SSLCERT *    cert )  ;
     

    Removes all allocated memory for the certificate cert.

    Parameters:
    cert [In] A reference to the SSLCERT certificate to free.
    note.gif
    Certificate structures have reference counts. Actual memory is freed only after all references are freed.
    See also:
    SSLCERT_reference_inc().
    Samples:
    bio_server.c, cache_server.c, nbio_server.c, PKCS11Client.c, s_crl_check.c, s_crl_verify.c, s_frombuf.c, sock_server.c, and ssl_server.c.

    SSLCERT* SSLCERT_from_binary (  SSLCERT **    pcert,
    unsigned char **    pp,
    long    length
    )  ;
     

    Creates an SSLCERT structure from the specified binary data in ASN.1 format indicated by pp with a length specified by length. SSLCERT is allocated if pcert is NULL.

    Parameters:
    pcert [Out] The SSLCERT reference pointer.
    pp [In] The binary data reference.
    length [In] The length of the data.
    note.gif
    On return, pp points to the end of the binary certificate.
    See also:
    SSLCERT_to_binary().
    Samples:
    s_crl_check.c, and s_crl_verify.c.

    void* SSLCERT_from_binary_bio (  void *    bp,
    SSLCERT *    cert
    )  ;
     

    Converts a binary certificate read from a BIO into an SSLCERT structure.

    Parameters:
    bp [In] A pointer to a BIO containing the binary certificate.
    cert [Out] The SSLCERT structure to propagate.
    If NULL, one will be created.
    Returns:
    A pointer to the created SSLCERT structure.
    NULL indicates error.

    SSLCERT* SSLCERT_new (  void    )  ;
     

    Creates a new SSLCERT structure or certificate.

    Returns:
    The SSLCERT reference.

    void* SSLCERT_PEM_read_bio_SSLCERT (  void *    bp,
    SSLCERT **    cert,
    PEM_PASSWORD_CB_T *    cb
    )  ;
     

    Converts a Privacy Enhanced Mail (PEM) encoded certificate read from a BIO into an SSLCERT structure.

    Parameters:
    bp [In] A reference to the BIO containing the PEM-encoded certificate.
    cert [Out] A pointer to the SSLCERT reference where the certificate will be loaded (optional).
    cb [In] The password callback function.
    If the data is encrypted and the callback is NULL, the default internal callback will prompt the user for a password.
    cb can be used to override this behavior and supply a password via other means.
    Returns:
    The SSLCERT reference to the certificate.
    NULL indicates error.
    note.gif
    If cert refers to an existing SSLCERT structure, the certificate is placed in the structure. In other cases, memory is allocated.
    Any memory allocated for the SSLCERT structure must be explicitly freed.
    See also:
    SSLCERT_free().
    Samples:
    PKCS11Client.c, and s_frombuf.c.

    void SSLCERT_reference_inc (  SSLCERT *    cert )  ;
     

    Increments the reference count for the specified certificate structure cert. This prevents the structure being freed if more than one application refers to the structure.

    Parameters:
    cert [In] A pointer to the SSLCERT structure whose reference count is to be incremented.
    note.gif
    The reference count is decremented by SSLCERT_free() so the actual memory allocation for the SSLCERT structure will remain until the last reference is removed.
    See also:
    SSLCERT_free().

    int SSLCERT_to_binary (  SSLCERT *    cert,
    unsigned char **    pp
    )  ;
     

    Creates ASN.1 binary certificate data from the specified SSLCERT structure. The data is placed in pp which is subsequently updated to point to the end of the certificate data.

    Parameters:
    cert [In] The SSLCERT reference pointer.
    pp [Out] The address of the data buffer reference.
    Returns:
    >0 indicates the length of the certificate data.
    0 indicates the certificate is NULL.
    note.gif
    The buffer must be large enough to hold the data. If the buffer is not allocated, the function only returns the length of the certificate data.
    See also:
    SSLCERT_from_binary().
    Example:

    SSLCERT *cert;
unsigned char *pp;
unsigned char *buf;
int ret;

/* cert = SSLCERT_new(...) */

/* Load cert structure with data */

/* Find the length of the certificate */
ret = SSLCERT_to_binary(cert,NULL);

/* Allocate the buffer to hold the data */
buf = (unsigned char *)malloc((size_t)ret);
if (buf == NULL)
{
    /* Malloc error - give up now */
    exit(0);
}

/* Convert the certificate structure to ASN.1 format */
pp = buf;
ret = SSLCERT_to_binary(cert,&pp);

if ((pp-buf) != ret)
{
    /* An error has occurred*/
}

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