Module Tls_config

TLS configuration utilities

This module provides shared TLS configuration creation to ensure consistent behavior across session-based and one-shot request modes.

Supports ALPN (Application-Layer Protocol Negotiation) for HTTP/2 upgrade per RFC 9113 Section 3.3.

val src : Logs.src

Logs source for this module

TLS Version Types

type tls_version =
  1. | TLS_1_2
    (*

    TLS 1.2 minimum (default, widely compatible)

    *)
  2. | TLS_1_3
    (*

    TLS 1.3 minimum (most secure, may not work with older servers)

    *)

Minimum TLS version configuration. Per Recommendation #6: Allow enforcing minimum TLS version.

val tls_version_to_tls : tls_version -> Tls.Core.tls_version

Convert our TLS version type to the underlying library's type

ALPN Protocol Negotiation

Per RFC 9113 Section 3.3, HTTP/2 connections over TLS use ALPN to negotiate the protocol.

val alpn_h2 : string

ALPN protocol identifiers.

ALPN identifier for HTTP/2: "h2"

val alpn_http11 : string

ALPN identifier for HTTP/1.1: "http/1.1"

type protocol_mode =
  1. | Auto
    (*

    Prefer HTTP/2 if available, fall back to HTTP/1.1

    *)
  2. | Http1_only
    (*

    Use HTTP/1.1 only

    *)
  3. | Http2_only
    (*

    Require HTTP/2

    *)

HTTP protocol mode for ALPN negotiation.

val alpn_protocols : protocol_mode -> string list

alpn_protocols mode returns the ALPN protocol list for the given mode.

  • Auto: "h2"; "http/1.1"
  • Http1_only: "http/1.1"
  • Http2_only: "h2"

Configuration Creation

val create_client : ?verify_tls:bool -> ?min_tls_version:tls_version -> ?protocol_mode:protocol_mode -> host:string -> unit -> Tls.Config.client

create_client ~host () creates a TLS client configuration.

  • parameter verify_tls

    If true (default), use system CA certificates for verification

  • parameter min_tls_version

    Minimum TLS version to accept (default TLS_1_2)

  • parameter protocol_mode

    HTTP protocol mode for ALPN (default Auto)

  • parameter host

    Hostname for error messages

  • returns

    TLS client configuration

val create_client_opt : ?existing_config:Tls.Config.client -> verify_tls:bool -> min_tls_version:tls_version -> ?protocol_mode:protocol_mode -> host:string -> unit -> Tls.Config.client option

create_client_opt ~verify_tls ~min_tls_version ~host () creates a TLS client configuration, or returns the existing one if provided.

  • parameter existing_config

    If provided, return this instead of creating new

  • parameter verify_tls

    If true, use system CA certificates for verification

  • parameter min_tls_version

    Minimum TLS version to accept

  • parameter protocol_mode

    HTTP protocol mode for ALPN (default Auto)

  • parameter host

    Hostname for error messages

  • returns

    Some TLS client configuration

ALPN Result Extraction

Helper functions for extracting negotiated protocol from TLS epoch.

type negotiated_protocol =
  1. | Http1_1
    (*

    HTTP/1.1

    *)
  2. | Http2
    (*

    HTTP/2

    *)

Negotiated HTTP protocol from ALPN.

val get_alpn_from_epoch : Tls.Core.epoch_data -> string option

get_alpn_from_epoch epoch extracts the negotiated ALPN protocol from TLS epoch data. Returns None if ALPN was not negotiated.

val negotiated_of_alpn : string -> negotiated_protocol option

negotiated_of_alpn alpn parses ALPN result string.

  • "h2" -> Some Http2
  • "http/1.1" -> Some Http1_1
  • other -> None
val default_protocol : negotiated_protocol

Default protocol (HTTP/1.1) when ALPN is not available.

val detect_protocol : mode:protocol_mode -> string option -> negotiated_protocol

detect_protocol ~mode alpn_result determines the protocol to use.

  • raises Failure

    if Http2_only mode but HTTP/2 not negotiated

val negotiated_to_string : negotiated_protocol -> string

Convert negotiated protocol to string ("HTTP/1.1" or "HTTP/2").

val pp_negotiated : Format.formatter -> negotiated_protocol -> unit

Pretty print negotiated protocol.