Crypto module

crypto

Cryptographic primitives, key helpers, and certificate utilities backed by OpenSSL.

crypto

Cryptographic primitives, key helpers, and certificate utilities backed by OpenSSL.

Classes

Name	Description
`Cipher`	Provides symmetric algorithms for encryption and decryption. The algorithms that are available depend on the particular version of OpenSSL that is installed.
`Hash`	Incremental cryptographic hash engine wrapping OpenSSL EVP digest functions.
`X509Certificate`	RAII wrapper for an OpenSSL X509 certificate with PEM loading and inspection.

Typedefs

Return	Name	Description
`std::unique_ptr< EVP_CIPHER_CTX, decltype(&EVP_CIPHER_CTX_free)>`	`EvpCipherCtxPtr`	Owning OpenSSL cipher context handle with automatic `EVP_CIPHER_CTX_free`.
`std::vector< unsigned char >`	`ByteVec`	Generic storage container for storing cryptographic binary data.
`std::unique_ptr< EVP_MD_CTX, decltype(&EVP_MD_CTX_free)>`	`EvpMdCtxPtr`	Owning OpenSSL digest context handle with automatic `EVP_MD_CTX_free`.
`::RSA`	`RSAKey`	Alias for the OpenSSL RSA key type, brought into the icy::crypto namespace.
`std::unique_ptr< X509, decltype(&X509_free)>`	`X509Ptr`	RAII pointer alias for OpenSSL `X509*` values.

EvpCipherCtxPtr

std::unique_ptr< EVP_CIPHER_CTX, decltype(&EVP_CIPHER_CTX_free)> EvpCipherCtxPtr()

Owning OpenSSL cipher context handle with automatic EVP_CIPHER_CTX_free.

ByteVec

std::vector< unsigned char > ByteVec()

Generic storage container for storing cryptographic binary data.

EvpMdCtxPtr

std::unique_ptr< EVP_MD_CTX, decltype(&EVP_MD_CTX_free)> EvpMdCtxPtr()

Owning OpenSSL digest context handle with automatic EVP_MD_CTX_free.

RSAKey

::RSA RSAKey()

Alias for the OpenSSL RSA key type, brought into the icy::crypto namespace.

Currently a transparent alias for the OpenSSL RSA struct. Use OpenSSL RSA_* functions directly to create, populate, and free RSAKey objects. This alias exists as a stable forward-declaration point; a higher-level RAII wrapper may replace it in a future version.

X509Ptr

std::unique_ptr< X509, decltype(&X509_free)> X509Ptr()

RAII pointer alias for OpenSSL X509* values.

Functions

Return	Name	Description
`std::string`	`encryptString`	Encrypts a string using the specified cipher, key, and IV in a single call.
`std::string`	`decryptString`	Decrypts a string using the specified cipher, key, and IV in a single call.
`void`	`initializeEngine`	Initialize the Crypto library, as well as the underlying OpenSSL libraries.
`void`	`uninitializeEngine`	Uninitializes the Crypto library.
`std::string`	`hash` `inline`	Computes a hex-encoded digest of a string in a single call.
`std::string`	`hash` `inline`	Computes a hex-encoded digest of a raw buffer in a single call.
`std::string`	`checksum` `inline`	Computes the hex-encoded checksum of a file using the given algorithm.
`std::string`	`computeHMAC`	Computes an HMAC-SHA1 message authentication code.

encryptString

template<typename K, typename I> std::string encryptString(const std::string & algorithm, const std::string & data, const K & key, const I & iv, Cipher::Encoding encoding)

Encrypts a string using the specified cipher, key, and IV in a single call.

Constructs a Cipher, optionally applies key and iv (skipped when empty), then delegates to Cipher::encryptString().

Parameters

K Key container type compatible with internal::Raw.
I IV container type compatible with internal::Raw.

Parameters

algorithm OpenSSL cipher name (e.g. "aes-256-cbc").
data Plaintext string to encrypt.
key Encryption key; pass an empty container to use a random key.
iv Initialization vector; pass an empty container to use a random IV.
encoding Transport encoding for the output (default: Binary).

Returns

Encrypted (and optionally encoded) result as a std::string.

decryptString

template<typename K, typename I> std::string decryptString(const std::string & algorithm, const std::string & data, const K & key, const I & iv, Cipher::Encoding encoding)

Decrypts a string using the specified cipher, key, and IV in a single call.

Constructs a Cipher, optionally applies key and iv (skipped when empty), then delegates to Cipher::decryptString().

Parameters

K Key container type compatible with internal::Raw.
I IV container type compatible with internal::Raw.

Parameters

algorithm OpenSSL cipher name (e.g. "aes-256-cbc").
data Ciphertext string to decrypt, in the format given by encoding.
key Decryption key; pass an empty container to use a random key.
iv Initialization vector; pass an empty container to use a random IV.
encoding Transport encoding of the input data (default: Binary).

Returns

Decrypted plaintext as a std::string.

initializeEngine

void initializeEngine()

Initialize the Crypto library, as well as the underlying OpenSSL libraries.

OpenSSL must be initialized before using any classes from the Crypto library. OpenSSL will be initialized automatically through OpenSSL instances held by various Crypto classes (Cipher, Hash, X509Certificate), however it is recommended to call initializeEngine() in any case at application startup.

The Crypto library can be called multiple times; however, for every call to initializeEngine(), a matching call to uninitializeEngine() must be performed.

uninitializeEngine

void uninitializeEngine()

Uninitializes the Crypto library.

hash

inline

inline std::string hash(const std::string & algorithm, std::string_view data)

Computes a hex-encoded digest of a string in a single call.

Parameters

algorithm OpenSSL digest name (e.g. "sha256", "md5").
data Input data to hash.

Returns

Lowercase hex-encoded digest string.

hash

inline

inline std::string hash(const std::string & algorithm, const void * data, unsigned length)

Computes a hex-encoded digest of a raw buffer in a single call.

Parameters

algorithm OpenSSL digest name (e.g. "sha256", "md5").
data Pointer to the input buffer.
length Number of bytes to hash.

Returns

Lowercase hex-encoded digest string.

checksum

inline

inline std::string checksum(const std::string & algorithm, const std::string & path)

Computes the hex-encoded checksum of a file using the given algorithm.

Reads the file in 4096-byte chunks; suitable for large files.

Parameters

algorithm OpenSSL digest name (e.g. "sha256", "md5").
path Filesystem path to the file to hash.

Returns

Lowercase hex-encoded digest string.

Exceptions

std::runtime_error if the file cannot be opened.

computeHMAC

std::string computeHMAC(std::string_view input, std::string_view key)

Computes an HMAC-SHA1 message authentication code.

Uses OpenSSL HMAC with SHA-1 as the underlying digest. The output is a 20-byte raw binary string (not hex-encoded).

Parameters

input Data to authenticate.
key Secret key used for the HMAC computation.

Returns

20-byte raw binary HMAC-SHA1 digest.

Exceptions

std::runtime_error if OpenSSL returns an unexpected digest length.

Built with