Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-tls

Source of release 0.7.1

0.7.1 / src / client.lucb

## The TLS 1.3 client handshake (RFC 8446 §4) over any byte source and sink:
## ClientHello with SNI, an optional HelloRetryRequest round, the encrypted
## server flight, certificate authentication under a Trust policy, and the
## client Finished. On success the channel holds application traffic keys.
## Out of scope: PSK resumption, 0-RTT and client certificates (a
## CertificateRequest is answered with an empty Certificate, RFC 8446 §4.4.2).
import io
import memory
import os
import time
from luce_crypto import native as crypto
import record
import handshake as hs
import signature
import trust

pub let invalid = crypto.invalid

let retry_random = b"\xcf\x21\xad\x74\xe5\x9a\x61\x11\xbe\x1d\x8c\x02\x1e\x65\xb8\x91\xc2\xa2\x11\x16\x7a\xbb\x8c\x5e\x07\x9e\x09\xe2\xc8\xa8\x33\x9c"

## The cipher suites this client offers, in preference order; only those the
## record layer supports are sent.
let offered_suites: u16[3] = [0x1301, 0x1302, 0x1303]

## The parts of a ServerHello or HelloRetryRequest the client acts on.
struct ServerHello:
    var retry: bool
    var suite: u16
    var group: u16
    var share: u8[97]
    var share_size: usize
    var cookie: u8[1024]
    var cookie_size: usize

## The ClientHello inputs that stay fixed across a HelloRetryRequest. The host name and
## the ALPN protocol are kept inside, so a handshake owns everything it needs between steps.
struct Hello:
    var random: u8[32]
    var session: u8[32]
    var host_bytes: u8[253]
    var host_size: usize
    var alpn_bytes: u8[255]
    var alpn_size: usize
    var certificate_requested: bool
    var request_context: u8[255]
    var request_context_size: usize

    ## The server name.
    func host() -> str:
        return (str)self.host_bytes[..<self.host_size]

    ## The one application protocol offered, or empty.
    func alpn() -> str:
        return (str)self.alpn_bytes[..<self.alpn_size]

## The message a client handshake waits for next (RFC 8446 §2, the client's view).
enum Stage:
    server_hello
    retried_server_hello
    encrypted_extensions
    certificate
    certificate_verify
    finished
    done
    failed

