docs: proposal for signing and verifying OSS release assets#1265
docs: proposal for signing and verifying OSS release assets#1265JeyJeyGao wants to merge 8 commits into
Conversation
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
JeyJeyGao
requested review from
NiazFK,
gokarnm,
priteshbandi,
rgnote,
shizhMSFT and
toddysm
as code owners
There was a problem hiding this comment.
Pull Request Overview
This PR proposes a new vendor-neutral signing solution and a simplified, stateless verification mode for OSS release assets to enhance Notation's usability for community users.
- Introduces a new proposal document detailing the signing and verification design.
- Updates command documentation to add new flags and usage examples for stateless verification in the blob verify command.
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| specs/proposals/oss-release-signing.md | New proposal document outlining the enhancements for OSS release signing. |
| specs/cmd/blob.md | Updates to the blob verify command documentation with new flags and examples. |
Comments suppressed due to low confidence (2)
specs/cmd/blob.md:190
- [nitpick] Consider verifying if 'stringArray' is the correct type for trusted identity. If typically only one identity is expected, updating the type to 'string' or clarifying that multiple identities are supported could improve clarity.
--trusted-identity stringArray trusted identity for the signing certificate (e.g., x509.subject:...) for stateless verification
specs/cmd/blob.md:596
- [nitpick] Replace the placeholder 'xxxx' in the certificate URL with a more descriptive placeholder (e.g., ) to reduce confusion in examples.
--certificate-url "https://raw.githubusercontent.com/xxxx/refs/tags/v0.1.0/notation.crt" \
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1265 +/- ##
=======================================
Coverage 76.96% 76.96%
=======================================
Files 68 68
Lines 3847 3847
=======================================
Hits 2961 2961
Misses 682 682
Partials 204 204 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
JeyJeyGao
changed the title
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
Signed-off-by: Junjie Gao <junjiegao@microsoft.com>
There was a problem hiding this comment.
Pull Request Overview
This PR introduces documentation changes to propose and support enhanced OSS release asset signing and verification. The changes include a new proposal outlining a vendor-neutral signing solution using a local encrypted key and simplified stateless verification, and updates to the CLI documentation adding new flags and examples for the stateless verification mode.
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| specs/proposals/oss-release-signing.md | Added a proposal document detailing the new signing plugin and simplified verification mode. |
| specs/cmd/blob.md | Updated CLI documentation with new flag definitions and usage examples for stateless verification. |
Comments suppressed due to low confidence (1)
specs/proposals/oss-release-signing.md:68
- The CLI example uses '--plugin signer' while the proposal refers to the signing plugin as 'notation-signer'. Consider renaming the flag value to 'notation-signer' for consistency with the proposal documentation.
notation blob sign --id signer --plugin signer \
| **Desired User Experience / CLI Operation:** | ||
| 1. The publisher obtains a private key `notation.key` with a certificate bundle `notation.pem`, either self-signed or CA-issued. | ||
| 2. Download the `notation-signer` plugin locally, and call `encrypt` command with password to get an encrypted key `notation.key.enc`. | ||
| ```sh | ||
| # on local machine | ||
| notation-signer encrypt notation.key | ||
| ``` | ||
| 3. The publisher adds the content of the encrypted key `notation.key.enc` and the password to the CI workflow secret (GitHub Action Secret), then exports them as environment variables `NOTATION_SIGNER_KEY` and `NOTATION_SIGNER_KEY_PASSWORD` later for the `notation` binary. | ||
| 4. Configure the release workflow to set up `notation` with the `notation-signer` plugin. | ||
| 5. Export the secrets as environment variables for notation and call the `notation blob sign` command to sign the release asset: | ||
| ```sh | ||
| # on CI workflow | ||
| notation blob sign --id signer --plugin signer \ | ||
| --plugin-config certificate_bundle_path=./notation.pem \ | ||
| <release-asset-path> | ||
| ``` | ||
| 6. The publisher attaches the assets, along with their signatures, to the release page. |
There was a problem hiding this comment.
I do have a concern regarding step 1, where user needs to bring their own private key. A leak of this private key could be a severe security issue. I'm thinking if we can give notation-signer the capability to generate a key pair, so that the signer can generate their key pair in the CI release pipeline on the fly. This private key is short-lived and won't be stored anywhere in the whole process.
Take GitHub release as an example:
- The publisher would like to release their assets through a GitHub workflow. In this workflow, they will need to install Notation CLI and notation-signer plugin.
- The next step would be using the notation-signer plugin to generate a key pair on the fly, sign their assets with the private key, throw away the private key once signing is completed, i.e., do not store the private key anywhere outside the CI pipeline as it's not needed in future verification.
- In the end, the assets, the signature, and the certificate containing the public key is released. (the signing certificate is a part of the certificate chain in the signature).
There was a problem hiding this comment.
I understand your concern, so we have step 2 to encrypt the key. After step 2, the original key can be removed. The risk of leaking the key will be low as we have password encryption.
Regarding your suggestion, I think the critical issue is ensuring authenticity. Every release has a new certificate, which serves as the trust anchor and proves authenticity. Publishing the signature with the certificate is very risky. As you know, our signature includes the certificate chain, so using the certificate published with the signature is similar to using the certificate in the signature directly. We should put the signature and certificate in different trust sources.
If we prefer a short-lived certificate, we should have a way to ensure authenticity. OIDC is a solution since the signing step needs to authenticate the signer's identity, but that is another story.
There was a problem hiding this comment.
I understand your concern, so we have step 2 to encrypt the key. After step 2, the original key can be removed. The risk of leaking the key will be low as we have password encryption.
The nature of letting the user deal with their own private key is not secure. This is the fundamental reason that we use key vaults in other Notation plugins. In addition, it is more convenient to generate the key pair on the fly. User won't need to worry about how to store/remove their private keys.
Regarding your suggestion, I think the critical issue is ensuring authenticity. Every release has a new certificate, which serves as the trust anchor and proves authenticity. Publishing the signature with the certificate is very risky. As you know, our signature includes the certificate chain, so using the certificate published with the signature is similar to using the certificate in the signature directly. We should put the signature and certificate in different trust sources.
What do you mean by Publishing the signature with the certificate is very risky? The verifier needs the public key to verify the signature, the certificate chain contains the signing certificate and is published along with the signature right (as an unprotected header)?
JeyJeyGao
changed the title
There was a problem hiding this comment.
Pull Request Overview
This PR proposes documentation improvements to describe a new vendor-neutral signer plugin and introduces a simplified, stateless verification mode for OSS release assets.
- Added a detailed design proposal in specs/proposals/oss-release-signing.md outlining the signing and verification process.
- Updated the command documentation in specs/cmd/blob.md to include new flags and examples for stateless verification mode.
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| specs/proposals/oss-release-signing.md | New proposal document detailing the signing process, key management, and verification challenges. |
| specs/cmd/blob.md | Added flags and examples to support stateless verification using both remote and local certificates. |
Comments suppressed due to low confidence (2)
specs/proposals/oss-release-signing.md:69
- [nitpick] The proposal uses 'notation.pem' for the certificate bundle, while the verification examples in specs/cmd/blob.md use 'notation.crt'. Consider aligning the certificate file naming for clarity.
notation blob sign --plugin-config certificate_bundle_path=./notation.pem \
specs/cmd/blob.md:609
- [nitpick] The verification example uses 'notation.crt' for the certificate file, which differs from the 'notation.pem' mentioned in the proposal. For consistency, consider using a single naming convention across the documentation.
--certificate-path "./notation.crt" \
ghost
left a comment
ghost
left a comment
There was a problem hiding this comment.
We need further discussion on the proposal.
|
Let me know when it is ready for review. Thanks. |
Provide solution for issues:
Sign Notation CLI release assets with Notation GitHub Actions #973
Support using signing key from GitHub Encrypted Secret #905
Signing with local private keys #539
ux: broken default
notation verifyexperience: #430