Crypto

Cryptographic hashing and HMAC, digital signatures, authenticated encryption, random bytes, constant-time comparison, and Base64 and UUID helpers. More...

Classes
struct	sourcemeta::core::AESCBCHMACCiphertext
struct	sourcemeta::core::AESGCMCiphertext
struct	sourcemeta::core::SecureStringScope
struct	sourcemeta::core::SecureAllocator< T >
class	sourcemeta::core::SecureString
class	sourcemeta::core::PrivateKey
class	sourcemeta::core::PublicKey
struct	sourcemeta::core::RSAPublicComponents
struct	sourcemeta::core::ECPublicComponents
struct	sourcemeta::core::EdwardsPublicComponents

Enumerations
enum class	sourcemeta::core::RSAOAEPHash : std::uint8_t { RSAOAEPHash::SHA1 , RSAOAEPHash::SHA256 }
enum class	sourcemeta::core::SignatureHashFunction : std::uint8_t { SignatureHashFunction::SHA256 , SignatureHashFunction::SHA384 , SignatureHashFunction::SHA512 }
enum class	sourcemeta::core::EllipticCurve : std::uint8_t { EllipticCurve::P256 , EllipticCurve::P384 , EllipticCurve::P521 }
enum class	sourcemeta::core::EdwardsCurve : std::uint8_t { EdwardsCurve::Ed25519 , EdwardsCurve::Ed448 }

