dymokomi/luce-tls
Source of release 0.7.0
## Stream: one owned TCP connection that is either plain or TLS and implements
## io.Reader and io.Writer, so protocol code (IMAP, SMTP) needs no transport
## glue. It upgrades in place for STARTTLS. The socket is kept nonblocking and
## every transfer waits through readiness like `net.DeadlineStream`, under the
## stream's deadline and cancellation signal, so another thread can cancel a
## blocked read (an IMAP IDLE) and a timed-out TLS read resumes intact.
##
## In nonblocking mode (`set_nonblocking`) nothing waits, for an event loop that
## watches the descriptor: a transfer that cannot progress fails with
## io.would_block, the TLS handshake advances step by step (`begin_tls`,
## `continue_tls`), and records the socket cannot take yet wait in the stream's
## outgoing queue until `flush` sends them.
import io
from luce_std import net
import c
import sync
import memory
import platform
import record
import client
import server
import trust
pub let invalid = record.invalid
## Re-exported trust policy; see `trust.Trust`.
pub type Trust = trust.Trust
## One plain or TLS client connection. Zero is closed. Copying does not
## duplicate ownership; close exactly one copy and synchronize calls on it.
pub struct Stream: io.Reader, io.Writer:
var connection: net.Connection
var channel: record.Channel
var secure: bool
var prepared: bool
var deadline: net.Deadline
var cancellation: sync.Cancellation*?
## Nonblocking mode: no transfer waits.
var nonblocking: bool
## TLS records written but not yet sent (nonblocking mode).
var outbox: Outbox
## The client handshake `begin_tls` started, until it completes (nonblocking
## mode): one element in the C heap, empty otherwise.
var handshake: client.Handshake[]
## Resolve `host`, try each address in resolver order, and, when `tls` is
## set, handshake under `policy` (default: the public roots). `alpn`, when
## not empty, is the one application protocol offered. `deadline` and
## `cancellation` bound the whole connect and stay set for later transfers.
pub static func connect(host: str, port: u16, tls: bool, deadline: net.Deadline = net.Deadline(),
cancellation: sync.Cancellation*? = none, policy: Trust = Trust(), alpn: str = "") -> Stream!:
var host_c: u8[256]
if host.length == 0 or host.length + 1 > host_c.length:
error(invalid, "host name must be 1 to 255 bytes")
for i in 0..<host.length:
host_c[i] = host.bytes[i]
host_c[host.length] = 0
var addresses = try net.resolve_all((c.str)(str)host_c[..<host.length], port)
defer addresses.destroy()
let candidates = addresses.view()
var stream = Stream(deadline = deadline, cancellation = cancellation)
for i in 0..<candidates.length:
let last = i + 1 == candidates.length
let connection = net.Connection.connect(candidates[i], deadline, cancellation, nonblocking = true) catch failure:
if last or failure.code == net.timed_out or failure.code == net.cancelled:
error(failure.code, failure.message)
continue
stream.connection = connection
stream.prepared = true
break
errdefer stream.destroy()
if tls:
try stream.start_tls(host, policy, alpn)
return stream
## Adopt a connected socket as a plain stream. It is made nonblocking on
## first use. The stream owns and closes it.
pub static func plain(connection: net.Connection) -> Stream:
return Stream(connection = connection)
## STARTTLS: run the TLS client handshake on this plain connection under
## the stream's deadline. Discard any plaintext buffered after the server's
## STARTTLS reply first (RFC 3207 §4.2, RFC 2595 §3.1). After a failure the
## stream is unusable and should be closed.
pub func start_tls(host: str, policy: Trust = Trust(), alpn: str = "") -> !:
if self.secure:
error(invalid, "the stream already uses TLS")
var link = try self.link()
try client.connect(&self.channel, &link, &link, host, &policy, alpn)
self.secure = true
## The negotiated TLS cipher suite (0x1301 AES-128-GCM, 0x1302 AES-256-GCM,
## 0x1303 ChaCha20-Poly1305), or zero when plain.
pub func cipher_suite() -> u16:
return self.channel.cipher_suite()
## Whether a TLS session protects the stream.
pub func is_secure() -> bool:
return self.secure
## Apply an absolute `deadline` and optional `cancellation` to subsequent
## reads, writes and close. `net.Deadline()` removes the time limit.
pub func set_deadline(deadline: net.Deadline, cancellation: sync.Cancellation*? = none):
self.deadline = deadline
self.cancellation = cancellation
## Decrypted bytes already buffered: `read` returns them without touching
## the socket, and a socket readiness poll cannot see them. Zero when plain.
pub func pending() -> usize:
return self.channel.pending()
## Whether the TLS peer has sent close_notify; `read` then returns zero.
pub func closed_by_peer() -> bool:
return self.channel.closed_by_peer()
## Read some bytes under the stream's deadline. Zero on a nonempty buffer
## is the end of the stream (TCP EOF, or close_notify when secure). A
## timeout (`net.timed_out`) or cancellation (`net.cancelled`) leaves the
## stream usable.
pub func read(buffer: u8[]) -> usize!:
return try self.read_within(buffer, self.deadline, self.cancellation)
## `read` with an explicit absolute deadline and cancellation for this call.
pub func read_within(buffer: u8[], deadline: net.Deadline, cancellation: sync.Cancellation*? = none) -> usize!:
if buffer.length == 0:
return 0
if self.nonblocking:
if self.handshake.length > 0:
error(invalid, "the TLS handshake is not complete")
if self.secure:
return try self.channel.read_application(&self.connection, buffer)
return try self.connection.read(buffer)
var link = try self.link_with(deadline, cancellation)
if self.secure:
return try self.channel.read_application(&link, buffer)
return try link.read(buffer)
## Send all of `data` under the stream's deadline and return its length.
## When secure, a failure part way leaves the TLS session unusable. In
## nonblocking mode, accept what can go now and return its count: a plain
## stream sends what the socket takes; a TLS stream seals up to one record,
## which waits in the outgoing queue if the socket cannot take it all. With
## records still queued nothing is accepted (io.would_block): `flush` first.
pub func write(data: const u8[]) -> usize!:
if self.nonblocking and data.length > 0:
if self.handshake.length > 0:
error(invalid, "the TLS handshake is not complete")
if not try self.flush():
error(io.would_block, "the stream's queued records wait for the socket")
if not self.secure:
return try self.connection.write(data)
let count = data.length if data.length < record.max_fragment else record.max_fragment
try self.channel.write_application(&self.outbox, data[..<count])
_ = try self.flush()
return count
try self.write_within(data, self.deadline, self.cancellation)
return data.length
## Send all of `data` with an explicit absolute deadline and cancellation.
pub func write_within(data: const u8[], deadline: net.Deadline, cancellation: sync.Cancellation*? = none) -> !:
if data.length == 0:
return
var link = try self.link_with(deadline, cancellation)
if self.secure:
try self.channel.write_application(&link, data)
else:
try io.write_all(&link, data)
## Wait for readiness. Read interest is satisfied at once by pending
## plaintext; otherwise this waits on the socket. Readiness is advisory: a
## readable TLS socket may hold only part of a record, or a record carrying
## no application data, so pair `read` with a deadline when a stall matters.
pub func wait(interest: net.WaitInterest = net.WaitInterest.read, deadline: net.Deadline = net.Deadline(),
cancellation: sync.Cancellation*? = none) -> net.Readiness!:
if interest != net.WaitInterest.write and self.pending() > 0:
return net.Readiness(readable = true, writable = interest == net.WaitInterest.both)
return try self.connection.wait(interest, deadline, cancellation)
## Borrow the socket descriptor, for a `net.Poller`. Check `pending()`
## before polling, and never read or write the descriptor directly.
pub func descriptor() -> platform.SocketDescriptor?:
return self.connection.descriptor()
## The connected peer's address.
pub func peer_address() -> net.SocketAddress!:
return try self.connection.peer_address()
## Send close_notify when secure (best effort, under the stream's
## deadline), close the socket and erase the session keys. Safe to repeat.
pub func close() -> !:
if self.connection.descriptor() == none:
return
if self.secure and self.channel.established():
_ = self.send_close_notify() catch: recover ()
self.release()
try self.connection.close()
## Close without close_notify, ignoring errors; for unwinding.
pub func destroy():
self.release()
self.connection.destroy()
## Erase the session and release the handshake and the outgoing queue.
func release():
self.end_handshake()
self.outbox.release()
self.channel.wipe()
self.secure = false
func send_close_notify() -> !:
if self.nonblocking:
# Best effort without waiting: what the socket takes now.
try self.channel.send_alert(&self.outbox, 1, 0)
_ = try self.flush()
return
var link = try self.link()
try self.channel.send_alert(&link, 1, 0)
# mark: Nonblocking mode ====================================================
## Switch nonblocking mode on or off. In nonblocking mode no transfer waits:
## one that cannot progress fails with io.would_block and is retried after
## the descriptor's readiness. Records queue in the stream (`queued`) until
## `flush` sends them. Turn it off only with nothing queued.
pub func set_nonblocking(enabled: bool) -> !:
if not enabled and self.outbox.count() > 0:
error(invalid, "records wait in the stream's outgoing queue")
if enabled and not self.prepared:
try self.connection.set_nonblocking(true)
self.prepared = true
self.nonblocking = enabled
## Whether the stream is in nonblocking mode.
pub func is_nonblocking() -> bool:
return self.nonblocking
## Bytes of records written but not yet sent: wait for write readiness and
## `flush` while this is not zero.
pub func queued() -> usize:
return self.outbox.count()
## Send queued records as far as the socket takes them; whether the queue
## is now empty.
pub func flush() -> bool!:
while self.outbox.count() > 0:
let sent = self.connection.write(self.outbox.view()) catch failure:
if failure.code == io.would_block:
return false
error(failure.code, failure.message)
self.outbox.consume(sent)
return true
## Start the TLS client handshake for `host` without waiting (nonblocking
## mode): the ClientHello is queued and sent as far as the socket takes it.
## Then call `continue_tls` whenever the descriptor is readable (or writable
## while records are queued) until it answers true.
pub func begin_tls(host: str, policy: Trust = Trust(), alpn: str = "") -> !:
if not self.nonblocking:
error(invalid, "begin_tls needs a nonblocking stream; use start_tls")
if self.secure or self.handshake.length > 0:
error(invalid, "the stream already uses TLS")
let storage = try new client.Handshake[1] --- in memory.heap
storage[0] = client.Handshake.start(&self.channel, &self.outbox, host, &policy, alpn) catch failure:
free(storage) in memory.heap
error(failure.code, failure.message)
self.handshake = storage
_ = try self.flush()
## Advance the handshake `begin_tls` started with what has arrived; true
## once it is complete and the stream is secure (its last flight may still
## be queued). False when it waits for the peer. A failure ends it: the
## stream is then unusable and should be closed.
pub func continue_tls() -> bool!:
if self.handshake.length == 0:
return self.secure
_ = try self.flush()
let done = self.handshake[0].step(&self.channel, &self.connection, &self.outbox) catch failure:
if failure.code == io.would_block:
_ = try self.flush()
return false
error(failure.code, failure.message)
self.end_handshake()
self.secure = done
_ = try self.flush()
return true
## Erase and release the handshake `begin_tls` started, if any.
func end_handshake():
if self.handshake.length == 0:
return
self.handshake[0].close()
free(self.handshake) in memory.heap
var empty: client.Handshake[]
self.handshake = empty
## Answer a TLS client on this plain stream as a small private-endpoint
## server, under the stream's deadline: one P-256 certificate (`der`) and
## its private key `d`, for loopback tests and private endpoints.
pub func accept_tls(der: const u8[], d: const u8[]) -> !:
if self.secure:
error(invalid, "the stream already uses TLS")
var link = try self.link()
try server.accept(&self.channel, &link, &link, der, d)
self.secure = true
func link() -> net.DeadlineStream!:
return try self.link_with(self.deadline, self.cancellation)
## A deadline view of the socket, switching it to nonblocking on first use.
func link_with(deadline: net.Deadline, cancellation: sync.Cancellation*?) -> net.DeadlineStream!:
if not self.prepared:
try self.connection.set_nonblocking(true)
self.prepared = true
return try net.DeadlineStream.over(&self.connection, deadline, cancellation)
## A stream's outgoing queue: whole records the socket has not taken yet, in the
## C heap. Writing appends; the stream sends from the front.
struct Outbox: io.Writer:
var data: u8[]
var start: usize
var end: usize
## Append all of `bytes`.
func write(bytes: const u8[]) -> usize!:
if bytes.length == 0:
return 0
if self.start == self.end:
self.start = 0
self.end = 0
if self.data.length - self.end < bytes.length:
let live = self.end - self.start
var capacity = self.data.length if self.data.length > 0 else 4096
while capacity < live + bytes.length:
capacity *= 2
let grown = try new u8[capacity] --- in memory.heap
memory.copy(grown, self.data[self.start..<self.end], live)
if self.data.length > 0:
free(self.data) in memory.heap
self.data = grown
self.start = 0
self.end = live
memory.copy(self.data[self.end..], bytes, bytes.length)
self.end += bytes.length
return bytes.length
## The bytes waiting.
func view() -> const u8[]:
return self.data[self.start..<self.end]
## How many bytes wait.
func count() -> usize:
return self.end - self.start
## Drop `count` bytes from the front.
func consume(count: usize):
self.start += count
## Release the storage.
func release():
if self.data.length > 0:
free(self.data) in memory.heap
var empty: u8[]
self.data = empty
self.start = 0
self.end = 0