Invoke-SqlColumnMasterKeyRotation

Invoke-SqlColumnMasterKeyRotation
    [-InputObject] <Database>
    -SourceColumnMasterKeyName <String>
    -TargetColumnMasterKeyName <String>
    [-KeyVaultAccessToken <String>]
    [-ManagedHsmAccessToken <String>]
    [-Script]
    [-AccessToken <PSObject>]
    [-TrustServerCertificate]
    [-HostNameInCertificate <String>]
    [-Encrypt <String>]
    [<CommonParameters>]

Invoke-SqlColumnMasterKeyRotation
    [[-Path] <String>]
    -SourceColumnMasterKeyName <String>
    -TargetColumnMasterKeyName <String>
    [-KeyVaultAccessToken <String>]
    [-ManagedHsmAccessToken <String>]
    [-Script]
    [-AccessToken <PSObject>]
    [-TrustServerCertificate]
    [-HostNameInCertificate <String>]
    [-Encrypt <String>]
    [<CommonParameters>]

The Invoke-SqlColumnMasterKeyRotation cmdlet initiates replacing an existing source column master key with a new target column master key for the Always Encrypted feature.

The cmdlet retrieves all column encryption key objects that contain encrypted key values that are encrypted with the specified source column master key.

Then, the cmdlet decrypts the current encrypted values, re-encrypts the resulting plaintext values with the target column master key, and then updates the impacted column encryption key objects to add the new encrypted values.

As a result, each impacted column encryption key contains two encrypted values: one produced using the current source column master key and another, produced using the target column master key.

If a source or a target column master key is stored in Azure, you need to specify a valid authentication token (or tokens) for a key vault or a managed HSM holding the key. Alternatively, you can authenticate to Azure with Add-SqlAzureAuthenticationContext before calling this cmdlet.

Module requirements: version 21+ on PowerShell 5.1; version 22+ on PowerShell 7.x.

Invoke-SqlColumnMasterKeyRotation -SourceColumnMasterKeyName "CMK1" -TargetColumnMasterKeyName "CMK2"

This command initiates the process of rotating the column master key named CMK1, and replacing it with the column master key named CMK2.

# Connect to Azure account.
Import-Module Az.Accounts -MinimumVersion 2.2.0
Connect-AzAccount

# Obtain access tokens.
$keyVaultAccessToken = (Get-AzAccessToken -ResourceUrl https://vault.azure.net).Token
$managedHSMAccessToken = (Get-AzAccessToken -ResourceUrl https://managedhsm.azure.net).Token

# Pass the tokens to the cmdlet.
Invoke-SqlColumnMasterKey -SourceColumnMasterKeyName CMK1 -TargetColumnMasterKeyName CMK2 -KeyVaultAccessToken $keyVaultAccessToken -ManagedHSMAccessToken $managedHSMAccessToken

The example initiates the process of rotating the column master key named CMK1 and replacing it with the column master key named CMK2. We assume one of the keys is stored in a key vault and the other key is stored in a managed HSM in Azure Key Vault. The Invoke-SqlColumnMasterKey will use the obtained authentication tokens to communicate with key vault and managed HSM endpoints.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.