(mozilla-projects-nss-ssl-functions-sslcrt)=

# sslcrt

::::{container}

:::{note}

- This page is part of the {ref}`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
  we are migrating into the format described in the [MDN Style
  Guide](https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide). If you are
  inclined to help with this migration, your help would be very much appreciated.
- Upgraded documentation may be found in the {ref}`mozilla_projects_nss_reference`
:::

```{rubric} Certificate Functions
:name: Certificate_Functions
```

::::

[Chapter 5](#chapter_5_certificate_functions) Certificate Functions

______________________________________________________________________

:::{container}
This chapter describes the functions and related types used to work with a certificate database
such as the `cert7.db` database provided with Communicator.

[Validating Certificates](#1060423)

[Manipulating Certificates](#1056436)

[Getting Certificate Information](#1056475)

[Comparing SecItem Objects](#1055384)
:::

## [Validating Certificates](#validating_certificates)

:::{container}
`` `CERT_VerifyCertNow ``

 \<#1058011>\`\_\_

`` `CERT_VerifyCertName ``

 \<#1050342>\`\_\_

`` `CERT_CheckCertValidTimes ``

 \<#1056662>\`\_\_

`` `NSS_CmpCertChainWCANames ``

 \<#1056760>\`\_\_

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

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate database handle.   |
|                                                 |                                                 |
|    handle                                       |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate to be checked.     |
|                                                 |                                                 |
|    cert                                         |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | Indicates whether certificate signatures are to |
|                                                 | be checked. ``PR_TRUE`` means certificate       |
|    checkSig                                     | signatures are to be checked. ``PR_FALSE``      |
|                                                 | means certificate signatures will not be        |
|                                                 | checked.                                        |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | One of these values:                            |
|                                                 |                                                 |
|    certUsage                                    | -  ``certUsageSSLClient``                       |
|                                                 | -  ``certUsageSSLServer``                       |
|                                                 | -  ``certUsageSSLServerWithStepUp``             |
|                                                 | -  ``certUsageSSLCA``                           |
|                                                 | -  ``certUsageEmailSigner``                     |
|                                                 | -  ``certUsageEmailRecipient``                  |
|                                                 | -  ``certUsageObjectSigner``                    |
|                                                 | -  ``certUsageUserCertImport``                  |
|                                                 | -  ``certUsageVerifyCA``                        |
|                                                 | -  ``certUsageProtectedObjectSigner``           |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | The PIN argument value to pass to PK11          |
|                                                 | functions. See description below for more       |
|    wincx                                        | information.                                    |
+-------------------------------------------------+-------------------------------------------------+
```

```{rubric} Returns
```

The function returns one of these values:

