Set-SqlColumnEncryption

  • 參考
模組:
SQLServer

加密、解密或重新加密資料庫中指定的資料行。

Syntax

Set-SqlColumnEncryption
   -ColumnEncryptionSettings <SqlColumnEncryptionSettings[]>
   [-UseOnlineApproach]
   [-KeepCheckForeignKeyConstraints]
   [-MaxDowntimeInSeconds <Int32>]
   [-KeyVaultAccessToken <String>]
   [-ManagedHsmAccessToken <String>]
   [-LockTimeoutInSeconds <Int32>]
   [-MaxIterationDurationInDays <Int32>]
   [-MaxDivergingIterations <Int32>]
   [-MaxIterations <Int32>]
   [-EnclaveAttestationProtocol <SqlConnectionAttestationProtocol>]
   [-EnclaveAttestationURL <String>]
   [-LogFileDirectory <String>]
   [-InputObject] <Database>
   [-Script]
   [-AccessToken <PSObject>]
   [-TrustServerCertificate]
   [-HostNameInCertificate <String>]
   [-Encrypt <String>]
   [<CommonParameters>]
Set-SqlColumnEncryption
   -ColumnEncryptionSettings <SqlColumnEncryptionSettings[]>
   [-UseOnlineApproach]
   [-KeepCheckForeignKeyConstraints]
   [-MaxDowntimeInSeconds <Int32>]
   [-KeyVaultAccessToken <String>]
   [-ManagedHsmAccessToken <String>]
   [-LockTimeoutInSeconds <Int32>]
   [-MaxIterationDurationInDays <Int32>]
   [-MaxDivergingIterations <Int32>]
   [-MaxIterations <Int32>]
   [-EnclaveAttestationProtocol <SqlConnectionAttestationProtocol>]
   [-EnclaveAttestationURL <String>]
   [-LogFileDirectory <String>]
   [[-Path] <String>]
   [-Script]
   [-AccessToken <PSObject>]
   [-TrustServerCertificate]
   [-HostNameInCertificate <String>]
   [-Encrypt <String>]
   [<CommonParameters>]

Description

Set-SqlColumnEncryption Cmdlet 會使用 Always Encrypted 功能來加密、解密或重新加密指定的資料庫數據行。

Cmdlet 接受 SqlColumnEncryptionSettings 對象的數位，每個物件都會指定資料庫中一個數據行的目標加密組態。

Cmdlet 會根據數據行目前的加密組態和指定的目標加密設定，加密、解密或重新加密每個指定的數據行。

Cmdlet 會與保存數據行主要金鑰的金鑰存放區通訊。 如果保護要加密、解密或重新加密之數據行的任何數據行主要密鑰儲存在 Azure 中，您必須為儲存金鑰保存庫或儲存金鑰的受控 HSM 指定有效的驗證權杖。 或者，您可以先使用 Add-SqlAzureAuthenticationContext 向 Azure 進行驗證，再呼叫此 Cmdlet。

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

範例

範例 1：將指定的目標加密設定套用至三個資料庫數據行。

在此範例中，數據 dbo.Student.Id 行會使用決定性加密和名為 MyCEK的數據行加密密鑰進行加密。

數據 dbo.Student.LastName 行會使用隨機加密和名為 MyCEK的數據行加密金鑰進行加密。

dbo.StudentFirstName如果數據行一開始加密，則數據行不會加密 (，則會) 解密。

此範例使用離線方法，這表示 Student 資料表在整個作業中仍無法使用更新。 假設數據行主要密鑰保護 MyCEK不會儲存在 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 -LogFileDirectory .

範例 2：將指定的目標加密設定套用至三個資料庫數據行， (數據行主要密鑰會儲存在 Azure 金鑰保存庫.)

此範例與上述範例類似;唯一的差異在於數據行主要密鑰保護MyCEK會儲存在 Azure 金鑰保存庫 中。

# 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

範例 3：使用在線方法將指定的目標加密設定套用至三個資料庫數據行。

