Roll or rotate a Customer Key or an availability key

  • Article

Caution

Only roll an encryption key that you use with Customer Key when your security or compliance requirements dictate that you must roll the key. Do not delete or disable any keys that are or were associated with policies, including older versions of keys that you used. When you roll your keys, there is content encrypted with the previous keys. For example, while active mailboxes are re-encrypted frequently, inactive, disconnected, and disabled mailboxes may still be encrypted with the previous keys. Microsoft SharePoint performs backup of content for restore and recovery purposes, so there may still be archived content using older keys.

Tip

If you're not an E5 customer, use the 90-day Microsoft Purview solutions trial to explore how additional Purview capabilities can help your organization manage data security and compliance needs. Start now at the Microsoft Purview compliance portal trials hub. Learn details about signing up and trial terms.

Windows 365 support for Microsoft Purview Customer Key is in public preview and is subject to change.

About rolling the availability key

Microsoft doesn't expose direct control of the availability key to customers. For example, you can only roll (rotate) the keys that you own in Azure Key Vault. Microsoft 365 rolls the availability keys on an internally defined schedule. There is no customer-facing, service-level agreement (SLA) for these key rolls. Microsoft 365 rotates the availability key using Microsoft 365 service code in an automated process. Microsoft administrators may initiate the roll process. The key is rolled using automated mechanisms without direct access to the key store. Access to the availability key secret store isn't provisioned to Microsoft administrators. Availability key rolling applies the same mechanism used to initially generate the key. For more information about the availability key, see Understand the availability key.

Important

Exchange Online availability keys can be effectively rolled by customers creating a new DEP, since a unique availability key is generated for each DEP you create. Availability keys for SharePoint, Microsoft OneDrive for work or school, and Teams files exist at the forest level and are shared across DEPs and customers, which means rolling only occurs at a Microsoft internally defined schedule. To mitigate the risk of not rolling the availability key each time a new DEP is created, SharePoint, OneDrive, and Teams roll the tenant intermediate key (TIK), the key wrapped by the customer root keys and availability key, each time a new DEP is created.

About rolling customer managed root keys

There are two ways to roll customer managed root keys: updating existing keys by requesting a new version of the key and refreshing the DEP, or creating and using a newly generated key and DEP. Instructions for each method of rolling your keys are found in the following section.

Request a new version of each existing root key you want to roll

To request a new version of an existing key, you use the same cmdlet, Add-AzKeyVaultKey, with the same syntax and key name that you originally used to create the key. After you've finished rolling any key associated with a Data Encryption Policy (DEP), you run another cmdlet to refresh the existing DEP to ensure that Customer Key uses the new key. Do this step in each Azure Key Vault (AKV).

For example:

  1. Sign in to your Azure subscription with Azure PowerShell. For instructions, see Sign in with Azure PowerShell.

  2. Run the Add-AzKeyVaultKey cmdlet as shown in the following example:

    Add-AzKeyVaultKey -VaultName Contoso-CK-EX-NA-VaultA1 -Name Contoso-CK-EX-NA-VaultA1-Key001 -Destination HSM -KeyOps @('wrapKey','unwrapKey') -NotBefore (Get-Date -Date "12/27/2016 12:01 AM")

    In this example, since a key named Contoso-CK-EX-NA-VaultA1-Key001 exists in the Contoso-CK-EX-NA-VaultA1 vault, the cmdlet creates a new version of the key. This operation preserves the previous key versions in the version history for the key. You need the previous key version to decrypt the data that it still encrypts. Once you complete rolling any key associated with a DEP, run an extra cmdlet to ensure that Customer Key begins using the new key. The following sections describe the cmdlets in more detail.

    Update the keys for multi-workload DEPs

    When you roll either of the Azure Key Vault keys associated with a DEP used with multiple workloads, you must update the DEP to point to the new key. This process doesn't rotate the availability key. The DataEncryptionPolicyID property doesn't change when you update it with a new version of the same key.

    To instruct Customer Key to use the new key to encrypt multiple workloads, complete these steps:

    1. On your local computer, using a work or school account that has global administrator or compliance admin permissions in your organization, connect to Exchange Online PowerShell.

    2. Run the Set-M365DataAtRestEncryptionPolicy cmdlet:

      Set-M365DataAtRestEncryptionPolicy -Identity <Policy>  -Refresh

      Where Policy is the name or unique ID of the policy.

    Update the keys for Exchange Online DEPs

    When you roll either of the Azure Key Vault keys associated with a DEP used with Exchange Online, you must update the DEP to point to the new key. This action doesn't rotate the availability key. The DataEncryptionPolicyID property for the mailbox doesn't change when you update it with a new version of the same key.

    To instruct Customer Key to use the new key to encrypt mailboxes, complete these steps:

    1. On your local computer, using a work or school account that has global administrator or compliance admin permissions in your organization, connect to Exchange Online PowerShell.

    2. Run the Set-DataEncryptionPolicy cmdlet:

        Set-DataEncryptionPolicy -Identity <Policy> -Refresh

      Where Policy is the name or unique ID of the policy.

Using a newly generated key for your DEP

When opting to use newly generated keys instead of updating existing ones, the process for updating your data encryption policies differs. Rather than refreshing an existing policy, you need to create and assign a new data encryption policy tailored to the new key.

  1. In order to create a new key and add it to your key vault, follow the instructions found in Add a key to each key vault by either creating or importing a key.

  2. Once added to your key vault, you must create a new data encryption policy with the key URI of the newly created key. Instructions on the creating and assigning data encryption policies can be found in Manage Customer Key for Microsoft 365.

Update the keys for SharePoint, OneDrive for work or school, and Teams files

SharePoint only allows you to roll one key at a time. If you want to roll both keys in a key vault, wait for the first operation to complete. Microsoft recommends that you stagger your operations to avoid this issue. When you roll either of the Azure Key Vault keys associated with a DEP used with SharePoint and OneDrive for work or school, you must update the DEP to point to the new key. This action doesn't rotate the availability key.

  1. Run the Update-SPODataEncryptionPolicy cmdlet as follows:

    Update-SPODataEncryptionPolicy  <SPOAdminSiteUrl> -KeyVaultName <ReplacementKeyVaultName> -KeyName <ReplacementKeyName> -KeyVersion <ReplacementKeyVersion> -KeyType <Primary | Secondary>

    While this cmdlet starts the key roll operation for SharePoint and OneDrive for work or school, the action doesn't complete immediately.

  2. To see the progress of the key roll operation, run the Get-SPODataEncryptionPolicy cmdlet as follows:

    Get-SPODataEncryptionPolicy <SPOAdminSiteUrl>