tls 0.12.0 · OCaml Package

Configuration of the TLS stack

Config type

type certchain = Core.Cert.t list * Mirage_crypto_pk.Rsa.priv

certificate chain and private key of the first certificate

type own_cert = [

| `None
| `Single of certchain
| `Multiple of certchain list
| `Multiple_default of certchain * certchain list

]

polymorphic variant of own certificates

type session_cache = Core.SessionID.t -> Core.epoch_data option

type ticket_cache = {

lookup : Cstruct.t -> (Core.psk13 * Core.epoch_data) option;
ticket_granted : Core.psk13 -> Core.epoch_data -> unit;
lifetime : int32;
timestamp : unit -> Core.Ptime.t;

}

type ticket_cache_opt = ticket_cache option

type config = private {

ciphers : Ciphersuite.ciphersuite list;
(*
ordered list (regarding preference) of supported cipher suites
*)
protocol_versions : Core.tls_version * Core.tls_version;
(*
supported protocol versions (min, max)
*)
signature_algorithms : Core.signature_algorithm list;
(*
ordered list of supported signature algorithms (regarding preference)
*)
use_reneg : bool;
(*
endpoint should accept renegotiation requests
*)
authenticator : X509.Authenticator.t option;
(*
optional X509 authenticator
*)
peer_name : string option;
(*
optional name of other endpoint (used for SNI RFC4366)
*)
own_certificates : own_cert;
(*
optional default certificate chain and other certificate chains
*)
acceptable_cas : X509.Distinguished_name.t list;
(*
ordered list of acceptable certificate authorities
*)
session_cache : session_cache;
ticket_cache : ticket_cache_opt;
cached_session : Core.epoch_data option;
cached_ticket : (Core.psk13 * Core.epoch_data) option;
alpn_protocols : string list;
(*
optional ordered list of accepted alpn_protocols
*)
groups : Core.group list;
zero_rtt : int32;

}

configuration parameters

val config_of_sexp : Sexplib.Sexp.t -> config

val sexp_of_config : config -> Sexplib.Sexp.t

val ciphers13 : config -> Ciphersuite.ciphersuite13 list

ciphers13 config are the ciphersuites for TLS 1.3 in the configuration.

type client

opaque type of a client configuration

val client_of_sexp : Sexplib.Sexp.t -> client

val sexp_of_client : client -> Sexplib.Sexp.t

type server

opaque type of a server configuration

val server_of_sexp : Sexplib.Sexp.t -> server

val sexp_of_server : server -> Sexplib.Sexp.t

Constructors

val client : 
  authenticator:X509.Authenticator.t ->
  ?peer_name:string ->
  ?ciphers:Ciphersuite.ciphersuite list ->
  ?version:(Core.tls_version * Core.tls_version) ->
  ?signature_algorithms:Core.signature_algorithm list ->
  ?reneg:bool ->
  ?certificates:own_cert ->
  ?cached_session:Core.epoch_data ->
  ?cached_ticket:(Core.psk13 * Core.epoch_data) ->
  ?ticket_cache:ticket_cache ->
  ?alpn_protocols:string list ->
  ?groups:Core.group list ->
  unit ->
  client

client authenticator ?peer_name ?ciphers ?version ?hashes ?reneg ?certificates ?alpn_protocols is client configuration with the given parameters.

raises Invalid_argument
if the configuration is invalid

val server : 
  ?ciphers:Ciphersuite.ciphersuite list ->
  ?version:(Core.tls_version * Core.tls_version) ->
  ?signature_algorithms:Core.signature_algorithm list ->
  ?reneg:bool ->
  ?certificates:own_cert ->
  ?acceptable_cas:X509.Distinguished_name.t list ->
  ?authenticator:X509.Authenticator.t ->
  ?session_cache:session_cache ->
  ?ticket_cache:ticket_cache ->
  ?alpn_protocols:string list ->
  ?groups:Core.group list ->
  ?zero_rtt:int32 ->
  unit ->
  server

server ?ciphers ?version ?hashes ?reneg ?certificates ?acceptable_cas ?authenticator ?alpn_protocols is server configuration with the given parameters.

raises Invalid_argument
if the configuration is invalid

val peer : client -> string -> client

peer client name is client with name as peer_name

Note on ALPN protocol selection

Both client and server constructors accept an alpn_protocols list. The list for server should be given in a descending order of preference. In the case of protocol selection, the server will iterate its list and select the first element that the client's list also advertises.

For example, if the client advertises ["foo"; "bar"; "baz"] and the server has ["bar"; "foo"], "bar" will be selected as the protocol of the handshake.

Utility functions

val default_signature_algorithms : Core.signature_algorithm list

default_signature_algorithms is a list of signature algorithms used by default

val supported_signature_algorithms : Core.signature_algorithm list

supported_signature_algorithms is a list of supported signature algorithms by this library

val min_dh_size : int

min_dh_size is minimal diffie hellman group size in bits (currently 1024)

val dh_group : Mirage_crypto_pk.Dh.group

dh_group is the default Diffie-Hellman group (currently the ffdhe2048 group from Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for TLS)

val supported_groups : Core.group list

supported_groups are the Diffie-Hellman groups supported in this library.

val min_rsa_key_size : int

min_rsa_key_size is minimal RSA modulus key size in bits (currently 1024)

module Ciphers : sig ... end

Cipher selection

Internal use only

val of_client : client -> config

of_client client is a client configuration for client

val of_server : server -> config

of_server server is a server configuration for server

val with_authenticator : config -> X509.Authenticator.t -> config

with_authenticator config auth is config with auth as authenticator

val with_own_certificates : config -> own_cert -> config

with_own_certificates config cert is config with cert as own_cert

val with_acceptable_cas : config -> X509.Distinguished_name.t list -> config

with_acceptable_cas config cas is config with cas as accepted_cas

package tls

Config type

Constructors

Note on ALPN protocol selection

Utility functions

Internal use only