From 551fa36462278bf6199ce784eb980fd9cca8f3dc Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Fri, 27 Sep 2024 15:55:48 +0800 Subject: [PATCH] docs: updated README.md based on v1.2.0 (#85) Signed-off-by: Patrick Zheng --- README.md | 60 ++++++++++++++++++++++++------------------------------- 1 file changed, 26 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index d24169c..f4cea3d 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,9 @@ Currently, [Azure Key Vault plugin for Notation](https://github.com/Azure/notati target_artifact_reference: signature_format: plugin_config: - allow_referrers_api: + force_referrers_tag: + timestamp_url: + timestamp_root_cert: ```
@@ -62,7 +64,7 @@ Currently, [Azure Key Vault plugin for Notation](https://github.com/Azure/notati See an example (Click here). ```yaml -- name: sign releasd artifact with notation-azure-kv plugin +- name: sign releasd artifact with notation-azure-kv plugin and timestamping uses: notaryproject/notation-action/sign@v1 with: plugin_name: azure-kv @@ -70,12 +72,14 @@ Currently, [Azure Key Vault plugin for Notation](https://github.com/Azure/notati plugin_checksum: 06bb5198af31ce11b08c4557ae4c2cbfb09878dfa6b637b7407ebc2d57b87b34 key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd target_artifact_reference: |- - myRegistry.azurecr.io/myRepo@sha256:aaabbb - myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd + myregistry.azurecr.io/myrepo@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + myotherregistry.azurecr.io/myotherrepo@sha256:aaad27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcaaa signature_format: cose plugin_config: |- ca_certs=.github/cert-bundle/cert-bundle.crt self_signed=false + timestamp_url: http://my.trusted.timestamp.authority.wabbit-networks.io + timestamp_root_cert: .github/cert-bundle/tsa-root.crt ``` Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers) in signing: @@ -83,17 +87,15 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut ```yaml - name: sign releasd artifact with notation-azure-kv plugin uses: notaryproject/notation-action/sign@v1 - env: - NOTATION_EXPERIMENTAL: 1 # this is required by Notation to use Referrers API with: - allow_referrers_api: 'true' + force_referrers_tag: 'false' # use referrers api first, if supported. plugin_name: azure-kv plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.2.0/notation-azure-kv_1.2.0_linux_amd64.tar.gz plugin_checksum: 06bb5198af31ce11b08c4557ae4c2cbfb09878dfa6b637b7407ebc2d57b87b34 key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd target_artifact_reference: |- - myRegistry.azurecr.io/myRepo@sha256:aaabbb - myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd + myregistry.azurecr.io/myrepo@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + myotherregistry.azurecr.io/myotherrepo@sha256:aaad27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcaaa signature_format: cose plugin_config: |- ca_certs=.github/cert-bundle/cert-bundle.crt @@ -111,9 +113,11 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut target_artifact_reference: trust_policy: trust_store: - allow_referrers_api: ``` +> [!Note] +> For Notation CLI v1.2.0 or later, verify always uses the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers) first, if Referrers API is not supported, automatically fallback to the [Referrers tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#referrers-tag-schema). +
See an example (Click here). @@ -123,15 +127,15 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut uses: notaryproject/notation-action/verify@v1 with: target_artifact_reference: |- - myRegistry.azurecr.io/myRepo@sha256:aaabbb - myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd + myregistry.azurecr.io/myrepo@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 + myotherregistry.azurecr.io/myotherrepo@sha256:aaad27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcaaa trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ``` > [!NOTE] -> - `.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-policy). -> - `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store). See an example of trust store below. +> - `.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.1.0/specs/trust-store-trust-policy.md#trust-policy). +> - `.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.1.0/specs/trust-store-trust-policy.md#trust-store). See an example of trust store below. ``` .github/truststore @@ -140,26 +144,14 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut │ └── │ ├── │ └── - └── signingAuthority - └── - ├── - └── -``` - -Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers) in verification: - -```yaml -- name: verify released artifact - uses: notaryproject/notation-action/verify@v1 - env: - NOTATION_EXPERIMENTAL: 1 # this is required by Notation to use Referrers API - with: - allow_referrers_api: 'true' - target_artifact_reference: |- - myRegistry.azurecr.io/myRepo@sha256:aaabbb - myOtherRegistry.azurecr.io/myOtherRepo@sha256:cccddd - trust_policy: .github/trustpolicy/trustpolicy.json - trust_store: .github/truststore + ├── signingAuthority + | └── + | ├── + | └── + └── tsa + └── + ├── + └── ```