RSA BSAFE Cert-C

Certificate Components for C

Crypto-C 6.2.1 Developer's Guide
Search

certlist.h File Reference

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

#include "basetype.h"
#include "bsafe.h"

Go to the source code of this file.

Data Structures

 LIST_OBJ_ENTRY_HANDLER
 Stores application-defined data. More...


Typedefs

typedef void(* VALUE_DESTRUCTOR )(POINTER value)
 Deletes a value. More...

typedef struct LIST_OBJ_ENTRY_HANDLER
 Stores application-defined data. More...


Functions

int C_CreateListObject (LIST_OBJ *listObject)
 Creates a new list object and saves the result in listObject. More...

int C_DeleteListObjectEntry (LIST_OBJ listObject, unsigned int entryIndex)
 Deletes the entry referenced by entryIndex in the listObject. More...

void C_DestroyListObject (LIST_OBJ *listObject)
 Frees all memory that listObject used, including all the entries in the listObject. More...

int C_GetListObjectEntry (LIST_OBJ listObject, unsigned int entryIndex, POINTER *entry)
 Retrieves the entry referenced by entryIndex of base zero in the listObject. More...

int C_GetListObjectCount (LIST_OBJ listObject, unsigned int *count)
 Retrieves the number of entries in listObject and returns it in entryCount. More...

void C_ResetListObject (LIST_OBJ listObject)
 Returns listObject to the state it was in after it was created by C_CreateListObject(). More...

int C_AddListObjectEntry (LIST_OBJ listObject, POINTER entry, unsigned int *entryIndex, LIST_OBJ_ENTRY_HANDLER *handler)
 Adds a new entry to listObject and returns the new entry's index in entryIndex. More...

int C_InsertListObjectEntry (LIST_OBJ listObject, POINTER entry, unsigned int entryIndex, LIST_OBJ_ENTRY_HANDLER *handler)
 Inserts an entry into listObject at the position entryIndex. More...

int C_AddCertToList (LIST_OBJ listObject, CERT_OBJ cert, unsigned int *entryIndex)
 Adds a copy of a certificate object to the specified list object. More...

int C_AddCertToListNoCopy (LIST_OBJ listObject, CERT_OBJ cert, unsigned int *entryIndex)
 Adds a certificate object reference to the specified list object. More...

int C_AddUniqueCertToList (LIST_OBJ listObject, CERT_OBJ cert, unsigned int *entryIndex)
 Adds a copy of a certificate object to the specified list object if it is not in the list. More...

int C_AddUniqueCertToListNoCopy (LIST_OBJ listObject, CERT_OBJ cert, unsigned int *entryIndex)
 Adds a copy of a certificate object reference to the specified list object if it is not in the list. More...

int C_InsertCertInList (LIST_OBJ listObject, CERT_OBJ cert, unsigned int entryIndex)
 Inserts a copy of a certificate object into the specified list object at the given position. More...

int C_InsertCertInListNoCopy (LIST_OBJ listObject, CERT_OBJ cert, unsigned int entryIndex)
 Inserts a copy of a certificate object reference into the specified list object at the given position. More...

int C_AddCRLToList (LIST_OBJ listObject, CRL_OBJ crl, unsigned int *entryIndex)
 Adds a copy of a CRL object to the specified list object. More...

int C_AddCRLToListNoCopy (LIST_OBJ listObject, CRL_OBJ crl, unsigned int *entryIndex)
 Adds a copy of a CRL object reference to the specified list object. More...

int C_AddUniqueCRLToList (LIST_OBJ listObject, CRL_OBJ crl, unsigned int *entryIndex)
 Adds a copy of a CRL object to the specified list object. More...

int C_AddUniqueCRLToListNoCopy (LIST_OBJ listObject, CRL_OBJ crl, unsigned int *entryIndex)
 Adds a copy of a CRL object reference to the specified list object. More...

int C_InsertCRLInList (LIST_OBJ listObject, CRL_OBJ crl, unsigned int entryIndex)
 Inserts a copy of a CRL object into the specified list object at the given position. More...

int C_InsertCRLInListNoCopy (LIST_OBJ listObject, CRL_OBJ crl, unsigned int entryIndex)
 Inserts a copy of a CRL object reference into the specified list object at the given position. More...

