TLS

Config(; ...)

Reusable TLS configuration for client and server sessions.

Keyword arguments:

• server_name: hostname or IP literal used for certificate verification. For clients, this also drives SNI when it is a hostname. If omitted, connect will try to derive it from the dial target.
• verify_peer: whether to validate the remote certificate chain and peer name.
• client_auth: server-side client certificate policy.
• cert_file / key_file: PEM-encoded certificate chain and private key. Servers must provide both; clients may provide both for mutual TLS.
• ca_file: CA bundle or hashed CA directory used to verify remote servers. When omitted, client verification uses NetworkOptions.ca_roots_path().
• client_ca_file: CA bundle or hashed CA directory used by servers to verify client certificates. This is required for server configs that verify presented client certs.
• alpn_protocols: ordered ALPN protocol preference list.
• handshake_timeout_ns: optional cap, in monotonic nanoseconds, applied only while the handshake is running. Existing transport deadlines still win if they are earlier.
• min_version / max_version: TLS protocol version bounds. nothing leaves the bound unset.

Returns a reusable immutable Config.

Throws ConfigError if the keyword combination is internally inconsistent.

ConnectionState

Snapshot of negotiated TLS connection state.

Fields:

• handshake_complete: whether the TLS handshake has finished successfully.
• version: negotiated TLS protocol version string as reported by OpenSSL.
• alpn_protocol: negotiated ALPN protocol, or nothing if ALPN was not used.

Conn

TLS stream wrapper over one TCP.Conn.

Conn is safe for one concurrent reader and one concurrent writer. Handshake, read, and write all have separate locks so lazy handshakes and shutdown can coordinate without corrupting the OpenSSL state machine. Because Conn <: IO, standard Base stream helpers like read, read!, readbytes!, eof, and write apply directly to decrypted application data.

Listener

TLS listener wrapper over TCP.Listener.

Accepted connections are wrapped in server-side TLS state but are not handshaken until handshake! or the first read/write call.

ConfigError

Raised when TLS configuration is invalid.

This is thrown before any network I/O starts, typically while normalizing a Config or constructing an SSL_CTX.

TLSError

Raised when TLS handshake/read/write/close operations fail.

code is usually an OpenSSL SSL_get_error result, though wrapper paths may set it to 0 when the failure is higher-level than one OpenSSL call. cause preserves the underlying Julia-side exception when the failure originated in the transport/poller layer instead of OpenSSL itself.

TLSHandshakeTimeoutError

Raised when handshake exceeds the configured timeout.

This is kept separate from TLSError because handshake timeouts are often configured and handled distinctly from generic TLS failures.

DeadlineExceededError

Alias for the transport deadline timeout type used by TLS.

Catch TLS.DeadlineExceededError for direct listener accept timeouts and when inspecting TLSError.cause. Higher-level TLS operations may wrap deadline expiry in TLSError or TLSHandshakeTimeoutError so callers can keep operation-specific handling.

client(tcp, config) -> Conn

Wrap an established TCP.Conn in client-side TLS state.

The handshake is deferred until handshake! or the first read/write operation.

Throws ConfigError or TLSError if the TLS state cannot be initialized.

server(tcp, config) -> Conn

Wrap an established TCP.Conn in server-side TLS state.

The handshake is deferred until handshake! or the first read/write operation.

Throws ConfigError or TLSError if the TLS state cannot be initialized.

connect(remote_addr; kwargs...) -> Conn
connect(remote_addr, local_addr; kwargs...) -> Conn

Connect to a concrete TCP.SocketAddr, negotiate TLS, and return a fully handshaken client connection.

This is the direct-address counterpart to the string-address connect(network, address; ...) overloads. The underlying socket setup is delegated to TCP.connect, after which the returned transport is wrapped in TLS and handshaken immediately.

TLS keyword arguments are forwarded to Config. If server_name is omitted, it is inferred from the concrete remote address when possible so peer verification and SNI can follow the same rules as the string-address client path.

connect(network, address; kwargs...) -> Conn

Connect to address, negotiate TLS, and return a fully handshaken client connection.

Network-resolution keyword arguments are:

• timeout_ns
• deadline_ns
• local_addr
• fallback_delay_ns
• resolver
• policy

TLS keyword arguments are forwarded to Config:

• server_name
• verify_peer
• client_auth
• cert_file
• key_file
• ca_file
• client_ca_file
• alpn_protocols
• handshake_timeout_ns
• min_version
• max_version

If server_name is omitted, it is derived from address when possible so SNI and peer verification use the dial target's host name automatically.

connect(address; kwargs...) -> Conn

Convenience shorthand for connect("tcp", address; kwargs...).

