Source code
Revision control
Copy as Markdown
Other Tools
.. _mozilla_projects_nss_reference_nss_certificate_functions:
NSS Certificate Functions
=========================
.. _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
- :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
:name: 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
: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:
*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
:name: returns
The function returns one of these values:
- If successful, SECSuccess.
- If unsuccessful, SECFailure. Use PR_GetError 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 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
:name: syntax_2
.. 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
:name: parameters_2
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
:name: returns_2
The function returns one of these values:
- If successful, SECSuccess.
- If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.
.. rubric:: Description
:name: description_2
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
:name: cert_verifycertname
Compares the common name specified in the subject DN for a certificate with a specified hostname.
.. rubric:: Syntax
:name: syntax_3
.. code::
#include <cert.h>
.. code::
SECStatus CERT_VerifyCertName(
CERTCertificate *cert,
char *hostname);
.. rubric:: Parameters
:name: parameters_3
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
:name: returns_3
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
:name: description_3
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_4
.. code::
#include <cert.h>
#include <certt.h>
.. code::
SECCertTimeValidity CERT_CheckCertValidTimes(
CERTCertificate *cert,
int64 t);
.. rubric:: Parameters
:name: parameters_4
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
:name: returns_4
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_5
.. code::
#include <nss.h>
SECStatus NSS_CmpCertChainWCANames(
CERTCertificate *cert,
CERTDistNames *caNames);
.. rubric:: Parameters
:name: parameters_5
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
:name: returns_5
The function returns one of these values:
- If successful, SECSuccess.
- If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.
.. rubric:: Manipulating Certificates
:name: manipulating_certificates
- `CERT_DupCertificate <#cert_dupcertificate>`__
- `CERT_DestroyCertificate <#cert_destroycertificate>`__
.. rubric:: CERT_DupCertificate
:name: cert_dupcertificate
Makes a shallow copy of a specified certificate.
.. rubric:: Syntax
:name: syntax_6
.. code::
#include <cert.h>
.. code::
CERTCertificate *CERT_DupCertificate(CERTCertificate *c)
.. rubric:: Parameter
:name: parameter
This function has the following parameter:
*c*\ A pointer to the certificate object to be duplicated.
.. rubric:: Returns
:name: returns_6
If successful, the function returns a pointer to a certificate object of type CERTCertificate.
.. rubric:: Description
:name: description_4
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_7
.. code::
#include <cert.h>
#include <certt.h>
.. code::
void CERT_DestroyCertificate(CERTCertificate *cert);
.. rubric:: Parameters
:name: parameters_6
This function has the following parameter:
*cert*\ A pointer to the certificate to destroy.
.. rubric:: Description
:name: description_5
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
:name: 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
:name: cert_findcertbyname
Finds the certificate in the certificate database with a specified DN.
.. rubric:: Syntax
:name: syntax_8
.. code::
#include <cert.h>
.. code::
CERTCertificate *CERT_FindCertByName (
CERTCertDBHandle *handle,
SECItem *name);
.. rubric:: Parameters
:name: parameters_7
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
:name: returns_7
If successful, the function returns a certificate object of type CERTCertificate.
.. rubric:: CERT_GetCertNicknames
:name: cert_getcertnicknames
Returns the nicknames of the certificates in a specified certificate database.
.. rubric:: Syntax
:name: syntax_9
.. code::
#include <cert.h>
#include <certt.h>
.. code::
CERTCertNicknames *CERT_GetCertNicknames (
CERTCertDBHandle *handle,
int what,
void *wincx);
.. rubric:: Parameters
:name: parameters_8
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
:name: returns_8
The function returns a CERTCertNicknames object containing the requested nicknames.
.. rubric:: Description
:name: description_6
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
:name: cert_freenicknames
Frees a CERTCertNicknames structure. This structure is returned by CERT_GetCertNicknames.
.. rubric:: Syntax
:name: syntax_10
.. code::
#include <cert.h>
.. code::
void CERT_FreeNicknames(CERTCertNicknames *nicknames);
.. rubric:: Parameters
:name: parameters_9
This function has the following parameter:
*nicknames*\ A pointer to the CERTCertNicknames structure to be freed.
.. rubric:: CERT_GetDefaultCertDB
:name: cert_getdefaultcertdb
Returns a handle to the default certificate database.
.. rubric:: Syntax
:name: syntax_11
.. code::
#include <cert.h>
.. code::
CERTCertDBHandle *CERT_GetDefaultCertDB(void);
.. rubric:: Returns
:name: returns_9
The function returns the CERTCertDBHandle for the default certificate database.
.. rubric:: Description
:name: description_7
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_12
.. code::
#include <nss.h>
.. code::
SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);
.. rubric:: Parameter
:name: parameter_2
This function has the following parameter:
*a*\ The certificate to check.
.. rubric:: Returns
:name: returns_10
The function returns one of these values:
- kt_null = 0
- kt_rsa
- kt_dh
- kt_fortezza
- kt_kea_size
.. rubric:: Comparing SecItem Objects
:name: comparing_secitem_objects
.. rubric:: SECITEM_CompareItem
:name: secitem_compareitem
Compares two SECItem objects and returns a SECComparison enumerator that shows the difference
between them.
.. rubric:: Syntax
:name: syntax_13
.. code::
#include <secitem.h>
#include <seccomon.h>
.. code::
SECComparison SECITEM_CompareItem(
SECItem *a,
SECItem *b);
.. rubric:: Parameters
:name: parameters_10
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
:name: returns_11
The function returns an enumerator of type SECComparison.
.. code::
typedef enum _SECComparison {
SECLessThan = -1,
SECEqual = 0,
SECGreaterThan = 1
} SECComparison;