Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
package tls
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
Transport layer security
TLS is an implementation of transport layer security in OCaml. TLS is a widely used security protocol which establishes an end-to-end secure channel (with optional (mutual) authentication) between two endpoints. It uses TCP/IP as transport. This library supports all three versions of TLS: 1.2, RFC5246, 1.1, RFC4346, and 1.0, RFC2246. SSL, the previous protocol definition, is not supported.
TLS is algorithmically agile: protocol version, key exchange algorithm, symmetric cipher, and message authentication code are negotiated upon connection.
This library implements several extensions of TLS, AES ciphers, TLS extensions (such as server name indication, SNI), Renegotiation extension, Session Hash and Extended Master Secret Extension.
This library does not contain insecure cipher suites (such as single DES, export ciphers, ...). It does not expose the server time in the server random, requires secure renegotiation.
This library consists of a core, implemented in a purely functional matter (Engine, this module), and effectful parts: Tls_lwt and Tls_mirage.
v0.11.0 - homepage
Abstract state type
Constructors
val client : Config.client -> state * Cstruct.tclient client is tls * out where tls is the initial state, and out the initial client hello
val server : Config.server -> stateserver server is tls where tls is the initial server state
Protocol failures
type error = [ | `AuthenticationFailure of X509.Validation.validation_error| `NoConfiguredCiphersuite of Ciphersuite.ciphersuite list| `NoConfiguredVersion of Core.tls_version| `NoConfiguredHash of Mirage_crypto.Hash.hash list| `NoMatchingCertificateFound of string| `NoCertificateConfigured| `CouldntSelectCertificate
]failures which can be mitigated by reconfiguration
type fatal = [ | `NoSecureRenegotiation| `NoCiphersuite of Packet.any_ciphersuite list| `NoVersion of Core.tls_any_version| `ReaderError of Reader.error| `NoCertificateReceived| `NotRSACertificate| `NotRSASignature| `KeyTooSmall| `RSASignatureMismatch| `RSASignatureVerificationFailed| `HashAlgorithmMismatch| `BadCertificateChain| `MACMismatch| `MACUnderflow| `RecordOverflow of int| `UnknownRecordVersion of int * int| `UnknownContentType of int| `CannotHandleApplicationDataYet| `NoHeartbeat| `BadRecordVersion of Core.tls_any_version| `BadFinished| `HandshakeFragmentsNotEmpty| `InvalidDH| `InvalidRenegotiation| `InvalidClientHello| `InvalidServerHello| `InvalidRenegotiationVersion of Core.tls_version| `InappropriateFallback| `UnexpectedCCS| `UnexpectedHandshake of Core.tls_handshake| `InvalidCertificateUsage| `InvalidCertificateExtendedUsage| `InvalidSession| `NoApplicationProtocol
]failures from received garbage or lack of features
val alert_of_failure : failure -> Packet.alert_typealert_of_failure failure is alert, the TLS alert type for this failure.
val string_of_failure : failure -> stringstring_of_failure failure is string, the string representation of the failure.
val failure_of_sexp : Sexplib.Sexp.t -> failurefailure_of_sexp sexp is failure, the unmarshalled sexp.
val sexp_of_failure : failure -> Sexplib.Sexp.tsexp_of_failure failure is sexp, the marshalled failure.
Protocol handling
type ret = [ | `Ok of [ `Ok of state | `Eof | `Alert of Packet.alert_type ] * [ `Response of Cstruct.t option ] * [ `Data of Cstruct.t option ]| `Fail of failure * [ `Response of Cstruct.t ]
]result type of handle_tls: either failed to handle the incoming buffer (`Fail) with failure and potentially a message to send to the other endpoint, or sucessful operation (`Ok) with a new state, an end of file (`Eof), or an incoming (`Alert). Possibly some `Response to the other endpoint is needed, and potentially some `Data for the application was received.
handle_tls state buffer is ret, depending on incoming state and buffer, the result is the appropriate ret
val can_handle_appdata : state -> boolcan_handle_appdata state is a predicate which indicates when the connection has already completed a handshake.
val handshake_in_progress : state -> boolhandshake_in_progrss state is a predicate which indicates whether there is a handshake in progress or scheduled.
send_application_data tls outs is (tls' * out) option where tls' is the new tls state, and out the cstruct to send over the wire (encrypted outs).
send_close_notify tls is tls' * out where tls' is the new tls state, and out the (possible encrypted) close notify alert.
val reneg :
?authenticator:X509.Authenticator.t ->
?acceptable_cas:X509.Distinguished_name.t list ->
?cert:Config.own_cert ->
state ->
(state * Cstruct.t) optionreneg ~authenticator ~acceptable_cas ~cert tls initiates a renegotation on tls, using the provided authenticator. It is tls' * out where tls' is the new tls state, and out either a client hello or hello request (depending on which communication endpoint tls is).
Session information
polymorphic variant of session information. The first variant `InitialEpoch will only be used for TLS states without completed handshake. The second variant, `Epoch, contains actual session data.
val epoch_of_sexp : Sexplib.Sexp.t -> epochepoch_of_sexp sexp is epoch, the unmarshalled sexp.
val sexp_of_epoch : epoch -> Sexplib.Sexp.tsexp_of_epoch epoch is sexp, the marshalled epoch.