x509 0.5.2 · OCaml Package

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 = [

| `RSA
| `EC of Asn.OID.t

]

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 = [

| `RSA of Nocrypto.Rsa.pub
| `EC_pub of Asn.OID.t

]

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 = [

| `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 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 = [

| `CN of string
| `Serialnumber of string
| `C of string
| `L of string
| `SP of string
| `O of string
| `OU of string
| `T of string
| `DNQ of string
| `Mail of string
| `DC of string
| `Given_name of string
| `Surname of string
| `Initials of string
| `Pseudonym of string
| `Generation of string
| `Other of Asn.OID.t * 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_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

Encodings

package x509

Abstract certificate type

Basic operations on a certificate