Module X509

X509 encoding, generation, and validation.

X509 is a module for handling X.509 certificates and supplementary material (such as public and private RSA or EC keys), as described in RFC 5280. X.509 describes a hierarchical public key infrastructure, where all trust is delegated to certificate authorities (CA). The task of a CA is to sign certificate signing requests (CSR), which turns them into certificates, after verification that the requestor is eligible.

An X.509 certificate is an authentication token: a public key, a subject (e.g. server name), a validity period, optionally a purpose (usage), and various other optional Extensions. The overall approach of this package is to support decoding what is present in the real world, including weak ciphers (various validation functions support an allow list to avoid using weak hashes in chains if needed).

The public keys of trusted CAs are distributed with the software, or configured manually. When an endpoint connects, it presents its certificate chain, which are pairwise signed certificates. This chain is verified: the signatures have to be valid, the last certificate must be signed by a trusted CA, the name has to match the expected name, all certificates must be valid at the current time, and the purpose of each certificate must match its usage. An alternative validator checks that the hash of the server certificate matches the given hash.

This module uses the result type for errors. No provided binging raises an exception. Provided submodules include decoders and encoders (ASN.1 DER and PEM encoding) of X.509v3 certificates, distinguished names, public keys and private keys (PKCS 8, RFC 5208), and certificate signing requests (PKCS 10, RFC 2986, both use parts of PKCS 9, RFC 2985), certificate validation by construction of authenticators. Name validation, as defined in RFC 6125, is also implemented.

The archive format for certificates and private keys, PKCS 12, RFC 7292, is implemented in the PKCS12 submodule. While PKCS 12 decryption supports the weak algorithm used by default by widely used software (RC2!), the encryption path only supports AES.

Missing is the handling of online certificate status protocol. Some X.509v3 extensions are not handled, but only parsed, such as name constraints. If any extension is marked as critical in a certificate, but not handled, the validation will fail.

v0.16.0 - homepage

module Host : sig ... end

Hostnames (strict, wildcard), used for validation.

module Key_type : sig ... end

Types of keys

module Public_key : sig ... end

Public keys

module Private_key : sig ... end

Private keys

module Distinguished_name : sig ... end

X.500 distinguished name

module General_name : sig ... end

A list of general_names is the value of both subjectAltName and IssuerAltName extension.

module Extension : sig ... end

X.509v3 extensions

module Certificate : sig ... end

X509v3 certificate

module Validation : sig ... end

Chain Validation.

Certificate Signing request

module Signing_request : sig ... end

A certificate authority (CA) deals with PKCS 10 certificate signing requests, their construction and encoding, and provisioning using a private key to generate a certificate with a signature thereof.

module CRL : sig ... end

X.509 Certificate Revocation Lists.

module Authenticator : sig ... end

Certificate chain authenticators

module PKCS12 : sig ... end

PKCS12 archive files

module OCSP : sig ... end

OCSP (Online Certificate Status Protocol) as described in RFC 6960.