From c966ea4c66770f8bd7bb7997ebb37f7492123896 Mon Sep 17 00:00:00 2001 From: Feynman Zhou Date: Wed, 20 Sep 2023 13:57:44 +0800 Subject: [PATCH] update README Signed-off-by: Feynman Zhou --- README.md | 60 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9d7288c..f65e490 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,15 @@ The following three actions are available: ## Usage -Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Notation](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html), [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push), [HashiCorp Vault plugin](https://github.com/notaryproject/notation-hashicorp-vault/pulls). Currently, [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push) has been well tested in the Notation Github Actions by the sub-project maintainers. You can submit test cases and examples for other plugins. +Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Notation](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html), [Azure Key Vault for Notation](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-sign-build-push), [HashiCorp Vault plugin](https://github.com/notaryproject/notation-hashicorp-vault/pulls). + +Currently, [Azure Key Vault plugin for Notation](https://github.com/Azure/notation-azure-kv) has been well tested in the Notation Github Actions by the sub-project maintainers. See this [doc](https://github.com/notation-playground/notation-integration-with-ACR-and-AKV/blob/main/sign-action.md) for hands-on steps if you want to use Notation with the AKV plugin. You can submit test cases and examples for other plugins here. + +### Notation Setup -### Notation: Setup ```yaml - name: setup Notation CLI - uses: notaryproject/notation-action/setup@main + uses: notaryproject/notation-action/setup@v1 with: version: url: @@ -30,17 +33,18 @@ Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Not ```yaml - name: setup Notation CLI - uses: notaryproject/notation-action/setup@main + uses: notaryproject/notation-action/setup@v1 with: version: "1.0.0" ``` -### Notation: Sign +### Notation Sign + ```yaml - name: sign releasd artifact with signing plugin - uses: notaryproject/notation-action/sign@main + uses: notaryproject/notation-action/sign@v1 with: plugin_name: plugin_url: @@ -58,11 +62,11 @@ Signing an image relies on a Notation plugin, such as [AWS Signer plugin for Not ```yaml - name: sign releasd artifact with notation-azure-kv plugin - uses: notaryproject/notation-action/sign@main + uses: notaryproject/notation-action/sign@v1 with: plugin_name: azure-kv - plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.0.0/notation-azure-kv_1.0.0_linux_amd64.tar.gz - plugin_checksum: 82d4fee34dfe5e9303e4340d8d7f651da0a89fa8ae03195558f83bb6fa8dd263 + plugin_url: https://github.com/Azure/notation-azure-kv/releases/download/v1.0.1/notation-azure-kv_1.0.1_linux_amd64.tar.gz + plugin_checksum: f8a75d9234db90069d9eb5660e5374820edf36d710bd063f4ef81e7063d3810b key_id: https://testnotationakv.vault.azure.net/keys/notationLeafCert/c585b8ad8fc542b28e41e555d9b3a1fd target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb signature_format: cose @@ -75,9 +79,9 @@ 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@main + uses: notaryproject/notation-action/sign@v1 env: - NOTATION_EXPERIMENTAL: 1 # this is requried by Notation to use Referrers API + NOTATION_EXPERIMENTAL: 1 # this is required by Notation to use Referrers API with: allow_referrers_api: 'true' plugin_name: azure-kv @@ -93,10 +97,11 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut -### Notation: Verify +### Notation Verify + ```yaml - name: verify released artifact - uses: notaryproject/notation-action/verify@main + uses: notaryproject/notation-action/verify@v1 with: target_artifact_reference: trust_policy: @@ -108,18 +113,18 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut See an example (Click here). -`.github/trustpolicy/trustpolicy.json` MUST follow the Notation [trust policy specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy). - ```yaml - name: verify released artifact - uses: notaryproject/notation-action/verify@main + uses: notaryproject/notation-action/verify@v1 with: target_artifact_reference: myRegistry.azurecr.io/myRepo@sha256:aaabbb trust_policy: .github/trustpolicy/trustpolicy.json trust_store: .github/truststore ``` -`.github/truststore` MUST follow the Notation [trust store specs](https://github.com/notaryproject/specifications/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-store). For example, +> [!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 └── x509 @@ -133,13 +138,16 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut └── ``` +> [!NOTE] +> `.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). + Example of using the [Referrers API](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc.3/spec.md#listing-referrers) in verification: ```yaml - name: verify released artifact - uses: notaryproject/notation-action/verify@main + uses: notaryproject/notation-action/verify@v1 env: - NOTATION_EXPERIMENTAL: 1 # this is requried by Notation to use Referrers API + 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 @@ -148,3 +156,17 @@ Example of using the [Referrers API](https://github.com/opencontainers/distribut ``` + +## Authentication + +To sign and verify an image stored in the private registry with Notation GitHub Actions, you need to authenticate with the registry and KMS (Key Management Service). See the following authentication options for references. + +### Registry authentication + +- Use [Docker login GitHub Action](https://github.com/marketplace/actions/docker-login). +- Use vendor-based login GitHub Action, such as [Amazon ECR "Login" Action for GitHub Actions](https://github.com/marketplace/actions/amazon-ecr-login-action-for-github-actions), [GitHub Action for Azure Login](https://github.com/marketplace/actions/azure-login) or [Azure Container Registry Login GitHub Actions](https://github.com/marketplace/actions/azure-container-registry-login). + +### KMS authentication + +If you use a signing key and certificate stored in a KMS, make sure to authenticate with the KMS before signing this image in your GitHub Actions workflow. +