RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Object Functions

This section outlines the functions that facilitate certificate objects. An R_CERT is an object representation of a certificate. Using the object, it is possible to create, manipulate, sign or verify certificates.

Functions

int R_CDECL R_CERT_new (R_CERT_CTX *cert_ctx, R_CERT_TYPE type, R_CERT **cert)
 Creates a new certificate. More...

int R_CDECL R_CERT_free (R_CERT *cert)
 Removes the certificate cert and frees all allocated memory. More...

int R_CDECL R_CERT_from_binary (R_CERT_CTX *cert_ctx, R_FLAG_SHARE flag, R_CERT_TYPE type, unsigned int max_buf_len, const unsigned char *buf, unsigned int *consumed_len, R_CERT **cert)
 Creates a certificate from the specified binary data in ASN.1 format indicated by data with a length of length. More...

int R_CDECL R_CERT_to_binary (R_CERT *cert, unsigned int max_buf_len, unsigned char *buf, unsigned int *outlen)
 Creates ASN.1 binary certificate data from the specified R_CERT structure. More...

int R_CDECL R_CERT_inc_reference (R_CERT *cert)
 Increments the reference count for the specified certificate structure cert. More...

int R_CDECL R_CERT_dup (R_CERT *cert, R_FLAG_SHARE flag, R_CERT **dup)
 Duplicates the certificate object cert and returns the duplicate in dup. More...

int R_CDECL R_CERT_get_info (R_CERT *cert, R_CERT_INFO info_id, void *value)
 Returns the requested information from the certificate. More...

int R_CDECL R_CERT_set_info (R_CERT *cert, R_CERT_INFO info_id, void *value)
 Sets the information into a certificate. More...

int R_CDECL R_CERT_public_key_to_R_PKEY (R_CERT *cert, R_FLAG_SHARE flag, R_PKEY **pkey)
 Returns the public key for the certificate cert. More...

int R_CDECL R_CERT_sign (R_CERT *cert, R_PKEY *pkey, int sig_type)
 Uses the signature type sig_type to sign the certificate cert. More...

int R_CDECL R_CERT_verify (R_CERT *cert, R_PKEY *pkey, int *verified)
 Verifies the R_CERT certificate cert using the public key pkey. More...

int R_CDECL R_CERT_compare_cb (R_CERT *cert1, R_CERT *cert2)
 Compares two certificates cert1 and cert2. More...

int R_CDECL R_CERT_is_equal (R_CERT *cert1, R_CERT *cert2)
 Compares certificates cert1 and cert2 to establish whether they are binary equivalents. More...

int R_CDECL R_CERT_is_info_present (R_CERT *cert, R_CERT_INFO info_id)
 Checks the specified extension is present in the certificate. More...

int R_CDECL R_CERT_is_info_critical (R_CERT *cert, R_CERT_INFO info_id)
 Checks that the specified extension in a certificate is critical. More...

int R_CDECL R_CERT_subject_name_compare_cb (R_CERT *cert1, R_CERT *cert2)
 Compares the subject name of two certificates cert1 and cert2. More...

int R_CDECL R_CERT_subject_name_is_equal (R_CERT *cert1, R_CERT *cert2)
 Compares the subject names of certificates cert1 and cert2 to establish whether they are binary equivalents. More...

int R_CDECL R_CERT_subject_name_to_string (R_CERT *cert, unsigned int max_str_len, char *str)
 Generates a string version of the subject name from the certificate cert and copies it into the string str. More...

int R_CDECL R_CERT_issuer_name_to_string (R_CERT *cert, unsigned int max_str_len, char *str)
 Generates a string version of the issuer name from the certificate cert and copies it into the string str. More...

int R_CDECL R_CERT_not_after_to_R_TIME (R_CERT *cert, R_TIME *not_after_time)
 Returns a reference to an R_TIME representation of the notAfter field for the certificate cert. More...

int R_CDECL R_CERT_not_after_from_R_TIME (R_CERT *cert, R_TIME *not_after_time)
 Stores the notAfter time into the certificate. More...

int R_CDECL R_CERT_not_before_to_R_TIME (R_CERT *cert, R_TIME *not_before_time)
 Returns a reference to an R_TIME representation of the notBefore field for the certificate cert. More...

int R_CDECL R_CERT_not_before_from_R_TIME (R_CERT *cert, R_TIME *not_before_time)
 Stores the notBefore time into the certificate. More...

int R_CDECL R_CERT_not_after_to_binary (R_CERT *cert, unsigned int max_buf_len, unsigned char *buf, unsigned int *out_len)
 Returns a reference to a binary representation of the notAfter field for the certificate cert. More...

int R_CDECL R_CERT_not_before_to_binary (R_CERT *cert, unsigned int max_buf_len, unsigned char *buf, unsigned int *out_len)
 Returns a reference to a binary representation of the notBefore field for the certificate cert. More...

int R_CDECL R_CERT_not_after_to_string (R_CERT *cert, unsigned int max_buf_len, char *str)
 Returns a string representation of the notAfter field for the certificate cert. More...

int R_CDECL R_CERT_not_before_to_string (R_CERT *cert, unsigned int max_buf_len, char *str)
 Returns a string representation of the notBefore field for the certificate cert. More...

