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.
Exports
Section titled “Exports”Types
enum Version
Section titled “enum Version”enum Version Tls10 Tls11 Tls12 Tls13 end
A TLS protocol version.
Version.to_string
Section titled “Version.to_string”impl Display for Version
fn to_string(version: Version) -> String
impl Display.to_string
assert "${Version.Tls13}" == "TLS 1.3"
Version.inspect
Section titled “Version.inspect”impl Debug for Version
fn inspect(value: Version) -> String
impl Debug.inspect
Version.equal
Section titled “Version.equal”impl Equatable for Version
fn equal(a: Version, b: Version) -> Bool
impl Equatable.equal
enum Curve
Section titled “enum Curve”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.
Curve.to_string
Section titled “Curve.to_string”impl Display for Curve
fn to_string(curve: Curve) -> String
impl Display.to_string
assert "${Curve.X25519MlKem768}" == "X25519MlKem768"
Curve.inspect
Section titled “Curve.inspect”impl Debug for Curve
fn inspect(value: Curve) -> String
impl Debug.inspect
Curve.equal
Section titled “Curve.equal”impl Equatable for Curve
fn equal(a: Curve, b: Curve) -> Bool
impl Equatable.equal
enum ClientAuth
Section titled “enum ClientAuth”enum ClientAuth NoCertificate Request RequireAny VerifyIfGiven Require end
Whether a server asks the client for a certificate, and checks it.
Variants
-
NoCertificateAsks for none: Go’s
NoClientCert. -
RequestAsks, and accepts any or none:
RequestClientCert. -
RequireAnyRequires one, any one:
RequireAnyClientCert. -
VerifyIfGivenChecks one against
client_rootswhen given:VerifyClientCertIfGiven. -
RequireRequires one and checks it:
RequireAndVerifyClientCert.
ClientAuth.to_string
Section titled “ClientAuth.to_string”impl Display for ClientAuth
fn to_string(auth: ClientAuth) -> String
impl Display.to_string
ClientAuth.inspect
Section titled “ClientAuth.inspect”impl Debug for ClientAuth
fn inspect(value: ClientAuth) -> String
impl Debug.inspect
ClientAuth.equal
Section titled “ClientAuth.equal”impl Equatable for ClientAuth
fn equal(a: ClientAuth, b: ClientAuth) -> Bool
impl Equatable.equal
enum Renegotiation
Section titled “enum Renegotiation”enum Renegotiation Never OnceAsClient FreelyAsClient end
Whether a client lets a server renegotiate.
Renegotiation.inspect
Section titled “Renegotiation.inspect”impl Debug for Renegotiation
fn inspect(value: Renegotiation) -> String
impl Debug.inspect
Renegotiation.equal
Section titled “Renegotiation.equal”impl Equatable for Renegotiation
fn equal(a: Renegotiation, b: Renegotiation) -> Bool
impl Equatable.equal
enum Roots
Section titled “enum Roots”enum Roots System Pem String Files List<String> end
The certificate authorities a side trusts.
Variants
-
SystemThe operating system’s.
-
PemThe PEM certificates in the text.
-
FilesThe PEM certificates in the files.
Roots.inspect
Section titled “Roots.inspect”impl Debug for Roots
fn inspect(value: Roots) -> String
impl Debug.inspect
struct CertificateInfo
Section titled “struct CertificateInfo”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())
CertificateInfo.inspect
Section titled “CertificateInfo.inspect”impl Debug for CertificateInfo
fn inspect(value: CertificateInfo) -> String
impl Debug.inspect
CertificateInfo.equal
Section titled “CertificateInfo.equal”impl Equatable for CertificateInfo
fn equal(a: CertificateInfo, b: CertificateInfo) -> Bool
impl Equatable.equal
struct Certificate
Section titled “struct Certificate”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.
Certificate.from_pem
Section titled “Certificate.from_pem”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.
Certificate.load
Section titled “Certificate.load”fn load(cert_path: String, key_path: String) -> Result<Certificate, Error>
type function on Certificate
A certificate from PEM files. Go’s LoadX509KeyPair.
Certificate.info
Section titled “Certificate.info”fn info(certificate: Certificate) -> CertificateInfo
type function on Certificate
What the chain’s first certificate says.
Certificate.inspect
Section titled “Certificate.inspect”impl Debug for Certificate
fn inspect(value: Certificate) -> String
impl Debug.inspect
struct CipherSuite
Section titled “struct CipherSuite”struct CipherSuite id: Int name: String versions: List<Version> insecure: Bool end
A cipher suite Go’s TLS implements.
CipherSuite.secure
Section titled “CipherSuite.secure”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")
CipherSuite.insecure
Section titled “CipherSuite.insecure”fn insecure() -> List<CipherSuite>
type function on CipherSuite
The suites Go implements but uses only when asked:
InsecureCipherSuites.
CipherSuite.name_of
Section titled “CipherSuite.name_of”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"
CipherSuite.inspect
Section titled “CipherSuite.inspect”impl Debug for CipherSuite
fn inspect(value: CipherSuite) -> String
impl Debug.inspect
CipherSuite.equal
Section titled “CipherSuite.equal”impl Equatable for CipherSuite
fn equal(a: CipherSuite, b: CipherSuite) -> Bool
impl Equatable.equal
struct ClientConfig
Section titled “struct ClientConfig”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.
ClientConfig.host
Section titled “ClientConfig.host”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.
ClientConfig.inspect
Section titled “ClientConfig.inspect”impl Debug for ClientConfig
fn inspect(value: ClientConfig) -> String
impl Debug.inspect
struct ServerConfig
Section titled “struct ServerConfig”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.
ServerConfig.host
Section titled “ServerConfig.host”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.
ServerConfig.inspect
Section titled “ServerConfig.inspect”impl Debug for ServerConfig
fn inspect(value: ServerConfig) -> String
impl Debug.inspect
struct ClientHello
Section titled “struct ClientHello”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.
ClientHello.supports
Section titled “ClientHello.supports”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.
ClientHello.inspect
Section titled “ClientHello.inspect”impl Debug for ClientHello
fn inspect(value: ClientHello) -> String
impl Debug.inspect
struct ConnectionState
Section titled “struct ConnectionState”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.
ConnectionState.of_parts
Section titled “ConnectionState.of_parts”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.
ConnectionState.inspect
Section titled “ConnectionState.inspect”impl Debug for ConnectionState
fn inspect(value: ConnectionState) -> String
impl Debug.inspect
enum Error
Section titled “enum Error”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
-
AlertThe peer sent an alert: Go’s
AlertError. -
VerificationThe peer’s certificate did not verify.
-
NotTlsThe peer did not speak TLS: Go’s
RecordHeaderError. -
CertificateA certificate or key that does not parse, or roots that hold none.
-
HandshakeAny other handshake failure.
Error.from_parts
Section titled “Error.from_parts”fn from_parts(parts: List<String>) -> Error
type function on Error
The error for the parts a crossing returns.
Error.to_string
Section titled “Error.to_string”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"
Error.inspect
Section titled “Error.inspect”impl Debug for Error
fn inspect(value: Error) -> String
impl Debug.inspect
Error.equal
Section titled “Error.equal”impl Equatable for Error
fn equal(a: Error, b: Error) -> Bool
impl Equatable.equal
tls.dial
Section titled “tls.dial”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.
tls.client
Section titled “tls.client”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.
tls.server
Section titled “tls.server”fn server(conn: Connection, config: ServerConfig) -> Result<Connection, net.Error>
The server side of client.
tls.listen
Section titled “tls.listen”fn listen(address: String, config: ServerConfig) -> Result<net.Listener, net.Error>
A TCP listener whose connections are TLS servers with config.
tls.state
Section titled “tls.state”fn state(conn: Connection) -> Maybe<ConnectionState>
What the connection’s handshake agreed on, or None when it is not a
TLS connection.
tls.wrap_listener
Section titled “tls.wrap_listener”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.
tls.verify_hostname
Section titled “tls.verify_hostname”fn verify_hostname(conn: Connection, host: String) -> Result<Unit, Error>
Whether the peer’s certificate covers host: Go’s VerifyHostname.