listen(network, address, config; backlog=128, reuseaddr=true) -> Listener

Create a TLS listener by first creating a TCP listener and then associating a server Config with accepted connections.

Accepted Conns are returned in lazy-handshake form.

Throws ConfigError if the server config is invalid and propagates any listener creation errors from TCP.listen.

listen(local_addr, config; backlog=128, reuseaddr=true) -> Listener

Create a TLS listener from a concrete local TCP.SocketAddr.

This is the direct-address counterpart to listen(network, address, config; ...). The underlying TCP listener is created with TCP.listen, then accepted connections are wrapped in lazy-handshake TLS state.

accept(listener) -> Conn

Accept one inbound TCP connection and wrap it in server-side TLS state.

The returned Conn has not handshaken yet. If the listener deadline expires, accept(listener) throws DeadlineExceededError.

handshake!(conn)

Run the TLS handshake to completion if it has not already finished.

This method is idempotent. Concurrent callers serialize through handshake_lock, so only one task drives OpenSSL while the others observe the completed state afterward.

Returns nothing.

Throws:

• TLSHandshakeTimeoutError when config.handshake_timeout_ns expires
• TLSError for OpenSSL or transport failures
• EOFError if the peer closes cleanly during the handshake

read!(conn, buf) -> buf

Read exactly length(buf) decrypted bytes into buf or throw EOFError.

Because Conn <: IO, Base's generic read! implementation already supports mutable byte views like @view bytes[2:5] in addition to plain vectors.

Use readbytes! or readavailable when you want a count-returning read that may stop early.

readbytes!(conn, buf, nb=length(buf); all::Bool=true) -> Int

Read up to nb decrypted bytes into buf, returning the byte count.

If all is true (the default), the call keeps reading until nb bytes have been transferred, EOF is reached, or an error occurs. If all is false, at most one underlying TLS read is performed.

Resizable Vector{UInt8} buffers grow when needed, matching Julia's standard readbytes! behavior. Fixed-size contiguous byte views must satisfy nb <= length(buf).

readavailable(conn) -> Vector{UInt8}

Read and return decrypted plaintext that is ready without requiring a full-buffer exact read.

eof(conn) -> Bool

Report whether the peer has cleanly finished the TLS stream.

isopen(conn) -> Bool

Return true while both the TLS state and underlying TCP transport remain open.

isopen(listener) -> Bool

Return true while the wrapped TCP listener remains open.

write(conn, buf) -> Int
write(conn, buf, nbytes) -> Int

Write plaintext application bytes through the TLS connection.

write(conn, buf) attempts to write the entire buffer. The fixed-size byte-buffer overload allows callers to cap the write at nbytes.

close(conn)

Close the TLS connection and the underlying TCP transport.

If the handshake completed, this best-effort sends a TLS close_notify alert before closing the socket. The method is idempotent and returns nothing.

close(listener)

Close the underlying TCP listener. Repeated closes are treated as no-ops.

closewrite(conn)

Send TLS shutdown on the write side and mark future writes as permanently failed.

This is the TLS analogue of half-closing a TCP socket. It requires the handshake to have completed because the TLS close-notify alert is itself a TLS record.

Returns nothing.

Throws TLSError if the TLS shutdown path fails.

set_deadline!(conn, deadline_ns)

Set both read and write deadlines on the underlying transport.

deadline_ns is interpreted using the same monotonic-clock convention as TCP and IOPoll: 0 clears the deadline, negative values mean the deadline has already expired, and positive values are absolute time_ns() values.

set_deadline!(listener, deadline_ns)

Set the accept deadline on the underlying TCP listener.

This affects accept(listener) only. The returned Conn still uses its own connection and handshake deadlines afterward. Expired accept waits throw DeadlineExceededError.

set_read_deadline!(conn, deadline_ns)

Set the read deadline on the underlying transport. See set_deadline! for the timestamp convention.

set_write_deadline!(conn, deadline_ns)

Set the write deadline on the underlying transport. See set_deadline! for the timestamp convention.

local_addr(conn)

Return the local TCP.SocketAddr for the wrapped transport.

local_addr(listener)

Return the local listening address for the wrapped TCP listener.

This is an alias for addr(listener).

remote_addr(conn)

Return the remote TCP.SocketAddr for the wrapped transport.

net_conn(conn) -> TCP.Conn

Expose the underlying TCP connection.

Callers that need transport-level inspection can reach through the TLS wrapper without reconstructing the socket state.

connection_state(conn) -> ConnectionState

Return a snapshot of the currently negotiated TLS state.

This does not force a handshake; if the handshake has not yet run, the returned ConnectionState reports handshake_complete=false.

addr(listener)

Return the local listening address for the wrapped TCP listener.