chore(docs): add ADR proposal for signing and verification of component descriptors by matthiasbruns · Pull Request #599 · open-component-model/open-component-model

matthiasbruns · 2025-08-21T12:53:02Z

Continuation of #547

What this PR does / why we need it

Enable easy interpretation of component descriptors in normalized form and provide a consistent experience for signing and verifying component descriptors.

Which issue(s) this PR fixes

fix open-component-model/ocm-project#579

…criptors Signed-off-by: Jakob Möller <jakob.moeller@sap.com>

Co-authored-by: Matthias Bruns <github@matthiasbruns.com> Signed-off-by: Jakob Möller <jakob.moeller@sap.com>

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

Signed-off-by: Matthias Bruns <git@matthiasbruns.com On-behalf-of: SAP <matthias.bruns@sap.com>

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

matthiasbruns · 2025-08-27T10:32:56Z

fyi: texts are improved by ai 🤖

Copilot

Pull Request Overview

This PR introduces an ADR (Architecture Decision Record) for the signing and verification of component descriptors in the Open Component Model (OCM). The proposal establishes a two-step flow for digest calculation and signing, with optional OCI Cosign support for enhanced interoperability.

Key changes:

Defines a standardized approach to component descriptor signing using JCS canonicalization
Introduces separate commands for digest calculation and signing operations
Adds comprehensive Cosign integration with OIDC authentication flows

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/adr/0008_signing_verification.md	Complete ADR document defining the signing/verification architecture with CLI examples and implementation details
.github/config/wordlist.txt	Adds technical terms used in the ADR to the spell-check allowlist

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

jakobmoellerdev · 2025-08-27T10:29:31Z

+# Step 2 — Signing (no digest mutation)
+# Direct signing via a single --cert (+ optional password).
+# Optional OCI Cosign signing for the same canonical payload.
+ocm sign cv <ref> \


this flag set is completely against our hard coding of signing plugins. we explicitly do not wanted to introduce hard coded flags for signing implementations on the commandline which is why open-component-model/ocm-project#544 exists. Does this here suggest dropping this again?

applied plugin stuff as far as I understood it

jakobmoellerdev · 2025-08-27T10:39:01Z

