RSA BSAFE Micro Edition Suite

Streamlined security for mobile and embedded devices
Search  Print

Certificate Handling Functions

This section details the functions that manage certificate handling. These functions are used to create, manipulate, print and destroy an X.509v3 certificate object.

Defines

#define SSLCERT_dup
 Creates a duplicate of the given SSLCERT certificate and returns the duplicate. More...


Functions

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

void SSLCERT_free (SSLCERT *cert)
 Frees a certificate structure. More...

int SSLCERT_verify (SSLCERT *cert, SSLCERT_PKEY *pkey)
 Verifies that the signature of a certificate is correct by generating a hash of the certificate data and comparing it to the hash retrieved from the signature data using the Certification Authority's (CA) public key. More...

int SSLCERT_to_binary (SSLCERT *cert, unsigned char **pp)
 Generates Distinguished Encoding Rules (DER) encoded data from a certificate structure. More...

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

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

int SSLCERT_get_signature_type (SSLCERT *cert)
 Returns a numeric type for a certificate signature type.

int SSLCERT_get_signature_digest_type (SSLCERT *cert)
 Returns a numeric type for digest type of a certificate signature.

int SSLCERT_get_signature_data (SSLCERT *cert, unsigned long *len, unsigned char **data)
 Returns the Signature field as raw data. More...

int SSLCERT_get_version (SSLCERT *cert)
 Returns a numeric type for certificate version.

char * SSLCERT_get_version_string (SSLCERT *cert)
 Returns a string type for certificate version.

int SSLCERT_subject_name_cmp (SSLCERT *cert1, SSLCERT *cert2)
 Compares the subject names of a pair of certificates in order to sort them. More...

SSLCERT_NAME * SSLCERT_get_issuer_name (SSLCERT *cert)
 Returns the X.509 name of a certificate issuer. More...

SSLCERT_NAME * SSLCERT_get_subject_name (SSLCERT *cert)
 Returns the X.509 name of a certificate subject. More...

SSLCERT_PKEY * SSLCERT_get_pubkey (SSLCERT *cert)
 Returns the public key information of a certificate. More...

int SSLCERT_check_private_key (SSLCERT *cert, SSLCERT_PKEY *pkey)
 Checks that the certificate was signed with the private key. More...

SSLCERT_NAME * SSLCERT_NAME_new (void)
 Creates an X.509 name structure. More...

void SSLCERT_NAME_free (SSLCERT_NAME *xn)
 Removes all allocated memory for the SSLCERT_NAME structure xn including all SSLCERT_NAME_ENTRY structures contained in the SSLCERT_NAME structure. More...

SSLCERT_NAME * SSLCERT_NAME_dup (SSLCERT_NAME *xn)
 Duplicates the SSLCERT_NAME structure specified by xn. More...

unsigned long SSLCERT_NAME_hash (SSLCERT_NAME *xname)
 Generates a hash of the SSLCERT_NAME structure xname. More...

int SSLCERT_NAME_cmp (SSLCERT_NAME *xn1, SSLCERT_NAME *xn2)
 Compares a pair of X.509 name structures in order to sort them. More...

SSLCERT_NAME * SSLCERT_NAME_from_binary (SSLCERT_NAME **xn, unsigned char **pp, long length)
 Creates an SSLCERT_NAME structure from the specified binary ASN.1 encoded data. More...

int SSLCERT_NAME_to_binary (SSLCERT_NAME *xn, unsigned char **pp)
 Creates ASN.1 encoded binary data from the specified SSLCERT_NAME structure and places the binary output in pp. More...

char * SSLCERT_NAME_oneline (SSLCERT_NAME *xn, char *buf, int len)
 Returns string representation of SSLCERT_NAME xn. More...

int SSLCERT_NAME_get_entry_count (SSLCERT_NAME *xn)
 Returns the number of SSLCERT_NAME_ENTRY items in the SSLCERT_NAME structure xn. More...

SSLCERT_NAME_ENTRY * SSLCERT_NAME_get_entry (SSLCERT_NAME *xn, int loc)
 Returns the specified SSLCERT_NAME_ENTRY from the SSLCERT_NAME structure xn. More...

 SSLCERT_NAME_ENTRY_get_oid_info (SSLCERT_NAME_ENTRY *cne, unsigned int *oidtype, unsigned char **oidpp, long *oidlen)
 Returns the Object Identifier (OID) information of the specified SSLCERT_NAME_ENTRY structure. More...

 SSLCERT_NAME_ENTRY_get_data_info (SSLCERT_NAME_ENTRY *cne, unsigned int *datatype, unsigned char **datapp, long *datalen)
 Returns the data component for the specified SSLCERT_NAME_ENTRY structure. More...

SSLCERT_PKEY * SSLCERT_PKEY_new (void)
 Creates an SSLCERT asymmetric key structure. More...

void SSLCERT_PKEY_free (SSLCERT_PKEY *pkey)
 Frees an SSLCERT asymmetric key structure. More...

