Tls

The sentence behind an error ("the certificate has expired"), or "". It is a copy in temporary storage, so it stays valid when the error is copied or goes out of scope, until the temporary storage is reset; copy it with copy_string to keep it longer.

The name of an alert description ("unknown_ca"), or "" for a number the module does not know.

One line for logs and messages: "certificate verification failed: the certificate has expired". Like detail, the text is in temporary storage, never inside the error.

line := error_text(Tls_Error.{ kind = .CLOSED });
assert(line.count > 0);

Parses the certificates and keys and builds the mbedTLS configurations. Call it once before the first connection; the config must stay where it is and outlive every stream made from it. Returns .CONFIG with a reason for a certificate or key that does not parse, a version range that is empty, or a server certificate without its key. A config with no certificate is a client; one with a certificate and key can also accept.

config: Tls_Config; // a client, trusting the system's roots
error := tls_config_init(*config);
assert(error.kind == .NONE, "%", error_text(error));
tls_config_free(*config);

Releases what tls_config_init built. Streams made from the config must be closed first.

config: Tls_Config;
tls_config_init(*config);
tls_config_free(*config);

Whether tls_accept works with this config: it was set up, and has a certificate and key.

client: Tls_Config;
tls_config_init(*client);
assert(!can_accept(*client)); // no certificate and key
tls_config_free(*client);

Runs the client handshake over reader and writer and checks the server's certificate against server_name (which is also sent as the SNI name; "" sends none, and with verify_name off the name is not checked). On success the stream owns the connection: close closes it. On an error nothing is closed, the connection is the caller's to close.

Io :: #import "Extensions/Io";

Io.io_run(() {
    config: Tls_Config;
    tls_config_init(*config);
    defer tls_config_free(*config);

    tcp, io_error := Io.connect("example.com:443");
    assert(io_error == .NONE);

    stream, error := tls_connect(*config, Io.reader_of(tcp), Io.writer_of(tcp), "example.com");
    if error.kind != .NONE {
        Io.close(tcp);
        return;
    }
    defer close(stream);

    write(stream, "hello");
});

Runs the server handshake. The config needs a certificate and key. On success the stream owns the connection; on an error the caller closes it.

Io :: #import "Extensions/Io";

// `config` has a certificate chain and private key; `listener` is an Io.Tcp_Listener.
serve_one :: (config: *Tls_Config, listener: Io.Tcp_Listener) {
    tcp, io_error := Io.accept(listener);
    if io_error != .NONE return;

    stream, error := tls_accept(config, Io.reader_of(tcp), Io.writer_of(tcp));
    if error.kind != .NONE {
        Io.close(tcp);
        return;
    }
    defer close(stream);

    write(stream, "welcome");
}

The ALPN protocol both sides chose ("" when none was).

uses_http2 :: (stream: *Tls_Stream) -> bool {
    return alpn_protocol(stream) == "h2";
}

The cipher suite in use, by mbedTLS's name ("TLS1-3-AES-128-GCM-SHA256", "TLS-ECDHE-ECDSA-WITH-CHACHA20-POLY1305-SHA256").

The DER of the certificate the peer proved itself with (the first of its chain): the server's on a client stream, the client's on a server stream that asked for one. The bytes belong to the stream and stay valid until close. Empty before the handshake or when the peer sent none.

The hash the peer certificate's signature uses, by lower-case name: "md5", "sha1", "sha224", "sha256", "sha384" or "sha512". "" when there is no certificate or the algorithm names no hash (Ed25519, unknown OIDs). It reads the certificate's own DER, not the library's view of it.

The name a client asked for in its SNI extension, on a stream from tls_accept ("" if it sent none). It points into the stream.

"TLSv1.3" or "TLSv1.2".

Why the last call that failed did (.NONE before any failure).

Waits for data and reads what is there, up to buffer.count bytes. 0 is the end: the peer sent close_notify. A connection that ends without it is an error (.CONNECTION_RESET, and last_error says .TRUNCATED): the data may have been cut off.

read_greeting :: (stream: *Tls_Stream) -> string {
    buffer: [64] u8;
    count, error := read(stream, buffer);
    if error != .NONE || count == 0 return "";
    return copy_string(string.{ count, buffer.data });
}

Waits until the library has accepted at least one byte of bytes and sends it, together with the records of as many more bytes as fit in BATCH_BYTES; returns how many it took.

