PolarSSL X.509 module MLD

Introduction

This document describes the internal function of the PolarSSL X.509 module.

Component overview

The X.509 module provides the structures and functions to manage X.509 certificates.

It is responsible for:

• Parsing and verifying X.509 certificates.
• Parsing and verifying X.509 certificate revocation lists (CRLs).
• Parsing and verifying RSA private keys and signatures.

This module interacts with the following other modules:

• Asymmetric cryptography module (Asym) for key parsing and signature verification
• Hashing module for signature verification

Component design

The internal design has two functions:

1. Parsing: RSA private keys, certificates and CRLs structures are initialized from a buffer or a file.
2. Verification: certificates and times can be verified.

All functions are prefixed x509_ for coherence.

Parsing function

The parsing process differs per X.509 element. The following object types can be parsed:

• Parsing an RSA private key yields a RSA context structure.
• Parsing a certificate adds to the end of a certificate-chain; the root certificate authority (CA) input must be parsed last.
• Parsing a CRL adds to the end of a CRL-chain. Each CRL contains a list of revocation entries from a specific CA.

The certificates may be DER and base64 encoded.

Only Basic Constraints are supported in the extensions.

All parsing functions return 0 on success and an OR-ed error code on error. On success, an initialized structure is assigned to the passed in pointer parameter. On failure, the pointer parameter is not modified.

The data is parsed to the structures in structures section. Some examples of how these structures are used are:

• ASN.1-structure: DER, which is an X.509 standard for encoding a certificate, e.g. 01 02 05 means type is integer, length is 2 octets (16 bits), value is 5.
• named information object-structure: Distinguished Name (DN), e.g. O=Fox-IT,OU=Crypto,CN=Distinguished Name.

Verification function

Time verification checks whether a time structure has expired. A time structure has expired when the point in time it represents is earlier than current local time.

Certificate verification is an all-in-one verification function that checks a certificate chain against a trusted CA chain and a CRL-chain. All three chains are passed in as function parameters. The certificate being verified is checked for expiration, revocation, common name (CN) mismatch, and trusted signature.

Used structures

This module implements the following data structures:

• x509_cert for certificate chains
• x509_crl for CRL chains

These structures are initialised and added to with the parsing functions described in the parsing section.

For the RSA private key handling the X.509 module makes use of the RSA context structure and parsing function as implemented by the Asym module.

The certificate and CRL structures allow for the X.509 v3 and v2 standard respectively, the latest version of which is described in  RFC 5280. Most values are represented in a type-length-value structure that implements the Abstract Syntax Notation One (ASN.1) standard in a flexible way. A chained variation uses this structure for named information objects.

Both the certificate and CRL structures contain a next-element to create a chain. The list of revocation entries inside the CRL structure is implemented in the same way.

Internal state

No internal state is kept within this module between function calls. All context structures are stateless. State is communicated as a return value.

The following sequence of activities is typical within a function call to this module:

Scenarios

The following scenarios are described:

• Load a valid certificate from a file
• Load a revoked certificate from a buffer
• Complex usage: exchange certificates

Load a valid certificate from a file

This scenario describes an application that uses the X.509 module to load a certificate from a file.

Load a revoked certificate from a buffer

This scenario describes an application that uses the X.509 module to load a certificate which has been revoked. The certificate is loaded from a buffer in memory.

Complex usage: exchange certificates

A typical scenario is that Alice wants to communicate securely with Bob. In order to do so she receives a certificate from Bob, either as a buffer or a file. Using the X.509 module she can parse the certificate and verify its validity. When Bob does the same with Alice's certificate, they can communicate securely.

Use cases

All uses are:

• Parse a certificate. A certificate includes information needed for secure communication.
• Parse a private key. A private key is needed to sign or decrypt a message.
• Parse a CRL. A list of entries with certificate revocation information.
• Verify a certificate. On success an application may decide to trust and use the certificate.