## A TLS 1.3 client handshake that advances as the server's messages arrive, so it can run
## over a nonblocking transport from an event loop as well as over a blocking one: `start`
## sends the ClientHello, each `step` processes whatever messages have arrived, and a source
## with nothing more yet (io.would_block) pauses it until the next step. What it sends goes
## to the sink in whole records. Close it when done, whatever the outcome.
pub struct Handshake:
    var stage: Stage
    var hello: Hello
    var policy: trust.Trust
    var now: i64
    var share: hs.KeyShare
    var messages: hs.Messages
    var schedule: hs.Schedule
    var suite: record.Suite
    var first: u8[2048]
    var first_size: usize
    var retried_suite: u16
    var server_key: signature.PublicKey

    ## Begin a handshake for `host` on an already connected transport: the ClientHello
    ## goes to `sink`. `now` is the Unix time for certificate validity; zero uses the wall
    ## clock. `alpn`, when not empty, is the one application protocol offered and must be
    ## what the server picks.
    pub static func start(channel: record.Channel*, sink: io.Writer, host: str, policy: const trust.Trust*, alpn: str = "",
                          now: i64 = 0) -> Handshake!:
        try check_host(host)
        if alpn.length > 255:
            error(invalid, "ALPN protocol name is too long")
        # The schedule restarts with the suite the server picks; until then it is the first offered one's.
        let suite = try record.suite_for(offered_suites[0])
        var handshake = Handshake(stage = Stage.server_hello, policy = *policy, now = now, suite = suite, schedule = try hs.Schedule.start(suite),
                                  share = try hs.KeyShare.generate(hs.group_x25519), messages = try hs.Messages.create())
        errdefer handshake.close()
        memory.copy(handshake.hello.host_bytes, host.bytes, host.length)
        handshake.hello.host_size = host.length
        memory.copy(handshake.hello.alpn_bytes, alpn.bytes, alpn.length)
        handshake.hello.alpn_size = alpn.length
        try os.random_bytes(handshake.hello.random)
        try os.random_bytes(handshake.hello.session)
        handshake.first_size = try build_hello(handshake.first, &handshake.hello, &handshake.share, b"")
        try channel.send(sink, record.handshake, handshake.first[..<handshake.first_size])
        return handshake

    ## Process the server's messages that `source` has, answering through `sink`; true once
    ## the handshake is complete and the channel holds application traffic keys. When the
    ## source has nothing more yet (io.would_block) the step stops with that error and the
    ## next step resumes where it stopped. Any other failure ends the handshake.
    pub func step(channel: record.Channel*, source: io.Reader, sink: io.Writer) -> bool!:
        if self.stage == Stage.failed:
            error(invalid, "the TLS handshake failed earlier")
        while self.stage != Stage.done:
            let message = self.messages.next(channel, source) catch failure:
                if failure.code != io.would_block:
                    self.stage = Stage.failed
                error(failure.code, failure.message)
            self.receive(channel, sink, message) catch failure:
                self.stage = Stage.failed
                error(failure.code, failure.message)
        return true

    ## Whether the handshake is complete.
    pub func complete() -> bool:
        return self.stage == Stage.done

    ## Erase the handshake's secrets and release its buffer; safe to repeat.
    pub func close():
        self.share.wipe()
        self.messages.close()
        self.schedule.wipe()
        crypto.wipe(u8[]((u8*)&self.first[0], memory.size_of(u8[2048])))

    ## One complete message from the server, in the current stage.
    func receive(channel: record.Channel*, sink: io.Writer, message: const u8[]) -> !:
        match self.stage:
            .server_hello:
                var server = ServerHello()
                try parse_server_hello(message, &self.hello, &server)
                self.suite = try record.suite_for(server.suite)
                self.schedule.wipe()
                self.schedule = try hs.Schedule.start(self.suite)
                if server.retry:
                    try self.retry(channel, sink, message, &server)
                    return
                try self.schedule.add(self.first[..<self.first_size])
                try self.enter_handshake(channel, message, &server)
            .retried_server_hello:
                var server = ServerHello()
                try parse_server_hello(message, &self.hello, &server)
                if server.retry or server.suite != self.retried_suite:
                    error(invalid, "ServerHello disagrees with the HelloRetryRequest")
                try self.enter_handshake(channel, message, &server)
            .encrypted_extensions:
                if message[0] != hs.encrypted_extensions:
                    error(invalid, "expected EncryptedExtensions")
                try check_encrypted_extensions(message, &self.hello)
                try self.schedule.add(message)
                self.stage = Stage.certificate
            .certificate:
                if message[0] == hs.certificate_request and not self.hello.certificate_requested:
                    try note_certificate_request(message, &self.hello)
                    try self.schedule.add(message)
                    return
                if message[0] != hs.certificate:
                    error(invalid, "expected the server Certificate")
                let at = self.now if self.now != 0 else time.unix()
                self.server_key = try trust.authenticate(&self.policy, message, self.hello.host(), at)
                try self.schedule.add(message)
                self.stage = Stage.certificate_verify
            .certificate_verify:
                try self.verify(message)
                try self.schedule.add(message)
                self.stage = Stage.finished
            .finished:
                try self.finish(channel, sink, message)
            .done, .failed:
                error(invalid, "unexpected TLS handshake message")

    ## A HelloRetryRequest: a new key share for the group the server asked for, and the
    ## second ClientHello.
    func retry(channel: record.Channel*, sink: io.Writer, message: const u8[], server: const ServerHello*) -> !:
        if server.group == self.share.group or not offers_group(server.group):
            error(invalid, "HelloRetryRequest selected an unusable group")
        try self.schedule.add_retry_hash(self.first[..<self.first_size])
        try self.schedule.add(message)
        self.share.wipe()
        self.share = try hs.KeyShare.generate(server.group)
        var second: u8[2048]
        let second_size = try build_hello(second, &self.hello, &self.share, server.cookie[..<server.cookie_size])
        try self.schedule.add(second[..<second_size])
        try channel.send(sink, record.handshake, second[..<second_size])
        self.retried_suite = server.suite
        self.stage = Stage.retried_server_hello

    ## The ServerHello that settles the key exchange: the shared secret, the handshake
    ## traffic keys for what the server sends next.
    func enter_handshake(channel: record.Channel*, message: const u8[], server: const ServerHello*) -> !:
        try self.schedule.add(message)
        if server.group != self.share.group:
            error(invalid, "ServerHello key share is for a group the client did not send")
        if not self.messages.empty():
            error(invalid, "handshake data straddles the TLS key change")
        var shared: u8[48]
        defer crypto.wipe(shared)
        let shared_size = try self.share.agree(server.share[..<server.share_size], shared)
        try self.schedule.enter_handshake(shared[..<shared_size])
        try channel.protect_read(self.suite, self.schedule.handshake_secret(false))
        self.stage = Stage.encrypted_extensions

    ## The server's CertificateVerify: its signature over the transcript so far.
    func verify(message: const u8[]) -> !:
        if message[0] != hs.certificate_verify or message.length < 8 or hs.message_length(message) != message.length - 4:
            error(invalid, "expected a well-formed CertificateVerify")
        let scheme = u16_at(message, 4)
        let size = (usize)u16_at(message, 6)
        if size != message.length - 8:
            error(invalid, "CertificateVerify signature length mismatch")
        var transcript_hash: u8[48]
        let hash_size = try self.schedule.current(transcript_hash)
        var content: u8[160]
        let content_size = hs.verify_content(true, transcript_hash[..<hash_size], content)
        try signature.verify_scheme(&self.server_key, scheme, content[..<content_size], message[8..])

    ## The server's Finished, then the client's flight and the application traffic keys.
    func finish(channel: record.Channel*, sink: io.Writer, message: const u8[]) -> !:
        let hash_size = self.suite.hash_size
        var expected: u8[48]
        try self.schedule.finished_value(self.schedule.handshake_secret(false), expected[..<hash_size])
        try hs.check_finished(message, expected[..<hash_size])
        try self.schedule.add(message)
        if not self.messages.empty():
            error(invalid, "unexpected handshake data after server Finished")
        var client_secret: u8[48]
        var server_secret: u8[48]
        defer crypto.wipe(client_secret)
        defer crypto.wipe(server_secret)
        try self.schedule.enter_application(client_secret, server_secret)
        try client_flight(channel, sink, &self.schedule, &self.hello, self.suite)
        try channel.start_application(self.suite, server_secret[..<hash_size], client_secret[..<hash_size])
        self.stage = Stage.done

