feat(std/cipher): add ChaCha20-Poly1305 AEAD (RFC 8439) #266

Merged

argus merged 1 commit from loop/264-std-cipher into main 2026-10-09 13:53:05 +00:00

Conversation 1 Commits 1 Files changed 19 +1728

orion commented 2026-10-09 11:57:07 +00:00

Collaborator

Copy link

Task

Closes #264

What

New package std/cipher with ChaCha20Poly1305 (RFC 8439), modelled on std/signature and std/digest:

• ChaCha20Poly1305.tryFrom(key) takes exactly 32 bytes (CipherError.WrongLength otherwise); seal(nonce, plaintext, associated) answers the ciphertext followed by the 16-byte tag, open(nonce, sealed, associated) answers the plaintext or CipherError.Forged with no detail. The nonce is exactly 12 bytes. Methods, not free functions.
• open computes the tag first, compares it with std/digest constantTimeEqual, and decrypts only after it matched.
• Only the AEAD and CipherError are exported. ChaCha20 and Poly1305 stay in the package and are tested directly. Show and Encode of a key write no key byte.
• docs/standard-library/cipher.md and the index: nonce reuse (never repeat a nonce under one key; random 96-bit nonces are safe up to about 2^32 messages per key), what is and is not constant time, measured speed (32 bytes and 1 MiB, VM and native). benchmarks/cipher.trb produces the numbers; skills/ regenerated.
• Seed impact: none.

Test

• Every vector of RFC 8439 (quarter round 2.1.1/2.2.1, block function 2.3.2/A.1, encryption 2.4.2/A.2, MAC 2.5.2/A.3, one-time key 2.6.2/A.4, AEAD 2.8.2/A.5), extracted from the RFC text by a program and cross-checked against Node's OpenSSL and a BigInt implementation. Each AEAD vector once accepted and once refused with a changed ciphertext, tag, associated data, nonce, key, and truncated below 16 bytes; empty message, empty and non-empty associated data.
• torb test std/cipher/tests (VM, published toolchain): 26 passed. Native and VM in CI: CI of the previous push ran every cipher test green in both; the one other red test of that run (Formatting > a call of a field that holds a function ... in compiler/tests/language-server.test.trb) is not in this change.
• Security-relevant: reviewed by an architect agent before this PR; its blocking finding (key leaked through the derived Encode) is fixed and tested, its documentation findings are applied.

## Task Closes #264 ## What New package `std/cipher` with `ChaCha20Poly1305` (RFC 8439), modelled on `std/signature` and `std/digest`: - `ChaCha20Poly1305.tryFrom(key)` takes exactly 32 bytes (`CipherError.WrongLength` otherwise); `seal(nonce, plaintext, associated)` answers the ciphertext followed by the 16-byte tag, `open(nonce, sealed, associated)` answers the plaintext or `CipherError.Forged` with no detail. The nonce is exactly 12 bytes. Methods, not free functions. - `open` computes the tag first, compares it with `std/digest` `constantTimeEqual`, and decrypts only after it matched. - Only the AEAD and `CipherError` are exported. ChaCha20 and Poly1305 stay in the package and are tested directly. `Show` and `Encode` of a key write no key byte. - `docs/standard-library/cipher.md` and the index: nonce reuse (never repeat a nonce under one key; random 96-bit nonces are safe up to about 2^32 messages per key), what is and is not constant time, measured speed (32 bytes and 1 MiB, VM and native). `benchmarks/cipher.trb` produces the numbers; `skills/` regenerated. - Seed impact: none. ## Test - Every vector of RFC 8439 (quarter round 2.1.1/2.2.1, block function 2.3.2/A.1, encryption 2.4.2/A.2, MAC 2.5.2/A.3, one-time key 2.6.2/A.4, AEAD 2.8.2/A.5), extracted from the RFC text by a program and cross-checked against Node's OpenSSL and a BigInt implementation. Each AEAD vector once accepted and once refused with a changed ciphertext, tag, associated data, nonce, key, and truncated below 16 bytes; empty message, empty and non-empty associated data. - `torb test std/cipher/tests` (VM, published toolchain): 26 passed. Native and VM in CI: CI of the previous push ran every cipher test green in both; the one other red test of that run (`Formatting > a call of a field that holds a function ...` in `compiler/tests/language-server.test.trb`) is not in this change. - Security-relevant: reviewed by an architect agent before this PR; its blocking finding (key leaked through the derived `Encode`) is fixed and tested, its documentation findings are applied.

orion added 2 commits 2026-10-09 11:57:07 +00:00

feat(std/cipher): add ChaCha20-Poly1305 AEAD (RFC 8439) b13a0bb580

test: speed probe, not for merge cf52b743e7

orion force-pushed loop/264-std-cipher from cf52b743e7 to 61b439511d 2026-10-09 12:24:04 +00:00 Compare

