Deelen iwwer

Roll or rotate a Customer Key or an availability key

Caution

Roll an encryption key used with Customer Key only if required by your organization's security or compliance policies.

Do not delete or disable any keys, including older versions, that are or were associated with SharePoint encryption policies.

For example:

  • SharePoint retains backup content for restore and recovery, which might also rely on older keys.

Prerequisites

Before you roll or rotate keys, ensure you have:

Important

Microsoft recommends that you use roles with the fewest permissions. Minimizing the number of users with the Global Administrator role helps improve security for your organization. Learn more about Microsoft Purview roles and permissions.

Quick reference: Commands by workload

Use the following table to quickly find the command you need based on your workload and scenario.

Workload Scenario Command
Multi-workload Refresh DEP with new key version Set-M365DataAtRestEncryptionPolicy -Identity <Policy> -Refresh
Multi-workload Replace keys in DEP Set-M365DataAtRestEncryptionPolicy -Identity <Policy> -Replace -AzureKeyIDs <KeyURI1>,<KeyURI2>
Exchange Refresh DEP with new key version Set-DataEncryptionPolicy -Identity <Policy> -Refresh
Exchange Replace keys in DEP Set-DataEncryptionPolicy -Identity <Policy> -Replace -AzureKeyIDs <KeyURI1>,<KeyURI2>
SharePoint/OneDrive Roll/Rotate a key Update-SPODataEncryptionPolicy <SPOAdminSiteUrl> -KeyVaultName <Name> -KeyName <Name> -KeyVersion <Version> -KeyType <Primary \| Secondary>
SharePoint/OneDrive Check roll progress Get-SPODataEncryptionPolicy <SPOAdminSiteUrl>
Azure Key Vault Create new key version Add-AzKeyVaultKey -VaultName <VaultName> -Name <KeyName> -Destination HSM -KeyOps @('wrapKey','unwrapKey')

Choose your key rolling method

There are two ways to roll customer-managed root keys. Use this guidance to determine which method is right for your scenario.

Method When to use What happens
Update existing key (create new version) Routine key rotation; maintaining the same key name Creates a new version of the existing key. The DEP references the same key name but uses the new version after refresh.
Replace with new key Compromised key; changing key vault; organizational restructuring Creates an entirely new key with a new name. The DEP is updated to reference the new key URIs.

About rolling the availability key

Microsoft doesn't provide customers with direct control over the availability key. For example, you can only roll the keys you manage in Azure Key Vault.

Microsoft 365 rolls the availability key on an internal schedule. There's no customer-facing service-level agreement (SLA) for these key rotations. Microsoft 365 uses service code to rotate the availability key automatically. In some cases, Microsoft administrators can initiate the process, but the key is rolled through automated mechanisms that don't allow direct access to the key store.

Microsoft administrators don't have provisioned access to the availability key secret store. The rolling process uses the same mechanism that generates the key during initial provisioning.

For more information, see Understand the availability key.

Important

For Exchange, you can effectively roll the availability key by creating a new data encryption policy (DEP). Each new DEP generates a unique availability key.

In contrast, availability keys for Customer Key in SharePoint and OneDrive are created at the forest level and shared across DEPs and customers. These keys are rolled only on a Microsoft-defined internal schedule.

To reduce the risk of not rolling the availability key with each new DEP, SharePoint, OneDrive, and Teams roll the tenant intermediate key (TIK) every time you create a new DEP. The TIK is the key wrapped by both the customer root keys and the availability key.

Roll customer-managed root keys

Method 1: Update an existing key (create a new version)

Use this method to create a new version of an existing key. This approach is recommended for routine key rotations.

Step 1: Create a new key version in Azure Key Vault

To request a new version of an existing key, use the Add-AzKeyVaultKey cmdlet with the same key name you used when creating the original key.

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

  2. Run the Add-AzKeyVaultKey cmdlet:

    Add-AzKeyVaultKey -VaultName <VaultName> -Name <KeyName> -Destination HSM -KeyOps @('wrapKey','unwrapKey') -NotBefore (Get-Date)

    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, a key named Contoso-CK-EX-NA-VaultA1-Key001 already exists in the Contoso-CK-EX-NA-VaultA1 vault. The cmdlet creates a new version of the key. Previous versions are retained in the key's version history.

  3. Repeat this step in each Azure Key Vault that contains keys you want to roll.

