Set-SqlColumnEncryption
データベース内の指定された列を暗号化、暗号化解除、または再暗号化します。
構文
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>]
説明
Set-SqlColumnEncryption コマンドレットは、Always Encrypted 機能を使用して、指定されたデータベース列の暗号化、暗号化解除、または再暗号化を行います。
このコマンドレットは、SqlColumnEncryptionSettings オブジェクトの配列を受け入れます。各オブジェクトは、データベース内の 1 つの列のターゲット暗号化構成を指定します。
コマンドレットは、列の現在の暗号化構成と指定されたターゲット暗号化設定に応じて、指定された各列の暗号化、暗号化解除、または再暗号化を行います。
コマンドレットは、列マスター キーを保持するキー ストアと通信します。 暗号化、暗号化解除、または再暗号化する列を保護する列マスター キーが Azure に格納されている場合は、キー コンテナーまたはキーを保持するマネージド HSM の有効な認証トークンを指定する必要があります。 または、このコマンドレットを呼び出す前に、Add-SqlAzureAuthenticationContext を使用して Azure に対して認証を行うことができます。
Module requirements: version 21+ on PowerShell 5.1; version 22+ on PowerShell 7.x.
例
例 1: 指定したターゲット暗号化設定を 3 つのデータベース列に適用します。
この例では、dbo.Student.Id
列は確定的暗号化と列暗号化キー (MyCEK
という名前) を使用して暗号化されます。
dbo.Student.LastName
列は、ランダム化された暗号化と列暗号化キー (MyCEK
という名前) を使用して暗号化されます。
dbo.StudentFirstName
列は暗号化されません (列が最初に暗号化されている場合、暗号化が解除されます)。
この例ではオフラインアプローチを使用しています。つまり、Student テーブルは操作全体を通じて更新できません。
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: 指定したターゲット暗号化設定を 3 つのデータベース列に適用します (列マスター キーは 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: オンラインアプローチを使用して、指定したターゲット暗号化設定を 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'
この例では、インプレース暗号化のすべての前提条件が満たされている場合、つまり、データベースにエンクレーブが有効になっており、コマンドレットによってトリガーされる暗号化操作で使用されるキーがエンクレーブ対応である場合に、インプレース暗号化を使用してデータベース列にターゲット暗号化設定を適用します。
パラメーター
-AccessToken
ユーザー/パスワードまたは Windows 認証の代わりに、SQL Server に対する認証に使用されるアクセス トークン。
これは、たとえば、Service Principal
または Managed Identity
を使用して SQL Azure DB
と SQL Azure Managed Instance
に接続するために使用できます。
使用するパラメーターには、トークンを表す文字列、または Get-AzAccessToken -ResourceUrl https://database.windows.net
を実行して返される PSAccessToken
オブジェクトを指定できます。
このパラメーターは、モジュールの v22 の新機能です。
型: | PSObject |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-AllowVerboseLogging
設定すると、コマンドレットはログ ファイルに詳細メッセージを追加し ('LogFileDirectory' パラメーターが設定されている場合)、操作を実行するために基になるライブラリによって使用される dacpac ファイルを保持します。
型: | SwitchParameter |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-ColumnEncryptionSettings
SqlColumnEncryptionSettings オブジェクトの配列を指定します。各オブジェクトは、データベース内の 1 つの列のターゲット暗号化構成を指定します。
型: | SqlColumnEncryptionSettings[] |
配置: | Named |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-EnclaveAttestationProtocol
セキュリティで保護されたエンクレーブを持つ Always Encrypted のエンクレーブの構成証明プロトコルを指定します。 このパラメーターは、データのダウンロードとアップロードの費用を無効にするために、サーバー側のセキュリティで保護されたエンクレーブ内で、コマンドレットが暗号化操作をインプレースで実行するために必要です。 インプレース暗号化には他の前提条件があることに注意してください。データベースにはエンクレーブが構成されている必要があり、エンクレーブ対応の暗号化キーを使用する必要があります。
型: | SqlConnectionAttestationProtocol |
Aliases: | AttestationProtocol |
指定可能な値: | NotSpecified, AAS, None, HGS |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-EnclaveAttestationURL
セキュリティで保護されたエンクレーブで Always Encrypted を使用する場合に、インプレース暗号化のエンクレーブ構成証明 URL を指定します。 EnclaveAttestationProtocol
型: | String |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-Encrypt
SQL Server に接続するときに使用する暗号化の種類。
この値は、Microsoft.Data.SqlClient ドライバーの SqlConnection オブジェクトの Encrypt
プロパティ SqlConnectionEncryptOption
にマップされます。
モジュールの v22 では、既定値は Optional
です (v21 との互換性のため)。 モジュールの v23 以降では、既定値は "必須" になり、既存のスクリプトに重大な変更が生じる可能性があります。
このパラメーターは、モジュールの v22 の新機能です。
型: | String |
指定可能な値: | Mandatory, Optional, Strict |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-HostNameInCertificate
SQL Server TLS/SSL 証明書の検証に使用するホスト名。 SQL Server インスタンスで Force Encryption が有効になっていて、ホスト名/短縮名を使用してインスタンスに接続する場合は、このパラメーターを渡す必要があります。 このパラメーターを省略した場合、強制暗号化が有効になっている SQL Server インスタンスに接続するには、完全修飾ドメイン名 (FQDN) を -ServerInstance に渡す必要があります。
このパラメーターは、モジュールの v22 の新機能です。
型: | String |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-InputObject
このコマンドレットが操作を実行する SQL データベース オブジェクトを指定します。
型: | Database |
配置: | 1 |
規定値: | None |
必須: | True |
パイプライン入力を受け取る: | True |
ワイルドカード文字を受け取る: | False |
-KeepCheckForeignKeyConstraints
設定すると、外部キー制約のチェック セマンティクス (CHECK または NOCHECK) が保持されます。
設定されていない場合、および UseOnlineApproach
KeepCheckForeignKeyConstraints は、UseOnlineApproach が設定されている場合にのみ有効です。
オフラインアプローチでは、外部キー制約のセマンティクスは常に保持されます。
型: | SwitchParameter |
配置: | Named |
規定値: | False |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-KeyVaultAccessToken
Azure Key Vault 内のキー コンテナーのアクセス トークンを指定します。 暗号化、暗号化解除、または再暗号化する列を保護する列マスター キーのいずれかが Azure Key Vault のキー コンテナーに格納されている場合は、このパラメーターを使用します。
型: | String |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-LockTimeoutInSeconds
コマンドレットが最後のキャッチアップ イテレーションを開始するために必要なデータベース ロックを待機する最大時間 (秒単位) を指定します。 -1 (既定値) の値は、タイムアウト期間がないことを示します (つまり、永久に待機します)。 値 0 は、まったく待機しないことを意味します。 ロックの待機がタイムアウト値を超えると、エラーが返されます。
UseOnlineApproach
型: | Int32 |
配置: | Named |
規定値: | -1 |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-LogFileDirectory
このコマンドレットを設定すると、指定したディレクトリにログ ファイルが作成されます。
型: | String |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-ManagedHsmAccessToken
Azure Key Vault 内のマネージド HSM のアクセス トークンを指定します。 暗号化、復号化、または再暗号化する列を保護する列マスター キーのいずれかが Azure Key Vault のマネージド HSM に格納されている場合は、このパラメーターを使用します。
型: | String |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-MaxDivergingIterations
連続するキャッチアップ イテレーションの最大数を指定します。ここで、処理された行の数が増えます。
この制限に達すると、コマンドレットはソース テーブルで行われた変更に追い付けることができないと想定し、操作を中止してデータベースの元の状態を再作成します。 UseOnlineApproach
型: | Int32 |
配置: | Named |
規定値: | 5 |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-MaxDowntimeInSeconds
ソース テーブルを読み取りと書き込みに使用できない最大時間 (秒単位) を指定します。
UseOnlineApproach
型: | Int32 |
配置: | Named |
規定値: | 1800 |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-MaxIterationDurationInDays
シード処理の最大時間 (日数) または 1 回のキャッチアップ イテレーションを指定します。
シード処理またはキャッチアップイテレーションに指定した値を超える時間がかかる場合、コマンドレットは操作を中止し、データベースの元の状態を再作成します。 UseOnlineApproach
型: | Int32 |
配置: | Named |
規定値: | 3 |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-MaxIterations
キャッチアップ フェーズでのイテレーションの最大数を指定します。
この制限に達すると、コマンドレットは操作を中止し、データベースの元の状態を再作成します。
UseOnlineApproach
型: | Int32 |
配置: | Named |
規定値: | 100 |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-Path
このコマンドレットが操作を実行する SQL データベースのパスを指定します。 このパラメーターの値を指定しない場合、コマンドレットは現在の作業場所を使用します。
型: | String |
配置: | 1 |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-ProgressAction
スクリプト、コマンドレット、またはプロバイダーによって生成された進行状況の更新 (Write-Progress コマンドレットによって生成された進行状況バーなど) に対する PowerShell の応答方法を決定します。 Write-Progress コマンドレットは、コマンドの状態を示す進行状況バーを作成します。
型: | ActionPreference |
Aliases: | proga |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-Script
このコマンドレットは、このコマンドレットが実行するタスクを実行する Transact-SQL スクリプトを返します。
型: | SwitchParameter |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-TrustServerCertificate
信頼を検証するために証明書チェーンのウォークをバイパスしながらチャネルを暗号化するかどうかを示します。
モジュールの v22 では、既定値は $true
です (v21 との互換性のため)。 モジュールの v23 以降では、既定値は "$false" になり、既存のスクリプトに重大な変更が生じる可能性があります。
このパラメーターは、モジュールの v22 の新機能です。
型: | SwitchParameter |
配置: | Named |
規定値: | None |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
-UseOnlineApproach
設定した場合、コマンドレットはオンラインアプローチを使用して、操作のほとんどの期間、読み取りと書き込みの両方でデータベースを他のアプリケーションが使用できるようにします。
それ以外の場合、コマンドレットは影響を受けるテーブルをロックし、操作全体の更新に使用できなくなります。 テーブルは読み取りに使用できます。
型: | SwitchParameter |
配置: | Named |
規定値: | False |
必須: | False |
パイプライン入力を受け取る: | False |
ワイルドカード文字を受け取る: | False |
入力
Microsoft.SqlServer.Management.Smo.Database
出力
String