75 lines
3.3 KiB
OCaml
75 lines
3.3 KiB
OCaml
|
open! Core
|
||
|
|
open! Async
|
||
|
|
|
||
|
|
(** Low-level API for working with TLS sessions.
|
||
|
|
Most applications should use the high-level API below *)
|
||
|
|
module Session = Session
|
||
|
|
|
||
|
|
(** Helper functions for [Async_unix]-specific IO operations commonly used with X509
|
||
|
|
certificates, such as loading from a Unix filesystem *)
|
||
|
|
module X509_async = X509_async
|
||
|
|
|
||
|
|
(** [listen] creates a [Tcp.Server.t] with the requested parameters, including those
|
||
|
|
specified in [Tls.Config.server]. The handler function exposes the low-level
|
||
|
|
[Session.t] to accommodate cases like interrogating a client certificate *)
|
||
|
|
val listen
|
||
|
|
: ?buffer_age_limit:Writer.buffer_age_limit
|
||
|
|
-> ?max_connections:int (** defaults to [10_000]. *)
|
||
|
|
-> ?max_accepts_per_batch:int (** defaults to [1]. *)
|
||
|
|
-> ?backlog:int (** defaults to [64]. *)
|
||
|
|
-> ?socket:([ `Unconnected ], ([< Socket.Address.t ] as 'address)) Socket.t
|
||
|
|
-> on_handler_error:[ `Call of 'address -> exn -> unit | `Ignore | `Raise ]
|
||
|
|
-> Tls.Config.server
|
||
|
|
-> ('address, 'listening_on) Tcp.Where_to_listen.t
|
||
|
|
-> ('address -> Session.t -> Reader.t -> Writer.t -> unit Deferred.t)
|
||
|
|
-> ('address, 'listening_on) Tcp.Server.t Deferred.t
|
||
|
|
|
||
|
|
type 'a io_handler = Reader.t -> Writer.t -> 'a Deferred.t
|
||
|
|
type 'a tls_handler = Session.t -> 'a io_handler
|
||
|
|
|
||
|
|
(** [upgrade_server_handler] is what [listen] calls to handle each client.
|
||
|
|
It is exposed so that low-level end-users of the library can use tls-async
|
||
|
|
inside of code that manages Tcp services directly.
|
||
|
|
|
||
|
|
The [tls_handler] argument will be called with the client Tls session,
|
||
|
|
reader and writer to be used for cleartext data.
|
||
|
|
|
||
|
|
The outer [reader] and [writer] will read encrypted data from and write
|
||
|
|
encrypted data to the connected socket. *)
|
||
|
|
val upgrade_server_handler
|
||
|
|
: config:Tls.Config.server
|
||
|
|
-> 'a tls_handler
|
||
|
|
-> 'a io_handler
|
||
|
|
|
||
|
|
(** [connect] behaves similarly to [Tcp.connect], exposing a cleartext reader and writer.
|
||
|
|
Callers should ensure they close the [Writer.t] and wait for the [unit Deferred.t]
|
||
|
|
returned by [`Closed_and_flushed_downstream] to completely shut down the TLS connection
|
||
|
|
|
||
|
|
[host] is used for peer name verification and should generally be provided. Passing
|
||
|
|
[None] will disable peer name verification unless [peer_name] was provided in the
|
||
|
|
[Tls.Config.client]. If both are present [host] overwrites [peer_name].
|
||
|
|
*)
|
||
|
|
val connect
|
||
|
|
: ?socket:([ `Unconnected ], 'addr) Socket.t
|
||
|
|
-> (Tls.Config.client
|
||
|
|
-> 'addr Tcp.Where_to_connect.t
|
||
|
|
-> host:[ `host ] Domain_name.t option
|
||
|
|
-> (Session.t * Reader.t * Writer.t) Deferred.Or_error.t)
|
||
|
|
Tcp.Aliases.with_connect_options
|
||
|
|
|
||
|
|
(** [upgrade_client_to_tls] upgrades an existing reader/writer to TLS,
|
||
|
|
returning a cleartext reader and writer.
|
||
|
|
Callers should ensure they close the [Writer.t] and wait for the [unit Deferred.t]
|
||
|
|
returned by [`Closed_and_flushed_downstream] to completely shut down the TLS connection
|
||
|
|
|
||
|
|
[host] is used for peer name verification and should generally be provided. Passing
|
||
|
|
[None] will disable peer name verification unless [peer_name] was provided in the
|
||
|
|
[Tls.Config.client]. If both are present [host] overwrites [peer_name].
|
||
|
|
*)
|
||
|
|
val upgrade_client_to_tls
|
||
|
|
: Tls.Config.client
|
||
|
|
-> host:[ `host ] Domain_name.t option
|
||
|
|
-> Reader.t
|
||
|
|
-> Writer.t
|
||
|
|
-> (Session.t * Reader.t * Writer.t) Deferred.Or_error.t
|