silk.tls.client.

When to use#

Most programs use silk.tls.connection, which drives this client over a ByteDuplex. Use Client directly when you need full control of the transport, for example in an event loop. Make it with Client.make, then move bytes between it and the transport until it reports Authenticated, and then read and write application data.

Details#

The client supports TLS 1.3 only, with the cipher suites ChaCha20-Poly1305, AES-128-GCM, and AES-256-GCM, and the key exchange groups X25519 and P-256. It checks the certificate chain against your TrustSnapshot, the host name of your ReferenceIdentity, the CertificateVerify signature, and the Finished message. It gives no application data before all checks pass.

Each call returns a Progress: how many bytes it took or wrote, and the next Demand. Output works in two steps: write Client.pendingOutput to the transport, and then call Client.ackWritten with the number of bytes written. The client does not keep your buffers. ClientLimits bound all memory and work.

Errors#

• TlsError for an alert from the server, a protocol error, a certificate that fails, a limit, or a call in the wrong state. An error is permanent for the client.

• OutOfMemoryError from Client.make if the Allocator fails.

Gotchas#

You provide the trust, the time, the random source, and the transport. The client supports one TLS 1.3 profile, not all of the Web PKI. Dropping the client does not send close_notify. Call Client.closeWrite first. Secrets are not erased.

Examples#

Make a client and send its ClientHello#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.tls.https_identity { HttpsIdentity, IdentityError, OriginHost, ReferenceIdentity }
import silk.collections.list { List }
import silk.system.random { Random }
import silk.core.result { Result }
import silk.system.system_clock { SystemClock }
import silk.tls.client { AlpnConfig, Client, ClientConfig, ClientLimits, Progress, TlsError }
import silk.tls.trust_anchor { TrustAnchor }
import silk.tls.trust_snapshot { SnapshotLimits, TrustSnapshot, TrustSourceError }
import silk.num.usize

// Not secure. Real programs use a `Random` provider from the operating system.
struct ExampleRandom {
  next: usize,
}

impl Random for ExampleRandom {
  effect fn fillBytes(self: &mut Self, output: &mut [u8]) -> () {
    let mut index: usize = 0
    while index < output.length {
      output[index] = usize.toU8((self.next + index) % 251 + 1)
      index = index + 1
    }
    self.next = self.next + output.length
    return ()
  }
}

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let mut random = ExampleRandom { next: 1 }
  let reference = match HttpsIdentity.reference(OriginHost<'static>.Dns { bytes: b"example.com" }) {
    Result<ReferenceIdentity, IdentityError>.Success { value } => value
    Result<ReferenceIdentity, IdentityError>.Failure { error: _ } => {
      return 1
    }
  }

  // An empty snapshot trusts no server. Real programs load CA certificates.
  let trust = match TrustSnapshot.fromAnchors(List<TrustAnchor>.make(), SnapshotLimits.defaults()) {
    Result<TrustSnapshot, TrustSourceError>.Success { value } => move value
    Result<TrustSnapshot, TrustSourceError>.Failure { error: _ } => {
      return 1
    }
  }
  let config = ClientConfig {
    reference: reference,
    alpn: AlpnConfig.defaults(),
    limits: ClientLimits.defaults()
  }
  let made = run Client.make(&config, move trust, SystemClock.make(1789156800, 0))
    |> Effect.provideMut<Random>(&mut random)
    |> Effect.provideMut<Allocator>(&mut allocator)
  let mut client = match move made {
    Result<Client, TlsError>.Success { value } => move value
    Result<Client, TlsError>.Failure { error: _ } => {
      return 1
    }
  }

  // The ClientHello is ready. Write it to the transport, then acknowledge the bytes written.
  let length = Client.pendingOutput(&client).length
  if length == 0 {
    return 1
  }
  return match Client.ackWritten(&mut client, length) {
    Result<Progress, TlsError>.Success { value: _ } => 0
    Result<Progress, TlsError>.Failure { error: _ } => 1
  }
}

Import as Client with import silk.tls.client { Client }.

Public declarations: 15.

NamedGroup#

pub enum NamedGroup

One key-exchange group selected for the authenticated connection.

X25519#

X25519

X25519 with a 32-byte encoded public key.

P256#

P256

The NIST P-256 curve with a 65-byte uncompressed encoded point.

AlpnProtocol#

pub struct AlpnProtocol<'a>