Step 2: Refresh the DEP to use the new key version

After creating a new key version, you must refresh the DEP to instruct Customer Key to use the new version.

For Multi-workload DEPs

  1. Connect to Exchange Online PowerShell using a work or school account with the appropriate permissions. For instructions, see Connect to Exchange Online PowerShell.

  2. Run the Set-M365DataAtRestEncryptionPolicy cmdlet:

    Set-M365DataAtRestEncryptionPolicy -Identity <Policy> -Refresh
    Parameter Description
    -Identity Unique name or GUID of the data encryption policy

    Note

    The DataEncryptionPolicyID property remains the same when updating the DEP with a new version of the same key. This action doesn't rotate the availability key.

For Exchange DEPs

  1. Connect to Exchange Online PowerShell using a work or school account with the appropriate permissions. For instructions, see Connect to Exchange Online PowerShell.

  2. Run the Set-DataEncryptionPolicy cmdlet:

    Set-DataEncryptionPolicy -Identity <Policy> -Refresh
    Parameter Description
    -Identity Unique name or GUID of the data encryption policy

    Note

    The DataEncryptionPolicyID property for the mailbox stays the same when updating the policy with a new version of the same key. This action doesn't rotate the availability key.

For SharePoint and OneDrive DEPs

SharePoint supports rolling only one key at a time. If you plan to roll both keys in a key vault, wait for the first operation to finish before starting the second. To avoid conflicts, Microsoft recommends staggering your operations.

  1. Run the Update-SPODataEncryptionPolicy cmdlet:

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

    This cmdlet starts the key roll operation, but the change doesn't take effect immediately.

  2. For keys stored in a Managed HSM, use -KeyVaultURL instead:

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

  3. To check the progress of the key roll operation, run:

    Get-SPODataEncryptionPolicy <SPOAdminSiteUrl>

Method 2: Replace keys with newly generated keys

Use this method when you need to replace existing keys entirely with new keys.

Important

Ensure that old keys remain enabled and accessible to Microsoft 365 services until the replacement process is fully completed.

  1. Connect to Exchange Online PowerShell using a work or school account with the appropriate permissions. For instructions, see Connect to Exchange Online PowerShell.

  2. Run the appropriate cmdlet based on your DEP type:

    For Exchange DEPs:

    Set-DataEncryptionPolicy -Identity <Policy> -Replace -AzureKeyIDs <KeyURI1>,<KeyURI2>

    For Multi-workload DEPs:

    Set-M365DataAtRestEncryptionPolicy -Identity <Policy> -Replace -AzureKeyIDs <KeyURI1>,<KeyURI2>
    Parameter Description
    -Identity Unique name or GUID of the data encryption policy
    -AzureKeyIDs Comma-separated URIs of the Azure Key Vault keys to use

    Example:

    Set-M365DataAtRestEncryptionPolicy -Identity ExampleDEP -Replace -AzureKeyIDs https://contoso_eastusvault02.vault.azure.net/keys/USA_key_01,https://contoso_eastusvault01.vault.azure.net/keys/USA_key_02

Note

The order of KeyURI1 and KeyURI2 doesn't matter. If you want to replace only one key while keeping the other, still provide the URI of both keys when running the command.

Caution

Wait 24 hours after you replace the keys before you disable and delete the keys that are no longer in use. After an additional 24-48 hours, if no issues are observed with Microsoft 365 services, purge the unused keys.

Verify key roll status

Use the following commands to verify the status of your key roll operations.

Workload Verification command
SharePoint/OneDrive Get-SPODataEncryptionPolicy <SPOAdminSiteUrl>
Exchange Get-DataEncryptionPolicy -Identity <Policy>
Multi-workload Get-M365DataAtRestEncryptionPolicy -Identity <Policy>

Troubleshooting

Issue Possible cause Resolution
Key roll fails with permission error Insufficient Azure Key Vault permissions Verify your account has wrapKey and unwrapKey permissions on the key vault
DEP refresh fails New key version not yet propagated Wait a few minutes and retry the refresh command
SharePoint roll shows "In Progress" for extended time Large tenant with significant data SharePoint key rolls can take time for large tenants. Continue monitoring with Get-SPODataEncryptionPolicy
Cannot access encrypted content after key roll Old key was disabled too soon Re-enable the old key and wait 24-48 hours before disabling again
  • Last updated on