Functions
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::random_bytes (std::span< std::uint8_t > buffer) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::random_bytes (const std::size_t length) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::secure_equals (const std::string_view left, const std::string_view right) noexcept -> bool
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_cbc_hmac_encrypt (const std::string_view key, const std::string_view iv, const std::string_view associated_data, const std::string_view plaintext) -> std::optional< AESCBCHMACCiphertext >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_cbc_hmac_decrypt (const std::string_view key, const std::string_view iv, const std::string_view associated_data, const std::string_view ciphertext, const std::string_view tag) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_gcm_encrypt (const std::string_view key, const std::string_view iv, const std::string_view associated_data, const std::string_view plaintext) -> std::optional< AESGCMCiphertext >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_gcm_decrypt (const std::string_view key, const std::string_view iv, const std::string_view associated_data, const std::string_view ciphertext, const std::string_view tag) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_256_gcm_seal (const std::string_view key, const std::string_view plaintext) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_256_gcm_unseal (const std::string_view key, const std::string_view sealed) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_key_wrap (const std::string_view key_encryption_key, const std::string_view key) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::aes_key_unwrap (const std::string_view key_encryption_key, const std::string_view wrapped_key) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64_encode (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64_encode (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64_encode (const std::string_view input, SecureString &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64_decode (const std::string_view input) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64_decode (const std::string_view input, SecureString &output) -> bool
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64url_encode (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64url_encode (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64url_encode (std::span< const std::uint8_t > input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64url_encode (const std::string_view input, SecureString &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::base64url_decode (const std::string_view input) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::crc32 (const std::string_view input) -> std::uint32_t
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::crc32_update (const std::uint32_t previous, const std::string_view input) -> std::uint32_t
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::ecdh_derive (const PrivateKey &private_key, const PublicKey &public_key) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::kdf_concat (const std::string_view shared_secret, const std::string_view algorithm_id, const std::string_view party_u_info, const std::string_view party_v_info, const std::size_t derived_key_bytes) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::fnv128_digest (const std::string_view input) -> std::array< std::uint8_t, 16 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::fnv128 (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::fnv128 (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha256 (const std::string_view key, const std::string_view message, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha256 (const std::string_view key, const std::string_view message) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha256_digest (const std::string_view key, const std::string_view message) -> std::array< std::uint8_t, 32 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha256_digest (const std::string_view key, std::span< const std::string_view > message) -> std::array< std::uint8_t, 32 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha384 (const std::string_view key, const std::string_view message, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha384 (const std::string_view key, const std::string_view message) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha384_digest (const std::string_view key, const std::string_view message) -> std::array< std::uint8_t, 48 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha512 (const std::string_view key, const std::string_view message, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha512 (const std::string_view key, const std::string_view message) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::hmac_sha512_digest (const std::string_view key, const std::string_view message) -> std::array< std::uint8_t, 64 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsa_oaep_encrypt (const PublicKey &key, const RSAOAEPHash hash, const std::string_view plaintext) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsa_oaep_decrypt (const PrivateKey &key, const RSAOAEPHash hash, const std::string_view ciphertext) -> std::optional< std::string >
auto	sourcemeta::core::secure_zero (void *const data, const std::size_t size) noexcept -> void
auto	sourcemeta::core::secure_zero (std::string &value) noexcept -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha1 (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha1 (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha256 (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha256 (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha256_digest (const std::string_view input) -> std::array< std::uint8_t, 32 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha256_digest (std::span< const std::string_view > input) -> std::array< std::uint8_t, 32 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha384 (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha384 (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha384_digest (const std::string_view input) -> std::array< std::uint8_t, 48 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha512 (const std::string_view input, std::ostream &output) -> void
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha512 (const std::string_view input) -> std::string
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::sha512_digest (const std::string_view input) -> std::array< std::uint8_t, 64 >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_private_key (const std::string_view pem) -> std::optional< PrivateKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_ec_private_key (const EllipticCurve curve, const std::string_view scalar, const std::string_view coordinate_x, const std::string_view coordinate_y) -> std::optional< PrivateKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::generate_ec_private_key (const EllipticCurve curve) -> std::optional< PrivateKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_edwards_private_key (const EdwardsCurve curve, const std::string_view seed) -> std::optional< PrivateKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_rsa_private_key (const std::string_view modulus, const std::string_view public_exponent, const std::string_view private_exponent, const std::string_view prime1, const std::string_view prime2, const std::string_view exponent1, const std::string_view exponent2, const std::string_view coefficient) -> std::optional< PrivateKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::derive_public_key (const PrivateKey &key) -> std::optional< PublicKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsassa_pkcs1_v15_sign (const PrivateKey &key, const SignatureHashFunction hash, const std::string_view message) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsassa_pss_sign (const PrivateKey &key, const SignatureHashFunction hash, const std::string_view message) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::ecdsa_sign (const PrivateKey &key, const SignatureHashFunction hash, const std::string_view message) -> std::optional< std::string >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::eddsa_sign (const PrivateKey &key, const std::string_view message) -> std::optional< std::string >
SOURCEMETA_CORE_CRYPTO_EXPORT auto	sourcemeta::core::uuidv4 () -> std::string
SOURCEMETA_CORE_CRYPTO_EXPORT auto	sourcemeta::core::is_uuid_like (const std::string_view value) -> bool
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_rsa_public_key (const std::string_view modulus, const std::string_view exponent) -> std::optional< PublicKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_ec_public_key (const EllipticCurve curve, const std::string_view coordinate_x, const std::string_view coordinate_y) -> std::optional< PublicKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::make_eddsa_public_key (const EdwardsCurve curve, const std::string_view public_key) -> std::optional< PublicKey >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsa_public_components (const PublicKey &key) -> std::optional< RSAPublicComponents >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::ec_public_components (const PublicKey &key) -> std::optional< ECPublicComponents >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::edwards_public_components (const PublicKey &key) -> std::optional< EdwardsPublicComponents >
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsassa_pkcs1_v15_verify (const PublicKey &key, const SignatureHashFunction hash, const std::string_view message, const std::string_view signature) -> bool
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::rsassa_pss_verify (const PublicKey &key, const SignatureHashFunction hash, const std::string_view message, const std::string_view signature) -> bool
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::ecdsa_verify (const PublicKey &key, const SignatureHashFunction hash, const std::string_view message, const std::string_view signature) -> bool
auto SOURCEMETA_CORE_CRYPTO_EXPORT	sourcemeta::core::eddsa_verify (const PublicKey &key, const std::string_view message, const std::string_view signature) -> bool

Detailed Description

Cryptographic hashing and HMAC, digital signatures, authenticated encryption, random bytes, constant-time comparison, and Base64 and UUID helpers.

This functionality is included as follows:

#include <sourcemeta/core/crypto.h>

---

Class Documentation

sourcemeta::core::AESCBCHMACCiphertext

struct sourcemeta::core::AESCBCHMACCiphertext

The output of an AES-CBC-HMAC encryption, a single owned buffer holding the ciphertext followed by its authentication tag, exposed as views.

Public Member Functions
auto	ciphertext () const -> std::string_view
	The ciphertext, a whole number of 16-byte blocks.
auto	tag () const -> std::string_view
	The authentication tag.
Public Attributes
std::string	data
	The ciphertext followed by its authentication tag.
std::string::size_type	tag_length
	The length in bytes of the trailing authentication tag.

sourcemeta::core::AESGCMCiphertext

struct sourcemeta::core::AESGCMCiphertext

The output of an AES-GCM encryption, a single owned buffer holding the ciphertext followed by its 16-byte authentication tag, exposed as views.

Public Member Functions
auto	ciphertext () const -> std::string_view
	The ciphertext, the same length as the plaintext.
auto	tag () const -> std::string_view
	The 16-byte authentication tag.
Public Attributes
std::string	data
	The ciphertext followed by its 16-byte authentication tag.

sourcemeta::core::SecureStringScope

struct sourcemeta::core::SecureStringScope

Overwrite the referenced string when leaving the current scope, so secret material a local holds is wiped across every return path without threading a manual call through each one. It clears only the live bytes the string owns at scope exit, so a reassignment, an in-place shrink, or a growth that reallocates before then can still leave earlier bytes in freed memory or in the capacity beyond the final length, a residual that only a wiping allocator closes. Prefer a wiping string for secrets that change size. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
#include <string>
 
std::string secret{"hunter2"};
{
  const sourcemeta::core::SecureStringScope scope{secret};
}
assert(secret == std::string(7, '\x00'));

Public Member Functions
	SecureStringScope (std::string &value) noexcept
	Capture the string to wipe when leaving the current scope.
	SecureStringScope (const SecureStringScope &)=delete
	SecureStringScope (SecureStringScope &&)=delete
Public Attributes
std::string &	target
	The captured string, whose storage is wiped at scope exit.

sourcemeta::core::SecureAllocator

struct sourcemeta::core::SecureAllocator

template<typename T>
struct sourcemeta::core::SecureAllocator< T >

A standard allocator that wipes every block it owns before releasing it, so a secret the storage held does not survive in freed memory. The deallocation covers the whole block, so a reallocation, a reassignment, or the destruction of the owner all clear the earlier bytes, closing the residue that the scope-based cleanup above cannot reach on its own. For example:

#include <sourcemeta/core/crypto.h>
#include <vector>
 
std::vector<char, sourcemeta::core::SecureAllocator<char>> secret;
secret.push_back('x');

Public Member Functions
	SecureAllocator () noexcept=default
	Construct an allocator, which holds no state of its own.
template<typename Other>
constexpr	SecureAllocator (const SecureAllocator< Other > &) noexcept
	Construct from an allocator for another type, as the containers require.
auto	allocate (const std::size_t count) -> T *
	Allocate storage for the given number of objects.
auto	deallocate (T *const pointer, const std::size_t count) noexcept -> void
	Wipe and release the storage of the given number of objects.

sourcemeta::core::SecureString

class sourcemeta::core::SecureString

A string whose bytes always live in heap storage that is wiped whenever it is released, so a secret it holds never reaches freed memory when the string reallocates on growth, is reassigned, or is destroyed, and never lingers in an inline buffer. Bytes abandoned by an in-place shrink stay in the still owned block only until that block is next reallocated or freed, when they too are wiped. For example:

#include <sourcemeta/core/crypto.h>
 
sourcemeta::core::SecureString secret{"hunter2"};
secret.append("!");

Public Member Functions
	SecureString ()=default
	Construct an empty string.
	SecureString (const std::string_view value)
	Construct from a view of bytes.
	SecureString (const char *const data, const size_type length)
	Construct from a pointer and a length.
	SecureString (const size_type count, const char value)
	Construct a run of a repeated byte.
auto	size () const noexcept -> size_type
	The number of bytes held.
auto	empty () const noexcept -> bool
	Whether no bytes are held.
auto	reserve (const size_type capacity) -> void
	Reserve storage for at least the given number of bytes.
auto	capacity () const noexcept -> size_type
	The number of bytes that can be held before growing the storage.
auto	resize (const size_type count, const char value) -> void
auto	push_back (const char value) -> void
	Append a single byte.
auto	append (const std::string_view value) -> void
	Append a view of bytes.
auto	append (const size_type count, const char value) -> void
	Append a run of a repeated byte.
auto	front () const noexcept -> char
	The first byte.
auto	back () const noexcept -> char
	The last byte.
auto	data () const noexcept -> const char *
	A pointer to the held bytes, valid until the next mutation.

Member Function Documentation

resize()

auto sourcemeta::core::SecureString::resize ( const size_type count, const char value ) -> void

inline

Resize to the given number of bytes, padding new ones with the given value.

sourcemeta::core::PrivateKey

class sourcemeta::core::PrivateKey

A parsed private key that holds the native key, so that the same key can produce many signatures without paying the key construction cost on every call. Build it once with the factory function and pass it to the matching signing function. The signing counterpart to PublicKey. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_private_key(pem)};
assert(key.has_value());
const auto signature{sourcemeta::core::rsassa_pkcs1_v15_sign(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, message)};
assert(signature.has_value());

Public Types
enum class	Type : std::uint8_t { RSA , EllipticCurve , Edwards }
	The kind of key, which fixes the signature schemes it can produce. More...
Public Member Functions
	PrivateKey (PrivateKey &&other) noexcept
	Move constructor.
	PrivateKey (const PrivateKey &)=delete
auto	type () const noexcept -> Type
	The kind of key this is.
	PrivateKey (Internal *internal) noexcept
	Take ownership of a parsed key. Prefer the factory function below.
auto	internal () const noexcept -> const Internal *

Member Enumeration Documentation

Type

enum class sourcemeta::core::PrivateKey::Type : std::uint8_t

strong

The kind of key, which fixes the signature schemes it can produce.

Enumerator
RSA	The RSA key type.
EllipticCurve	The elliptic-curve key type.
Edwards	The Edwards-curve key type.

Member Function Documentation

internal()

auto sourcemeta::core::PrivateKey::internal ( ) const -> const Internal *

inlinenodiscardnoexcept

Access the parsed key, which the signing functions read. The type is opaque, so there is nothing a caller can do with it

sourcemeta::core::PublicKey

class sourcemeta::core::PublicKey

A parsed public key that holds the native key, so that the same key can verify many signatures without paying the key construction cost on every call. Build it once with one of the factory functions and pass it to the matching verification function. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_rsa_public_key(modulus, exponent)};
assert(key.has_value());
assert(sourcemeta::core::rsassa_pkcs1_v15_verify(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, message,
    signature));

Public Types
enum class	Type : std::uint8_t { RSA , EllipticCurve , Edwards }
	The kind of key, which fixes the signature schemes it can verify. More...
Public Member Functions
	PublicKey (PublicKey &&other) noexcept
	Move constructor.
	PublicKey (const PublicKey &)=delete
auto	type () const noexcept -> Type
	The kind of key this is.
	PublicKey (Internal *internal) noexcept
	Take ownership of a parsed key. Prefer the factory functions below.
auto	internal () const noexcept -> const Internal *

Member Enumeration Documentation

Type

enum class sourcemeta::core::PublicKey::Type : std::uint8_t

strong

The kind of key, which fixes the signature schemes it can verify.

Enumerator
RSA	The RSA key type.
EllipticCurve	The elliptic-curve key type.
Edwards	The Edwards-curve key type.

Member Function Documentation

internal()

auto sourcemeta::core::PublicKey::internal ( ) const -> const Internal *

inlinenodiscardnoexcept

Access the parsed key, which the verification functions read. The type is opaque, so there is nothing a caller can do with it

sourcemeta::core::RSAPublicComponents

struct sourcemeta::core::RSAPublicComponents

The public components of an RSA key, as raw big-endian bytes in minimal form.

Public Attributes
std::string	modulus
	The RSA modulus.
std::string	exponent
	The RSA public exponent.

sourcemeta::core::ECPublicComponents

struct sourcemeta::core::ECPublicComponents

The public coordinates of an elliptic curve key, each padded to the curve field width, together with the curve they belong to.

Public Attributes
EllipticCurve	curve
	The curve the coordinates belong to.
std::string	x
	The x coordinate.
std::string	y
	The y coordinate.

sourcemeta::core::EdwardsPublicComponents

struct sourcemeta::core::EdwardsPublicComponents

The public point of an Edwards-curve key, together with the curve it belongs to.

Public Attributes
EdwardsCurve	curve
	The curve the point belongs to.
std::string	point
	The encoded public point.

Enumeration Type Documentation

EdwardsCurve

enum class sourcemeta::core::EdwardsCurve : std::uint8_t

strong

The Edwards curves supported by signature verification.

Enumerator
Ed25519	The Ed25519 Edwards curve.
Ed448	The Ed448 Edwards curve.

EllipticCurve

enum class sourcemeta::core::EllipticCurve : std::uint8_t

strong

The NIST elliptic curves supported by signature verification.

Enumerator
P256	The NIST P-256 elliptic curve.
P384	The NIST P-384 elliptic curve.
P521	The NIST P-521 elliptic curve.

RSAOAEPHash

enum class sourcemeta::core::RSAOAEPHash : std::uint8_t

strong

The hash function that RSA-OAEP uses for both the label digest and the mask generation function.

Enumerator
SHA1	The SHA-1 hash function, selecting RSA-OAEP.
SHA256	The SHA-256 hash function, selecting RSA-OAEP-256.

SignatureHashFunction

enum class sourcemeta::core::SignatureHashFunction : std::uint8_t

strong

The hash functions supported by signature verification.

Enumerator
SHA256	The SHA-256 hash function.
SHA384	The SHA-384 hash function.
SHA512	The SHA-512 hash function.

Function Documentation

aes_256_gcm_seal()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_256_gcm_seal	(	const std::string_view	key,
		const std::string_view	plaintext ) -> std::optional< std::string >

Seal a plaintext under a 256-bit key using AES-256 in Galois/Counter Mode (NIST SP 800-38D) with a fresh random nonce and no associated data. The result is the self-contained sealed message, the nonce followed by the ciphertext and the authentication tag, and its confidentiality and integrity are both protected when the library is built against a system cryptography provider. Returns no value when the key is not 256 bits, the plaintext is too large to process, or the random nonce could not be drawn. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto sealed{sourcemeta::core::aes_256_gcm_seal(key, "hello")};
assert(sealed.has_value());

aes_256_gcm_unseal()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_256_gcm_unseal	(	const std::string_view	key,
		const std::string_view	sealed ) -> std::optional< std::string >

Open a message sealed with aes_256_gcm_seal under the same 256-bit key, returning the original plaintext. Returns no value when the key is not 256 bits, the input is too short to be a sealed message or too large to process, or the authentication tag does not verify, so a tampered or truncated message is rejected rather than decrypted. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto plaintext{sourcemeta::core::aes_256_gcm_unseal(key, sealed)};
assert(plaintext.has_value());

aes_cbc_hmac_decrypt()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_cbc_hmac_decrypt	(	const std::string_view	key,
		const std::string_view	iv,
		const std::string_view	associated_data,
		const std::string_view	ciphertext,
		const std::string_view	tag ) -> std::optional< std::string >

Decrypt a message produced by aes_cbc_hmac_encrypt under the same key, initialization vector, and associated data, returning the original plaintext. The authentication tag is verified in constant time before, and independent of, the decryption, so a tampered message is rejected rather than decrypted. Returns no value when the key or initialization vector is not a valid length, the tag length does not match the key, an input is malformed or too large to process, or the authentication tag does not verify. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto plaintext{sourcemeta::core::aes_cbc_hmac_decrypt(
    key, iv, "", result.value().ciphertext(), result.value().tag())};
assert(plaintext.has_value());

aes_cbc_hmac_encrypt()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_cbc_hmac_encrypt	(	const std::string_view	key,
		const std::string_view	iv,
		const std::string_view	associated_data,
		const std::string_view	plaintext ) -> std::optional< AESCBCHMACCiphertext >

Encrypt a plaintext with AES-CBC-HMAC-SHA2 (RFC 7518 Section 5.2) under a key whose size selects the variant, a 128-bit initialization vector, and associated data that is authenticated but not encrypted. A 32, 48, or 64-byte key selects A128CBC-HS256, A192CBC-HS384, or A256CBC-HS512 respectively. Returns no value when the key is not one of the three valid sizes, the initialization vector is not 128 bits, or an input is too large to process. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto result{
    sourcemeta::core::aes_cbc_hmac_encrypt(key, iv, "", "hello")};
assert(result.has_value());

aes_gcm_decrypt()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_gcm_decrypt	(	const std::string_view	key,
		const std::string_view	iv,
		const std::string_view	associated_data,
		const std::string_view	ciphertext,
		const std::string_view	tag ) -> std::optional< std::string >

Decrypt a message produced by aes_gcm_encrypt under the same key, initialization vector, and associated data, returning the original plaintext. Returns no value when the key or initialization vector is not a valid length, the tag is not 16 bytes, an input is too large to process, or the authentication tag does not verify, so a tampered message is rejected rather than decrypted. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto plaintext{sourcemeta::core::aes_gcm_decrypt(
    key, iv, "", result.value().ciphertext(), result.value().tag())};
assert(plaintext.has_value());

aes_gcm_encrypt()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_gcm_encrypt	(	const std::string_view	key,
		const std::string_view	iv,
		const std::string_view	associated_data,
		const std::string_view	plaintext ) -> std::optional< AESGCMCiphertext >

Encrypt a plaintext with AES in Galois/Counter Mode (NIST SP 800-38D) under a 128, 192, or 256-bit key, a 96-bit initialization vector, and associated data that is authenticated but not encrypted. Returns no value when the key is not one of the three valid sizes, the initialization vector is not 96 bits, or an input is too large to process. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto result{sourcemeta::core::aes_gcm_encrypt(key, iv, "", "hello")};
assert(result.has_value());

aes_key_unwrap()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_key_unwrap	(	const std::string_view	key_encryption_key,
		const std::string_view	wrapped_key ) -> std::optional< std::string >

Unwrap a key wrapped with aes_key_wrap under the same key-encryption key, returning the original key. The integrity check is verified, so a tampered or wrongly keyed input is rejected rather than returned. Returns no value when the key-encryption key is not a valid length, the wrapped key is not a whole number of at least three 64-bit blocks, an input is too large to process, or the integrity check fails. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{
    sourcemeta::core::aes_key_unwrap(key_encryption_key, wrapped.value())};
assert(key.has_value());

aes_key_wrap()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::aes_key_wrap	(	const std::string_view	key_encryption_key,
		const std::string_view	key ) -> std::optional< std::string >

Wrap a key with AES Key Wrap (RFC 3394) under a key-encryption key whose size selects AES-128, AES-192, or AES-256. The wrapped output is eight bytes longer than the input and carries an integrity check. Returns no value when the key-encryption key is not 128, 192, or 256 bits, the key being wrapped is not a whole number of at least two 64-bit blocks, or an input is too large to process. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto wrapped{sourcemeta::core::aes_key_wrap(key_encryption_key, key)};
assert(wrapped.has_value());

base64_decode() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64_decode

(

const std::string_view

input

)

-> std::optional< std::string >

Decode a Base64 string (RFC 4648 Section 4), returning no value unless the input is a canonical padded encoding. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto result{sourcemeta::core::base64_decode("Zm9vYmFy")};
assert(result.has_value());
assert(result.value() == "foobar");

base64_decode() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64_decode	(	const std::string_view	input,
		SecureString &	output ) -> bool

Decode a Base64 string (RFC 4648 Section 4) into a wiping string, for a decoded value that is secret such as a client credential, returning whether the input is a canonical padded encoding. On success the decoded bytes are appended, and on failure the output is left with its original contents, so a reused buffer never keeps a partial decode. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
sourcemeta::core::SecureString result;
assert(sourcemeta::core::base64_decode("Zm9vYmFy", result));
assert(result == "foobar");

base64_encode() [1/3]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64_encode

(

const std::string_view

input

)

-> std::string

Encode a byte sequence using Base64 (RFC 4648 Section 4). For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
assert(sourcemeta::core::base64_encode("foobar") == "Zm9vYmFy");

base64_encode() [2/3]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64_encode	(	const std::string_view	input,
		SecureString &	output ) -> void

Encode a byte sequence using Base64 (RFC 4648 Section 4), appending to a wiping string so that an encoded secret is never held in ordinary storage. The output must not alias the input. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
sourcemeta::core::SecureString result;
sourcemeta::core::base64_encode("foobar", result);
assert(result == "Zm9vYmFy");

base64_encode() [3/3]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64_encode	(	const std::string_view	input,
		std::ostream &	output ) -> void

Encode a byte sequence using Base64 (RFC 4648 Section 4) into a stream. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <cassert>
 
std::ostringstream result;
sourcemeta::core::base64_encode("foobar", result);
assert(result.str() == "Zm9vYmFy");

base64url_decode()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64url_decode

(

const std::string_view

input

)

-> std::optional< std::string >

Decode an unpadded Base64url string (RFC 4648 Section 5), returning no value unless the input is a canonical encoding. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto result{sourcemeta::core::base64url_decode("Zm8")};
assert(result.has_value());
assert(result.value() == "fo");

base64url_encode() [1/4]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64url_encode

(

const std::string_view

input

)

-> std::string

Encode a byte sequence using unpadded Base64url (RFC 4648 Section 5). For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
assert(sourcemeta::core::base64url_encode("fo") == "Zm8");

base64url_encode() [2/4]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64url_encode	(	const std::string_view	input,
		SecureString &	output ) -> void

Append the unpadded Base64url encoding (RFC 4648 Section 5) of a byte sequence to a wiping string, so that encoding a secret does not leave it in an intermediate buffer. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
sourcemeta::core::SecureString result;
sourcemeta::core::base64url_encode("fo", result);
assert(result == "Zm8");

base64url_encode() [3/4]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64url_encode	(	const std::string_view	input,
		std::ostream &	output ) -> void

Encode a byte sequence using unpadded Base64url (RFC 4648 Section 5) into a stream. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <cassert>
 
std::ostringstream result;
sourcemeta::core::base64url_encode("fo", result);
assert(result.str() == "Zm8");

base64url_encode() [4/4]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::base64url_encode

(

std::span< const std::uint8_t >

input

)

-> std::string

Encode raw bytes using unpadded Base64url (RFC 4648 Section 5), for a byte buffer such as a hash digest rather than a character string. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::sha256_digest("fo")};
assert(!sourcemeta::core::base64url_encode(digest).empty());

crc32()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::crc32

(

const std::string_view

input

)

-> std::uint32_t

Compute the CRC-32 checksum (ISO 3309, polynomial 0xEDB88320) of a byte sequence. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::crc32("123456789") << "\n";

crc32_update()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::crc32_update	(	const std::uint32_t	previous,
		const std::string_view	input ) -> std::uint32_t

Extend an existing CRC-32 checksum with additional bytes, returning the updated value. Pass zero as the previous value to start a fresh computation. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
auto checksum{sourcemeta::core::crc32_update(0, "hello")};
checksum = sourcemeta::core::crc32_update(checksum, " world");
std::cout << checksum << "\n";

derive_public_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::derive_public_key

(

const PrivateKey &

key

)

-> std::optional< PublicKey >

Derive the public key from a private key, returning no value when the public part cannot be produced. The derived key exports its components through the public component functions, so a private key parsed from a PEM document can still be rendered to a public key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_private_key(pem)};
assert(key.has_value());
const auto public_key{sourcemeta::core::derive_public_key(key.value())};
assert(public_key.has_value());

ec_public_components()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::ec_public_components

(

const PublicKey &

key

)

-> std::optional< ECPublicComponents >

Extract the public coordinates of an elliptic curve key, returning no value when the key is not an elliptic curve key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_ec_public_key(
    sourcemeta::core::EllipticCurve::P256, x, y)};
assert(key.has_value());
const auto components{sourcemeta::core::ec_public_components(key.value())};
assert(components.has_value());

ecdh_derive()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::ecdh_derive	(	const PrivateKey &	private_key,
		const PublicKey &	public_key ) -> std::optional< std::string >

Compute the raw Elliptic Curve Diffie-Hellman shared secret from a private key and a peer public key on the same curve, returning the agreed point's x coordinate as fixed-length big-endian bytes. Returns no value when the keys are not both elliptic curve keys on the same curve, or the peer point is not on the curve. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto secret{sourcemeta::core::ecdh_derive(private_key, peer_key)};
assert(secret.has_value());

ecdsa_sign()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::ecdsa_sign	(	const PrivateKey &	key,
		const SignatureHashFunction	hash,
		const std::string_view	message ) -> std::optional< std::string >

Produce an ECDSA signature (FIPS 186-4 Section 6.4) over a message. The signature is the raw concatenation of the two integers, each padded to the curve field width, as JWS mandates (RFC 7518 Section 3.4), matching what ecdsa_verify expects. Returns no value when the key is not an elliptic curve key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_private_key(pem)};
assert(key.has_value());
const auto signature{sourcemeta::core::ecdsa_sign(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, message)};
assert(signature.has_value());

ecdsa_verify()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::ecdsa_verify	(	const PublicKey &	key,
		const SignatureHashFunction	hash,
		const std::string_view	message,
		const std::string_view	signature ) -> bool

Verify an ECDSA signature (FIPS 186-4 Section 6.4) over a message with the given elliptic curve key. The signature is the raw concatenation of the two integers, each padded to the curve field width, as JWS mandates (RFC 7518 Section 3.4). The signature is invalid rather than an error if it is malformed or the key is not an elliptic curve key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_ec_public_key(
    sourcemeta::core::EllipticCurve::P256, x, y)};
assert(key.has_value());
assert(!sourcemeta::core::ecdsa_verify(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, "message",
    "signature"));

eddsa_sign()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::eddsa_sign	(	const PrivateKey &	key,
		const std::string_view	message ) -> std::optional< std::string >

Produce an EdDSA signature (RFC 8032) over a message. There is no separate hash function, as the curve fixes it. Returns no value when the key is not an Edwards curve key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_private_key(pem)};
assert(key.has_value());
const auto signature{sourcemeta::core::eddsa_sign(key.value(), message)};
assert(signature.has_value());

eddsa_verify()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::eddsa_verify	(	const PublicKey &	key,
		const std::string_view	message,
		const std::string_view	signature ) -> bool

Verify an EdDSA signature (RFC 8032) over a message with the given Edwards curve key. There is no separate hash function, as the curve fixes it. The signature is invalid rather than an error if it is malformed or the key is not an Edwards curve key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_eddsa_public_key(
    sourcemeta::core::EdwardsCurve::Ed25519, public_key)};
assert(key.has_value());
assert(!sourcemeta::core::eddsa_verify(key.value(), "message",
"signature"));

edwards_public_components()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::edwards_public_components

(

const PublicKey &

key

)

-> std::optional< EdwardsPublicComponents >

Extract the public point of an Edwards-curve key, returning no value when the key is not an Edwards-curve key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_eddsa_public_key(
    sourcemeta::core::EdwardsCurve::Ed25519, public_key)};
assert(key.has_value());
const auto components{
    sourcemeta::core::edwards_public_components(key.value())};
assert(components.has_value());

fnv128() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::fnv128

(

const std::string_view

input

)

-> std::string

Hash a string using the non-cryptographic 128-bit FNV-1 function, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::fnv128("foo bar") << "\n";

fnv128() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::fnv128	(	const std::string_view	input,
		std::ostream &	output ) -> void

Hash a string using the non-cryptographic 128-bit FNV-1 function. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::fnv128("foo bar", result);
std::cout << result.str() << "\n";

fnv128_digest()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::fnv128_digest

(

const std::string_view

input

)

-> std::array< std::uint8_t, 16 >

Hash a string using the non-cryptographic 128-bit FNV-1 function, returning the raw digest in big-endian byte order. For example:

#include <sourcemeta/core/crypto.h>
 
const auto digest{sourcemeta::core::fnv128_digest("foo bar")};
assert(digest.size() == 16);

generate_ec_private_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::generate_ec_private_key

(

const EllipticCurve

curve

)

-> std::optional< PrivateKey >

Generate a new random elliptic curve private key on the given curve, returning no value when the platform cannot produce one. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::generate_ec_private_key(
    sourcemeta::core::EllipticCurve::P256)};
assert(key.has_value());

hmac_sha256() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha256	(	const std::string_view	key,
		const std::string_view	message ) -> std::string

Authenticate a message under a key using HMAC-SHA256, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::hmac_sha256("key", "foo bar") << "\n";

hmac_sha256() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha256	(	const std::string_view	key,
		const std::string_view	message,
		std::ostream &	output ) -> void

Authenticate a message under a key using HMAC-SHA256, writing the hex digest. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::hmac_sha256("key", "foo bar", result);
std::cout << result.str() << "\n";

hmac_sha256_digest() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha256_digest	(	const std::string_view	key,
		const std::string_view	message ) -> std::array< std::uint8_t, 32 >

Authenticate a message under a key using HMAC-SHA256, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::hmac_sha256_digest("key", "foo bar")};
assert(digest.size() == 32);

hmac_sha256_digest() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha256_digest	(	const std::string_view	key,
		std::span< const std::string_view >	message ) -> std::array< std::uint8_t, 32 >

Authenticate a message given as a sequence of string parts under a key using HMAC-SHA256, as if the parts were a single concatenated message, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <array>
#include <cassert>
#include <string_view>
 
const std::array<std::string_view, 2> parts{{"foo ", "bar"}};
const auto digest{sourcemeta::core::hmac_sha256_digest("key", parts)};
assert(digest.size() == 32);

hmac_sha384() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha384	(	const std::string_view	key,
		const std::string_view	message ) -> std::string

Authenticate a message under a key using HMAC-SHA384, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::hmac_sha384("key", "foo bar") << "\n";

hmac_sha384() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha384	(	const std::string_view	key,
		const std::string_view	message,
		std::ostream &	output ) -> void

Authenticate a message under a key using HMAC-SHA384, writing the hex digest. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::hmac_sha384("key", "foo bar", result);
std::cout << result.str() << "\n";

hmac_sha384_digest()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha384_digest	(	const std::string_view	key,
		const std::string_view	message ) -> std::array< std::uint8_t, 48 >

Authenticate a message under a key using HMAC-SHA384, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::hmac_sha384_digest("key", "foo bar")};
assert(digest.size() == 48);

hmac_sha512() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha512	(	const std::string_view	key,
		const std::string_view	message ) -> std::string

Authenticate a message under a key using HMAC-SHA512, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::hmac_sha512("key", "foo bar") << "\n";

hmac_sha512() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha512	(	const std::string_view	key,
		const std::string_view	message,
		std::ostream &	output ) -> void

Authenticate a message under a key using HMAC-SHA512, writing the hex digest. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::hmac_sha512("key", "foo bar", result);
std::cout << result.str() << "\n";

hmac_sha512_digest()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::hmac_sha512_digest	(	const std::string_view	key,
		const std::string_view	message ) -> std::array< std::uint8_t, 64 >

Authenticate a message under a key using HMAC-SHA512, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::hmac_sha512_digest("key", "foo bar")};
assert(digest.size() == 64);

is_uuid_like()

SOURCEMETA_CORE_CRYPTO_EXPORT auto sourcemeta::core::is_uuid_like

(

const std::string_view

value

)

-> bool

Check whether the given string is shaped like a UUID: exactly 36 characters in the 8-4-4-4-12 hex-with-dashes layout, case-insensitive. This is a purely lexical check and does not validate the version or variant nibbles.

#include <sourcemeta/core/crypto.h>
 
#include <cassert>
 
assert(sourcemeta::core::is_uuid_like("98d80576-482e-427f-8434-7f86890ab222"));
assert(sourcemeta::core::is_uuid_like("00000000-0000-0000-0000-000000000000"));
assert(!sourcemeta::core::is_uuid_like("not-a-uuid"));

kdf_concat()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::kdf_concat	(	const std::string_view	shared_secret,
		const std::string_view	algorithm_id,
		const std::string_view	party_u_info,
		const std::string_view	party_v_info,
		const std::size_t	derived_key_bytes ) -> std::optional< std::string >

Derive a key from a shared secret with the Concat KDF (RFC 7518 Section 4.6), the single-step key derivation function over SHA-256, where the algorithm identifier and the two party information strings are the already decoded bytes that make up the derivation context. Returns no value when the context or the requested key length exceeds the 32-bit fields the construction encodes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::kdf_concat(secret, "A128GCM", "Alice",
                                            "Bob", 16)};
assert(key.has_value());
assert(key.value().size() == 16);

make_ec_private_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_ec_private_key	(	const EllipticCurve	curve,
		const std::string_view	scalar,
		const std::string_view	coordinate_x,
		const std::string_view	coordinate_y ) -> std::optional< PrivateKey >

Parse an elliptic curve private key from its raw big-endian private scalar and public point coordinates, returning no value when the material is malformed. The public coordinates are required because the platform key backends store the point alongside the scalar.

make_ec_public_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_ec_public_key	(	const EllipticCurve	curve,
		const std::string_view	coordinate_x,
		const std::string_view	coordinate_y ) -> std::optional< PublicKey >

Parse an elliptic curve public key from its raw big-endian point coordinates, returning no value when the point is malformed.

make_eddsa_public_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_eddsa_public_key	(	const EdwardsCurve	curve,
		const std::string_view	public_key ) -> std::optional< PublicKey >

Parse an Edwards-curve public key from its raw encoded point, returning no value when the key is malformed or the wrong length for the curve.

make_edwards_private_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_edwards_private_key	(	const EdwardsCurve	curve,
		const std::string_view	seed ) -> std::optional< PrivateKey >

Parse an Edwards-curve private key from its raw seed, returning no value when the seed is the wrong length for the curve.

make_private_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_private_key

(

const std::string_view

pem

)

-> std::optional< PrivateKey >

Parse a private key from an unencrypted PKCS#8 PEM document (RFC 5958), returning no value when the input is not a supported RSA, elliptic curve, or Edwards private key. Encrypted documents are not supported. An elliptic curve key must carry its public point, which is optional in SEC1 (RFC 5915), because some backends store the point alongside the private scalar.

make_rsa_private_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_rsa_private_key	(	const std::string_view	modulus,
		const std::string_view	public_exponent,
		const std::string_view	private_exponent,
		const std::string_view	prime1,
		const std::string_view	prime2,
		const std::string_view	exponent1,
		const std::string_view	exponent2,
		const std::string_view	coefficient ) -> std::optional< PrivateKey >

Parse an RSA private key from the components of its two-prime form (RFC 8017 Section 3.2), each a raw big-endian integer, in the order modulus, public exponent, private exponent, first prime, second prime, first prime exponent, second prime exponent, and coefficient. Every component is required, as the platform backends import the key from its full private structure rather than recomputing the primes. Returns no value when the material is malformed.

make_rsa_public_key()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::make_rsa_public_key	(	const std::string_view	modulus,
		const std::string_view	exponent ) -> std::optional< PublicKey >

Parse an RSA public key from its raw big-endian modulus and exponent bytes, returning no value when the material is malformed or beyond 4096 bits.

random_bytes() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::random_bytes

(

const std::size_t

length

)

-> std::string

Return the given number of random bytes as a string, drawn from the operating system's cryptographically secure provider. The same backend caveat as the buffer-filling overload applies. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto bytes{sourcemeta::core::random_bytes(32)};
assert(bytes.size() == 32);

random_bytes() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::random_bytes

(

std::span< std::uint8_t >

buffer

)

-> void

Fill a buffer with random bytes drawn from the operating system's cryptographically secure provider. The bytes are only cryptographically secure when the library is built against a system provider (OpenSSL, the Apple Security framework, or Windows CNG). The reference backend used when no system provider is available falls back to a non-cryptographic generator. For example:

#include <sourcemeta/core/crypto.h>
#include <array>
#include <cstdint>
 
std::array<std::uint8_t, 16> buffer{};
sourcemeta::core::random_bytes(buffer);

rsa_oaep_decrypt()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsa_oaep_decrypt	(	const PrivateKey &	key,
		const RSAOAEPHash	hash,
		const std::string_view	ciphertext ) -> std::optional< std::string >

Decrypt a message produced by rsa_oaep_encrypt under the matching RSA private key and hash, returning the original plaintext. Returns no value when the key is not RSA, the ciphertext is malformed, or the padding check fails. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::rsa_oaep_decrypt(
    private_key, sourcemeta::core::RSAOAEPHash::SHA256, wrapped.value())};
assert(key.has_value());

rsa_oaep_encrypt()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsa_oaep_encrypt	(	const PublicKey &	key,
		const RSAOAEPHash	hash,
		const std::string_view	plaintext ) -> std::optional< std::string >

Encrypt a short key or message with RSA-OAEP (RFC 8017) under an RSA public key, where SHA1 selects RSA-OAEP and SHA256 selects RSA-OAEP-256. Returns no value when the key is not RSA, the plaintext is too long for the modulus, or the operation fails. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto wrapped{sourcemeta::core::rsa_oaep_encrypt(
    public_key, sourcemeta::core::RSAOAEPHash::SHA256, key)};
assert(wrapped.has_value());

rsa_public_components()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsa_public_components

(

const PublicKey &

key

)

-> std::optional< RSAPublicComponents >

Extract the public components of an RSA key, returning no value when the key is not an RSA key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_rsa_public_key(modulus, exponent)};
assert(key.has_value());
const auto components{sourcemeta::core::rsa_public_components(key.value())};
assert(components.has_value());

rsassa_pkcs1_v15_sign()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsassa_pkcs1_v15_sign	(	const PrivateKey &	key,
		const SignatureHashFunction	hash,
		const std::string_view	message ) -> std::optional< std::string >

Produce an RSASSA-PKCS1-v1_5 signature (RFC 8017 Section 8.2.1) over a message, returning no value when the key is not an RSA key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_private_key(pem)};
assert(key.has_value());
const auto signature{sourcemeta::core::rsassa_pkcs1_v15_sign(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, message)};
assert(signature.has_value());

