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 TlsIOResult
class TlsError

Types 11

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.

SUCCESS = 0Operation completed successfully.
HANDSHAKE_FAILED = 1TLS handshake failed to complete.
CERTIFICATE_INVALID = 2Peer certificate is invalid or malformed.
CERTIFICATE_EXPIRED = 3Peer certificate has expired.
CERTIFICATE_REVOKED = 4Peer certificate has been revoked.
CERTIFICATE_UNKNOWN = 5Peer certificate is unknown or untrusted.
PROTOCOL_ERROR = 6TLS protocol error occurred.
WOULD_BLOCK = 7Operation would block (non-blocking I/O).
CLOSED = 8Connection has been closed.
INTERNAL_ERROR = 9Internal TLS library error.
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.
HANDSHAKING = 1TLS handshake is in progress.
CONNECTED = 2TLS connection is established and ready for data.
SHUTDOWN = 3TLS shutdown is in progress.
ERROR = 4An error occurred on the connection.
structCertificateInfo

X.509 certificate information.

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

Fields
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() 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).
Methods
TlsContext clientContext() pure @safe nothrow @nogcCreate a client-side TLS context with secure defaults.
TlsContext serverContext() 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.
bool isVersionRangeValid() const pure @safe nothrow @nogcCheck if the version range is valid.
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) pure @safe nothrow @nogcCreate a successful result.
TlsIOResult failure(TlsErrorCode code) 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() pure @safe nothrow @nogcCreate a completed handshake result.
HandshakeResult continuing() pure @safe nothrow @nogcCreate an in-progress handshake result.
HandshakeResult failed(TlsErrorCode code) pure @safe nothrow @nogcCreate a failed handshake result.