# crypto

<a id="crypto"></a>

# crypto

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

## Classes

| Name | Description |
|------|-------------|
| [`Cipher`](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#cipher) | Provides symmetric algorithms for encryption and decryption. The algorithms that are available depend on the particular version of OpenSSL that is installed. |
| [`Hash`](https://auscaster.com/icey/docs/api-reference/icy-crypto-Hash.md#hash-3) | Incremental cryptographic hash engine wrapping OpenSSL EVP digest functions. |
| [`X509Certificate`](https://auscaster.com/icey/docs/api-reference/icy-crypto-X509Certificate.md#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`](#evpcipherctxptr)  | Owning OpenSSL cipher context handle with automatic `EVP_CIPHER_CTX_free`. |
| `std::vector< unsigned char >` | [`ByteVec`](#bytevec)  | Generic storage container for storing cryptographic binary data. |
| `std::unique_ptr< EVP_MD_CTX, decltype(&EVP_MD_CTX_free)>` | [`EvpMdCtxPtr`](#evpmdctxptr)  | Owning OpenSSL digest context handle with automatic `EVP_MD_CTX_free`. |
| `::RSA` | [`RSAKey`](#rsakey)  | Alias for the OpenSSL RSA key type, brought into the [icy::crypto](#crypto) namespace. |
| `std::unique_ptr< X509, decltype(&X509_free)>` | [`X509Ptr`](#x509ptr)  | RAII pointer alias for OpenSSL `X509*` values. |

---

<a id="evpcipherctxptr"></a>

### EvpCipherCtxPtr

```cpp
using EvpCipherCtxPtr = std::unique_ptr< EVP_CIPHER_CTX, decltype(&EVP_CIPHER_CTX_free)>
```

[Defined in src/crypto/include/icy/crypto/cipher.h:34](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/cipher.h#L34)

Owning OpenSSL cipher context handle with automatic `EVP_CIPHER_CTX_free`.

---

<a id="bytevec"></a>

### ByteVec

```cpp
using ByteVec = std::vector< unsigned char >
```

[Defined in src/crypto/include/icy/crypto/crypto.h:63](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/crypto.h#L63)

Generic storage container for storing cryptographic binary data.

---

<a id="evpmdctxptr"></a>

### EvpMdCtxPtr

```cpp
using EvpMdCtxPtr = std::unique_ptr< EVP_MD_CTX, decltype(&EVP_MD_CTX_free)>
```

[Defined in src/crypto/include/icy/crypto/hash.h:29](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/hash.h#L29)

Owning OpenSSL digest context handle with automatic `EVP_MD_CTX_free`.

---

<a id="rsakey"></a>

### RSAKey

```cpp
using RSAKey = ::RSA
```

[Defined in src/crypto/include/icy/crypto/rsa.h:29](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/rsa.h#L29)

Alias for the OpenSSL RSA key type, brought into the [icy::crypto](#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.

---

<a id="x509ptr"></a>

### X509Ptr

```cpp
using X509Ptr = std::unique_ptr< X509, decltype(&X509_free)>
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:30](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L30)

RAII pointer alias for OpenSSL `X509*` values.

## Functions

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

---

<a id="encryptstring"></a>

### encryptString

```cpp
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 = Cipher::Binary)
```

[Defined in src/crypto/include/icy/crypto/cipher.h:361](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/cipher.h#L361)

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

Constructs a [Cipher](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#cipher), optionally applies `key` and `iv` (skipped when empty), then delegates to [Cipher::encryptString()](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#encryptstring-1).

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

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `algorithm` | `const std::string &` | OpenSSL cipher name (e.g. "aes-256-cbc"). |
| `data` | `const std::string &` | Plaintext string to encrypt. |
| `key` | `const K &` | Encryption key; pass an empty container to use a random key. |
| `iv` | `const I &` | Initialization vector; pass an empty container to use a random IV. |
| `encoding` | [`Cipher::Encoding`](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#encoding-1) | Transport encoding for the output (default: Binary). |

---

<a id="decryptstring"></a>

### decryptString

```cpp
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 = Cipher::Binary)
```

[Defined in src/crypto/include/icy/crypto/cipher.h:390](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/cipher.h#L390)

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

Constructs a [Cipher](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#cipher), optionally applies `key` and `iv` (skipped when empty), then delegates to [Cipher::decryptString()](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#decryptstring-1).

#### Returns
Decrypted plaintext as a std::string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `algorithm` | `const std::string &` | OpenSSL cipher name (e.g. "aes-256-cbc"). |
| `data` | `const std::string &` | Ciphertext string to decrypt, in the format given by `encoding`. |
| `key` | `const K &` | Decryption key; pass an empty container to use a random key. |
| `iv` | `const I &` | Initialization vector; pass an empty container to use a random IV. |
| `encoding` | [`Cipher::Encoding`](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#encoding-1) | Transport encoding of the input data (default: Binary). |

---

<a id="initializeengine"></a>

### initializeEngine

```cpp
void initializeEngine()
```

[Defined in src/crypto/include/icy/crypto/crypto.h:57](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/crypto.h#L57)

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](https://auscaster.com/icey/docs/api-reference/icy-crypto-Cipher.md#cipher), [Hash](https://auscaster.com/icey/docs/api-reference/icy-crypto-Hash.md#hash-3), [X509Certificate](https://auscaster.com/icey/docs/api-reference/icy-crypto-X509Certificate.md#x509certificate)), however it is recommended to call [initializeEngine()](#initializeengine) in any case at application startup.

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

---

<a id="uninitializeengine"></a>

### uninitializeEngine

```cpp
void uninitializeEngine()
```

[Defined in src/crypto/include/icy/crypto/crypto.h:60](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/crypto.h#L60)

Uninitializes the Crypto library.

---

<a id="hash-1"></a>

### hash

`inline`

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

[Defined in src/crypto/include/icy/crypto/hash.h:108](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/hash.h#L108)

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

#### Returns
Lowercase hex-encoded digest string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `algorithm` | `const std::string &` | OpenSSL digest name (e.g. "sha256", "md5"). |
| `data` | `std::string_view` | Input data to hash. |

---

<a id="hash-2"></a>

### hash

`inline`

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

[Defined in src/crypto/include/icy/crypto/hash.h:122](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/hash.h#L122)

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

#### Returns
Lowercase hex-encoded digest string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `algorithm` | `const std::string &` | OpenSSL digest name (e.g. "sha256", "md5"). |
| `data` | `const void *` | Pointer to the input buffer. |
| `length` | `unsigned` | Number of bytes to hash. |

---

<a id="checksum-1"></a>

### checksum

`inline`

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

[Defined in src/crypto/include/icy/crypto/hash.h:139](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/hash.h#L139)

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

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

#### Returns
Lowercase hex-encoded digest string.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `algorithm` | `const std::string &` | OpenSSL digest name (e.g. "sha256", "md5"). |
| `path` | `const std::string &` | Filesystem path to the file to hash. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the file cannot be opened. |

---

<a id="computehmac"></a>

### computeHMAC

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

[Defined in src/crypto/include/icy/crypto/hmac.h:33](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/hmac.h#L33)

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).

#### Returns
20-byte raw binary HMAC-SHA1 digest.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `input` | `std::string_view` | Data to authenticate. |
| `key` | `std::string_view` | Secret key used for the HMAC computation. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if OpenSSL returns an unexpected digest length. |