RSA Security logo

RSA BSAFE Cert-C
API Reference

certapi.h File Reference

This file defines the Cert-C certificate object API and data types.

#include "basetype.h"
#include "certext.h"
#include "certalg.h"

Go to the source code of this file.

Data Structures

 CERT_FIELDS
 Used to view and update information in an opaque CERT_OBJ object. More...


Typedefs

typedef CERT_FIELDS CERT_FIELDS
 Used to view and update information in an opaque CERT_OBJ object. More...


Functions

int C_CreateCertObject (CERT_OBJ *certObj, CERTC_CTX ctx)
 Stores a copy of ctx, the Cert-C context, in the resulting certObj. More...

int C_CreateCertObjectReference (CERTC_CTX ctx, CERT_OBJ certObj, CERT_OBJ *certObjRef)
 Creates a new reference to an existing certObj. More...

int C_SetCertFields (CERT_OBJ certObj, CERT_FIELDS *certFields)
 Sets the certObj to the value in certFields. More...

int C_GetCertDER (CERT_OBJ certObj, unsigned char **der, unsigned int *derLen)
 Obtains the DER encoding of the value of certObj. More...

int C_SetCertBER (CERT_OBJ certObj, unsigned char *ber, unsigned int berLen)
 Modifies the value of certObj to the BER-encoded certificate ber that has a length berLen. More...

int C_SetCertInnerBER (CERT_OBJ certObj, unsigned char *ber, unsigned int berLen)
 Modifies the value of certObj to the BER encoding of a certificate "to be signed" value given by the ber of length berLen. More...

int C_GetCertFields (CERT_OBJ certObj, CERT_FIELDS *certFields)
 Fills certFields with the value found in the CERT_FIELDS data structure in certObj. More...

int C_GetCertInnerDER (CERT_OBJ certObj, unsigned char **der, unsigned int *derLen)
 Obtains the DER encoding of the "to be signed" value of certObj, storing a pointer to the DER encoding in der and its length in derLen. More...

int C_ResetCertObject (CERT_OBJ certObj)
 Returns certObj to the state it was in after it was created by C_CreateCertObject(), freeing any memory that was held by the object. More...

void C_DestroyCertObject (CERT_OBJ *certObj)
 Frees the memory that certObj used and sets certObj to NULL_PTR. More...

int C_SignCert (CERT_OBJ certObj, B_KEY_OBJ privateKey,...)
 Signs a certificate using privateKey. More...

int C_VerifyCertSignature (CERT_OBJ certObj, B_KEY_OBJ publicKey,...)
 The Checks the signature of the certificate in certObj using the public key of the issuer, in publicKey. More...

Typedef Documentation

typedef struct CERT_FIELDS CERT_FIELDS
 

Used to view and update information in an opaque CERT_OBJ object. The application calls the C_GetCertFields() and C_SetCertFields() functions.

Parameters:
version A UINT2 value that indicates the certificate's version number. Cert-C recognizes the following three certificate version numbers:
Version Number Description
CERT_VERSION_1 1988 format (This is the default.)
CERT_VERSION_2 1992 format (Supports issuerUniqueId and subjectUniqueId fields.)
CERT_VERSION_3 1995 format (Supports issuerUniqueId, subjectUniqueId, and certExtensions fields.)


Cert-C returns an error if the value of version does not agree with other data in certFields. For example, if the version is CERT_VERSION_1 and there are some extensions in the certExtensions field, an error is returned.
serialNumber An ITEM structure that specifies the certificate's serial number. The data member points to the internal location of the serialNumber in the CERT_OBJ object.
  • serialNumber.data The serial number in canonical format, with the most significant byte first.
  • serialNumber.len The length of the serial number. A serialNumber.len of 0 (zero) implies that the serial number is 0 (zero).
