Module X509.Signing_request

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.

type t

The abstract type of a (self-signed) certification request.

Decoding and encoding in ASN.1 DER and PEM format

val decode_der : ?allowed_hashes:Mirage_crypto.Hash.hash list -> Cstruct.t -> (t, [> `Msg of string ]) Stdlib.result

decode_der ~allowed_hashes cstruct is signing_request, the ASN.1 decoded cstruct or an error. The signature on the signing request is validated, and its hash algorithm must be in allowed_hashes (by default only SHA-2 is accepted).

val encode_der : t -> Cstruct.t

encode_der sr is cstruct, the ASN.1 encoded representation of the sr.

val decode_pem : Cstruct.t -> (t, [> `Msg of string ]) Stdlib.result

decode_pem pem is t, where the single signing request of the pem is extracted

val encode_pem : t -> Cstruct.t

encode_pem signing_request is pem, the pem encoded signing request.

Construction of a signing request

module Ext : sig ... end
type request_info = {
  1. subject : Distinguished_name.t;
  2. public_key : Public_key.t;
  3. extensions : Ext.t;
}

The raw request info of a PKCS 10 certification request info.

val info : t -> request_info

info signing_request is request_info, the information inside the signing_request.

val signature_algorithm : t -> (Key_type.signature_scheme * Mirage_crypto.Hash.hash) option

signature_algorithm signing_request is the algorithm used for the signature.

val hostnames : t -> Host.Set.t

hostnames signing_request is the set of domain names this signing_request is requesting. This is either the content of the DNS entries of the SubjectAlternativeName extension, or the common name of the signing_request.

val create : Distinguished_name.t -> ?digest:Mirage_crypto.Hash.hash -> ?extensions:Ext.t -> Private_key.t -> (t, [> `Msg of string ]) Stdlib.result

create subject ~digest ~extensions private creates signing_request, a certification request using the given subject, digest (defaults to `SHA256) and list of extensions.

Provision a signing request to a certificate

val sign : t -> valid_from:Ptime.t -> valid_until:Ptime.t -> ?allowed_hashes:Mirage_crypto.Hash.hash list -> ?digest:Mirage_crypto.Hash.hash -> ?serial:Z.t -> ?extensions:Extension.t -> ?subject:Distinguished_name.t -> Private_key.t -> Distinguished_name.t -> (Certificate.t, Validation.signature_error) Stdlib.result

sign signing_request ~valid_from ~valid_until ~allowed_hashes ~digest ~serial ~extensions ~subject private issuer creates certificate, a signed certificate. Signing can fail if the signature on the signing_request is invalid, or its hash algorithm does not occur in allowed_hashes (default all SHA-2 algorithms). Public key and subject are taken from the signing_request unless subject is passed, the extensions are added to the X.509 certificate. The private key is used to sign the certificate, the issuer is recorded in the certificate. The digest defaults to `SHA256. The serial defaults to a random value between 1 and 2^64. Certificate version is always 3. Please note that the extensions in the signing_request are ignored, you can pass them using:

match Ext.find Extensions (info csr).extensions with
| Ok ext -> ext
| Error _ -> Extension.empty