Skip to content
FutureBlitz

    Install

    Import std.net.tls

    std.net.tls

    std.net.tls: TLS 1.2 and 1.3 over any stream that's a Reader and a Writer, as a TcpStream is, through mbedTLS. TlsClient connects as a client, checking that the server's certificate is for the host it connects to and that a root it trusts signed it: the OS's, or roots of its own. TlsServer accepts as a server, with its certificate chain and key, and can ask each client for a certificate too. Either gives a TlsStream, a Reader and a Writer of what goes through TLS, with Async twins, which says the version of TLS, the application protocol ALPN agreed on, and the other side's certificate: client.Connect(Try TcpStream.Connect(host, 443), host). TlsListener takes TCP connections and accepts each as a TlsServer.

    A handshake that fails throws a NetError: of TLS, which says why, like "the server's certificate has expired", or of CLOSED when the stream ends first. One the stream under it fails throws what that stream's failure was for: a TcpStream's NetError or TimeoutError, or for a stream that isn't a socket, a NetError of OTHER. After the handshake, TLS that fails throws an IOError, whose Cause is a NetError of TLS, or an IOError of UNEXPECTED_END for a stream that ends without the close_notify a TLS connection ends with, since what came may be cut short; the stream's own failure is thrown as that stream threw it.

    std/net/tls.fb

    Types

    TlsClient class 

    Public Class TlsClient

    A client of TLS, which connects over a stream to a server whose certificate is for the host it connects to, which a root it trusts signed: the OS's, as it starts, or its own. It can offer application protocols, and give a certificate of its own to a server that asks for one.

    std/net/tls.fb, line 208

    • Public New() constructor #

      A new TlsClient, which trusts the OS's roots.

    • Public Method TrustOnly(roots: Certificate[]) method #

      Trusts only roots from then on, instead of the OS's roots, as for a server whose certificate a CA of a company's own signed.

    • Public Method TrustOsRoots() method #

      Trusts the OS's roots again, from then on.

    • @PanicsAtCaller Public Method Offer(protocols: String[]) method #

      Offers the application protocols, like "h2" and "http/1.1", most wanted first, of which the server picks one, which the TlsStream's Protocol says. Panics for a name that isn't 1 to 255 bytes, or has a NUL, or names that come to more than 8192 bytes, each with 1 more.

    • @PanicsAtCaller Public Method Identify(chain: Certificate[], key: Key) method #

      Gives a server that asks for a certificate chain, its own certificate first, and key, its private key. Panics when the chain is empty, or a certificate is one mbedTLS can't read, or the key isn't the first certificate's private key, of ECDSA P-256 or RSA, or the first certificate's usages aren't a TLS client's.

    • @PanicsAtCaller Public Method Connect<S>(stream: S, host: String): TlsStream<S> Throws NetError, TimeoutError method #

      TLS over stream to host, a name or an IP address, which the server's certificate has to be for, once the handshake is done. A name goes to the server as its server_name, and an address as none, as RFC 6066 has it. Panics for an empty host, one with a NUL, or one of more than 255 bytes.

    • @PanicsAtCaller Public Async Method ConnectAsync<S>(stream: S, host: String): TlsStream<S> Throws NetError, TimeoutError method #

      Connect's Async twin, which waits on the main thread.

    TlsServer class 

    Public Class TlsServer

    A server of TLS, which accepts connections over streams with its certificate chain and key, and can ask each client for a certificate that a root it trusts signed.

    std/net/tls.fb, line 288

    • @PanicsAtCaller Public New(chain: Certificate[], key: Key) constructor #

      A server whose certificate is chain's first, which the others signed, up to one a client's root signed, and whose private key is key. Panics when the chain is empty, or a certificate is one mbedTLS can't read, or the key isn't the first certificate's private key, of ECDSA P-256 or RSA, or the first certificate's usages aren't a TLS server's.

    • @PanicsAtCaller Public Method Offer(protocols: String[]) method #

      Picks the first of the application protocols, most wanted first, that a client offers, which the TlsStream's Protocol says, and refuses a client that offers only others. Panics for a name that isn't 1 to 255 bytes, or has a NUL, or names that come to more than 8192 bytes, each with 1 more.

    • @PanicsAtCaller Public Method Identify(chain: Certificate[], key: Key) method #

      Gives connections chain and key from then on, as a renewed certificate is given; those accepted before keep what they had. Panics as New does.

    • Public Method RequireClients(roots: Certificate[]) method #

      Asks each client for a certificate that one of roots signed, and refuses a client without one, from then on.

    • Public Method Accept<S>(stream: S): TlsStream<S> Throws NetError, TimeoutError method #

      TLS over stream, from a client, once the handshake is done.

    • Public Async Method AcceptAsync<S>(stream: S): TlsStream<S> Throws NetError, TimeoutError method #

      Accept's Async twin, which waits on the main thread.

    TlsStream class 

    Public Class TlsStream<S> Implements Reader, Writer

    TLS over S, a stream: what's written goes to the other side through TLS's records, and what's read came from it. A failure of TLS after the handshake throws an IOError, whose Cause is a NetError of TLS, and the stream's own failure is thrown as it was. Close sends close_notify, which a read on the other side ends at; one that ends without it throws an IOError of UNEXPECTED_END. Neither closes the stream it's on, which Stream gives.

    std/net/tls.fb, line 354

    • Public Property Stream: S property #

      The stream it's on.

    • Public Property Version: String property #

      The version of TLS the handshake agreed on: "TLS 1.2" or "TLS 1.3".

    • Public Property Protocol: String? property #

      The application protocol the server picked of those the client offered, or Null for none.

    • Public Property PeerCertificate: Certificate? property #

      The other side's certificate, or Null when it sent none, as a client asked for none does, or it's of a key std.crypto doesn't take.

    • Public Method Read(into: Buffer<UInt8>): Int64 Throws IOError method #

      Up to into.Count bytes of what the other side sent, once a record of them has come, or 0 once it closed with close_notify.

    • Public Async Method ReadAsync(into: Buffer<UInt8>): Int64 Throws IOError method #

      Read's Async twin, which waits on the main thread instead of blocking it. One that can only block reads with Read.

      Doc from std.io.streams.Reader.ReadAsync.

    • Public Method Write(from: Buffer<UInt8>) Throws IOError method #

      Writes from's bytes to the other side, a record at a time. After Close, it throws an IOError whose Cause is a NetError of CLOSED.

    • Public Async Method WriteAsync(from: Buffer<UInt8>) Throws IOError method #

      Write's Async twin, which waits on the main thread instead of blocking it.

      Doc from std.io.streams.Writer.WriteAsync.

    • Public Method Flush() Throws IOError method #

      Flushes the other stream, which holds what it wrote.

    • Public Async Method FlushAsync() Throws IOError method #

      Flush's Async twin.

      Doc from std.io.streams.Writer.FlushAsync.

    • Public Method Close() Throws IOError method #

      Sends close_notify, which tells the other side nothing more comes, and flushes the other stream, the first time; a write after it throws. It doesn't close that stream, which Stream gives, and what the other side sends can still be read.

    • Public Async Method CloseAsync() Throws IOError method #

      What Close does, without blocking its thread: a call gives its Task.

    TlsListener class 

    Public Class TlsListener

    Takes TCP connections at an address and accepts each as its TlsServer does, giving them as TlsStreams over TcpStreams. It closes when it goes, or at Close.

    std/net/tls.fb, line 599

    • @PanicsAtCaller Public Static Method Listen(address: SocketAddress, server: TlsServer, backlog: Int = BACKLOG): TlsListener Throws NetError static method #

      Listens at address as server, as TcpListener.Listen does. Panics for a backlog below 1.

    • @PanicsAtCaller Public Static Method Listen(host: String, port: UInt16, server: TlsServer, backlog: Int = BACKLOG): TlsListener Throws NetError static method #

      Listens at host's first address and port as server. Panics for a backlog below 1.

    • Public Property LocalAddress: SocketAddress property #

      Where it listens, the port the OS picked included.

    • Public Method Accept(timeout: Duration? = Null): TlsStream<TcpStream> Throws NetError, TimeoutError method #

      The next connection, once its handshake is done, waiting up to timeout for a TCP connection and its handshake, or as long as they take for a Null one. A client whose handshake fails throws here, as a NetError, or as a TimeoutError when it's too slow for timeout, after which the listener takes the next one.

    • Public Async Method AcceptAsync(timeout: Duration? = Null): TlsStream<TcpStream> Throws NetError, TimeoutError method #

      Accept's Async twin, which waits on the main thread.

    • Public Method Close() method #

      Closes it at once, as a TcpListener closes.

    Report an issue with this page or with FutureBlitz on GitHub.