sslcrt¶

Note

This page is part of the OLD SSL Reference that we are migrating into the format described in the MDN 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 NSS reference

Certificate Functions

`Chapter 5: <#chapter_5_certificate_functions>`__ Certificate Functions

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

Manipulating Certificates

Getting Certificate Information

Comparing SecItem Objects

Validating Certificates ¶

`CERT_VerifyCertNow <#1058011>`__

`CERT_VerifyCertName <#1050342>`__

`CERT_CheckCertValidTimes <#1056662>`__

`NSS_CmpCertChainWCANames <#1056760>`__

CERT_VerifyCertNow

Checks that the current date is within the certificate’s validity period and that the CA signature on the certificate is valid.

Syntax

#include <cert.h>

SECStatus CERT_VerifyCertNow(
   CERTCertDBHandle *handle,
   CERTCertificate *cert,
   PRBool checkSig,
   SECCertUsage certUsage,
   void *wincx);

Parameters

This function has the following parameters:

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.

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 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 mozilla_projects_nss_ssl_functions_sslfnc#1123385.

CERT_VerifyCertName

Compares the common name specified in the subject DN for a certificate with a specified hostname.

Syntax

#include <cert.h>

SECStatus CERT_VerifyCertName(
   CERTCertificate *cert,
   char *hostname);

Parameters

This function has the following parameters:

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.

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.

CERT_CheckCertValidTimes

Checks whether a specified time is within a certificate’s validity period.

Syntax

#include <cert.h>
#include <certt.h>

SECCertTimeValidity CERT_CheckCertValidTimes(
   CERTCertificate *cert,
   int64 t);

Parameters

This function has the following parameters:

Returns

The function returns an enumerator of type SECCertTimeValidity:

typedef enum {
   secCertTimeValid,
   secCertTimeExpired,
   secCertTimeNotValidYet
} SECCertTimeValidity;

NSS_CmpCertChainWCANames

Determines whether any of the signers in the certificate chain for a specified certificate are on a specified list of CA names.

Syntax

#include <nss.h>

SECStatus NSS_CmpCertChainWCANames(
   CERTCertificate *cert,
   CERTDistNames *caNames);

Parameters

This function has the following parameters:

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 ¶

`CERT_DupCertificate <#1058344>`__

`CERT_DestroyCertificate <#1050532>`__

CERT_DupCertificate

Makes a shallow copy of a specified certificate.

Syntax

#include <cert.h>

CERTCertificate *CERT_DupCertificate(CERTCertificate *c)

Parameter

This function has the following parameter:

Returns

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

Description

The CERT_DupCertificate function increments the reference count for the certificate passed in the c parameter.

CERT_DestroyCertificate

Destroys a certificate object.

Syntax

#include <cert.h>
#include <certt.h>

void CERT_DestroyCertificate(CERTCertificate *cert);

Parameters

This function has the following parameter:

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 ¶

`CERT_FindCertByName <#1050345>`__

`CERT_GetCertNicknames <#1050346>`__

`CERT_FreeNicknames <#1050349>`__

`CERT_GetDefaultCertDB <#1052308>`__

`NSS_FindCertKEAType <#1056950>`__

CERT_FindCertByName

Finds the certificate in the certificate database with a specified DN.

Syntax

#include <cert.h>

CERTCertificate *CERT_FindCertByName (
   CERTCertDBHandle *handle,
   SECItem *name);

Parameters

This function has the following parameters:

Returns

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

CERT_GetCertNicknames

Returns the nicknames of the certificates in a specified certificate database.

Syntax

#include <cert.h>
#include <certt.h>

CERTCertNicknames *CERT_GetCertNicknames (
   CERTCertDBHandle *handle,
   int what,
   void *wincx);

Parameters

This function has the following parameters:

Returns

The function returns a CERTCertNicknames object containing the requested nicknames.

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 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 mozilla_projects_nss_ssl_functions_sslfnc#1123385.

CERT_FreeNicknames

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

Syntax

#include <cert.h>

void CERT_FreeNicknames(CERTCertNicknames *nicknames);

Parameters

This function has the following parameter:

CERT_GetDefaultCertDB

Returns a handle to the default certificate database.

Syntax

#include <cert.h>

CERTCertDBHandle *CERT_GetDefaultCertDB(void);

Returns

The function returns the `CERTCertDBHandle <ssltyp.html#1028465>`__ for the default certificate database.

Description

This function is useful for determining whether the default certificate database has been opened.

NSS_FindCertKEAType

Returns key exchange type of the keys in an SSL server certificate.

Syntax

#include <nss.h>

SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);

Parameter

This function has the following parameter:

Returns

The function returns one of these values:

kt_null = 0
kt_rsa
kt_dh
kt_fortezza
kt_kea_size

Comparing SecItem Objects ¶

SECITEM_CompareItem

Compares two `SECItem <ssltyp.html#1026076>`__ objects and returns a SECComparison enumerator that shows the difference between them.

Syntax

#include <secitem.h>
#include <seccomon.h>

SECComparison SECITEM_CompareItem(
   SECItem *a,
   SECItem *b);

Parameters

This function has the following parameters:

Returns

The function returns an enumerator of type SECComparison.

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

sslcrt¶

Validating Certificates¶

Manipulating Certificates¶

Getting Certificate Information¶

Comparing SecItem Objects¶

Validating Certificates ¶

Manipulating Certificates ¶

Getting Certificate Information ¶

Comparing SecItem Objects ¶