eve.tls.api

TLS API Contract Module

This module defines the common API/contract that platform-specific TLS implementations (OpenSSL on Linux, SChannel on Windows) must implement. It provides types for TLS configuration, connection state, certificate handling, and stream operations.

Copyright

Copyright © 2025 Dejan Lekic

License

Boost Software License, Version 1.0
enum HandshakeState TlsErrorCode TlsRole TlsState TlsVerifyMode TlsVersion
struct CertificateInfo HandshakeResult TlsContext TlsIoInterest TlsIOResult
class TlsError

Types 12

enumTlsVersion : ubyte

TLS protocol versions supported by the library.

These values represent the various versions of the TLS protocol that can be negotiated during the handshake.

TLS_1_0 = 0x01TLS 1.0 (deprecated, insecure).
TLS_1_1 = 0x02TLS 1.1 (deprecated, insecure).
TLS_1_2 = 0x03TLS 1.2 (widely supported, secure).
TLS_1_3 = 0x04TLS 1.3 (latest, most secure).
enumTlsErrorCode : ubyte

Error codes for TLS operations.

These codes identify specific TLS-related failures that may occur during handshake, data transfer, or certificate validation.

Retryability and Fatality Guide:

  • OK — Success, no retry needed
  • HANDSHAKE_FAILED — Generally fatal, handshake cannot proceed
  • CERTIFICATE_* — Fatal, certificate validation failed
  • PROTOCOL_ERROR — Fatal, protocol violation detected
  • WOULD_BLOCK — Retryable, wait for I/O readiness
  • CLOSED — Fatal, connection cannot be reused
  • INTERNAL_ERROR — Fatal, TLS library state corrupted
  • WANT_READ — Retryable, continue when readable
  • WANT_WRITE — Retryable, continue when writable
  • IO_ERROR — Depends on underlying error; may be retryable
  • INIT_FAILED — Fatal, context setup failed
  • CERT_ERROR — Fatal, certificate loading failed
  • KEY_ERROR — Fatal, key loading failed
  • INVALID_STATE — Fatal, stream in wrong state

OK = 0Operation completed successfully. Retryable: No (operation completed) Fatal: No
HANDSHAKE_FAILED = 1TLS handshake failed to complete. Retryable: No Fatal: Yes (handshake cannot proceed)
CERTIFICATE_INVALID = 2Peer certificate is invalid or malformed. Retryable: No Fatal: Yes (certificate validation failed)
CERTIFICATE_EXPIRED = 3Peer certificate has expired. Retryable: No Fatal: Yes (certificate validation failed)
CERTIFICATE_REVOKED = 4Peer certificate has been revoked. Retryable: No Fatal: Yes (certificate validation failed)
CERTIFICATE_UNKNOWN = 5Peer certificate is unknown or untrusted. Retryable: No Fatal: Yes (certificate validation failed)
PROTOCOL_ERROR = 6TLS protocol error occurred. Retryable: No Fatal: Yes (protocol violation detected)
WOULD_BLOCK = 7Operation would block (non-blocking I/O). Retryable: Yes (wait for I/O readiness) Fatal: No Action: Wait for socket to become readable or writable
CLOSED = 8Connection has been closed. Retryable: No Fatal: Yes (connection cannot be reused)
INTERNAL_ERROR = 9Internal TLS library error. Retryable: No Fatal: Yes (TLS library state corrupted)
WANT_READ = 10Operation needs to read data before continuing. Retryable: Yes (continue when socket becomes readable) Fatal: No Action: Register for read readiness before retrying
WANT_WRITE = 11Operation needs to write data before continuing. Retryable: Yes (continue when socket becomes writable) Fatal: No Action: Register for write readiness before retrying
IO_ERROR = 12Underlying I/O subsystem error. Retryable: Maybe (depends on errno/GetLastError) Fatal: Depends on error code Action: Check underlying I/O error for details
INIT_FAILED = 13TLS context or stream initialization failed. Retryable: No Fatal: Yes (TLS context setup failed)
CERT_ERROR = 14Certificate loading or processing error. Retryable: No Fatal: Yes (certificate loading failed)
KEY_ERROR = 15Private key loading or processing error. Retryable: No Fatal: Yes (key loading failed)
INVALID_STATE = 16Operation called in invalid state for this TLS stream. Retryable: No Fatal: Yes (stream in wrong state)
classTlsError : Exception

TLS-specific exception with error code.

This exception is thrown when a TLS operation fails. It includes an error code that identifies the specific type of failure.

Fields
TlsErrorCode codeThe specific TLS error code.
Constructors
this(TlsErrorCode code, string msg, string file = __FILE__, size_t line = __LINE__)Construct a TlsError with the given code and message.
this(string msg, string file = __FILE__, size_t line = __LINE__)Construct a TlsError with just a message (defaults to INTERNAL_ERROR).
enumTlsVerifyMode : ubyte

Certificate verification modes.

These modes control how the TLS implementation verifies the peer's certificate during the handshake.

NONE = 0Do not verify the peer's certificate.
PEER = 1Verify the peer's certificate if provided.
FAIL_IF_NO_PEER_CERT = 2Fail the handshake if the peer does not provide a certificate.
CLIENT_ONCE = 4Request client certificate only once (server mode).
enumTlsRole : ubyte

TLS connection role.

Identifies whether the connection acts as a client or server during the TLS handshake.

CLIENT = 0Client role - initiates the handshake.
SERVER = 1Server role - responds to handshake initiation.
enumHandshakeState : ubyte

TLS handshake progress state.

Tracks the current state of the TLS handshake process.

