Fields
read_seq: u64,
write_seq: u64,
partial_cleartext_idx: u15,
The starting index of cleartext bytes inside partially_read_buffer
.
partial_ciphertext_idx: u15,
The ending index of cleartext bytes inside partially_read_buffer
as well as the starting index of ciphertext bytes.
partial_ciphertext_end: u15,
The ending index of ciphertext bytes inside partially_read_buffer
.
received_close_notify: bool,
When this is true, the stream may still not be at the end because there may be data in partially_read_buffer
.
allow_truncation_attacks: bool = false,
By default, reaching the end-of-stream when reading from the server will cause error.TlsConnectionTruncated
to be returned, unless a close_notify message has been received. By setting this flag to true
, instead, the end-of-stream will be forwarded to the application layer above TLS. This makes the application vulnerable to truncation attacks unless the application layer itself verifies that the amount of data received equals the amount of data expected, such as HTTP with the Content-Length header.
application_cipher: tls.ApplicationCipher,
partially_read_buffer: [tls.max_ciphertext_record_len]u8,
The size is enough to contain exactly one TLSCiphertext record. This buffer is segmented into four parts: 0. unused
- cleartext
- ciphertext
- unused The fields
partial_cleartext_idx
,partial_ciphertext_idx
, andpartial_ciphertext_end
describe the span of the segments.
Functions
fn init(stream: anytype, ca_bundle: Certificate.Bundle, host: []const u8) InitError(@TypeOf(stream))!Client
Initiates a TLS handshake and establishes a TLSv1.3 session with
stream
, which…Initiates a TLS handshake and establishes a TLSv1.3 session with
stream
, which must conform toStreamInterface
.host
is only borrowed during this function call.fn read(c: *Client, stream: anytype, buffer: []u8) !usize
Receives TLS-encrypted data from
stream
, which must conform to `StreamInterfac…Receives TLS-encrypted data from
stream
, which must conform toStreamInterface
.fn readAll(c: *Client, stream: anytype, buffer: []u8) !usize
Receives TLS-encrypted data from
stream
, which must conform to `StreamInterfac…Receives TLS-encrypted data from
stream
, which must conform toStreamInterface
. Returns the number of bytes read. If the number read is smaller thanbuffer.len
, it means the stream reached the end. Reaching the end of the stream is not an error condition.fn readAtLeast(c: *Client, stream: anytype, buffer: []u8, len: usize) !usize
Receives TLS-encrypted data from
stream
, which must conform to `StreamInterfac…Receives TLS-encrypted data from
stream
, which must conform toStreamInterface
. Returns the number of bytes read, calling the underlying read function the minimal number of times until the buffer has at leastlen
bytes filled. If the number read is less thanlen
it means the stream reached the end. Reaching the end of the stream is not an error condition.fn readv(c: *Client, stream: anytype, iovecs: []std.os.iovec) !usize
Receives TLS-encrypted data from
stream
, which must conform to `StreamInterfac…Receives TLS-encrypted data from
stream
, which must conform toStreamInterface
. Returns the number of bytes read. If the number read is less than the space provided it means the stream reached the end. Reaching the end of the stream is not an error condition. Theiovecs
parameter is mutable because this function needs to mutate the fields in order to handle partial reads from the underlying stream layer.fn readvAdvanced(c: *Client, stream: anytype, iovecs: []const std.os.iovec) !usize
Receives TLS-encrypted data from
stream
, which must conform to `StreamInterfac…Receives TLS-encrypted data from
stream
, which must conform toStreamInterface
. Returns number of bytes that have been read, populated insideiovecs
. A return value of zero bytes does not mean end of stream. Instead, check theeof()
for the end of stream. Theeof()
may be true after any call toread
, including when greater than zero bytes are returned, and this function asserts thateof()
isfalse
. Seereadv
for a higher level function that has the same, familiar API as other read functions, such asstd.fs.File.read
.fn readvAtLeast(c: *Client, stream: anytype, iovecs: []std.os.iovec, len: usize) !usize
Receives TLS-encrypted data from
stream
, which must conform to `StreamInterfac…Receives TLS-encrypted data from
stream
, which must conform toStreamInterface
. Returns the number of bytes read, calling the underlying read function the minimal number of times until the iovecs have at leastlen
bytes filled. If the number read is less thanlen
it means the stream reached the end. Reaching the end of the stream is not an error condition. Theiovecs
parameter is mutable because this function needs to mutate the fields in order to handle partial reads from the underlying stream layer.fn write(c: *Client, stream: anytype, bytes: []const u8) !usize
Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
. …Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
. Returns the number of plaintext bytes sent, which may be fewer thanbytes.len
.fn writeAll(c: *Client, stream: anytype, bytes: []const u8) !void
Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
.fn writeAllEnd(c: *Client, stream: anytype, bytes: []const u8, end: bool) !void
Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
. …Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
. Ifend
is true, then this function additionally sends aclose_notify
alert, which is necessary for the server to distinguish between a properly finished TLS session, or a truncation attack.fn writeEnd(c: *Client, stream: anytype, bytes: []const u8, end: bool) !usize
Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
. …Sends TLS-encrypted data to
stream
, which must conform toStreamInterface
. Returns the number of plaintext bytes sent, which may be fewer thanbytes.len
. Ifend
is true, then this function additionally sends aclose_notify
alert, which is necessary for the server to distinguish between a properly finished TLS session, or a truncation attack.