RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Operation Functions

This section outlines the functions that manage certificate store objects. These objects can be used to interact with the certificate store.

Typedefs

typedef int(* R_CERT_STORE_CB_T )(void *, void *)
 The type of callback function that iterates over objects in the store. More...


Functions

int R_CERT_STORE_new (R_CERT_STORE_CTX *ctx, R_CERT_STORE **obj)
 Creates a new store object obj. More...

int R_CERT_STORE_free (R_CERT_STORE *obj)
 Deallocates the store object obj and clears any state associated with the object. More...

int R_CERT_STORE_get_info (R_CERT_STORE *obj, R_CERT_STORE_INFO info_id, void *value)
 Returns information from the certificate store object. More...

int R_CERT_STORE_set_info (R_CERT_STORE *obj, R_CERT_STORE_INFO info_id, void *value)
 Sets information into the certificate store object for the specified information identifier. More...

int R_CERT_STORE_init (R_CERT_STORE *obj)
 Initializes the state of the certificate store object. More...

int R_CERT_STORE_update (R_CERT_STORE *obj)
 Updates the certificate store content using the certificate in the certificate store object obj. More...

int R_CERT_STORE_add (R_CERT_STORE *obj)
 Adds the certificate associated with the certificate store object obj into the certificate store context. More...

int R_CERT_STORE_delete (R_CERT_STORE *obj)
 Deletes the certificate entry in the certificate store object obj from the certificate store. More...

int R_CERT_STORE_find (R_CERT_STORE *obj)
 Calls a custom search callback, specified by the application, to retrieve a certificate from the store. More...

int R_CERT_STORE_next (R_CERT_STORE *obj)
 Retrieves the certificate details of the certificate at the next index in the store. More...

int R_CERT_STORE_find_entry_by_subject (R_CERT_STORE *obj, R_CERT_NAME *subject, R_CERT_STORE_CERT_TYPE cert_class)
 Loads the certificate store object obj with the details of the first certificate store entry found with subject name subject and certificate class cert_class. More...

int R_CERT_STORE_find_entry_by_issuer (R_CERT_STORE *obj, R_CERT_NAME *issuer, R_CERT_STORE_CERT_TYPE cert_class)
 Loads the certificate store object obj with the details of the first certificate store entry found with issuer name issuer and certificate class cert_class. More...

int R_CERT_STORE_find_entry_by_pubkey (R_CERT_STORE *obj, R_PKEY *pubkey, R_CERT_STORE_CERT_TYPE cert_class)
 Loads the certificate store object obj with the details of the first certificate store entry found with public key pubkey and certificate class cert_class. More...

int R_CERT_STORE_find_entry_by_fingerprint (R_CERT_STORE *obj, R_ITEM *fprint, R_CERT_STORE_CERT_TYPE cert_class)
 Loads the certificate store object obj with the details of the first certificate store entry found with fingerprint fprint and certificate class cert_class. More...

int R_CERT_STORE_find_entry_by_issuer_and_serial (R_CERT_STORE *obj, R_CERT_NAME *issuer, R_ITEM *serial, int cert_class)
 Loads the certificate store object obj with the details of the first certificate store entry found with issuer name issuer, serial number serial and certificate class cert_class. More...

int R_CERT_STORE_set_cert_data (R_CERT_STORE *obj, R_CERT_STORE_CERT_DATA *data)
 Sets certificate information from the R_CERT_STORE_CERT_DATA structure data into the certificate store object obj. More...

int R_CERT_STORE_get_cert_data (R_CERT_STORE *obj, R_CERT_STORE_CERT_DATA *data)
 Retrieves certificate information into the R_CERT_STORE_CERT_DATA structure data from the certificate store object obj. More...

int R_CERT_STORE_set_cert (R_CERT_STORE *obj, R_CERT *cert, R_ITEM *id)
 Sets the certificate cert and user-defined identifier id into the certificate store object obj. More...

int R_CERT_STORE_get_cert (R_CERT_STORE *obj, R_CERT **cert, R_ITEM **id)
 Retrieves the certificate cert and user-defined identifier id from the certificate store object obj. More...

int R_CERT_STORE_set_cert_state (R_CERT_STORE *obj, R_CERT_STORE_STATE state)
 Sets the state of the certificate, which includes the trust level, into the certificate store object obj. More...

int R_CERT_STORE_get_cert_state (R_CERT_STORE *obj, R_CERT_STORE_STATE *state)
 Retrieves the state of the certificate, which includes the trust level, from the certificate store object obj. More...

int R_CERT_STORE_set_cert_class (R_CERT_STORE *obj, R_CERT_STORE_CERT_TYPE cert_class)
 Sets the class of the certificate into the certificate store object obj. More...

int R_CERT_STORE_get_cert_class (R_CERT_STORE *obj, R_CERT_STORE_CERT_TYPE *cert_class)
 Retrieves the class of the certificate cert_class from the certificate store object obj. More...

int R_CERT_STORE_set_compare_func (R_CERT_STORE *obj, R_CERT_STORE_CB_T *func)
 Sets the function to use for matching when searching through the certificates in the certificate store. More...

Typedef Documentation

typedef int(* R_CERT_STORE_CB_T)(void *, void *)
 

The type of callback function that iterates over objects in the store. This function is also used as a checking function when stepping through the store.

