Skip to content

std::tls

TLS: the certificates a side presents, the roots it trusts, and the versions, cipher suites and protocols it allows. A ClientConfig or ServerConfig is a value, used by std::http (ClientOptions.tls, Server.tls) and std::net (tls.dial, tls.listen, tls.client, tls.server).

certificate = Certificate.load("cert.pem", "key.pem")?

listener = http.listen(Server{
    address: ":8443",
    tls:     Some(ServerConfig{certificates: [certificate]}),
})?

A config’s defaults are the system’s trusted roots, TLS 1.2 or later, and only cipher suites and curves with no known weakness.

Import with import std::tls.

enum Version
    Tls10
    Tls11
    Tls12
    Tls13
end

A TLS protocol version.

impl Display for Version

fn to_string(version: Version) -> String

impl Display.to_string

assert "${Version.Tls13}" == "TLS 1.3"

impl Debug for Version

fn inspect(value: Version) -> String

impl Debug.inspect

impl Equatable for Version

fn equal(a: Version, b: Version) -> Bool

impl Equatable.equal

enum Curve
    X25519
    P256
    P384
    P521
    X25519MlKem768
    P256MlKem768
    P384MlKem1024
    MlKem1024
end

A key exchange a side offers: an elliptic curve, or a hybrid with the post-quantum ML-KEM.

impl Display for Curve

fn to_string(curve: Curve) -> String

impl Display.to_string

assert "${Curve.X25519MlKem768}" == "X25519MlKem768"

impl Debug for Curve

fn inspect(value: Curve) -> String

impl Debug.inspect

impl Equatable for Curve

fn equal(a: Curve, b: Curve) -> Bool

impl Equatable.equal

enum ClientAuth
    NoCertificate
    Request
    RequireAny
    VerifyIfGiven
    Require
end

Whether a server asks the client for a certificate, and checks it.

Variants

  • NoCertificate

    Asks for none: Go’s NoClientCert.

  • Request

    Asks, and accepts any or none: RequestClientCert.

  • RequireAny

    Requires one, any one: RequireAnyClientCert.

  • VerifyIfGiven

    Checks one against client_roots when given: VerifyClientCertIfGiven.

  • Require

    Requires one and checks it: RequireAndVerifyClientCert.

impl Display for ClientAuth

fn to_string(auth: ClientAuth) -> String

impl Display.to_string

impl Debug for ClientAuth

fn inspect(value: ClientAuth) -> String

impl Debug.inspect

impl Equatable for ClientAuth

fn equal(a: ClientAuth, b: ClientAuth) -> Bool

impl Equatable.equal

enum Renegotiation
    Never
    OnceAsClient
    FreelyAsClient
end

Whether a client lets a server renegotiate.

impl Debug for Renegotiation

fn inspect(value: Renegotiation) -> String

impl Debug.inspect

impl Equatable for Renegotiation

fn equal(a: Renegotiation, b: Renegotiation) -> Bool

impl Equatable.equal

enum Roots
    System
    Pem String
    Files List<String>
end

The certificate authorities a side trusts.

Variants

  • System

    The operating system’s.

  • Pem

    The PEM certificates in the text.

  • Files

    The PEM certificates in the files.

impl Debug for Roots

fn inspect(value: Roots) -> String

impl Debug.inspect

struct CertificateInfo
    subject: String
    issuer: String
    serial: String
    not_before: Instant
    not_after: Instant
    dns_names: List<String>
end

What a certificate says: who it names and who signed it, when it is valid, and the DNS names it covers. The validity is a pair of moments, of any year X.509 writes: a certificate may be valid until 9999-12-31 (“no well-defined expiration”). Compare one with Instant.now():

expired = Instant.is_before(info.not_after, Instant.now())

impl Debug for CertificateInfo

fn inspect(value: CertificateInfo) -> String

impl Debug.inspect

impl Equatable for CertificateInfo

fn equal(a: CertificateInfo, b: CertificateInfo) -> Bool

impl Equatable.equal

struct Certificate
    handle: http_host.Certificate
end

A certificate chain and its private key, which a side presents. The key stays inside the value: nothing reads it back.

fn from_pem(cert: String, key: String) -> Result<Certificate, Error>

type function on Certificate

A certificate from PEM text: the chain, then its key. Go’s X509KeyPair.

fn load(cert_path: String, key_path: String) -> Result<Certificate, Error>

type function on Certificate

A certificate from PEM files. Go’s LoadX509KeyPair.

fn info(certificate: Certificate) -> CertificateInfo

type function on Certificate

What the chain’s first certificate says.

impl Debug for Certificate

fn inspect(value: Certificate) -> String

impl Debug.inspect

struct CipherSuite
    id: Int
    name: String
    versions: List<Version>
    insecure: Bool
end

A cipher suite Go’s TLS implements.

fn secure() -> List<CipherSuite>

type function on CipherSuite

The suites Go’s TLS uses by default: Go’s CipherSuites.

assert Iter.any_match(CipherSuite.secure(), fn s -> s.name == "TLS_AES_128_GCM_SHA256")
fn insecure() -> List<CipherSuite>

type function on CipherSuite

The suites Go implements but uses only when asked: InsecureCipherSuites.

fn name_of(id: Int) -> String

type function on CipherSuite

A suite’s standard name, or its ID in hex for a suite with no known name.

assert CipherSuite.name_of(0x1301) == "TLS_AES_128_GCM_SHA256"

impl Debug for CipherSuite

fn inspect(value: CipherSuite) -> String

impl Debug.inspect

impl Equatable for CipherSuite

