Module Tls.EngineSource

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.12.8 - homepage

Abstract state type

Sourcetype state

The abstract type of a TLS state.

Constructors

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

Sourceval server : Config.server -> state

server server is tls where tls is the initial server state

Protocol failures

Sourcetype error = [
  1. | `AuthenticationFailure of X509.Validation.validation_error
  2. | `NoConfiguredCiphersuite of Ciphersuite.ciphersuite list
  3. | `NoConfiguredVersions of Core.tls_version list
  4. | `NoConfiguredSignatureAlgorithm of Core.signature_algorithm list
  5. | `NoMatchingCertificateFound of string
  6. | `NoCertificateConfigured
  7. | `CouldntSelectCertificate
]

failures which can be mitigated by reconfiguration

Sourcetype client_hello_errors = [
  1. | `EmptyCiphersuites
  2. | `NotSetCiphersuites of Packet.any_ciphersuite list
  3. | `NoSupportedCiphersuite of Packet.any_ciphersuite list
  4. | `NotSetExtension of Core.client_extension list
  5. | `HasSignatureAlgorithmsExtension
  6. | `NoSignatureAlgorithmsExtension
  7. | `NoGoodSignatureAlgorithms of Core.signature_algorithm list
  8. | `NoKeyShareExtension
  9. | `NoSupportedGroupExtension
  10. | `NotSetSupportedGroup of Packet.named_group list
  11. | `NotSetKeyShare of (Packet.named_group * Cstruct.t) list
  12. | `NotSubsetKeyShareSupportedGroup of Packet.named_group list * (Packet.named_group * Cstruct.t) list
  13. | `Has0rttAfterHRR
  14. | `NoCookie
]
Sourcetype fatal = [
  1. | `NoSecureRenegotiation
  2. | `NoSupportedGroup
  3. | `NoVersions of Core.tls_any_version list
  4. | `ReaderError of Reader.error
  5. | `NoCertificateReceived
  6. | `NoCertificateVerifyReceived
  7. | `NotRSACertificate
  8. | `NotRSASignature
  9. | `KeyTooSmall
  10. | `RSASignatureMismatch
  11. | `RSASignatureVerificationFailed
  12. | `UnsupportedSignatureScheme
  13. | `HashAlgorithmMismatch
  14. | `BadCertificateChain
  15. | `MACMismatch
  16. | `MACUnderflow
  17. | `RecordOverflow of int
  18. | `UnknownRecordVersion of int * int
  19. | `UnknownContentType of int
  20. | `CannotHandleApplicationDataYet
  21. | `NoHeartbeat
  22. | `BadRecordVersion of Core.tls_any_version
  23. | `BadFinished
  24. | `HandshakeFragmentsNotEmpty
  25. | `InsufficientDH
  26. | `InvalidDH
  27. | `InvalidRenegotiation
  28. | `InvalidClientHello of client_hello_errors
  29. | `InvalidServerHello
  30. | `InvalidRenegotiationVersion of Core.tls_version
  31. | `InappropriateFallback
  32. | `UnexpectedCCS
  33. | `UnexpectedHandshake of Core.tls_handshake
  34. | `InvalidCertificateUsage
  35. | `InvalidCertificateExtendedUsage
  36. | `InvalidSession
  37. | `NoApplicationProtocol
  38. | `HelloRetryRequest
  39. | `InvalidMessage
  40. | `Toomany0rttbytes
  41. | `MissingContentType
  42. | `Downgrade12
  43. | `Downgrade11
  44. | `UnsupportedKeyExchange
]

failures from received garbage or lack of features

Sourcetype failure = [
  1. | `Error of error
  2. | `Fatal of fatal
]

type of failures

Sourceval alert_of_failure : failure -> Packet.alert_type

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

Sourceval string_of_failure : failure -> string

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

Sourceval failure_of_sexp : Sexplib.Sexp.t -> failure

failure_of_sexp sexp is failure, the unmarshalled sexp.

Sourceval sexp_of_failure : failure -> Sexplib.Sexp.t

sexp_of_failure failure is sexp, the marshalled failure.

Protocol handling

Sourcetype ret = [
  1. | `Ok of [ `Ok of state | `Eof | `Alert of Packet.alert_type ] * [ `Response of Cstruct.t option ] * [ `Data of Cstruct.t option ]
  2. | `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.

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

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

Sourceval can_handle_appdata : state -> bool

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

Sourceval handshake_in_progress : state -> bool

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

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

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

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

Sourceval key_update : ?request:bool -> state -> (state * Cstruct.t, failure) 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

Sourcetype epoch = [
  1. | `InitialEpoch
  2. | `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.

Sourceval epoch_of_sexp : Sexplib.Sexp.t -> epoch

epoch_of_sexp sexp is epoch, the unmarshalled sexp.

Sourceval sexp_of_epoch : epoch -> Sexplib.Sexp.t

sexp_of_epoch epoch is sexp, the marshalled epoch.

Sourceval epoch : state -> epoch

epoch state is epoch, which contains the session information.