StormByte-Crypto 3.1.0
C++26 cryptography module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Crypto::AEAD Namespace Reference

Classes

struct  Sealed
 Detached public ciphertext and full-length authentication tag. More...

Typedefs

using ExpectedSealed = StormByte::Expected<Sealed, Error>
using ExpectedPlaintext = StormByte::Expected<StormByte::Safe::SecureBinary, Error>

Enumerations

enum class  Algorithm { AES128GCM , AES256GCM }
 Supported raw-key authenticated encryption algorithms. More...
enum class  Error {
  UnsupportedAlgorithm , InvalidKeySize , InvalidNonceSize , InvalidTagSize ,
  InputTooLong , AuthenticationFailed , BackendFailure
}
 Typed validation, authentication and backend failures. More...

Functions

ExpectedSealed Seal (Algorithm algorithm, const Secure::Password &key, std::span< const std::byte > nonce, std::span< const std::byte > plaintext, std::span< const std::byte > aad={})
 Encrypt binary plaintext with a raw AES key and detached full tag.
ExpectedPlaintext Open (Algorithm algorithm, const Secure::Password &key, std::span< const std::byte > nonce, std::span< const std::byte > ciphertext, std::span< const std::byte > tag, std::span< const std::byte > aad={})
 Authenticate the entire ciphertext before returning any plaintext.

Variables

constexpr std::size_t NonceSize = 12
 Only 96-bit nonces are accepted.
constexpr std::size_t TagSize = 16
 Only full 128-bit tags are accepted.
constexpr std::uint64_t MaxMessageSize = (std::uint64_t{1} << 36) - 32
 GCM byte limit.
constexpr std::uint64_t MaxAADSize = (std::uint64_t{1} << 61) - 1
 GCM AAD byte limit.

Typedef Documentation

◆ ExpectedPlaintext

◆ ExpectedSealed

Enumeration Type Documentation

◆ Algorithm

Supported raw-key authenticated encryption algorithms.

Enumerator
AES128GCM 

AES-GCM with an exactly 16-byte key.

AES256GCM 

AES-GCM with an exactly 32-byte key.

◆ Error

enum class StormByte::Crypto::AEAD::Error
strong

Typed validation, authentication and backend failures.

Enumerator
UnsupportedAlgorithm 
InvalidKeySize 
InvalidNonceSize 
InvalidTagSize 
InputTooLong 
AuthenticationFailed 
BackendFailure 

Function Documentation

◆ Open()

ExpectedPlaintext StormByte::Crypto::AEAD::Open ( Algorithm algorithm,
const Secure::Password & key,
std::span< const std::byte > nonce,
std::span< const std::byte > ciphertext,
std::span< const std::byte > tag,
std::span< const std::byte > aad = {} )

Authenticate the entire ciphertext before returning any plaintext.

Parameters
algorithmAES128GCM or AES256GCM.
keyImmutable wiped raw key storage.
nonceBorrowed exactly 12-byte nonce.
ciphertextBorrowed binary ciphertext, possibly empty.
tagBorrowed exactly 16-byte authentication tag.
aadBorrowed binary additional authenticated data, possibly empty.
Returns
Independently owned wiped plaintext bytes or a typed error; never partial plaintext.
Note
A same-length wrong key, nonce, tag, ciphertext or AAD produces AuthenticationFailed. Private tentative plaintext is wiped on failure. SecureBinary copies own independent buffers. Borrowed views and copies into plain Binary are the caller's responsibility. No Crypto++ types escape.

◆ Seal()

ExpectedSealed StormByte::Crypto::AEAD::Seal ( Algorithm algorithm,
const Secure::Password & key,
std::span< const std::byte > nonce,
std::span< const std::byte > plaintext,
std::span< const std::byte > aad = {} )

Encrypt binary plaintext with a raw AES key and detached full tag.

Parameters
algorithmAES128GCM or AES256GCM.
keyImmutable wiped raw key storage, not a password to derive.
nonceBorrowed exactly 12-byte nonce.
plaintextBorrowed binary plaintext, possibly empty.
aadBorrowed binary additional authenticated data, possibly empty.
Returns
Ciphertext of exactly plaintext length and a 16-byte tag, or a typed error.
Note
The caller MUST ensure nonce uniqueness for each key, across all calls and processes. This API generates no nonce, salt, envelope or TLS record. Borrowed inputs are copied/consumed synchronously and are never wiped.

Variable Documentation

◆ MaxAADSize

std::uint64_t StormByte::Crypto::AEAD::MaxAADSize = (std::uint64_t{1} << 61) - 1
inlineconstexpr

GCM AAD byte limit.

◆ MaxMessageSize

std::uint64_t StormByte::Crypto::AEAD::MaxMessageSize = (std::uint64_t{1} << 36) - 32
inlineconstexpr

GCM byte limit.

◆ NonceSize

std::size_t StormByte::Crypto::AEAD::NonceSize = 12
inlineconstexpr

Only 96-bit nonces are accepted.

◆ TagSize

std::size_t StormByte::Crypto::AEAD::TagSize = 16
inlineconstexpr

Only full 128-bit tags are accepted.