SSLCERT_PKEY * SSLCERT_PKEY_from_PUBKEY_binary (int type, SSLCERT_PKEY **ppkey, unsigned char **pp, long length)
 Creates an SSLCERT asymmetric key structure from ASN.1 encoded public key data. More...

void SSLCERT_PKEY_reference_inc (SSLCERT_PKEY *pkey)
 Increments the reference count of the SSLCERT asymmetric key structure. More...

SSLCERT_PKEY * SSLCERT_PKEY_from_binary (int type, SSLCERT_PKEY **pkey, unsigned char **pp, long length)
 Creates a new SSLCERT_PKEY structure from the private key component of the binary data specified by pkey. More...

SSLCERT_PKEY * SSLCERT_PKEY_to_binary (EVP_PKEY *ppkey, unsigned char **pp)
 Creates ASN.1 binary key data from the specified EVP_PKEY structure. More...

SSLCERT_PKEY * SSLCERT_PKEY_to_PUBKEY_binary (EVP_PKEY *ppkey, unsigned char **pp)
 Creates ASN.1 binary public key data from the specified EVP_PKEY structure. More...

int SSLCERT_get_serialNumber_info (SSLCERT *cert, unsigned int *type, unsigned char **pp, long *length)
 Returns the ASN.1 information for the certificate's serial number. More...

int SSLCERT_get_serialNumber_int (SSLCERT *cert, unsigned long *snump)
 Returns the serial number of the certificate as an integer. More...

int SSLCERT_get_notAfter (SSLCERT *cert, unsigned int *type, unsigned char **pp, long *length)
 Returns the ASN.1 data information about the NotAfter field of a certificate. More...

int SSLCERT_get_notBefore (SSLCERT *cert, unsigned int *type, unsigned char **pp, long *length)
 Returns the ASN.1 data information about the NotBefore field of a certificate. More...

int SSLCERT_NAME_get_info (SSLCERT_NAME *xn, unsigned char **pp, long *length)
 Returns the ASN.1 data from an X.509 name structure. More...

int SSLCERT_NAME_ENTRY_get_info (SSLCERT_NAME_ENTRY *cne, unsigned int *oidtype, unsigned char **oidpp, long *oidlen, unsigned int *datatype, unsigned char **datapp, long *datalen)
 Returns the Object Identifier (OID) and data information for an X.509 name entry. More...

int SSLCERT_get_TBSCertificate_data (SSLCERT *cert, unsigned long *len, unsigned char **data)
 Returns the TBSCertificate data. More...

int SSLCERT_get_validity_seconds (SSLCERT *cert, unsigned int id, unsigned long *pseconds)
 Returns the Certificate validity time in seconds. More...

int SSLCERT_get_basic_constraints_int (SSLCERT *cert, unsigned int *crit, unsigned long *constraints, int *is_ca)
 Returns the Basic Constraints value as an integer. More...

int SSLCERT_get_key_usage_int (SSLCERT *cert, unsigned int *crit, unsigned long *usage)
 Returns the Key Usage field as an integer. More...

int SSLCERT_get_crl_distribution_points (SSLCERT *cert, int index, int what, unsigned int *crit, unsigned long *len, unsigned char **data)
 Returns the CRL Distribution Points contents. More...

char* R_CDECL SSLCERT_OID_to_string (unsigned char *data, long len, int flag)
 Returns a string representation of a Distinguished Name (DN) Object Identifier (OID) value. More...

int R_CDECL SSLCERT_fingerprint (SSLCERT *cert, unsigned char *buf, unsigned int *plen)
 Returns the fingerprint of an X.509 certificate created using a digest function. More...

int R_CDECL SSLCERT_compare_ASN1_time (int time_encoding, unsigned char *cert_time, unsigned int now_time, int *result)
 Compares the ASN.1 time data information field of a certificate with the present time. More...

Define Documentation

#define SSLCERT_dup
 

Creates a duplicate of the given SSLCERT certificate and returns the duplicate.

Parameters:
a [In] The SSLCERT certificate to duplicate.

Function Documentation

int SSLCERT_check_private_key (  SSLCERT *    cert,
SSLCERT_PKEY *    pkey
)  ;
 

Checks that the certificate was signed with the private key.

Parameters:
cert [In] The certificate.
pkey [In] The SSLCERT_PKEY reference.
Returns:
1 indicates match.
0 indicates no match.
Samples:
rcert2sslcert.c, and sslcert2rcert.c.

int R_CDECL SSLCERT_compare_ASN1_time (  int    time_encoding,
unsigned char *    cert_time,
unsigned int    now_time,
int *    result
)  ;
 

Compares the ASN.1 time data information field of a certificate with the present time. The comparison is made after converting the current time value to an ASN.1 string. This function generates valid ASN.1 time strings for times between 1970 and 2069.

Parameters:
time_encoding [In] The type of the ASN.1 time data.
See ASN.1 Time Encoding Identifiers for valid values.
cert_time [In] The ASN.1 encoded time data from a certificate.
now_time [In] The present time to be compared with cert_time. This time is the number of seconds since January 1, 1970.
result [Out] 0 indicates cert_time equals now_time
1 indicates cert_time is greater.
-1 indicates cert_time is less than now_time.
Returns:
1 indicates success.
0 indicates now_time is not less than 2070 or if an unknown time encoding is requested.
See also:
SSLCERT_get_notBefore(), SSLCERT_get_notAfter() and R_time_to_int().
Samples:
verify_cb.c.