int C_AddPrivateKeyToList (LIST_OBJ listObject, B_KEY_OBJ privateKey, unsigned int *entryIndex)
 Adds a copy of a private key object to the specified list object. More...

int C_InsertPrivateKeyInList (LIST_OBJ listObject, B_KEY_OBJ privateKey, unsigned int entryIndex)
 Inserts a copy of a private key object into the specified list object at the given position. More...

int C_AddItemToList (LIST_OBJ listObject, ITEM *item, unsigned int *entryIndex)
 Adds a copy of an item to the specified list object. More...

int C_InsertItemInList (LIST_OBJ listObject, ITEM *item, unsigned int entryIndex)
 Inserts a copy of an item into the specified list object at the given position. More...

int C_AddUniqueItemToList (LIST_OBJ listObject, ITEM *item, unsigned int *entryIndex)
 Adds a copy of an ITEM to the specified list object if it is not on the list. More...


Typedef Documentation

typedef struct LIST_OBJ_ENTRY_HANDLER LIST_OBJ_ENTRY_HANDLER
 

Stores application-defined data. An application can use this structure to store any kind of application-defined data in a LIST_OBJ, even though Cert-C does not know the type of data structure the application requires. The application must set up the AllocAndCopy and Destructor callback functions to handle the type of data structure that it is using. These callback functions must recognize the type of data structure in value without being informed by the Cert-C function that passes the value to the callback. An application can use the AllocAndCopy feature to insert application-defined values into a list object.

typedef void(* VALUE_DESTRUCTOR)( POINTER value)
 

Deletes a value. Use the VALUE_DESTRUCTOR structure in EXTENSION_HANDLER and LIST_OBJ_ENTRY_HANDLER structures.

Parameters:
value A pointer to the value to delete.


Function Documentation

int C_AddCertToList LIST_OBJ    listObject,
CERT_OBJ    cert,
unsigned int *    entryIndex
;
 

Adds a copy of a certificate object to the specified list object. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of the certificate object. As an output parameter, it is the updated list.
cert [In] The certificate to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.
Samples:
certutil.c, chain.c, cmpku.c, cmprev.c, datamsg.c, kcscrs.c, kcsscep.c, ocsp.c, and scepreq.c.

int C_AddCertToListNoCopy LIST_OBJ    listObject,
CERT_OBJ    cert,
unsigned int *    entryIndex
;
 

Adds a certificate object reference to the specified list object. Duplicate list entries are permitted.

The difference between this function and C_AddCertToList() is that only a reference to the certificate is added to the list and not a true copy of the certificate. This greatly improves performance, but the certificate should not be modified outside of the list.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with the certificate object. As an output parameter, it is the updated list.
cert [In] The certificate to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddCRLToList LIST_OBJ    listObject,
CRL_OBJ    crl,
unsigned int *    entryIndex
;
 

Adds a copy of a CRL object to the specified list object. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of the CRL object. As an output parameter, it is the updated list.
crl [In] The CRL to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.
Samples:
crlutil.c, and datamsg.c.

int C_AddCRLToListNoCopy LIST_OBJ    listObject,
CRL_OBJ    crl,
unsigned int *    entryIndex
;
 

Adds a copy of a CRL object reference to the specified list object. Duplicate list entries are permitted.

The difference between this function and C_AddCRLToList() is that only a reference to the CRL is copied to the list and not a true copy of the CRL. This enhances performance, but the CRL should not be modified outside of the list.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with the CRL object. As an output parameter, it is the updated list.
crl [In] The CRL reference to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddItemToList LIST_OBJ    listObject,
ITEM *    item,
unsigned int *    entryIndex
;
 

Adds a copy of an item to the specified list object. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of the item structure. As an output parameter, it is the updated list.
item [In] The item to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.
Samples:
asn1.c, cmp.c, dhcert.c, kcsscep.c, keywrap.c, ocsp.c, p7stream.c, pkiutil.c, roleattrib.c, and sslcpvt.c.

int C_AddListObjectEntry LIST_OBJ    listObject,
POINTER    entry,
unsigned int *    entryIndex,
LIST_OBJ_ENTRY_HANDLER   handler
;
 

