unikernel/duniverse/ocaml-tls/eio/tls_eio.mli

@@ -0,0 +1,59 @@
+(** Effectful operations using Eio for pure TLS.
+
+    The pure TLS is state and buffer in, state and buffer out.  This
+    module uses Eio for communication over the network. *)
+
+open Eio.Std
+
+(** [Tls_alert] exception received from the other endpoint *)
+exception Tls_alert   of Tls.Packet.alert_type
+
+(** [Tls_failure] exception while processing incoming data *)
+exception Tls_failure of Tls.Engine.failure
+
+type t = [ `Tls | Eio.Flow.two_way_ty | Eio.Resource.close_ty ] r
+
+(** {2 Constructors} *)
+
+(** [server_of_flow server flow] is [t], after server-side TLS
+    handshake of [flow] using [server] configuration.
+
+    You must ensure a RNG is installed while using TLS, e.g. using [Mirage_crypto_rng_unix.use_default ()].
+    Ideally, this would be part of the [server] config so you couldn't forget it,
+    but for now you'll get a runtime error if you forget. *)
+val server_of_flow :
+  Tls.Config.server ->
+  [> Eio.Flow.two_way_ty | Eio.Resource.close_ty] r -> t
+
+(** [client_of_flow client ~host fd] is [t], after client-side
+    TLS handshake of [flow] using [client] configuration and [host].
+
+    You must ensure a RNG is installed while using TLS, e.g. using [Mirage_crypto_rng_unix.use_default ()].
+    Ideally, this would be part of the [client] config so you couldn't forget it,
+    but for now you'll get a runtime error if you forget. *)
+val client_of_flow :
+  Tls.Config.client -> ?host:[ `host ] Domain_name.t ->
+  [> Eio.Flow.two_way_ty | Eio.Resource.close_ty] r -> t
+
+(** {2 Control of TLS features} *)
+
+(** [reneg ~authenticator ~acceptable_cas ~cert ~drop t] renegotiates the
+    session, and blocks until the renegotiation finished.  Optionally, a new
+    [authenticator] and [acceptable_cas] can be used.  The own certificate can
+    be adjusted by [cert]. If [drop] is [true] (the default),
+    application data received before the renegotiation finished is dropped. *)
+val reneg :
+  ?authenticator:X509.Authenticator.t ->
+  ?acceptable_cas:X509.Distinguished_name.t list ->
+  ?cert:Tls.Config.own_cert ->
+  ?drop:bool ->
+  t -> unit
+
+(** [key_update ~request t] updates the traffic key and requests a traffic key
+    update from the peer if [request] is provided and [true] (the default).
+    This is only supported in TLS 1.3. *)
+val key_update : ?request:bool -> t -> unit
+
+(** [epoch t] returns [epoch], which contains information of the
+    active session. *)
+val epoch : t -> (Tls.Core.epoch_data, unit) result