Sends all of bytes. On an error it returns how many went out. Sends all of bytes, waiting for the peer as needed, and returns how many went out with an Io.Io_Error. On .NONE that is bytes.count; on an error it is the bytes that were already sent. It is the same as write_some repeated, so a large write is split into records and may take several scheduler turns. Use write_some to send what fits without looping.

send_frame :: (stream: *Tls_Stream) {
    frame := u8.[1, 2, 3];
    sent, error := write(stream, frame);
    assert(error == .NONE && sent == frame.count);
}

Waits until read would not have to wait for the network: decrypted bytes are waiting, or something has arrived (which may still be only part of a record).

Ends the stream: sends close_notify (unless now, which does not wait and sends nothing) and closes the connection under it, which wakes fibers still waiting on it with .CLOSED. The stream is freed once those fibers have left, so it must not be used after close; close it once.

finish :: (stream: *Tls_Stream) {
    close(stream); // sends close_notify, closes the TCP connection, frees the stream
}

Whether reader is a TLS stream's reader (from reader_of) whose connection ended without the peer's close_notify (last_error(stream).kind == .TRUNCATED). For a protocol that frames its own messages, such as HTTP, where that end is no failure once the message is complete.

The stream as an Io.Reader, for code written against readers (Io.read_all, the Http client). Reading it is read; closing it closes the whole stream, once. The reader points at the stream, so it is only valid until close.

Io :: #import "Extensions/Io";

read_everything :: (stream: *Tls_Stream) -> string {
    data, error := Io.read_all(reader_of(stream));
    return cast(string) data;
}

The stream as an Io.Writer, for code written against writers. Writing it is write_some; closing it closes the whole stream, once, so close either the reader or the writer of a stream and not both. It is only valid until close.

Reads the names of the certificate in der. False when the DER is not a certificate.

Releases the lists inside names (allocated with context.allocator by certificate_names) and resets it. The strings in it pointed into the DER, so they are not valid afterwards.

Asks Security.framework whether chain (DER, the server's certificate first) is a valid chain for server_name. "" if it is, else why not.

What went wrong, in one value for everything the module does: a bad certificate in a config, a handshake that failed, a peer that is not who it says it is, a connection that broke.

config: Tls_Config;
config.certificate_chain_pem = "this is not a certificate";
config.private_key_pem = "this is not a key";

error := tls_config_init(*config);
assert(error.kind == .CONFIG);
assert(error_text(error).count > 0);

The sentence for people ("the certificate has expired") is kept inside the error in detail_bytes; read it with detail(*error) or print the whole error with error_text. code is mbedTLS's own negative error number (0 when the error did not come from it).

A TLS protocol version, for Tls_Config.min_version and max_version: the range a client offers or a server accepts. The defaults are the whole range, TLS_1_2 to TLS_1_3, and the version that was settled on is reported by version(stream) as "TLSv1.2" or "TLSv1.3". Older versions are not supported. tls_config_init fails with .CONFIG when the range is empty (min_version above max_version).

config: Tls_Config;
config.min_version = .TLS_1_3;
config.max_version = .TLS_1_2;

error := tls_config_init(*config);
assert(error.kind == .CONFIG);

Decides whether to trust a peer's certificate chain, instead of mbedTLS's own verification. chain is the peer's certificates in DER, its own first; server_name is what the client asked for (empty on the server). Returns "" to accept, or why the chain is rejected. It runs on the fiber that is doing the handshake, after the handshake itself succeeded, and may wait.

Gets one line of the NSS key log format (no newline), such as CLIENT_HANDSHAKE_TRAFFIC_SECRET <client random> <secret>, in hex.

Zero-initialised, a config is a client that verifies servers against the system's roots. Fill in the fields you need, then call tls_config_init.

client: Tls_Config;
client.alpn = .["h2", "http/1.1"];
assert(tls_config_init(*client).kind == .NONE);
defer tls_config_free(*client);

A TLS connection over any Io.Reader and Io.Writer pair. Read and write it with read, write_some and write, or through reader_of and writer_of.

Slices into the DER the names were read from: they are valid as long as it is.

CERT_CHAIN_PARA up to pftCacheResync, the part every Windows version since Vista reads.

HTTPSPolicyCallbackData

The library makes one record per call (up to 8 KiB of data); a write of more goes through several records into out and reaches the connection in one send, up to this much, instead of one send (and one trip through the scheduler) per record.

What the library returns, by name (all negative).

The library's own network codes (its sockets are not compiled in): what the BIO callbacks return when the Io call under them failed. The stream keeps the Io_Error.

mbedtls_x509_crt_verify's result bits.