RSA BSAFE Cert-C API Reference

certlist.h File Reference

This file defines 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 LIST_OBJ_ENTRY_HANDLER	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)
	Gets the entry referenced by entryIndex of base zero in the listObject. More...
int	C_GetListObjectCount (LIST_OBJ listObject, unsigned int *count)
	Gets the number of entries in listObject and returns it in count. 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. 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. 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. More...

---

Typedef Documentation

typedef struct LIST_OBJ_ENTRY_HANDLER LIST_OBJ_ENTRY_HANDLER

Stores application-defined data. An application can use the LIST_OBJ_ENTRY_HANDLER 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. Parameters: AllocAndCopy Allocates and copies the information given in value, then sets the pointer to the duplication in newValue. A successful operation returns zero 0; a failed operation returns the E_ALLOC error. If data is not valid, then no memory is allocated and the E_DATA error should be returned. This function is used by C_AddListObjectEntry() and C_InsertListObjectEntry() to add list object values into an existing list. newValue This is an output field containing the new copy of value that is returned by the AllocAndCopy function. value This is an input field containing list-object entry information that is used by the AllocAndCopy function. Destructor Deallocates the value that was allocated by the AllocAndCopy callback, freeing all memory associated with it. If value is (POINTER)NULL_PTR, then Destructor performs no operation. Destructor is used with the C_DestroyListObject() and C_DeleteListObjectEntry() functions when a list-object value is deleted from an extension.

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 This is both an input and an output parameter. 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 This input parameter is the certificate to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the certificate to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the CRL to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 greatly enhances performance, but the CRL should not be modified outside of the list. Parameters: listObject This is both an input and an output parameter. 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 This input parameter is the CRL reference to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the item to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is 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 This output parameter is the list-entry index. If entryIndex is (unsigned int *)NULL_PTR, it is ignored. handler This input parameter is the handler for allocating and deleting a list entry. The Destructor and AllocAndCopy callbacks are contained in handler. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the private key to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 the certificate to add is not in the list, this function adds it. If the certificate is already on the list, this function does not add it again. Duplicate list entries (as determined by matching issuer names and serial numbers) are not permitted. Parameters: listObject This is both an input and an output parameter. 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 This input parameter is the certificate to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 the certificate to add is not in the list, this function adds it. If the certificate is already on the list, this function 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 This is both an input and an output parameter. 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 This input parameter is the certificate to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the CRL to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 greatly enhances performance, but the CRL should not be modified outside of the list. Parameters: listObject This is both an input and an output parameter. 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 This input parameter is the CRL to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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

Adds a copy of an ITEM to the specified list object. If the ITEM to add is not in the list, this function adds it. If the ITEM is already on the list, this function does not add it again. Duplicate list entries (which are determined by matching item lengths and data values) are not permitted. Parameters: listObject This is both an input and an output parameter. 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 This input parameter is the item to add to the list object. entryIndex This output parameter is the index of the newly added list entry. If this parameter is NULL, it is ignored. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_CreateListObject (  LIST_OBJ *    listObject )  ;

Creates a new list object and saves the result in listObject. If C_CreateListObject() is unsuccessful, no memory is allocated and listObject is set to (LIST_OBJ)NULL_PTR. Parameters: listObject This output parameter is a pointer to the newly created list object. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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. If the entry is not found, an error is returned. Parameters: listObject This is both an input and an output parameter. As an input parameter, it is the list object to be updated. As an output parameter, it is the updated list. entryIndex This input parameter is the index of the entry to be deleted. Returns: If successful, returns 0. If not, returns a Cert-C error code.

void C_DestroyListObject (  LIST_OBJ *    listObject )  ;

Frees all memory that listObject used, including all the entries in the listObject. Then, it sets listObject to (LIST_OBJ)NULL_PTR. If listObject is already (LIST_OBJ)NULL_PTR, then no action is taken. Parameters: listObject This is both an input and an output parameter. 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.

int C_GetListObjectCount (  LIST_OBJ    listObject, unsigned int *    count )  ;

Gets the number of entries in listObject and returns it in count. Parameters: listObject This input parameter is the list object. count This output parameter is the number of entries in the list object. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int C_GetListObjectEntry (  LIST_OBJ    listObject, unsigned int    entryIndex, POINTER *    entry )  ;

Gets 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. C_GetListObjectEntry() is intended to get 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. Note: The fields returned from this function are read-only. You do not need to create any objects or items prior to calling this function. Do not call any functions that modify these fields. Do not call any C_Destroy*() functions on these fields. Parameters: listObject This input parameter is the list object. entryIndex This input parameter is the entry-list index. entry This output parameter is the entry value. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the certificate to add to the list object. entryIndex This input parameter is the index of the position for the newly added list entry. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the certificate to add to the list object. entryIndex This input parameter is the index of the position for the newly added list entry. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the CRL to add to the list object. entryIndex This input parameter is the index of the position for the newly added list entry. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 greatly enhances performance, but the CRL should not be modified outside of the list. Parameters: listObject This is both an input and an output parameter. 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 This input parameter is the CRL to add to the list object. entryIndex This input parameter is the index of the position for the newly added list entry. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the item to add to the list object. entryIndex This input parameter is the index of the position for the newly added list entry. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is 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 This input parameter is the list entry index. If the value of entryIndex is greater than the entries count in listObject, an error is returned. handler This input parameter is the handler for allocating and deleting a list entry. The AllocAndCopy and Destructor callbacks are contained in handler. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. 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 This input parameter is the private key to add to the list object. entryIndex This input parameter is the index of the position for the newly added list entry. Returns: If successful, returns 0. If not, returns a Cert-C error code.

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 This is both an input and an output parameter. As an input parameter, it is the list object that Cert-C should reset. As an output parameter, it is the reset list object. Returns: None.

---

RSA BSAFE^® Cert-C 2.7 API Reference