Module Bytesrw_tls

TLS encrypted streams (via conf-mbedtls)

This module provides support for reading and writing TLS encrypted streams. It depends on the bytesrw.crypto library in and is thus subject to its automatic initialization.

Backend. The concrete TLS implementation is abtracted away. It is currently provided by the Mbed TLS C library.

Sample code. Have a look the min_tls.ml, webfetch.ml and webserve.ml examples in the source repository and read a few certificate tips.

Certificates and configuration

module X509_certchain : sig ... end

X.509 certificate chains.

module Conf : sig ... end

TLS connection configuration.

module Info : sig ... end

TLS connection information.

val backend_info : unit -> string

backend_info () is a string that indicates the underyling library and version implementing the TLS support.

Streams

type Bytesrw.Bytes.Stream.error +=
  1. | Error of string

The type for TLS streams errors.

Readers and writers using TLS encrypted streams may Bytes.Stream.Error with this error.

val for_client_socket : Conf.t -> peer_hostname:string -> peer:Unix.file_descr -> (Info.t -> peer:(Bytesrw.Bytes.Writer.t * Bytesrw.Bytes.Reader.t) -> 'a) -> ('a, string) Stdlib.result

for_client_socket conf ~peer_hostname ~peer:fd f setups a TLS stream on fd according to conf assuming it contacts peer_hostname and the fd is Unix.connected to the IP address of that peer. Unless Conf.verify_peer conf is false, the peer certificate is verified using the Conf.trusted_certs certificates. If Conf.own_certs is present the first of these certificates is presented to the peer for potential authentication (mutual TLS).

If the connection setup fails, Error _ is returned. Otherwise f is called with information about the connection and a pair (send, recv) of bytes writer and reader. Writing plain data on send sends it encrypted to the peer and reading from recv reads decrypted data received from the peer.

Both info and (send, recv) are only valid during the call to f and using them afterwards raises Invalid_argument.

  • raises Invalid_argument

    if Conf.kind conf <> Client.

val for_server_socket : Conf.t -> peer:Unix.file_descr -> (Info.t -> peer:(Bytesrw.Bytes.Writer.t * Bytesrw.Bytes.Reader.t) -> 'a) -> ('a, string) Stdlib.result

for_server_socket conf ~peer:fd f setups a TLS stream on fd according to conf assuming fd has been Unix.accepted from a listening socket. If Conf.verify_peer conf is true, the peer must present a certificate which can be verified using the Conf.trusted_certs certificates.

If the connection setup fails, Error _ is returned. Otherwise f is called with the information about the connection and a pair (send, recv) of bytes writer and reader. Writing plain data on send sends it encrypted to the peer and reading from recv reads decrypted data received from the peer.

Both info and (send, recv) are only valid during the call to f using them afterwards raises Invalid_argument.

The Conf.own_certs certificate is given to the peer for verification.

  • raises Invalid_argument

    if Conf.kind conf <> Server.

Certificate tips for development

The certificate business may get in the way when you develop servers. Here are a few strategies.

Self-signed certificates

You can easily generate self-signed certificates with X509_certchain.self_signed function. For example if no certificate is specifed on the command line, the webserve.ml example generates one dynamically for localhost and outputs it on stdout which you can then read e.g. from curl or instruct your browser to trust them when they hit them.

webserve > /tmp/cert.pem
curl --cacert /tmp/cert.pem https://localhost:4443

The certown tool distributed with the library can also be used to generate these certificates for example:

certown self-signed /tmp/myapp
webserve --own-cert /tmp/myapp.cert.pem --own-key /tmp/myapp.key.pem
curl --cacert /tmp/myapp.cert.pem https://localhost:4443

Become your own certificate authority

A self-signed certificate for a certificate authority can be created with X509_certchain.self_signed ~is_ca:true. Be careful with the private key of this certificate, you need to protect it.

Add this certificate to the trusted certificate authorities (CA) of your system or browser. Equiped with the CA certificate and private key you can generate certificates signed by it with X509_certchain.ca_signed. These should then validate in browsers without more operations.

The certown tool distributed with the library helps to streamline this workflow. For example the following create a CA certificate (valid for 47 days) and private key in the ~/.local/share/certown directory and tries to install the certificate as a system trusted CA.

certown ca create   # Creates a CA cert in ~/.local/share/certown
certown ca install  # Install the CA cert in your system, sudo may be needed
certown ca-signed /tmp/myapp # Generate certificate (chain) signed by the CA
webserve --own-cert /tmp/mycert.cert.pem --own-key /tmp/mycert.key.pem
curl https://localhost:4443