rsassa_pkcs1_v15_verify()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsassa_pkcs1_v15_verify	(	const PublicKey &	key,
		const SignatureHashFunction	hash,
		const std::string_view	message,
		const std::string_view	signature ) -> bool

Verify an RSASSA-PKCS1-v1_5 signature (RFC 8017 Section 8.2.2) over a message with the given RSA key. The signature is invalid rather than an error if it is malformed or the key is not an RSA key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_rsa_public_key(modulus, exponent)};
assert(key.has_value());
assert(!sourcemeta::core::rsassa_pkcs1_v15_verify(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, "message",
    "signature"));

rsassa_pss_sign()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsassa_pss_sign	(	const PrivateKey &	key,
		const SignatureHashFunction	hash,
		const std::string_view	message ) -> std::optional< std::string >

Produce an RSASSA-PSS signature (RFC 8017 Section 8.1.1) over a message, with the salt length fixed to the hash function output as RFC 7518 Section 3.5 requires. Returns no value when the key is not an RSA key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_private_key(pem)};
assert(key.has_value());
const auto signature{sourcemeta::core::rsassa_pss_sign(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, message)};
assert(signature.has_value());

rsassa_pss_verify()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::rsassa_pss_verify	(	const PublicKey &	key,
		const SignatureHashFunction	hash,
		const std::string_view	message,
		const std::string_view	signature ) -> bool

