From 5faf6ebadc2ddec1bef799eceed54d870cabe5e3 Mon Sep 17 00:00:00 2001 From: Hidde Beydals Date: Fri, 21 Oct 2022 15:09:03 +0000 Subject: [PATCH] RFC: add design details artifact digest Signed-off-by: Hidde Beydals --- rfcs/XXXX-artifact-revision-format/README.md | 50 +++++++++++++++++++- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/rfcs/XXXX-artifact-revision-format/README.md b/rfcs/XXXX-artifact-revision-format/README.md index 9b6706f0..636aea6e 100644 --- a/rfcs/XXXX-artifact-revision-format/README.md +++ b/rfcs/XXXX-artifact-revision-format/README.md @@ -283,15 +283,60 @@ release. ### Artifact Digest +The `Artifact`'s `Digest` field advertises the checksum of the file in the +`URL`. The checksum within the value MUST be appended with an alias for the +algorithm separated by `:` (e.g. `sha256:...`). This follows the +[digest format][go-digest] of OCI. + +#### Format + +```text + ":" +``` + +Where `" "` indicates a literal string, and `< >` a variable. + #### Library +The library used for calculating the `Digest` field value is +`github.com/opencontainers/go-digest`. This library is used by various +OCI libraries which we already depend on, stable and extensible. + #### Configuration +The checksum MUST be calculated using the algorithm configured in the +`--artifact-digest-algo` flag of the source-controller binary. The default +value is `sha256`, but can be changed to `sha384`, `sha512` or `blake3`. + +**Note:** availability of BLAKE3 is at present dependent on an explicit import +of `github.com/opencontainers/go-digest/blake3`. + +When the provided algorithm is NOT supported, the source-controller MUST +fail to start. + +When the configured algorithm changes, the `Digest` MAY be recalculated to +update the value. + #### Calculation +The checksum MUST be calculated using the algorithm configured in the +`--artifact-digest-algo` flag of the source-controller binary. + #### Verification -#### Deprecation of Checksum +The checksum of a downloaded artifact MUST be verified against the `Digest` +field value. If the checksum does not match, the verification MUST fail. + +### Deprecation of Checksum + +The `Artifact`'s `Checksum` field is deprecated and MUST be removed in a +future release. The `Digest` field MUST be used instead. + +#### Backwards compatibility + +To allow backwards compatability, the source-controller could continue +to advertise the checksum part of a `Digest` in the `Checksum` field until +the field is removed. ## Implementation History @@ -302,4 +347,5 @@ Major milestones in the lifecycle of the RFC such as: - The version of Flux where the RFC was retired or superseded. --> -[BLAKE3]: https://github.com/BLAKE3-team/BLAKE3 \ No newline at end of file +[BLAKE3]: https://github.com/BLAKE3-team/BLAKE3 +[go-digest]: https://pkg.go.dev/github.com/opencontainers/go-digest#hdr-Basics \ No newline at end of file