90 lines
4.2 KiB
Markdown
90 lines
4.2 KiB
Markdown
|
## TLS - Transport Layer Security purely in OCaml
|
||
|
|
|
||
|
|
v2.0.3
|
||
|
|
|
||
|
|
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](http://tools.ietf.org/html/rfc2818)), 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](https://www.usenix.org/conference/usenixsecurity15/technical-sessions/presentation/kaloper-mersinjak) for further details.
|
||
|
|
|
||
|
|
## Documentation
|
||
|
|
|
||
|
|
[API documentation](https://mirleft.github.io/ocaml-tls/doc)
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
`opam install tls` will install this library.
|
||
|
|
|
||
|
|
You can also build this locally by conducting the steps:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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][ssl]) can offer.
|
||
|
|
- [lwt](https://ocsigen.org/lwt/latest/manual/manual): `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](https://github.com/robur-coop/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](https://mirageos.org): `tls-mirage` proposes a composition
|
||
|
|
of a [`Mirage_flow.S`](https://github.com/mirage/mirage-flow/) module to
|
||
|
|
obtain a new `Mirage_flow.S` (corresponding to the TLS layer) which uses the
|
||
|
|
lwt scheduler.
|
||
|
|
- [eio](https://github.com/ocaml-multicore/eio): `tls-eio` proposes the creation
|
||
|
|
of an _eio flow_ from another _eio flow_.
|
||
|
|
- [async](https://github.com/janestreet/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][sendmail], 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][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](https://mirageos.org),
|
||
|
|
which makes it portable and available on many systems (even the most restricted
|
||
|
|
ones such as [Solo5](https://github.com/solo5/solo5) as long as OCaml is
|
||
|
|
available on them.
|
||
|
|
|
||
|
|
[sendmail]: https://github.com/mirage/colombe
|
||
|
|
[albatross]: https://github.com/robur-coop/albatross
|
||
|
|
[ssl]: https://github.com/savonet/ocaml-ssl
|