Share via

New-SqlColumnMasterKeySettings

  • Reference
Module:
SQLServer

Creates a SqlColumnMasterKeySettings object describing a master key stored in an arbitrarily specified key store provider and path.

Syntax

New-SqlColumnMasterKeySettings
   [-KeyStoreProviderName] <String>
   [-KeyPath] <String>
   [[-Signature] <String>]
   [-KeyVaultAccessToken <String>]
   [-ManagedHsmAccessToken <String>]
   [-AllowEnclaveComputations]
   [-ProgressAction <ActionPreference>]
   [<CommonParameters>]

Description

The New-SqlColumnMasterKeySettings cmdlet creates a SqlColumnMasterKeySettings in-memory object that stores properties of a column master key for Always Encrypted: KeyStoreProviderName, KeyPath, AllowEnclaveComputations, and Signature. This cmdlet can be used for custom key store providers and when both the key store provider name and a fully-formatted key path are known.

The cmdlet may communicate with a key store holding the column master key to generate a signature of key metadata properties. If the key is stored in Azure, you need to specify a valid authentication token for a key vault or a managed HSM holding the key. Alternatively, you can authenticate to Azure with Add-SqlAzureAuthenticationContext before calling this cmdlet.

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

Examples

Example 1: Generate settings for a column master key that is in Azure Key Vault and is not enclaved-enabled.

$cmkSettings = New-SqlColumnMasterKeySettings -KeyStoreProviderName 'AZURE_KEY_VAULT' -KeyPath 'https://myvault.vault.azure.net/keys/CMK/4c05f1a41b12488f9cba2ea964b6a700'

Example 2: Generate settings for a column master key that is in a custom provider

$cmkSettings = New-SqlColumnMasterKeySettings -KeyStoreProviderName 'CUSTOM_PROVIDER' -KeyPath '\\SecureNetworkShare\Keys\AlwaysEncrypted.key'

Example 3: Generate settings for a column master key that is in Azure Key Vault, allows enclave computations and is signed using the provided signature.

$cmkSettings = New-SqlColumnMasterKeySettings -KeyStoreProviderName 'AZURE_KEY_VAULT' -KeyPath 'https://myvault.vault.azure.net/keys/CMK/4c05f1a41b12488f9cba2ea964b6a700' -AllowEnclaveComputations -Signature '0x19BEB4F27F582FDBBD0C7E5F92CF161D79D5E7F5A5183F9C8E710252E7028A3654FBEAF834EE45925024F1A32BD3C6D7D92B46E38690830E20E0777607B073E6665EB05E39263C02557D1208ACECB2251A108D0DEFC25232B67FD223C590258C817292FAFCE2388507812D64A0AEC9E546B0B8E4B2F3EA436053CB158F3CF478C5F5EDA511D0F752F60C3B129BF21356A93368FCC7FD6FAA8DB4E919EB551F375181CA3F4D0404A811C99BD2C8D10C0003AC12B138371F2D76611768B4E84D44116C42F00D679B36D41FBD9467B58291B1F4348C7B422793DA0614EF980CA0A7F42B6D627AFA5A753F0869D2C2F9B0FD38289D5433CE9266C6F867334654BE12'

Example 4: Generate settings for a column master key that is in Azure Key Vault, allows enclave computations and is auto-signed.

# 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

# Pass the token to the cmdlet. It will use the token to communicate with a key vault in Azure Key Vault to sign the column master key properties.
$cmkSettings = New-SqlColumnMasterKeySettings -KeyStoreProviderName 'AZURE_KEY_VAULT' -KeyPath 'https://myvault.vault.azure.net/keys/CMK/4c05f1a41b12488f9cba2ea964b6a700' -AllowEnclaveComputations -KeyVaultAccessToken $keyVaultAccessToken

Parameters

-AllowEnclaveComputations

Specifies whether the column master key allows enclave computations. If the parameter is specified, server-side secure enclaves will be allowed to perform computations on data protected with the column master key. Not valid for SQL Server 2017 and older versions.

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

-KeyPath

Specifies the path within the key store of the physical master key.

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

-KeyStoreProviderName

Specifies the provider name of the key store used to protect the physical master key.

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

-KeyVaultAccessToken

Specifies an access token for key vaults in Azure Key Vault. Use this parameter if the specified column master key is stored in a key vault in Azure Key Vault and the cmdlet is expected to sign key metadata.

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

-ManagedHsmAccessToken

Specifies an access token for managed HSMs in Azure Key Vault. Use this parameter if the specified column master key is stored in a managed HSM in Azure Key Vault and the cmdlet is expected to sign key metadata.

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

-ProgressAction

Determines how PowerShell responds to progress updates generated by a script, cmdlet, or provider, such as the progress bars generated by the Write-Progress cmdlet. The Write-Progress cmdlet creates progress bars that show a command's status.

Type:ActionPreference
Aliases:proga
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Signature

Specifies a hexadecimal string that is a digital signature of column master key properties. A client driver can verify the signature to ensure the column master key properties have not been tampered with. This parameter is allowed only if AllowEnclaveComputations is specified. If AllowEnclaveComputations is specified, but Signature is not, the cmdlet automatically computes the signature and populates the Signature property of the new SqlColumnMasterKeySettings object.

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