int R_CDECL SSLCERT_fingerprint (  SSLCERT *    cert,
unsigned char *    buf,
unsigned int *    plen
)  ;
 

Returns the fingerprint of an X.509 certificate created using a digest function.

Parameters:
cert [In] The reference to an X.509 certificate.
buf [Out] The buffer for the digest.
Should be EVP_MAX_MD_SIZE Bytes long.
plen [Out] The reference to the variable for the digest length. The amount of data copied into the buffer is returned in plen.
Returns:
1 indicates the fingerprint was calculated successfully.
0 indicates otherwise.

void SSLCERT_free (  SSLCERT *    cert )  ;
 

Frees a certificate structure.

Parameters:
cert [In] A reference to the certificate structure.
note.gif
cert must be a valid certificate reference.
Returns:
The current reference count. Certificate structure has been freed when reference count equals zero.
See also:
SSLCERT_new().
Samples:
bio_server.c, cache_server.c, nbio_server.c, p7ssl_server.c, rcert2sslcert.c, s_crl_check.c, s_crl_verify.c, sock_server.c, ssl_server.c, and sslcert2rcert.c.

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

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

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

int SSLCERT_get_basic_constraints_int (  SSLCERT *    cert,
unsigned int *    crit,
unsigned long *    constraints,
int *    is_ca
)  ;
 

Returns the Basic Constraints value as an integer.

Parameters:
cert [in] The X.509 certificate reference.
crit [out] Critical flag,
0: false or not there
constraints [out] Basic constraints integer
is_ca [out] Basic constraints CA field
note.gif
If the certificate does not contain the constraint size, the function will not update the field. This requires the user application to initialize the constraints integer to the maximum the application supports, so that it can use the given default value.
Returns:
1 for success.
otherwise indicates an error (data too long, no Basic Constraints found,..)
Samples:
verify_cb.c.

int SSLCERT_get_crl_distribution_points (  SSLCERT *    cert,
int    index,
int    what,
unsigned int *    crit,
unsigned long *    len,
unsigned char **    data
)  ;
 

Returns the CRL Distribution Points contents.

Parameters:
cert [In] The X.509 certificate reference.
index [In] Index number for cRLDistribution point
what [In] One of CRL Distribution Point Identifiers
crit [Out] Critical flag,
0: false or not there
len [Out] Length of returned data
data [Out] Read Only memory ptr
note.gif
The return place has to be preinitialized.
An index that does not return 1 means, that the certificate does not contain any more distribution points.
Returns:
1 for success.
otherwise indicates an error (no more DP, no DP founds, etc...)

SSLCERT_NAME * SSLCERT_get_issuer_name (  SSLCERT *    cert )  ;
 

Returns the X.509 name of a certificate issuer.

Parameters:
cert [In] The SSLCERT reference.
Returns:
The SSLCERT_NAME reference.
Example:

SSLCERT *cert;
SSLCERT_NAME *cert_name;

cert = SSLCERT_new();

/* Load certificate data */

/* Return the issuer name */
cert_name = SSLCERT_get_issuer_name(cert);
Samples:
rcert2sslcert.c, sslcert2rcert.c, and verify_cb.c.

int SSLCERT_get_key_usage_int (  SSLCERT *    cert,
unsigned int *    crit,
unsigned long *    usage
)  ;
 

Returns the Key Usage field as an integer.

Parameters:
cert [in] The X.509 certificate reference.
crit [out] Critical flag
0: false or not there
usage [out] Key Usage integer
Returns:
1 for success.
otherwise indicates an error. (data too long, no Key Usage not found,..)

int SSLCERT_get_notAfter (  SSLCERT *    cert,
unsigned int *    type,
unsigned char **    pp,
long *    length
)  ;
 

Returns the ASN.1 data information about the NotAfter field of a certificate.

Parameters:
cert [In] The certificate.
type [Out] The type of the NotAfter data. One of:
  • 23 represents ASN.1 UTC time.
  • 24 represents ASN.1 Generalized time.
    • pp [Out] The NotBefore data. This is the string of ASN.1 time data.
    length [Out] The length of the NotAfter data.
    Returns:
    1 indicates succcessful extraction of data from the certificate.
    0 indicates otherwise.
    note.gif
    type, pp, and length must all be valid variables.
    See also:
    SSLCERT_get_notBefore().
    Example:

    SSLCERT *cert;
unsigned int type;
unsigned char *data;
long len;
unsigned char *notAfter = NULL;
int asn1Encoding = 0;
int result=0,ret=0;
#ifndef SSLCME
R_TIME_T not_after;
#endif /* !SSLCME */

cert = SSLCERT_new();

/* Load certificate data, etc */