Adds a new entry to listObject and returns the new entry's index in entryIndex.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a new entry. As an output parameter, it is the updated list.
entry [In] The entry for the list object. The data for the new entry is given in entry. The C data structure for entry is a logical generic pointer type, although the actual C data structure supplied must match the type that the AllocAndCopy callback in handler expects. The AllocAndCopy callback is called to obtain a separate copy of entry, and then the copy is inserted into the listObject. When this entry is deleted, the Destructor callback provided in the handler is called to destroy the copy. The caller can modify entry and handler after this call.
entryIndex [Out] The list-entry index. If entryIndex is (unsigned int *)NULL_PTR, it is ignored.
handler [In] The handler for allocating and deleting a list entry. The Destructor and AllocAndCopy callbacks are contained in handler.
Returns:
0 indicates success.
See Errors for error information.
Samples:
p12util.c.

int C_AddPrivateKeyToList LIST_OBJ    listObject,
B_KEY_OBJ    privateKey,
unsigned int *    entryIndex
;
 

Adds a copy of a private key object to the specified list object. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of the private key object. As an output parameter, it is the updated list.
privateKey [In] The private key to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddUniqueCertToList LIST_OBJ    listObject,
CERT_OBJ    cert,
unsigned int *    entryIndex
;
 

Adds a copy of a certificate object to the specified list object if it is not in the list. If the certificate is already on the list, it does not add it again. Duplicate list entries (as determined by matching issuer names and serial numbers) are not permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of a certificate. As an output parameter, it is the updated list.
cert [In] The certificate to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddUniqueCertToListNoCopy LIST_OBJ    listObject,
CERT_OBJ    cert,
unsigned int *    entryIndex
;
 

Adds a copy of a certificate object reference to the specified list object if it is not in the list. If the certificate is already on the list, it does not add it again. Duplicate list entries (as determined by matching issuer names and serial numbers) are not permitted.

The difference between this function and C_AddUniqueCertToList() is that only a reference to the certificate is added to the list and not a true copy of the certificate. This greatly improves performance, but the certificate should not be modified outside of the list.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with the certificate object. As an output parameter, it is the updated list.
cert [In] The certificate to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddUniqueCRLToList LIST_OBJ    listObject,
CRL_OBJ    crl,
unsigned int *    entryIndex
;
 

Adds a copy of a CRL object to the specified list object. If the CRL to add is not in the list, this function adds it. If the CRL is already on the list, this function does not add it again. Duplicate list entries (which are determined by matching issuer names and last-update times) are not permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of a CRL. As an output parameter, it is the updated list.
crl [In] The CRL to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddUniqueCRLToListNoCopy LIST_OBJ    listObject,
CRL_OBJ    crl,
unsigned int *    entryIndex
;
 

Adds a copy of a CRL object reference to the specified list object. If the CRL to add is not in the list, this function adds it. If the CRL is already on the list, this function does not add it again. Duplicate list entries (which are determined by matching issuer names and last-update times) are not permitted.

The difference between this function and C_AddUniqueCRLToList() is that only a reference to the CRL is copied to the list and not a true copy of the CRL. This enhances performance, but the CRL should not be modified outside of the list.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with the CRL object. As an output parameter, it is the updated list.
crl [In] The CRL to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_AddUniqueItemToList LIST_OBJ    listObject,
ITEM *    item,
unsigned int *    entryIndex
;
 

Adds a copy of an ITEM to the specified list object if it is not on the list. If the ITEM is already on the list, it does not add it again. Duplicate list entries (which are determined by matching item lengths and data values) are not permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of an ITEM. As an output parameter, it is the updated list.
item [In] The item to add to the list object.
entryIndex [Out] The index of the newly added list entry.
Ignored if this parameter is NULL.
Returns:
0 indicates success.
See Errors for error information.

int C_CreateListObject LIST_OBJ   listObject ;
 

Creates a new list object and saves the result in listObject. If this function is unsuccessful, no memory is allocated and listObject is set to (LIST_OBJ)NULL_PTR.

