From 6eadf67d53d1061ba6222538df78dc02c45f63af Mon Sep 17 00:00:00 2001 From: Glenn Fiedler Date: Thu, 9 Jul 2026 13:18:22 -0400 Subject: [PATCH] Track libsodium upstream in NOTES.md instead of filing issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first real run of the nightly libsodium check found 1.0.22 (vendored is 1.0.20) but reported green without filing its tracking issue: creation failed on a missing 'dependencies' label and a '|| echo' fallback masked it. Rather than fix issue-filing, drop it — the record belongs in sodium/NOTES.md. - scheduled.yml: the check now compares the latest upstream release to a "Last reviewed upstream release" marker in NOTES.md and fails (no issue) if a newer, unreviewed release exists. Failing self-clears when NOTES.md is updated. - sodium/NOTES.md: add the marker (1.0.22) and a review log. Reviewing 1.0.21/1.0.22 found most changes are outside the included slice, but the AEAD post-MAC-verification memory fence (speculative-access hardening) from 1.0.20-stable/1.0.21 does touch the ChaCha20-Poly1305 decrypt path and is noted as pending incorporation on the next re-vendor. It is a defense-in-depth hardening, not a functional or interop change, so vendored 1.0.20 stays correct meanwhile. Co-Authored-By: Claude Fable 5 --- .github/workflows/scheduled.yml | 37 ++++++++------------------ sodium/NOTES.md | 47 ++++++++++++++++++++++----------- 2 files changed, 42 insertions(+), 42 deletions(-) diff --git a/.github/workflows/scheduled.yml b/.github/workflows/scheduled.yml index 735e89b..2999bde 100644 --- a/.github/workflows/scheduled.yml +++ b/.github/workflows/scheduled.yml @@ -103,44 +103,29 @@ jobs: name: libsodium upstream check runs-on: ubuntu-24.04 timeout-minutes: 10 - permissions: - contents: read - issues: write env: GH_TOKEN: ${{ github.token }} steps: - uses: actions/checkout@v4 - - name: Compare vendored version to latest upstream release + - name: Compare latest upstream release to the reviewed marker run: | set -euo pipefail - vendored=$(grep -oP 'SODIUM_VERSION_STRING\s+"\K[^"]+' sodium/sodium.h) - echo "vendored libsodium: $vendored" + # the record of what has been reviewed lives in sodium/NOTES.md, not in issues. + # fail if a newer upstream release exists than the "Last reviewed" marker there; + # clearing the failure means reviewing the release and updating NOTES.md. + + reviewed=$(grep -oP 'Last reviewed upstream release:\s*\K[0-9.]+' sodium/NOTES.md) + echo "last reviewed upstream release (per sodium/NOTES.md): $reviewed" latest=$(gh api repos/jedisct1/libsodium/releases/latest --jq '.tag_name' | sed 's/-RELEASE$//; s/^v//') echo "latest upstream release: $latest" - if [ "$vendored" = "$latest" ]; then - echo "vendored subset is up to date" - exit 0 - fi - - title="libsodium $latest is available (vendored subset is $vendored)" - - # don't open a duplicate if an open issue with this exact title already exists - existing=$(gh issue list --state open --search "in:title \"$title\"" --json number --jq 'length') - if [ "$existing" != "0" ]; then - echo "an open issue for $latest already exists; nothing to do" + if [ "$latest" = "$reviewed" ]; then + echo "no unreviewed upstream release" exit 0 fi - gh issue create \ - --title "$title" \ - --label dependencies \ - --body "The vendored libsodium subset in \`sodium/\` is at **$vendored**, but upstream has released **$latest**. - - Review the upstream changelog for security-relevant fixes and, if warranted, regenerate the amalgamated subset per \`sodium/NOTES.md\` (re-run the known-answer validation, including \`test_crypto_aead_vectors\`, afterwards). - - Opened automatically by the scheduled \`libsodium upstream check\` job." \ - || echo "could not create issue (the 'dependencies' label may not exist); please create it manually" + echo "::error::libsodium $latest is available and has not been reviewed (marker is $reviewed). Review it against the included slice and update the 'Last reviewed upstream release' marker and review log in sodium/NOTES.md." + exit 1 diff --git a/sodium/NOTES.md b/sodium/NOTES.md index 6920f92..8344d12 100644 --- a/sodium/NOTES.md +++ b/sodium/NOTES.md @@ -39,23 +39,38 @@ ChaCha20, Poly1305, and AEAD implementations are byte-identical across 1.0.17 ## Upstream tracking -Vendoring decouples this tree from upstream security updates, so the pinned version -is watched rather than assumed current. The scheduled `libsodium upstream check` job -(`.github/workflows/scheduled.yml`) reads the version from `SODIUM_VERSION_STRING` in -`sodium.h`, compares it to the latest `jedisct1/libsodium` release, and opens a -tracking issue if a newer release exists. When that fires: - -1. Read the upstream changelog for changes touching the included slice (ChaCha20, - Poly1305, the two AEAD constructions, and their support code — most releases do - not). -2. If a relevant fix landed, regenerate the amalgamation per "Structure / regenerating" - above and bump `SODIUM_VERSION_STRING`. -3. Re-run the validation below — in particular `test_crypto_aead_vectors`, which runs - in CI on every platform — and confirm the output is still bit-identical to the new - upstream for both AEADs. +Vendoring decouples this tree from upstream security updates, so upstream releases are +watched rather than assumed reviewed. The scheduled `libsodium upstream check` job +(`.github/workflows/scheduled.yml`) compares the latest `jedisct1/libsodium` release to +the marker below and **fails** if a newer, unreviewed release exists — it does not open +issues; this file is the record. To clear it, review the new release and update the +marker (and the log) here. + + Last reviewed upstream release: 1.0.22 -If the release only touches code outside the included slice, bumping the pinned -version string (so the check goes quiet) is enough; note the reason in the commit. +Reviewing a new release means: + +1. Read the upstream changelog for changes touching the **included slice** (ChaCha20, + Poly1305, the two AEAD constructions, and their support code — most releases touch + none of it). +2. If a relevant fix landed, regenerate the amalgamation per "Structure / regenerating" + above, bump `SODIUM_VERSION_STRING`, and re-run the validation below — in particular + `test_crypto_aead_vectors`, which runs in CI on every platform — confirming the output + is still bit-identical to the new upstream for both AEADs. +3. Update the marker above to the reviewed version and add a line to the log, whether or + not the vendored code changed. + +### Review log + +- **1.0.22 (reviewed; vendored still 1.0.20).** 1.0.21 and 1.0.22 are mostly outside the + included slice — the ed25519 small-order-point fix, ipcrypt, XOF/SHA-3, ML-KEM768 / + X-Wing, and assorted build/platform work do not touch the ChaCha20/Poly1305/AEAD code + netcode uses. **One item does:** 1.0.20-stable/1.0.21 added memory fences after MAC + verification in the AEAD path (a speculative-access hardening — plaintext must not be + read before authentication completes). This appears to touch the ChaCha20-Poly1305 + decrypt code in this subset and is **pending incorporation** on the next re-vendor; + it is a defense-in-depth hardening, not a functional or interop change, so the vendored + 1.0.20 remains correct and interoperable in the meantime. ## What is included