StormByte-Crypto 3.1.0
C++26 cryptography module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Crypto::TLS::Session Class Referencefinal

OpenSSL-backed TLS 1.3 stream engine driven only by caller buffers. More...

#include <StormByte/crypto/tls/session.hxx>

Public Member Functions

 Session () noexcept
 Construct a failed, empty session.
 Session (Session &&other) noexcept
 Transfer session state.
 ~Session () noexcept
 Destroy the TLS state and its private OpenSSL resources.
Session & operator= (Session &&other) noexcept
 Transfer session state.
 Session (const Session &)=delete
Session & operator= (const Session &)=delete
StormByte::Expected< std::size_t, SessionError > FeedEncrypted (std::span< const std::byte > encrypted)
 Copy ciphertext into the bounded input buffer and advance TLS.
StormByte::Expected< std::size_t, SessionError > DrainEncrypted (std::span< std::byte > output)
 Copy pending TLS protocol bytes into the caller's output buffer.
StormByte::Expected< std::size_t, SessionError > WritePlaintext (std::span< const std::byte > plaintext)
 Encrypt caller plaintext after successful handshake validation.
StormByte::Expected< std::size_t, SessionError > ReadPlaintext (std::span< std::byte > output)
 Decrypt available application bytes into the caller's buffer.
StormByte::Expected< void, SessionError > Shutdown ()
 Begin or advance orderly TLS shutdown.
State Status () const noexcept
 Read the current lifecycle state.
SessionError Failure () const noexcept
 Read the sticky fatal failure, if any.
std::string_view FailureDetail () const noexcept
 Read the first fatal failure's explanation without logging or allocation.
bool HandshakeComplete () const noexcept
 Test whether the TLS handshake finished successfully.
std::string_view NegotiatedALPN () const noexcept
 Read the negotiated application protocol.

Static Public Member Functions

static StormByte::Expected< Session, SessionError > CreateClient (const ClientConfiguration &configuration)
 Create a client with explicit identity, trust, time and TLS policy.
static StormByte::Expected< Session, SessionError > CreateServer (const ServerConfiguration &configuration)
 Create a server that presents the configured certificate and key.

Static Public Attributes

static constexpr std::size_t MaxInputChunk = 64 * 1024
 Maximum ciphertext accepted by one FeedEncrypted call.
static constexpr std::size_t MaxPendingCiphertext = 1024 * 1024
 Maximum ciphertext retained in either internal buffer.

Detailed Description

OpenSSL-backed TLS 1.3 stream engine driven only by caller buffers.

Crypto performs no socket, DNS, HTTP, filesystem or clock I/O. Callers feed received ciphertext with FeedEncrypted, drain pending protocol bytes with DrainEncrypted, and exchange application bytes with WritePlaintext and ReadPlaintext. Methods report partial progress so the caller retains ownership of transport scheduling, deadlines, cancellation and retries. OpenSSL types are private to the implementation and are not part of this API.

Each session is single-threaded; callers must serialize all operations on it.

Constructor & Destructor Documentation

◆ Session() [1/3]

StormByte::Crypto::TLS::Session::Session ( )
noexcept

Construct a failed, empty session.

◆ Session() [2/3]

StormByte::Crypto::TLS::Session::Session ( Session && other)
noexcept

Transfer session state.

Parameters
otherSource session; it becomes empty.

◆ ~Session()

StormByte::Crypto::TLS::Session::~Session ( )
noexcept

Destroy the TLS state and its private OpenSSL resources.

◆ Session() [3/3]

StormByte::Crypto::TLS::Session::Session ( const Session & )
delete

Member Function Documentation

◆ CreateClient()

StormByte::Expected< Session, SessionError > StormByte::Crypto::TLS::Session::CreateClient ( const ClientConfiguration & configuration)
static

Create a client with explicit identity, trust, time and TLS policy.

Parameters
configurationBorrowed options copied or consumed during this call.
Returns
Configured client or a typed setup failure.
Exceptions
StormByte::Safe::AllocationErrorSafe-owned configuration cannot be copied.

◆ CreateServer()

StormByte::Expected< Session, SessionError > StormByte::Crypto::TLS::Session::CreateServer ( const ServerConfiguration & configuration)
static

