X.509 Module Level Design
This document describes the internal function of the mbed TLS X.509 module.
Note: The writing part of the X.509 module is not (yet) covered in this document.
The X.509 module provides the structures and functions to manage X.509 certificates.
It is responsible for:
This module interacts with the following other modules:
The internal design has two functions:
All functions are prefixed x509_ for coherence.
The parsing process differs per X.509 element. The following object types can be parsed:
The certificates may be DER and PEM (base64) encoded.
At least Basic Constraints, Key Usage, Extended Key Usage, Subject Alt Name and NS Cert Type 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 the structures section. Some examples of how these structures are used are:
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.
This module implements the following data structures:
These structures are initialised and added to with the parsing functions described in the parsing section.
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.
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:
The following scenarios are described:
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.
All uses are: