tls 0.17.1 · OCaml Package

Configuration of the TLS stack

Config type

type certchain = X509.Certificate.t list * X509.Private_key.t

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 -> Ptime.t;

}

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 : [ `host ] Domain_name.t 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 option;
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;
(*
the first FFDHE will be used for TLS 1.2 and below if a DHE ciphersuite is used
*)
zero_rtt : int32;
ip : Ipaddr.t option;

}

configuration parameters

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

type server

opaque type of a server configuration

Constructors

val client : 
  authenticator:X509.Authenticator.t ->
  ?peer_name:[ `host ] Domain_name.t ->
  ?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 ->
  ?ip:Ipaddr.t ->
  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 ->
  ?ip:Ipaddr.t ->
  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 -> [ `host ] Domain_name.t -> 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 supported_groups : Core.group list

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

val elliptic_curve : Core.group -> bool

elliptic_curve group is true if group is an elliptic curve, false otherwise.

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