security.h File Reference

Application-layer authenticated encryption with symmetric, hybrid asymmetric, and pluggable backends. More...

#include <cstdint>
#include <memory>
#include <string>
#include "../base/bytes.h"
#include "../base/functional.h"
#include "../base/macros.h"

Include dependency graph for security.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	vlink::Security
	Thread-safe authenticated encryption with symmetric, asymmetric, and pluggable modes. More...
struct	vlink::Security::Config
	Aggregate of every parameter accepted by the Security constructor. More...
struct	vlink::Security::Config::Advanced
	Low-frequency policy knobs and sender-authentication keys. More...

Namespaces
	vlink

Detailed Description

Application-layer authenticated encryption with symmetric, hybrid asymmetric, and pluggable backends.

Security sits between VLink serialisation and any transport layer. Every endpoint (publisher / subscriber / client / server / setter / getter) may own at most one Security instance; the instance authenticates and encrypts each outbound message and verifies and decrypts each inbound message before the transport sees the payload. It is fully orthogonal to the channel-level TLS controlled by SslOptions and can be combined with it.

Compiling with VLINK_ENABLE_SECURITY enables the OpenSSL-backed default crypto suite. Without that macro only the user-supplied callback path is available.

Encryption algorithms

Algorithm	Key size	Mode / construction	Used for
AES-GCM	128 bit	AEAD, 12-byte nonce, 16-byte tag	bulk encrypt / decrypt
RSA-OAEP-SHA256	>= 2048 b	wrap a fresh per-message AES key	asymmetric session-key wrap
RSA-PSS-SHA256	>= 2048 b	sender signature over AAD-bound envelope	optional sender identity
SHA-256 truncation	256 -> 128	derive raw key -> AES-128 key	symmetric key derivation
PBKDF2-HMAC-SHA256	configurable iters	derive passphrase -> AES-128	symmetric key derivation

Key sources

Source	Selector field(s)	Notes
Built-in default symmetric	every cryptographic field empty	only with VLINK_ENABLE_SECURITY
Explicit raw key	Config::key	SHA-256 truncated to AES-128
Passphrase + salt	Config::passphrase + pbkdf2_salt	PBKDF2-HMAC-SHA256 @ iterations
Peer public-key PEM	Config::public_key_pem	RSA-OAEP wrap of a fresh session key
Local private-key PEM	Config::private_key_pem	RSA-OAEP unwrap of session key
Custom callback pair	encrypt_callback + decrypt_callback	bypasses every built-in algorithm

Mode summary diagram

    sender                                       transport                                       receiver
+------------+                                 +-----------+                                 +-------------+
|  plaintext | ---> [select mode] ---> AEAD/RSA-OAEP envelope ---> bytes on wire --->  [select mode] ---> |
+------------+         ^                                                                  ^   plaintext   |
                       |                                                                  |               |
         custom > asymmetric > symmetric                       custom > asymmetric > symmetric            |
                                                                                                          |
encrypt(in, out)  -->  envelope(version, mode, nonce, AAD)  -->  ciphertext + tag  -->  decrypt(in, out)  v

Example (1: custom callback pair)

vlink::Security::Config cfg;
cfg.encrypt_callback = [](const vlink::Bytes& in, vlink::Bytes& out) {
  out = my_aead_encrypt(in);
  return !out.empty();
};
cfg.decrypt_callback = [](const vlink::Bytes& in, vlink::Bytes& out) {
  out = my_aead_decrypt(in);
  return !out.empty();
};
vlink::Security sec(std::move(cfg));

Example (2: symmetric passphrase with PBKDF2)

vlink::Security::Config cfg;
cfg.passphrase = "correct horse battery staple";
cfg.pbkdf2_salt = shared_salt;            // >= 16 bytes, shared out of band
cfg.pbkdf2_iterations = 200000U;
vlink::Security sec(cfg);

Example (3: asymmetric PEM with optional sender authentication)

auto sender_cfg = vlink::Security::from_public_key_path("peer_pub.pem");
sender_cfg.advanced.signing_key_pem = own_priv_pem;   // optional RSA-PSS signature
vlink::Security sender(std::move(sender_cfg));
 
auto receiver_cfg = vlink::Security::from_private_key_path("own_priv.pem");
receiver_cfg.advanced.verify_key_pem = peer_pub_pem;  // reject unsigned envelopes
vlink::Security receiver(std::move(receiver_cfg));

Note

• Every public method is thread-safe; concurrent encrypt() / decrypt() are serialised by an internal mutex.
• Configuration is immutable after construction; rebuild the Security instance to change keys or callbacks.
• When VLINK_ENABLE_SECURITY is undefined only the callback path is usable; other fields are accepted but emit a warning and remain unconfigured.