One borrowed opaque ALPN protocol offered in caller order.

Field bytes#

pub bytes: &'a [u8]

The nonempty protocol bytes, without a length prefix.

AlpnConfig#

pub union AlpnConfig<'a>

Borrowed ALPN policy copied by Client.make.

Disabled#

Disabled

Sends no ALPN extension and accepts no server selection.

Offered#

Offered

Sends one ordered, nonempty, duplicate-free protocol list.

Field protocols#

pub protocols: &'a [AlpnProtocol<'a>]

The protocols in preference order.

Field required#

pub required: bool

Whether absence of a server selection is a failure.

Implementation Copy for AlpnProtocol<'a>#

impl<'a> Copy for AlpnProtocol<'a>

Implementation Copy for AlpnConfig<'a>#

impl<'a> Copy for AlpnConfig<'a>

Implementation AlpnConfig<'a>#

impl<'a> AlpnConfig<'a>

Associated function defaults#

pub fn defaults() -> AlpnConfig<'a>

Returns the default policy, which sends no ALPN extension.

ClientLimits#

pub struct ClientLimits

Inclusive local resource policy for one client connection. The limits bound all memory and work of the client.

Field handshakeBodyBytes#

pub handshakeBodyBytes: usize

Maximum body bytes in one handshake message.

Field handshakeBytes#

pub handshakeBytes: usize

Maximum total initial-handshake bytes, including four-byte headers.

Field handshakeMessages#

pub handshakeMessages: usize

Maximum initial-handshake message count.

Field peerCertificates#

pub peerCertificates: usize

Maximum peer certificate count, including the leaf.

Field certificateBytes#

pub certificateBytes: usize

Maximum DER bytes in one peer certificate.

Field certificateTotalBytes#

pub certificateTotalBytes: usize

Maximum aggregate peer DER bytes.

Field cookieBytes#

pub cookieBytes: usize

Maximum echoed HelloRetryRequest cookie bytes.

Field extensionBytes#

pub extensionBytes: usize

Maximum bytes in one extension vector.

Field emptyRecords#

pub emptyRecords: usize

Maximum consecutive empty application or compatibility records.

Field postHandshakeControls#

pub postHandshakeControls: usize

Maximum consecutive post-handshake control messages without positive application content.

Field tickets#

pub tickets: usize

Maximum accepted NewSessionTicket messages.

Field ticketBytes#

pub ticketBytes: usize

Maximum total encoded NewSessionTicket bytes.

Field certificateDecode#

pub certificateDecode: DecodeLimits

Strict certificate decoder policy.

Field sanDecode#

pub sanDecode: SanDecodeLimits

Strict SAN adapter policy.

Field identity#

pub identity: IdentityLimits

HTTPS identity policy.

Field path#

pub path: ValidationLimits

Certificate-path policy.

Implementation Copy for ClientLimits#

impl Copy for ClientLimits

Implementation ClientLimits#

impl ClientLimits

Associated function defaults#

pub fn defaults() -> ClientLimits

Returns the finite TLS client defaults.

ClientConfig#

pub struct ClientConfig<'a>

Borrowed client configuration that construction copies into owned storage.

Field reference#

pub reference: ReferenceIdentity<'a>

A reference already admitted by HttpsIdentity.reference. Construction revalidates it.

Field alpn#

pub alpn: AlpnConfig<'a>

ALPN policy, with opaque protocols in caller preference order.

Field limits#

pub limits: ClientLimits

Finite connection limits and nested certificate policies.

Demand#

pub enum Demand

The next action or observable connection event of a Client, in Progress.demand.

NeedInput#

NeedInput

Supply peer transport bytes.

NeedOutput#

NeedOutput

Write and acknowledge the complete pending output suffix before other work.

PlaintextReady#

PlaintextReady

Read authenticated buffered application plaintext.

Authenticated#

Authenticated

Observe the one-shot authentication transition and its metadata.

PeerClosed#

PeerClosed

The peer receive direction closed cleanly.

Closed#

Closed

Both directions closed cleanly and no output remains.

Progress#

pub struct Progress

Exact progress from one Client operation: how many bytes it took or wrote, and the next Demand.

Field consumed#

pub consumed: usize

The accepted prefix of caller input or application plaintext.

Field written#

pub written: usize

The bytes copied into a caller plaintext destination.

Field demand#

pub demand: Demand

The next action or event under the fixed precedence rule.

ClientOperation#