Returns:
0 indicates success.
1 indicates error.

Function Documentation

int R_CERT_STORE_add (  R_CERT_STORE *    obj )  ;
 

Adds the certificate associated with the certificate store object obj into the certificate store context. If a matching certificate is found in the store, this function updates the entry instead of adding a new certificate store entry.
R_CERT_STORE_INFO_USER_ID is used to determine whether an entry is unique so that the same certificate may be added into the store multiple times via different user identifiers. In the case where the user identifier is NULL, the certificate itself is used to test uniqueness.

Parameters:
obj [In] The store object to add.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
note.gif
R_CERT_STORE_update() has the same underlying implementation as this function.
Call R_CERT_STORE_CTX_lock() prior to this function and R_CERT_STORE_CTX_unlock() after this function to ensure the certificate object is freed when adding in a threaded environment.
See also:
R_CERT_STORE_update(), R_CERT_STORE_delete(), R_CERT_STORE_CTX_lock() and R_CERT_STORE_CTX_unlock().
Example:

/* $Id: R_CERT_STORE_add.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
char *certfile                   /* The certificate filename */
R_CERT_CTX *cert_ctx;            /* The certificate context */
R_CERT *cert = NULL;             /* The certificate */
R_CERT_STORE *store_obj = NULL;  /* The certificate store object */
...
/* Read the certificate from a file */
if ((ret = R_CERT_read_file(cert_ctx, certfile, R_CERT_TYPE_X509,
    R_FORMAT_PEM, &cert)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Certificate from file failure\n");
    goto end;
}

/* Create a new store object in order to load items into the certificate
 * store
 */
if ((ret = R_CERT_STORE_new(store_ctx, &store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Set the certificate into the store object */
if ((ret = R_CERT_STORE_set_cert(store_obj, cert, NULL)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate failure\n");
    goto end;
}

/* As the certificate store object now owns the certificate, the application
 * is not required to free it
 */
cert = NULL;

/* Set the certificate class into the store object */
if ((ret = R_CERT_STORE_set_cert_class(store_obj,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Set the certificate state into the store object */
if ((ret = R_CERT_STORE_set_cert_state(store_obj,
    R_CERT_STORE_STATE_TRUSTED_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Add the contents of the store object into the certificate store */
if ((ret = R_CERT_STORE_add(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Add store object failure\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
cm_open_strm_cb.c, store.c, vfy_adv.c, vfy_bc.c, and vfy_smpl.c.

int R_CERT_STORE_delete (  R_CERT_STORE *    obj )  ;
 

Deletes the certificate entry in the certificate store object obj from the certificate store. The user identifer, set into obj via R_CERT_STORE_set_info() is used to determine which entry is removed. In the case where the user identifer is NULL, the certificate is used to find the correct entry in the store (the R_CERT_STORE_CTX).

Parameters:
obj [In] The store object to delete.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
note.gif
Call R_CERT_STORE_CTX_lock() prior to this function and R_CERT_STORE_CTX_unlock() after this function to ensure the deleted certificate object is not accessed when in a threaded environment.
See also:
R_CERT_STORE_add(), R_CERT_STORE_update(), R_CERT_STORE_CTX_lock() and R_CERT_STORE_CTX_unlock().
Samples:
store.c.

int R_CERT_STORE_find (  R_CERT_STORE *    obj )  ;
 

Calls a custom search callback, specified by the application, to retrieve a certificate from the store. The details of the matching certificate (if available) are loaded into the R_CERT_STORE object obj. This function returns no error if the object matches its conditions.

Parameters:
obj [In] The store object.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_compare_func().

int R_CERT_STORE_find_entry_by_fingerprint (  R_CERT_STORE *    obj,
R_ITEM *    fprint,
R_CERT_STORE_CERT_TYPE    cert_class
)  ;
 

Loads the certificate store object obj with the details of the first certificate store entry found with fingerprint fprint and certificate class cert_class.

Parameters:
obj [In] The certificate store object with which to find the certificate.
fprint [In] The fingerprint of the certificate to find.
cert_class [In] The class name of the certificate to find.
See Class Defines for valid values.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_find_entry_by_issuer(), R_CERT_STORE_find_entry_by_issuer_and_serial(), R_CERT_STORE_find_entry_by_subject() and R_CERT_STORE_find_entry_by_pubkey().

int R_CERT_STORE_find_entry_by_issuer (  R_CERT_STORE *    obj,
R_CERT_NAME *    issuer,
R_CERT_STORE_CERT_TYPE    cert_class
)  ;
 

Loads the certificate store object obj with the details of the first certificate store entry found with issuer name issuer and certificate class cert_class.

Parameters:
obj [In] The certificate store object with which to find the certificate.
issuer [In] The issuer name of the certificate to find.
cert_class [In] The class name of the certificate to find.
See Class Defines for valid values.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_find_entry_by_fingerprint(), R_CERT_STORE_find_entry_by_issuer_and_serial(), R_CERT_STORE_find_entry_by_subject() and R_CERT_STORE_find_entry_by_pubkey().
Samples:
store.c.

int R_CERT_STORE_find_entry_by_issuer_and_serial (  R_CERT_STORE *    obj,
R_CERT_NAME *    issuer,
R_ITEM *    serial,
int    cert_class
)  ;
 

Loads the certificate store object obj with the details of the first certificate store entry found with issuer name issuer, serial number serial and certificate class cert_class.

Parameters:
obj [In] The certificate store object with which to find the certificate.
issuer [In] The issuer name of the certificate to find.
serial [In] The serial number of the certificate to find.
cert_class [In] The class name of the certificate to find.
See Class Defines for valid values.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_find_entry_by_fingerprint(), R_CERT_STORE_find_entry_by_issuer(), R_CERT_STORE_find_entry_by_subject() and R_CERT_STORE_find_entry_by_pubkey().
Samples:
cm_open_strm_cb.c, and cm_vfy_strm_cb.c.

int R_CERT_STORE_find_entry_by_pubkey (  R_CERT_STORE *    obj,
R_PKEY *    pubkey,
R_CERT_STORE_CERT_TYPE    cert_class
)  ;
 

Loads the certificate store object obj with the details of the first certificate store entry found with public key pubkey and certificate class cert_class.

Parameters:
obj [In] The certificate store object with which to find the certificate.
pubkey [In] The public key of the certificate to find.
cert_class [In] The class name of the certificate to find.
See Class Defines for valid values.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_find_entry_by_fingerprint(), R_CERT_STORE_find_entry_by_issuer_and_serial(), R_CERT_STORE_find_entry_by_subject() and R_CERT_STORE_find_entry_by_issuer().
Samples:
store.c.

int R_CERT_STORE_find_entry_by_subject (  R_CERT_STORE *    obj,
R_CERT_NAME *    subject,
R_CERT_STORE_CERT_TYPE    cert_class
)  ;
 

Loads the certificate store object obj with the details of the first certificate store entry found with subject name subject and certificate class cert_class.

Parameters:
obj [In] The certificate store object with which to find the certificate.
subject [In] The subject name of the certificate to find.
cert_class [In] The class name of the certificate to find.
See Class Defines for valid values.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_find_entry_by_fingerprint(), R_CERT_STORE_find_entry_by_issuer_and_serial(), R_CERT_STORE_find_entry_by_issuer() and R_CERT_STORE_find_entry_by_pubkey().
Example:

/* $Id: R_CERT_STORE_CTX_lock.c,v 1.3 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
R_CERT_STORE_CTX *store_ctx;     /* The certificate store context */
R_CERT_STORE *store_obj;         /* The certificate store object */
R_CERT_NAME *subject_name;       /* The subject name of a certificate in
                                  * the store
                                  */
R_PKEY *private_key;             /* The private key of a certificate already
                                  * loaded into the store
                                  */
...
/* Find a certificate in the store using subject name as the search
 * criteria and copy this entry into the store object
 */
if ((ret = R_CERT_STORE_find_entry_by_subject(store_obj, subject_name,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to find certificate in store\n");
    goto end;
}

/* Add the private key of the certificate to the existing contents of the
 * store object
 */
if ((ret = R_CERT_STORE_set_info(store_obj, R_CERT_STORE_INFO_PRIV_KEY,
    private_key)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to set private key into store object\n");
    goto end;
}

/* As the certificate store object now owns the private key, the application
 * is not required to free it
 */
private_key = NULL;

/*
 * Multithreading Case:
 *
 * Lock the certificate store before updating the details for this entry.
 * Note that locking callbacks must have been registered with the library
 * prior to calling R_CERT_STORE_CTX_lock() and R_CERT_STORE_CTX_unlock().
 *
 * Refer to the threading sample for instructions on registering locking
 * callbacks.
 */
R_CERT_STORE_CTX_lock(store_ctx, R_CERT_STORE_CTX_LOCK_WRITE);

/* Update the certificate store entry with the private key */
ret = R_CERT_STORE_update(store_obj);

R_CERT_STORE_CTX_unlock(store_ctx, R_CERT_STORE_CTX_LOCK_WRITE);

if (ret != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to update certificate store entry\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
store.c.

int R_CERT_STORE_free (  R_CERT_STORE *    obj )  ;
 

Deallocates the store object obj and clears any state associated with the object. As no operations can be performed on a store object once it has been deallocated, this function should be the last operation performed on an object.

Parameters:
obj [In] A pointer to the store object to free.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_new().
Samples:
cm_open_strm_cb.c, cm_vfy_strm_cb.c, store.c, vfy_adv.c, vfy_bc.c, and vfy_smpl.c.

int R_CERT_STORE_get_cert (  R_CERT_STORE *    obj,
R_CERT **    cert,
R_ITEM **    id
)  ;
 

Retrieves the certificate cert and user-defined identifier id from the certificate store object obj. The certificate cert returned by this function must be explicitly freed with R_CERT_free().

Parameters:
obj [In] The certificate store object from which to retrieve the certificate and identifier.
cert [Out] The retrieved certificate
id [Out] The retrieved user-defined identifier.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_cert() and R_CERT_STORE_get_info().
Example:

/* $Id: R_CERT_verify.c,v 1.7 2003/06/16 06:31:20 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;     /* The return value */
BIO *bio_out;               /* The output channel for error messages */
R_CERT_CTX *cert_ctx;       /* The certificate context */
R_CERT_STORE *store_obj;    /* The certificate store object */
R_CERT *cert = NULL;        /* The certificate */
R_CERT_NAME *issuer = NULL; /* The name of the certificate issuer */
R_CERT *ca_cert = NULL;     /* The certificate from the CA that signed the
                             * certificate being verified
                             */
R_PKEY *ca_key = NULL;      /* The public key of the CA certificate */
char *certfile;             /* The file where the certificate is stored */
int verified;               /* The result of the certificate
                             * verification
                             */
...
/* Read the certificate from a file */
if ((ret = R_CERT_read_file(cert_ctx, certfile, R_CERT_TYPE_X509,
    R_FORMAT_BINARY, &cert)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Certificate read failure\n");
    goto end;
}

/* Retrieve the issuer name from the certificate */
if ((ret = R_CERT_issuer_name_to_R_CERT_NAME(cert, R_FLAG_SHARE_DATA,
    &issuer)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Unable to retrieve certificate issuer name\n");
    goto end;
}

/* Using the issuer name retrieve the CA details from the certificate store */
if ((ret = R_CERT_STORE_find_entry_by_subject(store_obj, issuer,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Unable to find CA certificate in store\n");
    goto end;
}

/* Retrieve the CA certificate from the store object */
if ((ret = R_CERT_STORE_get_cert(store_obj, &ca_cert, NULL)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Unable to retrieve certificate from store object\n");
    goto end;
}

/* Retrieve the public key from the CA certificate */
if ((ret = R_CERT_public_key_to_R_PKEY(ca_cert, R_FLAG_SHARE_DATA,
    &ca_key)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to retrieve public key from certificate\n");
    goto end;
}

/* Verify the certificate signature using the public key */
if ((ret = R_CERT_verify(cert, ca_key, &verified)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to verify certificate signature\n");
    goto end;
}

if (!verified)
{
    BIO_printf(bio_out, "Failed to verify certificate signature\n");
    ret = R_ERROR_FAILED;
}
else
{
    BIO_printf(bio_out, "Certificate verification successful\n");
}

...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}

int R_CERT_STORE_get_cert_class (  R_CERT_STORE *    obj,
R_CERT_STORE_CERT_TYPE *    cert_class
)  ;
 

Retrieves the class of the certificate cert_class from the certificate store object obj.

Parameters:
obj [In] The certificate store object from which to retrieve the certificate class. See Class Defines for valid values.
cert_class [Out] The retrieved class of the certificate.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_cert_class() and R_CERT_STORE_get_info().
Example:

/* $Id: R_CERT_STORE_get_cert_class.c,v 1.4 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;        /* The return value */
BIO *bio_out;                  /* The output channel for error messages */
R_CERT_STORE *store_obj;       /* The certificate store object */
R_CERT_STORE_CERT_TYPE class;  /* The classification of the type of certificate
                                * being added to the store
                                */
...
/* Set the class to be a Certification Authority's (CA) certificate */
class = R_CERT_STORE_CA_CERTIFICATE;

/* Set the class of the certificate to be a manufacturer's certificate */
if ((ret = R_CERT_STORE_set_cert_class(store_obj, class)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set class failure\n");
    goto end;
}

/* Retrieve the class of the certificate from the store object and check
 * that it has been set correctly
 */
if ((ret = R_CERT_STORE_get_cert_class(store_obj, &class)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Get class failure\n");
    goto end;
}

if (class != R_CERT_STORE_CA_CERTIFICATE)
{
    BIO_printf(bio_out, "Failed to set certificate class\n");
    ret = R_ERROR_FAILED;
    goto end;
}

...
end:
if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}

int R_CERT_STORE_get_cert_data (  R_CERT_STORE *    obj,
R_CERT_STORE_CERT_DATA *    data
)  ;
 

Retrieves certificate information into the R_CERT_STORE_CERT_DATA structure data from the certificate store object obj. Any certificate returned by this function via data must be explicitly freed with R_CERT_free().

Parameters:
obj [In] The certificate store object from which to retrieve the certificate data.
data [Out] The retrieved certificate information.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_cert_data() and R_CERT_STORE_get_info().
Samples:
cm_open_strm_cb.c.

int R_CERT_STORE_get_cert_state (  R_CERT_STORE *    obj,
R_CERT_STORE_STATE *    state
)  ;
 

Retrieves the state of the certificate, which includes the trust level, from the certificate store object obj.

Parameters:
obj [In] The certificate store object from which to retrieve the certificate state.
See States for valid values.
state [Out] The retrieved state.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_cert_state() and R_CERT_STORE_get_info().
Samples:
store.c.

int R_CERT_STORE_get_info (  R_CERT_STORE *    obj,
R_CERT_STORE_INFO    info_id,
void *    value
)  ;
 

Returns information from the certificate store object.

Parameters:
obj [In] The certificate store object.
info_id [In] The information identifier.
See Information Identifiers for valid values and the data type of value.
value [Out] The retrieved data for the information identifier.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_info().
Example:

/* $Id: R_CERT_STORE_next.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;  /* The return value */
BIO *bio_out;            /* The output channel for error messages */
R_CERT_STORE *store_obj; /* The certificate store object */
R_ITEM f_item;           /* The item where the current store entry's
                          * user identifier will be loaded
                          */

R_ITEM m_item = { 23, "RSA Test Certificate 1" };
                         /* The user identifier of the certificate
                          * The store entry to find
                          */
...
/* Reset the store object to its initial state. This resets the index of
 * the object so that R_CERT_STORE_next() will retrieve the first
 * entry in the store.
 */
if ((ret = R_CERT_STORE_init(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Search for a certificate with a particular user identifier */

/* Retrieve the next entry (by index order) from the store */
while ((ret = R_CERT_STORE_next(store_obj)) != R_ERROR_NONE)
{
    /* Retrieve the user identifier from the store object */
    if ((ret = R_CERT_STORE_get_info(store_obj, R_CERT_STORE_INFO_USER_ID,
        &f_item)) != R_ERROR_NONE)
    {
        BIO_printf(bio_out, "Store object get info failure\n");
        goto end;
    }

    if ((f_item.data != NULL) && (f_item.len != 0))
    {
        if ((f_item.len - m_item.len) == 0)
        {
            if (Memcmp(f_item.data, m_item.data, m_item.len) == 0)
            {
                /* A matching certificate store entry has been found */
                break;
            }
        }
    }
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}

int R_CERT_STORE_init (  R_CERT_STORE *    obj )  ;
 

Initializes the state of the certificate store object. If iterating through all certificates in the store, use this function to reset to the start.

Parameters:
obj [In] The certificate store object.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_new(), R_CERT_STORE_free() and R_CERT_STORE_next().
Example:

/* $Id: R_CERT_STORE_next.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;  /* The return value */
BIO *bio_out;            /* The output channel for error messages */
R_CERT_STORE *store_obj; /* The certificate store object */
R_ITEM f_item;           /* The item where the current store entry's
                          * user identifier will be loaded
                          */

R_ITEM m_item = { 23, "RSA Test Certificate 1" };
                         /* The user identifier of the certificate
                          * The store entry to find
                          */
...
/* Reset the store object to its initial state. This resets the index of
 * the object so that R_CERT_STORE_next() will retrieve the first
 * entry in the store.
 */
if ((ret = R_CERT_STORE_init(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Search for a certificate with a particular user identifier */

/* Retrieve the next entry (by index order) from the store */
while ((ret = R_CERT_STORE_next(store_obj)) != R_ERROR_NONE)
{
    /* Retrieve the user identifier from the store object */
    if ((ret = R_CERT_STORE_get_info(store_obj, R_CERT_STORE_INFO_USER_ID,
        &f_item)) != R_ERROR_NONE)
    {
        BIO_printf(bio_out, "Store object get info failure\n");
        goto end;
    }

    if ((f_item.data != NULL) && (f_item.len != 0))
    {
        if ((f_item.len - m_item.len) == 0)
        {
            if (Memcmp(f_item.data, m_item.data, m_item.len) == 0)
            {
                /* A matching certificate store entry has been found */
                break;
            }
        }
    }
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
cm_open_strm_cb.c, store.c, and vfy_bc.c.

int R_CERT_STORE_new (  R_CERT_STORE_CTX *    ctx,
R_CERT_STORE **    obj
)  ;
 

Creates a new store object obj. The object is used to perform operations on the store such as adding certificates, finding certificates and retrieving information from certificates.

Parameters:
ctx [In] The certificate store context from which to create a store object.
obj [Out] A pointer to the generated certificate store object.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_free().
Example:

/* $Id: R_CERT_STORE_add.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
char *certfile                   /* The certificate filename */
R_CERT_CTX *cert_ctx;            /* The certificate context */
R_CERT *cert = NULL;             /* The certificate */
R_CERT_STORE *store_obj = NULL;  /* The certificate store object */
...
/* Read the certificate from a file */
if ((ret = R_CERT_read_file(cert_ctx, certfile, R_CERT_TYPE_X509,
    R_FORMAT_PEM, &cert)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Certificate from file failure\n");
    goto end;
}

/* Create a new store object in order to load items into the certificate
 * store
 */
if ((ret = R_CERT_STORE_new(store_ctx, &store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Set the certificate into the store object */
if ((ret = R_CERT_STORE_set_cert(store_obj, cert, NULL)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate failure\n");
    goto end;
}

/* As the certificate store object now owns the certificate, the application
 * is not required to free it
 */
cert = NULL;

/* Set the certificate class into the store object */
if ((ret = R_CERT_STORE_set_cert_class(store_obj,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Set the certificate state into the store object */
if ((ret = R_CERT_STORE_set_cert_state(store_obj,
    R_CERT_STORE_STATE_TRUSTED_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Add the contents of the store object into the certificate store */
if ((ret = R_CERT_STORE_add(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Add store object failure\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
cm_open_strm_cb.c, cm_vfy_strm_cb.c, store.c, vfy_adv.c, vfy_bc.c, and vfy_smpl.c.

int R_CERT_STORE_next (  R_CERT_STORE *    obj )  ;
 

Retrieves the certificate details of the certificate at the next index in the store. The index of the current certificate in obj is used to determine which is the next certificate store entry. If there are no certificate details loaded into obj the first certificate entry in the store is returned. The certificate itself can be retrieved from obj via R_CERT_STORE_get_cert().

Parameters:
obj [In] The store object.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_set_compare_func() and R_CERT_STORE_get_cert().
Example:

/* $Id: R_CERT_STORE_next.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;  /* The return value */
BIO *bio_out;            /* The output channel for error messages */
R_CERT_STORE *store_obj; /* The certificate store object */
R_ITEM f_item;           /* The item where the current store entry's
                          * user identifier will be loaded
                          */

R_ITEM m_item = { 23, "RSA Test Certificate 1" };
                         /* The user identifier of the certificate
                          * The store entry to find
                          */
...
/* Reset the store object to its initial state. This resets the index of
 * the object so that R_CERT_STORE_next() will retrieve the first
 * entry in the store.
 */
if ((ret = R_CERT_STORE_init(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Search for a certificate with a particular user identifier */

/* Retrieve the next entry (by index order) from the store */
while ((ret = R_CERT_STORE_next(store_obj)) != R_ERROR_NONE)
{
    /* Retrieve the user identifier from the store object */
    if ((ret = R_CERT_STORE_get_info(store_obj, R_CERT_STORE_INFO_USER_ID,
        &f_item)) != R_ERROR_NONE)
    {
        BIO_printf(bio_out, "Store object get info failure\n");
        goto end;
    }

    if ((f_item.data != NULL) && (f_item.len != 0))
    {
        if ((f_item.len - m_item.len) == 0)
        {
            if (Memcmp(f_item.data, m_item.data, m_item.len) == 0)
            {
                /* A matching certificate store entry has been found */
                break;
            }
        }
    }
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}

int R_CERT_STORE_set_cert (  R_CERT_STORE *    obj,
R_CERT *    cert,
R_ITEM *    id
)  ;
 

Sets the certificate cert and user-defined identifier id into the certificate store object obj. Frees any certificate currently referenced by obj. As the object assumes ownership of the new certificate, the calling application should not explicitly free it.

Parameters:
obj [In] The certificate store object against which to set the certificate and identifier.
cert [In] The supplied certificate.
id [In] The supplied identifier.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
note.gif
If a reference to the certificate is required by the application it can be acquired by calling R_CERT_inc_reference() (the application will also need to free the certificate in this case).
See also:
R_CERT_STORE_get_cert() and R_CERT_STORE_set_info().
Example:

/* $Id: R_CERT_STORE_add.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
char *certfile                   /* The certificate filename */
R_CERT_CTX *cert_ctx;            /* The certificate context */
R_CERT *cert = NULL;             /* The certificate */
R_CERT_STORE *store_obj = NULL;  /* The certificate store object */
...
/* Read the certificate from a file */
if ((ret = R_CERT_read_file(cert_ctx, certfile, R_CERT_TYPE_X509,
    R_FORMAT_PEM, &cert)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Certificate from file failure\n");
    goto end;
}

/* Create a new store object in order to load items into the certificate
 * store
 */
if ((ret = R_CERT_STORE_new(store_ctx, &store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Set the certificate into the store object */
if ((ret = R_CERT_STORE_set_cert(store_obj, cert, NULL)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate failure\n");
    goto end;
}

/* As the certificate store object now owns the certificate, the application
 * is not required to free it
 */
cert = NULL;

/* Set the certificate class into the store object */
if ((ret = R_CERT_STORE_set_cert_class(store_obj,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Set the certificate state into the store object */
if ((ret = R_CERT_STORE_set_cert_state(store_obj,
    R_CERT_STORE_STATE_TRUSTED_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Add the contents of the store object into the certificate store */
if ((ret = R_CERT_STORE_add(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Add store object failure\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
store.c, vfy_adv.c, vfy_bc.c, and vfy_smpl.c.

int R_CERT_STORE_set_cert_class (  R_CERT_STORE *    obj,
R_CERT_STORE_CERT_TYPE    cert_class
)  ;
 

Sets the class of the certificate into the certificate store object obj.

Parameters:
obj [In] The certificate store object of the certificate against which to set the certificate class.
See Class Defines for valid values.
cert_class [In] The supplied class.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_get_cert_class() and R_CERT_STORE_set_info().
Example:

/* $Id: R_CERT_STORE_get_cert_class.c,v 1.4 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;        /* The return value */
BIO *bio_out;                  /* The output channel for error messages */
R_CERT_STORE *store_obj;       /* The certificate store object */
R_CERT_STORE_CERT_TYPE class;  /* The classification of the type of certificate
                                * being added to the store
                                */
...
/* Set the class to be a Certification Authority's (CA) certificate */
class = R_CERT_STORE_CA_CERTIFICATE;

/* Set the class of the certificate to be a manufacturer's certificate */
if ((ret = R_CERT_STORE_set_cert_class(store_obj, class)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set class failure\n");
    goto end;
}

/* Retrieve the class of the certificate from the store object and check
 * that it has been set correctly
 */
if ((ret = R_CERT_STORE_get_cert_class(store_obj, &class)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Get class failure\n");
    goto end;
}

if (class != R_CERT_STORE_CA_CERTIFICATE)
{
    BIO_printf(bio_out, "Failed to set certificate class\n");
    ret = R_ERROR_FAILED;
    goto end;
}

...
end:
if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
store.c.

int R_CERT_STORE_set_cert_data (  R_CERT_STORE *    obj,
R_CERT_STORE_CERT_DATA *    data
)  ;
 

Sets certificate information from the R_CERT_STORE_CERT_DATA structure data into the certificate store object obj. This function will free any certificate, private key or Certificate Revocation List currently referenced by obj. The object assumes ownership of the new certificate, private key and CRL so the application should not free these objects explicitly.

If either (or both) the private key or CRL is not required they must be initialized to NULL before calling this function.

Parameters:
obj [In] The certificate store object against which to set the certificate information.
data [In] The supplied certificate information.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
note.gif
If the application requires it's own certificate, private key or CRL reference it can acquire one by calling R_CERT_inc_reference(), R_PKEY_dup() or R_CRL_dup() respectively (in this case the application will also be required to free the reference).
See also:
R_CERT_STORE_get_cert_data() and R_CERT_STORE_set_cert().
Example:

/* $Id: R_CERT_STORE_set_cert_data.c,v 1.3 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret=R_ERROR_NONE;     /* The return value */
BIO *bio_out;             /* The output channel for error messages */
R_CERT_STORE *store_obj;  /* The certificate store object */
R_CERT_STORE_CERT_DATA cert_data;
                          /* The certificate data to be set into the store
                           * object
                           */
R_CERT *cert;             /* The certificate that will be added into the
                           * certificate store
                           */
R_ITEM user_id = { 21, "RSA CA Certificate 1" };
                          /* The user defined identifier for the certificate
                           * (optional)
                           */
R_PKEY *privkey;          /* The private key of the certificate (optional) */
R_CRL *crl;               /* A list of leaf certificates that have been revoked
                           * by the certificate being loaded into the store
                           * (optional)
                           */
...
/* Initialize the certificate store object to reset any fields that may have
 * been set previously.
 */
if ((ret = R_CERT_STORE_init(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

cert_data.cert = cert;
/* If the user idenitifier is not required this field must be set to NULL */
cert_data.id   = &user_id;
cert_data.state = R_CERT_STORE_STATE_TRUSTED_CERTIFICATE;
cert_data.class = R_CERT_STORE_CA_CERTIFICATE;
/* If the private key is not required this field must be set to NULL */
cert_data.privkey = privkey;
/* If the crl is not required this field must be set to NULL */
cert_data.crt = crl;

/* Set the certificate data into the store object */
if ((ret = R_CERT_STORE_set_cert_data(store_obj, &cert_data)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate data failure\n");
    goto end;
}

/* The certificate store object now owns the certificate, the private key,
 * and the crl so the application is not required to free them
 */
cert = NULL;
privkey = NULL;
crl = NULL;

/* Add the contents of the store object into the certificate store */
if ((ret = R_CERT_STORE_add(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Add store object failure\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
cm_open_strm_cb.c.

int R_CERT_STORE_set_cert_state (  R_CERT_STORE *    obj,
R_CERT_STORE_STATE    state
)  ;
 

Sets the state of the certificate, which includes the trust level, into the certificate store object obj.

Parameters:
obj [In] The certificate store object against which to set the state.
See States for valid values.
state [In] The supplied state.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_get_cert_state() and R_CERT_STORE_set_info().
Example:

/* $Id: R_CERT_STORE_add.c,v 1.6 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
char *certfile                   /* The certificate filename */
R_CERT_CTX *cert_ctx;            /* The certificate context */
R_CERT *cert = NULL;             /* The certificate */
R_CERT_STORE *store_obj = NULL;  /* The certificate store object */
...
/* Read the certificate from a file */
if ((ret = R_CERT_read_file(cert_ctx, certfile, R_CERT_TYPE_X509,
    R_FORMAT_PEM, &cert)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Certificate from file failure\n");
    goto end;
}

/* Create a new store object in order to load items into the certificate
 * store
 */
if ((ret = R_CERT_STORE_new(store_ctx, &store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "New store object failure\n");
    goto end;
}

/* Set the certificate into the store object */
if ((ret = R_CERT_STORE_set_cert(store_obj, cert, NULL)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate failure\n");
    goto end;
}

/* As the certificate store object now owns the certificate, the application
 * is not required to free it
 */
cert = NULL;

/* Set the certificate class into the store object */
if ((ret = R_CERT_STORE_set_cert_class(store_obj,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Set the certificate state into the store object */
if ((ret = R_CERT_STORE_set_cert_state(store_obj,
    R_CERT_STORE_STATE_TRUSTED_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Set certificate class failure\n");
    goto end;
}

/* Add the contents of the store object into the certificate store */
if ((ret = R_CERT_STORE_add(store_obj)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Add store object failure\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
store.c, vfy_adv.c, vfy_bc.c, and vfy_smpl.c.

int R_CERT_STORE_set_compare_func (  R_CERT_STORE *    obj,
R_CERT_STORE_CB_T *    func
)  ;
 

Sets the function to use for matching when searching through the certificates in the certificate store.

Parameters:
obj [In] The certificate store object.
func [In] The function to call when searching.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_next().

int R_CERT_STORE_set_info (  R_CERT_STORE *    obj,
R_CERT_STORE_INFO    info_id,
void *    value
)  ;
 

Sets information into the certificate store object for the specified information identifier.

Parameters:
obj [In] The certificate store object.
info_id [In] The information identifier.
See Information Identifiers for valid values and the data type of value.
value [In] The data set against the object.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
See also:
R_CERT_STORE_get_info().
Example:

/* $Id: R_CERT_STORE_CTX_lock.c,v 1.3 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
R_CERT_STORE_CTX *store_ctx;     /* The certificate store context */
R_CERT_STORE *store_obj;         /* The certificate store object */
R_CERT_NAME *subject_name;       /* The subject name of a certificate in
                                  * the store
                                  */
R_PKEY *private_key;             /* The private key of a certificate already
                                  * loaded into the store
                                  */
...
/* Find a certificate in the store using subject name as the search
 * criteria and copy this entry into the store object
 */
if ((ret = R_CERT_STORE_find_entry_by_subject(store_obj, subject_name,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to find certificate in store\n");
    goto end;
}

/* Add the private key of the certificate to the existing contents of the
 * store object
 */
if ((ret = R_CERT_STORE_set_info(store_obj, R_CERT_STORE_INFO_PRIV_KEY,
    private_key)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to set private key into store object\n");
    goto end;
}

/* As the certificate store object now owns the private key, the application
 * is not required to free it
 */
private_key = NULL;

/*
 * Multithreading Case:
 *
 * Lock the certificate store before updating the details for this entry.
 * Note that locking callbacks must have been registered with the library
 * prior to calling R_CERT_STORE_CTX_lock() and R_CERT_STORE_CTX_unlock().
 *
 * Refer to the threading sample for instructions on registering locking
 * callbacks.
 */
R_CERT_STORE_CTX_lock(store_ctx, R_CERT_STORE_CTX_LOCK_WRITE);

/* Update the certificate store entry with the private key */
ret = R_CERT_STORE_update(store_obj);

R_CERT_STORE_CTX_unlock(store_ctx, R_CERT_STORE_CTX_LOCK_WRITE);

if (ret != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to update certificate store entry\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}

int R_CERT_STORE_update (  R_CERT_STORE *    obj )  ;
 

Updates the certificate store content using the certificate in the certificate store object obj. R_CERT_STORE_add() and R_CERT_STORE_update() have the same underlying implementation. If a matching certificate is not found in the store R_CERT_STORE_update() causes that entry to be added rather than return R_ERROR_NOT_FOUND. The R_CERT_STORE_INFO_USER_ID is used to determine whether an entry is unique. This means that the same certificate may be added into the store multiple times via different user ids. In the case where the user id is NULL, the certificate itself is used to test uniqueness.

Parameters:
obj [In] The store object with which to update the store context.
Returns:
R_ERROR_NONE indicates success.
See Identifiers for valid values.
note.gif
Call R_CERT_STORE_CTX_lock() prior to this function and R_CERT_STORE_CTX_unlock() after this function to ensure the certificate object data is not accidentally overwritten when in a threaded environment.
The certificate belongs to the context upon successful completion of this function and does not need to be freed by the caller.
See also:
R_CERT_STORE_add(), R_CERT_STORE_delete(), R_CERT_STORE_CTX_lock(), R_CERT_STORE_set_cert() and R_CERT_STORE_CTX_unlock().
Example:

/* $Id: R_CERT_STORE_CTX_lock.c,v 1.3 2003/06/17 05:26:06 jmckee Exp $ */
/*
 * Copyright (C) 1998-2003 RSA Security Inc. All rights reserved.
 *
 * This work contains proprietary information of RSA Security.
 * Distribution is limited to authorized licensees of RSA
 * Security. Any unauthorized reproduction, distribution or
 * modification of this work is strictly prohibited.
 */
int ret = R_ERROR_NONE;          /* The return value */
BIO *bio_out;                    /* The output channel for error messages */
R_CERT_STORE_CTX *store_ctx;     /* The certificate store context */
R_CERT_STORE *store_obj;         /* The certificate store object */
R_CERT_NAME *subject_name;       /* The subject name of a certificate in
                                  * the store
                                  */
R_PKEY *private_key;             /* The private key of a certificate already
                                  * loaded into the store
                                  */
...
/* Find a certificate in the store using subject name as the search
 * criteria and copy this entry into the store object
 */
if ((ret = R_CERT_STORE_find_entry_by_subject(store_obj, subject_name,
    R_CERT_STORE_CA_CERTIFICATE)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to find certificate in store\n");
    goto end;
}

/* Add the private key of the certificate to the existing contents of the
 * store object
 */
if ((ret = R_CERT_STORE_set_info(store_obj, R_CERT_STORE_INFO_PRIV_KEY,
    private_key)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to set private key into store object\n");
    goto end;
}

/* As the certificate store object now owns the private key, the application
 * is not required to free it
 */
private_key = NULL;

/*
 * Multithreading Case:
 *
 * Lock the certificate store before updating the details for this entry.
 * Note that locking callbacks must have been registered with the library
 * prior to calling R_CERT_STORE_CTX_lock() and R_CERT_STORE_CTX_unlock().
 *
 * Refer to the threading sample for instructions on registering locking
 * callbacks.
 */
R_CERT_STORE_CTX_lock(store_ctx, R_CERT_STORE_CTX_LOCK_WRITE);

/* Update the certificate store entry with the private key */
ret = R_CERT_STORE_update(store_obj);

R_CERT_STORE_CTX_unlock(store_ctx, R_CERT_STORE_CTX_LOCK_WRITE);

if (ret != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to update certificate store entry\n");
    goto end;
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
Samples:
store.c.

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