Module Tls.Engine

Abstract state type

type state

The abstract type of a TLS state.

Constructors

val client : Config.client -> state * Cstruct.t

client client is tls * out where tls is the initial state, and out the initial client hello

val server : Config.server -> state

server 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
| `NoConfiguredVersions of Core.tls_version list
| `NoConfiguredSignatureAlgorithm of Core.signature_algorithm list
| `NoMatchingCertificateFound of string
| `NoCertificateConfigured
| `CouldntSelectCertificate
]

failures which can be mitigated by reconfiguration

type client_hello_errors = [
| `EmptyCiphersuites
| `NotSetCiphersuites of Packet.any_ciphersuite list
| `NoSupportedCiphersuite of Packet.any_ciphersuite list
| `NotSetExtension of Core.client_extension list
| `HasSignatureAlgorithmsExtension
| `NoSignatureAlgorithmsExtension
| `NoGoodSignatureAlgorithms of Core.signature_algorithm list
| `NoKeyShareExtension
| `NoSupportedGroupExtension
| `NotSetSupportedGroup of Packet.named_group list
| `NotSetKeyShare of (Packet.named_group * Cstruct.t) list
| `NotSubsetKeyShareSupportedGroup of Packet.named_group list * (Packet.named_group * Cstruct.t) list
| `Has0rttAfterHRR
| `NoCookie
]
type fatal = [
| `NoSecureRenegotiation
| `NoSupportedGroup
| `NoVersions of Core.tls_any_version list
| `ReaderError of Reader.error
| `NoCertificateReceived
| `NoCertificateVerifyReceived
| `NotRSACertificate
| `NotRSASignature
| `KeyTooSmall
| `RSASignatureMismatch
| `RSASignatureVerificationFailed
| `UnsupportedSignatureScheme
| `HashAlgorithmMismatch
| `BadCertificateChain
| `MACMismatch
| `MACUnderflow
| `RecordOverflow of int
| `UnknownRecordVersion of int * int
| `UnknownContentType of int
| `CannotHandleApplicationDataYet
| `NoHeartbeat
| `BadRecordVersion of Core.tls_any_version
| `BadFinished
| `HandshakeFragmentsNotEmpty
| `InsufficientDH
| `InvalidDH
| `InvalidRenegotiation
| `InvalidClientHello of client_hello_errors
| `InvalidServerHello
| `InvalidRenegotiationVersion of Core.tls_version
| `InappropriateFallback
| `UnexpectedCCS
| `UnexpectedHandshake of Core.tls_handshake
| `InvalidCertificateUsage
| `InvalidCertificateExtendedUsage
| `InvalidSession
| `NoApplicationProtocol
| `HelloRetryRequest
| `InvalidMessage
| `Toomany0rttbytes
| `MissingContentType
| `Downgrade12
| `Downgrade11
| `UnsupportedKeyExchange
]

failures from received garbage or lack of features

type failure = [
| `Error of error
| `Fatal of fatal
]

type of failures

val alert_of_failure : failure -> Packet.alert_type

alert_of_failure failure is alert, the TLS alert type for this failure.

val string_of_failure : failure -> string

string_of_failure failure is string, the string representation of the failure.

val failure_of_sexp : Sexplib.Sexp.t -> failure

failure_of_sexp sexp is failure, the unmarshalled sexp.

val sexp_of_failure : failure -> Sexplib.Sexp.t

sexp_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.

val handle_tls : state -> Cstruct.t -> ret

handle_tls state buffer is ret, depending on incoming state and buffer, the result is the appropriate ret

val can_handle_appdata : state -> bool

can_handle_appdata state is a predicate which indicates when the connection has already completed a handshake.

val handshake_in_progress : state -> bool

handshake_in_progrss state is a predicate which indicates whether there is a handshake in progress or scheduled.

val send_application_data : state -> Cstruct.t list -> (state * Cstruct.t) option

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).

val send_close_notify : state -> state * Cstruct.t

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) option

reneg ~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).

val key_update : ?⁠request:bool -> state -> (state * Cstruct.t, failure) Stdlib.result

key_update ~request state initiates a KeyUpdate (TLS 1.3 only). If request is provided and true (the default), the KeyUpdate message contains a request that the peer should update their traffic key as well.

Session information

type epoch = [
| `InitialEpoch
| `Epoch of Core.epoch_data
]

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 -> epoch

epoch_of_sexp sexp is epoch, the unmarshalled sexp.

val sexp_of_epoch : epoch -> Sexplib.Sexp.t

sexp_of_epoch epoch is sexp, the marshalled epoch.

val epoch : state -> epoch

epoch state is epoch, which contains the session information.