tls

nimony/lib/std/tls.nim

A TLS 1.3 client (RFC 8446) as a streamio.TlsEngine: a state machine that takes records in and gives records out and does no I/O of its own. The stream core moves the bytes (connect(address, tls = newTlsEngine())).

What it speaks, deliberately few:

TLS 1.3 only. Every server worth trusting has spoken it for years, and

1.2's surface is most of what has gone wrong with TLS.

Key exchange X25519; cipher suite TLS_CHACHA20_POLY1305_SHA256.
Server authentication by std/crypto/x509 against a TrustStore:

ECDSA P-256/P-384 and RSA-PSS CertificateVerify, a chain to a root, the host name. There is no "insecure" switch; a caller who must talk to a self-signed server puts that certificate into the store.

No session resumption, no 0-RTT, no client certificates (a request for one is answered with an empty certificate, which the server may refuse).

.. code-block:: nim let e = newTlsEngine() let (r, w) = connect("example.com:443", "GET / HTTP/1.1\r\n...", tls = e) # on a failure, e.failure / e.certError / e.alert say what went wrong

type TlsFailure = enum
  tfNone = (0, "no failure")
  tfRandom = (1, "the system random number generator could not be read")
  tfProtocol = (2, "the peer violated the TLS protocol")
  tfAlert = (3, "the peer sent a fatal alert")
  tfUnsupported = (4, "the server chose parameters this client does not speak")
  tfCertificate = (5, "the server\27s certificate is not trusted")
  tfSignature = (6, "the server\27s handshake signature does not verify")
  tfFinished = (7, "the handshake transcript does not match")
  tfDecrypt = (8, "a record failed authentication")
  tfState = (9, "the engine was used out of order")

func dollar`.TlsFailure(e: TlsFailure): string
func dollar`.HsState(e: HsState): string
type NimonyTlsEngine = ref NimonyTlsEngine.Obj not nil

type NimonyTlsEngine.Obj = object
  failure: TlsFailure
  certError: CertError
  alert: int64
  alpn: string
  store: TrustStore
  host: string
  state: HsState
  secretKey: array[0..31, uint8]
  transcript: Sha256
  hsSecret: seq[uint8]
  cHs: seq[uint8]
  sHs: seq[uint8]
  certRequested: bool
  leaf: Certificate
  rd: Direction
  wr: Direction
  encrypted: bool
  inBuf: seq[uint8]
  hs: seq[uint8]
  outBuf: string
  app: string
  peerClosed: bool
  closeSent: bool

proc newTlsEngine(store: sink TrustStore): ref NimonyTlsEngine.Obj not nil
An engine that trusts store's roots.
proc newTlsEngine(): ref NimonyTlsEngine.Obj not nil
The default engine, verifying against the system's root certificates.
method start(e: ref NimonyTlsEngine.Obj not nil; host: string)
method recordsIn(e: ref NimonyTlsEngine.Obj not nil; src: openArray[char]; used: var int64)
method recordsOut(e: ref NimonyTlsEngine.Obj not nil; dest: var string)
method appIn(e: ref NimonyTlsEngine.Obj not nil; src: openArray[char]; used: var int64)
Sealed as application records of at most 16 KiB each.
method appOut(e: ref NimonyTlsEngine.Obj not nil; dest: var string)
method close(e: ref NimonyTlsEngine.Obj not nil)
method isConnected(e: ref NimonyTlsEngine.Obj not nil): bool
method isPeerClosed(e: ref NimonyTlsEngine.Obj not nil): bool