New-SqlAzureKeyVaultColumnMasterKeySettings

Reference

Module:: SQLServer

Creates a SqlColumnMasterKeySettings object describing an asymmetric key stored in Azure Key Vault.

Syntax

New-SqlAzureKeyVaultColumnMasterKeySettings
   [-KeyUrl] <String>
   [[-Signature] <String>]
   [-KeyVaultAccessToken <String>]
   [-ManagedHsmAccessToken <String>]
   [-AllowEnclaveComputations]
   [<CommonParameters>]

Description

Creates a SqlColumnMasterKeySettings object describing a column master key stored in a key vault or in a managed HSM in Azure Key Vault.

If you're using the cmdlet to sign key metadata, you need to specify a valid authentication token for key vaults or managed HSMs. 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: Create a simple SqlColumnMasterKeySettings object

$CMKSettings = New-SqlAzureKeyVaultColumnMasterKeySettings -KeyUrl 'https://myvault.vault.contoso.net/keys/CMK/4c05f1a41b12488f9cba2ea964b6a700'

This command creates a SqlColumnMasterKeySettings object that references a key in Azure Key Vault and stores the result in the variable named $CMKSettings

Example 2: Create a SqlColumnMasterKeySettings with auto-signed properties allowing enclave computations

# 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 the key vault containing the column master key to sign the column master key metadata properties.
$cmkSettings = New-SqlAzureKeyVaultColumnMasterKeySettings -KeyUrl 'https://myvault.vault.azure.net/keys/CMK/4c05f1a41b12488f9cba2ea964b6a700' -AllowEnclaveComputations -keyVaultAccessToken $keyVaultAccessToken

This command creates a SqlColumnMasterKeySettings object that references a key in a key vault and stores the result in the variable named $cmkSettings. The key allows enclave computations. Since the signature parameter is not specified, the cmdlet automatically computes the signature and populates the Signature property of the SqlColumnMasterKeySettings object.

This example illustrates obtaining an authentication token for key vaults in Azure Key Vault, and passing it to the cmdlet.

Example 3: Create a SqlColumnMasterKeySettings object allowing enclave computations

# Note: actual signature truncated for brevity
$signature = "0x19BEB4F27F582F...89D5433CE9266C6F867334654BE12"
$cmkSettings = New-SqlAzureKeyVaultColumnMasterKeySettings -KeyUrl 'https://myvault.vault.contoso.net/keys/CMK/4c05f1a41b12488f9cba2ea964b6a700' -AllowEnclaveComputations -Signature $signature

This command creates a SqlColumnMasterKeySettings object that references a key in a key vault and stores the result in the variable named $cmkSettings. The key allows enclave computations. The signature of the key properties is specified in the Signature parameter.

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:	1
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyUrl

Specifies the link, as a URL, of the key in Azure Key Vault or a managed HSM.

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

-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:	2
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Outputs

SqlColumnMasterKeySettings

SQLServer_Cmdlets