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

crlapi.h File Reference

This file contains Cert-C CRL object API and data types.

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

Go to the source code of this file.

Data Structures

CRL_ENTRY_INFO

Allows viewing and alteration of aspects of a CRL entry in a CRL_ENTRIES_OBJ object via C_GetCRLEntry() and C_AddCRLEntry(). More...

CRL_FIELDS

Allows viewing and updating of an opaque CRL_OBJ object via C_GetCRLFields() and C_SetCRLFields(). More...

Typedefs

typedef struct CRL_ENTRY_INFO

Allows viewing and alteration of aspects of a CRL entry in a CRL_ENTRIES_OBJ object via C_GetCRLEntry() and C_AddCRLEntry().

typedef struct CRL_FIELDS

Allows viewing and updating of an opaque CRL_OBJ object via C_GetCRLFields() and C_SetCRLFields().

Functions

int C_GetCRLEntriesCount (CRL_ENTRIES_OBJ crlEntriesObject, unsigned int *count)

Sets count to the number of revocation entries contained in crlEntriesObj, which is typically the crlEntries member of a CRL_FIELDS structure. More...

int C_GetCRLEntry (CRL_ENTRIES_OBJ crlEntriesObject, CRL_ENTRY_INFO *crlEntryInfo, unsigned int crlEntryIndex)

Gets the entry in the CRL list of crlEntriesObj at position index. More...

int C_AddCRLEntry (CRL_ENTRIES_OBJ crlEntriesObject, CRL_ENTRY_INFO *crlEntryInfo, unsigned int *index)

Adds a new CRL entry into the crlEntriesObject with the value given in crlEntryInfo. More...

int C_DeleteCRLEntry (CRL_ENTRIES_OBJ crlEntriesObject, unsigned int crlEntryIndex)

Deletes the entry in crlEntriesObj referenced by index. More...

int C_FindCRLEntryBySerialNumber (CRL_ENTRIES_OBJ crlEntriesObject, unsigned char *serialNumber, unsigned int serialNumberLen, unsigned int *crlEntryIndex)

Searches for the CRL entry list in crlEntriesObject for an entry with the given serialNumber. More...

void C_ResetCRLEntries (CRL_ENTRIES_OBJ crlEntriesObject)

Returns crlEntriesObj to the state it was in after it was created, by setting the number of entries to 0 (zero) and freeing any memory that was held by the object. More...

int C_CreateCRLObject (CRL_OBJ *crlObj, CERTC_CTX ctx)

Stores a copy of applContext, the Cert-C context, in the resulting crlObject. More...

int C_CreateCRLObjectReference (CERTC_CTX ctx, CRL_OBJ crlObj, CRL_OBJ *crlObjRef)

Creates a new reference to an existing crlObject. More...

void C_DestroyCRLObject (CRL_OBJ *crlObject)

Frees the memory used by crlObject, and sets crlObject to (CRL_OBJ)NULL_PTR. More...

int C_PrepareUnsignedCRLForIssuer (CRL_OBJ crlObject, NAME_OBJ issuerName)

Sets the CRL version in crlObject to CRL_VERSION_1, the issuer to issuerName, the signature algorithm to SA_MD2_WITH_RSA_ENCRYPTION, and the CRL_ENTRIES_OBJ to an empty list. More...

int C_SetCRLFields (CRL_OBJ crlObject, CRL_FIELDS *crlFields)

Sets crlObject with the value in crlFields. More...

int C_GetCRLFields (CRL_OBJ crlObject, CRL_FIELDS *crlFields)

Fills crlFields with the value found in crlObject. More...

int C_GetCRLDER (CRL_OBJ crlObject, unsigned char **der, unsigned int *derLen)

Obtains the DER encoding of the value of crlObject, and stores a pointer to the DER encoding in der and its length in derLen. More...

int C_SetCRLBER (CRL_OBJ crlObject, unsigned char *ber, unsigned int berLen)

Modifies the value of crlObject to the BER-encoded CRL given by crlBER and crlBERLen. More...

int C_GetCRLInnerDER (CRL_OBJ crlObject, unsigned char **innerDER, unsigned int *innerDERLen)

Obtains the DER encoding of the "to be signed" value of crlObject, and stores a pointer to the DER encoding in innerDER and its length in innerDERLen. More...

int C_SetCRLInnerBER (CRL_OBJ crlObject, unsigned char *innerBER, unsigned int innerBERLen)

Sets the value of crlObject to the BER encoding of a CRL's "to be signed" value given by innerBER, of length innerBERLen. More...

int C_SignCRL (CRL_OBJ crlObj, B_KEY_OBJ privateKey,...)

Signs a CRL using privateKey. More...

int C_VerifyCRLSignature (CRL_OBJ crlObj, B_KEY_OBJ publicKey,...)

Uses publicKey, the public key of the issuer, to check the signature of the CRL in crlObject. More...

Function Documentation

int C_AddCRLEntry ( CRL_ENTRIES_OBJ crlEntriesObject,

CRL_ENTRY_INFO * crlEntryInfo,

unsigned int * index

) ;

Adds a new CRL entry into the crlEntriesObject with the value given in crlEntryInfo. The data structure for crlEntryInfo is CRL_ENTRY_INFO.
Parameters:

crlEntriesObject [In, Out] The CRL entries object to be updated.

crlEntryInfo [In] A pointer to a CRL_ENTRY_INFO structure for the CRL entries information. Separate copies of the crlEntryExtensions and serialNumber (with leading zeroes stripped) are created internally for the crlEntriesObject, so that they can be changed after this call.

index [Out] The CRL entries index. Regardless of the CRL version, the index of the new entry is returned in index.
Ignored if this parameter is NULL.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crlutil.c.

int C_CreateCRLObject ( CRL_OBJ * crlObject,

CERTC_CTX applContext

) ;

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

crlObject [Out] A pointer to where the new CRL object is stored.

applContext [In] The Cert-C context.

Returns:
0 indicates success.
See Errors for error information.
Samples:
chain.c, crl.c, crlutil.c, datamsg.c, and p12util.c.

int C_CreateCRLObjectReference ( CERTC_CTX ctx,

CRL_OBJ crlObject,

CRL_OBJ * crlObjectRef

) ;

Creates a new reference to an existing crlObject. Many references to a CRL object can be created, and as with the original crlObject, each reference must be destroyed via C_DestroyCRLObject().
The reference can be treated exactly as any other CRL object, with one exception: modifying one reference to a CRL object modifies references to that object.
Parameters:

ctx [In] The Cert-C context.

crlObject [In] The CRL object from which a new reference will be created.

crlObjectRef [Out] A pointer to the location of the new CRL object reference.

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

int C_DeleteCRLEntry ( CRL_ENTRIES_OBJ crlEntriesObj,

unsigned int index

) ;

Deletes the entry in crlEntriesObj referenced by index. The entries after index are all shifted back by one. The crlEntriesObj is typically the crlEntries member of a CRL_FIELDS structure.
Parameters:

crlEntriesObj [In, Out] The CRL entries object.

index [In] The index of the CRL entry to delete.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c.

void C_DestroyCRLObject ( CRL_OBJ * crlObject ) ;

Frees the memory used by crlObject, and sets crlObject to (CRL_OBJ)NULL_PTR. If crlObject is already (CRL_OBJ)NULL_PTR, then no action is taken.
Parameters:

crlObject [In, Out] As an input parameter, it is the CRL object that Cert-C should destroy. As an output parameter, it is (CRL_OBJ)NULL_PTR.

Samples:
chain.c, crl.c, crlutil.c, datamsg.c, demo.c, and p12util.c.

