| 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. |