Source code
Revision control
Copy as Markdown
Other Tools
(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
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;
```
:::