(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 <cert.h>
```

```{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 <cert.h>
```

```{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 <cert.h>
```

```{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 <cert.h>
#include <certt.h>
```

```{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 <nss.h>

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 <cert.h>
```

```{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 <cert.h>
#include <certt.h>
```

```{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 <cert.h>
```

```{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 <cert.h>
#include <certt.h>
```

```{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 <cert.h>
```

```{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 <cert.h>
```

```{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 <nss.h>
```

```{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 <secitem.h>
#include <seccomon.h>
```

```{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;
```

:::
