Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-tls

Source of release 0.7.0

0.7.0 / src / record.lucb

## The TLS 1.3 record layer (RFC 8446 §5 and §7.3): cipher-suite parameters,
## per-direction traffic keys, and the Channel that carries both directions of
## one connection. Incoming records are reassembled incrementally, so a read
## interrupted by a deadline resumes exactly where it stopped, and are decrypted
## in place: decrypted application data stays in the record buffer until the
## caller consumes it, which is what `pending` reports. The channel reads only
## the bytes of one record at a time, so socket readiness and `pending` together
## describe everything that is available.
import io
from luce_crypto import native as crypto
import tls
import memory

pub let invalid = crypto.invalid

## RFC 8446 §5.1 content types.
pub let change_cipher_spec: u8 = 20
pub let alert: u8 = 21
pub let handshake: u8 = 22
pub let application_data: u8 = 23

## RFC 8446 §B.4 cipher suites.
pub let aes_128_gcm_sha256: u16 = 0x1301
pub let aes_256_gcm_sha384: u16 = 0x1302
pub let chacha20_poly1305_sha256: u16 = 0x1303

## The largest plaintext fragment of one record.
pub let max_fragment: usize = 16384
let header_size: usize = 5
let max_body: usize = 16384 + 256
let tag_size: usize = 16

## A cipher suite's hash and key sizes.
pub struct Suite:
    pub var id: u16
    pub var hash: str
    pub var hash_size: usize
    pub var key_size: usize

## The parameters of a supported cipher suite.
pub func suite_for(id: u16) -> Suite!:
    if id == aes_128_gcm_sha256:
        return Suite(id = id, hash = "sha256", hash_size = 32, key_size = 16)
    if id == aes_256_gcm_sha384:
        return Suite(id = id, hash = "sha384", hash_size = 48, key_size = 32)
    if id == chacha20_poly1305_sha256:
        return Suite(id = id, hash = "sha256", hash_size = 32, key_size = 32)
    error(invalid, "unsupported TLS cipher suite")

## Whether this build can protect records with `id`.
pub func suite_supported(id: u16) -> bool:
    return id == aes_128_gcm_sha256 or id == aes_256_gcm_sha384 or id == chacha20_poly1305_sha256

## A diagnostic for a received fatal alert (RFC 8446 §6.2).
func alert_message(description: u8) -> str:
    if description == 10: return "the peer sent the TLS alert unexpected_message"
    if description == 20: return "the peer sent the TLS alert bad_record_mac"
    if description == 40: return "the peer sent the TLS alert handshake_failure"
    if description == 42: return "the peer sent the TLS alert bad_certificate"
    if description == 47: return "the peer sent the TLS alert illegal_parameter"
    if description == 48: return "the peer sent the TLS alert unknown_ca"
    if description == 50: return "the peer sent the TLS alert decode_error"
    if description == 51: return "the peer sent the TLS alert decrypt_error"
    if description == 70: return "the peer sent the TLS alert protocol_version"
    if description == 80: return "the peer sent the TLS alert internal_error"
    if description == 109: return "the peer sent the TLS alert missing_extension"
    if description == 112: return "the peer sent the TLS alert unrecognized_name"
    if description == 116: return "the peer sent the TLS alert certificate_required"
    if description == 120: return "the peer sent the TLS alert no_application_protocol"
    return "the peer sent a fatal TLS alert"

func seal(id: u16, key: const u8[], nonce: const u8[], aad: const u8[], plain: const u8[], cipher: u8[], tag: u8[]) -> !:
    if id == chacha20_poly1305_sha256:
        try crypto.aead_seal(key, nonce, aad, plain, cipher, tag)
    else:
        try crypto.aes_gcm_seal(key, nonce, aad, plain, cipher, tag)

func open(id: u16, key: const u8[], nonce: const u8[], aad: const u8[], cipher: const u8[], tag: const u8[], plain: u8[]) -> !:
    if id == chacha20_poly1305_sha256:
        try crypto.aead_open(key, nonce, aad, cipher, tag, plain)
    else:
        try crypto.aes_gcm_open(key, nonce, aad, cipher, tag, plain)