Parameters:
listObject [Out] A pointer to the newly created list object.
Returns:
0 indicates success.
See Errors for error information.
Samples:
asn1.c, certsonly.c, chain.c, cmp.c, cmpku.c, cmprev.c, cms.c, datamsg.c, dbutil.c, dhcert.c, extract.c, kcscrs.c, kcsscep.c, keywrap.c, ldap.c, ldap2.c, mscapicert.c, ocsp.c, p12memio.c, p7stream.c, pkcs10.c, pkcs11db.c, pkcs11msg.c, pkcs12.c, pkcs12exp.c, pkiutil.c, roleattrib.c, rsadbcert.c, rsadbm.c, saltname.c, scepdb.c, scepreq.c, sslcpvt.c, validate.c, and verisign.c.

int C_DeleteListObjectEntry LIST_OBJ    listObject,
unsigned int    entryIndex
;
 

Deletes the entry referenced by entryIndex in the listObject. The indexes of all the entries after entryIndex are shifted back by one. Returns an error if the entry is not found.

Parameters:
listObject [In, Out] As an input parameter, it is the list object to be updated. As an output parameter, it is the updated list.
entryIndex [In] The index of the entry to be deleted.
Returns:
0 indicates success.
See Errors for error information.

void C_DestroyListObject LIST_OBJ   listObject ;
 

Frees all memory that listObject used, including all the entries in the listObject. Sets listObject to (LIST_OBJ)NULL_PTR. No action is taken if listObject is already (LIST_OBJ)NULL_PTR.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should destroy. As an output parameter, it is (LIST_OBJ)NULL_PTR.
Returns:
None.
Samples:
asn1.c, certsonly.c, chain.c, cmp.c, cmpku.c, cmprev.c, cms.c, datamsg.c, dbutil.c, dhcert.c, extract.c, kcscrs.c, kcsscep.c, keywrap.c, ldap.c, ldap2.c, mscapicert.c, ocsp.c, p12memio.c, p7stream.c, pkcs10.c, pkcs11db.c, pkcs11msg.c, pkcs12.c, pkcs12exp.c, pkiutil.c, roleattrib.c, rsadbcert.c, rsadbm.c, saltname.c, scepdb.c, scepreq.c, sslcpvt.c, validate.c, and verisign.c.

int C_GetListObjectCount LIST_OBJ    listObject,
unsigned int *    entryCount
;
 

Retrieves the number of entries in listObject and returns it in entryCount.

Parameters:
listObject [In] The list object.
entryCount [Out] The number of entries in the list object.
Returns:
0 indicates success.
See Errors for error information.
Samples:
certutil.c, crlutil.c, datamsg.c, dbutil.c, extract.c, ldap.c, ldap2.c, mscapicert.c, p12memio.c, pkcs10.c, pkcs11db.c, pkcs12.c, pkcs12exp.c, pkiutil.c, rsadbcert.c, rsadbm.c, scepreq.c, and validate.c.

int C_GetListObjectEntry LIST_OBJ    listObject,
unsigned int    entryIndex,
POINTER   entry
;
 

Retrieves the entry referenced by entryIndex of base zero in the listObject. If found, a pointer to the entry is saved in entry. Otherwise, an error is returned. The data structure for entry depends on the list object's type. This function is is intended to obtain a read-only entry. Do not attempt to perform any C_Set*() or C_Destroy*() functions on it. entry is undefined after listObject is modified or destroyed.

Parameters:
listObject [In] The list object.
entryIndex [In] The entry-list index.
entry [Out] The entry value.
Returns:
0 indicates success.
See Errors for error information.
Samples:
certutil.c, crlutil.c, datamsg.c, dbutil.c, dhcert.c, extract.c, keywrap.c, ldap.c, ldap2.c, mscapicert.c, p12memio.c, p7stream.c, pkcs10.c, pkcs11db.c, pkcs11msg.c, pkcs12.c, pkiutil.c, rsadbcert.c, rsadbm.c, saltname.c, scepreq.c, sslcpvt.c, and userextn.c.

int C_InsertCertInList LIST_OBJ    listObject,
CERT_OBJ    cert,
unsigned int    entryIndex
;
 

Inserts a copy of a certificate object into the specified list object at the given position. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of a certificate. As an output parameter, it is the updated list.
cert [In] The certificate to add to the list object.
entryIndex [In] The index of the position for the newly added list entry.
Returns:
0 indicates success.
See Errors for error information.

