Tls¶

1

import "std/net/tls";

TlsContext struct¶

Owns an SSL_CTX, i.e. the certificate/trust/verification setup that is shared by every connection made or accepted through it. Build one with newClientTlsContext or newServerTlsContext, and hand it to openTlsClientSocket or acceptTlsConnection.

A default-constructed context wraps no SSL_CTX and must not be used - it only exists so that structs which embed a TlsContext (like HttpServer) can be default-constructed themselves.

Methods¶

close¶

1

public p TlsContext.close()

Releases the underlying SSL_CTX. Safe to call more than once and on a default-constructed, never-initialized context.

TlsSocket struct¶

A TCP socket with a TLS record layer on top. Exposes the same read/writeAll/setTimeout shape as Socket, so the generic wire transport of "std/net/http" (sendRequest, receiveResponse, ...) works on it unchanged.

Methods¶

read¶

1

public f<long> TlsSocket.read(byte* buffer, long size)

Reads up to size bytes from the connection into the given buffer. Note: The given buffer needs to be at least of the given size.

Parameters

Returns: long — Number of bytes read, or a value <= 0 on error/EOF

writeAll¶

1

public f<bool> TlsSocket.writeAll(byte* content, unsigned long size)

Writes an array of bytes to the connection, retrying until either all of them were handed over to TLS or the connection breaks. Note: The given buffer needs to be at least of the given size.

Parameters

Returns: bool — true if all bytes were written, false if the connection broke in between

setTimeout¶

1

public f<bool> TlsSocket.setTimeout(unsigned long milliseconds)

Limits how long a single read or write on this connection may block. Forwards to the underlying Socket, see Socket.setTimeout.

Parameters

Returns: bool — Setting the timeout was successful or not

closeConnection¶

1

public f<bool> TlsSocket.closeConnection()

Shuts down the TLS layer and closes the current connection, while keeping the listening socket (for a server) open. This is what a server does after it has finished serving a single client.

Returns: bool — Closing the connection was successful or not

close¶

1

public f<bool> TlsSocket.close()

Shuts down the TLS layer and closes the socket. This method should always be called by the user before exiting the program.

Returns: bool — Closing the connection was successful or not

Functions¶

newClientTlsContext¶

1

public f<Result<TlsContext>> newClientTlsContext(string caFile = "")

Builds the TLS context a client hands to openTlsClientSocket. Server certificates are always verified; there is no escape hatch to turn that off, since a client that does not verify the server it talks to gets no confidentiality guarantee worth having.

Parameters

Returns: Result<TlsContext> — A ready-to-use client context, or an error describing why it could not be built

newServerTlsContext¶

1

public f<Result<TlsContext>> newServerTlsContext(string certFile, string keyFile)

Builds the TLS context an HttpServer hands to acceptTlsConnection, loading the certificate chain and private key it presents to clients.

Parameters

Returns: Result<TlsContext> — A ready-to-use server context, or an error describing why it could not be built

openTlsClientSocket¶

1

public f<Result<TlsSocket>> openTlsClientSocket(string host, unsigned short port, const TlsContext& context, unsigned long timeoutMillis = 0l)

Opens a TCP connection to the given host and port and performs a TLS client handshake on top of it, verifying the server's certificate against context and its name against host.

Parameters

Returns: Result<TlsSocket> — The established TLS connection, or an error describing why it could not be established

acceptTlsConnection¶

1

public f<Result<TlsSocket>> acceptTlsConnection(Socket& sock, const TlsContext& context)

Performs a TLS server handshake on the connection sock most recently accepted via Socket.acceptConnection.

This is a free function rather than a method on Socket because Socket is defined per-platform (see "std/net/socket_linux" and friends) and Spice does not support adding methods to a struct from outside the file that defines it.

Parameters

Returns: Result<TlsSocket> — The established TLS connection, or an error describing why it could not be established