This chapter describes the functions and related types used to work with a certificate database such as the cert8.db database provided with NSS. This was converted from "Chapter 5: Certificate Functions".
Checks that the current date is within the certificate's validity period and that the CA signature on the certificate is valid.
#include <cert.h>
SECStatus CERT_VerifyCertNow( CERTCertDBHandle *handle, CERTCertificate *cert, PRBool checkSig, SECCertUsage certUsage, void *wincx);
This function has the following parameters:
handleA pointer to the certificate database handle.
certA pointer to the certificate to be checked.
checkSigIndicates whether certificate signatures are to be checked.
certUsageOne of these values:
wincxThe PIN argument value to pass to PK11 functions. See description below for more information.
The function returns one of these values:
The CERT_VerifyCertNow function must call one or more PK11 functions to obtain the services of a PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for details), which must be specified in the wincx parameter. To obtain the value to pass in the wincx parameter, call SSL_RevealPinArg.
Checks that the a given aribrary date is within the certificate's validity period and that the CA signature on the certificate is valid. It also optionally returns a log of all the problems with the chain. Calling CERT_VerifyCert with the parameters: CERT_VerifyCert(handle, cert, checkSig, certUsage, PR_Now(), wincx, NULL) is equivalent to calling CERT_VerifyNow(handle, cert, checkSig, certUsage, wincx).
#include <cert.h>
SECStatus CERT_VerifyCert( CERTCertDBHandle *handle, CERTCertificate *cert, PRBool checkSig, SECCertUsage certUsage, int 64 t, void *wincx CERTVerifyLog *log);
This function has the following parameters:
handleA pointer to the certificate database handle.
certA pointer to the certificate to be checked.
checkSigIndicates whether certificate signatures are to be checked.
certUsageOne of these values:
tTime in which to validate the certificate.
wincxThe PIN argument value to pass to PK11 functions. See description below for more information.
logOptional certificate log which returns all the errors in processing a given certificate chain. See Using CERTVerifyLog for more information.
The function returns one of these values:
The CERT_VerifyCert function must call one or more PK11 functions to obtain the services of a PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for details), which must be specified in the wincx parameter. To obtain the value to pass in the wincx parameter, call SSL_RevealPinArg.
Compares the common name specified in the subject DN for a certificate with a specified hostname.
#include <cert.h>
SECStatus CERT_VerifyCertName( CERTCertificate *cert, char *hostname);
This function has the following parameters:
certA pointer to the certificate against which to check the hostname referenced by hostname.
hostnameThe hostname to be checked.
The function returns one of these values:
The comparison performed by CERT_VerifyCertName is not a simple string comparison. Instead, it takes account of the following rules governing the construction of common names in SSL server certificates:
Checks whether a specified time is within a certificate's validity period.
#include <cert.h> #include <certt.h>
SECCertTimeValidity CERT_CheckCertValidTimes( CERTCertificate *cert, int64 t);
This function has the following parameters:
certA pointer to the certificate whose validity period you want to check against.
tThe time to check against the certificate's validity period. For more information, see the NSPR header pr_time.h.
The function returns an enumerator of type SECCertTimeValidity:
typedef enum {
secCertTimeValid,
secCertTimeExpired,
secCertTimeNotValidYet
} SECCertTimeValidity;
Determines whether any of the signers in the certificate chain for a specified certificate are on a specified list of CA names.
#include <nss.h> SECStatus NSS_CmpCertChainWCANames( CERTCertificate *cert, CERTDistNames *caNames);
This function has the following parameters:
certA pointer to the certificate structure for the certificate whose certificate chain is to be checked.
caNamesA pointer to a structure that contains a list of distinguished names (DNs) against which to check the DNs for the signers in the certificate chain.
The function returns one of these values:
Makes a shallow copy of a specified certificate.
#include <cert.h>
CERTCertificate *CERT_DupCertificate(CERTCertificate *c)
This function has the following parameter:
cA pointer to the certificate object to be duplicated.
If successful, the function returns a pointer to a certificate object of type CERTCertificate.
The CERT_DupCertificate function increments the reference count for the certificate passed in the c parameter.
Destroys a certificate object.
#include <cert.h> #include <certt.h>
void CERT_DestroyCertificate(CERTCertificate *cert);
This function has the following parameter:
certA pointer to the certificate to destroy.
Certificate and key structures are shared objects. When an application makes a copy of a particular certificate or key structure that already exists in memory, SSL makes a shallow copy--that is, it increments the reference count for that object rather than making a whole new copy. When you call CERT_DestroyCertificate or SECKEY_DestroyPrivateKey, the function decrements the reference count and, if the reference count reaches zero as a result, both frees the memory and sets all the bits to zero. The use of the word "destroy" in function names or in the description of a function implies reference counting.
Never alter the contents of a certificate or key structure. If you attempt to do so, the change affects all the shallow copies of that structure and can cause severe problems.
Finds the certificate in the certificate database with a specified DN.
#include <cert.h>
CERTCertificate *CERT_FindCertByName ( CERTCertDBHandle *handle, SECItem *name);
This function has the following parameters:
handleA pointer to the certificate database handle.
nameThe subject DN of the certificate you wish to find.
If successful, the function returns a certificate object of type CERTCertificate.
Returns the nicknames of the certificates in a specified certificate database.
#include <cert.h> #include <certt.h>
CERTCertNicknames *CERT_GetCertNicknames ( CERTCertDBHandle *handle, int what, void *wincx);
This function has the following parameters:
handleA pointer to the certificate database handle.
whatOne of these values:
wincxThe PIN argument value to pass to PK11 functions. See description below for more information.
The function returns a CERTCertNicknames object containing the requested nicknames.
CERT_GetCertNicknames must call one or more PK11 functions to obtain the services of a PKCS #11 module. Some of the PK11 functions require a PIN argument (see SSL_SetPKCS11PinArg for details), which must be specified in the wincx parameter. To obtain the value to pass in the wincx parameter, call SSL_RevealPinArg.
Frees a CERTCertNicknames structure. This structure is returned by CERT_GetCertNicknames.
#include <cert.h>
void CERT_FreeNicknames(CERTCertNicknames *nicknames);
This function has the following parameter:
nicknamesA pointer to the CERTCertNicknames structure to be freed.
Returns a handle to the default certificate database.
#include <cert.h>
CERTCertDBHandle *CERT_GetDefaultCertDB(void);
The function returns the CERTCertDBHandle for the default certificate database.
This function is useful for determining whether the default certificate database has been opened.
Returns key exchange type of the keys in an SSL server certificate.
#include <nss.h>
SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);
This function has the following parameter:
aThe certificate to check.
The function returns one of these values:
Compares two SECItem objects and returns a SECComparison enumerator that shows the difference between them.
#include <secitem.h> #include <seccomon.h>
SECComparison SECITEM_CompareItem( SECItem *a, SECItem *b);
This function has the following parameters:
aA pointer to one of the items to be compared.
bA pointer to one of the items to be compared.
The function returns an enumerator of type SECComparison.
typedef enum _SECComparison {
SECLessThan = -1,
SECEqual = 0,
SECGreaterThan = 1
} SECComparison;