RSA BSAFE Cert-C API Reference

certdb.h File Reference

This file defines the Cert-C database API.

The application should call these routines rather than directly calling the SERVICE_HANDLER functions.

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

Go to the source code of this file.

Functions
void	C_FreeIterator (DB_ITERATOR *dbIterator)
	Frees a database iterator previously created by one of the C_SelectFirst*() functions. More...
int	C_InsertCert (SERVICE database, CERT_OBJ cert)
	Inserts the certificate into the database or databases that are bound to the service handle. More...
int	C_InsertCertList (SERVICE database, LIST_OBJ certs)
	Inserts a list of certificates into the database or databases bound to the service handle. More...
int	C_InsertCRL (SERVICE database, CRL_OBJ crl)
	Inserts a CRL into the database or databases bound to the service handle. More...
int	C_InsertCRLList (SERVICE database, LIST_OBJ crlList)
	Inserts a list of CRLs into a database or databases bound to the service handle. More...
int	C_InsertPrivateKey (SERVICE database, CERT_OBJ cert, B_KEY_OBJ privateKey)
	Inserts a private key into the database or databases bound to the service handle. More...
int	C_InsertPrivateKeyBySPKI (SERVICE database, ITEM *spki, B_KEY_OBJ privateKey)
	Inserts a private key into the database or databases bound to the service handle. More...
int	C_SelectCertByIssuerSerial (SERVICE database, NAME_OBJ issuerName, ITEM *serialNumber, LIST_OBJ certList)
	Retrieves the certificate, identified by the specified issuer name and serial number, from the database or databases bound to the service handle. More...
int	C_SelectCertBySubject (SERVICE database, NAME_OBJ subjectName, LIST_OBJ certList)
	Retrieves one or more certificates, identified by the specified subject name, from the database or databases bound to the service handle. More...
int	C_SelectCertByExtensions (SERVICE database, NAME_OBJ baseName, EXTENSIONS_OBJ extensions, LIST_OBJ certList)
	Retrieves one or more certificates, identified by the specified extensions and base subject name, from the database or databases bound to the service handle. More...
int	C_SelectFirstCert (SERVICE database, DB_ITERATOR *dbIterator, LIST_OBJ certList)
	Retrieves the first certificate from the database or databases bound to the service handle, and adds a copy of the certificate to the certificate list. More...
int	C_SelectNextCert (DB_ITERATOR *dbIterator, LIST_OBJ certList)
	Retrieves the next certificate from the database or databases bound to the iterator and adds a copy of the certificate to the certificate list. More...
int	C_SelectCRLByIssuerTime (SERVICE database, NAME_OBJ issuerName, UINT4 time, LIST_OBJ crlList)
	Retrieves a CRL, identified by the specified issuer name and time, from the database or databases bound to the service handle. More...
int	C_SelectFirstCRL (SERVICE database, DB_ITERATOR *dbIterator, LIST_OBJ crlList)
	Retrieves the first CRL from the database or databases bound to the service handle, and adds a copy of the CRL to the CRL list. More...
int	C_SelectNextCRL (DB_ITERATOR *dbIterator, LIST_OBJ crlList)
	Retrieves the next CRL from the database or databases bound to the iterator, and adds a copy of the CRL to the CRL list. More...
int	C_SelectPrivateKeyByCert (SERVICE database, CERT_OBJ cert, B_KEY_OBJ privateKey)
	Retrieves the private key, identified by the specified certificate, from the database or databases bound to the service handle. More...
int	C_SelectPrivateKeyBySPKI (SERVICE database, ITEM *spki, B_KEY_OBJ privateKey)
	Retrieves the private key, identified by the specified subject's public-key identifier, from the database or databases bound to the service handle. More...
int	C_SelectFirstPrivateKey (SERVICE database, DB_ITERATOR *dbIterator, B_KEY_OBJ privateKey)
	Retrieves the first private key from the database or databases bound to the service handle. More...
int	C_SelectNextPrivateKey (DB_ITERATOR *dbIterator, B_KEY_OBJ privateKey)
	Retrieves the next private key from the database or databases bound to the iterator. More...
int	C_DeleteCert (SERVICE database, NAME_OBJ issuerName, ITEM *serialNumber)
	Deletes the certificate, identified by the specified issuer name and serial number, from the database or databases bound to the service handle. More...
int	C_DeleteCRL (SERVICE database, NAME_OBJ issuerName, UINT4 lastUpdate)
	Deletes the CRL, identified by the specified issuer name and last-update time, from the database or databases bound to the service handle. More...