int C_FindCRLEntryBySerialNumber ( CRL_ENTRIES_OBJ crlEntriesObject,

unsigned char * serialNumber,

unsigned int serialNumberLen,

unsigned int * entryIndex

) ;

Searches for the CRL entry list in crlEntriesObject for an entry with the given serialNumber. If an entry is found, its index in the list is returned in entryIndex. Otherwise, E_NOT_FOUND is returned.
Parameters:

crlEntriesObject [In] The CRL entries object.

serialNumber [In] The certificate's serial number.

serialNumberLen [In] The length of the certificate's serial number.

entryIndex [Out] A pointer to the CRL entries index result.
Ignored if this parameter is NULL.

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

int C_GetCRLDER ( CRL_OBJ crlObject,

unsigned char ** der,

unsigned int * derLen

) ;

Obtains the DER encoding of the value of crlObject, and stores a pointer to the DER encoding in der and its length in derLen.
Parameters:

crlObject [In] The CRL object.

der [Out] The DER-encoded CRL.

derLen [Out] The length of the DER-encoded CRL.

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:
crl.c, crlutil.c, datamsg.c, extract.c, p12memio.c, and pkcs12.c.

int C_GetCRLEntriesCount ( CRL_ENTRIES_OBJ crlEntriesObj,

unsigned int * count

) ;

Sets count to the number of revocation entries contained in crlEntriesObj, which is typically the crlEntries member of a CRL_FIELDS structure.
Parameters:

crlEntriesObj [In] The CRL entries object.

count [Out] The number of entries in the CRL entries object.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c, and crlutil.c.

int C_GetCRLEntry ( CRL_ENTRIES_OBJ crlEntriesObj,

CRL_ENTRY_INFO * crlEntryInfo,

unsigned int index

) ;

Gets the entry in the CRL list of crlEntriesObj at position index. The data structure for crlEntryInfo is CRL_ENTRY_INFO.
Parameters:

crlEntriesObj [In] The CRL entries object.

crlEntryInfo [Out] A pointer to a data structure that contains information about a CRL entry. The serialNumber.data and serialNumber.len fields are set to the entries serial number and its length. The serial number returned by C_GetCRLEntry() has no leading zeroes. A crlEntryInfo.serialNumber.len of 0 (zero) implies that the serial number is 0 (zero). The actionTime field is set to the action time of the entry, measured in the number of seconds since 12:00 A.M. GMT, January 1, 1970. The crlEntryExtensions field is set to the extensions object in the entry, if one exists. Otherwise, it is set to (EXTENSIONS_OBJ)NULL_PTR.

index [In] The CRL entries index.

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:
crl.c, and crlutil.c.

int C_GetCRLFields ( CRL_OBJ crlObject,

CRL_FIELDS * crlFields

) ;

Fills crlFields with the value found in crlObject. The data structure for crlFields is CRL_FIELDS.
Parameters:

crlObject [In] The CRL object.

crlFields [In, Out] The data structure for the CRL information. The version field indicates the CRL is either CRL_VERSION_1 or CRL_VERSION_2. The signatureAlgorithm field contains one of the following types:

Signature Algorithm Type Description

SA_MD2_WITH_RSA_ENCRYPTION Signature operations that involve the MD2 digest algorithm and RSA public key algorithm

SA_MD5_WITH_RSA_ENCRYPTION Signature operations that involve the MD5 digest algorithm and RSA public key algorithm

SA_SHA1_WITH_RSA_ENCRYPTION Signature operations that involve the SHA-1 digest algorithm and 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 RSA public key algorithm

SA_DSA_WITH_SHA1 Signature operations that involve the SHA-1 and DSA

The issuerName name object specifies the CRL's issuer. The lastUpdate and nextUpdate values specify the CRL's validity period. The time values are measured in seconds since 12:00 A.M. GMT, January 1, 1970. The crlEntries field gives access to the CRL. Its data can be obtained with the CRL entries functions. extensionsObject gives all the CRL extensions that have been added. The NAME_OBJ, CRL_ENTRIES_OBJECT, and EXTENSIONS_OBJ do not need to be created before this call.