## Run the client handshake for `host` on an already connected transport to its end.
## `source` and `sink` usually view the same connection. `now` is the Unix time
## for certificate validity; zero uses the wall clock. `alpn`, when not empty,
## is the one application protocol offered and must be what the server picks.
pub func connect(channel: record.Channel*, source: io.Reader, sink: io.Writer, host: str,
                 policy: const trust.Trust*, alpn: str = "", now: i64 = 0) -> !:
    var handshake = try Handshake.start(channel, sink, host, policy, alpn, now)
    defer handshake.close()
    while not try handshake.step(channel, source, sink):
        continue

## Whether `group` is one the client listed in supported_groups.
func offers_group(group: u16) -> bool:
    return group == hs.group_x25519 or (group == hs.group_secp256r1 and hs.p256_key_exchange)

func offers_suite(suite: u16) -> bool:
    for i in 0..<offered_suites.length:
        if offered_suites[i] == suite and record.suite_supported(suite):
            return true
    return false

## Server names are 1–253 ASCII bytes; SNI is omitted for IP literals.
func check_host(host: str) -> !:
    if host.length == 0 or host.length > 253:
        error(invalid, "TLS host name must be 1 to 253 bytes")
    for i in 0..<host.length:
        let c = host.bytes[i]
        if c <= 0x20 or c >= 0x7f:
            error(invalid, "TLS host name must be printable ASCII")

func is_ip_literal(host: str) -> bool:
    var dots: usize = 0
    for i in 0..<host.length:
        let c = host.bytes[i]
        if c == ':':
            return true
        if c == '.':
            dots += 1
        elif c < '0' or c > '9':
            return false
    return dots == 3