Verify an RSASSA-PSS signature (RFC 8017 Section 8.1.2) over a message with the given RSA key. The salt is expected to be as long as the hash function output, as RFC 7518 requires, and signatures carrying any other salt length are invalid, as are signatures verified against a non-RSA key. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto key{sourcemeta::core::make_rsa_public_key(modulus, exponent)};
assert(key.has_value());
assert(!sourcemeta::core::rsassa_pss_verify(
    key.value(), sourcemeta::core::SignatureHashFunction::SHA256, "message",
    "signature"));

secure_equals()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::secure_equals ( const std::string_view left, const std::string_view right ) -> bool

noexcept

Compare two byte sequences for equality in constant time when their lengths match, returning false immediately when the lengths differ. The comparison does not short-circuit on the first differing byte, so it does not leak the position of a mismatch through timing. The length of the inputs is not treated as secret. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
assert(sourcemeta::core::secure_equals("expected", "expected"));
assert(!sourcemeta::core::secure_equals("expected", "actual"));

secure_zero() [1/2]

auto sourcemeta::core::secure_zero ( std::string & value ) -> void

inlinenoexcept

Overwrite the storage a string owns with zeroes, so a secret it held does not linger in memory. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
#include <string>
 
std::string secret{"hunter2"};
sourcemeta::core::secure_zero(secret);
assert(secret == std::string(7, '\x00'));

