ddn.api.net.tls

TLS protocol versions.

TLS connection role.

TLS handshake state.

Distinguishes between different lifecycle stages of a TLS connection.

Certificate verification mode. Peer certificate verification mode.

Normative default: contexts start in REQUIRED mode for clients and NONE mode for servers; implementations MUST use these defaults when setVerifyMode is never called, so no backend can silently ship an unverified client connection.

Result of a non-blocking I/O operation.

Progress indicator for non-blocking TLS operations.

Every potentially-blocking operation returns TlsProgress instead of blocking. The caller checks the result and re-drives the operation when I/O is possible.

Typed error information for non-blocking TLS operations.

Used by TlsResult and TlsStream.lastError to report errors without throwing exceptions. This is the preferred error reporting mechanism for non-blocking I/O.

Result of a TLS read or write operation.

Combines byte count with progress information and optional error details. The eof field distinguishes between "no data yet" (bytes=0, eof=false) and "connection closed" (bytes=0, eof=true).

Opaque handle for event loop registration.

Abstracts platform differences (POSIX fd, Windows SOCKET, etc.) so that TLS code remains platform-agnostic.

Common TLS cipher suites for type-safe configuration.

Use setCipherSuites() with these enum values for compile-time checking. For custom or unlisted cipher suites, use setCipherSuiteStrings().

Base exception for TLS-related errors.

Exception thrown when the TLS handshake fails.

Exception for certificate verification failures in throwing (blocking) API layers. The non-blocking stream API reports the same condition as TlsProgress.ERROR with TlsError.type == CERTIFICATE_ERROR.

Exception thrown when a TLS alert is received.

Abstract transport layer for TLS.

This interface abstracts the underlying byte stream (TCP socket, memory buffer, pipe, etc.) that TLS operates over. Implementations wrap the actual I/O mechanism.

This separation allows:

• Testing TLS logic without real network I/O
• Using TLS over different transport mechanisms
• Implementing non-blocking I/O patterns

Return Value Convention:

• Positive value: Number of bytes read/written
• Zero (0): Clean end-of-file (EOF) - peer closed connection gracefully
• Negative value: IoResult enum indicating error condition

Represents an X.509 certificate for TLS operations.

• Represents a chain of certificates.
• The first certificate is the end-entity (leaf) certificate, /
• Represents a certificate chain as presented by a peer.
• The getters are deliberately not const: inside a const method stored
• interface references become const and cannot be returned as mutable
• references without unsafe casts. Implementations return the live objects.
• Chains obtained during verification must be treated as read-only by
• convention. *
• Certificates are ordered leaf-first, as received: the leaf certificate is
• followed by intermediate certificates, and optionally the root CA.

Certificate store for trusted CA certificates.

Represents a resumable TLS session.

Sessions can be cached and reused to speed up subsequent connections to the same server by skipping the full handshake.

Cache for storing and retrieving TLS sessions.

Security Considerations: Implementations should:

• Limit the maximum number of cached sessions to prevent memory exhaustion from attackers flooding the server with session resumption attempts.
• Implement an eviction policy (e.g., LRU - Least Recently Used) when the limit is reached.
• Periodically call pruneExpired() to remove stale sessions.

  See Also

  RECOMMENDED_MAX_SIZE for suggested default cache size.

Information provided to the verification callback during handshake. Outcome of the standard (built-in) certificate verification that ran before a TlsVerifyCallback is invoked.

Encrypted TLS stream for reading and writing application data.

A TLS stream wraps an underlying transport and provides transparent encryption/decryption of data. The handshake must complete before application data can be exchanged.

Usage:

auto stream = context.clientStream(transport, "example.com");
stream.handshake();  // Perform TLS handshake
stream.write(cast(const(ubyte)[])"GET / HTTP/1.1\r\n\r\n");
ubyte[4096] buffer;
auto n = stream.read(buffer[]);
stream.close();

TLS context for configuring and creating TLS connections.

A context holds configuration that can be shared across multiple connections:

• Certificate chain and private key (for servers, or client authentication)
• Trusted CA certificates
• Protocol version constraints
• Cipher suite preferences

Contexts are typically created once and reused for many connections.