After this call, the issuerName, crlEntries and extensionsObject fields point to the issuer name object, the CRL entries object, and the extensions object in the crlObject, respectively. Treat these objects as read-only fields. Do not call any functions that manipulate or modify the crlObj fields, because you will not be changing the actual values within crlObj itself. Do not attempt to call any C_Destroy*() functions on these objects, because if crlObj is destroyed, the objects are undefined. To change the crlObj fields, you must create new field structures and call C_SetCrlFields().
Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c, crlutil.c, and dcrl.c.

int C_GetCRLInnerDER ( CRL_OBJ crlObject,

unsigned char ** innerDER,

unsigned int * innerDERLen

) ;

Obtains the DER encoding of the "to be signed" value of crlObject, and stores a pointer to the DER encoding in innerDER and its length in innerDERLen. The "to be signed" part of the CRL is the inner value without the issuer's signature.
Parameters:

crlObject [In] The CRL object.

innerDER [Out] The DER-encoded inner CRL.

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

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:
crl.c.

int C_PrepareUnsignedCRLForIssuer ( CRL_OBJ crlObject,

NAME_OBJ issuerName

) ;

Sets the CRL version in crlObject to CRL_VERSION_1, the issuer to issuerName, the signature algorithm to SA_MD2_WITH_RSA_ENCRYPTION, and the CRL_ENTRIES_OBJ to an empty list. The last-update and next-update times are set to 0 (zero), which represents 12:00 A.M. GMT, January 1, 1970.
Parameters:

crlObject [In, Out] The CRL object.

issuerName [In] The CRL issuer name.

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

void C_ResetCRLEntries ( CRL_ENTRIES_OBJ crlEntriesObj ) ;

Returns crlEntriesObj to the state it was in after it was created, by setting the number of entries to 0 (zero) and freeing any memory that was held by the object. crlEntriesObj is typically the crlEntries member of a CRL_FIELDS structure.
Parameters:

crlEntriesObj [In, Out] As an input parameter, it is the CRL entries object that Cert-C should reset. As an output parameter, it is the reset CRL entries object.

int C_SetCRLBER ( CRL_OBJ crlObject,

unsigned char * crlBER,

unsigned int crlBERLen

) ;

Modifies the value of crlObject to the BER-encoded CRL given by crlBER and crlBERLen. A separate copy of the BER-encoded CRL is allocated inside the CRL object so that crlBER can be changed after calling this function. If crlBER includes X.509 v3 extensions, these extensions are parsed and checked against the registered and supported standard extensions.
If the incoming extension's criticality is TRUE and it is registered as FALSE in the extension handler table, the extension is saved with the criticality set to TRUE. However, if the incoming criticality is FALSE and the registered value is TRUE, an error is returned.
Parameters:

crlObject [In, Out] As an input parameter, it is the CRL object that Cert-C should update. As an output parameter, it is the updated CRL object.

crlBER [In] The BER-encoded CRL.

crlBERLen [In] The length of the BER-encoded CRL.

Returns:
0 indicates success.
See Errors for error information.
Samples:
chain.c, crl.c, crlutil.c, and datamsg.c.

int C_SetCRLFields ( CRL_OBJ crlObject,

CRL_FIELDS * crlFields

) ;

Sets crlObject with the value in crlFields. This value may be the current working value of crlObject, or another CRL object. After calling this function, the value in crlFields becomes the actual value of crlObject. The data structure for crlFields is CRL_FIELDS.
Parameters:

crlObject [In, Out] The CRL object.

