Invoke-SqlColumnMasterKeyRotation
Inicia la rotación de una clave maestra de columna.
Sintaxis
ByObject
Invoke-SqlColumnMasterKeyRotation
[-InputObject] <Database>
-SourceColumnMasterKeyName <String>
-TargetColumnMasterKeyName <String>
[-KeyVaultAccessToken <String>]
[-ManagedHsmAccessToken <String>]
[-Script]
[-AccessToken <PSObject>]
[-TrustServerCertificate]
[-HostNameInCertificate <String>]
[-Encrypt <String>]
[<CommonParameters>]
ByPath
Invoke-SqlColumnMasterKeyRotation
[[-Path] <String>]
-SourceColumnMasterKeyName <String>
-TargetColumnMasterKeyName <String>
[-KeyVaultAccessToken <String>]
[-ManagedHsmAccessToken <String>]
[-Script]
[-AccessToken <PSObject>]
[-TrustServerCertificate]
[-HostNameInCertificate <String>]
[-Encrypt <String>]
[<CommonParameters>]
Description
El cmdlet Invoke-SqlColumnMasterKeyRotation inicia la sustitución de una clave maestra de columna de origen existente por una nueva clave maestra de columna de destino para la característica Always Encrypted.
El cmdlet recupera todos los objetos de clave de cifrado de columnas que contienen valores de clave cifrados cifrados con la clave maestra de columna de origen especificada.
A continuación, el cmdlet descifra los valores cifrados actuales, vuelve a cifrar los valores de texto no cifrado resultantes con la clave maestra de columna de destino y, a continuación, actualiza los objetos de clave de cifrado de columna afectadas para agregar los nuevos valores cifrados.
Como resultado, cada clave de cifrado de columna afectada contiene dos valores cifrados: uno generado mediante la clave maestra de columna de origen actual y otra, generada mediante la clave maestra de columna de destino.
Si una clave maestra de columna de origen o de destino se almacena en Azure, debe especificar un token de autenticación válido (o tokens) para un almacén de claves o un HSM administrado que contenga la clave. Como alternativa, puede autenticarse en Azure con Add-SqlAzureAuthenticationContext antes de llamar a este cmdlet.
Module requirements: version 21+ on PowerShell 5.1; version 22+ on PowerShell 7.x.
Ejemplos
Ejemplo 1: Iniciar el proceso de rotación de la clave maestra de columna.
Invoke-SqlColumnMasterKeyRotation -SourceColumnMasterKeyName "CMK1" -TargetColumnMasterKeyName "CMK2"
Este comando inicia el proceso de rotación de la clave maestra de columna denominada CMK1 y la reemplaza por la clave maestra de columna denominada CMK2.
Ejemplo 2: Iniciar el proceso de rotación de la clave maestra de columna con tokens de autenticación especificados
# 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
En el ejemplo se inicia el proceso de rotación de la clave maestra de columna denominada CMK1 y se reemplaza por la clave maestra de columna denominada CMK2.
Se supone que una de las claves se almacena en un almacén de claves y la otra clave se almacena en un HSM administrado en Azure Key Vault.
Invoke-SqlColumnMasterKey usará los tokens de autenticación obtenidos para comunicarse con el almacén de claves y los puntos de conexión de HSM administrados.
Parámetros
-AccessToken
El token de acceso que se usa para autenticarse en SQL Server, como alternativa a la autenticación de usuario o contraseña de Windows.
Esto se puede usar, por ejemplo, para conectarse a SQL Azure DB y SQL Azure Managed Instance usar o Service Principal .Managed Identity
El parámetro que se va a usar puede ser una cadena que representa el token o un PSAccessToken objeto tal como se devuelve mediante la ejecución Get-AzAccessToken -ResourceUrl https://database.windows.netde .
Este parámetro es nuevo en la versión 22 del módulo.
Propiedades del parámetro
| Tipo: | PSObject |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-Encrypt
Tipo de cifrado que se va a usar al conectarse a SQL Server.
Este valor se asigna a la Encrypt propiedad SqlConnectionEncryptOption del objeto SqlConnection del controlador Microsoft.Data.SqlClient.
En la versión 22 del módulo, el valor predeterminado es Optional (por compatibilidad con v21). En la versión 23+ del módulo, el valor predeterminado será "Obligatorio", que puede crear un cambio importante para los scripts existentes.
Este parámetro es nuevo en la versión 22 del módulo.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Valores aceptados: | Mandatory, Optional, Strict |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-HostNameInCertificate
Nombre de host que se va a usar al validar el certificado TLS/SSL de SQL Server. Debe pasar este parámetro si la instancia de SQL Server está habilitada para Forzar cifrado y desea conectarse a una instancia mediante el nombre de host o el nombre corto. Si se omite este parámetro, es necesario pasar el nombre de dominio completo (FQDN) a -ServerInstance es necesario para conectarse a una instancia de SQL Server habilitada para Forzar cifrado.
Este parámetro es nuevo en la versión 22 del módulo.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-InputObject
Especifica el objeto de base de datos SQL para el que este cmdlet ejecuta la operación.
Propiedades del parámetro
| Tipo: | Database |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
ByObject
| Posición: | 1 |
| Mandatory: | True |
| Valor de la canalización: | True |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-KeyVaultAccessToken
Especifica un token de acceso para almacenes de claves en Azure Key Vault. Use este parámetro si la clave maestra de columna de destino o actual se almacena en un almacén de claves de Azure Key Vault.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-ManagedHsmAccessToken
Especifica un token de acceso para los HSM administrados en Azure Key Vault. Use este parámetro si la clave maestra de columna de destino o actual se almacena en un HSM administrado en Azure Key Vault.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-Path
Especifica la ruta de acceso de la base de datos SQL, para la que este cmdlet ejecuta la operación.
Si no especifica un valor para este parámetro, el cmdlet usa la ubicación de trabajo actual.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
ByPath
| Posición: | 1 |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-Script
Indica que este cmdlet ejecuta un script de Transact-SQL que realiza la tarea.
Propiedades del parámetro
| Tipo: | SwitchParameter |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-SourceColumnMasterKeyName
Especifica el nombre de la clave maestra de columna de origen.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | True |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-TargetColumnMasterKeyName
Especifica el nombre de la clave maestra de columna de destino.
Propiedades del parámetro
| Tipo: | String |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | True |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
-TrustServerCertificate
Indica si el canal se cifrará mientras se pasa la cadena de certificados para validar la confianza.
En la versión 22 del módulo, el valor predeterminado es $true (por compatibilidad con v21). En la versión 23+ del módulo, el valor predeterminado será "$false", que puede crear un cambio importante para los scripts existentes.
Este parámetro es nuevo en la versión 22 del módulo.
Propiedades del parámetro
| Tipo: | SwitchParameter |
| Valor predeterminado: | None |
| Admite caracteres comodín: | False |
| DontShow: | False |
Conjuntos de parámetros
(All)
| Posición: | Named |
| Mandatory: | False |
| Valor de la canalización: | False |
| Valor de la canalización por nombre de propiedad: | False |
| Valor de los argumentos restantes: | False |
CommonParameters
Este cmdlet admite los parámetros comunes: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction y -WarningVariable. Para obtener más información, vea about_CommonParameters.