secure_zero() [2/2]

auto sourcemeta::core::secure_zero ( void *const data, const std::size_t size ) -> void

inlinenoexcept

Overwrite a buffer that held secret material with zeroes, so it does not linger in memory after it is no longer needed. The write goes through a volatile access, so the compiler does not elide it as a dead store. For example:

#include <sourcemeta/core/crypto.h>
#include <array>
#include <cstdint>
 
std::array<std::uint8_t, 4> buffer{{1, 2, 3, 4}};
sourcemeta::core::secure_zero(buffer.data(), buffer.size());

sha1() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha1

(

const std::string_view

input

)

-> std::string

Hash a string using SHA-1 (RFC 3174), returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::sha1("foo bar") << "\n";

sha1() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha1	(	const std::string_view	input,
		std::ostream &	output ) -> void

Hash a string using SHA-1 (RFC 3174). For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::sha1("foo bar", result);
std::cout << result.str() << "\n";

sha256() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha256

(

const std::string_view

input

)

-> std::string

Hash a string using SHA-256, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::sha256("foo bar") << "\n";

sha256() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha256	(	const std::string_view	input,
		std::ostream &	output ) -> void

Hash a string using SHA-256. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::sha256("foo bar", result);
std::cout << result.str() << "\n";

sha256_digest() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha256_digest