Create a server that presents the configured certificate and key.

Parameters
configurationBorrowed certificate/key and policy options.
Returns
Configured server or a typed setup failure.
Exceptions
StormByte::Safe::AllocationErrorSafe-owned configuration cannot be copied.

◆ DrainEncrypted()

StormByte::Expected< std::size_t, SessionError > StormByte::Crypto::TLS::Session::DrainEncrypted ( std::span< std::byte > output)

Copy pending TLS protocol bytes into the caller's output buffer.

Parameters
outputDestination for ciphertext.
Returns
Number of encrypted bytes produced; zero means no output is pending.

◆ Failure()

SessionError StormByte::Crypto::TLS::Session::Failure ( ) const
noexcept

Read the sticky fatal failure, if any.

Returns
Failure code; BackendFailure for a session that was never created.

◆ FailureDetail()

std::string_view StormByte::Crypto::TLS::Session::FailureDetail ( ) const
noexcept

Read the first fatal failure's explanation without logging or allocation.

Returns
Borrowed English text, empty until a fatal failure; empty sessions report why.
Note
Valid until destruction or move-assignment. Copy before destroying the session. Contains no peer names, certificate bodies, credentials or application data.

◆ FeedEncrypted()

StormByte::Expected< std::size_t, SessionError > StormByte::Crypto::TLS::Session::FeedEncrypted ( std::span< const std::byte > encrypted)

Copy ciphertext into the bounded input buffer and advance TLS.

Parameters
encryptedCaller-owned network bytes.
Returns
Number of bytes consumed; zero means backpressure or no progress.
Exceptions
Noexception is raised for peer-controlled protocol errors; they set Failed.

◆ HandshakeComplete()

bool StormByte::Crypto::TLS::Session::HandshakeComplete ( ) const
noexcept

Test whether the TLS handshake finished successfully.

Returns
True only while the session is Open or Closing after a validated handshake.

◆ NegotiatedALPN()

std::string_view StormByte::Crypto::TLS::Session::NegotiatedALPN ( ) const
noexcept

Read the negotiated application protocol.

Returns
Borrowed protocol name, empty when ALPN was not negotiated.
Note
The view remains valid only while this session remains alive.

◆ operator=() [1/2]

Session & StormByte::Crypto::TLS::Session::operator= ( const Session & )
delete

◆ operator=() [2/2]

Session & StormByte::Crypto::TLS::Session::operator= ( Session && other)
noexcept

Transfer session state.

Parameters
otherSource session; it becomes empty.
Returns
This session.

◆ ReadPlaintext()

StormByte::Expected< std::size_t, SessionError > StormByte::Crypto::TLS::Session::ReadPlaintext ( std::span< std::byte > output)

Decrypt available application bytes into the caller's buffer.

Parameters
outputDestination for plaintext.
Returns
Number of plaintext bytes produced; zero means more ciphertext is needed.

◆ Shutdown()

StormByte::Expected< void, SessionError > StormByte::Crypto::TLS::Session::Shutdown ( )

Begin or advance orderly TLS shutdown.

Returns
Success, including when peer close-notify is still outstanding.

◆ Status()

State StormByte::Crypto::TLS::Session::Status ( ) const
noexcept

Read the current lifecycle state.

Returns
State; a moved-from or empty session reports Failed.

◆ WritePlaintext()

StormByte::Expected< std::size_t, SessionError > StormByte::Crypto::TLS::Session::WritePlaintext ( std::span< const std::byte > plaintext)

Encrypt caller plaintext after successful handshake validation.

Parameters
plaintextApplication bytes.
Returns
Number of plaintext bytes consumed; partial progress is allowed.

Member Data Documentation

◆ MaxInputChunk

std::size_t StormByte::Crypto::TLS::Session::MaxInputChunk = 64 * 1024
staticconstexpr

Maximum ciphertext accepted by one FeedEncrypted call.

◆ MaxPendingCiphertext

std::size_t StormByte::Crypto::TLS::Session::MaxPendingCiphertext = 1024 * 1024
staticconstexpr

Maximum ciphertext retained in either internal buffer.


The documentation for this class was generated from the following file: