unikernel/duniverse/ocaml-tls/async/tls_async.mli

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