crlFields [In] A pointer to a CRL_FIELDS data structure for the CRL information. The version field of CRL_FIELDS can be either CRL_VERSION_1 or CRL_VERSION_2. If the value of version does not agree with other data in CRL_FIELDS, then Cert-C modifies the version to agree with the other data in CRL_FIELDS. For example, if there are extensions in the crlExtensions field, the version will be set to CRL_VERSION_2. The signatureAlgorithm field of CRL_FIELDS must be one of the following:

SA_MD_WITH_RSA_ENCRYPTION
SA_MD5_WITH_RSA_ENCRYPTION
SA_SHA1_WITH_RSA_ENCRYPTION
SA_OIW_SHA1_WITH_RSA_ENCRYPTION
SA_DSA_WITH_SHA1. The issuerName object specifies the name of the issuer of the CRL. If any fields in CRL_FIELDS are different from the fields returned by C_GetCRLFields(), then this function makes a separate copy of those fields. The lastUpdate and nextUpdate values specify the CRL's validity period. The time values are measured in seconds since 12:00 A.M. GMT, January 1, 1970. If lastUpdate is later than nextUpdate, an error is returned.

The crlEntries object supplies the certificate revocation entries. It is usually the same object that is returned by C_GetCRLEntries(). If crlEntries is (CRL_ENTRIES_OBJ)NULL_PTR, this indicates that there are no revocation entries. The extensionsObject supplies all the CRL extensions that were added.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c, crlutil.c, and dcrl.c.

int C_SetCRLInnerBER ( CRL_OBJ crlObject,

unsigned char * innerBER,

unsigned int innerBERLen

) ;

Sets the value of crlObject to the BER encoding of a CRL's "to be signed" value given by innerBER, of length innerBERLen. The "to be signed" part of the CRL is the inner value without the issuer signature. A separate copy of the BER encoding is allocated inside the CRL object so that innerBER can be changed after calling this function.
If the inner CRL includes X.509 v3 extensions, these extensions are parsed and saved in crlObject. If the incoming extension 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 the registered value is TRUE, an error is returned.
Parameters:

crlObject [In, Out] The CRL object.

innerBER [In] The BER-encoded inner CRL.

innerBERLen [In] The length of the BER-encoded inner CRL.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c.

int C_SignCRL ( CRL_OBJ crlObject,

B_KEY_OBJ privateKey,

...

) ;

Signs a CRL using privateKey. This function contains extra variable parameters that make it backward-compatible with BCERT v1.
Parameters:

crlObject [In] The CRL 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 CRL.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c, crlutil.c, and dcrl.c.

int C_VerifyCRLSignature ( CRL_OBJ crlObject,

B_KEY_OBJ publicKey,

...

) ;

Uses publicKey, the public key of the issuer, to check the signature of the CRL in crlObject. This function contains extra variable parameters that make it backward-compatible with BCERT v1.
Parameters:

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

publicKey [In] The CRL issuer's public key that is used to verify the CRL signature.

Returns:
0 indicates success.
See Errors for error information.
Samples:
crl.c.

Data Structures
	CRL_ENTRY_INFO
	Allows viewing and alteration of aspects of a CRL entry in a CRL_ENTRIES_OBJ object via C_GetCRLEntry() and C_AddCRLEntry(). More...
	CRL_FIELDS
	Allows viewing and updating of an opaque `CRL_OBJ` object via C_GetCRLFields() and C_SetCRLFields(). More...
Typedefs
typedef struct	CRL_ENTRY_INFO
	Allows viewing and alteration of aspects of a CRL entry in a CRL_ENTRIES_OBJ object via C_GetCRLEntry() and C_AddCRLEntry().
typedef struct	CRL_FIELDS
	Allows viewing and updating of an opaque `CRL_OBJ` object via C_GetCRLFields() and C_SetCRLFields().
Functions
int	C_GetCRLEntriesCount (CRL_ENTRIES_OBJ crlEntriesObject, unsigned int *count)
	Sets count to the number of revocation entries contained in crlEntriesObj, which is typically the `crlEntries` member of a `CRL_FIELDS` structure. More...