signatureAlgorithm An int value that indicates the algorithm used to create the certificate signature. For an unsigned certificate, this algorithm is used to sign the certificate. Cert-C supports the following signature algorithm types:
Signature Algorithm Type Description
SA_MD2_WITH_RSA_ENCRYPTION Signature operations that involve the MD2 digest algorithm and the RSA public-key algorithm
SA_MD5_WITH_RSA_ENCRYPTION Signature operations that involve the MD5 digest algorithm and the RSA public-key algorithm
SA_SHA1_WITH_RSA_ENCRYPTION Signature operations that involve the SHA-1 digest algorithm and the RSA public-key algorithm
SA_OIW_SHA1_WITH_RSA_ENCRYPTION Signature operations that involve the SHA-1 digest algorithm, the OAEP masking according to OIW (OSI Implementers' Workshop) syntax, and the RSA public-key algorithm
SA_DSA_WITH_SHA1 SHA-1 digest algorithm and the Digital Signature Algorithm
issuerName A NAME_OBJ object that contains the name of the issuer that signed the certificate. For an unsigned certificate or self-signed certificate, the issuerName is the same as the subjectName.
validity This is a structure consisting of two parts: start and end. These represent the time at which a certificate becomes valid, and the time at which it ceases to be valid. The time is specified as the number of seconds since 12:00 AM GMT, January 1, 1970.
  • validity.start A UINT4 value that indicates the time at which a certificate becomes valid.
  • validity.end A UINT4 value that indicates the time at which a certificate ceases to be valid.
subjectName A NAME_OBJ object that contains the certificate's subject name.
publicKey An ITEM structure that points to the certificate's DER-encoded public key. The data member points to the internal location of the publicKey in the CERT_OBJ object. Note that Cert-C supports key sizes of up to 2048 bits.
issuerUniqueID A BIT_STRING structure that points to the certificate issuer's unique identification. The data member points to the internal location of the issuerUniqueID in the CERT_OBJ object. This field applies only to CERT_VERSION_2 and CERT_VERSION_3 certificates. When you call C_SetCertFields() for CERT_VERSION_1 certificates, set the data field of this BIT_STRING to NULL_PTR and the len and unusedBits fields to 0 (zero).
subjectUniqueID A BIT_STRING structure that points to the certificate subject's unique identification. The data member points to the internal location of the subjectUniqueID in the CERT_OBJ object. This field applies only to CERT_VERSION_2 and CERT_VERSION_3 certificates. When you call C_SetCertFields() for CERT_VERSION_1 certificates, set the data field of this BIT_STRING to NULL_PTR and the len and unusedBits fields to 0 (zero).
certExtensions An EXTENSIONS_OBJ object that contains X.509 v3 extensions for the certificate. This field applies only to CERT_VERSION_3 certificates. When you call C_SetCertFields() for CERT_VERSION_1 or CERT_VERSION_2 certificates, set this field to (EXTENSIONS_OBJ) NULL_PTR.
reserved Set this field to NULL_PTR; it is reserved for future use.

Function Documentation

int C_CreateCertObject (  CERT_OBJ *    certObj,
CERTC_CTX    ctx
)  ;
 

Stores a copy of ctx, the Cert-C context, in the resulting certObj. If C_CreateCertObject() is unsuccessful, no memory will be allocated and certObj will be set to (CERT_OBJ)NULL_PTR.

Parameters:
certObj This output parameter is a pointer to the location of the new certificate object.
ctx This input parameter is the Cert-C context.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_CreateCertObjectReference (  CERTC_CTX    ctx,
CERT_OBJ    certObj,
CERT_OBJ *    certObjRef
)  ;
 

Creates a new reference to an existing certObj. Many references to a certificate object can be created, and, just as with the original certObj, each reference must be destroyed using C_DestroyCertObject().

The reference can be treated exactly as any other certificate object, with one exception: modifying one reference to a certificate object modifies all references to that object.

Parameters:
ctx This input parameter is the Cert-C context.
certObj This input parameter is the certificate object from which a new reference will be created.
certObjRef This output parameter is a pointer to the location of the new certificate object reference.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyCertObject (  CERT_OBJ *    certObj )  ;
 

Frees the memory that certObj used and sets certObj to NULL_PTR. If certObj is already set to (CERT_OBJ)NULL_PTR, then no action is taken.

Parameters:
certObj This is both an input and an output parameter. As an input parameter, it is the certificate object that Cert-C should destroy. As an output parameter, it is (CERT_OBJ)NULL_PTR.
Returns:
None.

int C_GetCertDER (  CERT_OBJ    certObj,
unsigned char **    der,
unsigned int *    derLen
)  ;
 

Obtains the DER encoding of the value of certObj.

Note: The fields returned from this function are read-only. You do not have to create any objects or items before calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
certObj This input parameter is the certificate object.
der This output parameter is the DER-encoded certificate.
derLen This output parameter is the length of the DER-encoded certificate.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetCertFields (  CERT_OBJ    certObj,
CERT_FIELDS *    certFields
)  ;
 

Fills certFields with the value found in the CERT_FIELDS data structure in certObj.

Note: It is not necessary to create any objects or items before calling this function. After calling this function, you share the returned fields with the certObj. If you modify any of these fields, you must call the C_SetCertFields function to ensure that the internal state of the object is consistent with these modifications.

Parameters:
certObj This input parameter is the certificate object. For more information on this structure, click on the data type link above.
certFields This output parameter is the data structure for the certificate information. For more information on this structure, click on the data type link above.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_GetCertInnerDER (  CERT_OBJ    certObj,
unsigned char **    der,
unsigned int *    derLen
)  ;
 

Obtains the DER encoding of the "to be signed" value of certObj, storing a pointer to the DER encoding in der and its length in derLen. The "to be signed" part of the certificate is the inner value without the issuer's signature. The der is useful for calculating information such as the certificate digest for validation purposes, where it is not desired to include the signature.

Note: The fields returned from this function are read-only. It is not necessary to create any objects or items before calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields.

Parameters:
certObj This input parameter is the certificate object.
der This output parameter is the DER-encoded inner value.
derLen This output parameter is the length of the DER-encoded inner value.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_ResetCertObject (  CERT_OBJ    certObj )  ;
 

Returns certObj to the state it was in after it was created by C_CreateCertObject(), freeing any memory that was held by the object. Resetting the certificate object resets all Cert-C objects within it. Any non-object data within it is freed; for example, ITEM.data would be freed.

This function is a convenience function that removes the need to create and destroy instances of CERT_OBJ. It is useful for performance reasons.

Parameters:
certObj This is both an input and an output parameter. As an input parameter, it is the certificate object that Cert-C should reset. As an output parameter, it is the reset certificate object.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetCertBER (  CERT_OBJ    certObj,
unsigned char *    ber,
unsigned int    berLen
)  ;
 

Modifies the value of certObj to the BER-encoded certificate ber that has a length berLen. A separate copy of the BER-encoded certificate is allocated inside the certObj so that ber can be changed after calling this function. If the certificate includes X.509 v3 extensions, these extensions are parsed and checked against the extension handler (saved in the certObj). If the incoming extension's criticality is TRUE and it is registered as FALSE, the extension is saved with the criticality set to TRUE. However, if the incoming criticality is FALSE and it is registered as TRUE, an error is returned.

Parameters:
certObj This is both an input and output parameter; it is the certificate object.
ber This input parameter is the BER-encoded certificate.
berLen This input parameter is the length of the BER-encoded certificate.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetCertFields (  CERT_OBJ    certObj,
CERT_FIELDS *    certFields
)  ;
 

Sets the certObj to the value in certFields. The value in certFields can be the current working value of certObj, or of another certificate object. After calling this function, the value in certFields becomes the actual value of certObj. The data structure for certFields is CERT_FIELDS.

Parameters:
certObj This is both an input and output parameter; it is the certificate object. For more information on this structure, click on the data-type link above.
certFields This input parameter is the certification information data structure. For more information on this structure, click on the data-type link above.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SetCertInnerBER (  CERT_OBJ    certObj,
unsigned char *    ber,
unsigned int    berLen
)  ;
 

Modifies the value of certObj to the BER encoding of a certificate "to be signed" value given by the ber of length berLen. The "to be signed" part of the certificate is the inner value without the issuer signature. A separate copy of the BER encoding is allocated inside the certificate object so that ber can be changed after the call.

Parameters:
certObj This is both an input and an output parameter. As an input parameter, it is the certificate object that Cert-C should update. As an output parameter, it is the updated certificate object.
ber This input parameter is the BER-encoding of the certificate "to be signed" fields.
berLen This input parameter is the length of the BER-encoding of the certificate "to be signed" fields.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_SignCert (  CERT_OBJ    certObj,
B_KEY_OBJ    privateKey,
...   
)  ;
 

Signs a certificate using privateKey. C_SignCert() is defined in the certapi.h header file; in the header file, it contains extra variable parameters. Including these variable parameters makes this function backward-compatible with BCERT v1.

Parameters:
certObj This input parameter is the certificate to sign. To ensure that CERTC_CTX is available, use Cert-C rather than BCERT to create this object.
privateKey This input parameter is the private key used to sign the certificate.
Returns:
If successful, returns 0. If not, returns a Cert-C error code.

int C_VerifyCertSignature (  CERT_OBJ    certObj,
B_KEY_OBJ    publicKey,
...   
)  ;
 

The Checks the signature of the certificate in certObj using the public key of the issuer, in publicKey. C_VerifyCertSignature() is defined in the certapi.h header file; in the header file, it contains extra variable parameters. Including these variable parameters makes this function backward-compatible with BCERT v1.

Parameters:
certObj This input parameter is the certificate object that contains the signature to verify. To ensure that CERTC_CTX is available, use Cert-C rather than BCERT to create this object.
publicKey This input parameter is the issuer's public key used to verify the certificate signature.
Returns:
If successful, returns 0. If not, returns a Cert-C error code. If the certificate contains X.509 v3 extensions and there is an unknown critical extension, then the error E_UNKNOWN_CRITICAL_EXTENSION is returned.


RSA BSAFE® Cert-C 2.7 API Reference