## Encode a ClientHello handshake message into `out`; returns its length.
func build_hello(out: u8[], hello: const Hello*, share: const hs.KeyShare*, cookie: const u8[]) -> usize!:
    var b = hs.Builder.over(out)
    b.put8(hs.client_hello)
    let body = b.open(3)
    b.put16(0x0303)
    b.put(hello.random)
    b.put8(32)
    b.put(hello.session)
    let suites = b.open(2)
    for i in 0..<offered_suites.length:
        if record.suite_supported(offered_suites[i]):
            b.put16((usize)offered_suites[i])
    b.close(suites, 2)
    b.put8(1)
    b.put8(0)
    let extensions = b.open(2)
    let host = hello.host()
    if not is_ip_literal(host):
        b.put16(0x0000)
        let sni = b.open(2)
        let list = b.open(2)
        b.put8(0)
        b.put16(host.length)
        b.put(host.bytes)
        b.close(list, 2)
        b.close(sni, 2)
    b.put16(0x002b)
    b.put16(3)
    b.put8(2)
    b.put16(0x0304)
    b.put16(0x000a)
    let groups = b.open(2)
    let group_list = b.open(2)
    b.put16((usize)hs.group_x25519)
    if hs.p256_key_exchange:
        b.put16((usize)hs.group_secp256r1)
    b.close(group_list, 2)
    b.close(groups, 2)
    b.put16(0x000d)
    let algorithms = b.open(2)
    let scheme_list = b.open(2)
    b.put(signature.offered_schemes)
    b.close(scheme_list, 2)
    b.close(algorithms, 2)
    b.put16(0x0033)
    let shares = b.open(2)
    let share_list = b.open(2)
    b.put16((usize)share.group)
    b.put16(share.public_key().length)
    b.put(share.public_key())
    b.close(share_list, 2)
    b.close(shares, 2)
    let protocol = hello.alpn()
    if protocol.length > 0:
        b.put16(0x0010)
        let alpn = b.open(2)
        let names = b.open(2)
        b.put8((u8)protocol.length)
        b.put(protocol.bytes)
        b.close(names, 2)
        b.close(alpn, 2)
    if cookie.length > 0:
        b.put16(0x002c)
        let cookie_extension = b.open(2)
        b.put16(cookie.length)
        b.put(cookie)
        b.close(cookie_extension, 2)
    b.close(extensions, 2)
    b.close(body, 3)
    return b.size()

func u16_at(data: const u8[], at: usize) -> u16:
    return ((u16)data[at] << 8) | (u16)data[at + 1]

## Parse a ServerHello or HelloRetryRequest (RFC 8446 §4.1.3, §4.1.4).
func parse_server_hello(message: const u8[], hello: const Hello*, out: ServerHello*) -> !:
    if message.length < 4 or message[0] != hs.server_hello or hs.message_length(message) != message.length - 4:
        error(invalid, "expected a ServerHello")
    if message.length < 4 + 2 + 32 + 1:
        error(invalid, "truncated ServerHello")
    if message[4] != 3 or message[5] != 3:
        error(invalid, "unexpected ServerHello legacy version")
    out.retry = crypto.equal(message[6..<38], retry_random)
    var at: usize = 38
    let session_size = (usize)message[at]
    at += 1
    if session_size != 32 or message.length - at < 32 + 5:
        error(invalid, "ServerHello session id mismatch")
    if not crypto.equal(message[at..<at + 32], hello.session):
        error(invalid, "ServerHello session id mismatch")
    at += 32
    out.suite = u16_at(message, at)
    if not offers_suite(out.suite):
        error(invalid, "the server selected a cipher suite the client did not offer")
    if message[at + 2] != 0:
        error(invalid, "ServerHello selected non-null compression")
    at += 3
    let extensions_size = (usize)u16_at(message, at)
    at += 2
    if extensions_size != message.length - at:
        error(invalid, "ServerHello extension length mismatch")
    var have_version = false
    var have_share = false
    while at < message.length:
        if message.length - at < 4:
            error(invalid, "truncated ServerHello extension")
        let kind = u16_at(message, at)
        let size = (usize)u16_at(message, at + 2)
        at += 4
        if size > message.length - at:
            error(invalid, "ServerHello extension runs past its container")
        let value = message[at..<at + size]
        if kind == 0x002b:
            if have_version or size != 2 or value[0] != 3 or value[1] != 4:
                error(invalid, "the server did not select TLS 1.3")
            have_version = true
        elif kind == 0x0033:
            if have_share:
                error(invalid, "duplicate ServerHello key_share")
            try parse_share(value, out)
            have_share = true
        elif kind == 0x002c and out.retry:
            if out.cookie_size != 0 or size < 3 or (usize)u16_at(value, 0) != size - 2 or size - 2 > out.cookie.length:
                error(invalid, "invalid HelloRetryRequest cookie")
            for i in 0..<size - 2:
                out.cookie[i] = value[2 + i]
            out.cookie_size = size - 2
        else:
            error(invalid, "ServerHello carries an extension the client did not offer")
        at += size
    if not have_version or (not have_share and not out.retry):
        error(invalid, "ServerHello lacks required TLS 1.3 extensions")
    if out.retry and not have_share and out.cookie_size == 0:
        error(invalid, "HelloRetryRequest would not change the ClientHello")