## One direction's record protection: AEAD key, static IV and sequence number.
## The zero value is unprotected, for the plaintext records that open a handshake.
pub struct Cipher:
    var suite: u16
    var key: u8[32]
    var key_size: usize
    var iv: u8[12]
    var sequence: u64

    ## Derive the key and IV of `suite` from a traffic secret (RFC 8446 §7.3).
    pub static func from_secret(suite: Suite, secret: const u8[]) -> Cipher!:
        var cipher = Cipher(suite = suite.id, key_size = suite.key_size)
        try tls.expand_label(secret, b"key", b"", cipher.key[..<suite.key_size], suite.hash)
        try tls.expand_label(secret, b"iv", b"", cipher.iv, suite.hash)
        return cipher

    ## Whether records in this direction are encrypted.
    pub func protected() -> bool:
        return self.suite != 0

    ## The per-record nonce: the IV with the sequence number XORed into its tail.
    func nonce(out: u8[]):
        for i in 0..<12:
            out[i] = self.iv[i]
        for i in 0..<8:
            out[4 + i] ^= (u8)(self.sequence >> (u64)(56 - 8 * i))

    ## Erase the key material of this exact object.
    pub func wipe():
        crypto.wipe(u8[]((u8*)&self, memory.size_of(Cipher)))

