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.

ECB is not an encryption scheme. This API is a raw block primitive. A real protocol needs a mode, a nonce/IV, authentication and key separation. Use TLS or an AEAD construction from the header layer; do not invent a mode from ECB.

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_configHostname, trust anchors, hostname/chain checks and kernel-offload preference.
tls_clientTLS state over a socket observer.
tls_socket_fileOwning socket + TLS client bundle.
iobuf_tls_socket_fileBuffered TLS socket for print/scan.
root_storeDER trust anchors decoded from PEM.
peer_certificatesParsed peer chain storage.
native_tls_socket_filePlatform 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.

Do not use raw primitives as a protocol. AES-ECB, a bare signature call and a raw X25519 result are building blocks. A secure protocol needs key derivation, nonces, authentication, transcript binding and error handling; the TLS layer already has them.

Key Takeaways