(

const std::string_view

input

)

-> std::array< std::uint8_t, 32 >

Hash a string using SHA-256, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::sha256_digest("foo bar")};
assert(digest.size() == 32);

sha256_digest() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha256_digest

(

std::span< const std::string_view >

input

)

-> std::array< std::uint8_t, 32 >

Hash a sequence of string parts using SHA-256 as if they were a single concatenated input, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <array>
#include <cassert>
#include <string_view>
 
const std::array<std::string_view, 2> parts{{"foo ", "bar"}};
const auto digest{sourcemeta::core::sha256_digest(parts)};
assert(digest.size() == 32);

sha384() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha384

(

const std::string_view

input

)

-> std::string

Hash a string using SHA-384, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::sha384("foo bar") << "\n";

sha384() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha384	(	const std::string_view	input,
		std::ostream &	output ) -> void

Hash a string using SHA-384. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::sha384("foo bar", result);
std::cout << result.str() << "\n";

sha384_digest()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha384_digest

(

const std::string_view

input

)

-> std::array< std::uint8_t, 48 >

Hash a string using SHA-384, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::sha384_digest("foo bar")};
assert(digest.size() == 48);

sha512() [1/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha512

(

const std::string_view

input

)

-> std::string

Hash a string using SHA-512, returning the hex digest as a string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::sha512("foo bar") << "\n";

sha512() [2/2]

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha512	(	const std::string_view	input,
		std::ostream &	output ) -> void

Hash a string using SHA-512. For example:

#include <sourcemeta/core/crypto.h>
#include <sstream>
#include <iostream>
 
std::ostringstream result;
sourcemeta::core::sha512("foo bar", result);
std::cout << result.str() << "\n";

sha512_digest()

auto SOURCEMETA_CORE_CRYPTO_EXPORT sourcemeta::core::sha512_digest

(

const std::string_view

input

)

-> std::array< std::uint8_t, 64 >

Hash a string using SHA-512, returning the raw digest bytes. For example:

#include <sourcemeta/core/crypto.h>
#include <cassert>
 
const auto digest{sourcemeta::core::sha512_digest("foo bar")};
assert(digest.size() == 64);

uuidv4()

SOURCEMETA_CORE_CRYPTO_EXPORT auto sourcemeta::core::uuidv4

(

)

-> std::string

Generate a random UUID v4 string. For example:

#include <sourcemeta/core/crypto.h>
#include <iostream>
 
std::cout << sourcemeta::core::uuidv4() << "\n";

See https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-4