StormByte-Crypto 3.1.0
C++26 cryptography module of the StormByte suite
Loading...
Searching...
No Matches
session.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Crypto.
5 *
6 * StormByte-Crypto original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Crypto source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, in particular OpenSSL, Crypto++, bundled libbzip2, the
23 * StormByte-Buffer tree and the StormByte suite it vendors), which remains
24 * under its own license.
25 *
26 * Neither license grants any patent rights. Any patent licenses required
27 * to use this software or third-party components must be obtained separately
28 * from the patent holders.
29 *
30 * StormByte-Crypto is distributed in the hope that it will be useful,
31 * but WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
33 * GNU Lesser General Public License for more details.
34 *
35 * You should have received a copy of the GNU Lesser General Public License
36 * version 3 along with StormByte-Crypto. If not, see
37 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
38 *
39 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
40 */
41
42#pragma once
43
47#include <StormByte/expected.hxx>
48
49#include <cstddef>
50#include <chrono>
51#include <memory>
52#include <span>
53#include <string_view>
54
55namespace StormByte::Crypto::TLS {
60 enum class Role {
63 };
64
76
89
96
101 enum class TrustSource {
104 };
105
115 struct ClientConfiguration final {
118 std::span<const X509::Certificate> trust_anchors{};
119 X509::TimePoint validation_time{std::chrono::floor<std::chrono::seconds>(
120 std::chrono::system_clock::now())};
121 bool require_revocation{false};
122 std::span<const X509::RevocationEvidence> revocation_evidence{};
123 std::span<const std::byte> certificate_chain_pem{};
124 std::span<const std::byte> private_key_pem{};
125 std::span<const std::byte> private_key_password{};
127 std::span<const std::byte> alpn_wire{};
128 };
129
138 struct ServerConfiguration final {
139 std::span<const std::byte> certificate_chain_pem{};
140 std::span<const std::byte> private_key_pem{};
141 std::span<const std::byte> private_key_password{};
143 std::span<const X509::Certificate> client_trust_anchors{};
144 X509::TimePoint validation_time{std::chrono::floor<std::chrono::seconds>(
145 std::chrono::system_clock::now())};
147 std::span<const std::byte> alpn_wire{};
148 };
149
164 public:
168 Session() noexcept;
169
174 Session(Session&& other) noexcept;
175
179 ~Session() noexcept;
180
186 Session& operator=(Session&& other) noexcept;
187
188 Session(const Session&) = delete;
189 Session& operator=(const Session&) = delete;
190
198
206
213 StormByte::Expected<std::size_t, SessionError> FeedEncrypted(std::span<const std::byte> encrypted);
214
220 StormByte::Expected<std::size_t, SessionError> DrainEncrypted(std::span<std::byte> output);
221
227 StormByte::Expected<std::size_t, SessionError> WritePlaintext(std::span<const std::byte> plaintext);
228
234 StormByte::Expected<std::size_t, SessionError> ReadPlaintext(std::span<std::byte> output);
235
241
246 State Status() const noexcept;
247
252 SessionError Failure() const noexcept;
253
260 std::string_view FailureDetail() const noexcept;
261
266 bool HandshakeComplete() const noexcept;
267
273 std::string_view NegotiatedALPN() const noexcept;
274
278 static constexpr std::size_t MaxInputChunk = 64 * 1024;
279
283 static constexpr std::size_t MaxPendingCiphertext = 1024 * 1024;
284
285 private:
286 struct Impl;
287
288 explicit Session(std::unique_ptr<Impl> impl) noexcept;
289 std::unique_ptr<Impl> m_impl;
290 };
291}
StormByte::Expected< std::size_t, SessionError > WritePlaintext(std::span< const std::byte > plaintext)
Encrypt caller plaintext after successful handshake validation.
static constexpr std::size_t MaxInputChunk
Maximum ciphertext accepted by one FeedEncrypted call.
Definition session.hxx:278
std::string_view FailureDetail() const noexcept
Read the first fatal failure's explanation without logging or allocation.
SessionError Failure() const noexcept
Read the sticky fatal failure, if any.
Session() noexcept
Construct a failed, empty session.
StormByte::Expected< std::size_t, SessionError > ReadPlaintext(std::span< std::byte > output)
Decrypt available application bytes into the caller's buffer.
std::string_view NegotiatedALPN() const noexcept
Read the negotiated application protocol.
static StormByte::Expected< Session, SessionError > CreateClient(const ClientConfiguration &configuration)
Create a client with explicit identity, trust, time and TLS policy.
bool HandshakeComplete() const noexcept
Test whether the TLS handshake finished successfully.
StormByte::Expected< std::size_t, SessionError > FeedEncrypted(std::span< const std::byte > encrypted)
Copy ciphertext into the bounded input buffer and advance TLS.
static constexpr std::size_t MaxPendingCiphertext
Maximum ciphertext retained in either internal buffer.
Definition session.hxx:283
StormByte::Expected< std::size_t, SessionError > DrainEncrypted(std::span< std::byte > output)
Copy pending TLS protocol bytes into the caller's output buffer.
State Status() const noexcept
Read the current lifecycle state.
static StormByte::Expected< Session, SessionError > CreateServer(const ServerConfiguration &configuration)
Create a server that presents the configured certificate and key.
StormByte::Expected< void, SessionError > Shutdown()
Begin or advance orderly TLS shutdown.
One supported subjectAltName entry (a DNS name or an IP address).
Definition certificate.hxx:156
TLS 1.3 policy and buffer-driven session engine.
const char * DescribeSessionError(SessionError error) noexcept
Describe a typed setup or operation failure without accessing backend state.
Role
TLS endpoint role for a stream session.
Definition session.hxx:60
@ Client
Initiates a TLS handshake and authenticates a server.
Definition session.hxx:61
@ Server
Accepts a TLS handshake and presents a configured certificate.
Definition session.hxx:62
State
Observable lifecycle of a buffer-driven TLS session.
Definition session.hxx:69
@ Closed
TLS shutdown completed.
Definition session.hxx:73
@ Closing
A local or peer close-notify is being exchanged.
Definition session.hxx:72
@ Open
The handshake completed and application data may flow.
Definition session.hxx:71
@ Failed
A fatal protocol, validation or backend error occurred.
Definition session.hxx:74
@ Handshaking
The peer handshake is not yet complete.
Definition session.hxx:70
SessionError
Typed TLS session failures.
Definition session.hxx:81
@ BackendFailure
OpenSSL failed an operation or resource allocation.
Definition session.hxx:84
@ BufferLimit
A configured internal bound would be exceeded.
Definition session.hxx:87
@ PeerRejected
Peer certificate, trust path, identity or revocation was rejected.
Definition session.hxx:85
@ InvalidState
The requested operation is invalid for this session state.
Definition session.hxx:86
@ InvalidConfiguration
Invalid role, identity, certificate, key or trust configuration.
Definition session.hxx:82
@ UnsupportedPolicy
The selected TLS policy cannot be represented by this engine.
Definition session.hxx:83
TrustSource
Source of trust anchors for a client or mutual-TLS server.
Definition session.hxx:101
@ Bundled
The versioned StormByte public server-root bundle.
Definition session.hxx:102
@ Custom
Only the explicitly supplied certificate authorities.
Definition session.hxx:103
std::chrono::sys_seconds TimePoint
Point in time with second precision, as stored in certificates.
Definition certificate.hxx:75
Root namespace of the StormByte suite.
std::conditional_t< Type::Reference< T >, std::expected< std::reference_wrapper< std::remove_reference_t< T > >, Safe::Shared< E > >, std::expected< T, Safe::Shared< E > > > Expected
STL namespace.
Borrowed construction inputs for an authenticated TLS client.
Definition session.hxx:115
bool require_revocation
Require fresh Good evidence for each non-anchor certificate.
Definition session.hxx:121
std::span< const std::byte > private_key_password
Optional password for an encrypted client key.
Definition session.hxx:125
std::span< const std::byte > certificate_chain_pem
Optional client certificate chain for mutual TLS.
Definition session.hxx:123
X509::TimePoint validation_time
Certificate/evidence validation time.
Definition session.hxx:119
Configuration policy
Validated TLS 1.3 suites, groups and signature schemes.
Definition session.hxx:126
std::span< const X509::Certificate > trust_anchors
Custom anchors, never merged with bundled roots.
Definition session.hxx:118
std::span< const std::byte > private_key_pem
Optional matching client private key.
Definition session.hxx:124
TrustSource trust_source
Trust store policy.
Definition session.hxx:117
std::span< const X509::RevocationEvidence > revocation_evidence
Borrowed DER evidence copied at construction.
Definition session.hxx:122
X509::SubjectAltName identity
Required expected DNS or binary IP SAN.
Definition session.hxx:116
std::span< const std::byte > alpn_wire
Optional length-prefixed ALPN protocol list.
Definition session.hxx:127
Mutable input with independent ordered preference lists.
Definition policy.hxx:128
Borrowed construction inputs for a TLS server.
Definition session.hxx:138
std::span< const std::byte > private_key_pem
PEM private key matching the leaf certificate.
Definition session.hxx:140
std::span< const std::byte > certificate_chain_pem
PEM leaf and optional intermediate certificates.
Definition session.hxx:139
bool require_client_certificate
Require and validate a client certificate.
Definition session.hxx:142
Configuration policy
Validated TLS 1.3 suites, groups and signature schemes.
Definition session.hxx:146
std::span< const X509::Certificate > client_trust_anchors
Exclusive custom client CA anchors for mTLS.
Definition session.hxx:143
X509::TimePoint validation_time
Client certificate validation time.
Definition session.hxx:144
std::span< const std::byte > alpn_wire
Optional length-prefixed server protocol preference list.
Definition session.hxx:147
std::span< const std::byte > private_key_password
Optional PEM key password.
Definition session.hxx:141
#define STORMBYTE_CRYPTO_PUBLIC
Definition visibility.h:53