package tls

TLS - Transport Layer Security purely in OCaml

v2.0.2

Transport Layer Security (TLS) is probably the most widely deployed security protocol on the Internet. It provides communication privacy to prevent eavesdropping, tampering, and message forgery. Furthermore, it optionally provides authentication of the involved endpoints. TLS is commonly deployed for securing web services (HTTPS), emails, virtual private networks, and wireless networks.

TLS uses asymmetric cryptography to exchange a symmetric key, and optionally authenticate (using X.509) either or both endpoints. It provides algorithmic agility, which means that the key exchange method, symmetric encryption algorithm, and hash algorithm are negotiated.

Read our Usenix Security 2015 paper for further details.

Documentation

API documentation

Installation

opam install tls will install this library.

You can also build this locally by conducting the steps:

opam install --deps-only -t . # or a named package instead of `.` - i.e. ./tls-lwt.opam
dune build --profile=release # you can also put a package list here, i.e. tls,tls-lwt -- you can also use `@all` target to compile examples as well

Usage

The core of ocaml-tls (the opam package tls, available in the lib subdirectory) is an library independent of schedulers and does not perform any I/O operations. The library is designed so that a Tls.Engine.state state informs you of when to write and when to feed more data. It does not use mutation and is in a value-passing style (so, read data and state is the input, and data to be sent or presented to the upper layer, and state is the output).

There are therefore ocaml-tls derivations with different schedulers that perform read and write operations. These derivations offer an interface similar to what an SSL socket (like ssl) can offer.

• lwt: tls-lwt proposes to initiate a TLS flow with Lwt_io.{input,output}_channel from a Unix socket. It can also propose an abstract type Tls_lwt.Unix.t (which can be created from a Unix socket) associated with a Tls_lwt.Unix interface similar to a Unix socket.
• miou: tls-miou-unix proposes a TLS flow via an abstract type Tls_miou_unix.t and an interface similar to a Unix socket from a Miou_unix.file_descr socket.
• MirageOS: tls-mirage proposes a composition of a Mirage_flow.S module to obtain a new Mirage_flow.S (corresponding to the TLS layer) which uses the lwt scheduler.
• eio: tls-eio proposes the creation of an eio flow from another eio flow.
• async: tls-async proposes a TLS flow via Async.{Reader,Writer}.t from a Async.Socket.

Depending on the scheduler you choose, you should choose one of these ocaml-tls derivations, distributed in the mentioned opam packages (tls-lwt, tls-mirage, tls-eio, tls-async). Each one takes advantage of what the scheduler used has to offer.

Composability

ocaml-tls can also be used as it is in order to be able to compose with other protocols without choosing a scheduler. This is the case, for example, with sendmail.starttls, which composes the SMTP and TLS protocols. The user can also be more selective about the use of certificates involved in a TLS connection, as albatross can offer in its transactions between clients and the server.

When seen as OCaml values, the critical elements that enable instantiation of a TLS connection can be very finely controlled.

Portability

ocaml-tls is currently used for MirageOS unikernels, which makes it portable and available on many systems (even the most restricted ones such as Solo5 as long as OCaml is available on them.