Thread-safe authenticated encryption with symmetric, asymmetric, and pluggable modes.
More...
#include <security.h>
Thread-safe authenticated encryption with symmetric, asymmetric, and pluggable modes.
One Security instance per endpoint. Configuration is supplied through Config at construction time; copy and assignment are deleted, move is supported. Each call to encrypt() / decrypt() selects a mode using the precedence order described in the file-level mode summary diagram.
◆ Callback
Callable signature for user-supplied encrypt / decrypt callbacks.
Implementations must populate out and return true on success; failure leaves out empty and the surrounding encrypt() / decrypt() call returns false. Function is copyable, so callbacks may be passed in a const-reference Config.
◆ Security() [1/4]
| vlink::Security::Security |
( |
| ) |
|
Constructs an empty Security; equivalent to Security(Config{}).
With built-in algorithms compiled in, this installs the default symmetric slot; otherwise the instance reports is_configured() == false and refuses to encrypt or decrypt.
◆ Security() [2/4]
| vlink::Security::Security |
( |
const Config & |
cfg | ) |
|
|
explicit |
Constructs from a configuration aggregate, copying caller state.
- Parameters
-
| cfg | Configuration aggregate; every non-empty field is validated and installed. |
◆ Security() [3/4]
| vlink::Security::Security |
( |
Config && |
cfg | ) |
|
|
explicit |
Constructs from a configuration aggregate, moving caller state in.
- Parameters
-
| cfg | Configuration aggregate consumed during construction. |
◆ ~Security()
| vlink::Security::~Security |
( |
| ) |
|
Destroys the instance and zeroises any held symmetric key material in place.
◆ Security() [4/4]
| vlink::Security::Security |
( |
Security && |
| ) |
|
|
noexcept |
Move-constructs from another Security; the source becomes default-constructed.
◆ can_decrypt()
| bool vlink::Security::can_decrypt |
( |
| ) |
const |
|
noexcept |
Reports whether decrypt() will succeed.
Requires at least one of: a custom callback pair, a derived AES-128 key, or a local private_key_pem. A bare public_key_pem alone is insufficient.
- Returns
true when a decryption capability is installed.
◆ can_encrypt()
| bool vlink::Security::can_encrypt |
( |
| ) |
const |
|
noexcept |
Reports whether encrypt() will succeed.
Requires at least one of: a custom callback pair, a derived AES-128 key, or a peer public_key_pem. A bare private_key_pem alone is insufficient.
- Returns
true when an encryption capability is installed.
◆ decrypt()
| bool vlink::Security::decrypt |
( |
const Bytes & |
in, |
|
|
Bytes & |
out |
|
) |
| |
Decrypts in into out using the highest-precedence active mode.
Mode selection mirrors encrypt() but uses the inbound direction (custom > asymmetric private key > symmetric). Tampered ciphertext, mismatched AAD, replayed sequence numbers, and missing or invalid RSA-PSS signatures (when verify_key_pem is set) cause failure.
- Parameters
-
| in | Ciphertext produced by a peer's encrypt(). |
| out | Output buffer overwritten on success and emptied on failure. |
- Returns
true on success; false otherwise.
◆ encrypt()
| bool vlink::Security::encrypt |
( |
const Bytes & |
in, |
|
|
Bytes & |
out |
|
) |
| |
Encrypts in into out using the highest-precedence active mode.
The selected mode follows the precedence summarised in the file-level diagram: custom > asymmetric (public key present) > symmetric. Empty in fails; AEAD requires at least one byte of authenticated material. Inputs exceeding INT_MAX bytes are rejected.
- Parameters
-
| in | Plaintext payload. |
| out | Output buffer overwritten on success and emptied on failure. |
- Returns
true on success; false otherwise.
◆ from_key_paths()
| static Config vlink::Security::from_key_paths |
( |
const std::string & |
public_key_path, |
|
|
const std::string & |
private_key_path |
|
) |
| |
|
static |
Loads both a public-key and a private-key PEM file into a fresh Config.
- Parameters
-
| public_key_path | Filesystem path of the PEM-encoded peer public key. |
| private_key_path | Filesystem path of the PEM-encoded local private key. |
- Returns
- Pre-populated
Config; per-file misses leave only the affected field empty.
◆ from_private_key_path()
| static Config vlink::Security::from_private_key_path |
( |
const std::string & |
private_key_path | ) |
|
|
static |
Loads a private-key PEM file into a fresh Config.
Reads the file at construction time and populates Config::private_key_pem. RSA validation is deferred until the Security constructor consumes the config.
- Parameters
-
| private_key_path | Filesystem path of the PEM-encoded private key. |
- Returns
- Pre-populated
Config; private_key_pem is empty when the file is unreadable.
◆ from_public_key_path()
| static Config vlink::Security::from_public_key_path |
( |
const std::string & |
public_key_path | ) |
|
|
static |
Loads a public-key PEM file into a fresh Config.
- Parameters
-
| public_key_path | Filesystem path of the PEM-encoded public key. |
- Returns
- Pre-populated
Config; public_key_pem is empty when the file is unreadable.
◆ is_configured()
| bool vlink::Security::is_configured |
( |
| ) |
const |
|
noexcept |
Reports whether at least one usable cryptographic slot is installed.
A true result merely means the instance can call encrypt() or decrypt() in some direction; senders should additionally verify can_encrypt() and receivers can_decrypt() to catch direction-specific RSA misconfiguration.
- Returns
true when any slot is usable in either direction.
◆ operator=()
Move-assigns from another Security; the source becomes default-constructed.
The documentation for this class was generated from the following file:
1.9.1