if (SSLCERT_get_notAfter(cert, &type, &data, &len))
{
    if ((notAfter = (unsigned char *)Malloc(len + 1)) == NULL)
    {
        printf("Unable to allocate memory for notAfter buffer\n");
    }

    if (Memcpy(notAfter, data, len) == NULL)
    {
        printf("Unable to copy notAfter time into memory buffer\n");
    }

    notAfter[len] = '\0';

    printf("Time asn1 string %s", notAfter);
    if (type == SSLCERT_ENCODING_ASN1_UTCTIME)
    {
        printf("UTC Time\n");
    }
    else
    {
        printf("Generalized Time\n");
    }

    asn1Encoding = type;
    ret = SSLCERT_compare_ASN1_time(asn1Encoding, &result,
                                     notAfter, now);
    if (ret == 1)
    {
        if (result == 1)
        {
            BIO_printf(bio_out, "Certificate notAfter date is Valid\n");
        }
        else
        {
            BIO_printf(bio_out, "Certificate is not valid.\n");
        }
    }
    else
    {
        BIO_printf(bio_err, "SSLCERT_compare_ASN1_time function failed\n");
    }

}
else
{
    printf("Failed to get the 'notAfter' date.\n");
}
    Samples:
    verify_cb.c.

    int SSLCERT_get_notBefore (  SSLCERT *    cert,
    unsigned int *    type,
    unsigned char **    pp,
    long *    length
    )  ;
     

    Returns the ASN.1 data information about the NotBefore field of a certificate.

    Parameters:
    cert [In] The X.509 certificate reference.
    type [Out] The ASN.1 type of the NotBefore data. One of:
  • 23 represents ASN1 UTC Time.
  • 24 represents ASN1 Generalized Time.
    • pp [Out] The NotBefore data. This is the string of ASN.1 time data.
    length [Out] The length of the NotBefore data.
    Returns:
    1 indicates succcessful extraction of data from the certificate.
    0 indicates otherwise.
    note.gif
    type, pp, and length must refer to valid variables.
    See also:
    SSLCERT_get_notAfter().
    Example:

    SSLCERT *cert;
unsigned int type;
unsigned char *data;
long len;
unsigned char *notBefore = NULL;
int asn1Encoding = 0;
int result=0,ret=0;
#ifndef SSLCME
R_TIME_T not_before;
#endif /* !SSLCME */

cert = SSLCERT_new();

/* Load certificate data, etc */