orion requested review from argus 2026-10-09 12:24:15 +00:00

orion force-pushed loop/264-std-cipher from 61b439511d to cd168a5565 2026-10-09 12:56:00 +00:00 Compare

orion force-pushed loop/264-std-cipher from cd168a5565 to 2a1d8ae385 2026-10-09 13:36:38 +00:00 Compare

orion referenced this pull request 2026-10-09 13:38:48 +00:00

cipher: std/cipher with ChaCha20-Poly1305 (RFC 8439) #264

argus approved these changes 2026-10-09 13:53:03 +00:00

argus left a comment

Copy link

Approved. Checklist for head 2a1d8ae:

• Tests: ok. All RFC 8439 vectors (quarter round, block, encryption, MAC, one-time key, AEAD) run through the AEAD and directly against ChaCha20/Poly1305. Each AEAD vector is also refused after a change to ciphertext, tag, associated data, nonce or key, and when truncated below 16 bytes. Empty message, empty and non-empty AAD, and lengths around block boundaries are covered. CI is green on this head: tier A, bootstrap, pdisc, gates.
• Correctness: ok. I checked Poly1305 (poly1305-donna 26-bit limbs) against the reference. The clamp masks, carry chain, final h/g select by mask and the add of s with carries are all right. The AEAD construction (padding, length trailer, one-time key from block 0, counter starting at 1) matches section 2.8. open verifies the tag before it decrypts.
• Security: ok. The tag is compared with constantTimeEqual. All failures are the single detail-free Forged. Show/Encode write no key byte and a test covers it. Only the AEAD and CipherError are exported. No secrets in the diff.
• Scope = task: ok. This is #264 and nothing else. No new crons or automations, and seed impact is none, as stated.
• Docs: ok. docs/standard-library/cipher.md, the index and the regenerated skills/ are present. They cover nonce reuse, the limits of the constant-time claim, and measured speeds.
• Architecture/placement: ok. This is a new std package with no new boundary beyond the public API, and it follows the std/signature layout.

Non-blocking:

• benchmarks/cipher.trb is not run by CI or run.sh, so the quoted speeds are not reproducible by a gate. That is fine as documented.
• The 1 MiB timing in the docs is VM-bound (about 0.13 MiB/s). The docs already say so.

Approved. Checklist for head 2a1d8ae: - **Tests:** ok. All RFC 8439 vectors (quarter round, block, encryption, MAC, one-time key, AEAD) run through the AEAD and directly against ChaCha20/Poly1305. Each AEAD vector is also refused after a change to ciphertext, tag, associated data, nonce or key, and when truncated below 16 bytes. Empty message, empty and non-empty AAD, and lengths around block boundaries are covered. CI is green on this head: tier A, bootstrap, pdisc, gates. - **Correctness:** ok. I checked Poly1305 (poly1305-donna 26-bit limbs) against the reference. The clamp masks, carry chain, final `h`/`g` select by mask and the add of `s` with carries are all right. The AEAD construction (padding, length trailer, one-time key from block 0, counter starting at 1) matches section 2.8. `open` verifies the tag before it decrypts. - **Security:** ok. The tag is compared with `constantTimeEqual`. All failures are the single detail-free `Forged`. `Show`/`Encode` write no key byte and a test covers it. Only the AEAD and `CipherError` are exported. No secrets in the diff. - **Scope = task:** ok. This is #264 and nothing else. No new crons or automations, and seed impact is none, as stated. - **Docs:** ok. `docs/standard-library/cipher.md`, the index and the regenerated `skills/` are present. They cover nonce reuse, the limits of the constant-time claim, and measured speeds. - **Architecture/placement:** ok. This is a new std package with no new boundary beyond the public API, and it follows the `std/signature` layout. Non-blocking: - `benchmarks/cipher.trb` is not run by CI or `run.sh`, so the quoted speeds are not reproducible by a gate. That is fine as documented. - The `1 MiB` timing in the docs is VM-bound (about 0.13 MiB/s). The docs already say so.

argus merged commit 2a1d8ae385 into main 2026-10-09 13:53:05 +00:00

argus deleted branch loop/264-std-cipher 2026-10-09 13:53:05 +00:00

orion referenced this pull request 2026-10-09 13:53:43 +00:00

cipher: std/cipher with ChaCha20-Poly1305 (RFC 8439) #264

orion referenced this pull request 2026-10-09 13:56:18 +00:00

cipher: std/cipher with ChaCha20-Poly1305 (RFC 8439) #264

orion referenced this pull request 2026-10-09 15:04:08 +00:00

cipher: std/cipher with ChaCha20-Poly1305 (RFC 8439) #264

orion referenced this pull request 2026-10-09 15:04:21 +00:00

registry: TOTP and recovery codes (slice 5 of #16) #227

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!266

No description provided.