- If successful, `SECSuccess`.
- If unsuccessful, `SECFailure`. Use
  `` `PR_GetError `` \<../../../../../nspr/reference/html/prerr.html#26127>\`\_\_ 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
{ref}`mozilla_projects_nss_ssl_functions_sslfnc#1088040` for details), which must be specified in
the `wincx` parameter. To obtain the value to pass in the `wincx` parameter, call
{ref}`mozilla_projects_nss_ssl_functions_sslfnc#1123385`.

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

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate against which to   |
|                                                 | check the hostname referenced by ``hostname``.  |
|    cert                                         |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | The hostname to be checked.                     |
|                                                 |                                                 |
|    hostname                                     |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{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 `` \<../../../../../nspr/reference/html/prerr.html#26127>\`\_\_ 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:

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate whose validity     |
|                                                 | period you want to check against.               |
|    cert                                         |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | The time to check against the certificate's     |
|                                                 | validity period. For more information, see the  |
|    t                                            | 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>
```

```{code}
SECStatus NSS_CmpCertChainWCANames(
   CERTCertificate *cert,
   CERTDistNames *caNames);
```

```{rubric} Parameters
```

This function has the following parameters:

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate structure for the  |
|                                                 | certificate whose certificate chain is to be    |
|    cert                                         | checked.                                        |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to a structure that contains a list   |
|                                                 | of distinguished names (DNs) against which to   |
|    caNames                                      | 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 `` \<../../../../../nspr/reference/html/prerr.html#26127>\`\_\_ to obtain the error
  code.
:::

## [Manipulating Certificates](#manipulating_certificates)

:::{container}
`` `CERT_DupCertificate ``

 \<#1058344>\`\_\_

`` `CERT_DestroyCertificate ``

 \<#1050532>\`\_\_

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

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate object to be       |
|                                                 | duplicated.                                     |
|    c                                            |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{rubric} Returns
```

If successful, the function returns a pointer to a certificate object of type
`` `CERTCertificate `` \<ssltyp.html#1027387>\`\_\_.

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

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate to destroy.        |
|                                                 |                                                 |
|    cert                                         |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{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 `` \<#1050532>\`\_\_ or
`` `SECKEY_DestroyPrivateKey `` \<sslkey.html#1051017>\`\_\_, 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.
:::

## [Getting Certificate Information](#getting_certificate_information)

:::{container}
`` `CERT_FindCertByName ``

 \<#1050345>\`\_\_

`` `CERT_GetCertNicknames ``

 \<#1050346>\`\_\_

`` `CERT_FreeNicknames ``

 \<#1050349>\`\_\_

`` `CERT_GetDefaultCertDB ``

 \<#1052308>\`\_\_

`` `NSS_FindCertKEAType ``

 \<#1056950>\`\_\_

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

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate database handle.   |
|                                                 |                                                 |
|    handle                                       |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | The subject DN of the certificate you wish to   |
|                                                 | find.                                           |
|    name                                         |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{rubric} Returns
```

If successful, the function returns a certificate object of type
`` `CERTCertificate `` \<ssltyp.html#1027387>\`\_\_.

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

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the certificate database handle.   |
|                                                 |                                                 |
|    handle                                       |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | One of these values:                            |
|                                                 |                                                 |
|    what                                         | -  ``SEC_CERT_NICKNAMES_ALL``                   |
|                                                 | -  ``SEC_CERT_NICKNAMES_USER``                  |
|                                                 | -  ``SEC_CERT_NICKNAMES_SERVER``                |
|                                                 | -  ``SEC_CERT_NICKNAMES_CA``                    |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | The PIN argument value to pass to PK11          |
|                                                 | functions. See description below for more       |
|    wincx                                        | 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
{ref}`mozilla_projects_nss_ssl_functions_sslfnc#1088040` for details), which must be specified in
the `wincx` parameter. To obtain the value to pass in the `wincx` parameter, call
{ref}`mozilla_projects_nss_ssl_functions_sslfnc#1123385`.

```{rubric} CERT_FreeNicknames
```

Frees a `CERTCertNicknames` structure. This structure is returned by
`` `CERT_GetCertNicknames `` \<#1050346>\`\_\_.

```{rubric} Syntax
```

```{code}
#include <cert.h>
```

```{code}
void CERT_FreeNicknames(CERTCertNicknames *nicknames);
```

```{rubric} Parameters
```

This function has the following parameter:

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the ``CERTCertNicknames``          |
|                                                 | structure to be freed.                          |
|    nicknames                                    |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{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 `` \<ssltyp.html#1028465>\`\_\_ 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:

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | The certificate to check.                       |
|                                                 |                                                 |
|    a                                            |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{rubric} Returns
```

The function returns one of these values:

- `kt_null = 0`
- `kt_rsa`
- `kt_dh`
- `kt_fortezza`
- `kt_kea_size`
:::

## [Comparing SecItem Objects](#comparing_secitem_objects)

:::{container}

```{rubric} SECITEM_CompareItem
```

Compares two `` `SECItem `` \<ssltyp.html#1026076>\`\_\_ 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:

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to one of the items to be compared.   |
|                                                 |                                                 |
|    a                                            |                                                 |
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to one of the items to be compared.   |
|                                                 |                                                 |
|    b                                            |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{rubric} Returns
```

The function returns an enumerator of type `SECComparison`.

```{code}
typedef enum _SECComparison {
   SECLessThan                = -1,
   SECEqual                = 0,
   SECGreaterThan = 1
} SECComparison;
```

:::
