Module Async_ssl.Ssl

An Async-pipe-based interface with OpenSSL.

This module allows you to create an SSL client and server, with encrypted communication between both.

module Version : module type of Version
module Opt : module type of Opt
module Verify_mode : module type of Verify_mode
val secure_ciphers : string list
module Certificate : sig ... end
module Session : sig ... end
module Connection : sig ... end

Creates either an SSL client or server.

NB: your achieved security will be very weak unless you check the connection parameters after the handshake. See the Connection module above.

version is optional, and allows you to customize the specific version of SSL that this connection should be using. It may be downgraded - you should check the actually negotiated version post-connection.

name allows you to name this connection, to make errors easier to track down.

If ca_file is not None, it points to a file of CA certificates in PEM format. It may have more than one certificate.

If ca_path is not None, it points to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The certificates in ca_path are only looked up lazily, not eagarly.

If both ca_file and ca_path are specified, the certificates in ca_file will be searched before the certificates in ca_path.

Any certificate authorities loaded are automatically trusted by OpenSSL.

crt_file and key_file are the on-disk locations of the server's public and private keys.

Any data written into app_to_ssl will be encrypted with SSL, and the encrypted data will eventually be written into ssl_to_net.

Similarly, any data written into net_to_ssl will be decrypted with SSL and written into ssl_to_app.

A picture is probably easier to understand:

                          app_to_ssl           ssl_to_net
        +---------------+ ---------> +-------+ ---------> +-----+
        | CLIENT/SERVER |            |  SSL  |            | NET |
        +---------------+ <--------- +-------+ <--------- +-----+
                          ssl_to_app           net_to_ssl

To close the connection and free associated memory, call Connection.close. This will close all the involved pipes.

The session argument enables the session resumption mechanism: when called with the same session value twice, the client will try to resume the session during the second call, resulting in a quicker handshake. It is your responsibility to keep the mapping between the destinations and the sessions to be used with them. Calling the client with the same session but with a differet ca_file or ca_path will result in an error. Use Connection.session_reused to find out if session resumption actually worked.

Both client and server become determined when the handshake has completed.

The hostname sets the hostname to pass to the server using the SNI extension.

val client : ?⁠version:Version.t ‑> ?⁠options:Opt.t list ‑> ?⁠name:string ‑> ?⁠hostname:string ‑> ?⁠allowed_ciphers:[ `Secure | `Openssl_default | `Only of string list ] ‑> ?⁠ca_file:string ‑> ?⁠ca_path:string ‑> ?⁠crt_file:string ‑> ?⁠key_file:string ‑> ?⁠verify_modes:Verify_mode.t list ‑> ?⁠session:Session.t ‑> app_to_ssl:string Async.Pipe.Reader.t ‑> ssl_to_app:string Async.Pipe.Writer.t ‑> net_to_ssl:string Async.Pipe.Reader.t ‑> ssl_to_net:string Async.Pipe.Writer.t ‑> unit ‑> Connection.t Async.Deferred.Or_error.t
val server : ?⁠version:Version.t ‑> ?⁠options:Opt.t list ‑> ?⁠name:string ‑> ?⁠allowed_ciphers:[ `Secure | `Openssl_default | `Only of string list ] ‑> ?⁠ca_file:string ‑> ?⁠ca_path:string ‑> crt_file:string ‑> key_file:string ‑> ?⁠verify_modes:Verify_mode.t list ‑> app_to_ssl:string Async.Pipe.Reader.t ‑> ssl_to_app:string Async.Pipe.Writer.t ‑> net_to_ssl:string Async.Pipe.Reader.t ‑> ssl_to_net:string Async.Pipe.Writer.t ‑> unit ‑> Connection.t Async.Deferred.Or_error.t