	RSA BSAFE Cert-C	Certificate Components for C
		Crypto-C 6.2.1 Developer's Guide
		Search

certapi.h File Reference

This file contains 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 struct 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 applContext, 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 with 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 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 and stores a pointer to the DER encoding in innerDER and its length in innerDERLen. More...

int C_ResetCertObject (CERT_OBJ certObj)

Returns certObj to the state it was in after it was created by C_CreateCertObject(), and frees any memory that was held by the object. More...

void C_DestroyCertObject (CERT_OBJ *certObj)

Frees the memory used by certObj 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,...)

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 C_GetCertFields() and C_SetCertFields().

Function Documentation

int C_CreateCertObject ( CERT_OBJ * certObj,

CERTC_CTX applContext

) ;

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

certObj [Out] A pointer to the location of the new certificate object.

applContext [In] The Cert-C context.

Returns:
0 indicates success.
See Errors for error information.
Samples:
cert.c, certutil.c, cftest.c, chain.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, critical.c, crl.c, datamsg.c, imdbcert.c, kcscrs.c, kcsscep.c, ocsp.c, p12util.c, p7stream.c, pkcs10.c, pkcs11db.c, pkcs11msg.c, pkcs12exp.c, saltname.c, scepreq.c, validate.c, and verisign.c.

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, as with certObj, each reference must be destroyed via C_DestroyCertObject().
The reference can be treated exactly as any other certificate object, with one exception: modifying one reference to a certificate object modifies references to that object.
Parameters:

ctx [In] The Cert-C context.

certObj [In] The certificate object from which a new reference will be created.

certObjRef [Out] A pointer to the location of the new certificate object reference.

Returns:
0 indicates success.
See Errors for error information.

void C_DestroyCertObject ( CERT_OBJ * certObj ) ;

Frees the memory used by certObj and sets certObj to NULL_PTR. No action is taken if certObj is already set to (CERT_OBJ)NULL_PTR.
Parameters:

certObj [In, Out] 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.
Samples:
cert.c, certutil.c, cftest.c, chain.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, critical.c, crl.c, datamsg.c, dcrl.c, fulfill.c, imdbcert.c, kcscrs.c, kcsscep.c, ocsp.c, p12util.c, p7stream.c, pkcs10.c, pkcs11db.c, pkcs11msg.c, pkcs12exp.c, saltname.c, scepreq.c, validate.c, and verisign.c.

int C_GetCertDER ( CERT_OBJ certObj,

unsigned char ** certDER,

unsigned int * certDERLen

) ;

Obtains the DER encoding of the value of certObj.
Parameters:

certObj [In] The certificate object.

certDER [Out] The DER-encoded certificate.

certDERLen [Out] The length of the DER-encoded certificate.

Returns:
0 indicates success.
See Errors for error information.

This function returns read-only fields. You do not have to create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
cert.c, certutil.c, cmp.c, datamsg.c, extract.c, fulfill.c, kcscrs.c, kcsscep.c, p12memio.c, p7stream.c, pkcs11msg.c, pkcs12.c, pkiutil.c, and verisign.c.

int C_GetCertFields ( CERT_OBJ certObj,

CERT_FIELDS * certFields

) ;

Fills certFields with the value in the CERT_FIELDS data structure in certObj.
Parameters:

certObj [In] The certificate object. For more information on this structure, click on the data type link above.

certFields [Out] The data structure for the certificate information. For more information on this structure, click on the data type link above.

Returns:
0 indicates success.
See Errors for error information.

Do not create any objects or items before calling this function. The returned fields are shared with certObj. If you modify any of these fields, you must call C_SetCertFields() to ensure the internal state of the object is consistent with the changes.
Samples:
cert.c, certutil.c, cftest.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, crl.c, datamsg.c, dcrl.c, fulfill.c, kcscrs.c, kcsscep.c, keyutil.c, ldap.c, ldap2.c, mscapicert.c, myprint.c, p7stream.c, pkcs10.c, pkcs11msg.c, pkcs12exp.c, pkiutil.c, saltname.c, scepreq.c, and verisign.c.

int C_GetCertInnerDER ( CERT_OBJ certObj,

unsigned char ** innerDER,

unsigned int * innerDERLen

) ;

