RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Key Usage Functions

This section details the functions that manage certificate key usage extensions.

Functions

int R_CDECL R_CERT_test_key_usage (R_CERT *cert, int bits)
 Checks the status of a bit flag in a key usage extension from an X.509 certificate. More...

int R_CDECL R_CERT_test_extended_key_usage (R_CERT *cert, R_OID **oid, unsigned int count)
 Checks the status of a bit flag in an extended key usage extension from an X.509 certificate. More...

int R_CDECL R_CERT_key_usage_to_string (R_CERT *cert, char *separator, unsigned int max_str_len, char *str)
 Returns the string representation of the key usage bits specified in the certificate specified by cert. More...

int R_CDECL R_CERT_extended_key_usage_to_string (R_CERT *cert, char *separator, unsigned int max_str_len, char *str)
 Returns the string description of the extended key usage data from the certificate cert. More...

Function Documentation

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

Returns the string description of the extended key usage data from the certificate cert. Data is extracted from the certificate using R_CERT_get_info().

Parameters:
cert [In] The certificate with extended key usage.
separator [In] The separator between usage strings.
max_str_len [In] The length of the string buffer.
str [Out] The extended key usage data string. A combination of:
  • "CLIENT AUTH".
  • "CODE SIGNING".
  • "EMAIL PROTECTION".
  • "IPSEC ENDSYSTEM".
  • "IPSEC TUNNEL".
  • "IPSEC USER".
  • "OCSP SIGNING".
  • "SERVER AUTH".
  • "TIME STAMPING".
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values. An error is returned if there is no extended key usage data in the certificate.
    note.gif
    The contents of the string buffer will be undefined if there is an error return.
    See also:
    R_CERT_key_usage_to_string() and R_OID_to_string().
    Samples:
    cm_adv.c, and ext.c.

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

    Returns the string representation of the key usage bits specified in the certificate specified by cert.

    Parameters:
    cert [In] The certificate for which to retrieve the key usage bit.
    separator [In] The separator between usage strings.
    max_str_len [In] The length of the string buffer.
    str [Out] The string representation of the specified key usage bit. A combination of:
  • "CRL_SIGN".
  • "DATA_ENCIPHERMENT".
  • "DECIPHER_ONLY".
  • "DIGITAL_SIGNATURE".
  • "ENCIPHER_ONLY".
  • "KEY_AGREEMENT".
  • "KEY_CERT_SIGN".
  • "KEY_ENCIPHERMENT".
  • "NON_REPUDIATION".
    • Returns:
    R_ERROR_NONE indicates success.
    See Identifiers for valid values.
    An error is returned if there is no key usage data in the certificate.
    note.gif
    The contents of the string buffer will be undefined if there is an error return.
    See also:
    R_CERT_extended_key_usage_to_string() and R_OID_to_string().
    Samples:
    cm_adv.c, and ext.c.

    int R_CDECL R_CERT_test_extended_key_usage (  R_CERT *    cert,
    R_OID **    oid,
    unsigned int    count
    )  ;
     

    Checks the status of a bit flag in an extended key usage extension from an X.509 certificate.

    Parameters:
    cert [In] The certificate that has key usage information.
    oid [In] The array of certificate related Object Identifiers (OIDs).
    count [In] The count of OIDs in the array.
    Returns:
    The test result:
  • 0 indicates at least one OID is not present or that there is a processing error.
  • 1 indicates all the OIDs are present.
    • Samples:
    ocsp_resp_vfy.c.

    int R_CDECL R_CERT_test_key_usage (  R_CERT *    cert,
    int    bits
    )  ;
     

    Checks the status of a bit flag in a key usage extension from an X.509 certificate.

    Parameters:
    cert [In] The certificate containing key usage information.
    bits [In] A combination of the bits in Key Usage Extensions.
    Returns:
    The bit set result. One of:
  • 0 indicates the bit/s is not set or has a value of zero.
  • 1 indicates the bit/s has a value of one.
    • 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:
    ocsp_resp_vfy.c.

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