X509_certchain (bytesrw.Bytesrw_tls.X509

Certificate chains

type t

The type for a certificate chain or a set of certificate.

Order. This may be a proper chain or not. When used as a chain, the certificates are assumed to be ordered as a list from leaf to root. If it's not a chain but for example the set of trusted certificate authorities of a client, the order does not matter.

val concat : t list -> t

concat css appends the certificates chains css from left to right. If the result is ordered the leaf is the leaf of List.hd css.

raises Invalid_argument
if css is empty.

val leaf : t -> t

leaf cs is the leaf certificate of c as a singleton chain.

val fold : ('a -> t -> 'a) -> 'a -> t -> 'a

fold f acc cs folds f over the individual certificates of cs starting with acc.

PEM format

PEM is plain text with DER certificates encoded in Base64 surrounded by specific begin/end headers. It can contain lists of certificates. If those are meant to be ordered they are expected to be read in leaf to root order. PEM files can be easily concatenated by separating them with newlines.

val of_pem : ?file:string -> string -> (t, string) Stdlib.result

of_pem s parses a certificate chain from bytes s which are assumed to be in PEM format and have been read from file (defaults to "-", only used for error messages). If you expect a chain, the certificates must be ordered from leaf to root in the data.

val to_pem : t -> string

to_pem cs is the certificate chain in PEM format. If the chain is ordered the result is ordered from leaf to root.

val read_pem_file : string -> (t, string) Stdlib.result

read_pem_file file reads certificates from file in PEM format using of_pem. The filename "-" can be used to read from stdin.

Note. Material loaded by this function can be seen by the GC.

DER format

val of_der_certs : string list -> (t, string) Stdlib.result

of_der_certs der_certs is a certificate chain from the list of individual certificates in DER format. If those are meant to be ordered they must be sorted from leaf to root.

raises Invalid_argument
if der_certs is empty.

val fold_der_certs : ('acc -> string -> 'acc) -> 'acc -> t -> 'acc

fold_der_certs f acc cs folds with f over the raw certificates in DER format of cs. If the certificate are ordered they are fold over from leaf to root.

System CA certificates

val system_ca_certs : unit -> (t option, string) Stdlib.result

system_ca_certs () tries to load the set of certificates of certification authorities (CA) that are trusted by your operating system using the procedure mentioned below. None is returned if none can be found.

The lookup is peformed as follows, in order.

If the SSL_CERT_FILE is set and non-empty, the certificates are loaded from the specified PEM file with of_pem. Note that such a file can be easily downloaded from curl's CA certificate extract.
On Windows it tries to load them from the "CA" certificate store.
On macOS it tries do load those returned by invoking SecTrustSettingsCopyCertificates on all domains (system, admin and user).
Otherwise it reads the first file that exists from the following list:
- /etc/ssl/certs/ca-certificates.crt
- /etc/ssl/cert.pem

Own certificate chains

module Private_key : sig ... end

Certificate private keys.

type own = t * Private_key.t

An own certificate is a certificate chain for which we have the private key for the leaf certificate.

Note. It's your duty to make sure the private and public key in the leaf certificate match. If they don't handshakes using the certificate will fail.

Self-signing

These are simple functions that can be used for generating certificates for development, see the certificate tips. They provide little control on the certificate fields. If you need fine grained control you may want to use something like ocaml-x509 but in practice you will likely get your certificates ready-made from certbot.

type ptime = float

The type POSIX time as returned by Unix.gettimeofday.

val self_signed : 
  ?private_key:Private_key.t ->
  ?invalid_before:float ->
  ?invalid_after:float ->
  ?is_ca:bool ->
  ?name:string ->
  unit ->
  (own, string) Stdlib.result

self_signed ~name () returns a self-signed certificate with:

name, the issuer and subject CN name. If ca is false this is also used to define a DNS subject alternative name, so it should be the DNS name of your host. Defaults to localhost.
is_ca, if true generates a certification authority certificate. This certificate is able to sign other certificates, see ca_signed. Defaults to false.
invalid_before, the time before which it is invalid. Defaults to current time as determined by Unix.gettimeofday.
invalid_after, the time after which it is invalid. Defaults to 47 days after invalid_before
private_key, if provided this is used for the private key. Otherwise a new one is generated with Private_key.generate.

val ca_signed : 
  ca:own ->
  ?private_key:Private_key.t ->
  ?invalid_before:float ->
  ?invalid_after:float ->
  ?name:string ->
  unit ->
  (own, string) Stdlib.result

ca_signed returns a certificate chain with the chain of ca and a new certificate signed by ca with:

name, the subject CN name and the DNS subject alternative name so it should be the DNS name of your host. Defaults to "localhost".
invalid_before, the time before which it is invalid. Defaults to current time as determined by Unix.gettimeofday.
invalid_after, the time after which it is invalid. Defaults to 47 days after invalid_before.
private_key, if provided this is used for the private key. Otherwise a new one is generated with Private_key.generate.

Formatting

val pp : Stdlib.Format.formatter -> t -> unit

pp formats a certificate chain for inspection in leaf to root order (if applicable).

val pp_pem : Stdlib.Format.formatter -> t -> unit

pp formats a certificate chain in PEM format in leaf to root order (if applicable).