RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Processing Functions

This section details the functions that facilitate certificate requests.

Typedefs

typedef int R_CDECL R_CERT_REQ_PRINT_FUNC_T (BIO *bio, R_CERT_REQ *req, R_FORMAT format, char *format_arg)
 The type of function that prints the details of a certificate request. More...


Functions

int R_CERT_REQ_new (R_CERT_REQ_CTX *req_ctx, R_CERT_REQ_TYPE type, R_CERT_REQ **req)
 Creates a new certificate request and returns it in req. More...

int R_CERT_REQ_free (R_CERT_REQ *req)
 Decrements the reference count for the certificate request req. More...

int R_CERT_REQ_from_binary (R_CERT_REQ_CTX *req_ctx, R_CERT_REQ_FLAG flag, R_CERT_REQ_TYPE type, unsigned int max_buf_len, const unsigned char *buf, unsigned int *consumed_len, R_CERT_REQ **req)
 Creates a certificate request from the content of buf and returns it in req. More...

int R_CERT_REQ_to_binary (R_CERT_REQ *req, unsigned int max_buf_len, unsigned char *buf, unsigned int *out_len)
 Converts the certificate request req to binary data and places it in buf. More...

int R_CERT_REQ_inc_reference (R_CERT_REQ *req)
 Increments the certificate request req reference count. More...

int R_CERT_REQ_subject_name_to_string (R_CERT_REQ *req, unsigned int max_str_len, char *str)
 Generates an ASCII representation of the subject name of the certificate request req and places it in str. More...

int R_CERT_REQ_public_key_to_R_PKEY (R_CERT_REQ *req, R_CERT_REQ_FLAG flag, R_PKEY **pkey)
 Returns the public key pkey contained in the certificate request req. More...

int R_CERT_REQ_get_info (R_CERT_REQ *req, R_CERT_REQ_INFO info_id, void *value)
 Retrieves information from the certificate request req. More...

int R_CERT_REQ_set_info (R_CERT_REQ *req, R_CERT_REQ_INFO info_id, void *value)
 Sets information into the certificate request req. More...

int R_CERT_REQ_subject_name_to_R_CERT_NAME (R_CERT_REQ *req, R_CERT_REQ_FLAG flag, R_CERT_NAME **subject)
 Returns the subject name contained by the certificate request req. More...

int R_CERT_REQ_verify (R_CERT_REQ *req, R_PKEY *pkey, int *verified)
 Verifies the certificate request req using the public key pkey. More...

int R_CERT_REQ_sign (R_CERT_REQ *req, R_PKEY *pkey, int sign_type)
 Signs the certificate request req with the private key pkey. More...

int R_CERT_REQ_fingerprint (R_CERT_REQ *req, int md_type, unsigned int max_buf_len, unsigned char *buf, unsigned int *out_len)
 Generates the fingerprint hash of the certificate request req and returns it in the buffer provided by the caller in buf. More...

int R_CDECL R_CERT_to_R_CERT_REQ (R_CERT *cert, R_CERT_REQ_CTX *ctx, R_CERT_REQ_TYPE type, R_CERT_REQ **req)
 Converts an existing certificate into a certificate request. More...

int R_CDECL R_CERT_REQ_to_R_CERT (R_CERT_REQ *req, R_CERT_CTX *ctx, R_CERT_TYPE type, R_CERT **cert)
 Creates a certificate from certificate request data. More...

int R_CDECL R_CERT_REQ_TYPE_from_string (char *str, R_CERT_REQ_TYPE *type)
 Converts a certificate request type string to a certificate request type value. More...

int R_CDECL R_CERT_REQ_TYPE_to_string (R_CERT_REQ_TYPE type, unsigned int max_str_len, char *str)
 Converts a certificate request type value to a certificate request type string. More...

int R_CDECL R_CERT_REQ_read (R_CERT_REQ_CTX *ctx, BIO *bio, R_CERT_REQ_TYPE type, R_FORMAT format, R_CERT_REQ **req)
 Creates a new certificate request from the data obtained from the BIO bio. More...

int R_CDECL R_CERT_REQ_read_file (R_CERT_REQ_CTX *ctx, char *filename, R_CERT_REQ_TYPE type, R_FORMAT format, R_CERT_REQ **req)
 Creates a new certificate request structure from the file filename. More...

