The module cryptography
The cryptography of the system as one module of code: each export is a primitive of Odin's core:crypto that the system took (support/cryptography, docs/CRYPTOGRAPHY.md), in the forms of the system.
- The caller supplies the memory: each Text is bytes of the caller, each
result is a buffer of the caller, so the module allocates nothing.
- Each byte of the caller is read once. The headers of the Texts and of the
result are read once at the entry. Each input that the code of the origin
reads more than once (a nonce, the additional data, a message to sign,
the info of HKDF, a tag) is first copied into memory of the module, with
a limit. So another thread or another program that writes the memory of
the caller during the call cannot make the export check some bytes and
use others.
- The result buffer must be private memory of the caller: an open and a
seal write it and read it back (the origin decrypts in place after the
tag check, and computes the tag of a seal over the bytes that it wrote).
docs/CRYPTOGRAPHY.md, section 6, says which arguments must be private.
- A failure is an error record and a negative count, never a boolean that a
caller can forget. An open whose tag does not verify gives Not_Authentic
and leaves no byte of the text in the result.
- The copies of secrets that the module makes are erased, and so is the
stack below each export after the work (erase_stack_below_the_caller):
the frames of the origin hold expanded keys and hash states.
A program says which cryptography it runs by the hash of this module: the hash names exactly the code that runs. The names of the algorithms stay as their standards write them.
| Fact | Value |
|---|---|
| Source | modules/cryptography |
| Boot image | in the boot image; the image is not built, so its size is not known |
| Imports | none |
| Imported by | cryptography_vectors, quic_echo |
Exports
| Export | What it does |
|---|---|
| seal_with_chacha20_poly1305(key: Text, nonce: Text, additional: Text, text: Text) -> Text | encrypts a text and appends its tag of 16 bytes (RFC 8439) |
| open_with_chacha20_poly1305(key: Text, nonce: Text, additional: Text, sealed: Text) -> Text | checks the tag of a sealed text and decrypts it (RFC 8439) |
| seal_with_aes_128_gcm(key: Text, nonce: Text, additional: Text, text: Text) -> Text | encrypts a text and appends its tag of 16 bytes (NIST SP 800-38D) |
| open_with_aes_128_gcm(key: Text, nonce: Text, additional: Text, sealed: Text) -> Text | checks the tag of a sealed text and decrypts it |
| sha256(text: Text) -> Text | gives the SHA-256 hash of a text: 32 bytes (FIPS 180-4) |
| hmac_sha256(key: Text, text: Text) -> Text | gives the HMAC of a text with a key, with SHA-256: 32 bytes (RFC 2104) |
| hkdf_sha256_extract(salt: Text, input: Text) -> Text | gives the pseudorandom key of HKDF from a salt and input keying material, with SHA-256: 32 bytes (RFC 5869, section 2.2) |
| hkdf_sha256_expand(key: Text, info: Text, length: Integer) -> Text | gives length bytes of output keying material from a pseudorandom key and an info text, with SHA-256 (RFC 5869, section 2.3) |
| x25519(scalar: Text, point: Text) -> Text | gives the shared secret of a scalar of 32 bytes and a point of 32 bytes (RFC 7748); with the point 9 it is the public key of the scalar |
| ed25519_public_key(secret: Text) -> Text | gives the public key of a private key of 32 bytes (RFC 8032, section 5.1.5) |
| ed25519_sign(secret: Text, message: Text) -> Text | gives the signature of a message of 4096 bytes at most, 64 bytes, with a private key of 32 bytes (RFC 8032, section 5.1.6) |
| ed25519_verify(public: Text, message: Text, signature: Text) -> Integer | checks the signature of a message of 4096 bytes at most with a public key of 32 bytes (RFC 8032, section 5.1.7; strict: a signature with a non-canonical S or R, or a public key of small order, is refused) |
| header_protection_mask_with_aes_128(key: Text, sample: Text) -> Text | gives the 5 bytes of the QUIC header protection mask of a sample of 16 bytes with a key of 16 bytes: AES-128 of the sample (RFC 9001, section 5.4.3) |
| header_protection_mask_with_chacha20(key: Text, sample: Text) -> Text | gives the 5 bytes of the QUIC header protection mask of a sample of 16 bytes with a key of 32 bytes: the ChaCha20 keystream at the counter and the nonce that the sample gives (RFC 9001, section 5.4.4) |
Read from the source of the module, as the build reads it to describe the exports (tools/kerneltool/describe.odin).