pub enum ClientOperation

A public operation rejected because of caller state.

FeedInput#

FeedInput

Transport input feed.

Progress#

Progress

State-machine progress without new bytes.

AckWritten#

AckWritten

Pending-output acknowledgment.

ReadPlaintext#

ReadPlaintext

Application plaintext read.

WritePlaintext#

WritePlaintext

Application plaintext write.

RequestKeyUpdate#

RequestKeyUpdate

Local traffic-key update request.

CloseWrite#

CloseWrite

Local write-direction close.

EndInput#

EndInput

Transport input end.

Implementation Debug for ClientOperation#

impl Debug for ClientOperation

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as FeedInput.

ProtocolReason#

pub enum ProtocolReason

A protocol grammar or state-machine rule rejected from the peer.

Record#

Record

A record has an invalid content type, version, length, padding, or inner framing.

UnexpectedMessage#

UnexpectedMessage

A handshake message arrived in an invalid order.

InvalidLength#

InvalidLength

A handshake message or vector is truncated or has trailing bytes.

Extension#

Extension

An extension is duplicated, unsolicited, misplaced, or malformed.

ServerHello#

ServerHello

ServerHello does not select the admitted TLS 1.3 profile.

HelloRetryRequest#

HelloRetryRequest

HelloRetryRequest violates its single-retry and changed-ClientHello rules.

CompatibilityCcs#

CompatibilityCcs

Compatibility CCS is outside its window or not exactly {1}.

CertificateRequest#

CertificateRequest

A CertificateRequest has invalid framing, duplication, or a profile-forbidden extension.

Certificate#

Certificate

A peer Certificate message violates its TLS envelope.

PostHandshake#

PostHandshake

A NewSessionTicket or KeyUpdate message violates its TLS envelope.

InternalState#

InternalState

The client reached an impossible private transition.

Implementation Debug for ProtocolReason#

impl Debug for ProtocolReason

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as Record.

TlsLimitKind#

pub enum TlsLimitKind

A named finite resource exhausted by peer input or configuration.

HandshakeBodyBytes#

HandshakeBodyBytes

One handshake body.

HandshakeBytes#

HandshakeBytes

Aggregate initial-handshake headers and bodies.

HandshakeMessages#

HandshakeMessages

Initial-handshake message count.

PeerCertificates#

PeerCertificates

Peer certificate count.

CertificateBytes#

CertificateBytes

DER bytes in one peer certificate.

CertificateTotalBytes#

CertificateTotalBytes

Aggregate peer certificate DER bytes.

CookieBytes#

CookieBytes

HelloRetryRequest cookie bytes.

ExtensionBytes#

ExtensionBytes

One extension vector.

EmptyRecords#

EmptyRecords

Consecutive empty application or compatibility records.

PostHandshakeControls#

PostHandshakeControls

Consecutive post-handshake control messages.

Tickets#

Tickets

NewSessionTicket count.

TicketBytes#

TicketBytes

Aggregate encoded NewSessionTicket bytes.

Arithmetic#

Arithmetic

Checked size arithmetic.

Alpn#

Alpn

One ALPN protocol or list.

CertificateDecode#

CertificateDecode

The configured certificate-decoder policy.

CertificateSanDecode#

CertificateSanDecode

The configured certificate-SAN decoder policy.

CertificateIdentity#

CertificateIdentity

The configured HTTPS identity policy.

CertificatePath#

CertificatePath

The configured certificate-path search policy.

CertificateProfile#

CertificateProfile

The configured semantic certificate-profile policy.

Implementation Debug for TlsLimitKind#

impl Debug for TlsLimitKind

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as HandshakeBodyBytes.

CertificateIdentityFailure#

pub union CertificateIdentityFailure

A certificate identity failure that preserves its originating actor.

Decode#

Decode

The certificate SAN adapter rejected structure or a resource bound.

Field error#

pub error: SanDecodeError

The complete SAN adapter failure.

Match#

Match

The HTTPS reference matcher rejected the complete decoded identity set.

Field error#

pub error: IdentityError

The complete HTTPS identity failure.

Implementation Debug for CertificateIdentityFailure#

impl Debug for CertificateIdentityFailure

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant and its fields, such as Decode { ... }.

CertificateVerifyFailure#

pub union CertificateVerifyFailure

A server CertificateVerify failure with its selected signature implementation.

Ecdsa#

Ecdsa

