gluegun/tls

Typed TLS client options for Gun and Erlang SSL.

Gluegun applies a secure baseline whenever a connection uses TLS (connection.Tls, or connection.Auto resolving to TLS): peer and hostname verification, system CA certificates, TLS 1.2/1.3, SNI for DNS hosts, and HTTPS hostname matching. See the TLS guide for the canonical default list and override behavior.

For development against self-signed endpoints, use insecure() — it returns a TlsOptions that disables verification (and therefore the rest of the secure baseline). Do not ship insecure() to production.

Production HTTPS

The minimal HTTPS setup is just:

import gluegun/connection

pub fn https_options() -> connection.ConnectOptions {
  connection.options()
  |> connection.with_transport(transport: connection.Tls)
}

Gluegun fills in verify_peer, the OS trust store, TLS 1.2/1.3, SNI, and HTTPS hostname matching automatically when you call connection.open(host:, port:).

Overriding the baseline

import gluegun/connection
import gluegun/tls

pub fn https_options() -> connection.ConnectOptions {
  let assert Ok(tls_options) =
    tls.options()
    |> tls.with_versions(versions: [tls.TlsV13])
    |> tls.with_cacertfile(cacertfile: "/etc/ssl/cert.pem")
    |> tls.with_depth(depth: 5)

  connection.options()
  |> connection.with_transport(transport: connection.Tls)
  |> connection.with_tls_options(tls_options: tls_options)
}

Any field you set on TlsOptions overrides the corresponding default; fields you leave unset are filled in by the secure baseline.

Types

ServerNameIndication

</>

SNI configuration for a TLS connection.

pub type ServerNameIndication {
  Disable
  ServerName(String)
}

Constructors

```
Disable
```
Disable SNI for this connection. Requires explicit VerifyNone: OTP also disables hostname verification.
```
ServerName(String)
```
Send the provided hostname as the SNI value.

TlsOptions

opaque </>

Pure representation of TLS client options before FFI conversion.

Build with options() then chain with_verify, with_versions, with_ciphers, with_cacerts, with_cacertfile, with_certfile, with_keyfile, with_server_name_indication, and with_depth. See the TLS guide for a production HTTPS baseline.

pub opaque type TlsOptions

TlsVersion

</>

Supported TLS protocol versions.

pub type TlsVersion {
  TlsV12
  TlsV13
}

Constructors

```
TlsV12
```
Allow TLS 1.2.
```
TlsV13
```
Allow TLS 1.3.

VerifyMode

</>

TLS peer verification mode.

pub type VerifyMode {
  VerifyPeer
  VerifyNone
}

Constructors

```
VerifyPeer
```
Verify the peer certificate chain and hostname.
```
VerifyNone
```
Disable peer certificate verification.

Values

insecure

</>

pub fn insecure() -> TlsOptions

Construct TLS options that disable peer verification.

Development only. Returns options with verify_none and SNI disabled, which suppresses Gluegun’s secure TLS defaults (system CA trust store, hostname verification, TLS 1.2/1.3 floor). This bypasses the protections that make HTTPS trustworthy — never use it against untrusted networks or production endpoints.

options

</>

pub fn options() -> TlsOptions

Construct empty TLS options.

with_cacertfile

</>

pub fn with_cacertfile(
  options: TlsOptions,
  cacertfile cacertfile: String,
) -> TlsOptions

Set the path to a PEM CA bundle file.

with_cacerts

</>

pub fn with_cacerts(
  options: TlsOptions,
  cacerts cacerts: List(BitArray),
) -> TlsOptions

Set DER-encoded trusted CA certificates.

with_certfile

</>

pub fn with_certfile(
  options: TlsOptions,
  certfile certfile: String,
) -> TlsOptions

Set the path to the client certificate file.

with_ciphers

</>

pub fn with_ciphers(
  options: TlsOptions,
  ciphers ciphers: List(String),
) -> TlsOptions

Set TLS cipher suite names.

with_depth

</>

pub fn with_depth(
  options: TlsOptions,
  depth depth: Int,
) -> Result(TlsOptions, error.GluegunError)

Set the maximum certificate chain depth, between zero and 255.

Invalid numeric options return InvalidOptions; they are not clamped.

with_keyfile

</>

pub fn with_keyfile(
  options: TlsOptions,
  keyfile keyfile: String,
) -> TlsOptions

Set the path to the client private key file.

with_server_name_indication

</>

pub fn with_server_name_indication(
  options: TlsOptions,
  server_name_indication server_name_indication: ServerNameIndication,
) -> TlsOptions

Set the TLS SNI value, or disable it with explicit VerifyNone.

Opening with disabled SNI under VerifyPeer returns InvalidOptions.

with_verify

</>

pub fn with_verify(
  options: TlsOptions,
  verify verify: VerifyMode,
) -> TlsOptions

Set the TLS peer verification mode.

with_versions

</>

pub fn with_versions(
  options: TlsOptions,
  versions versions: List(TlsVersion),
) -> TlsOptions

Set TLS protocol versions in preference order.