if (SSLCERT_get_notBefore(cert, &type, &data, &len))
{
    if ((notBefore = (unsigned char *)Malloc(len + 1)) == NULL)
    {
        printf("Unable to allocate memory for notBefore buffer\n");
    }

    if (Memcpy(notBefore, data, len) == NULL)
    {
        printf("Unable to copy notBefore time into memory buffer\n");
    }

    notBefore[len] = '\0';

    printf("Time asn1 string %s", notBefore);
    if (type == SSLCERT_ENCODING_ASN1_UTCTIME)
    {
        printf("UTC Time\n");
        asn1Encoding = SSLCERT_ENCODING_ASN1_UTCTIME;
    }
    else
    {
        printf("Generalized Time\n");
        asn1Encoding = SSLCERT_ENCODING_ASN1_GENERALIZEDTIME;
    }

    asn1Encoding = type;
    ret = SSLCERT_compare_ASN1_time(asn1Encoding, &result,
                                     notBefore, now);

    if (ret == 1)
    {
        if (result == -1)
        {
            BIO_printf(bio_out, "Certificate notBefore date is Valid\n");
        }
        else
        {
            BIO_printf(bio_out, "Certificate is not valid.\n");
        }
    }
    else
    {
        BIO_printf(bio_err, "SSLCERT_compare_ASN1_time function failed\n");
    }

}
else
{
    printf("Failed to get the 'notBefore' date.\n");
}
    Samples:
    verify_cb.c.

    SSLCERT_PKEY * SSLCERT_get_pubkey (  SSLCERT *    cert )  ;
     

    Returns the public key information of a certificate.

    Parameters:
    cert [In] The SSLCERT reference pointer.
    Returns:
    The SSLCERT_PKEY reference pointer.
    NULL indicates error.
    note.gif
    Users are not required to free the returned key as it is a reference pointer.
    See also:
    SSLCERT_verify().
    Samples:
    verify_cb.c.

    int SSLCERT_get_serialNumber_info (  SSLCERT *    cert,
    unsigned int *    type,
    unsigned char **    pp,
    long *    length
    )  ;
     

    Returns the ASN.1 information for the certificate's serial number.

    Parameters:
    cert [In] The certificate.
    type [Out] The serial number type.
    pp [Out] The serial number value.
    length [Out] The serial number length.
    Returns:
    1 indicates the information was successfully extracted.
    0 indicates otherwise.
    note.gif
    pp, type, and length must all dereference to valid variables.

    int SSLCERT_get_serialNumber_int (  SSLCERT *    cert,
    unsigned long *    snump
    )  ;
     

    Returns the serial number of the certificate as an integer.

    Parameters:
    cert [In] The certificate reference.
    snump [Out] The serial number as an integer.
    Returns:
    1 for success.
    otherwise indicates an error.

    int SSLCERT_get_signature_data (  SSLCERT *    cert,
    unsigned long *    len,
    unsigned char **    data
    )  ;
     

    Returns the Signature field as raw data.

    Parameters:
    cert [in] The X.509 certificate reference.
    len [out] Length of returned data
    data [out] Read Only memory ptr
    Returns:
    1 for success.
    otherwise indicates an error.
    note.gif
    The data pointer content is freed by the library. The application is required to copy the data if needed.

    SSLCERT_NAME * SSLCERT_get_subject_name (  SSLCERT *    cert )  ;
     

    Returns the X.509 name of a certificate subject.

    Parameters:
    cert [In] The SSLCERT reference.
    Returns:
    The SSLCERT_NAME reference.
    NULL indicates error.
    See also:
    SSLCERT_subject_name_cmp().
    Samples:
    rcert2sslcert.c, s_crl_verify.c, sslcert2rcert.c, and verify_cb.c.

    int SSLCERT_get_TBSCertificate_data (  SSLCERT *    cert,
    unsigned long *    len,
    unsigned char **    data
    )  ;
     

    Returns the TBSCertificate data.

    Parameters:
    cert [in] The X.509 certificate reference.
    len [out] Length of returned data.
    data [out] Read Only memory ptr.
    Returns:
    1 for success.
    otherwise indicates an error.
    note.gif
    The data pointer content is freed by the library. The application is not allowed to write into the fields. If required, application malloc and copy the returned data.

    int SSLCERT_get_validity_seconds (  SSLCERT *    cert,
    unsigned int    id,
    unsigned long *    pseconds
    )  ;
     

    Returns the Certificate validity time in seconds.

    Parameters:
    cert [in] The X.509 certificate reference.
    id [in] One of Certificate Validity Time Identifiers
    pseconds [out] Number of seconds since 1 Jan 1970.
    Returns:
    1 for success.
    otherwise indicates an error.

    int SSLCERT_NAME_cmp (  SSLCERT_NAME *    xn1,
    SSLCERT_NAME *    xn2
    )  ;
     

    Compares a pair of X.509 name structures in order to sort them.

    Parameters:
    xn1 [In] The SSLCERT_NAME reference.
    xn2 [In] The SSLCERT_NAME reference.
    Returns:
    <0 indicates that xn1 is smaller than xn2.
    0 indicates that xn1 is equal to xn2.
    >0 indicates that xn1 is greater than xn2.
    See also:
    SSLCERT_NAME_new().
    Samples:
    s_crl_verify.c, and verify_cb.c.

    SSLCERT_NAME * SSLCERT_NAME_dup (  SSLCERT_NAME *    xn )  ;
     

    Duplicates the SSLCERT_NAME structure specified by xn.

    Parameters:
    xn [In] The SSLCERT_NAME reference to duplicate.
    Returns:
    The duplicate SSLCERT_NAME reference.
    NULL indicates error.
    See also:
    SSLCERT_NAME_new(), SSLCERT_NAME_free().

    SSLCERT_NAME_ENTRY_get_data_info (  SSLCERT_NAME_ENTRY *    cne,
    unsigned int *    datatype,
    unsigned char **    datapp,
    long *    datalen
    )  ;
     

    Returns the data component for the specified SSLCERT_NAME_ENTRY structure.

    Parameters:
    cne [In] The SSLCERT_NAME_ENTRY reference.
    datatype [Out] The SSLCERT_NAME_ENTRY data type reference.
    datapp [Out] The reference to the pointer indicating the SSLCERT_NAME_ENTRY data.
    datalen [Out] The SSLCERT_NAME_ENTRY data length reference.
    Returns:
    1 indicates success.
    0 indicates error.
    See also:
    SSLCERT_NAME_ENTRY_get_info.

    int SSLCERT_NAME_ENTRY_get_info (  SSLCERT_NAME_ENTRY *    cne,
    unsigned int *    oidtype,
    unsigned char **    oidpp,
    long *    oidlen,
    unsigned int *    datatype,
    unsigned char **    datapp,
    long *    datalen
    )  ;
     

    Returns the Object Identifier (OID) and data information for an X.509 name entry.

    Parameters:
    cne [In] The X.509 name entry reference.
    Must be a valid reference to a name entry.
    oidtype [Out] The OID type of the name entry.
    oidpp [Out] The OID value of the name entry.
    Must be large enough to hold the values extracted from the name entry.
    oidlen [Out] The length of the OID value of the name entry.
    datatype [Out] The data type of the name entry .
    datapp [Out] The data value of the name entry.
    Must be large enough to hold the values extracted from the name entry.
    datalen [Out] The length of the data value of the name entry.
    Returns:
    1 indicates that the information was successfully extracted from the name entry structure.
    0 indicates otherwise.
    note.gif
    If any of the output parameters are valid references, return data is placed in the variables to which they refer.
    Example:

    SSLCERT_NAME_ENTRY *cne;