+### Cosign OIDC token capture (implementation sketch)
+
+```go
+func resolveSigstoreIDToken(ctx context.Context, flagToken string) (string, error) {


see my comment above: is it possible to sign / verify across binary boundary?

i can provide a test project for this

jakobmoellerdev · 2025-08-27T10:40:56Z

+
+---
+
+## Sequence Diagrams


These flows completely omit (maybe on purpose) signing handlers as plugins for OCM. This means we would have to build a hard go.mod dependency to sigstore, which is (for me) and absolute hard rejection argument because of cosigns difficult dependency chain that we would inherit (see https://github.com/sigstore/cosign/blob/main/go.mod)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fabianburth · 2025-08-27T11:51:25Z

+    3. Else, if interactive TTY is available, run an **interactive loopback** browser flow to retrieve the token.
+    4. Else, run the **device flow** to retrieve the token.
+  - Produce a Cosign signature over the **same canonical bytes**.
+  - When `--cosign-upload` is present and `<ref>` maps to an OCI subject (`<name>@<digest>`), attach the Cosign signature to the registry using Cosign conventions.


Could you elaborate how the signing and verification workflows would compare for:

component stored in oci (so, we can upload the signature)

component not stored in oci (so, we cannot upload the signature)

fabianburth · 2025-08-27T11:59:41Z

+- Computes the component-version digest from canonical bytes.
+- If `--pin` is provided, compares and fails on mismatch.


I think currently, the ADR does mention the actual original purpose of --pin which was to avoid an additional roundtrip of downloading resources and descriptors after already having done that in add digests. In general, the relationship between those commands is not really apparent here.

…nce our normalization On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

…iasbruns/open-component-model into docs/signing-verification-handler

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

jakobmoellerdev · 2025-08-28T23:19:59Z

I think this PR needs to be rewritten for several reasons:

It needs to accomodate plugin interfaces (those were removed)
It needs to use less AI generated flows and have actually tested proven flow examples
It should not use flags hardcoded on the CLI, but defer to the argument interpreter EPIC and use specs as we do everywhere else
It should use the existing credential graph and credential plugins for configuration of any credential information

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

…-model into docs/signing-verification-handler

jakobmoellerdev · 2025-09-01T13:06:27Z

closing as discussed

…nt descriptors (#767) Continuation of #547 and #599  #### What this PR does / why we need it Enable easy interpretation of component descriptors in normalized form and provide a consistent experience for signing and verifying component descriptors. #### Which issue(s) this PR fixes  fix open-component-model/ocm-project#579 --------- Signed-off-by: Jakob Möller <jakob.moeller@sap.com> Co-authored-by: Matthias Bruns <github@matthiasbruns.com> Co-authored-by: Fabian Burth <fabian.burth@sap.com> Co-authored-by: Gergely Brautigam <gergely.brautigam@sap.com>

jakobmoellerdev and others added 2 commits August 13, 2025 11:48

docs(adr): add proposal for signing and verification of component des…

889594b

…criptors Signed-off-by: Jakob Möller <jakob.moeller@sap.com>

chore: adopt pr review feedback

8ba876f

Co-authored-by: Matthias Bruns <github@matthiasbruns.com> Signed-off-by: Jakob Möller <jakob.moeller@sap.com>

Copilot AI review requested due to automatic review settings August 21, 2025 12:53

matthiasbruns requested a review from a team as a code owner August 21, 2025 12:53

github-actions Bot added component/github-actions Changes on GitHub Actions or within `.github/` directory area/documentation Documentation related size/m Medium labels Aug 21, 2025

This comment was marked as outdated.

Sign in to view

feat: update adr to cover digest an pinning split

9e1179a

matthiasbruns marked this pull request as draft August 21, 2025 13:07

matthiasbruns mentioned this pull request Aug 21, 2025

chore(docs): add ADR proposal for signing and verification of component descriptors #547

Closed

matthiasbruns added 2 commits August 22, 2025 09:22

fix: formatting

7bdfd0e

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

feat: update code examples

abbc72d

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

jakobmoellerdev changed the title ~~Docs/signing verification handler~~ chore(docs): add ADR proposal for signing and verification of component descriptors Aug 22, 2025

github-actions Bot added the kind/chore chore, maintenance, etc. label Aug 22, 2025

feat: simplify commands

27e1967

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

matthiasbruns commented Aug 25, 2025

View reviewed changes

Comment thread docs/adr/0008_signing_verification.md Outdated

matthiasbruns added 8 commits August 25, 2025 09:37

feat: simplify stuff

dc05382

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

feat: iterate

6567a81

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

feat: add named signatures

6740224

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

chore: fix references

4baa9f5

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

fix: references

931dec0

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

feat: add cosign concept

fc5d5a8

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

feat: add pseudo cosign wait flow

748799e

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

chore: cleanup

8e79857

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

matthiasbruns marked this pull request as ready for review August 27, 2025 10:25

Merge branch 'main' into docs/signing-verification-handler

db594e9

Signed-off-by: Matthias Bruns <git@matthiasbruns.com On-behalf-of: SAP <matthias.bruns@sap.com>

matthiasbruns force-pushed the docs/signing-verification-handler branch from 28624d9 to db594e9 Compare August 27, 2025 10:26

matthiasbruns and others added 2 commits August 27, 2025 12:30

fix: spellcheck

18c3135

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

Merge branch 'main' into docs/signing-verification-handler

05713fd

matthiasbruns requested a review from Copilot August 27, 2025 10:33

Copilot AI reviewed Aug 27, 2025

View reviewed changes

Comment thread docs/adr/0008_signing_verification.md Outdated

Comment thread docs/adr/0008_signing_verification.md Outdated

jakobmoellerdev requested changes Aug 27, 2025

View reviewed changes

Update docs/adr/0008_signing_verification.md

33898da

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fabianburth requested changes Aug 27, 2025

View reviewed changes

matthiasbruns added 3 commits August 27, 2025 16:18

chore: apply feedback on optional cosign, remove upload stuff, refere…

539ae5c

…nce our normalization On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

<Merge branch 'docs/signing-verification-handler' of github.com:matth…

381fd7b

…iasbruns/open-component-model into docs/signing-verification-handler

chore: remove digest details - that's part of another adr

69a5c64

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

matthiasbruns added 2 commits August 29, 2025 11:07

feat: migrate to plugin system

e0596a1

On-behalf-of: SAP <matthias.bruns@sap.com> Signed-off-by: Matthias Bruns <git@matthiasbruns.com>

Merge branch 'main' of github.com:open-component-model/open-component…

538fe83

…-model into docs/signing-verification-handler

jakobmoellerdev mentioned this pull request Sep 1, 2025

chore(docs): add ADR proposal for signing and verification of component descriptors #767

Merged

jakobmoellerdev closed this Sep 1, 2025

		- Computes the component-version digest from canonical bytes.
		- If `--pin` is provided, compares and fails on mismatch.

Conversation

matthiasbruns commented Aug 21, 2025

What this PR does / why we need it

Which issue(s) this PR fixes

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

matthiasbruns commented Aug 27, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jakobmoellerdev Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

matthiasbruns Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jakobmoellerdev Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

matthiasbruns Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

jakobmoellerdev Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fabianburth Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fabianburth Aug 27, 2025

Choose a reason for hiding this comment

Uh oh!

jakobmoellerdev commented Aug 28, 2025

Uh oh!

jakobmoellerdev commented Sep 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants