Set-SqlColumnEncryption
Criptografa, descriptografa ou criptografa novamente colunas especificadas no banco de dados.
Sintaxe
ByObject
Set-SqlColumnEncryption
[-InputObject] <Database>
-ColumnEncryptionSettings <SqlColumnEncryptionSettings[]>
[-UseOnlineApproach]
[-KeepCheckForeignKeyConstraints]
[-MaxDowntimeInSeconds <Int32>]
[-KeyVaultAccessToken <String>]
[-ManagedHsmAccessToken <String>]
[-LockTimeoutInSeconds <Int32>]
[-MaxIterationDurationInDays <Int32>]
[-MaxDivergingIterations <Int32>]
[-MaxIterations <Int32>]
[-EnclaveAttestationProtocol <SqlConnectionAttestationProtocol>]
[-EnclaveAttestationURL <String>]
[-LogFileDirectory <String>]
[-AllowVerboseLogging]
[-DisableFallBackToClientSide]
[-Script]
[-AccessToken <PSObject>]
[-TrustServerCertificate]
[-HostNameInCertificate <String>]
[-Encrypt <String>]
[<CommonParameters>]
ByPath
Set-SqlColumnEncryption
[[-Path] <String>]
-ColumnEncryptionSettings <SqlColumnEncryptionSettings[]>
[-UseOnlineApproach]
[-KeepCheckForeignKeyConstraints]
[-MaxDowntimeInSeconds <Int32>]
[-KeyVaultAccessToken <String>]
[-ManagedHsmAccessToken <String>]
[-LockTimeoutInSeconds <Int32>]
[-MaxIterationDurationInDays <Int32>]
[-MaxDivergingIterations <Int32>]
[-MaxIterations <Int32>]
[-EnclaveAttestationProtocol <SqlConnectionAttestationProtocol>]
[-EnclaveAttestationURL <String>]
[-LogFileDirectory <String>]
[-AllowVerboseLogging]
[-DisableFallBackToClientSide]
[-Script]
[-AccessToken <PSObject>]
[-TrustServerCertificate]
[-HostNameInCertificate <String>]
[-Encrypt <String>]
[<CommonParameters>]
Description
O cmdlet Set-SqlColumnEncryption criptografa, descriptografa ou criptografa novamente as colunas de banco de dados especificadas usando o recurso Always Encrypted.
O cmdlet aceita uma matriz de objetos SqlColumnEncryptionSettings , cada um dos quais especifica a configuração de criptografia de destino para uma coluna no banco de dados.
O cmdlet criptografará, descriptografará ou criptografará novamente cada coluna especificada, dependendo da configuração de criptografia atual da coluna e das configurações de criptografia de destino especificadas.
O cmdlet se comunica com repositórios de chaves que contêm chaves mestras de colunas. Se qualquer chave mestra de coluna que protege as colunas a serem criptografadas, descriptografadas ou criptografadas novamente, for armazenada no Azure, você precisará especificar um token de autenticação válido para um cofre de chaves ou um HSM gerenciado que contém a chave. Como alternativa, você pode autenticar no Azure com Add-SqlAzureAuthenticationContext antes de chamar esse cmdlet.
Module requirements: version 21+ on PowerShell 5.1; version 22+ on PowerShell 7.x.
Exemplos
Exemplo 1: aplique as configurações de criptografia de destino especificadas a três colunas de banco de dados.
Neste exemplo, a dbo.Student.Id coluna é criptografada usando criptografia determinística e a chave de criptografia de coluna, chamada MyCEK.
A dbo.Student.LastName coluna é criptografada usando criptografia aleatória e a chave de criptografia de coluna, chamada MyCEK.
A dbo.StudentFirstName coluna não é criptografada (se a coluna for criptografada inicialmente, ela será descriptografada).
O exemplo usa a abordagem offline, o que significa que a tabela Student permanecerá indisponível para atualizações durante toda a operação.
Suponha que a chave mestra de coluna, protegendo MyCEK, não esteja armazenada no Azure Key Vault.
$ces1 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.Id' -EncryptionType 'Deterministic' -EncryptionKey 'MyCek'
$ces2 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.LastName' -EncryptionType 'Randomized' -EncryptionKey 'MyCek'
$ces3 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.FirstName' -EncryptionType 'Plaintext'
Set-SqlColumnEncryption -ColumnEncryptionSettings $ces1,$ces2,$ces3 -LogFileDirectory .
Exemplo 2: aplicar as configurações de criptografia de destino especificadas às três colunas de banco de dados (a chave mestra de coluna é armazenada no Azure Key Vault).)
Este exemplo é semelhante ao acima; a única diferença é que a proteção MyCEK da chave mestra de coluna é armazenada no Azure Key Vault.
# Connect to Azure account.
Import-Module Az.Accounts -MinimumVersion 2.2.0
Connect-AzAccount
# Obtain an access token for key vaults.
$keyVaultAccessToken = (Get-AzAccessToken -ResourceUrl https://vault.azure.net).Token
$ces1 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.Id' -EncryptionType 'Deterministic' -EncryptionKey 'MyCek'
$ces2 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.LastName' -EncryptionType 'Randomized' -EncryptionKey 'MyCek'
$ces3 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.FirstName' -EncryptionType 'Plaintext'
# Pass the token to the cmdlet. It will use the token to communicate with Azure Key Vault to obtain the plaintext value of the column encryption key.
Set-SqlColumnEncryption -ColumnEncryptionSettings $ces1,$ces2,$ces3 -LogFileDirectory . -KeyVaultAccessToken $keyVaultAccessToken
Exemplo 3: aplique as configurações de criptografia de destino especificadas a três colunas de banco de dados usando a abordagem online.
Neste exemplo Student , a tabela ficará indisponível para leituras e gravações por até 30 segundos (o valor especificado usando o parâmetro MaxDowntimeInSeconds ).) Suponha que a chave mestra de coluna, protegendo MyCEK, seja armazenada fora do Azure (não é necessário passar um token do Azure).
$ces1 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.Id' -EncryptionType 'Deterministic' -EncryptionKey 'MyCek'
$ces2 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.LastName' -EncryptionType 'Randomized' -EncryptionKey 'MyCek'
$ces3 = New-SqlColumnEncryptionSettings -ColumnName 'dbo.Student.FirstName' -EncryptionType 'Plaintext'
Set-SqlColumnEncryption -ColumnEncryptionSettings $ces1,$ces2,$ces3 -UseOnlineApproach -MaxDowntimeInSeconds 30 -LogFileDirectory .
Exemplo 4: aplicar configurações de criptografia de destino a várias colunas usando criptografia in-loco.
$ces1 = New-SqlColumnEncryptionSettings -ColumnName dbo.Student.Id -EncryptionType 'Randomized' -EncryptionKey 'CEK1'
$ces2 = New-SqlColumnEncryptionSettings -ColumnName dbo.Student.LastName -EncryptionType 'Randomized' -EncryptionKey 'CEK1'
$ces3 = New-SqlColumnEncryptionSettings -ColumnName dbo.Student.FirstName -EncryptionType 'Randomized' -EncryptionKey 'CEK1'
Set-SqlColumnEncryption -ColumnEncryptionSettings $ces1,$ces2,$ces3 -LogFileDirectory . -EnclaveAttestationProtocol 'AAS' -EnclaveAttestationURL 'https://enclavedemoattest.weu.attest.azure.net'
Este exemplo aplica as configurações de criptografia de destino às colunas de banco de dados usando criptografia in-loco, desde que todos os pré-requisitos para criptografia in-loco sejam atendidos, ou seja, o banco de dados tem um enclave habilitado e as chaves usadas em operações criptográficas, que o cmdlet dispara, são habilitadas para enclave.
Parâmetros
-AccessToken
O token de acesso usado para autenticar no SQL Server, como uma alternativa ao usuário/senha ou à Autenticação do Windows.
Isso pode ser usado, por exemplo, para se conectar SQL Azure DB e SQL Azure Managed Instance usar um Service Principal ou um Managed Identity.
O parâmetro a ser usado pode ser uma cadeia de caracteres que representa o token ou um PSAccessToken objeto conforme retornado executando Get-AzAccessToken -ResourceUrl https://database.windows.net.
Esse parâmetro é novo na v22 do módulo.
Propriedades do parâmetro
| Tipo: | PSObject |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-AllowVerboseLogging
Se definido, o cmdlet adicionará mensagens detalhadas ao arquivo de log (se o parâmetro 'LogFileDirectory' estiver definido) e manterá os arquivos dacpac usados pelas bibliotecas subjacentes para executar a operação.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-ColumnEncryptionSettings
Especifica uma matriz de objetos SqlColumnEncryptionSettings , cada um dos quais especifica a configuração de criptografia de destino para uma coluna no banco de dados.
Propriedades do parâmetro
| Tipo: | SqlColumnEncryptionSettings[] |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-DisableFallBackToClientSide
Ao especificar esse parâmetro, o cmdlet erroria com uma mensagem de erro apropriada se a operação for inelegível para o modo in-loco em vez de voltar silenciosamente ao modo de criptografia do lado do cliente.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-EnclaveAttestationProtocol
Especifica o protocolo de atestado de um enclave para Always Encrypted com enclaves seguros. Esse parâmetro é necessário para que o cmdlet execute operações criptográficas in-loco - dentro de um enclave seguro do lado do servidor - para anular a despesa de baixar e carregar os dados. Observe que a criptografia in-loco tem outros pré-requisitos: seu banco de dados deve ter um enclave configurado e você precisa usar chaves criptográficas habilitadas para enclave.
Propriedades do parâmetro
| Tipo: | SqlConnectionAttestationProtocol |
| Valor padrão: | None |
| Valores aceitos: | NotSpecified, AAS, None, HGS |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | AttestationProtocol |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-EnclaveAttestationURL
Especifica uma URL de atestado de enclave para criptografia in-loco ao usar o Always Encrypted com enclaves seguros. Obrigatório se EnclaveAttestationProtocol estiver definido como AAS ou HGS.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Encrypt
O tipo de criptografia a ser usado ao se conectar ao SQL Server.
Esse valor é mapeado para a Encrypt propriedade SqlConnectionEncryptOption no objeto SqlConnection do driver Microsoft.Data.SqlClient.
Na v22 do módulo, o padrão é Optional (para compatibilidade com v21). Na v23+ do módulo, o valor padrão será 'Obrigatório', o que pode criar uma alteração significativa para scripts existentes.
Esse parâmetro é novo na v22 do módulo.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Valores aceitos: | Mandatory, Optional, Strict |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-HostNameInCertificate
O nome do host a ser usado na validação do certificado TLS/SSL do SQL Server. Você deve passar esse parâmetro se a instância do SQL Server estiver habilitada para o Force Encryption e quiser se conectar a uma instância usando nome de host/nome curto. Se esse parâmetro for omitido, passar o FQDN (Nome de Domínio Totalmente Qualificado) para -ServerInstance será necessário para se conectar a uma instância do SQL Server habilitada para o Force Encryption.
Esse parâmetro é novo na v22 do módulo.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-InputObject
Especifica o objeto de banco de dados SQL, para o qual esse cmdlet executa a operação.
Propriedades do parâmetro
| Tipo: | Database |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
ByObject
| Cargo: | 1 |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-KeepCheckForeignKeyConstraints
Se definido, verifique se a semântica (CHECK ou NOCHECK) das restrições de chave estrangeira é preservada.
Caso contrário, se não estiver definido e se UseOnlineApproach não estiver definido, restrições de chave estrangeira serão sempre recriadas com a opção NOCHECK para minimizar o impacto sobre os aplicativos.
KeepCheckForeignKeyConstraints é válido somente quando UseOnlineApproach está definido.
Com a abordagem offline, a semântica das restrições de chave estrangeira é sempre preservada.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-KeyVaultAccessToken
Especifica um token de acesso para cofres de chaves no Azure Key Vault. Use esse parâmetro se qualquer uma das chaves mestras de coluna que protegem as colunas a serem criptografadas, descriptografadas ou criptografadas novamente, estiverem armazenadas em cofres de chaves no Azure Key Vault.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-LockTimeoutInSeconds
Especifica o tempo máximo (em segundos) em que o cmdlet aguardará os bloqueios de banco de dados necessários para iniciar a última iteração de recuperação. Um valor de -1 (padrão) não indica nenhum período de tempo limite (ou seja, aguarde para sempre). Um valor de 0 significa não esperar. Quando uma espera por um bloqueio excede o valor de tempo limite, um erro é retornado. Válido somente se UseOnlineApproach estiver definido.
Propriedades do parâmetro
| Tipo: | Int32 |
| Valor padrão: | -1 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-LogFileDirectory
Se definido, o cmdlet criará um arquivo de log no diretório especificado.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-ManagedHsmAccessToken
Especifica um token de acesso para HSMs gerenciados no Azure Key Vault. Use esse parâmetro se qualquer uma das chaves mestras de coluna que protegem as colunas a serem criptografadas, descriptografadas ou criptografadas novamente, forem armazenadas em HSMs gerenciados no Azure Key Vault.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-MaxDivergingIterations
Especifica o número máximo de iterações de recuperação consecutivas, em que o número de linhas processadas aumenta. Quando esse limite é atingido, o cmdlet pressupõe que ele não será capaz de acompanhar as alterações feitas na tabela de origem e anula a operação e recria o estado original do banco de dados. Válido somente se UseOnlineApproach estiver definido. Deve ser menor que o valor de MaxIterations.
Propriedades do parâmetro
| Tipo: | Int32 |
| Valor padrão: | 5 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-MaxDowntimeInSeconds
Especifica o tempo máximo (em segundos), durante o qual a tabela de origem não estará disponível para leituras e gravações. Válido somente se UseOnlineApproach estiver definido.
Propriedades do parâmetro
| Tipo: | Int32 |
| Valor padrão: | 300 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-MaxIterationDurationInDays
Especifica o tempo máximo (em dias) de propagação ou uma única iteração de recuperação. Se a propagação ou qualquer iteração de recuperação levar mais do que o valor especificado, o cmdlet anulará a operação e recria o estado original do banco de dados. Válido somente se UseOnlineApproach estiver definido.
Propriedades do parâmetro
| Tipo: | Int32 |
| Valor padrão: | 3 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-MaxIterations
Especifica o número máximo de iterações na fase de recuperação. Quando esse limite é atingido, o cmdlet anula a operação e recria o estado original do banco de dados. Válido somente se UseOnlineApproach estiver definido.
Propriedades do parâmetro
| Tipo: | Int32 |
| Valor padrão: | 100 |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Path
Especifica o caminho do banco de dados SQL, para o qual esse cmdlet executa a operação. Se você não especificar um valor para esse parâmetro, o cmdlet usará o local de trabalho atual.
Propriedades do parâmetro
| Tipo: | String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
ByPath
| Cargo: | 1 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Script
Indica que esse cmdlet retorna um script Transact-SQL que executa a tarefa executada por esse cmdlet.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-TrustServerCertificate
Indica se o canal será criptografado ao ignorar a cadeia de certificados para validar a confiança.
Na v22 do módulo, o padrão é $true (para compatibilidade com v21). Na v23+ do módulo, o valor padrão será "$false", o que pode criar uma alteração significativa para scripts existentes.
Esse parâmetro é novo na v22 do módulo.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UseOnlineApproach
Se definido, o cmdlet usará a abordagem online para garantir que o banco de dados esteja disponível para outros aplicativos para leituras e gravações durante a maior parte da operação.
Caso contrário, o cmdlet bloqueará as tabelas afetadas, tornando-as indisponíveis para atualizações de toda a operação. As tabelas estarão disponíveis para leituras.
Propriedades do parâmetro
| Tipo: | SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
CommonParameters
Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.