unsigned int oidtype;
unsigned char *oidpp;
long oidlen;
unsigned int datatype;
unsigned char *datapp;
long datalen;

/* cne = SSLCERT_NAME_get_entry(.....) */

if (SSLCERT_NAME_ENTRY_get_info(cne, &oidtype, &oidpp, &oidlen,
    &datatype, &datapp, &datalen) == 0 )
{
    fprintf(stderr,"error extracting information\n");
}

    SSLCERT_NAME_ENTRY_get_oid_info (  SSLCERT_NAME_ENTRY *    cne,
    unsigned int *    oidtype,
    unsigned char **    oidpp,
    long *    oidlen
    )  ;
     

    Returns the Object Identifier (OID) information of the specified SSLCERT_NAME_ENTRY structure. The OID information specifies the type, length and value of the OID components for the name entry.

    Parameters:
    cne [In] The SSLCERT_NAME_ENTRY pointer.
    oidtype [Out] The SSLCERT_NAME_ENTRY OID type reference.
    oidpp [Out] The reference to the pointer pointing to the OID.
    oidlen [Out] The SSLCERT_NAME_ENTRY object identifier length reference.
    Returns:
    1 indicates success.
    0 indicates an error.
    note.gif
    The type returned is a standard ASN.1 type value.
    See also:
    SSLCERT_NAME_ENTRY_get_info().

    void SSLCERT_NAME_free (  SSLCERT_NAME *    xn )  ;
     

    Removes all allocated memory for the SSLCERT_NAME structure xn including all SSLCERT_NAME_ENTRY structures contained in the SSLCERT_NAME structure.

    Parameters:
    xn [In] The SSLCERT_NAME reference.
    Samples:
    s_crl_verify.c, and verify_cb.c.

    SSLCERT_NAME * SSLCERT_NAME_from_binary (  SSLCERT_NAME **    xn,
    unsigned char **    pp,
    long    length
    )  ;
     

    Creates an SSLCERT_NAME structure from the specified binary ASN.1 encoded data.

    Parameters:
    xn [Out] The SSLCERT_NAME structure reference.
    If xn is NULL, an SSLCERT_NAME structure is allocated.
    pp [In] The binary data reference.
    length [In] The length of the data.
    Returns:
    A pointer to the SSLCERT_NAME structure containing encoded data.
    NULL indicates error.
    See also:
    SSLCERT_NAME_to_binary().
    Example:

    SSLCERT_NAME *cn;
unsigned char *pp;
long length;

cn = SSLCERT_NAME_new();

if (cn == NULL)
{
/* Error */
}

if (SSLCERT_from_binary(&cn, &pp, length == NULL))
{
/* Error condition - perform error processing */
}

/* Perform operations */

/* Free the structure */
SSLCERT_NAME_free(cn);
cn = NULL;
    Samples:
    s_crl_verify.c, and verify_cb.c.

    SSLCERT_NAME_ENTRY * SSLCERT_NAME_get_entry (  SSLCERT_NAME *    xn,
    int    loc
    )  ;
     

    Returns the specified SSLCERT_NAME_ENTRY from the SSLCERT_NAME structure xn. The location index loc indicates which entry to retrieve.

    Parameters:
    xn [In] The SSLCERT_NAME structure reference.
    loc [In] The index of the required SSLCERT_NAME_ENTRY.
    Returns:
    The SSLCERT_NAME_ENTRY pointer.
    NULL indicates error. For example, name is NULL, index is out of range, etc).
    See also:
    SSLCERT_NAME_get_entry_count().
    Example:

    SSLCERT_NAME *xn;
SSLCERT_NAME_ENTRY *xne;
int loc, count, i;

/* xn = SSLCERT_get_subject_name(...) */

/* Retrieve the number of name entries */
count = SSLCERT_NAME_get_entry_count(xn);

