Module X509

module X509: sig .. end
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 certificate revocation lists, online certificate status protocol, some X.509v3 extensions (such as policy and name constraints). The only supported key type is RSA.

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 = [ `EC of Asn.OID.t | `RSA ] 
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 = [ `EC_pub of Asn.OID.t | `RSA of ] 
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,, 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 = [ `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 = [ `Strict of string | `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 X509.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 = [ `C of string
| `CN of string
| `DC of string
| `DNQ of string
| `Generation of string
| `Given_name of string
| `Initials of string
| `L of string
| `Mail of string
| `O of string
| `OU of string
| `Other of Asn.OID.t * string
| `Pseudonym of string
| `SP of string
| `Serialnumber of string
| `Surname of string
| `T of 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 X509.component.
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.
module Extension: sig .. end
X.509v3 extensions
module CA: sig .. end
Certificate Authority operations
module Validation: sig .. end
X.509 Certificate Chain Validation.
module Authenticator: sig .. end
Authenticators of certificate chains
module Encoding: sig .. end