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_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 <#validating_certificates>`__
------------------------------------------------------
.. container::
| ```CERT_VerifyCertNow`` <#1058011>`__
| ```CERT_VerifyCertName`` <#1050342>`__
| ```CERT_CheckCertValidTimes`` <#1056662>`__
| ```NSS_CmpCertChainWCANames`` <#1056760>`__
.. rubric:: CERT_VerifyCertNow
:name: 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
:name: syntax
.. code::
#include <cert.h>
.. code::
SECStatus CERT_VerifyCertNow(
CERTCertDBHandle *handle,
CERTCertificate *cert,
PRBool checkSig,
SECCertUsage certUsage,
void *wincx);
.. rubric:: Parameters
:name: parameters
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. 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
:name: 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
:name: 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
:name: cert_verifycertname
Compares the common name specified in the subject DN for a certificate with a specified hostname.
.. rubric:: Syntax
:name: syntax_2
.. code::
#include <cert.h>
.. code::
SECStatus CERT_VerifyCertName(
CERTCertificate *cert,
char *hostname);
.. rubric:: Parameters
:name: parameters_2
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. 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
:name: returns_2
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
:name: description_2
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
:name: cert_checkcertvalidtimes
Checks whether a specified time is within a certificate's validity period.
.. rubric:: Syntax
:name: syntax_3
.. code::
#include <cert.h>
#include <certt.h>
.. code::
SECCertTimeValidity CERT_CheckCertValidTimes(
CERTCertificate *cert,
int64 t);
.. rubric:: Parameters
:name: parameters_3
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. 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
:name: returns_3
The function returns an enumerator of type ``SECCertTimeValidity``:
.. code::
typedef enum {
secCertTimeValid,
secCertTimeExpired,
secCertTimeNotValidYet
} SECCertTimeValidity;
.. rubric:: NSS_CmpCertChainWCANames
:name: 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
:name: syntax_4
.. code::
#include <nss.h>
.. code::
SECStatus NSS_CmpCertChainWCANames(
CERTCertificate *cert,
CERTDistNames *caNames);
.. rubric:: Parameters
:name: parameters_4
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. 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
:name: returns_4
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 <#manipulating_certificates>`__
----------------------------------------------------------
.. container::
| ```CERT_DupCertificate`` <#1058344>`__
| ```CERT_DestroyCertificate`` <#1050532>`__
.. rubric:: CERT_DupCertificate
:name: cert_dupcertificate
Makes a shallow copy of a specified certificate.
.. rubric:: Syntax
:name: syntax_5
.. code::
#include <cert.h>
.. code::
CERTCertificate *CERT_DupCertificate(CERTCertificate *c)
.. rubric:: Parameter
:name: parameter
This function has the following parameter:
+-------------------------------------------------+-------------------------------------------------+
| .. code:: | A pointer to the certificate object to be |
| | duplicated. |
| c | |
+-------------------------------------------------+-------------------------------------------------+
.. rubric:: Returns
:name: returns_5
If successful, the function returns a pointer to a certificate object of type
```CERTCertificate`` <ssltyp.html#1027387>`__.
.. rubric:: Description
:name: description_3
The ``CERT_DupCertificate`` function increments the reference count for the certificate passed in
the ``c`` parameter.
.. rubric:: CERT_DestroyCertificate
:name: cert_destroycertificate
Destroys a certificate object.
.. rubric:: Syntax
:name: syntax_6
.. code::
#include <cert.h>
#include <certt.h>
.. code::
void CERT_DestroyCertificate(CERTCertificate *cert);
.. rubric:: Parameters
:name: parameters_5
This function has the following parameter:
+-------------------------------------------------+-------------------------------------------------+
| .. code:: | A pointer to the certificate to destroy. |
| | |
| cert | |
+-------------------------------------------------+-------------------------------------------------+
.. rubric:: Description
:name: description_4
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 <#getting_certificate_information>`__
----------------------------------------------------------------------
.. container::
| ```CERT_FindCertByName`` <#1050345>`__
| ```CERT_GetCertNicknames`` <#1050346>`__
| ```CERT_FreeNicknames`` <#1050349>`__
| ```CERT_GetDefaultCertDB`` <#1052308>`__
| ```NSS_FindCertKEAType`` <#1056950>`__
.. rubric:: CERT_FindCertByName
:name: cert_findcertbyname
Finds the certificate in the certificate database with a specified DN.
.. rubric:: Syntax
:name: syntax_7
.. code::
#include <cert.h>
.. code::
CERTCertificate *CERT_FindCertByName (
CERTCertDBHandle *handle,
SECItem *name);
.. rubric:: Parameters
:name: parameters_6
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. code:: | A pointer to the certificate database handle. |
| | |
| handle | |
+-------------------------------------------------+-------------------------------------------------+
| .. code:: | The subject DN of the certificate you wish to |
| | find. |
| name | |
+-------------------------------------------------+-------------------------------------------------+
.. rubric:: Returns
:name: returns_6
If successful, the function returns a certificate object of type
```CERTCertificate`` <ssltyp.html#1027387>`__.
.. rubric:: CERT_GetCertNicknames
:name: cert_getcertnicknames
Returns the nicknames of the certificates in a specified certificate database.
.. rubric:: Syntax
:name: syntax_8
.. code::
#include <cert.h>
#include <certt.h>
.. code::
CERTCertNicknames *CERT_GetCertNicknames (
CERTCertDBHandle *handle,
int what,
void *wincx);
.. rubric:: Parameters
:name: parameters_7
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. 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
:name: returns_7
The function returns a ``CERTCertNicknames`` object containing the requested nicknames.
.. rubric:: Description
:name: description_5
``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
:name: cert_freenicknames
Frees a ``CERTCertNicknames`` structure. This structure is returned by
```CERT_GetCertNicknames`` <#1050346>`__.
.. rubric:: Syntax
:name: syntax_9
.. code::
#include <cert.h>
.. code::
void CERT_FreeNicknames(CERTCertNicknames *nicknames);
.. rubric:: Parameters
:name: parameters_8
This function has the following parameter:
+-------------------------------------------------+-------------------------------------------------+
| .. code:: | A pointer to the ``CERTCertNicknames`` |
| | structure to be freed. |
| nicknames | |
+-------------------------------------------------+-------------------------------------------------+
.. rubric:: CERT_GetDefaultCertDB
:name: cert_getdefaultcertdb
Returns a handle to the default certificate database.
.. rubric:: Syntax
:name: syntax_10
.. code::
#include <cert.h>
.. code::
CERTCertDBHandle *CERT_GetDefaultCertDB(void);
.. rubric:: Returns
:name: returns_8
The function returns the ```CERTCertDBHandle`` <ssltyp.html#1028465>`__ for the default
certificate database.
.. rubric:: Description
:name: description_6
This function is useful for determining whether the default certificate database has been opened.
.. rubric:: NSS_FindCertKEAType
:name: nss_findcertkeatype
Returns key exchange type of the keys in an SSL server certificate.
.. rubric:: Syntax
:name: syntax_11
.. code::
#include <nss.h>
.. code::
SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);
.. rubric:: Parameter
:name: parameter_2
This function has the following parameter:
+-------------------------------------------------+-------------------------------------------------+
| .. code:: | The certificate to check. |
| | |
| a | |
+-------------------------------------------------+-------------------------------------------------+
.. rubric:: Returns
:name: returns_9
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 <#comparing_secitem_objects>`__
----------------------------------------------------------
.. container::
.. rubric:: SECITEM_CompareItem
:name: secitem_compareitem
Compares two ```SECItem`` <ssltyp.html#1026076>`__ objects and returns a ``SECComparison``
enumerator that shows the difference between them.
.. rubric:: Syntax
:name: syntax_12
.. code::
#include <secitem.h>
#include <seccomon.h>
.. code::
SECComparison SECITEM_CompareItem(
SECItem *a,
SECItem *b);
.. rubric:: Parameters
:name: parameters_9
This function has the following parameters:
+-------------------------------------------------+-------------------------------------------------+
| .. 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
:name: returns_10
The function returns an enumerator of type ``SECComparison``.
.. code::
typedef enum _SECComparison {
SECLessThan = -1,
SECEqual = 0,
SECGreaterThan = 1
} SECComparison;