int R_CDECL R_CERT_REQ_write (R_CERT_REQ *req, BIO *bio, R_FORMAT format, void *format_arg)
 Outputs the R_CERT_REQ structure req to the BIO bio. More...

int R_CDECL R_CERT_REQ_write_file (R_CERT_REQ *req, char *filename, R_FORMAT format, void *format_arg)
 Outputs the R_CERT_REQ structure req to the file filename. More...

Typedef Documentation

typedef int R_CDECL R_CERT_REQ_PRINT_FUNC_T(BIO *bio, R_CERT_REQ *req, R_FORMAT format, char *format_arg)
 

The type of function that prints the details of a certificate request.

Parameters:
bio [In] The BIO to which the output is printed.
cert [In] The certificate to print.
format [In] The format of the output data.
See Data Encoding Formats for valid values.
format_arg [In] The format argument.
See Data Encoding Formats for valid values.

Function Documentation

int R_CERT_REQ_fingerprint (  R_CERT_REQ *    req,
int    md_type,
unsigned int    max_buf_len,
unsigned char *    buf,
unsigned int *    out_len
)  ;
 

Generates the fingerprint hash of the certificate request req and returns it in the buffer provided by the caller in buf.

Parameters:
req [In] The certificate request.
md_type [In] The message digest type. One of:
  • R_CR_ID_MD2.
  • R_CR_ID_MD5.
  • R_CR_ID_SHA1.
    • max_buf_len [In] The length of the data buffer.
    buf [Out] The data buffer to hold the fingerprint.
    out_len [Out] The length of the fingerprint.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    The hash buffer must have been allocated enough Bytes in length. R_CR_DIGEST_MAX_LEN can be used for convenience as it will hold any digest.

    int R_CERT_REQ_free (  R_CERT_REQ *    req )  ;
     

    Decrements the reference count for the certificate request req. If the count falls to zero all the memory associated with the request is freed.

    Parameters:
    req [In] The certificate request.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    cert_smpl.c, req.c, req_smpl.c, and reqgen.c.

    int R_CERT_REQ_from_binary (  R_CERT_REQ_CTX *    req_ctx,
    R_CERT_REQ_FLAG    flag,
    R_CERT_REQ_TYPE    type,
    unsigned int    max_buf_len,
    const unsigned char *    buf,
    unsigned int *    consumed_len,
    R_CERT_REQ **    req
    )  ;
     

    Creates a certificate request from the content of buf and returns it in req.

    Parameters:
    req_ctx [In] The certificate request context.
    flag [In] The copy flag indicating how the data is placed in the certificate request.
    See Flags for valid values.
    type [In] The type of the certificate request.
    See Types for valid values.
    max_buf_len [In] The length of the data buffer.
    buf [In] The data buffer containing the certificate request.
    consumed_len [Out] The amount of data used in creating the certificate.
    req [Out] The new certificate request.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    cert_smpl.c.

    int R_CERT_REQ_get_info (  R_CERT_REQ *    req,
    R_CERT_REQ_INFO    info_id,
    void *    value
    )  ;
     

    Retrieves information from the certificate request req.

    Parameters:
    req [In] The certificate request.
    info_id [In] The information identifier.
    See Information Identifiers for valid values and the data type to pass into value.
    value [Out] The information value.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.

    int R_CERT_REQ_inc_reference (  R_CERT_REQ *    req )  ;
     

    Increments the certificate request req reference count. The count is used to indicate the number of references to the same certificate request that are in use. The data will be freed only when all references are no longer using it. Reference counting is best utilized when a request object is being shared among threads to negate the possibility of referencing freed memory.

    Parameters:
    req [In] The certificate request.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.

    int R_CERT_REQ_new (  R_CERT_REQ_CTX *    req_ctx,
    R_CERT_REQ_TYPE    type,
    R_CERT_REQ **    req
    )  ;
     

    Creates a new certificate request and returns it in req.

    Parameters:
    req_ctx [In] The certificate request context.
    type [In] The type of the certificate request.
    req [Out] The certificate request.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    The request is empty and can be filled via R_CERT_REQ_set_info() with Information Identifiers.
    Samples:
    req_smpl.c, and reqgen.c.

    int R_CERT_REQ_public_key_to_R_PKEY (  R_CERT_REQ *    req,
    R_CERT_REQ_FLAG    flag,
    R_PKEY **    pkey
    )  ;
     

    Returns the public key pkey contained in the certificate request req.

    Parameters:
    req [In] The certificate request.
    flag [In] The copy flag, indicating how the data from the request is placed in the public key.
    See Flags for valid values.
    pkey [Out] The public key from the request.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    req.c.

    int R_CDECL R_CERT_REQ_read (  R_CERT_REQ_CTX *    ctx,
    BIO *    bio,
    R_CERT_REQ_TYPE    type,
    R_FORMAT    format,
    R_CERT_REQ **    req
    )  ;
     

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

    Parameters:
    ctx [In] The R_CERT_REQ reference.
    bio [In] The BIO from which to read the certificate data.
    type [In] The certificate request type.
    Only R_CERT_REQ_TYPE_PKCS10 is supported.
    format [In] The certificate request format.
    See Data Encoding Formats for valid values.
    req [Out] The created R_CERT_REQ structure.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_REQ_read_file(), R_CERT_REQ_write() and R_CERT_REQ_write_file().
    Samples:
    req.c.

    int R_CDECL R_CERT_REQ_read_file (  R_CERT_REQ_CTX *    ctx,
    char *    filename,
    R_CERT_REQ_TYPE    type,
    R_FORMAT    format,
    R_CERT_REQ **    req
    )  ;
     

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

    Parameters:
    ctx [In] The R_CERT_REQ reference.
    filename [In] The name of the file with the request data.
    type [In] The certificate request type.
    Only R_CERT_REQ_TYPE_PKCS10 is supported.
    format [In] The certificate request format.
    See Data Encoding Formats for valid values.
    req [Out] The created R_CERT_REQ structure.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_REQ_read(), R_CERT_REQ_write() and R_CERT_REQ_write_file().
    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. */
}

    int R_CERT_REQ_set_info (  R_CERT_REQ *    req,
    R_CERT_REQ_INFO    info_id,
    void *    value
    )  ;
     

    Sets information into the certificate request req.

    Parameters:
    req [In] The certificate request.
    info_id [In] The information identifier.
    See Information Identifiers for valid values and the data type specified in value.
    value [In] The information value.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    req_smpl.c, and reqgen.c.

    int R_CERT_REQ_sign (  R_CERT_REQ *    req,
    R_PKEY *    pkey,
    int    sign_type
    )  ;
     

    Signs the certificate request req with the private key pkey. The message digest algorithm used is determined by md_type.

    Parameters:
    req [In] The certificate request.
    pkey [In] The private key.
    sign_type [In] The type of signature to produce. One of:
  • R_CR_ID_MD5_RSA.
  • R_CR_ID_SHA1_DSA.
  • R_CR_ID_SHA1_RSA.
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    Passing in NULL to pkey causes the function to generate the signature with the certificate request's public key.
    R_CERT_REQ_sign() is implemented using R_CERT_sign().
    See also:
    R_CERT_verify().
    Samples:
    req_smpl.c, and reqgen.c.

    int R_CERT_REQ_subject_name_to_R_CERT_NAME (  R_CERT_REQ *    req,
    R_CERT_REQ_FLAG    flag,
    R_CERT_NAME **    subject
    )  ;
     

    Returns the subject name contained by the certificate request req.

    Parameters:
    req [In] The certificate request.
    flag [In] The copy flag.
    See Flags for valid values.
    subject [Out] The subject name.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.

    int R_CERT_REQ_subject_name_to_string (  R_CERT_REQ *    req,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Generates an ASCII representation of the subject name of the certificate request req and places it in str. max_str_len contains the maximum number of characters including the NULL terminator.

    Parameters:
    req [In] The certificate request.
    max_str_len [In] The maximum number of characters to put into the string.
    str [Out] The character string into which to put the subject name.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.

    int R_CERT_REQ_to_binary (  R_CERT_REQ *    req,
    unsigned int    max_buf_len,
    unsigned char *    buf,
    unsigned int *    out_len
    )  ;
     

    Converts the certificate request req to binary data and places it in buf.

    Parameters:
    req [In] The certificate request.
    max_buf_len [In] The amount of memory allocated to data buffer in Bytes.
    buf [Out] The binary data buffer.
    out_len [Out] The amount of data placed into buf in Bytes.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.

    int R_CDECL R_CERT_REQ_to_R_CERT (  R_CERT_REQ *    req,
    R_CERT_CTX *    ctx,
    R_CERT_TYPE    type,
    R_CERT **    cert
    )  ;
     

    Creates a certificate from certificate request data. Neither the certificate request signature nor the certificate request version is checked to see if the request is valid. The new certificate is populated with the subject name and the public key from the request. The certificate will need other mandatory fields to be filled out before it can be signed by the issuer.

    Parameters:
    req [In] A pointer to a certificate request.
    ctx [In] A pointer to a certificate context.
    type [In] The certificate type.
    cert [Out] The generated certificate output.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    Use this function when issuing a certificate as a Certification Authority (CA).
    See also:
    R_CERT_REQ_new(), R_CERT_REQ_verify(), R_CERT_set_info(), and R_CERT_sign().
    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, and req.c.

    int R_CDECL R_CERT_REQ_TYPE_from_string (  char *    str,
    R_CERT_REQ_TYPE *    type
    )  ;
     

    Converts a certificate request type string to a certificate request type value.

    Parameters:
    str [In] The certificate request type string. One of:
  • "X509_REQ"/"x509_req".
  • "PKCS10_REQ"/"pkcs10_req".
    • type [Out] The certificate request type value.
    See Types for valid values.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_REQ_TYPE_to_string()
    Samples:
    req.c.

    int R_CDECL R_CERT_REQ_TYPE_to_string (  R_CERT_REQ_TYPE    type,
    unsigned int    max_str_len,
    char *    str
    )  ;
     

    Converts a certificate request type value to a certificate request type string.

    Parameters:
    type [In] The certificate request type value.
    max_str_len [In] The amount of memory allocated to str.
    str [Out] The certificate request type string.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_REQ_TYPE_from_string()

    int R_CERT_REQ_verify (  R_CERT_REQ *    req,
    R_PKEY *    pkey,
    int *    verified
    )  ;
     

    Verifies the certificate request req using the public key pkey.

    Parameters:
    req [In] The certificate request.
    pkey [In] The public key.
    verified [Out] Indicates whether the signature was verified or not. One of:
  • 0 indicates the signature was not verified with the key.
  • 1 indicates the signature was verified with the key.
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    Samples:
    req.c.

    int R_CDECL R_CERT_REQ_write (  R_CERT_REQ *    req,
    BIO *    bio,
    R_FORMAT    format,
    void *    format_arg
    )  ;
     

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

    Parameters:
    req [In] The certificate request to output.
    bio [In] The BIO destination for the output data.
    format [In] The certificate request format.
    See Data Encoding Formats for valid values and corresponding arguments.
    format_arg [In] The format-specific argument.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_REQ_write_file(), R_CERT_REQ_read() and R_CERT_REQ_read_file().
    Samples:
    req.c, req_smpl.c, and reqgen.c.

    int R_CDECL R_CERT_REQ_write_file (  R_CERT_REQ *    req,
    char *    filename,
    R_FORMAT    format,
    void *    format_arg
    )  ;
     

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

    Parameters:
    req [In] The certificate request to output.
    filename [In] The name of the file to write to.
    format [In] The certificate request format.
    See Data Encoding Formats for valid values and corresponding arguments.
    format_arg [In] The format-specific argument.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    See also:
    R_CERT_REQ_write(), R_CERT_REQ_read() and R_CERT_REQ_read_file().

    int R_CDECL R_CERT_to_R_CERT_REQ (  R_CERT *    cert,
    R_CERT_REQ_CTX *    ctx,
    R_CERT_REQ_TYPE    type,
    R_CERT_REQ **    req
    )  ;
     

    Converts an existing certificate into a certificate request.

    Parameters:
    cert [In] The certificate.
    ctx [In] The context information for the certificate request.
    type [In] The type of certificate request.
    See Types for valid values.
    req [Out] The generated certificate request.
    Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    note.gif
    Use this function when requesting a replacement for a certificate that is due to expire or has already expired.
    The request will not be signed, only populated with the relevant certificate information.
    See also:
    R_CERT_REQ_new() and R_CERT_REQ_free().
    Samples:
    reqgen.c.

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