NOT_STARTED = 0Handshake has not been initiated.
IN_PROGRESS = 1Handshake is currently in progress.
COMPLETED = 2Handshake completed successfully.
FAILED = 3Handshake failed with an error.
enumTlsState : ubyte

TLS stream state.

Represents the overall state of a TLS stream connection.

DISCONNECTED = 0Not connected to any peer.
INITIALIZING = 1TLS context is being initialized.
READY = 2TLS context initialized, ready to start handshake.
HANDSHAKING = 3TLS handshake is in progress.
CONNECTED = 4TLS connection is established and ready for data.
SHUTDOWN = 5TLS shutdown is in progress (close-notify pending).
CLOSED = 6TLS connection has been fully closed.
ERROR = 7An error occurred on the connection.
structTlsIoInterest

I/O interest flags for a TLS stream.

After each TLS operation (handshake, read, write, shutdown), the caller should query TlsStream.ioInterest() to determine what events to wait for on the underlying transport. This is necessary because TLS operations can require both reads and writes (e.g.\ renegotiation).

Fields
ushort bits
noneNo I/O interest (disconnected, closed, or error).
readableWait for the transport to become readable.
writableWait for the transport to become writable.
readWriteWait for both read and write readiness.
structCertificateInfo

X.509 certificate information.

Contains the essential fields extracted from an X.509 certificate, typically used for displaying certificate details or logging.

Fields
bool hasValueWhether a certificate was received from the peer.
string subjectCertificate subject distinguished name.
string issuerCertificate issuer distinguished name.
string notBeforeStart of certificate validity period (ISO 8601 format).
string notAfterEnd of certificate validity period (ISO 8601 format).
string serialNumberCertificate serial number as hex string.
Methods
bool isValid() const pure @safe nothrow @nogcCheck if the certificate information is valid.
CertificateInfo empty() static pure @safe nothrow @nogcCreate an empty/invalid certificate info.
structTlsContext

TLS configuration context.

Holds configuration parameters for TLS connections, including protocol version constraints and certificate verification settings. This context is used to initialize TLS streams.

Fields
TlsVersion minVersionMinimum allowed TLS protocol version.
TlsVersion maxVersionMaximum allowed TLS protocol version.
TlsVerifyMode verifyModeCertificate verification mode.
TlsRole roleConnection role (client or server).
string serverNameServer hostname for SNI (Server Name Indication).
string caCertFilePath to CA certificates file (PEM format).
string certFilePath to client/server certificate file (PEM format).
string keyFilePath to private key file (PEM format).
string[] alpnProtocolsALPN protocol list for negotiation (e.g. ["h2", "http/1.1"]).
Methods
TlsContext clientContext() static pure @safe nothrow @nogcCreate a client-side TLS context with secure defaults.
TlsContext serverContext() static pure @safe nothrow @nogcCreate a server-side TLS context with secure defaults.
TlsContext setMinVersion(TlsVersion ver) ref pure @safe nothrow @nogc returnSet the minimum TLS protocol version.
TlsContext setMaxVersion(TlsVersion ver) ref pure @safe nothrow @nogc returnSet the maximum TLS protocol version.
TlsContext setVerifyMode(TlsVerifyMode mode) ref pure @safe nothrow @nogc returnSet the certificate verification mode.
TlsContext setServerName(string name) ref pure @safe nothrow @nogc returnSet the server name for SNI.
TlsContext setCaCertFile(string path) ref pure @safe nothrow @nogc returnSet the CA certificates file path.
TlsContext setCertFile(string path) ref pure @safe nothrow @nogc returnSet the certificate file path.
TlsContext setKeyFile(string path) ref pure @safe nothrow @nogc returnSet the private key file path.
TlsContext setAlpnProtocols(string[] protocols) ref pure @safe nothrow @nogc returnSet the ALPN protocol list.
bool isVersionRangeValid() const pure @safe nothrow @nogcCheck if the version range is valid.
bool isClient() const pure @safe nothrow @nogcCheck if this context is configured for client role.
bool isServer() const pure @safe nothrow @nogcCheck if this context is configured for server role.
structTlsIOResult

I/O result for TLS stream operations.

Encapsulates the result of a read or write operation, including the number of bytes transferred and any error that occurred.

Fields
size_t bytesTransferredNumber of bytes successfully transferred.
TlsErrorCode errorError code if the operation failed.
Methods
bool isSuccess() const pure @safe nothrow @nogcCheck if the operation completed successfully.
bool wouldBlock() const pure @safe nothrow @nogcCheck if the operation would block.
bool isClosed() const pure @safe nothrow @nogcCheck if the connection was closed.
TlsIOResult success(size_t bytes) static pure @safe nothrow @nogcCreate a successful result.
TlsIOResult failure(TlsErrorCode code) static pure @safe nothrow @nogcCreate a failure result.
structHandshakeResult

Handshake result from a TLS handshake operation.

Contains the current state of the handshake and any error information.

Fields
HandshakeState stateCurrent state of the handshake.
TlsErrorCode errorError code if handshake failed.
Methods
bool isComplete() const pure @safe nothrow @nogcCheck if the handshake completed successfully.
bool inProgress() const pure @safe nothrow @nogcCheck if the handshake is still in progress.
bool isFailed() const pure @safe nothrow @nogcCheck if the handshake failed.
HandshakeResult completed() static pure @safe nothrow @nogcCreate a completed handshake result.
HandshakeResult continuing() static pure @safe nothrow @nogcCreate an in-progress handshake result.
HandshakeResult failed(TlsErrorCode code) static pure @safe nothrow @nogcCreate a failed handshake result.