ECDSA-P256/SHA-256 verification failed.

Field error#

pub error: P256SignatureError

The exact primitive failure.

EcdsaP384#

EcdsaP384

ECDSA-P384/SHA-384 verification failed.

Field error#

pub error: P384SignatureError

The exact primitive failure.

Rsa#

Rsa

RSA-PSS-RSAE/SHA-256 verification failed.

Field error#

pub error: RsaError

The exact primitive failure.

Implementation Debug for CertificateVerifyFailure#

impl Debug for CertificateVerifyFailure

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant and its fields, such as Ecdsa { ... }.

TlsError#

pub union TlsError

A typed TLS client failure: an alert from the server, a protocol error, a certificate that fails, a limit, or a call in the wrong state. An error is permanent for the client.

PeerAlert#

PeerAlert

The peer sent a fatal alert with this wire description.

Field code#

pub code: u8

The alert description byte.

BadRecordMac#

BadRecordMac

Protected record authentication failed.

ProtocolViolation#

ProtocolViolation

Peer syntax, ordering, or negotiation violated the selected TLS profile.

Field reason#

pub reason: ProtocolReason

The rejected rule.

CertificateDecode#

CertificateDecode

A peer certificate did not decode.

Field error#

pub error: DecodeError

The complete strict decoder failure.

CertificatePath#

CertificatePath

Certificate-path construction or validation failed.

Field error#

pub error: ValidationError

The complete bounded path failure.

CertificateIdentity#

CertificateIdentity

SAN decoding or HTTPS reference matching failed.

Field error#

pub error: CertificateIdentityFailure

The exact nested identity failure.

CertificateVerify#

CertificateVerify

Server CertificateVerify did not authenticate the transcript with the selected leaf key.

Field error#

pub error: CertificateVerifyFailure

The exact selected primitive failure.

Finished#

Finished

Server Finished did not authenticate the transcript.

UnsupportedProfile#

UnsupportedProfile

A server-selected suite, group, signature, or extension shape is outside the selected profile.

LimitExceeded#

LimitExceeded

A finite resource budget was exceeded.

Field kind#

pub kind: TlsLimitKind

The exhausted resource category.

Field limit#

pub limit: usize

The inclusive configured limit.

InvalidState#

InvalidState

A caller operation is invalid in the current state.

Field operation#

pub operation: ClientOperation

The rejected operation.

EmptyBuffer#

EmptyBuffer

A caller supplied an empty plaintext output buffer.

HandshakeTruncated#

HandshakeTruncated

Transport input ended before authentication and peer closure.

Truncated#

Truncated

Transport input ended after authentication without peer close_notify.

NoApplicationProtocol#

NoApplicationProtocol

The server omits a required ALPN selection or selects a protocol that was not offered.

Implementation Debug for TlsError#

impl Debug for TlsError

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant and its fields, such as PeerAlert { ... }.

Implementation Copy for CertificateVerifyFailure#

impl Copy for CertificateVerifyFailure

Authentication#

pub struct Authentication<'a>

Authenticated result metadata borrowed from one client owner.

Implementation Authentication<'a>#

impl<'a> Authentication<'a>

Method suite#

pub fn suite(self: &Self) -> CipherSuite

Returns the negotiated TLS 1.3 cipher suite.

Method group#

pub fn group(self: &Self) -> NamedGroup

Returns the negotiated ephemeral key-exchange group.

Method selectedAlpn#

pub fn selectedAlpn(self: &Self) -> Option<&'a [u8]>

Returns the selected offered ALPN protocol, or None when ALPN was disabled or optional.

Method leafDer#

pub fn leafDer(self: &Self) -> &'a [u8]

Borrows the exact DER of the leaf used for path, identity, and signature authentication.

Method intermediateIndices#

pub fn intermediateIndices(self: &Self) -> &'a [usize]

Borrows selected intermediate indices in leaf-to-anchor order.

Method anchorIndex#

pub fn anchorIndex(self: &Self) -> usize

Returns the selected explicit trust-anchor index.

Method validationTime#

pub fn validationTime(self: &Self) -> Instant

Returns the exact caller-supplied validation instant, including nanoseconds.

Method revocationStatus#

pub fn revocationStatus(self: &Self) -> RevocationStatus

Returns the revocation evidence produced by certificate-path validation.

Method sanIndex#

pub fn sanIndex(self: &Self) -> usize

