nss tech note4

Pulling certificate extension information out of SSL certificates

NSS Technical Note: 4

Note: This document contains code snippets that focus on essential aspects of the task and often do not illustrate all the cleanup that needs to be done. Also, this document does not attempt to be an exhaustive survey of all possible ways to do a certain task; it merely tries to show a certain way. .. rubric:: Include these files

name

include_these_files

#include “ssl.h” #include “cert.h” .. rubric:: Get the handle of the cert associated with an SSL connection

name

get_the_handle_of_the_cert_associated_with_an_ssl_connection

CERTCertificate* cert = SSL_PeerCertificate(PRFileDesc *fd);

If SSL client, this will get you the server’s cert handle; If SSL server, this will get you the client’s cert handle IF client auth is enabled

CERTCertificate* cert = SSL_LocalCertificate(PRFileDesc *fd);

If SSL client, this will get you the client cert’s handle, IF client auth happened If SSL server, this will get you the server’s cert handle

Don’t forget to clean up the cert handle when you’re done with it

void CERT_DestroyCertificate(CERTCertificate *cert); .. rubric:: Some info is readily available

name

some_info_is_readily_available

cert->subjectName (char*) cert->issuerName (char*) cert->emailAddr (char*)

OR char *CERT_GetCertificateEmailAddress(CERTCertificate *cert);

cert->keyUsage (unsigned int) .. rubric:: To break the issuer and subject names into components

name

to_break_the_issuer_and_subject_names_into_components

Pass &(cert->issuer) or &(cert->subject) to the following functions

char *CERT_GetCommonName(CERTName *name); char *CERT_GetCertEmailAddress(CERTName *name); char *CERT_GetCountryName(CERTName *name); char *CERT_GetLocalityName(CERTName *name); char *CERT_GetStateName(CERTName *name); char *CERT_GetOrgName(CERTName *name); char *CERT_GetOrgUnitName(CERTName *name); char *CERT_GetDomainComponentName(CERTName *name); char *CERT_GetCertUid(CERTName *name);

Example code to illustrate access to the info is given below. .. rubric:: Background on cert extensions

name

background_on_cert_extensions

An extension has the following attributes

  • Object Id (OID) : A unique OID represents an algorithm, a mechanism, a piece of information, etc. Examples: X500 RSA Encryption, Certificate Basic Constraints, PKCS#7 Digested Data, etc. There is a long list of pre-defined OIDs, and new ones can be added dynamically by an application. The OID data structure contains an array of identifier bytes (each byte is a “level” in a hierarchical namespace), a text description, and some other things.

  • Critical : indicates whether the extension is critical

  • Value : The value of the extension

Some miscellaneous helper functions

  • Compare two SECItems (e.g., two OIDs) PRBool SECITEM_ItemsAreEqual(const SECItem *a, const SECItem *b);

  • Interpreting a SECItem value as an integer If SECItem *item->len <=4, then int value = DER_GetInteger(item);

  • Interpreting a SECItem value as a string Use string copy functions to copy item->len bytes from item->data and null terminate explicitly

Some higher level extension functions

  • Get a specific extension from the list of extensions, given the extension tag SECStatus CERT_FindCertExtension (CERTCertificate *cert, int tag, SECItem *value);

  • Get a specific extension from the ISSUER’s cert* SECStatus CERT_FindIssuerCertExtension (CERTCertificate *cert, int tag, SECItem *value);*

  • Get the value of an extension with the given OID SECStatus CERT_FindCertExtensionByOID (CERTCertificate *cert, SECItem *oid, SECItem *value);

  • Get the decoded value of the “Basic Constraints” extension SECStatus CERT_FindBasicConstraintExten (CERTCertificate *cert, CERTBasicConstraints *value);

  • Get value of the keyUsage extension. This uses PR_Alloc to allocate buffer for the decoded value, The caller should free up the storage allocated in value->data. SECStatus CERT_FindKeyUsageExtension (CERTCertificate *cert, SECItem *value);

  • Get decoded value of the subjectKeyID extension. This uses PR_Alloc to allocate buffer for the decoded value, The caller should free up the storage allocated in value->data. SECStatus CERT_FindSubjectKeyIDExten (CERTCertificate *cert, SECItem *retItem);

For more information