int	C_GetCRLEntry (CRL_ENTRIES_OBJ crlEntriesObject, CRL_ENTRY_INFO *crlEntryInfo, unsigned int crlEntryIndex)
	Gets the entry in the CRL list of crlEntriesObj at position index. More...
int	C_AddCRLEntry (CRL_ENTRIES_OBJ crlEntriesObject, CRL_ENTRY_INFO crlEntryInfo, unsigned int index)
	Adds a new CRL entry into the crlEntriesObject with the value given in crlEntryInfo. More...
int	C_DeleteCRLEntry (CRL_ENTRIES_OBJ crlEntriesObject, unsigned int crlEntryIndex)
	Deletes the entry in crlEntriesObj referenced by index. More...
int	C_FindCRLEntryBySerialNumber (CRL_ENTRIES_OBJ crlEntriesObject, unsigned char serialNumber, unsigned int serialNumberLen, unsigned int crlEntryIndex)
	Searches for the CRL entry list in crlEntriesObject for an entry with the given serialNumber. More...
void	C_ResetCRLEntries (CRL_ENTRIES_OBJ crlEntriesObject)
	Returns crlEntriesObj to the state it was in after it was created, by setting the number of entries to `0` (zero) and freeing any memory that was held by the object. More...
int	C_CreateCRLObject (CRL_OBJ *crlObj, CERTC_CTX ctx)
	Stores a copy of applContext, the Cert-C context, in the resulting crlObject. More...
int	C_CreateCRLObjectReference (CERTC_CTX ctx, CRL_OBJ crlObj, CRL_OBJ *crlObjRef)
	Creates a new reference to an existing crlObject. More...
void	C_DestroyCRLObject (CRL_OBJ *crlObject)
	Frees the memory used by crlObject, and sets crlObject to `(CRL_OBJ)NULL_PTR`. More...
int	C_PrepareUnsignedCRLForIssuer (CRL_OBJ crlObject, NAME_OBJ issuerName)
	Sets the CRL version in crlObject to `CRL_VERSION_1`, the issuer to issuerName, the signature algorithm to `SA_MD2_WITH_RSA_ENCRYPTION`, and the `CRL_ENTRIES_OBJ` to an empty list. More...
int	C_SetCRLFields (CRL_OBJ crlObject, CRL_FIELDS *crlFields)
	Sets crlObject with the value in crlFields. More...
int	C_GetCRLFields (CRL_OBJ crlObject, CRL_FIELDS *crlFields)
	Fills crlFields with the value found in crlObject. More...
int	C_GetCRLDER (CRL_OBJ crlObject, unsigned char *der, unsigned int derLen)
	Obtains the DER encoding of the value of crlObject, and stores a pointer to the DER encoding in der and its length in derLen. More...
int	C_SetCRLBER (CRL_OBJ crlObject, unsigned char *ber, unsigned int berLen)
	Modifies the value of crlObject to the BER-encoded CRL given by crlBER and crlBERLen. More...
int	C_GetCRLInnerDER (CRL_OBJ crlObject, unsigned char *innerDER, unsigned int innerDERLen)
	Obtains the DER encoding of the "to be signed" value of crlObject, and stores a pointer to the DER encoding in innerDER and its length in innerDERLen. More...
int	C_SetCRLInnerBER (CRL_OBJ crlObject, unsigned char *innerBER, unsigned int innerBERLen)
	Sets the value of crlObject to the BER encoding of a CRL's "to be signed" value given by innerBER, of length innerBERLen. More...
int	C_SignCRL (CRL_OBJ crlObj, B_KEY_OBJ privateKey,...)
	Signs a CRL using privateKey. More...
int	C_VerifyCRLSignature (CRL_OBJ crlObj, B_KEY_OBJ publicKey,...)
	Uses publicKey, the public key of the issuer, to check the signature of the CRL in crlObject. More...