Module X509.CRL

X.509 Certificate Revocation Lists.

A certificate revocation list is a signed structure consisting of an issuer, a timestamp, possibly a timestamp when to expect the next update, and a list of revoked certificates (represented by a serial, a revocation date, and extensions (e.g. reason) - see RFC 5280 section 5.2 for a list of available extensions (not enforced)). It also may contain any extensions, e.g. a CRL number and whether it is partial or complete.

type t

The type of a revocation list, kept abstract.

Encoding and decoding in ASN.1 DER format

val encode_der : t -> string

encode_der crl is buffer, the ASN.1 DER encoding of the given certificate revocation list.

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

decode_der buffer is crl, the certificate revocation list of the ASN.1 encoded buffer.

Operations on CRLs

val issuer : t -> Distinguished_name.t

issuer c is the issuer of the revocation list.

val this_update : t -> Ptime.t

this_update t is the timestamp of the revocation list.

val next_update : t -> Ptime.t option

next_update t is either None or Some ts, the timestamp of the next update.

type revoked_cert = {
  1. serial : string;
  2. date : Ptime.t;
  3. extensions : Extension.t;
}

The type of a revoked certificate, which consists of a serial number, the revocation date, and possibly extensions. See RFC 5280 section 5.3 for allowed extensions (not enforced).

val reason : revoked_cert -> Extension.reason option

reason revoked extracts the Reason extension from revoked if present.

val revoked_certificates : t -> revoked_cert list

revoked_certificates t is the list of revoked certificates of the revocation list.

val extensions : t -> Extension.t

extensions t is the list of extensions, see RFC 5280 section 5.2 for possible values.

val crl_number : t -> int option

crl_number t is the number of the CRL.

val signature_algorithm : t -> (Key_type.signature_scheme * Digestif.hash') option

signature_algorithm t is the algorithm used for the signature.

Validation and verification of CRLs

val validate : t -> ?allowed_hashes:Digestif.hash' list -> Public_key.t -> (unit, [> Validation.signature_error ]) Stdlib.result

validate t ~allowed_hashes pk validates the digital signature of the revocation list. The allowed_hashes defaults to SHA-2.

type verification_error = [
  1. | Validation.signature_error
  2. | `Issuer_subject_mismatch of Distinguished_name.t * Distinguished_name.t
  3. | `Not_yet_valid of Distinguished_name.t * Ptime.t * Ptime.t
  4. | `Next_update_scheduled of Distinguished_name.t * Ptime.t * Ptime.t
]

The type of CRL verification errors.

val pp_verification_error : verification_error Fmt.t

pp_verification_error ppf vere pretty-prints the CRL verification error vere on ppf.

val verify : t -> ?allowed_hashes:Digestif.hash' list -> ?time:Ptime.t -> Certificate.t -> (unit, [> verification_error ]) Stdlib.result

verify t ~allowed_hashes ~time cert verifies that the issuer of t matches the subject of cert, and validates the digital signature of the revocation list. The used hash algorithm must be in the allowed_hashes (defaults to SHA-2). If time is provided, it must be after this_update and before next_update of t.

val is_revoked : ?allowed_hashes:Digestif.hash' list -> issuer:Certificate.t -> cert:Certificate.t -> t list -> bool

is_revoked ~allowed_hashes ~issuer ~cert crls is true if there exists a revocation of cert in crls which is signed by the issuer. The subject of issuer must match the issuer of the crl. The hash algorithm used for signing must be in the allowed_hashes (defaults to SHA-2).

Construction and signing of CRLs

val revoke : ?digest:Digestif.hash' -> issuer:Distinguished_name.t -> this_update:Ptime.t -> ?next_update:Ptime.t -> ?extensions:Extension.t -> revoked_cert list -> Private_key.t -> (t, [> `Msg of string ]) Stdlib.result

revoked ~digest ~issuer ~this_update ~next_update ~extensions certs priv constructs a revocation list with the given parameters.

val revoke_certificate : revoked_cert -> this_update:Ptime.t -> ?next_update:Ptime.t -> t -> Private_key.t -> (t, [> `Msg of string ]) Stdlib.result

revoke_certificate cert ~this_update ~next_update t priv adds cert to the revocation list, increments its counter, adjusts this_update and next_update timestamps, and digitally signs it using priv.

val revoke_certificates : revoked_cert list -> this_update:Ptime.t -> ?next_update:Ptime.t -> t -> Private_key.t -> (t, [> `Msg of string ]) Stdlib.result

revoke_certificates certs ~this_update ~next_update t priv adds certs to the revocation list, increments its counter, adjusts this_update and next_update timestamps, and digitally signs it using priv.