unikernel/duniverse/ocaml-tls/README.md

@@ -0,0 +1,89 @@
+## 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