Set-SqlColumnEncryption

模組:

SQLServer

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

語法

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>]
   [-AllowVerboseLogging]
   [-InputObject] <Database>
   [-Script]
   [-AccessToken <PSObject>]
   [-TrustServerCertificate]
   [-HostNameInCertificate <String>]
   [-Encrypt <String>]
   [-ProgressAction <ActionPreference>]
   [<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>]
   [-AllowVerboseLogging]
   [[-Path] <String>]
   [-Script]
   [-AccessToken <PSObject>]
   [-TrustServerCertificate]
   [-HostNameInCertificate <String>]
   [-Encrypt <String>]
   [-ProgressAction <ActionPreference>]
   [<CommonParameters>]

Description

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

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

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

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

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 數據行未加密（如果數據行一開始加密，則會解密）。

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

範例 2：將指定的目標加密設定套用至三個資料庫數據行（數據行主要密鑰儲存在 Azure Key Vault 中。

此範例與上述範例類似;唯一的差異在於保護 MyCEK 的數據行主要密鑰會儲存在 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

範例 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 驗證的替代方案。

例如，這可用來使用 Service Principal 或 Managed Identity來連線到 SQL Azure DB 和 SQL Azure Managed Instance。

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

此參數是模組 v22 的新功能。

類型:	PSObject
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-AllowVerboseLogging

如果設定，Cmdlet 會將詳細資訊訊息新增至記錄檔（如果已設定 'LogFileDirectory' 參數），並保留基礎連結庫用來執行作業的 dacpac 檔案。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ColumnEncryptionSettings

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

類型:	SqlColumnEncryptionSettings[]
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-EnclaveAttestationProtocol

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

類型:	SqlConnectionAttestationProtocol
別名:	AttestationProtocol
接受的值:	NotSpecified, AAS, None, HGS
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-EnclaveAttestationURL

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Encrypt

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

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

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

此參數是模組 v22 的新功能。

類型:	String
接受的值:	Mandatory, Optional, Strict
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HostNameInCertificate

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

此參數是模組 v22 的新功能。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-InputObject

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

類型:	Database
Position:	1
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-KeepCheckForeignKeyConstraints

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

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

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

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

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-KeyVaultAccessToken

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-LockTimeoutInSeconds

指定 Cmdlet 將等候開始最後一個追補反覆專案所需的資料庫鎖定時間上限（以秒為單位）。 -1 值（預設值）表示沒有逾時期間（也就是永遠等候）。 值為 0 表示完全不等候。 當等候鎖定超過逾時值時，會傳回錯誤。 只有在設定UseOnlineApproach 時才有效。

類型:	Int32
Position:	Named
預設值:	-1
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-LogFileDirectory

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ManagedHsmAccessToken

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

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaxDivergingIterations

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

類型:	Int32
Position:	Named
預設值:	5
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaxDowntimeInSeconds

指定源數據表無法用於讀取和寫入的最大時間（以秒為單位）。 只有在設定UseOnlineApproach 時才有效。

類型:	Int32
Position:	Named
預設值:	1800
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaxIterationDurationInDays

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

類型:	Int32
Position:	Named
預設值:	3
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaxIterations

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

類型:	Int32
Position:	Named
預設值:	100
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Path

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

類型:	String
Position:	1
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ProgressAction

決定 PowerShell 如何回應腳本、Cmdlet 或提供者所產生的進度更新，例如 Write-Progress Cmdlet 所產生的進度列。 Write-Progress Cmdlet 會建立顯示命令狀態的進度列。

類型:	ActionPreference
別名:	proga
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Script

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TrustServerCertificate

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

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

此參數是模組 v22 的新功能。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-UseOnlineApproach

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

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

類型:	SwitchParameter
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

Microsoft.SqlServer.Management.Smo.Database

輸出

String

相關連結

• SQLServer_Cmdlets