for (i=0; i<count; i++)
{
    /* Extract the name entry */
    xne = SSLCERT_NAME_get_entry(xn,i);

    /* Use the name entry */
}

    int SSLCERT_NAME_get_entry_count (  SSLCERT_NAME *    xn )  ;
     

    Returns the number of SSLCERT_NAME_ENTRY items in the SSLCERT_NAME structure xn.

    Parameters:
    xn [In] The SSLCERT_NAME structure reference.
    Returns:
    A number greater than 0 indicates the entry count.
    A number less than 0 indicates an error.
    See also:
    SSLCERT_NAME_get_entry().

    int SSLCERT_NAME_get_info (  SSLCERT_NAME *    xn,
    unsigned char **    pp,
    long *    length
    )  ;
     

    Returns the ASN.1 data from an X.509 name structure.

    Parameters:
    xn [In] The X.509 name reference.
    pp [Out] The name data.
    length [Out] The length of the name data.
    Returns:
    1 indicates that the information was successfully extracted from the name structure.
    0 indicates otherwise.
    note.gif
    pp and length must reference valid variables.

    unsigned long SSLCERT_NAME_hash (  SSLCERT_NAME *    xname )  ;
     

    Generates a hash of the SSLCERT_NAME structure xname.

    Parameters:
    xname [In] The SSLCERT reference.
    Returns:
    The SSLCERT_NAME structure hash.
    0 indicates error.

    SSLCERT_NAME * SSLCERT_NAME_new (  void    )  ;
     

    Creates an X.509 name structure.

    Returns:
    The SSLCERT_NAME reference.
    NULL indicates error.

    char * SSLCERT_NAME_oneline (  SSLCERT_NAME *    xn,
    char *    buf,
    int    len
    )  ;
     

    Returns string representation of SSLCERT_NAME xn.

    Parameters:
    xn [In] The SSLCERT_NAME reference.
    buf [Out] A string representation of SSLCERT_NAME. Memory is allocated if this parameter is NULL.
    len [In] The length of buf
    Returns:
    The string representation of SSLCERT_NAME.
    Samples:
    rcert2sslcert.c, s_crl_verify.c, sslcert2rcert.c, and verify_cb.c.

    int SSLCERT_NAME_to_binary (  SSLCERT_NAME *    xn,
    unsigned char **    pp
    )  ;
     

    Creates ASN.1 encoded binary data from the specified SSLCERT_NAME structure and places the binary output in pp.

    Parameters:
    xn [In] The SSLCERT_NAME reference.
    pp [Out] The address of the pointer to the buffer reference.
    pp will be updated to point to the last Byte written.
    If pp is NULL, the size of the SSLCERT_NAME data is returned.
    Returns:
    The number of Bytes of SSLCERT_NAME data.
    0 indicates error.
    See also:
    SSLCERT_NAME_from_binary().

    SSLCERT * SSLCERT_new (  void    )  ;
     

    Creates a new certificate structure.

    Returns:
    A reference to the SSLCERT structure.
    note.gif
    Memory allocated for the SSLCERT structure must be freed by the caller.
    See also:
    SSLCERT_new().

    char* R_CDECL SSLCERT_OID_to_string (  unsigned char *    data,
    long    len,
    int    flag
    )  ;
     

    Returns a string representation of a Distinguished Name (DN) Object Identifier (OID) value.

    Parameters:
    data [In] The OID value.
    len [In] The length of the OID value.
    flag [In] The flag to control the name type that is returned. One of:
  • 0 for a long name.
  • 1 for a short name.
    • Returns:
    The string representation of the OID value.
    note.gif
    This only handles a small set of OIDs and returns NULL for unrecognized OIDs.

    void SSLCERT_PKEY_free (  SSLCERT_PKEY *    pkey )  ;
     

    Frees an SSLCERT asymmetric key structure.

    Parameters:
    pkey [In] The SSLCERT_PKEY reference.
    See also:
    SSLCERT_PKEY_new() and SSLCERT_PKEY_reference_inc().
    Samples:
    bio_server.c, cache_server.c, evpkey2rpkey.c, nbio_server.c, p7ssl_server.c, rcert2sslcert.c, sock_server.c, ssl_server.c, sslcert2rcert.c, and verify_cb.c.

    SSLCERT_PKEY * SSLCERT_PKEY_from_binary (  int    type,
    SSLCERT_PKEY **    pkey,
    unsigned char **    pp,
    long    length
    )  ;
     

    Creates a new SSLCERT_PKEY structure from the private key component of the binary data specified by pkey.

    Parameters:
    type [In] The key type is EVP_PKEY_RSA.
    pkey [Out] The address of the SSLCERT_PKEY pointer.
    If pkey is NULL, SSLCERT_PKEY_from_binary() allocates SSLCERT_PKEY memory.
    pp [In] The address of the binary ASN.1 data pointer.
    pp is passed as an address of the position in the data stream so that it can be updated.
    length [In] The length of the data.
    Returns:
    The SSLCERT_PKEY reference to an existing or new SSLCERT_PKEY structure.
    NULL indicates error.
    See also:
    SSLCERT_PKEY_from_PUBKEY_binary().
    Samples:
    rcert2sslcert.c.

    SSLCERT_PKEY * SSLCERT_PKEY_from_PUBKEY_binary (  int    type,
    SSLCERT_PKEY **    ppkey,
    unsigned char **    pp,
    long    length
    )  ;
     

    Creates an SSLCERT asymmetric key structure from ASN.1 encoded public key data.

    Parameters:
    type [In] The key type is EVP_PKEY_RSA.
    ppkey [Out] The address of the SSLCERT_PKEY pointer.
    If ppkey is NULL, SSLCERT_PKEY_from_PUBKEY_binary() allocates SSLCERT_PKEY memory.
    pp [In] The address of the binary ASN.1 data pointer.
    The data pointer pp is passed as an address of the position in the data stream so that it can be updated.
    length [In] The length of the data.
    Returns:
    The SSLCERT_PKEY reference to an existing or new SSLCERT_PKEY structure.
    NULL indicates error.
    See also:
    SSLCERT_PKEY_from_binary().
    Samples:
    evpkey2rpkey.c, and verify_cb.c.

    SSLCERT_PKEY * SSLCERT_PKEY_new (  void    )  ;
     

    Creates an SSLCERT asymmetric key structure.

    Returns:
    The SSLCERT_PKEY reference.
    NULL indicates error.
    See also:
    SSLCERT_PKEY_free() and SSLCERT_PKEY_reference_inc().

    void SSLCERT_PKEY_reference_inc (  SSLCERT_PKEY *    pkey )  ;
     

    Increments the reference count of the SSLCERT asymmetric key structure.

    Parameters:
    pkey [In] The SSLCERT_PKEY reference.
    note.gif
    The reference count is decremented by SSLCERT_PKEY_free() so the actual memory allocation for the SSLCERT_PKEY structure will remain until the last reference is removed.
    See also:
    SSLCERT_PKEY_new() and SSLCERT_PKEY_free().

    SSLCERT_PKEY * SSLCERT_PKEY_to_binary (  EVP_PKEY *    ppkey,
    unsigned char **    pp
    )  ;
     

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

    Parameters:
    ppkey [In] The EVP_PKEY reference pointer.
    pp [Out] The address of the data buffer reference.
    Returns:
    >0 indicates the length of the key data.
    0 indicates the key is NULL.
    note.gif
    The buffer must be large enough to hold the data. If the buffer is not allocated, the function only returns the length of the certificate data.
    See also:
    SSLCERT_PKEY_to_PUBKEY_binary().
    Samples:
    evpkey2rpkey.c, and sslcert2rcert.c.

    SSLCERT_PKEY * SSLCERT_PKEY_to_PUBKEY_binary (  EVP_PKEY *    ppkey,
    unsigned char **    pp
    )  ;
     

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

    Parameters:
    ppkey [In] The EVP_PKEY reference pointer.
    pp [Out] The address of the data buffer reference.
    Returns:
    >0 indicates the length of the key data.
    0 indicates the key is NULL.
    note.gif
    The buffer must be large enough to hold the data. If the buffer is not allocated, the function only returns the length of the certificate data.
    See also:
    SSLCERT_PKEY_to_PUBKEY_binary().
    Samples:
    evpkey2rpkey.c.

    void SSLCERT_reference_inc (  SSLCERT *    cert )  ;
     

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

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

    int SSLCERT_subject_name_cmp (  SSLCERT *    cert1,
    SSLCERT *    cert2
    )  ;
     

    Compares the subject names of a pair of certificates in order to sort them.

    Parameters:
    cert1 [In] The SSLCERT reference.
    cert2 [In] The SSLCERT reference.
    Returns:
    A number less than 0 indicates that cert1 is less than cert2.
    0 indicates that cert1 is equal to cert2.
    A number greater than 0 indicates that cert1 is more than cert2.
    See also:
    SSLCERT_get_subject_name().
    Example:

    SSLCERT *cert1, *cert2;