int	C_DeletePrivateKey (SERVICE database, CERT_OBJ cert)
	Deletes the private key, identified by the specified certificate, from the database or databases bound to the service handle. More...
int	C_DeletePrivateKeyBySPKI (SERVICE database, ITEM *spki)
	Deletes the private key, identified by the specified subject-public-key identifier, from the database or databases bound to the service handle. More...
int	C_SelectCertByAttributes (SERVICE database, NAME_OBJ baseName, ATTRIBUTES_OBJ attributes, LIST_OBJ certList)
	Retrieves one or more certificates, identified by the specified attributes and base subject name, from the database or databases bound to the service handle. More...

---

Function Documentation

int C_DeleteCert (  SERVICE    database, NAME_OBJ    issuerName, ITEM *    serialNumber )  ;

Deletes the certificate, identified by the specified issuer name and serial number, from the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to delete the certificate from all of the service providers, in the order in which they were bound. Parameters: database This input parameter contains a service handle that was returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. issuerName This input parameter contains an initialized name object giving the name of the certificate issuer. serialNumber This input parameter points to an ITEM containing the serial number of the certificate to delete. Returns: This function returns 0 (zero) if at least one service provider deleted the certificate. If no certificate was deleted, this function returns the status from the last service provider in the set bound to the service handle.

int C_DeleteCRL (  SERVICE    database, NAME_OBJ    issuerName, UINT4    lastUpdate )  ;

Deletes the CRL, identified by the specified issuer name and last-update time, from the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to delete the matching CRL from all of the service providers, in the order in which they were bound. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. issuerName This input parameter contains an initialized name object giving the name of the CRL issuer. lastUpdate This input parameter contains the value of the last-update field of the corresponding CRL. Returns: This function returns 0 (zero) if at least one service provider deleted the CRL. If no CRL was deleted, this function returns the status from the last service provider in the set bound to the service handle.

int C_DeletePrivateKey (  SERVICE    database, CERT_OBJ    cert )  ;