## Both directions of one TLS connection without its transport. The reader
## reassembles one record at a time in `record`; decrypted plaintext stays there
## in [start, end) until consumed. Copying a channel copies its keys and state;
## use one copy at a time and `wipe` it when done.
pub struct Channel:
    var read: Cipher
    var write: Cipher
    var suite: u16
    var read_secret: u8[48]
    var write_secret: u8[48]
    var record: u8[16645]
    var received: usize
    var kind: u8
    var start: usize
    var end: usize
    var peer_closed: bool
    var key_update_due: bool
    var failed: bool

    ## Decrypted application data received but not yet read. A readiness wait on
    ## the socket cannot see these bytes, so check this first.
    pub func pending() -> usize:
        if self.kind != application_data:
            return 0
        return self.end - self.start

    ## The unread plaintext of the last record returned by `next`.
    pub func plaintext() -> const u8[]:
        return self.record[self.start..<self.end]

    ## Mark the current record's plaintext as consumed.
    pub func consume(count: usize):
        assert(count <= self.end - self.start)
        self.start += count

    ## The negotiated cipher suite (RFC 8446 §B.4), or zero before the handshake.
    pub func cipher_suite() -> u16:
        return self.suite

    ## Whether application keys are installed and no error has occurred.
    pub func established() -> bool:
        return self.write.protected() and self.read.protected() and not self.failed

    ## Whether the peer sent close_notify.
    pub func closed_by_peer() -> bool:
        return self.peer_closed

    ## Protect incoming records with keys from a handshake traffic secret.
    pub func protect_read(suite: Suite, secret: const u8[]) -> !:
        self.read = try Cipher.from_secret(suite, secret)

    ## Protect outgoing records with keys from a handshake traffic secret.
    pub func protect_write(suite: Suite, secret: const u8[]) -> !:
        self.write = try Cipher.from_secret(suite, secret)

    ## Install application traffic secrets and their keys.
    pub func start_application(suite: Suite, read_secret: const u8[], write_secret: const u8[]) -> !:
        self.suite = suite.id
        for i in 0..<suite.hash_size:
            self.read_secret[i] = read_secret[i]
            self.write_secret[i] = write_secret[i]
        self.read = try Cipher.from_secret(suite, read_secret)
        self.write = try Cipher.from_secret(suite, write_secret)

    ## Read the rest of one record from `source`. Bytes already received are
    ## kept, so after a timeout the next call continues the same record. Only
    ## transport errors leave the channel usable; protocol errors fail it.
    func fill(source: io.Reader) -> !:
        while true:
            var want = header_size
            if self.received >= header_size:
                want = header_size + (((usize)self.record[3] << 8) | (usize)self.record[4])
                if self.received == want:
                    return
            let count = try source.read(self.record[self.received..<want])
            if count == 0:
                self.failed = true
                if self.received == 0:
                    error(io.unexpected_eof, "the peer closed the connection without close_notify")
                error(io.unexpected_eof, "the peer closed the connection inside a TLS record")
            self.received += count
            if self.received == header_size:
                let header = tls.parse_record(self.record[..<header_size]) catch failure:
                    self.failed = true
                    error(failure.code, failure.message)
                let limit = max_body if self.read.protected() else max_fragment
                if header.length == 0 or (usize)header.length > limit:
                    self.failed = true
                    error(invalid, "TLS record length is out of range")

    ## Receive and unprotect the next record, returning its content type. Its
    ## plaintext is `plaintext()`. A change_cipher_spec record is returned as is
    ## for the handshake to judge. Unread plaintext must be consumed first.
    pub func next(source: io.Reader) -> u8!:
        if self.failed:
            error(invalid, "the TLS channel failed earlier")
        if self.start != self.end:
            error(invalid, "unread TLS plaintext would be overwritten")
        try self.fill(source)
        errdefer self.failed = true
        let length = self.received - header_size
        self.received = 0
        self.kind = self.record[0]
        self.start = header_size
        self.end = header_size + length
        if self.kind == change_cipher_spec:
            if length != 1 or self.record[header_size] != 1:
                error(invalid, "malformed change_cipher_spec record")
            return self.kind
        if not self.read.protected():
            return self.kind
        if self.kind != application_data or length < tag_size + 1:
            error(invalid, "unexpected record type under TLS record protection")
        var nonce: u8[12]
        self.read.nonce(nonce)
        let sealed = length - tag_size
        let body = self.record[header_size..<header_size + sealed]
        try open(self.read.suite, self.read.key[..<self.read.key_size], nonce, self.record[..<header_size], body,
                 self.record[header_size + sealed..<header_size + length], body)
        self.read.sequence += 1
        var at = sealed
        while at > 0 and body[at - 1] == 0:
            at -= 1
        if at == 0:
            error(invalid, "protected TLS record has no content type")
        if at - 1 > max_fragment:
            error(invalid, "TLS record plaintext exceeds 2^14 bytes")
        self.kind = body[at - 1]
        self.end = header_size + at - 1
        if self.kind == change_cipher_spec:
            error(invalid, "change_cipher_spec inside TLS record protection")
        if self.kind != handshake and self.kind != application_data and self.kind != alert:
            error(invalid, "unknown TLS inner content type")
        if self.kind != application_data and self.end == self.start:
            error(invalid, "empty TLS handshake or alert record")
        return self.kind

    ## Send `data` as records of content type `kind`, fragmenting at 2^14 bytes.
    ## A failed write leaves the peer with a partial record, so the channel is
    ## unusable afterwards.
    pub func send(sink: io.Writer, kind: u8, data: const u8[]) -> !:
        if self.failed:
            error(invalid, "the TLS channel failed earlier")
        errdefer self.failed = true
        var done: usize = 0
        while true:
            let size = max_fragment if data.length - done > max_fragment else data.length - done
            try self.send_fragment(sink, kind, data[done..<done + size])
            done += size
            if done == data.length:
                return

    func send_fragment(sink: io.Writer, kind: u8, fragment: const u8[]) -> !:
        var record: u8[16406]
        record[1] = 3
        record[2] = 3
        if not self.write.protected():
            record[0] = kind
            record[3] = (u8)(fragment.length >> 8)
            record[4] = (u8)fragment.length
            for i in 0..<fragment.length:
                record[header_size + i] = fragment[i]
            try io.write_all(sink, record[..<header_size + fragment.length])
            return
        let inner = fragment.length + 1
        let length = inner + tag_size
        record[0] = application_data
        record[3] = (u8)(length >> 8)
        record[4] = (u8)length
        for i in 0..<fragment.length:
            record[header_size + i] = fragment[i]
        record[header_size + fragment.length] = kind
        var nonce: u8[12]
        self.write.nonce(nonce)
        let body = record[header_size..<header_size + inner]
        try seal(self.write.suite, self.write.key[..<self.write.key_size], nonce, record[..<header_size], body, body,
                 record[header_size + inner..<header_size + length])
        self.write.sequence += 1
        try io.write_all(sink, record[..<header_size + length])

    ## Send a fatal or warning alert (RFC 8446 §6).
    pub func send_alert(sink: io.Writer, level: u8, description: u8) -> !:
        var body: u8[2]
        body[0] = level
        body[1] = description
        try self.send(sink, alert, body)

    ## Read application data into `buffer`, receiving records as needed. Zero
    ## means the peer sent close_notify. Post-handshake NewSessionTicket messages
    ## are ignored and KeyUpdate is honoured (RFC 8446 §4.6.3).
    pub func read_application(source: io.Reader, buffer: u8[]) -> usize!:
        if buffer.length == 0:
            return 0
        while self.pending() == 0:
            if self.peer_closed:
                return 0
            self.start = self.end
            let kind = try self.next(source)
            if kind == alert:
                try self.receive_alert()
                return 0
            elif kind == handshake:
                try self.post_handshake()
            elif kind != application_data:
                self.failed = true
                error(invalid, "unexpected TLS record after the handshake")
        let count = buffer.length if buffer.length < self.pending() else self.pending()
        for i in 0..<count:
            buffer[i] = self.record[self.start + i]
        self.start += count
        return count

    ## Encrypt and send application data, first answering a peer KeyUpdate.
    pub func write_application(sink: io.Writer, data: const u8[]) -> !:
        if self.key_update_due:
            let message = b"\x18\x00\x00\x01\x00"
            try self.send(sink, handshake, message)
            try self.update_write_key()
            self.key_update_due = false
        try self.send(sink, application_data, data)

    ## Send a KeyUpdate asking the peer to update too (RFC 8446 §4.6.3), then
    ## switch this side's write key.
    pub func request_key_update(sink: io.Writer) -> !:
        let message = b"\x18\x00\x00\x01\x01"
        try self.send(sink, handshake, message)
        try self.update_write_key()

    ## Handle a received alert record: close_notify ends the stream; any other
    ## alert fails the channel with a diagnostic naming it.
    pub func receive_alert() -> !:
        let body = self.plaintext()
        if body.length != 2:
            self.failed = true
            error(invalid, "malformed TLS alert")
        self.start = self.end
        if body[1] == 0:
            self.peer_closed = true
            return
        self.failed = true
        error(invalid, alert_message(body[1]))

    ## Process whole post-handshake messages within one record.
    func post_handshake() -> !:
        let body = self.plaintext()
        var at: usize = 0
        while at < body.length:
            if body.length - at < 4:
                error(invalid, "fragmented post-handshake message is unsupported")
            let length = ((usize)body[at + 1] << 16) | ((usize)body[at + 2] << 8) | (usize)body[at + 3]
            if length > body.length - at - 4:
                error(invalid, "fragmented post-handshake message is unsupported")
            let kind = body[at]
            if kind == 24:
                if length != 1 or body[at + 4] > 1:
                    error(invalid, "malformed KeyUpdate")
                if body[at + 4] == 1:
                    self.key_update_due = true
                try self.update_read_key()
            elif kind != 4:
                error(invalid, "unexpected post-handshake message")
            at += 4 + length
        self.start = self.end

    func update_read_key() -> !:
        let parameters = try suite_for(self.suite)
        var next: u8[48]
        defer crypto.wipe(next)
        try tls.expand_label(self.read_secret[..<parameters.hash_size], b"traffic upd", b"", next[..<parameters.hash_size], parameters.hash)
        for i in 0..<parameters.hash_size:
            self.read_secret[i] = next[i]
        self.read = try Cipher.from_secret(parameters, next[..<parameters.hash_size])

    func update_write_key() -> !:
        let parameters = try suite_for(self.suite)
        var next: u8[48]
        defer crypto.wipe(next)
        try tls.expand_label(self.write_secret[..<parameters.hash_size], b"traffic upd", b"", next[..<parameters.hash_size], parameters.hash)
        for i in 0..<parameters.hash_size:
            self.write_secret[i] = next[i]
        self.write = try Cipher.from_secret(parameters, next[..<parameters.hash_size])

    ## Erase keys, secrets and buffered plaintext of this exact object.
    pub func wipe():
        crypto.wipe(u8[]((u8*)&self, memory.size_of(Channel)))