int R_CDECL R_CERT_read (R_CERT_CTX *cert_ctx, BIO *bio, R_CERT_TYPE type, R_FORMAT format, R_CERT **cert)
 Creates a new certificate from the data obtained from the BIO bio. More...

int R_CDECL R_CERT_read_file (R_CERT_CTX *cert_ctx, char *filename, R_CERT_TYPE type, R_FORMAT format, R_CERT **cert)
 Creates a new certificate structure from the file filename. More...

int R_CDECL R_CERT_write (R_CERT *cert, BIO *bio, R_FORMAT format, void *format_arg)
 Outputs the R_CERT structure cert to the BIO bio. More...

int R_CDECL R_CERT_write_file (R_CERT *cert, char *filename, R_FORMAT format, void *format_arg)
 Outputs the R_CERT structure cert to the file filename. More...

int R_CDECL R_CERT_TYPE_from_string (char *str, R_CERT_TYPE *type)
 Returns the certificate type for the string str. More...

int R_CDECL R_CERT_TYPE_to_string (R_CERT_TYPE type, unsigned int max_str_len, char *str)
 Returns the string for the type type. More...

int R_CDECL R_CERT_fingerprint (R_CERT *cert, int md_type, unsigned int max_buf_len, unsigned char *buf, unsigned int *out_len)
 Returns the fingerprint hash of a certificate. More...

int R_CDECL R_CERT_is_matching_private_key (R_CERT *cert, R_PKEY *pkey)
 Checks that the specified private key pkey corresponds to the public key in the certificate cert. More...

int R_CDECL R_CERT_time_validity (R_CERT *cert, int *validity)
 Checks the validity of the specified certificate cert. More...

int R_CDECL R_CERT_issuer_name_to_R_CERT_NAME (R_CERT *cert, R_FLAG_SHARE flag, R_CERT_NAME **issuer)
 Creates an R_CERT_NAME that contains the issuer name for the certificate cert. More...

int R_CDECL R_CERT_subject_name_to_R_CERT_NAME (R_CERT *cert, R_FLAG_SHARE flag, R_CERT_NAME **subject)
 Creates an R_CERT_NAME that contains the subject name subject for the certificate cert. More...

int R_CDECL R_CERT_check (R_CERT *cert, unsigned int check_flag)
 Checks the version of an X.509 certificate when extensions or subject and issuer unique identifiers are present. More...

Function Documentation

int R_CDECL R_CERT_check (  R_CERT *    cert,
unsigned int    check_flag
)  ;
 

Checks the version of an X.509 certificate when extensions or subject and issuer unique identifiers are present. Also checks that any unrecognized extensions are not critical.

