NSS Certificate Functions

Syntax

#include <cert.h> 

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

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.

Returns

The function returns one of these values:

• If successful, SECSuccess.
• If unsuccessful, SECFailure. Use PR_GetError 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 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.

Syntax

#include <cert.h> 

SECStatus CERT_VerifyCert(
  CERTCertDBHandle *handle, 
  CERTCertificate *cert,
  PRBool checkSig, 
  SECCertUsage certUsage,
  int 64 t, 
  void *wincx
  CERTVerifyLog *log);

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

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 Using CERTVerifyLog for more information.

Returns

The function returns one of these values:

• If successful, SECSuccess.
• If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.

Description

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.

Syntax

#include <cert.h>

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

Parameters

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.

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 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.

Syntax

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

SECCertTimeValidity CERT_CheckCertValidTimes(
  CERTCertificate *cert,
  int64 t);

Parameters

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.

Returns

The function returns an enumerator of type SECCertTimeValidity:

typedef enum {
  secCertTimeValid,
  secCertTimeExpired,
  secCertTimeNotValidYet
} SECCertTimeValidity;

Syntax

#include <nss.h>

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

Parameters

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.

Returns

The function returns one of these values:

• If successful, SECSuccess.
• If unsuccessful, SECFailure. Use PR_GetError to obtain the error code.

Syntax

#include <cert.h>

CERTCertificate *CERT_DupCertificate(CERTCertificate *c)

Parameter

This function has the following parameter:

c A pointer to the certificate object to be duplicated.

Returns

If successful, the function returns a pointer to a certificate object of type CERTCertificate.

Description

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

Syntax

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

void CERT_DestroyCertificate(CERTCertificate *cert);

Parameters

This function has the following parameter:

cert A pointer to the certificate to destroy.

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 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.

Syntax

#include <cert.h>

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

Parameters

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.

Returns

If successful, the function returns a certificate object of type CERTCertificate.

Syntax

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

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

Parameters

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.

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 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.

Syntax

#include <cert.h>

void CERT_FreeNicknames(CERTCertNicknames *nicknames);

Parameters

This function has the following parameter:

nicknames A pointer to the CERTCertNicknames structure to be freed.

Syntax

#include <cert.h>

CERTCertDBHandle *CERT_GetDefaultCertDB(void);

Returns

The function returns the CERTCertDBHandle for the default certificate database.

Description

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

Syntax

#include <nss.h>

SSLKEAType NSS_FindCertKEAType(CERTCertificate * cert);

Parameter

This function has the following parameter:

a The certificate to check.

Returns

The function returns one of these values:

• kt_null = 0
• kt_rsa
• kt_dh
• kt_fortezza
• kt_kea_size

Syntax

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

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

Parameters

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.

Returns

The function returns an enumerator of type SECComparison.

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