package x509

  1. Overview
  2. Docs

X509 encoding, generation, and validation.

X509 is a module for handling X.509 certificates, 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 public keys of trusted CAs are distributed with the software, or configured manually. When an endpoint connects, it has to present 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 provides parsers and unparsers (PEM encoding) of ASN.1 encoded X.509 certificates, public and private RSA keys (PKCS 8, RFC 5208), and certificate signing requests (PKCS 10, RFC 2986) (both require parts of PKCS9, RFC 2985), validation of certificates, and construction of authenticators. Name validation, as defined in RFC 6125, is also implemented. The CA module provides functionality to create and sign CSR.

Missing is the handling of online certificate status protocol, some X.509v3 extensions (such as policy and name constraints). The only supported key type is RSA.

0.6.3 - homepage

Abstract certificate type

type t

The abstract type of a certificate, with encoding and decoding to PEM.

val t_of_sexp : Sexplib.Sexp.t -> t

t_of_sexp sexp is certificate, the unmarshalled sexp.

val sexp_of_t : t -> Sexplib.Sexp.t

sexp_of_t certificate is sexp, the marshalled certificate.

Basic operations on a certificate

type key_type = [
  1. | `RSA
  2. | `EC of Asn.oid
]

The polymorphic variant of public key types.

val supports_keytype : t -> key_type -> bool

supports_keytype certificate key_type is result, whether public key of the certificate matches the given key_type.

type public_key = [
  1. | `RSA of Nocrypto.Rsa.pub
  2. | `EC_pub of Asn.oid
]

The polymorphic variant of public keys, with PKCS 8 encoding and decoding to PEM.

val key_id : public_key -> Cstruct.t

key_id public_key is result, the 160-bit `SHA1 hash of the BIT STRING subjectPublicKey (excluding tag, length, and number of unused bits) for publicKeyInfo of public_key.

RFC 5280, 4.2.1.2, variant (1)

val key_fingerprint : ?hash:Nocrypto.Hash.hash -> public_key -> Cstruct.t

key_fingerprint ?hash public_key is result, the hash (by default SHA256) of the DER encoded public key (equivalent to `openssl x509 -noout -pubkey | openssl pkey -pubin -outform DER | openssl dgst -HASH`).

type private_key = [
  1. | `RSA of Nocrypto.Rsa.priv
]

The polymorphic variant of private keys, with PKCS 8 encoding and decoding to PEM.

val public_key : t -> public_key

public_key certificate is pubkey, the public key of the certificate.

val hostnames : t -> string list

hostnames certficate are hostnames, the list of hostnames this certificate is valid for. Currently, these are the DNS names of the Subject Alternative Name extension, if present, or otherwise the singleton list containing the common name.

type host = [
  1. | `Strict of string
  2. | `Wildcard of string
]

The polymorphic variant for hostname validation.

val supports_hostname : t -> host -> bool

supports_hostname certificate host is result, whether the certificate contains the given host, using hostnames.

val common_name_to_string : t -> string

common_name_to_string certificate is common_name, the common name of the subject of the certificate.

type component = [
  1. | `CN of string
  2. | `Serialnumber of string
  3. | `C of string
  4. | `L of string
  5. | `SP of string
  6. | `O of string
  7. | `OU of string
  8. | `T of string
  9. | `DNQ of string
  10. | `Mail of string
  11. | `DC of string
  12. | `Given_name of string
  13. | `Surname of string
  14. | `Initials of string
  15. | `Pseudonym of string
  16. | `Generation of string
  17. | `Other of Asn.oid * string
]

The polymorphic variant of a distinguished name component, as defined in X.500.

type distinguished_name = component list

A distinguished name is a list of component.

val distinguished_name_of_sexp : Sexplib.Sexp.t -> distinguished_name

distinguished_name_of_sexp sexp is a distinguished_name, the unmarshalled sexp.

val sexp_of_distinguished_name : distinguished_name -> Sexplib.Sexp.t

sexp_of_distinguished_name dn is sexp, the marshalled dn.

val distinguished_name_to_string : distinguished_name -> string

distinguished_name_to_string dn is string, the string representation of the dn.

val fingerprint : Nocrypto.Hash.hash -> t -> Cstruct.t

fingerprint hash cert is digest, the digest of cert using the specified hash algorithm

val subject : t -> distinguished_name

subject certificate is dn, the subject as dn of the certificate.

val issuer : t -> distinguished_name

issuer certificate is dn, the issuer as dn of the certificate.

val serial : t -> Z.t

serial certificate is sn, the serial number of the certificate.

val validity : t -> Ptime.t * Ptime.t

validity certificate is from, until, the validity of the certificate.

module Extension : sig ... end

X.509v3 extensions

module CA : sig ... end

Certificate Authority operations

module CRL : sig ... end

X.509 Certificate Revocation Lists.

module Validation : sig ... end

X.509 Certificate Chain Validation.

module Authenticator : sig ... end

Authenticators of certificate chains

module Encoding : sig ... end

Encodings