Returns the matching SAN's original certificate index.

Client#

pub struct Client

A TLS 1.3 client state machine that does no I/O.

When to use#

Most programs use silk.tls.connection, which drives this client over a ByteDuplex. Use it directly when you need full control of the transport, for example in an event loop. Make it with Client.make, then move bytes between it and the transport until it reports Authenticated, and then read and write application data.

Details#

Each operation returns a Progress with a Demand that tells you what to do next. Output works in two steps: write Client.pendingOutput to the transport, and then call Client.ackWritten with the number of bytes written. The client does not keep your buffers. ClientLimits bound all memory and work.

It supports TLS 1.3 only, with the cipher suites ChaCha20-Poly1305, AES-128-GCM, and AES-256-GCM, the key exchange groups X25519 and P-256, and server keys ECDSA P-256, ECDSA P-384, and RSA (PSS with SHA-256). It checks the certificate chain against your TrustSnapshot, the host name of your ReferenceIdentity, the CertificateVerify signature, and the Finished message. It gives no application data before all checks pass.

Gotchas#

A TlsError is permanent for the client. Dropping the client does not send close_notify. Call Client.closeWrite first. Secrets are not erased.

Implementation Client#

impl Client

Associated function make#

pub effect fn make<'a>(
    config: &ClientConfig<'a>,
    trust: TrustSnapshot,
    validationTime: Instant,
  ) -> Result<Client, TlsError>
  ! OutOfMemoryError
  ? &mut Allocator | &mut Random

Returns a new client for config and trust, with the ClientHello already queued as pending output.

validationTime is the time used to check certificate dates. The client copies config and consumes trust. A DNS name is sent as SNI in lowercase. An IP address sends no SNI.

Errors#

• Failure with a TlsError if config is not valid.

• OutOfMemoryError if the Allocator fails.

Gotchas#

Give a correct current time and a secure Random provider. If Random fails, the program stops.

Method pendingOutput#

pub fn pendingOutput<'a>(self: &'a Self) -> &'a [u8]

Returns the TLS output to send to the server. After you send some of it, call Client.ackWritten.

Method authentication#

pub fn authentication<'a>(self: &'a Self) -> Option<Authentication<'a>>

Returns the result of authentication, after the Authenticated action. Before that, returns None.

Method feedInput#

pub effect fn feedInput(
    self: &mut Self,
    input: &[u8],
  ) -> Result<Progress, TlsError>
  ! OutOfMemoryError
  ? &mut Allocator | &mut Random

Gives bytes from the server to the client. consumed in the result tells how many it accepted.

Details#

The client does not keep input. Give the bytes that it did not accept again in the next call. The client processes all complete handshake messages before it asks for more input. After the server sends close_notify, the client accepts and ignores all later bytes.

Method progress#

pub effect fn progress(self: &mut Self) -> Result<Progress, TlsError>
  ! OutOfMemoryError
  ? &mut Allocator | &mut Random

Processes buffered handshake messages without new input, and returns the next action.

Method ackWritten#

pub fn ackWritten(self: &mut Self, count: usize) -> Result<Progress, TlsError>

Tells the client that the transport sent the first count bytes of Client.pendingOutput.

Method readPlaintext#

pub fn readPlaintext(
    self: &mut Self,
    output: &mut [u8],
  ) -> Result<Progress, TlsError>

Copies decrypted application data into output. produced in the result tells how many bytes.

Gotchas#

An empty output returns the EmptyBuffer error. It never means the end of input.

Method writePlaintext#

pub fn writePlaintext(self: &mut Self, input: &[u8]) -> Result<Progress, TlsError>

Encrypts a prefix of input, at most 16384 bytes. consumed in the result tells how many bytes.

Details#

When TLS output is waiting, the client accepts no bytes. Send that output first. Do not give accepted bytes again, even if the transport sent only part of the record.

Method requestKeyUpdate#

pub fn requestKeyUpdate(self: &mut Self) -> Result<Progress, TlsError>

Asks for a new local traffic key before the next application write. More calls before that write do nothing.

Method closeWrite#

pub fn closeWrite(self: &mut Self) -> Result<Progress, TlsError>

Queues close_notify after the accepted output. More calls do nothing.

Method endInput#

pub fn endInput(self: &mut Self) -> Result<Progress, TlsError>

Tells the client that the transport has no more input. Pending output stays pending.

Category: TLS and certificates.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.