From 29b9ab3d4eb2df5d7ea06355fab7fe4ddd70029c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A1bor=20Z=20Sink=C3=B3?= Date: Mon, 2 Nov 2026 22:00:11 +0100 Subject: [PATCH] docs(release): the sha256 hex form holds for the artifacts digests only; build_hash and the provenance digests stay base64 The digest paragraph said the form is the form of the receipt fields (primitive_build_hash, grammar_sha256) so a consumer needs no re-encoding for the new fields. That is true of the artifacts digests and false for primitive_build_hash: release.build_hash is an existing field and still base64 SHA-256, like provenance.grammar_*, dependency_lock_sha256 and specs[].meta_hash. The sentence now says so and says that the conversion belongs to the consumer's own contract, which this contract does not define. English (normative) and Hungarian (summary) alike. No record, code or vector changes. --- [signing-metadata] key = cic-my-sign-key signature = vault:v1:MEQCIEecwxmWXVnV8Gf8KgxpX+cgdpXXBLDWtwMwN3Xy0wVGAiAS9MlFuLD7d9AkMjz5kGJKNAub+Fp0cNiiPe1uHQzkig== hash-algorithm = sha256 digest = LIOryfKo5q0Uohv8YPsacJ2SsaY22CesJ/CqIpdUBFE= [certificate] -----BEGIN CERTIFICATE----- MIICBjCCAaygAwIBAgIUSnRMR6RPnEbg296XWPOqq/u5PCwwCgYIKoZIzj0EAwIw QzELMAkGA1UEBhMCSFUxGTAXBgNVBAoMEENlbnRyYWxJbmZyYUNvcmUxGTAXBgNV BAMMEENJQyBEZXZlbG9wZXIgQ0EwHhcNMjYwMzIwMTMyMjU5WhcNMjYxMjMxMTMy MjU5WjBFMQswCQYDVQQGEwJIVTEZMBcGA1UECgwQQ2VudHJhbEluZnJhQ29yZTEb MBkGA1UEAwwSR2Fib3IgWm9sdGFuIFNpbmtvMFkwEwYHKoZIzj0CAQYIKoZIzj0D AQcDQgAEIG2CVmTfmLB9pLLclj7YmP2eedAjklpy4LGrU2ijoiy6Xqpuybv7OgJe i+ez31s65NEV8+X/ByeX1cstR988z6N8MHowCQYDVR0TBAIwADAdBgNVHQ4EFgQU yZN6AIX/TNnIJ9GwAa/NRN3ujHAwHwYDVR0jBBgwFoAUXn6CHYzPUqU4JVP8g+OS WeDYjhcwDgYDVR0PAQH/BAQDAgeAMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEF BQcDBDAKBggqhkjOPQQDAgNIADBFAiEA+bFzXRoJ4PCQbhAAtpkcMjt0vNj5rEW0 lOMBGDNyaWkCIB1vmM7PcZzv/c9bIrxF5kqv6QXomouhByUfeNUTbpKW -----END CERTIFICATE----- --- docs/en/RELEASE-RECORD-CONTRACT.md | 2 +- docs/hu/RELEASE-RECORD-CONTRACT.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/RELEASE-RECORD-CONTRACT.md b/docs/en/RELEASE-RECORD-CONTRACT.md index ccedb66..3a4f584 100644 --- a/docs/en/RELEASE-RECORD-CONTRACT.md +++ b/docs/en/RELEASE-RECORD-CONTRACT.md @@ -21,7 +21,7 @@ Out of scope, kept as separate, later work (the trust gates): the external trust * **Source commit**: the git commit the release is made from, `provenance.source_commit`. * **Artifact**: a file, identified by its path in the tree of the source commit, that the record releases. * **Blob bytes**: the content of the git blob at that path in the source commit, exactly as stored (no filter, no line-ending conversion, no normalization). -* **Digest**: `sha256:` followed by 64 lowercase hexadecimal digits, the SHA-256 of the blob bytes. This is the form of the receipt fields (`primitive_build_hash`, `grammar_sha256`), so a consumer needs no re-encoding for the new fields. The algorithm is carried in the value itself. +* **Digest**: `sha256:` followed by 64 lowercase hexadecimal digits, the SHA-256 of the blob bytes. This is the form the digest fields of a receipt take (`sha256:` and 64 lowercase hex), so a consumer needs no re-encoding of an `artifacts` digest. It holds for the `artifacts` digests **only**: `release.build_hash`, `provenance.grammar_sha256`, `provenance.grammar_schema_sha256`, `provenance.dependency_lock_sha256` and `specs[].meta_hash` remain base64 SHA-256 (the legacy form, below), so a receipt field that takes one of them needs the conversion that the consumer's own contract defines; this contract does not define it. The algorithm of an `artifacts` digest is carried in the value itself. ## 4. Envelope 3 diff --git a/docs/hu/RELEASE-RECORD-CONTRACT.md b/docs/hu/RELEASE-RECORD-CONTRACT.md index f6d5aff..50ca5ef 100644 --- a/docs/hu/RELEASE-RECORD-CONTRACT.md +++ b/docs/hu/RELEASE-RECORD-CONTRACT.md @@ -7,7 +7,7 @@ Az angol változat (`docs/en/RELEASE-RECORD-CONTRACT.md`) a normatív forrás; e * **Cél.** A fogyasztó a release rekordból magából ellenőrizhesse, hogy a release pontosan a pinelt bájtokat tartalmazza. Az envelope 2-ben a rekord csak a séma-forrásokat és két grammar-fájlt digesteli (base64); a többi a `source_commit`-ra támaszkodik, ami `null` is lehet. A tulajdonos döntése (2026-11-01): a rekord minden artifactról saját digestet és algoritmust hordoz; a `source_commit` kötelező marad, de nem helyettesíti a digesteket. * **Hatókör.** A rekord állításai a kiadott fájlokról, kódolásuk és az elutasítás feltételei. Nincs benne: trust anchor, aláíró jogosultsága, tanúsítvány-érvényesség, manifest-eredet, hitelesség. Az aláírási mechanizmus nem változik. Ennek a szerződésnek a teljesítése nem jelent hitelességet. * **A compiler nem a fogyasztótól tanulja, mit digesteljen.** Az artifact-halmazt a termelő deklarálja a `project.yaml`-ban, **kizárólag explicit, repo-gyökérhez viszonyított fájlútvonalakkal** (`compiler_settings.release_artifacts.paths`); az első verzióban nincs glob, `include` vagy `exclude` (az később, külön verziózott bővítés lehet). Az útvonalak kizárólag a `source_commit` Git-fájából oldódnak fel, nem a munkakönyvtárból; a fogyasztó pin-manifestjét a compiler nem olvassa. Hiányzó deklaráció, üres lista, nem szabályos (abszolút, `..`, `.`, üres szegmens, visszaper, NUL), duplikált vagy a fában nem található útvonal, valamint könyvtár, szimbolikus link vagy submodule: a compiler elutasít (`declaration_*`, `declared_path_*`). A fogyasztó a saját követelményét ellenőrzi a halmaz ellen. -* **Rekord (envelope 3).** `provenance.source_commit`: 40 kisbetűs hex, kötelező, sosem `null`. `artifacts.files[]`: `{path, digest}` útvonal szerint bájtsorrendben rendezve, egyedi útvonalakkal; `digest` = `sha256:` + 64 kisbetűs hex, a git blob nyers bájtjainak SHA-256-ja szűrés és normalizálás nélkül. `artifacts.manifest_digest`: a `sha256sum` formátumú sorok SHA-256-ja. A forma azonos a receipt mezőivel, ezért a fogyasztónak nem kell átkódolnia. A `build_hash` az envelope 2 szabálya szerint a teljes csomagot fedi, tehát az új tagokat a meglévő aláírás is köti; ez a lefedettség követelmény, amíg a 12. szakasz golden vektorai nem bizonyítják, nem bizonyított tulajdonság. +* **Rekord (envelope 3).** `provenance.source_commit`: 40 kisbetűs hex, kötelező, sosem `null`. `artifacts.files[]`: `{path, digest}` útvonal szerint bájtsorrendben rendezve, egyedi útvonalakkal; `digest` = `sha256:` + 64 kisbetűs hex, a git blob nyers bájtjainak SHA-256-ja szűrés és normalizálás nélkül. `artifacts.manifest_digest`: a `sha256sum` formátumú sorok SHA-256-ja. A forma azonos a receipt digest-mezőinek formájával, ezért az `artifacts` digesteket a fogyasztónak nem kell átkódolnia. Ez **csak** az `artifacts` digesteire igaz: a `release.build_hash`, a `provenance.grammar_sha256`, a `provenance.grammar_schema_sha256`, a `provenance.dependency_lock_sha256` és a `specs[].meta_hash` base64 SHA-256 marad (a régi forma), így az a receipt-mező, amely ezek egyikét veszi át, a fogyasztó saját szerződése szerinti átalakítást igényli; ezt ez a szerződés nem határozza meg. A `build_hash` az envelope 2 szabálya szerint a teljes csomagot fedi, tehát az új tagokat a meglévő aláírás is köti; ez a lefedettség követelmény, amíg a 12. szakasz golden vektorai nem bizonyítják, nem bizonyított tulajdonság. * **Útvonal-karakterkészlet.** Az útvonal nem tartalmazhat vezérlőkaraktert (U+0000–U+001F, U+007F; LF, CR, TAB, NUL is tiltott), mert a manifest soralapú, és egy sortörés az útvonalban kétértelművé tenné a sorhatárt. Új manifest-formátum nem kell; a hiba `artifact_path_form`, illetve a compilerben `declaration_path_form`. * **Egyediség.** Az `artifacts.files[].path` és a `specs[].source_path` egyedi; a verifier elutasítja a duplikátumot, nem engedi, hogy a későbbi felülírja a korábbit. A rendezetlen listát elutasítja, nem rendezi csendben. * **Legacy envelope 1.** Az a rekord legacy envelope 1, és csak az, amelyben nincs `provenance` tag, a `release` leképezés `envelope` nélkül, és a `release.build_hash` és `release.sign` nem üres szöveg (pl. `release/cic-primitives-v0.1.5.yaml`): `envelope_too_old`. Más, mindkét envelope-mezőt nélkülöző rekord `envelope_unsupported`; pontosan az egyik hiánya `envelope_mismatch`. **Hiányzó `cic_countersign`:** nem elutasítás és nem siker; a verifier `INCOMPLETE`-nek jelenti, és egy későbbi, ellenjegyzést előíró release-policy nem teljesül tőle.