Deletes the private key, identified by the specified certificate, from the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to delete the key from all of the service providers, in the order in which they were bound. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. cert This input parameter contains an initialized certificate object. Cert-C uses the information in the certificate (usually the subject's public-key identifier) to identify the corresponding private key to delete. Returns: This function returns 0 (zero) if at least one service provider deleted the private key. If no private key was deleted, this function returns the status from the last service provider in the set bound to the service handle.

int C_DeletePrivateKeyBySPKI (  SERVICE    database, ITEM *    spki )  ;

Deletes the private key, identified by the specified subject-public-key identifier, from the database or databases bound to the service handle. If more than one service-provider instance has been bound to the service handle, Cert-C attempts to delete the key from all of the service providers, in the order in which they were bound. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. spki This input parameter contains the DER-encoded subject-public-key identifier corresponding to the private key. (The format of the data in ITEM is the same as that in the publicKey field of the CERT_FIELDS data type.) Returns: This function returns 0 (zero) if at least one service provider deleted the private key. If no private key was deleted, this function returns the status from the last service provider in the set bound to the service handle.

void C_FreeIterator (  DB_ITERATOR *    dbIterator )  ;

Frees a database iterator previously created by one of the C_SelectFirst*() functions. C_FreeIterator() can be called to free an iterator before retrieving all of the records of a particular type. If a C_SelectFirst*() or C_SelectNext*() function has returned a non-zero status, it is not necessary to call C_FreeIterator(). Upon return, the iterator is set to NULL_PTR. Parameters: dbIterator This is both an input and an output parameter. It points to a Cert-C database iterator handle that was returned by a previous call to C_SelectFirstCert(), C_SelectFirstCRL(), or C_SelectFirstPrivateKey(). Returns: None.

int C_InsertCert (  SERVICE    database, CERT_OBJ    cert )  ;

Inserts the certificate into the database or databases that are bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to insert the certificate into each instance. If a given certificate is already in the database (as determined by matching issuer names and serial numbers), it is not added again. This is considered equivalent to a successful insertion of the certificate into the database. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. cert This input parameter contains an initialized certificate object. A copy of the certificate is added to the databases bound to the service handle. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_InsertCertList (  SERVICE    database, LIST_OBJ    certs )  ;

Inserts a list of certificates into the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to insert the list of certificates into each instance. If a given certificate is already in the database (as determined by matching issuer names and serial numbers), it is not added again. This is considered equivalent to a successful insertion of the certificate into the database. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. certs This input parameter contains an initialized list of certificate objects. A copy of each certificate is added to the database or databases bound to the service handle. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_InsertCRL (  SERVICE    database, CRL_OBJ    crl )  ;

Inserts a CRL into the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to insert the CRL into each instance. If a given CRL is already in the database (as determined by matching issuer names and last-update times), it is not added again. This is considered equivalent to a successful insertion of the CRL into the database. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. crl This input parameter contains an initialized CRL object. A copy of the CRL is added to the database or databases bound to the service handle. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_InsertCRLList (  SERVICE    database, LIST_OBJ    crlList )  ;

Inserts a list of CRLs into a database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to insert the CRLs into each instance. If a given CRL is already in the database (as determined by matching issuer names and last-update times), it is not added again. This is considered equivalent to a successful insertion of the CRL into the database. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. crlList This input parameter contains an initialized list of CRL objects. A copy of each CRL is added to the database or databases bound to the service handle. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_InsertPrivateKey (  SERVICE    database, CERT_OBJ    cert, B_KEY_OBJ    privateKey )  ;

Inserts a private key into the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to insert the key into each instance. If a given key is already in the database, it is not added again. This is considered equivalent to a successful insertion of the key into the database. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. cert This input parameter contains an initialized certificate object. Cert-C uses the information contained in the certificate (usually the subject's public-key identifier) to identify the corresponding private key. privateKey This input parameter contains an initialized private-key object. A copy of the private key is added to the database or databases bound to the service handle. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_InsertPrivateKeyBySPKI (  SERVICE    database, ITEM *    spki, B_KEY_OBJ    privateKey )  ;

Inserts a private key into the database or databases bound to the service handle. The private key is identified by the corresponding subject-public-key identifier. If more than one service-provider instance has been bound to the service handle, Cert-C attempts to insert the key into each instance. If a given key is already in the database, it is not added again. This is considered equivalent to a successful insertion of the key into the database. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. spki This input parameter contains the DER-encoded subject-public-key identifier corresponding to the private key. (The format of the data in ITEM is the same as that in the publicKey field of the CERT_FIELDS data type.) privateKey This input parameter contains an initialized private-key object. A copy of the private key is added to the database or databases bound to the service handle. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectCertByAttributes (  SERVICE    database, NAME_OBJ    baseName, ATTRIBUTES_OBJ    attributes, LIST_OBJ    certList )  ;

Retrieves one or more certificates, identified by the specified attributes and base subject name, from the database or databases bound to the service handle. C_SelectCertByAttributes() then adds a copy of each matching certificate to the certificate list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve matching certificates from all service providers, in the order in which they were bound. If a copy of a given certificate is already in the certificate list (as determined by matching issuer names and serial numbers), it is not added again. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE2. baseName This input parameter contains a name object that is compared against the subject name of a candidate certificate. All of the components of the base name must match the corresponding components of the candidate certificate subject name. However, the certificate subject name may contain more AVAs than are present in the baseName, and still match. If baseName has a value of NULL_PTR, it is considered to match a candidate certificate. attributes This input parameter contains an initialized attributes object that, in turn, contains a set of attribute name-value pairs. If the value of this parameter is NULL_PTR, all certificates that match the base name in the bound database or databases are returned. certList This input and output parameter points to an initialized list object. This function adds a copy of each matching certificate to this certificate list. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectCertByExtensions (  SERVICE    database, NAME_OBJ    baseName, EXTENSIONS_OBJ    extensions, LIST_OBJ    certList )  ;

Retrieves one or more certificates, identified by the specified extensions and base subject name, from the database or databases bound to the service handle. C_SelectCertByExtensions() then adds a copy of each matching certificate to the certificate list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve matching certificates from all service providers, in the order in which they were bound. If a copy of a given certificate is already in the list (as determined by matching issuer names and serial numbers), it is not added again. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. baseName This input parameter contains a name object that is compared against the subject name of a candidate certificate. All of the components of the base name must match the corresponding components of the candidate certificate subject name. However, the certificate subject name may contain more AVAs than are present in the baseName, and still match. If baseName has a value of NULL_PTR, it is considered to match a candidate certificate. However, that some database service providers (for example, the LDAP service provider) may refuse to perform this operation unless a base name is specified. extensions This input parameter contains an initialized extensions object that, in turn, contains a set of extensions types and values. If the value of this parameter is NULL_PTR, all certificates that match the base name in the bound database or databases are returned. The extensions object is compared with the extensions contained in a candidate certificate in a way that is functionally equivalent to C_CompareExtensions(). The extensions parameter of C_SelectCertByExtensions() is the first parameter of C_CompareExtensions(), and the extensions object from the candidate certificate fields is the second parameter. certList This input and output parameter points to an initialized list object. This function adds a copy of matching certificates to this certificate list. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectCertByIssuerSerial (  SERVICE    database, NAME_OBJ    issuerName, ITEM *    serialNumber, LIST_OBJ    certList )  ;

Retrieves the certificate, identified by the specified issuer name and serial number, from the database or databases bound to the service handle. C_SelectCertByIssuerSerial() then adds a copy of the certificate to the certificate list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve the certificate from each service provider, in the order in which they were bound, until the certificate is located. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. issuerName This input parameter contains an initialized name object giving the name of the certificate issuer. serialNumber This input parameter points to an ITEM containing the serial number of the certificate to retrieve. certList This input and output parameter points to an initialized list object. This function adds a copy of the specified certificate to this list. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectCertBySubject (  SERVICE    database, NAME_OBJ    subjectName, LIST_OBJ    certList )  ;

Retrieves one or more certificates, identified by the specified subject name, from the database or databases bound to the service handle. C_SelectCertBySubject() then adds a copy of each matching certificate to the certificate list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve matching certificates from all service providers, in the order in which they were bound. If a copy of a given certificate is already in the list (as determined by matching issuer names and serial numbers), it is not added again. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. subjectName This input parameter contains an initialized name object giving the subject name of the certificates to select. certList This is both an input and an output parameter. It is the list to append with a copy of the selected certificate. As an input parameter, it is a pointer to an initialized list object. As an output parameter, it is the updated list object. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectCRLByIssuerTime (  SERVICE    database, NAME_OBJ    issuerName, UINT4    time, LIST_OBJ    crlList )  ;

Retrieves a CRL, identified by the specified issuer name and time, from the database or databases bound to the service handle. C_SelectCRLByIssuerTime() then adds a copy of the matching CRL to the CRL list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve the matching CRL from all of the service providers, in the order in which they were bound. If a copy of the CRL is already in the list (as determined by matching issuer names and last-update times), it is not added again. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. issuerName This input parameter contains an initialized name object giving the name of the CRL issuer. time This is an input parameter. A candidate CRL matches if the issuer name matches, if the specified time is greater than or equal to the last-update time of the candidate CRL, and if the candidate CRL has the greatest last-update time of all candidate CRLs with matching issuer names. crlList This is both an input and an output parameter. It is the list to append with a copy of the selected CRL. As an input parameter, it is a pointer to an initialized list object. As an output parameter, it is the updated list object. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectFirstCert (  SERVICE    database, DB_ITERATOR *    dbIterator, LIST_OBJ    certList )  ;

Retrieves the first certificate from the database or databases bound to the service handle, and adds a copy of the certificate to the certificate list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve the first certificate from all of the service providers. It does this in the order in which the certificates were bound, until a certificate is successfully retrieved. If a copy of the certificate is already in the list (as determined by matching issuer names and serial numbers), it is not added again. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. dbIterator This output parameter points to an uninitialized DB_ITERATOR variable. This function allocates the iterator, and returns it in this parameter. If the database contains no certificates, the iterator is set to NULL_PTR. certList This input and output parameter is the list to append with a copy of the first certificate in the database. As an input parameter, it is a pointer to an initialized list object. As an output parameter, it is the updated list object. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectFirstCRL (  SERVICE    database, DB_ITERATOR *    dbIterator, LIST_OBJ    crlList )  ;

Retrieves the first CRL from the database or databases bound to the service handle, and adds a copy of the CRL to the CRL list. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve the first CRL from all of the service providers, in the order in which they were bound, until a CRL is successfully retrieved. If a copy of the CRL is already in the list (as determined by matching issuer names and last-update times), it is not added again. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. dbIterator This output parameter points to an uninitialized DB_ITERATOR variable. The function allocates the iterator and returns it in this parameter. If the database contains no CRLs, the iterator is set to NULL_PTR. crlList This input and output parameter is the list to append with a copy of the first CRL in the database. As an input parameter, it is a pointer to an initialized list object. As an output parameter, it is the updated list object. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectFirstPrivateKey (  SERVICE    database, DB_ITERATOR *    dbIterator, B_KEY_OBJ    privateKey )  ;

Retrieves the first private key from the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve the first private key from all of the service providers, in the order in which they were bound, until a private key is successfully retrieved. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. dbIterator This output parameter points to an uninitialized DB_ITERATOR variable. The function allocates the iterator and returns it in this parameter. If the database contains no private keys, the iterator is set to NULL_PTR. privateKey This is both an input and output parameter. As an input parameter, it contains an allocated but uninitialized key object. As an output parameter, this function initializes the object with key information taken from the database entry. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectNextCert (  DB_ITERATOR *    dbIterator, LIST_OBJ    certList )  ;

Retrieves the next certificate from the database or databases bound to the iterator and adds a copy of the certificate to the certificate list. If more than one service-provider instance is bound to the iterator, Cert-C attempts to retrieve the next certificate from all the service providers, in the order in which they were bound, until a certificate is successfully retrieved. If a copy of the certificate is already in the list (as determined by matching issuer names and serial numbers), it is not added again. Parameters: dbIterator This is both an input and an output parameter. It points to an initialized DB_ITERATOR variable. (The iterator must be created by a previous call to C_SelectFirstCert().) If all of the certificates in the database have been retrieved, or if any other error occurs, the memory associated with the iterator is freed, the variable is set to NULL_PTR, and E_NOT_FOUND is returned. certList This is both an input and an output parameter. It is the list to append with a copy of the next certificate in the database. As an input parameter, it is a pointer to an initialized list object. As an output parameter, it is the updated list object. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectNextCRL (  DB_ITERATOR *    dbIterator, LIST_OBJ    crlList )  ;

Retrieves the next CRL from the database or databases bound to the iterator, and adds a copy of the CRL to the CRL list. If more than one service-provider instance is bound to the iterator, Cert-C attempts to retrieve the first CRL from all of the service providers, in the order in which they were bound, until a CRL is successfully retrieved. If a copy of the CRL is already in the list (as determined by matching issuer names and last-update times), it is not added again. Parameters: dbIterator This is both an input and an output parameter. It points to an initialized DB_ITERATOR variable. (The iterator must already be created by a previous call to C_SelectFirstCRL().) If all of the CRLs in the database have been retrieved, or if any other error occurs, the memory associated with the iterator is freed, the variable is set to NULL_PTR, and E_NOT_FOUND is returned. crlList This is both an input and an output parameter. It is the list to append with a copy of the next CRL in the database. As an input parameter, it is a pointer to an initialized list object. As an output parameter, it is the updated list object. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectNextPrivateKey (  DB_ITERATOR *    dbIterator, B_KEY_OBJ    privateKey )  ;

Retrieves the next private key from the database or databases bound to the iterator. If more than one service-provider instance is bound to the iterator, Cert-C attempts to retrieve the next private key from all of the service providers, in the order in which they were bound, until a private key is successfully retrieved. Parameters: dbIterator This is both an input and an output parameter. It points to an initialized DB_ITERATOR variable. (The iterator must already be created by a previous call to C_SelectFirstPrivateKey().) If all of the keys in the database have been retrieved, or if any other error occurs, the memory associated with the iterator is freed, the variable is set to NULL_PTR, and E_NOT_FOUND is returned. privateKey This is both an input and an output parameter. As an input parameter, it contains an allocated but uninitialized key object. As an output parameter, this function initializes the object with key information taken from the database entry. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectPrivateKeyByCert (  SERVICE    database, CERT_OBJ    cert, B_KEY_OBJ    privateKey )  ;

Retrieves the private key, identified by the specified certificate, from the database or databases bound to the service handle. If more than one service-provider instance is bound to the service handle, Cert-C attempts to retrieve the key from all of the service providers, in the order in which they were bound, until a private key is retrieved successfully. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. cert This input parameter contains an initialized certificate object. Information contained in the certificate (usually the subject's public-key identifier) is used to locate the corresponding private key. privateKey This is both an input and an output parameter. As an input parameter, it contains an allocated but uninitialized key object. As an output parameter, this function initializes the object with key information taken from the database entry. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

int C_SelectPrivateKeyBySPKI (  SERVICE    database, ITEM *    spki, B_KEY_OBJ    privateKey )  ;

Retrieves the private key, identified by the specified subject's public-key identifier, from the database or databases bound to the service handle. If more than one service-provider instance has been bound to the service handle, Cert-C attempts to retrieve the private key from all of the service providers, in the order in which they were bound, until a private key is retrieved successfully. Parameters: database This input parameter contains a service handle returned by C_BindService() or C_BindServices(). The service-provider instances bound to the handle must be of type SPT_DATABASE or SPT_DATABASE2. spki This input parameter contains the DER-encoded subject-public-key identifier corresponding to the private key. The format of the data in ITEM is the same as that in the publicKey field of the CERT_FIELDS data type. privateKey This is both an input and an output parameter. As an input parameter, it contains an allocated, uninitialized key object. As an output parameter, this function initializes the object with key information taken from the database entry. Returns: If successful, returns 0 (zero). If not, returns a Cert-C error code.

---

RSA BSAFE^® Cert-C 2.7 API Reference