Parameters:
cert [In] The certificate to check.
check_flag [In] The certificate check options that will be executed. One of:
  • R_CERT_CHECK_FLAG_VERSION.
  • R_CERT_CHECK_FLAG_EXTENSIONS.
  • R_CERT_CHECK_FLAG_ALL.
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    ext.c.

    int R_CDECL R_CERT_compare_cb (  R_CERT *    cert1,
    R_CERT *    cert2
    )  ;
     

    Compares two certificates cert1 and cert2.

    Parameters:
    cert1 [In] The first certificate.
    cert2 [In] The second certificate.
    Returns:
    The comparison result:
  • <0 indicates cert1 is smaller than cert2.
  • =0 indicates cert1 is equal to cert2.
  • >0 indicates cert1 is greater than cert2.
    • note.gif
    The certificates cert1 and cert2 are processed as unsigned character strings.
    This function is intended for use as the compare function for qsort, bsearch and a certificate store. The terms used for the result description, that is, 'smaller than' and 'greater than', are only meaningful for sorting and do not necessarily indicate the relative number of Bytes in the certificates.
    See also:
    R_CERT_is_equal().

    int R_CDECL R_CERT_dup (  R_CERT *    cert,
    R_FLAG_SHARE    flag,
    R_CERT **    dup
    )  ;
     

    Duplicates the certificate object cert and returns the duplicate in dup.

    Parameters:
    cert [In] The original certificate.
    flag [In] The share flag.
    See Shared Flag Identifiers for valid values.
    dup [Out] The duplicate certificate.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.

    int R_CDECL R_CERT_fingerprint (  R_CERT *    cert,
    int    md_type,
    unsigned int    max_buf_len,
    unsigned char *    buf,
    unsigned int *    out_len
    )  ;
     

    Returns the fingerprint hash of a certificate. The buffer buf should be R_CR_DIGEST_MAX_LEN Bytes long and the amount of data copied into the buffer is returned in out_len.

    Parameters:
    cert [In] The certificate.
    md_type [In] The digest type. One of:
  • R_CR_ID_MD2.
  • R_CR_ID_MD5.
  • R_CR_ID_SHA1.
    • max_buf_len [In] The length allocated for the data buffer.
    buf [Out] The buffer in which to put the fingerprint. The buffer may be NULL, in which case just the length of the digest is returned.
    out_len [Out] The length of the fingerprint.
    Returns:
    R_ERROR_NONE indicates success.
    R_ERROR_BAD_VALUE indicates an invalid message digest.
    See Identifiers for valid values.
    Samples:
    cert.c.

    int R_CDECL R_CERT_free (  R_CERT *    cert )  ;
     

    Removes the certificate cert and frees all allocated memory.

    Parameters:
    cert [In] The certificate to destroy.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    Certificate structures have reference counts. Actual memory is freed only after all references are freed.
    See also:
    R_CERT_inc_reference().
    Samples:
    cert.c, cert_smpl.c, cm_env_sm.c, cm_open.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign_sm.c, ext.c, frombuf.c, ocsp_req_create.c, ocsp_resp_vfy.c, p7ssl_client.c, rcert2sslcert.c, req.c, reqgen.c, ss_cert_smpl.c, sslcert2rcert.c, store.c, verify.c, vfy_adv.c, vfy_bc.c, and vfy_smpl.c.

    int R_CDECL R_CERT_from_binary (  R_CERT_CTX *    cert_ctx,
    R_FLAG_SHARE    flag,
    R_CERT_TYPE    type,
    unsigned int    max_buf_len,
    const unsigned char *    buf,
    unsigned int *    consumed_len,
    R_CERT **    cert
    )  ;
     

    Creates a certificate from the specified binary data in ASN.1 format indicated by data with a length of length. If cert is NULL then a certificate is allocated.

    Parameters:
    cert_ctx [In] The certificate context.
    flag [In] The share flag.
    See Shared Flag Identifiers for valid values.
    type [In] The certificate type.
    See Certificate Types for valid values.
    max_buf_len [In] The length of the binary data.
    buf [In] The binary data buffer holding the certificate.
    consumed_len [Out] The amount of data used to create the certificate.
    cert [Out] The created certificate structure.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_to_binary().
    Samples:
    cm_env_sm.c, cm_sign_sm.c, p7ssl_client.c, rcert2sslcert.c, sslcert2rcert.c, verify.c, vfy_adv.c, and vfy_smpl.c.

    int R_CDECL R_CERT_get_info (  R_CERT *    cert,
    R_CERT_INFO    info_id,
    void *    value
    )  ;
     

    Returns the requested information from the certificate.

    Parameters:
    cert [In] The certificate from which to retrieve the information.
    info_id [In] The information identifier.
    See Information Types for valid values and the data type returned in value.
    value [Out] The data block to fill with requested information.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_set_info().
    Samples:
    cert.c, ext.c, ocsp_req_create.c, ocsp_resp_vfy.c, and vfy_adv.c.

    int R_CDECL R_CERT_inc_reference (  R_CERT *    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] The certificate being referenced.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    The reference count is decremented by R_CERT_free() so the actual memory allocation for the certificate will remain until the last reference is removed.
    See also:
    R_CERT_free().
    Samples:
    cm_env_sm.c.

    int R_CDECL R_CERT_is_equal (  R_CERT *    cert1,
    R_CERT *    cert2
    )  ;
     

    Compares certificates cert1 and cert2 to establish whether they are binary equivalents.

    Parameters:
    cert1 [In] The first certificate.
    cert2 [In] The second certificate.
    Returns:
    The comparison result. One of:
  • 0 indicates cert1 is not equal to cert2.
  • 1 indicates cert1 is equal to cert2.
    • note.gif
    The certificates cert1 and cert2 are processed as binary data.
    See also:
    R_CERT_compare_cb().

    int R_CDECL R_CERT_is_info_critical (  R_CERT *    cert,
    R_CERT_INFO    info_id
    )  ;
     

    Checks that the specified extension in a certificate is critical.

    Parameters:
    cert [In] The certificate.
    info_id [In] The identifier of the extension to check. One of:
  • R_CERT_INFO_KEY_USAGE.
  • R_CERT_INFO_EXTENDED_KEY_USAGE.
  • R_CERT_INFO_BASIC_CONSTRAINTS.
  • R_CERT_INFO_AUTHORITY_KEY_ID.
  • R_CERT_INFO_SUBJECT_KEY_ID.
  • R_CERT_INFO_SUBJECT_ALT_NAME.
    • Returns:
    0 indicates the extension is not present or not critical.
    1 indicates the extension is present and critical.
    See also:
    R_CERT_is_info_present().
    Samples:
    cm_adv.c.

    int R_CDECL R_CERT_is_info_present (  R_CERT *    cert,
    R_CERT_INFO    info_id
    )  ;
     

    Checks the specified extension is present in the certificate.

    Parameters:
    cert [In] The certificate.
    info_id [In] The identifier of the extension to check. One of:
  • R_CERT_INFO_KEY_USAGE.
  • R_CERT_INFO_EXTENDED_KEY_USAGE.
  • R_CERT_INFO_BASIC_CONSTRAINTS.
  • R_CERT_INFO_AUTHORITY_KEY_ID.
  • R_CERT_INFO_SUBJECT_KEY_ID.
  • R_CERT_INFO_SUBJECT_ALT_NAME.
    • Returns:
    0 indicates the extension is not present.
    1 indicates the extension is present.
    See also:
    R_CERT_is_info_critical().
    Samples:
    cm_adv.c, and ocsp_resp_vfy.c.

    int R_CDECL R_CERT_is_matching_private_key (  R_CERT *    cert,
    R_PKEY *    pkey
    )  ;
     

    Checks that the specified private key pkey corresponds to the public key in the certificate cert.

    Parameters:
    cert [In] The certificate.
    pkey [In] The private key to check.
    Returns:
    The comparison returns. One of:
  • 0 indicates error or no match.
  • 1 indicates a successful match.
    • Samples:
    rcert2sslcert.c, reqgen.c, and sslcert2rcert.c.

    int R_CDECL R_CERT_issuer_name_to_R_CERT_NAME (  R_CERT *    cert,
    R_FLAG_SHARE    flag,
    R_CERT_NAME **    issuer
    )  ;
     

    Creates an R_CERT_NAME that contains the issuer name for the certificate cert.

    Parameters:
    cert [In] The certificate from which to retrieve the issuer name.
    flag [In] The share flag.
    See Shared Flag Identifiers for valid values.
    issuer [Out] The new issuer name.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    This function is used for comparative purposes and for manipulating the name in a structured manner. The caller should free the issuer name.
    See also:
    R_CERT_NAME_free()
    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 */
}
    Samples:
    store.c.

    int R_CDECL R_CERT_issuer_name_to_string (  R_CERT *    cert,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Generates a string version of the issuer name from the certificate cert and copies it into the string str.

    Parameters:
    cert [In] The certificate containing the issuer name.
    max_str_len [In] The length of the string buffer.
    str [Out] The buffer containing the issuer name string.
    Returns:
    R_ERROR_NONE indicates success.
    R_ERROR_BUFFER_TOO_SMALL if the buffer to hold the string is not large enough.
    See Identifiers for valid values.
    note.gif
    If the maximum length of the string is less than required, the string is truncated and the last character is the NULL terminator. An error code is returned in this case.
    See also:
    R_CERT_issuer_name_to_R_CERT_NAME(), R_CERT_subject_name_to_string() and R_CERT_subject_name_to_R_CERT_NAME().
    Samples:
    cert.c, rcert2sslcert.c, sslcert2rcert.c, and vfy_adv.c.

    int R_CDECL R_CERT_new (  R_CERT_CTX *    ctx,
    R_CERT_TYPE    type,
    R_CERT **    cert
    )  ;
     

    Creates a new certificate. Certificates are used for authenticating the peer in some key exchange algorithms.

    Parameters:
    ctx [In] The certificate context to use when creating the new certificate.
    type [In] The certificate type.
    See Certificate Types for valid values.
    cert [Out] The created certificate.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    ss_cert_smpl.c.

    int R_CDECL R_CERT_not_after_from_R_TIME (  R_CERT *    cert,
    R_TIME *    not_after_time
    )  ;
     

    Stores the notAfter time into the certificate.

    Parameters:
    cert [In] The certificate.
    not_after_time [In] The notAfter time to set.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_not_after_to_R_TIME(), R_CERT_not_before_from_R_TIME() and R_CERT_not_before_to_R_TIME().
    Samples:
    cert_smpl.c, req.c, and ss_cert_smpl.c.

    int R_CDECL R_CERT_not_after_to_binary (  R_CERT *    cert,
    unsigned int    max_buf_len,
    unsigned char *    buf,
    unsigned int *    out_len
    )  ;
     

    Returns a reference to a binary representation of the notAfter field for the certificate cert. The time data is in buf and the length of the data is in out_len. Certificates are not valid after the notAfter date.

    Parameters:
    cert [In] The certificate from which to retrieve the information.
    max_buf_len [In] The length allocated for the data buffer.
    buf [Out] The buffer of binary data.
    out_len [Out] The length of data in the buffer.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    The notAfter information is a time value in binary format (that is, the format of the data inside the certificate).
    Passing in a NULL buffer returns the required length for the size of the buffer.
    See also:
    R_CERT_not_before_to_binary().
    Samples:
    cm_adv.c.

    int R_CDECL R_CERT_not_after_to_R_TIME (  R_CERT *    cert,
    R_TIME *    not_after_time
    )  ;
     

    Returns a reference to an R_TIME representation of the notAfter field for the certificate cert.

    Parameters:
    cert [In] The certificate from which to retrieve the data.
    not_after_time [Out] The retrieved notAfter time.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for other values.
    See also:
    R_CERT_not_before_to_R_TIME().
    Example:

    /* $Id: R_CERT_not_before_to_R_TIME.c,v 1.4 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 *cert;                /* The certificate */
R_TIME_CTX *tctx;            /* The time context */
R_TIME *cert_time = NULL;    /* The object where the certificate time is
                              * loaded
                              */
R_TIME *curr_time = NULL;    /* The current time */
int cmp_result;              /* The result after comparing the current
                              * time with the certificate times
                              */
...
/* Create a time object to store the current time */
if ((ret = R_TIME_new(tctx, &curr_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to create time object\n");
    goto end;
}

/* Retrieve the current system time */
if ((ret = R_TIME_time(curr_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to retrieve current system time\n");
    goto end;
}

/* Create a time object to store the certificate times */
if ((ret = R_TIME_new(tctx, &cert_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to create time object\n");
    goto end;
}

/* Retrieve the notBefore time from the certificate */
if ((ret = R_CERT_not_before_to_R_TIME(cert, cert_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out,
        "Failed to retrieve notBefore time from certificate\n");
    goto end;
}

/* Compare the notBefore time to the current time */
if ((ret = R_TIME_cmp(curr_time, cert_time, &cmp_result)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to compare notBefore and current times\n");
    goto end;
}

if (cmp_result < 0)
{
    BIO_printf(bio_out, "Certificate is not yet current\n");
    goto end;
}

/* Retrieve the notBefore time from the certificate */
if ((ret = R_CERT_not_after_to_R_TIME(cert, cert_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out,
        "Failed to retrieve notAfter time from certificate\n");
    goto end;
}

/* Compare the notAfter time to the current time */
if ((ret = R_TIME_cmp(curr_time, cert_time, &cmp_result)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to compare notAfter and current times\n");
    goto end;
}

if (cmp_result > 0)
{
    BIO_printf(bio_out, "Certificate has expired\n");
    goto end;
}
...
end:

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

    int R_CDECL R_CERT_not_after_to_string (  R_CERT *    cert,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Returns a string representation of the notAfter field for the certificate cert. The format of the string is R_TIME_EXTERNAL_FORMAT_SHRF.

    Parameters:
    cert [In] The certificate from which to retrieve the data.
    max_str_len [In] The number of Bytes allocated for the string.
    str [Out] The string to which to write the result.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_not_before_to_string().
    Samples:
    cert.c, and vfy_adv.c.

    int R_CDECL R_CERT_not_before_from_R_TIME (  R_CERT *    cert,
    R_TIME *    not_before_time
    )  ;
     

    Stores the notBefore time into the certificate.

    Parameters:
    cert [In] The certificate.
    not_before_time [In] The notBefore time to set.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_not_before_to_R_TIME(), R_CERT_not_after_from_R_TIME() and R_CERT_not_after_to_R_TIME().
    Samples:
    cert_smpl.c, req.c, and ss_cert_smpl.c.

    int R_CDECL R_CERT_not_before_to_binary (  R_CERT *    cert,
    unsigned int    max_buf_len,
    unsigned char *    buf,
    unsigned int *    out_len
    )  ;
     

    Returns a reference to a binary representation of the notBefore field for the certificate cert. The time data is in buf and the length of the data is in out_len. Certificates are not valid before the notBefore date.

    Parameters:
    cert [In] The certificate from which to retrieve the information.
    max_buf_len [In] The length allocated for the data buffer.
    buf [Out] The buffer of binary data.
    out_len [Out] The length of data in the buffer.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    The notBefore information is a time value in binary format (that is, the format of the data inside the certificate).
    Passing in a NULL buffer returns the required length for the size of the buffer.
    See also:
    R_CERT_not_after_to_binary().
    Samples:
    cm_adv.c.

    int R_CDECL R_CERT_not_before_to_R_TIME (  R_CERT *    cert,
    R_TIME *    not_before_time
    )  ;
     

    Returns a reference to an R_TIME representation of the notBefore field for the certificate cert.

    Parameters:
    cert [In] The certificate from which to retrieve the data.
    not_before_time [Out] The retrieved notBefore time.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_not_after_to_R_TIME().
    Example:

    /* $Id: R_CERT_not_before_to_R_TIME.c,v 1.4 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 *cert;                /* The certificate */
R_TIME_CTX *tctx;            /* The time context */
R_TIME *cert_time = NULL;    /* The object where the certificate time is
                              * loaded
                              */
R_TIME *curr_time = NULL;    /* The current time */
int cmp_result;              /* The result after comparing the current
                              * time with the certificate times
                              */
...
/* Create a time object to store the current time */
if ((ret = R_TIME_new(tctx, &curr_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to create time object\n");
    goto end;
}

/* Retrieve the current system time */
if ((ret = R_TIME_time(curr_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to retrieve current system time\n");
    goto end;
}

/* Create a time object to store the certificate times */
if ((ret = R_TIME_new(tctx, &cert_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to create time object\n");
    goto end;
}

/* Retrieve the notBefore time from the certificate */
if ((ret = R_CERT_not_before_to_R_TIME(cert, cert_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out,
        "Failed to retrieve notBefore time from certificate\n");
    goto end;
}

/* Compare the notBefore time to the current time */
if ((ret = R_TIME_cmp(curr_time, cert_time, &cmp_result)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to compare notBefore and current times\n");
    goto end;
}

if (cmp_result < 0)
{
    BIO_printf(bio_out, "Certificate is not yet current\n");
    goto end;
}

/* Retrieve the notBefore time from the certificate */
if ((ret = R_CERT_not_after_to_R_TIME(cert, cert_time)) != R_ERROR_NONE)
{
    BIO_printf(bio_out,
        "Failed to retrieve notAfter time from certificate\n");
    goto end;
}

/* Compare the notAfter time to the current time */
if ((ret = R_TIME_cmp(curr_time, cert_time, &cmp_result)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Failed to compare notAfter and current times\n");
    goto end;
}

if (cmp_result > 0)
{
    BIO_printf(bio_out, "Certificate has expired\n");
    goto end;
}
...
end:

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

    int R_CDECL R_CERT_not_before_to_string (  R_CERT *    cert,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Returns a string representation of the notBefore field for the certificate cert. The format of the string is R_TIME_EXTERNAL_FORMAT_SHRF.

    Parameters:
    cert [In] The certificate from which to retrieve the data.
    max_str_len [In] The number of Bytes allocated for the string.
    str [Out] The string to which to write the result.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_not_after_to_string().
    Samples:
    cert.c, and vfy_adv.c.

    int R_CDECL R_CERT_public_key_to_R_PKEY (  R_CERT *    cert,
    R_FLAG_SHARE    flag,
    R_PKEY **    pkey
    )  ;
     

    Returns the public key for the certificate cert. The public key in a certificate is used to encrypt data and decrypt the signatures of certificates signed by the certificate.

    Parameters:
    cert [In] The certificate from which to retrieve the public key.
    flag [In] The share flag.
    See Shared Flag Identifiers for valid values.
    pkey [Out] The retrieved public key.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    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 */
}
    Samples:
    cert.c, ocsp_resp_find_key.c, ocsp_resp_vfy.c, store.c, and verify.c.

    int R_CDECL R_CERT_read (  R_CERT_CTX *    cert_ctx,
    BIO *    bio,
    R_CERT_TYPE    type,
    R_FORMAT    format,
    R_CERT **    cert
    )  ;
     

    Creates a new certificate from the data obtained from the BIO bio. The encoding format is specified by format. This information is used when decoding the certificate.

    Parameters:
    cert_ctx [In] The certificate context.
    bio [In] The BIO from which to read the certificate data.
    type [In] The certificate type.
    See Certificate Types for valid values.
    format [In] The certificate format.
    See R_FORMAT_BINARY.
    cert [Out] The created R_CERT structure.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_read_file(), R_CERT_write() and R_CERT_write_file().
    Samples:
    cert.c, ext.c, and frombuf.c.

    int R_CDECL R_CERT_read_file (  R_CERT_CTX *    cert_ctx,
    char *    filename,
    R_CERT_TYPE    type,
    R_FORMAT    format,
    R_CERT **    cert
    )  ;
     

    Creates a new certificate structure from the file filename. The encoding format is specified by format. This information is used when decoding the certificate.

    Parameters:
    cert_ctx [In] The certificate context.
    filename [In] The name of the file with the certificate data.
    type [In] The certificate type.
    See Certificate Types for valid values.
    format [In] The certificate request format.
    R_FORMAT_BINARY.
    cert [Out] The created R_CERT structure.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_read(), R_CERT_write() and R_CERT_write_file().
    Example:

    /* $Id: R_CERT_CTX_new.c,v 1.5 2003/06/18 02:29:01 hfrancis 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_LIB_CTX *lib_ctx;              /* The library context */
R_CERT_CTX *cert_ctx = NULL;     /* The certificate context */
R_CERT *cert = NULL;             /* The certificate */
char *certfile;                  /* The file where the certificate is stored */
...
/* Create an X.509 certificate context */
if ((ret = R_CERT_CTX_new(lib_ctx, R_RES_FLAG_DEF, R_CERT_TYPE_X509,
    &cert_ctx)) != R_ERROR_NONE)
{
    BIO_printf(bio_out, "Certificate context new failure\n");
    goto end:
}

/* 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;
}

/* Check for the certificate sign key usage extension in the certificate */
if (R_CERT_test_key_usage(cert, R_CERT_KEY_USAGE_KEY_CERT_SIGN) == 1)
{
    BIO_printf(bio_out, "The certificate sign key usage extension is set\n");
}
else
{
    BIO_printf(bio_out, "The certificate sign key usage extension is not set\n");
}
...
end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code */
}
    Samples:
    cm_open.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, ocsp_req_create.c, req.c, reqgen.c, store.c, and vfy_bc.c.

    int R_CDECL R_CERT_set_info (  R_CERT *    cert,
    R_CERT_INFO    info_id,
    void *    value
    )  ;
     

    Sets the information into a certificate.

    Parameters:
    cert [In] The certificate.
    info_id [In] The information identifier.
    See Information Types for valid values and the data type of the information specified in value.
    value [In] The information data to set.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_get_info().
    Example:

    /* $Id: R_CERT_REQ_read_file.c,v 1.9 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. */
R_CERT_REQ_CTX *req_ctx;     /* The context definition for the request. */
R_CERT_REQ *req;             /* The certificate request. */
R_CERT_CTX *cert_ctx;        /* The context definition for a certificate. */
R_CERT *new_cert = NULL;     /* A container to hold a certificate. */
R_CERT_NAME *name = NULL;    /* May contain name information associated with
                                a certificate. */
char *req_file = NULL;       /* The file that contains the cert request. */
int req_type;                /* The type of certificate request, e.g. X.509 */
int req_form;                /* The format of the request, BIN or PEM. */
int cert_type;               /* Specifies the type of a certificate. */

static char issuer_name[] =
"C=AU, ST=Qld, L=Brisbane, O=RSA Security, OU=Engineering, CN=Root Certificate";

/* Create a library context, certificate context and certificate
 * request context.
 */
...

/* Load the certificate request from an existing file into a structure,
 * ensuring that the correct request type and format are specified.
 */
if (R_CERT_REQ_read_file(req_ctx, req_file, req_type, req_form,
    &req) != R_ERROR_NONE)
{
    goto end;
}

/* The returned certificate request can now be used to generate a
 * new certificate.
 */
if (R_CERT_REQ_to_R_CERT(req, cert_ctx, cert_type, &new_cert))
    != R_ERROR_NONE)
{
    goto end;
}

/* Information, such as the certificate issuer name, can now be changed in
 * this new certificate. To do this, first ensure that the name is in the
 * correct format so that it can be entered into the certificate.
 */
if (R_CERT_NAME_from_string(cert_ctx, issuer_name, &name)
    != R_ERROR_NONE)
{
    goto end;
}

/* Set this name information in the certificate. */
if (R_CERT_set_info(new_cert, R_CERT_INFO_ISSUER_R_CERT_NAME,
    name) != R_ERROR_NONE)
{
    goto end;
}

end:

if (ret != R_ERROR_NONE)
{
    /* Error handling code. */
}
    Samples:
    cert_smpl.c, req.c, and ss_cert_smpl.c.

    int R_CDECL R_CERT_sign (  R_CERT *    cert,
    R_PKEY *    pkey,
    int    sig_type
    )  ;
     

    Uses the signature type sig_type to sign the certificate cert. The private key pkey is used to encrypt the message digest.

    Parameters:
    cert [In] The certificate to sign.
    pkey [In] The private key used to sign the certificate.
    sig_type [In] The signature type. One of:
  • R_CR_ID_MD2_RSA.
  • R_CR_ID_MD5_RSA.
  • R_CR_ID_SHA1_RSA.
  • R_CR_ID_SHA1_DSA.
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_verify() and R_CERT_public_key_to_R_PKEY().
    Samples:
    cert_smpl.c, req.c, and ss_cert_smpl.c.

    int R_CDECL R_CERT_subject_name_compare_cb (  R_CERT *    cert1,
    R_CERT *    cert2
    )  ;
     

    Compares the subject name of two certificates cert1 and cert2.

    Parameters:
    cert1 [In] The first certificate.
    cert2 [In] The second certificate.
    Returns:
    The comparison result:
  • <0 indicates cert1 is smaller than cert2.
  • =0 indicates cert1 is equal to cert2.
  • >0 indicates cert1 is greater than cert2.
    • note.gif
    The certificates cert1 and cert2 are processed as unsigned character strings.
    This function is intended for use as the compare function for qsort, bsearch and a certificate store.
    See also:
    R_CERT_subject_name_is_equal().

    int R_CDECL R_CERT_subject_name_is_equal (  R_CERT *    cert1,
    R_CERT *    cert2
    )  ;
     

    Compares the subject names of certificates cert1 and cert2 to establish whether they are binary equivalents.

    Parameters:
    cert1 [In] The first certificate.
    cert2 [In] The second certificate.
    Returns:
    The comparison result:
  • 0 indicates cert1 is not equal to cert2.
  • 1 indicates cert1 is equal to cert2.
    • note.gif
    The certificates cert1 and cert2 are processed as binary data.
    See also:
    R_CERT_subject_name_compare_cb().

    int R_CDECL R_CERT_subject_name_to_R_CERT_NAME (  R_CERT *    cert,
    R_FLAG_SHARE    flag,
    R_CERT_NAME **    subject
    )  ;
     

    Creates an R_CERT_NAME that contains the subject name subject for the certificate cert.

    Parameters:
    cert [In] The certificate from which to retrieve the subject name.
    flag [In] The share flag.
    See Shared Flag Identifiers for valid values.
    subject [Out] The new subject name.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    The caller should free the subject name when it is no longer needed.
    See also:
    R_CERT_NAME_free().
    Samples:
    cert.c, ocsp_resp_find_key.c, req.c, and store.c.

    int R_CDECL R_CERT_subject_name_to_string (  R_CERT *    cert,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Generates a string version of the subject name from the certificate cert and copies it into the string str.

    Parameters:
    cert [In] The certificate containing the subject name.
    max_str_len [In] The length of the string buffer.
    str [Out] The buffer containing the subject name string.
    Returns:
    R_ERROR_NONE indicates success.
    R_ERROR_BUFFER_TOO_SMALL if the buffer to hold the string is not large enough.
    See Identifiers for valid values.
    note.gif
    If the maximum length of the string is less than required, the string is truncated and the last character is the NULL terminator. An error code is returned in this case.
    See also:
    R_CERT_subject_name_to_R_CERT_NAME(), R_CERT_issuer_name_to_string(), R_CERT_NAME_to_string() and R_CERT_issuer_name_to_R_CERT_NAME().
    Samples:
    cert.c, rcert2sslcert.c, sslcert2rcert.c, and vfy_adv.c.

    int R_CDECL R_CERT_time_validity (  R_CERT *    cert,
    int *    validity
    )  ;
     

    Checks the validity of the specified certificate cert. A certificate is valid if the current time falls between the notBefore and notAfter periods specified for the certificate.

    Parameters:
    cert [In] The certificate to check for time validity.
    validity [Out] The validity type. One of:
  • R_CERT_TIME_CURRENT.
  • R_CERT_TIME_EXPIRED.
  • R_CERT_TIME_NOT_YET_CURRENT.
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_not_after_to_binary(), R_CERT_not_before_to_binary(), R_CERT_not_after_to_string() and R_CERT_not_before_to_string().
    Example:

    /* $Id: R_CERT_time_validity.c,v 1.4 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 *cert;          /* The certificate */
int validity;          /* The result obtained when checking the validity
                        * of the certificate
                        */
char *str;
...
/* Check the notBefore and notAfter times of the certificate */
if ((ret = R_CERT_time_validity(cert, &validity)) != R_ERROR_NONE)
{
    goto end;
}

/* Display the result of the validity check */
if (validity == R_CERT_TIME_CURRENT)
{
    str = "is current";
}
else if (validity == R_CERT_TIME_NOT_YET_CURRENT)
{
    str = "is not yet current";
}
else
{
    str = "has expired";
}

BIO_printf(bio_out, "Certificate %s\n", str);
...
end:

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

    int R_CDECL R_CERT_to_binary (  R_CERT *    cert,
    unsigned int    max_buf_len,
    unsigned char *    buf,
    unsigned int *    out_len
    )  ;
     

    Creates ASN.1 binary certificate data from the specified R_CERT structure.

    Parameters:
    cert [In] The certificate from which to generate binary data.
    max_buf_len [In] The length allocated for the data buffer.
    buf [Out] The buffer of binary data.
    out_len [Out] The length of the data in the buffer.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    If buf is NULL, only the data length is calculated and returned in out_len.
    See also:
    R_CERT_from_binary().
    Samples:
    rcert2sslcert.c.

    int R_CDECL R_CERT_TYPE_from_string (  char *    str,
    R_CERT_TYPE *    type
    )  ;
     

    Returns the certificate type for the string str. This function is used for interpreting user input.

    Parameters:
    str [In] The format identifier string.
    See Certificate Types for valid values.
    type [Out] The certificate type identifier.
    See Certificate Types for valid values.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_TYPE_to_string().
    Samples:
    cert.c, cm_env.c, cm_env_strm.c, cm_env_strm_membio.c, cm_open.c, cm_open_strm.c, cm_open_strm_cb.c, cm_open_strm_membio.c, cm_sign.c, cm_sign_dgst.c, cm_sign_strm.c, ext.c, req.c, reqgen.c, store.c, and vfy_bc.c.

    int R_CDECL R_CERT_TYPE_to_string (  R_CERT_TYPE    type,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Returns the string for the type type. This function is used to create a human readable form of the certificate type.

    Parameters:
    type [In] The certificate type identifier.
    See Certificate Types for valid values.
    max_str_len [In] The maximum length of the string.
    str [Out] The certificate identifier string.
    See Certificate Types for valid values.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_TYPE_from_string().

    int R_CDECL R_CERT_verify (  R_CERT *    cert,
    R_PKEY *    pkey,
    int *    verified
    )  ;
     

    Verifies the R_CERT certificate cert using the public key pkey.

    Parameters:
    cert [In] The certificate to verify.
    pkey [In] The public key of a Certification Authority (CA) used to verify.
    verified [Out] Indicates whether the signature is verified or not. One of:
  • 0 indicates the signature was not validated with key.
  • 1 indicates the signature was validated with key.
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_sign() and R_CERT_public_key_to_R_PKEY().

    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 */
}
    Samples:
    cert.c, and verify.c.

    int R_CDECL R_CERT_write (  R_CERT *    cert,
    BIO *    bio,
    R_FORMAT    format,
    void *    format_arg
    )  ;
     

    Outputs the R_CERT structure cert to the BIO bio. format indicates how to encode the certificate. format_arg is extra data used in the formatting processing code.

    Parameters:
    cert [In] The certificate to output.
    format [In] The certificate format.
    See Data Encoding Formats for valid values.
    format_arg [In] The argument. One of:
  • CODE_BINARY - a string for the name of the function to get the certificate.
  • CODE_FIELDS - a string for the name of the certificate that is prepended to each field name.
    • bio [In] The BIO destination for the output data.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_write_file(), R_CERT_read() and R_CERT_read_file().
    Samples:
    cert.c, cert_smpl.c, frombuf.c, req.c, ss_cert_smpl.c, vfy_adv.c, and vfy_smpl.c.

    int R_CDECL R_CERT_write_file (  R_CERT *    cert,
    char *    filename,
    R_FORMAT    format,
    void *    format_arg
    )  ;
     

    Outputs the R_CERT structure cert to the file filename. format indicates how to encode the certificate. format_arg is extra data used in the formatting processing code.

    Parameters:
    cert [In] The certificate to output.
    format [In] The certificate format.
    See Data Encoding Formats for valid values.
    format_arg [In] The argument. One of:
  • CODE_BINARY - a string for the name of the function to get the certificate.
  • CODE_FIELDS - a string for the name of the certificate that is placed before each field name.
    • filename [In] The name of the file to write to.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_write(), R_CERT_read() and R_CERT_read_file().

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