Authentication & Security Tokens
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and security tokens in HXLibs provide a mechanism for secure data exchange and identity verification. The system converts complex C++ objects into encrypted, URL-safe strings for transport across network boundaries.
The core implementation utilizes AES-256-GCM encryption and Base64Url encoding to ensure data confidentiality and integrity. This module integrates with the library's reflection system to handle serialization automatically.
Token Architecture
The token system consists of three primary layers: serialization, encryption, and encoding.
The diagram shows the bidirectional transformation between native C++ structures and secure transportable tokens.
Sources: include/HXLibs/net/token/Token.hpp:46-73
TokenApi
The TokenApi class serves as the primary interface for token operations. It uses a singleton pattern accessible via get() to manage thread-local encryption contexts.
toToken<T>(T&& t): Serializes a reflected object to JSON, encrypts it using AES-256-GCM, and encodes the result in Base64Url format.fromToken<T>(T& t, std::string_view urlBase64): Decodes a Base64Url string, decrypts the payload, and deserializes the JSON back into a C++ object.
Sources: include/HXLibs/net/token/Token.hpp:46-73
Cryptographic Implementation
Encryption relies on the OpenSSL library to implement the AES-256-GCM algorithm.
AES-256-GCM Details
The Aes256Gcm class manages the encryption lifecycle, including Initialization Vector (IV) generation and authentication tag validation.
| Component | Size | Description |
|---|---|---|
| Key | 32 Bytes | Symmetric key for AES-256. |
| IV | 12 Bytes | Random Initialization Vector generated per encryption. |
| Tag | 16 Bytes | Authentication tag for GCM integrity check. |
Sources: include/HXLibs/net/token/tools/Aes256Gcm.hpp:33-145
Data Flow for Encryption
- Generate a random 12-byte IV using
RAND_bytes. - Initialize the OpenSSL
EVP_CIPHER_CTXwithEVP_aes_256_gcm. - Encrypt the plaintext and retrieve the 16-byte authentication tag.
- Concatenate the results into a single binary string:
IV + Ciphertext + Tag.
Sources: include/HXLibs/net/token/tools/Aes256Gcm.hpp:78-114
Networking and Integration
Security tokens are typically transported via HTTP headers or within API request bodies.
HTTP Authentication Headers
Clients use the Authorization header to present tokens to a server. The library supports standard schemes such as Bearer tokens.
The sequence shows how the security token is used within a standard HTTP request flow.
Sources: examples/ai/ai.cpp:111-131, include/HXLibs/net/protocol/http/Http.hpp:130-140
Security Configurations
For transport-level security, the library provides SSL/TLS configurations through the SslConfig and SslContext classes.
| Option | Value | Description |
|---|---|---|
SslVerifyOption::None | SSL_VERIFY_NONE | No certificate verification. |
SslVerifyOption::ClientPeer | SSL_VERIFY_PEER | Client verifies server certificate. |
SslVerifyOption::ServerPeer | `PEER | FAIL_IF_NO_CERT` |
Sources: include/HXLibs/net/protocol/https/Https.hpp:35-46
Usage Example
The following code demonstrates defining a data structure, generating a token, and reconstructing the object from that token.
// 1. Define reflected structure
struct UserSession {
uint64_t userId;
std::string username;
};
// 2. Generate Token
auto& api = token::TokenApi::get();
UserSession session{123, "dev_user"};
std::string token = api.toToken(session);
// 3. Reconstruct from Token
UserSession validatedSession{};
api.fromToken(validatedSession, token);
Sources: tests/net/token.cpp:44-64, include/HXLibs/net/token/Token.hpp:54-73
Summary
The Authentication & Security Tokens module provides high-level abstractions for securing data at rest (via Aes256Gcm) and in transit (via TokenApi). By combining C++20 reflection with industry-standard OpenSSL encryption, it allows developers to implement secure session management and API authentication with minimal manual data handling.