|
| 1 | +--- |
| 2 | +title: Customer-managed keys - overview |
| 3 | +description: Learn about the customer-managed keys, an overview on its key features and considerations before you encrypt your Premium registry with a customer-managed key stored in Azure Key Vault. |
| 4 | +ms.topic: tutorial |
| 5 | +ms.date: 08/5/2022 |
| 6 | +ms.author: tejaswikolli |
| 7 | +--- |
| 8 | + |
| 9 | +# Tutorial: An overview of a customer-managed key encryption for your Azure Container Registry |
| 10 | + |
| 11 | +Azure Container Registry, automatically encrypts the images and other artifacts you store. By default, Azure automatically encrypts the registry content at rest with [service-managed keys](../security/fundamentals/encryption-models.md). You can supplement default encryption with an additional encryption layer using a customer-managed key. |
| 12 | + |
| 13 | + |
| 14 | +In this tutorial, part one in a four-part series: |
| 15 | + |
| 16 | +> [!div class="checklist"] |
| 17 | +> * customer-managed key - Overview |
| 18 | +> * Enable a customer-managed key - CLI, Portal, and Resource Manager Template |
| 19 | +> * Rotate and revoke a customer-managed key |
| 20 | +> * Troubleshoot a customer-managed key |
| 21 | +
|
| 22 | +## About customer-managed key |
| 23 | + |
| 24 | +A customer-managed key gives you the ownership to bring your own key in the [Azure Key Vault](../key-vault/general/overview.md). The customer-managed key also allows you to manage key rotations, controls the access and permissions to use the key, and audit the usage of the key. |
| 25 | + |
| 26 | +The key features include: |
| 27 | + |
| 28 | +>* **Regulatory compliance standards**: By default, Azure automatically encrypts the registry content at rest with [service-managed keys,](../security/fundamentals/encryption-models.md) but customer-managed keys encryption meets the guidelines of standard regulatory compliance. |
| 29 | +
|
| 30 | +>* **Integration with Azure key vault**: Customer-managed keys support server-side encryption through integration with [Azure Key Vault.](../key-vault/general/overview.md). With customer-managed keys, you can create your own encryption keys and store them in an Azure Key Vault, or you can use Azure Key Vault APIs to generate keys. |
| 31 | +
|
| 32 | +>* **Key life cycle management**: Integrating customer-managed keys with [Azure Key Vault](../key-vault/general/overview.md), will give you full control and responsibility for the key lifecycle, including rotation and management. |
| 33 | +
|
| 34 | +## Before you enable a customer-managed key |
| 35 | + |
| 36 | +Configure Azure Container Registry (ACR) with a customer-managed key consider knowing: |
| 37 | + |
| 38 | +>* This feature is available in the **Premium** container registry service tier. For more information, see [ACR service tiers.](container-registry-skus.md) |
| 39 | +>* You can currently enable a customer-managed key only while creating a registry. |
| 40 | +>* You can't disable the encryption after enabling a customer-managed key on a registry. |
| 41 | +>* You have to configure a *user-assigned* managed identity to access the key vault. Later, if required you can enable the registry's *system-assigned* managed identity for key vault access. |
| 42 | +>* Azure Container Registry supports only RSA or RSA-HSM keys. Elliptic curve keys aren't currently supported. |
| 43 | +>* In a registry encrypted with a customer-managed key, you can retain logs for [ACR Tasks](container-registry-tasks-overview.md) only for 24 hours. To retain logs for a longer period, see guidance to [export and store task run logs.](container-registry-tasks-logs.md#alternative-log-storage) |
| 44 | +>* [Content trust](container-registry-content-trust.md) is currently not supported in a registry encrypted with a customer-managed key. |
| 45 | +
|
| 46 | +## Update the customer-managed key version |
| 47 | + |
| 48 | +Azure Container Registry supports both automatic and manual rotation of registry encryption keys when a new key version is available in Azure Key Vault. |
| 49 | + |
| 50 | +>[!IMPORTANT] |
| 51 | +>It is an important security consideration for a registry with customer-managed key encryption to frequently update (rotate) the key versions. Follow your organization's compliance policies to regularly update [key versions,](../key-vault/general/about-keys-secrets-certificates.md#objects-identifiers-and-versioning) while storing a customer-managed key in Azure Key Vault. |
| 52 | +
|
| 53 | +* **Automatically update the key version** - With a registry encrypted with a non-versioned key, Azure Container Registry regularly checks the Azure key vault for a new key version and updates the customer-managed key within 1 hour. So, we suggest omitting the key version when you enable registry encryption with a customer-managed key. So, that ACR automatically uses and updates to the latest key version. |
| 54 | + |
| 55 | +* **Manually update the key version** - With a registry encrypted with a specific key version, Azure Container Registry uses that version for encryption until you manually rotate the customer-managed key. So, we suggest specifying the key version when you enable registry encryption with a customer-managed key. So, that ACR will use a specific version of a key for registry encryption. |
| 56 | + |
| 57 | +For details, see [Choose key ID with version](tutorial-enable-customer-managed-keys.md#option-1-manual-key-rotation---key-id-with-version) , or [Choose key ID without key version](tutorial-enable-customer-managed-keys.md#option-2-automatic-key-rotation---key-id-omitting-version), and [Update key version](tutorial-rotate-revoke-customer-managed-keys.md#create-or-update-key-version---cli) later in this tutorial. |
| 58 | + |
| 59 | +## Next steps |
| 60 | + |
| 61 | +In this tutorial, you have an overview on a customer-managed keys, their key features, and a brief of the considerations to enable a customer-managed key to your registry and types of updating key versions. |
| 62 | + |
| 63 | +Advance to the next [tutorial](tutorial-enable-customer-managed-keys.md) to enable your container registry with a customer-managed keys using Azure CLI, Azure portal, and Azure Resource Manager template. |
| 64 | +* Learn more about [encryption at rest in Azure](../security/fundamentals/encryption-atrest.md). |
| 65 | +* Learn more about access policies and how to [secure access to a key vault](../key-vault/general/security-features.md). |
| 66 | + |
| 67 | + |
| 68 | +<!-- LINKS - external --> |
| 69 | + |
| 70 | +<!-- LINKS - internal --> |
| 71 | + |
| 72 | +[az-feature-register]: /cli/azure/feature#az_feature_register |
| 73 | +[az-feature-show]: /cli/azure/feature#az_feature_show |
| 74 | +[az-group-create]: /cli/azure/group#az_group_create |
| 75 | +[az-identity-create]: /cli/azure/identity#az_identity_create |
| 76 | +[az-feature-register]: /cli/azure/feature#az_feature_register |
| 77 | +[az-deployment-group-create]: /cli/azure/deployment/group#az_deployment_group_create |
| 78 | +[az-keyvault-create]: /cli/azure/keyvault#az_keyvault_create |
| 79 | +[az-keyvault-key-create]: /cli/azure/keyvault/key#az_keyvault_key_create |
| 80 | +[az-keyvault-key]: /cli/azure/keyvault/key |
| 81 | +[az-keyvault-set-policy]: /cli/azure/keyvault#az_keyvault_set_policy |
| 82 | +[az-keyvault-delete-policy]: /cli/azure/keyvault#az_keyvault_delete_policy |
| 83 | +[az-resource-show]: /cli/azure/resource#az_resource_show |
| 84 | +[az-acr-create]: /cli/azure/acr#az_acr_create |
| 85 | +[az-acr-show]: /cli/azure/acr#az_acr_show |
| 86 | +[az-acr-encryption-rotate-key]: /cli/azure/acr/encryption#az_acr_encryption_rotate_key |
| 87 | +[az-acr-encryption-show]: /cli/azure/acr/encryption#az_acr_encryption_show |
0 commit comments