Debian Codegraph @

pkg/signature/kms/azure/README.md

raw
1 # Azure KMS
2
3 In order to use Azure KMS ([Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/general/basic-concepts)) with the sigstore project you need to have a few things setup in Azure first.
4 The key creation will be handled in sigstore, however the Azure Key Vault and the required permission will have to be configured before.
5
6 ## Azure Prerequisites
7
8 - [Resource Group](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal#what-is-a-resource-group)
9 - [Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/general/basic-concepts)
10 - [Key Vault permissions](https://docs.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
11 - [Container Registry](https://docs.microsoft.com/en-us/azure/container-registry/container-registry-intro) _(not required, but used in below examples)_
12
13 ## Permissions (Access Policies)
14
15 Different commands require different Key Vault access policies. For more information check the official [Azure Docs](https://azure.microsoft.com/en-us/services/key-vault/).
16
17 ## Using Azure KMS with Cosign
18
19 An Azure KMS key must be provided in the following format:
20 `azurekms://[Key Vault Name].vault.azure.net/[Key Name]`
21
22 A specific key version can optionally be provided:
23 `azurekms://[Key Vault Name].vault.azure.net/[Key Name]/[Key Version]`
24
25 ### cosign generate-key-pair
26
27 Required access policies (keys): `get`, `create`
28
29 ```shell
30 cosign generate-key-pair --kms azurekms://[Key Vault Name].vault.azure.net/[Key Name]
31 ```
32
33 ### cosign sign
34
35 Required access policies (keys): `get`, `sign`
36
37 ```shell
38 az acr login --name [Container Registry Name]
39 cosign sign --key azurekms://[Key Vault Name].vault.azure.net/[Key Name] [Container Registry Name].azurecr.io/[Image Name]
40 ```
41
42 ### cosign verify
43
44 Required access policy (keys): `verify`
45
46 ```shell
47 az acr login --name [Container Registry Name]
48 cosign verify --key azurekms://[Key Vault Name].vault.azure.net/[Key Name] [Container Registry Name].azurecr.io/[Image Name]
49 ```
50
51 ## Authentication
52
53 This module uses the [`DefaultCredential` type](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#DefaultAzureCredential)
54 to authenticate. This type supports the following authentication methods:
55
56 1. Environment variables
57 1. Workload identity
58 1. Managed identity
59 1. Azure CLI
60 1. Azure Developer CLI
61
62 See the [official documentation](
63 https://learn.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication?tabs=bash) for more information.
64
65 If you would like to use a cloud other than the Azure public cloud, configure `AZURE_ENVIRONMENT`. The following values are accepted:
66 - `AZUREUSGOVERNMENT`, `AZUREUSGOVERNMENTCLOUD` uses the Azure US Government Cloud
67 - `AZURECHINACLOUD` uses Azure China Cloud
68 - `AZURECLOUD`, `AZUREPUBLICCLOUD` uses the public cloud
69
70 If `AZURE_ENVIRONMENT` is not configured, Azure public cloud is used.
71
72 ## Integration Testing
73
74 In addition to unit tests in this module, there is `integration_test.go`, which requires you to provide either environment or CLI credentials. Because the Sigstore project does not use Azure, the tests are not run as part of any CI/CD. These tests are for Azure client developers to test that changes work as expected against their own Azure subscription.
75
76 Run the integration tests with `go test -tags=integration ./...` in the root of this module.