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 using Distinguished_name.matches, 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 using Distinguished_name.matches. Nonmatching CRLs are ignored; false does not establish that cert is unrevoked. The hash algorithm used for signing must be in 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.