在此範例 Student 數據表中，最多 30 秒的讀取和寫入無法使用， (使用 MaxDowntimeInSeconds 參數所指定的值。) 假設數據行主要密鑰保護 MyCEK， 會儲存在 Azure 外部， (傳遞 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 .

範例 4：使用就地加密將目標加密設定套用至多個數據行。

$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'

本範例會使用就地加密將目標加密設定套用至資料庫數據行，前提是符合就地加密的所有必要條件，也就是資料庫已啟用記憶體保護區，以及 Cmdlet 觸發的密碼編譯作業中使用的密鑰已啟用記憶體保護區。

參數

-AccessToken

用來驗證 SQL Server 的存取令牌，作為使用者/密碼或 Windows 驗證的替代方案。

例如，這可用來連線至 SQL Azure DB 或使用 或使用 SQL Azure Managed InstanceService Principal 或 Managed Identity。

要使用的參數可以是字串，代表令牌或 PSAccessToken 執行 所傳 Get-AzAccessToken -ResourceUrl https://database.windows.net回的物件。

這個參數是模組 v22 的新功能。

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ColumnEncryptionSettings

指定 SqlColumnEncryptionSettings 物件的陣列，每個物件都會指定資料庫中一個數據行的目標加密組態。

Type:SqlColumnEncryptionSettings[]
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-EnclaveAttestationProtocol

指定具有安全記憶體保護區之 Always Encrypted的記憶體保護區證明通訊協定。 Cmdlet 需要此參數，才能就地執行密碼編譯作業 - 在伺服器端安全記憶體保護區內， 以排除下載和上傳數據的費用。 請注意，就地加密具有其他必要條件：您的資料庫必須已設定記憶體保護區，而且您必須使用已啟用記憶體保護區的密碼編譯密鑰。

Type:SqlConnectionAttestationProtocol
Aliases:AttestationProtocol
Accepted values:NotSpecified, AAS, None, HGS
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EnclaveAttestationURL

使用具有安全記憶體保護區的 Always Encrypted 時，指定就地加密的記憶體保護區證明 URL。 如果 EnclaveAttestationProtocol 設定為 AAS 或 HGS，則為必要專案。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Encrypt

線上至 SQL Server時要使用的加密類型。

這個值會對應至 Encrypt Microsoft.Data.SqlClient 驅動程式之 SqlConnection 物件上的 屬性 SqlConnectionEncryptOption 。

在模組的 v22 中，預設值為 Optional (，以便與 v21) 相容。 在模組 v23+ 中，預設值會是「強制」，這可能會為現有的腳本建立重大變更。

這個參數是模組 v22 的新功能。

Type:String
Accepted values:Mandatory, Optional, Strict
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HostNameInCertificate

用於驗證 SQL Server TLS/SSL 憑證的主機名稱。 如果您的 SQL Server 實例已啟用強制加密，而且您想要使用主機名/簡短名稱連線到實例，則必須傳遞此參數。 如果省略此參數，則必須將完整域名 (FQDN) 傳遞至 -ServerInstance，才能連線到啟用強制加密的 SQL Server 實例。

這個參數是模組 v22 的新功能。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

指定這個 Cmdlet 執行作業的 SQL 資料庫物件。

Type:Database
Position:1
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-KeepCheckForeignKeyConstraints

如果設定，則會保留外鍵條件約束 (的 CHECK 或 NOCHECK) 檢查語意。

否則，如果未設定，且未設定 UseOnlineApproach ，則一律會使用NOCHECK選項重新建立外鍵條件約束，以將對應用程式的影響降到最低。

KeepCheckForeignKeyConstraints 只有在設定 UseOnlineApproach 時才有效。

使用脫機方法時，一律會保留外鍵條件約束的語意。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-KeyVaultAccessToken

指定 Azure 金鑰保存庫 中金鑰保存庫的存取令牌。 如果保護要加密、解密或重新加密之數據行的任何數據行主要密鑰儲存在 Azure 金鑰保存庫 的金鑰保存庫中，請使用此參數。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LockTimeoutInSeconds

指定 cmdlet 會等候資料庫鎖定， (以秒為單位的時間上限) ，以秒為單位開始進行最後一次追補反覆專案。 默認值 -1 () 表示沒有逾 (時期間，也就是永遠等候) 。 值為 0 表示完全不等候。 當等待鎖定超出逾時值時，會傳回錯誤。 只有在設定 UseOnlineApproach 時才有效。

Type:Int32
Position:Named
Default value:-1
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LogFileDirectory

如果設定，Cmdlet 會在指定的目錄中建立記錄檔。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ManagedHsmAccessToken

指定 Azure 金鑰保存庫 中受控 HSM 的存取令牌。 如果保護要加密、解密或重新加密之數據行的任何數據行主要密鑰儲存在 Azure 金鑰保存庫 的受控 HSM 中，請使用此參數。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxDivergingIterations

指定連續攔截反覆運算的最大數目，其中已處理的數據列數目會增加。 達到此限制時，Cmdlet 會假設它無法跟上源數據表中所做的變更，並中止作業並重新建立資料庫的原始狀態。 只有在設定 UseOnlineApproach 時才有效。 必須小於 MaxIterations的值。

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxDowntimeInSeconds

指定) 秒 (的最大時間，在此期間，源數據表將無法用於讀取和寫入。 只有在設定 UseOnlineApproach 時才有效。

Type:Int32
Position:Named
Default value:1800
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxIterationDurationInDays

指定植入或單一追補反覆專案) 天數 (的最大時間。 如果植入或任何追補反覆專案需要超過指定的值，Cmdlet 會中止作業，並重新建立資料庫的原始狀態。 只有在設定 UseOnlineApproach 時才有效。

Type:Int32
Position:Named
Default value:3
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxIterations

指定追補階段中的反覆項目數目上限。 達到此限制時，Cmdlet 會中止作業，並重新建立資料庫的原始狀態。 只有在設定 UseOnlineApproach 時才有效。

Type:Int32
Position:Named
Default value:100
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

指定此 Cmdlet 執行作業的 SQL 資料庫路徑。 如果您未指定此參數的值，Cmdlet 會使用目前的工作位置。

Type:String
Position:1
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Script

指出此 Cmdlet 會傳回 Transact-SQL 腳本，以執行此 Cmdlet 執行的工作。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TrustServerCertificate

指出通道是否會在略過憑證鏈結以驗證信任時加密。

在模組的 v22 中，預設值為 $true (，以便與 v21) 相容。 在模組 v23+ 中，預設值會是 『$false』，這可能會為現有的腳本建立重大變更。

這個參數是模組 v22 的新功能。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseOnlineApproach

如果設定，Cmdlet 會使用線上方法，以確保資料庫可供其他應用程式在大部分作業期間內讀取和寫入使用。

否則，Cmdlet 會鎖定受影響的數據表，使其無法用於整個作業的更新。 數據表將可供讀取使用。

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

輸入

Microsoft.SqlServer.Management.Smo.Database

輸出

String