Obtains the DER encoding of the "to be signed" value of certObj and stores a pointer to the DER encoding in innerDER and its length in innerDERLen. The "to be signed" part of the certificate is the inner value without the issuer's signature. The innerDER is useful for calculating information such as the certificate digest for validation purposes, where the signature is not required.
Parameters:

certObj [In] The certificate object.

innerDER [Out] The DER-encoded inner value.

innerDERLen [Out] The length of the DER-encoded inner value.

Returns:
0 indicates success.
See Errors for error information.

This function returns read-only fields. Do not create any objects or items before calling this function. Do not call any functions, such as C_Destroy*(), that modify these fields.
Samples:
p7stream.c.

int C_ResetCertObject ( CERT_OBJ certObj ) ;

Returns certObj to the state it was in after it was created by C_CreateCertObject(), and frees 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, such as ITEM.data, is 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 [In, Out] 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:
0 indicates success.
See Errors for error information.

int C_SetCertBER ( CERT_OBJ certObj,

unsigned char * certBER,

unsigned int certBERLen

) ;

Modifies the value of certObj to the BER-encoded certificate ber with a length berLen. A separate copy of the BER-encoded certificate is allocated inside certObj so 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 [In, Out] The certificate object.

certBER [In] The BER-encoded certificate.

certBERLen [In] The length of the BER-encoded certificate.

Returns:
0 indicates success.
See Errors for error information.
Samples:
cert.c, certutil.c, cftest.c, chain.c, cmpku.c, cmpreq.c, cmprev.c, cms.c, critical.c, crl.c, datamsg.c, dcrl.c, imdbcert.c, kcscrs.c, kcsscep.c, ocsp.c, p7stream.c, pkcs10.c, pkcs11msg.c, saltname.c, scepreq.c, validate.c, and verisign.c.

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 [In, Out] The certificate object. For more information on this structure, click on the data-type link above.

certFields [In] The certification information data structure. For more information on this structure, click on the data-type link above.

Returns:
0 indicates success.
See Errors for error information.
Samples:
certutil.c, cftest.c, fulfill.c, pkcs10.c, and pkcs11db.c.

int C_SetCertInnerBER ( CERT_OBJ certObj,

unsigned char * innerBER,

unsigned int innerBERLen

) ;

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 [In, Out] As an input parameter, it is the certificate object that Cert-C should update. As an output parameter, it is the updated certificate object.

innerBER [In] The BER encoding of the certificate "to be signed" fields.

innerBERLen [In] The length of the BER encoding of the certificate "to be signed" fields.

Returns:
0 indicates success.
See Errors for error information.

int C_SignCert ( CERT_OBJ certObj,

B_KEY_OBJ privateKey,

...

) ;

Signs a certificate using privateKey.
Parameters:

certObj [In] The certificate to sign. To ensure that CERTC_CTX is available, use Cert-C rather than BCERT to create this object.

privateKey [In] The private key used to sign the certificate.

Returns:
0 indicates success.
See Errors for error information.

This function is defined in certapi.h, where it contains extra variable parameters. Including these variable parameters makes this function backward-compatible with BCERT v1.
Samples:
certutil.c, fulfill.c, pkcs10.c, and pkcs11db.c.

int C_VerifyCertSignature ( CERT_OBJ certObj,

B_KEY_OBJ publicKey,

...

) ;

Checks the signature of the certificate in certObj using the public key of the issuer, in publicKey.
Parameters:

certObj [In] 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 [In] The issuer's public key used to verify the certificate signature.

Returns:
0 indicates success.
See Errors for error information. If the certificate contains X.509 v3 extensions and there is an unknown critical extension, then the error E_UNKNOWN_CRITICAL_EXTENSION is returned.

This function is defined in certapi.h and contains extra variable parameters. Including these variable parameters makes this function backward-compatible with BCERT v1.
Samples:
cert.c, and fulfill.c.

Data Structures
	CERT_FIELDS
	Used to view and update information in an opaque `CERT_OBJ` object. More...
Typedefs
typedef struct	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 applContext, 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 with 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 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 and stores a pointer to the DER encoding in innerDER and its length in innerDERLen. More...
int	C_ResetCertObject (CERT_OBJ certObj)
	Returns certObj to the state it was in after it was created by C_CreateCertObject(), and frees any memory that was held by the object. More...
void	C_DestroyCertObject (CERT_OBJ *certObj)
	Frees the memory used by certObj 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,...)
	Checks the signature of the certificate in certObj using the public key of the issuer, in publicKey. More...