int ret;

/* Allocate certificate structures */
cert1 = SSLCERT_new();
cert2 = SSLCERT_new();

/* Compare certificate subject names */
ret = SSLCERT_subject_name_cmp(cert1, cert2);
if (ret !=0)
{
    printf ("Certificate subject names differ\n");
}

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

    Generates Distinguished Encoding Rules (DER) encoded data from a certificate structure. The data is placed in pp which is subsequently updated to point to the end of the certificate data.

    Parameters:
    cert [In] The certificate.
    pp [Out] The buffer against which to hold the certificate digest.
    The buffer must be large enough to hold the data. If the buffer is not allocated, the function only returns the length of the certificate data.
    Returns:
    A number greater than 0 indicates the length of the certificate data.
    0 indicates that the certificate is NULL.
    See also:
    SSLCERT_from_binary().
    Example:

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

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

/* Load cert structure with data */

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

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

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

if ((pp-buf) != ret)
{
    /* An error has occurred*/
}
    Samples:
    sslcert2rcert.c.

    int SSLCERT_verify (  SSLCERT *    cert,
    SSLCERT_PKEY *    pkey
    )  ;
     

    Verifies that the signature of a certificate is correct by generating a hash of the certificate data and comparing it to the hash retrieved from the signature data using the Certification Authority's (CA) public key. The hash type is obtained from the certificate's signature algorithm.

    Parameters:
    cert [In] A reference to the certificate.
    pkey [In] The public key of the signing authority.
    Returns:
    1 indicates that the certificate's signature and the public key correspond.
    0 indicates otherwise.
    See also:
    SSLCERT_get_pubkey().
    Example:

        SSLCERT *issuer;
    SSLCERT *cert;
    EVP_PKEY *public_key;

    /* Get a reference to the public key of the issuer certificate */
    public_key = SSLCERT_get_pubkey(issuer);

    if (public_key == NULL)
    {
        BIO_printf(bio_err, "Errors during SSLCERT_get_pubkey\n");
        goto err;
    }

    ret = SSLCERT_verify(cert, pubkey);

    if (ret == 1)
    {
        BIO_printf(bio_err, "Certificate has been verified\n");
    }
    else
    {
        BIO_printf(bio_err, "Errors during SSLCERT_verify\n");
    }
    Samples:
    verify_cb.c.

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