(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 ``` ```{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 ``` ```{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 #include ``` ```{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 ``` ```{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 ``` ```{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 `` \\`\_\_. ```{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: ```{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 `` \\`\_\_, 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 ``` ```{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 `` \\`\_\_. ```{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: ```{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 ``` ```{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 ``` ```{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: ```{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 `` \\`\_\_ 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: ```{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; ``` :::