Ch26.21: Crypto and TLS
1. Two Modules
Primitive cryptography is in fast_io_crypto; the TLS record layer and socket
wrapper are in fast_io.tls. The TLS module imports the crypto module. Neither
is part of the umbrella fast_io module.
| Module | Exports |
|---|---|
fast_io_crypto |
CRC32/CRC32C, AES-128/192/256, Ed25519, X25519, NIST elliptic curves and ECDSA helpers. |
fast_io.tls |
TLS client config, TLS clients, socket files, root store, peer certificates, platform backends, handshake operations. |
2. CRC32
crc32_context and crc32c_context are incremental hash contexts:
::fast_io::crc32c_context crc;
crc.update(data, data + size);
auto const value{crc.digest_value()};
| Member | Meaning |
|---|---|
update(first, last) | Feed a byte range. |
reset() | Restart the context. |
digest_value() | Return the 32-bit digest. |
digest_to_byte_ptr(ptr) | Write the digest in wire byte order. |
do_final() | No-op finalisation hook. |
The implementation uses the hardware CRC instruction where available and a table fallback otherwise. The context is constexpr.
3. AES
aes_ctx<key_size> takes a raw key and operates on 16-byte blocks in ECB
mode. The aliases are aes128, aes192 and aes256.
::fast_io::aes128 cipher{key_bytes.data()};
cipher.encrypt(plain, nblocks, ciphertext);
cipher.decrypt(ciphertext, nblocks, plain);
One context serves both directions; decryption reuses the encryption schedule in reverse.
The block loop is inside the backend, and from/to may alias.
4. Ed25519 and X25519
ed25519 and diffie_hellman::x25519 expose fixed-size operations on
std::byte spans or raw pointers. The raw-pointer forms end in
_to_ptr.
| Operation | Meaning |
|---|---|
ed25519::create_key_pair(...) | Public/private key pair from a 32-byte secret. |
ed25519::sign_message(...) | 64-byte signature for a message. |
ed25519::verify_signature(...) | Boolean verification. |
x25519::calculate_public_key(...) | Public key from a 32-byte secret. |
The _to_ptr and span overloads are equivalent; the span forms enforce the
fixed sizes at the type level. The blinding overloads accept an explicit blinding context.
The exported X25519 surface derives a public key; the shared-secret construction is part
of the protocol layer, not a separate exported helper.
5. NIST Curves and ECDSA
ecc::secp256r1, secp384r1 and secp521r1 are the
exported curve types. The module also exports ECDSA verification, signing, RFC 6979
deterministic signing and the RFC 6979 DRBG.
These are low-level arithmetic and signature primitives. They do not manage keys, select a hash, or decide which curve is appropriate for a protocol. Use the TLS layer for a complete handshake.
6. TLS Types
| Type | Role |
|---|---|
tls_client_config | Hostname, trust anchors, hostname/chain checks and kernel-offload preference. |
tls_client | TLS state over a socket observer. |
tls_socket_file | Owning socket + TLS client bundle. |
iobuf_tls_socket_file | Buffered TLS socket for
print/scan. |
root_store | DER trust anchors decoded from PEM. |
peer_certificates | Parsed peer chain storage. |
native_tls_socket_file | Platform TLS backend (SChannel or OpenSSL/GnuTLS where configured). |
tls_socket_file owns the socket; tls_socket borrows an observer.
The TLS stream is still a device: after the handshake, use print,
scan and transmit.
7. Handshake and Trust
::fast_io::tls::tls_socket_file tls{std::move(sock)};
::fast_io::operations::handshake(tls, ::fast_io::u8cstring_view{u8"example.com"});
::fast_io::io::println(tls, "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n");
The hostname overload loads the system trust bundle, checks the chain and verifies the
hostname. For a custom bundle, fill tls_client_config from a
root_store and call the config overload of handshake.
The trust loader (root_store_load_system, root_store_load_pem_file)
is header-side. The TLS module exports the types and handshake operation, not a string-path
loader.
8. Backends and Boundaries
fast_io.tls can use its own userspace record layer, the OS backend
(SChannel on Windows, native TLS where available) or OpenSSL/GnuTLS backends when built.
tls_default_crypto selects the platform default; the config and socket types
stay the same.
Header-side extras include SHA-1/SHA-256/SHA-512, HMAC, MD5, RSA, AEAD constructions,
padding and the platform crypto backends. They are not in the fast_io_crypto
module export list yet.
Key Takeaways
- Crypto primitives are in
fast_io_crypto; TLS is infast_io.tls. - CRC32/CRC32C contexts are incremental and constexpr.
- AES is a raw 16-byte ECB block primitive; it is not a complete encryption scheme.
- Ed25519 and X25519 have span and
_to_ptrforms. - NIST curves and ECDSA helpers are low-level; TLS provides the complete handshake.
- TLS socket files are devices;
print/scanwork after the handshake. - The hostname handshake loads the system trust store; a custom bundle uses
tls_client_config. - SHA/HMAC/RSA/AEAD/padding and platform backends remain header-side.