(mozilla-projects-nss-reference-nss-certificate-functions)= # NSS Certificate Functions ## [Certificate Functions](#certificate_functions) :::{container} 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"](https://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt.html). - {ref}`mozilla_projects_nss_reference` - [Validating Certificates](NSS_Certificate_Functions#Validating_Certificates) - [Manipulating Certificates](NSS_Certificate_Functions#Manipulating_Certificates) - [Getting Certificate Information](NSS_Certificate_Functions#Getting_Certificate_Information) - [Comparing SecItem Objects](NSS_Certificate_Functions#Comparing_SecItem_Objects) ```{rubric} Validating Certificates ``` - [CERT_VerifyCertNow](NSS_Certificate_Functions#CERT_VerifyCertNow) - [CERT_VerifyCert](NSS_Certificate_Functions#CERT_VerifyCert) - [CERT_VerifyCertName](NSS_Certificate_Functions#CERT_VerifyCertName) - [CERT_CheckCertValidTimes](NSS_Certificate_Functions#CERT_CheckCertValidTimes) - [NSS_CmpCertChainWCANames](NSS_Certificate_Functions#NSS_CmpCertChainWCANames) ```{rubric} CERT_VerifyCertNow ``` Checks that the current date is within the certificate's validity period and that the CA signature on the certificate is valid. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} SECStatus CERT_VerifyCertNow( CERTCertDBHandle *handle, CERTCertificate *cert, PRBool checkSig, SECCertUsage certUsage, void *wincx); ``` ```{rubric} Parameters ``` This function has the following parameters: *handle*A pointer to the certificate database handle. *cert*A pointer to the certificate to be checked. *checkSig*Indicates whether certificate signatures are to be checked. - PR_TRUE means certificate signatures are to be checked. - PR_FALSE means certificate signatures will not be checked. *certUsage*One of these values: - certUsageSSLClient - certUsageSSLServer - certUsageSSLServerWithStepUp - certUsageSSLCA - certUsageEmailSigner - certUsageEmailRecipient - certUsageObjectSigner - certUsageUserCertImport - certUsageVerifyCA - certUsageProtectedObjectSigner *wincx*The PIN argument value to pass to PK11 functions. See description below for more information. ```{rubric} Returns ``` The function returns one of these values: - If successful, SECSuccess. - If unsuccessful, SECFailure. Use PR_GetError to obtain the error code. ```{rubric} Description ``` 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. ```{rubric} CERT_VerifyCert :name: cert_verifycert ``` 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). ```{rubric} Syntax ``` ```{code} #include ``` ```{code} SECStatus CERT_VerifyCert( CERTCertDBHandle *handle, CERTCertificate *cert, PRBool checkSig, SECCertUsage certUsage, int 64 t, void *wincx CERTVerifyLog *log); ``` ```{rubric} Parameters ``` This function has the following parameters: *handle*A pointer to the certificate database handle. *cert*A pointer to the certificate to be checked. *checkSig*Indicates whether certificate signatures are to be checked. - PR_TRUE means certificate signatures are to be checked. - PR_FALSE means certificate signatures will not be checked. *certUsage*One of these values: - certUsageSSLClient - certUsageSSLServer - certUsageSSLServerWithStepUp - certUsageSSLCA - certUsageEmailSigner - certUsageEmailRecipient - certUsageObjectSigner - certUsageUserCertImport - certUsageVerifyCA - certUsageProtectedObjectSigner *t*Time in which to validate the certificate. *wincx*The PIN argument value to pass to PK11 functions. See description below for more information. *log*Optional certificate log which returns all the errors in processing a given certificate chain. See {ref}`mozilla_projects_nss_certverify_log` for more information. ```{rubric} Returns ``` The function returns one of these values: - If successful, SECSuccess. - If unsuccessful, SECFailure. Use PR_GetError to obtain the error code. ```{rubric} Description ``` 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. ```{rubric} CERT_VerifyCertName ``` Compares the common name specified in the subject DN for a certificate with a specified hostname. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} SECStatus CERT_VerifyCertName( CERTCertificate *cert, char *hostname); ``` ```{rubric} Parameters ``` This function has the following parameters: *cert*A pointer to the certificate against which to check the hostname referenced by hostname. *hostname*The hostname to be checked. ```{rubric} Returns ``` The function returns one of these values: - If the common name in the subject DN for the certificate matches the domain name passed in the hostname parameter, SECSuccess. - If the common name in the subject DN for the certificate is not identical to the domain name passed in the hostname parameter, SECFailure. Use PR_GetError to obtain the error code. ```{rubric} Description ``` 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: - \* matches anything - ? matches one character - \\ escapes a special character - \$ matches the end of the string - \[abc] matches one occurrence of a, b, or c. The only character that needs to be escaped in this is \], all others are not special. - \[a-z] matches any character between a and z - \[^az] matches any character except a or z - \~ followed by another shell expression removes any pattern matching the shell expression from the match list - (foo|bar) matches either the substring foo or the substring bar. These can be shell expressions as well. ```{rubric} CERT_CheckCertValidTimes ``` Checks whether a specified time is within a certificate's validity period. ```{rubric} Syntax ``` ```{code} #include #include ``` ```{code} SECCertTimeValidity CERT_CheckCertValidTimes( CERTCertificate *cert, int64 t); ``` ```{rubric} Parameters ``` This function has the following parameters: *cert*A pointer to the certificate whose validity period you want to check against. *t*The time to check against the certificate's validity period. For more information, see the NSPR header pr_time.h. ```{rubric} Returns ``` The function returns an enumerator of type SECCertTimeValidity: ```{code} typedef enum { secCertTimeValid, secCertTimeExpired, secCertTimeNotValidYet } SECCertTimeValidity; ``` ```{rubric} NSS_CmpCertChainWCANames ``` Determines whether any of the signers in the certificate chain for a specified certificate are on a specified list of CA names. ```{rubric} Syntax ``` ```{code} #include SECStatus NSS_CmpCertChainWCANames( CERTCertificate *cert, CERTDistNames *caNames); ``` ```{rubric} Parameters ``` This function has the following parameters: *cert*A pointer to the certificate structure for the certificate whose certificate chain is to be checked. *caNames*A 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. ```{rubric} Returns ``` The function returns one of these values: - If successful, SECSuccess. - If unsuccessful, SECFailure. Use PR_GetError to obtain the error code. ```{rubric} Manipulating Certificates ``` - [CERT_DupCertificate](#cert_dupcertificate) - [CERT_DestroyCertificate](#cert_destroycertificate) ```{rubric} CERT_DupCertificate ``` Makes a shallow copy of a specified certificate. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} CERTCertificate *CERT_DupCertificate(CERTCertificate *c) ``` ```{rubric} Parameter ``` This function has the following parameter: *c*A pointer to the certificate object to be duplicated. ```{rubric} Returns ``` If successful, the function returns a pointer to a certificate object of type CERTCertificate. ```{rubric} Description ``` The CERT_DupCertificate function increments the reference count for the certificate passed in the c parameter. ```{rubric} CERT_DestroyCertificate ``` Destroys a certificate object. ```{rubric} Syntax ``` ```{code} #include #include ``` ```{code} void CERT_DestroyCertificate(CERTCertificate *cert); ``` ```{rubric} Parameters ``` This function has the following parameter: *cert*A pointer to the certificate to destroy. ```{rubric} Description ``` 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. ```{rubric} Getting Certificate Information ``` - [CERT_FindCertByName](#cert_findcertbyname) - [CERT_GetCertNicknames](#cert_getcertnicknames) - [CERT_FreeNicknames](#cert_freenicknames) - [CERT_GetDefaultCertDB](#cert_getdefaultcertdb) - [NSS_FindCertKEAType](#nss_findcertkeatype) ```{rubric} CERT_FindCertByName ``` Finds the certificate in the certificate database with a specified DN. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} CERTCertificate *CERT_FindCertByName ( CERTCertDBHandle *handle, SECItem *name); ``` ```{rubric} Parameters ``` This function has the following parameters: *handle*A pointer to the certificate database handle. *name*The subject DN of the certificate you wish to find. ```{rubric} Returns ``` If successful, the function returns a certificate object of type CERTCertificate. ```{rubric} CERT_GetCertNicknames ``` Returns the nicknames of the certificates in a specified certificate database. ```{rubric} Syntax ``` ```{code} #include #include ``` ```{code} CERTCertNicknames *CERT_GetCertNicknames ( CERTCertDBHandle *handle, int what, void *wincx); ``` ```{rubric} Parameters ``` This function has the following parameters: *handle*A pointer to the certificate database handle. *what*One of these values: - SEC_CERT_NICKNAMES_ALL - SEC_CERT_NICKNAMES_USER - SEC_CERT_NICKNAMES_SERVER - SEC_CERT_NICKNAMES_CA *wincx*The PIN argument value to pass to PK11 functions. See description below for more information. ```{rubric} Returns ``` The function returns a CERTCertNicknames object containing the requested nicknames. ```{rubric} Description ``` 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. ```{rubric} CERT_FreeNicknames ``` Frees a CERTCertNicknames structure. This structure is returned by CERT_GetCertNicknames. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} void CERT_FreeNicknames(CERTCertNicknames *nicknames); ``` ```{rubric} Parameters ``` This function has the following parameter: *nicknames*A pointer to the CERTCertNicknames structure to be freed. ```{rubric} CERT_GetDefaultCertDB ``` Returns a handle to the default certificate database. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} CERTCertDBHandle *CERT_GetDefaultCertDB(void); ``` ```{rubric} Returns ``` The function returns the CERTCertDBHandle for the default certificate database. ```{rubric} Description ``` This function is useful for determining whether the default certificate database has been opened. ```{rubric} NSS_FindCertKEAType ``` Returns key exchange type of the keys in an SSL server certificate. ```{rubric} Syntax ``` ```{code} #include ``` ```{code} SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert); ``` ```{rubric} Parameter ``` This function has the following parameter: *a*The certificate to check. ```{rubric} Returns ``` The function returns one of these values: - kt_null = 0 - kt_rsa - kt_dh - kt_fortezza - kt_kea_size ```{rubric} Comparing SecItem Objects ``` ```{rubric} SECITEM_CompareItem ``` Compares two SECItem objects and returns a SECComparison enumerator that shows the difference between them. ```{rubric} Syntax ``` ```{code} #include #include ``` ```{code} SECComparison SECITEM_CompareItem( SECItem *a, SECItem *b); ``` ```{rubric} Parameters ``` This function has the following parameters: *a*A pointer to one of the items to be compared. *b*A pointer to one of the items to be compared. ```{rubric} Returns ``` The function returns an enumerator of type SECComparison. ```{code} typedef enum _SECComparison { SECLessThan = -1, SECEqual = 0, SECGreaterThan = 1 } SECComparison; ``` :::