int C_InsertCertInListNoCopy LIST_OBJ    listObject,
CERT_OBJ    cert,
unsigned int    entryIndex
;
 

Inserts a copy of a certificate object reference into the specified list object at the given position. Duplicate list entries are permitted.

The difference between this function and C_InsertCertInList() is that only a reference to the certificate is inserted in the list and not a true copy of the certificate. This greatly improves performance, but the certificate should not be modified outside of the list.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with the certificate object. As an output parameter, it is the updated list.
cert [In] The certificate to add to the list object.
entryIndex [In] The index of the position for the newly added list entry.
Returns:
0 indicates success.
See Errors for error information.

int C_InsertCRLInList LIST_OBJ    listObject,
CRL_OBJ    crl,
unsigned int    entryIndex
;
 

Inserts a copy of a CRL object into the specified list object at the given position. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of the certificate object. As an output parameter, it is the updated list.
crl [In] The CRL to add to the list object.
entryIndex [In] The index of the position for the newly added list entry.
Returns:
0 indicates success.
See Errors for error information.

int C_InsertCRLInListNoCopy LIST_OBJ    listObject,
CRL_OBJ    crl,
unsigned int    entryIndex
;
 

Inserts a copy of a CRL object reference into the specified list object at the given position. Duplicate list entries are permitted.

The difference between this function and C_InsertCRLInList() is that only a reference to the CRL is copied to the list and not a true copy of the CRL. This enhances performance, but the CRL should not be modified outside of the list.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with the CRL object. As an output parameter, it is the updated list.
crl [In] The CRL to add to the list object.
entryIndex [In] The index of the position for the newly added list entry.
Returns:
0 indicates success.
See Errors for error information.

int C_InsertItemInList LIST_OBJ    listObject,
ITEM *    item,
unsigned int    entryIndex
;
 

Inserts a copy of an item into the specified list object at the given position. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of an item. As an output parameter, it is the updated list.
item [In] The item to add to the list object.
entryIndex [In] The index of the position for the newly added list entry.
Returns:
0 indicates success.
See Errors for error information.

int C_InsertListObjectEntry LIST_OBJ    listObject,
POINTER    entry,
unsigned int    entryIndex,
LIST_OBJ_ENTRY_HANDLER   handler
;
 

Inserts an entry into listObject at the position entryIndex.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of an entry. As an output parameter, it is the updated list.
entry [In] The entry to insert into the list object. The data for the new entry is given in entry. The C data structure for entry is a logical generic pointer type, though the actual C data structure supplied must match the type that the AllocAndCopy callback in handler expects. The AllocAndCopy callback is called to obtain a separate copy of entry. If the value of entryIndex is greater than the entries count in listObject, an error is returned. Otherwise, the copy is inserted into listObject at position entryIndex. When this entry is deleted, the Destructor callback provided in handler is called to destroy the copy. entry and handler can be modified by the caller after this call.
entryIndex [In] The list entry index. If the value of entryIndex is greater than the entries count in listObject, an error is returned.
handler [In] The handler for allocating and deleting a list entry. The AllocAndCopy and Destructor callbacks are contained in handler.
Returns:
0 indicates success.
See Errors for error information.

int C_InsertPrivateKeyInList LIST_OBJ    listObject,
B_KEY_OBJ    privateKey,
unsigned int    entryIndex
;
 

Inserts a copy of a private key object into the specified list object at the given position. Duplicate list entries are permitted.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should update with a copy of a private key. As an output parameter, it is the updated list.
privateKey [In] The private key to add to the list object.
entryIndex [In] The index of the position for the newly added list entry.
Returns:
0 indicates success.
See Errors for error information.

void C_ResetListObject LIST_OBJ    listObject ;
 

Returns listObject to the state it was in after it was created by C_CreateListObject(). It releases all the memory used by listObject.

Parameters:
listObject [In, Out] As an input parameter, it is the list object that Cert-C should reset. As an output parameter, it is the reset list object.
Samples:
datamsg.c, pkcs11msg.c, userextn.c, and validate.c.


Copyright (c) 1999-2005 RSA Security Inc. All rights reserved. 067-001001-2720-001-000 - 2.7.2