fn equal(a: CipherSuite, b: CipherSuite) -> Bool

impl Equatable.equal

struct ClientConfig
    roots: Roots = Roots.System
    certificates: List<Certificate> = []
    server_name: Maybe<String> = None
    insecure_skip_verify: Bool = False
    next_protocols: List<String> = []
    min_version: Version = Version.Tls12
    max_version: Maybe<Version> = None
    cipher_suites: Maybe<List<Int>> = None
    curves: Maybe<List<Curve>> = None
    session_tickets: Bool = True
    session_cache: Int = 0
    renegotiation: Renegotiation = Renegotiation.Never
    verify: Maybe<(ConnectionState) -> Result<Unit, String>> = None
    key_log: Maybe<Writer> = None
end

How a client checks a server and what it offers.

fn host(config: ClientConfig) -> Result<http_host.TlsConfig, Error>

type function on ClientConfig

The configuration Go builds for this config, for std::http and std::net.

impl Debug for ClientConfig

fn inspect(value: ClientConfig) -> String

impl Debug.inspect

struct ServerConfig
    certificates: List<Certificate>
    client_auth: ClientAuth = ClientAuth.NoCertificate
    client_roots: Roots = Roots.System
    next_protocols: List<String> = []
    min_version: Version = Version.Tls12
    max_version: Maybe<Version> = None
    cipher_suites: Maybe<List<Int>> = None
    curves: Maybe<List<Curve>> = None
    session_tickets: Bool = True
    certificate_for: Maybe<(ClientHello) -> Maybe<Certificate>> = None
    verify: Maybe<(ConnectionState) -> Result<Unit, String>> = None
    key_log: Maybe<Writer> = None
end

What a server presents and how it checks clients.

fn host(config: ServerConfig) -> Result<http_host.TlsConfig, Error>

type function on ServerConfig

The configuration Go builds for this config, for std::http and std::net.

impl Debug for ServerConfig

fn inspect(value: ServerConfig) -> String

impl Debug.inspect

struct ClientHello
    server_name: String
    protocols: List<String>
    versions: List<Version>
    cipher_suites: List<Int>
    handle: http_host.Handle
end

What a client asked for when it started a handshake: Go’s ClientHelloInfo, for ServerConfig.certificate_for.

fn supports(hello: ClientHello, certificate: Certificate) -> Bool

type function on ClientHello

Whether the client can use certificate: its key, signature and curves are ones the client offered. Go’s SupportsCertificate.

impl Debug for ClientHello

fn inspect(value: ClientHello) -> String

impl Debug.inspect

struct ConnectionState
    version: Version
    handshake_complete: Bool
    resumed: Bool
    cipher_suite: CipherSuite
    curve: Maybe<Curve>
    protocol: Maybe<String>
    server_name: String
    local_certificate: Maybe<CertificateInfo>
    peer_certificates: List<CertificateInfo>
    verified_chains: List<List<CertificateInfo>>
end

What a finished handshake agreed on.

fn of_parts(parts: List<List<String>>) -> ConnectionState

type function on ConnectionState

The state a crossing returns: the handshake’s fields, the local certificate’s info, the peer’s certificates, then each verified chain.

impl Debug for ConnectionState

fn inspect(value: ConnectionState) -> String

impl Debug.inspect

enum Error
    Alert { code: Int, reason: String }
    Verification { reason: String, certificates: List<CertificateInfo> }
    NotTls { reason: String }
    Certificate { reason: String }
    Handshake { reason: String }
end

Why TLS failed.

Variants

  • Alert

    The peer sent an alert: Go’s AlertError.

  • Verification

    The peer’s certificate did not verify.

  • NotTls

    The peer did not speak TLS: Go’s RecordHeaderError.

  • Certificate

    A certificate or key that does not parse, or roots that hold none.

  • Handshake

    Any other handshake failure.

fn from_parts(parts: List<String>) -> Error

type function on Error

The error for the parts a crossing returns.

impl Display for Error

fn to_string(error: Error) -> String

impl Display.to_string

assert "${Error.NotTls{reason: "first record does not look like a TLS handshake"}}"
    == "the peer does not speak TLS: first record does not look like a TLS handshake"

impl Debug for Error

fn inspect(value: Error) -> String

impl Debug.inspect

impl Equatable for Error

fn equal(a: Error, b: Error) -> Bool

impl Equatable.equal

fn dial(address: String, config: ClientConfig = ClientConfig{}, options: net.DialOptions = net.DialOptions{}) -> Result<Connection, net.Error>

A TLS connection to address, its handshake done. The server name is the address’s host unless config names one.

fn client(conn: Connection, config: ClientConfig) -> Result<Connection, net.Error>

A TLS client over an open connection, as STARTTLS starts one. Use the result, not conn, from here on.

fn server(conn: Connection, config: ServerConfig) -> Result<Connection, net.Error>

The server side of client.

fn listen(address: String, config: ServerConfig) -> Result<net.Listener, net.Error>

A TCP listener whose connections are TLS servers with config.

fn state(conn: Connection) -> Maybe<ConnectionState>

What the connection’s handshake agreed on, or None when it is not a TLS connection.

fn wrap_listener(listener: net.Listener, config: ServerConfig) -> Result<net.Listener, net.Error>

The listener’s connections as TLS servers with config, each handshake done on the task that accepts it. It shares the listener: closing one closes both. Go’s NewListener.

fn verify_hostname(conn: Connection, host: String) -> Result<Unit, Error>

Whether the peer’s certificate covers host: Go’s VerifyHostname.