func parse_share(value: const u8[], out: ServerHello*) -> !:
    if value.length < 2:
        error(invalid, "truncated key_share")
    out.group = u16_at(value, 0)
    if not offers_group(out.group):
        error(invalid, "the server selected a group the client did not offer")
    if out.retry:
        if value.length != 2:
            error(invalid, "invalid HelloRetryRequest key_share")
        return
    if value.length < 4 or (usize)u16_at(value, 2) != value.length - 4 or value.length - 4 > out.share.length:
        error(invalid, "invalid ServerHello key_share")
    for i in 0..<value.length - 4:
        out.share[i] = value[4 + i]
    out.share_size = value.length - 4

## Remember a CertificateRequest's context; the client answers it with an
## empty certificate list. Its extensions are not interpreted.
func note_certificate_request(message: const u8[], hello: Hello*) -> !:
    if message.length < 5 or hs.message_length(message) != message.length - 4:
        error(invalid, "malformed CertificateRequest")
    let size = (usize)message[4]
    if message.length - 5 < size + 2 or (usize)u16_at(message, 5 + size) != message.length - 7 - size:
        error(invalid, "malformed CertificateRequest")
    for i in 0..<size:
        hello.request_context[i] = message[5 + i]
    hello.request_context_size = size
    hello.certificate_requested = true

## EncryptedExtensions must be well formed; a selected ALPN protocol must be
## exactly the one offered.
func check_encrypted_extensions(message: const u8[], hello: const Hello*) -> !:
    if message.length < 6 or hs.message_length(message) != message.length - 4 or (usize)u16_at(message, 4) != message.length - 6:
        error(invalid, "malformed EncryptedExtensions")
    var at: usize = 6
    while at < message.length:
        if message.length - at < 4:
            error(invalid, "truncated EncryptedExtensions entry")
        let kind = u16_at(message, at)
        let size = (usize)u16_at(message, at + 2)
        at += 4
        if size > message.length - at:
            error(invalid, "EncryptedExtensions entry runs past its container")
        if kind == 0x0010:
            let value = message[at..<at + size]
            let name = hello.alpn().bytes
            if name.length == 0 or size != 3 + name.length or (usize)u16_at(value, 0) != size - 2 or (usize)value[2] != name.length:
                error(invalid, "the server selected an ALPN protocol the client did not offer")
            if not crypto.equal(value[3..], name):
                error(invalid, "the server selected an ALPN protocol the client did not offer")
        elif kind == 0x002b or kind == 0x0033 or kind == 0x0029:
            error(invalid, "EncryptedExtensions carries a ServerHello-only extension")
        at += size

## Send change_cipher_spec (middlebox compatibility), an empty Certificate
## when one was requested, and the client Finished.
func client_flight(channel: record.Channel*, sink: io.Writer, schedule: hs.Schedule*, hello: const Hello*, suite: record.Suite) -> !:
    let ccs = b"\x01"
    try channel.send(sink, record.change_cipher_spec, ccs)
    try channel.protect_write(suite, schedule.handshake_secret(true))
    if hello.certificate_requested:
        var empty: u8[264]
        var b = hs.Builder.over(empty)
        b.put8(hs.certificate)
        let body = b.open(3)
        b.put8((u8)hello.request_context_size)
        b.put(hello.request_context[..<hello.request_context_size])
        _ = b.open(3)
        b.close(body, 3)
        try schedule.add(empty[..<b.size()])
        try channel.send(sink, record.handshake, empty[..<b.size()])
    var verify: u8[48]
    try schedule.finished_value(schedule.handshake_secret(true), verify[..<suite.hash_size])
    var message: u8[52]
    message[0] = hs.finished
    message[3] = (u8)suite.hash_size
    for i in 0..<suite.hash_size:
        message[4 + i] = verify[i]
    try schedule.add(message[..<4 + suite.hash_size])
    try channel.send(sink, record.handshake, message[..<4 + suite.hash_size])