Add-AzureKeyVaultKey

キー コンテナーにキーを作成するか、キー コンテナーにキーをインポートします。

重要

Az PowerShell モジュール で AzureRM PowerShell モジュールのすべての機能およびその他を利用できるようになったため、2024 年 2 月 29 日に AzureRM PowerShell モジュールは廃止になります。

サービスの中断を回避するために、2024 年 2 月 29 日までに、AzureRM PowerShell モジュールを使用するスクリプトを更新して、Az PowerShell モジュールを使用するようにしてください。 スクリプトを自動的に更新するには、 クイックスタート ガイドに従ってください。

構文

Add-AzureKeyVaultKey
   [-VaultName] <String>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-VaultName] <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-InputObject] <PSKeyVault>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-InputObject] <PSKeyVault>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-ResourceId] <String>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-ResourceId] <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

説明

Add-AzureKeyVaultKey コマンドレットは、Azure Key Vault のキー コンテナーにキーを作成するか、キー コンテナーにキーをインポートします。 次のいずれかの方法を使用してキーを追加するには、このコマンドレットを使用します。

  • Key Vault サービスのハードウェア セキュリティ モジュール (HSM) にキーを作成します。
  • Key Vault サービスのソフトウェアにキーを作成します。
  • 独自のハードウェア セキュリティ モジュール (HSM) から Key Vault サービスの HSM にキーをインポートします。
  • コンピューター上の .pfx ファイルからキーをインポートします。
  • コンピューター上の .pfx ファイルから、Key Vault サービスのハードウェア セキュリティ モジュール (HSM) にキーをインポートします。 これらの操作の場合は、キー属性を指定するか、既定の設定を受け入れます。 キー コンテナー内の既存のキーと同じ名前のキーを作成またはインポートすると、元のキーが新しいキーに指定した値で更新されます。 以前の値には、そのバージョンのキーのバージョン固有の URI を使用してアクセスできます。 キーのバージョンと URI 構造については、Key Vault REST API ドキュメントの「キーとシークレットについて」を参照してください。 注: 独自のハードウェア セキュリティ モジュールからキーをインポートするには、まず、Azure Key Vault BYOK ツールセットを使用して BYOK パッケージ (.byok ファイル名拡張子を持つファイル) を生成する必要があります。 詳細については、「Azure Key Vault のHSM-Protected キーを生成および転送する方法」を参照してください。 ベスト プラクティスとして、Backup-AzureKeyVaultKey コマンドレットを使用して、キーの作成または更新後にキーをバックアップします。 削除を取り消す機能はないため、誤ってキーを削除したり、削除して気を変えたりした場合、復元できるバックアップがない限り、キーは回復できません。

例 1: キーを作成する

PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITSoftware' -Destination 'Software'

Vault Name     : contoso
Name           : ITSoftware
Version        : 67da57e9cadf48a2ad8d366b115843ab
Id             : https://contoso.vault.azure.net:443/keys/ITSoftware/67da57e9cadf48a2ad8d366b115843ab
Enabled        : True
Expires        :
Not Before     :
Created        : 5/21/2018 11:10:58 PM
Updated        : 5/21/2018 11:10:58 PM
Purge Disabled : False
Tags           :

このコマンドは、Contoso という名前のキー コンテナーに ITSoftware という名前のソフトウェアで保護されたキーを作成します。

例 2: HSM で保護されたキーを作成する

PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITHsm' -Destination 'HSM'

Vault Name     : contoso
Name           : ITHsm
Version        : 67da57e9cadf48a2ad8d366b115843ab
Id             : https://contoso.vault.azure.net:443/keys/ITSoftware/67da57e9cadf48a2ad8d366b115843ab
Enabled        : True
Expires        :
Not Before     :
Created        : 5/21/2018 11:10:58 PM
Updated        : 5/21/2018 11:10:58 PM
Purge Disabled : False
Tags           :

このコマンドは、Contoso という名前のキー コンテナーに HSM で保護されたキーを作成します。

例 3: 既定値以外の値を持つキーを作成する

PS C:\> $KeyOperations = 'decrypt', 'verify'
PS C:\> $Expires = (Get-Date).AddYears(2).ToUniversalTime()
PS C:\> $NotBefore = (Get-Date).ToUniversalTime()
PS C:\> $Tags = @{'Severity' = 'high'; 'Accounting' = "true"}
PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITHsmNonDefault' -Destination 'HSM' -Expires $Expires -NotBefore $NotBefore -KeyOps $KeyOperations -Disable -Tag $Tags

Vault Name     : contoso
Name           : ITHsmNonDefault
Version        : 929bfc14db84439b823ffd1bedadaf5f
Id             : https://contoso.vault.azure.net:443/keys/ITHsmNonDefault/929bfc14db84439b823ffd1bedadaf5f
Enabled        : False
Expires        : 5/21/2020 11:12:43 PM
Not Before     : 5/21/2018 11:12:50 PM
Created        : 5/21/2018 11:13:17 PM
Updated        : 5/21/2018 11:13:17 PM
Purge Disabled : False
Tags           : Name        Value
                 Severity    high
                 Accounting  true

最初のコマンドは、値の暗号化解除と検証を$KeyOperations変数に格納します。 2 番目のコマンドでは、Get-Date コマンドレットを使用して、UTC で定義された DateTime オブジェクトを作成します。 そのオブジェクトは、2 年後の時刻を指定します。 このコマンドは、その日付を$Expires変数に格納します。 詳細を表示するには「Get-Help Get-Date」を入力します。 3 番目のコマンドは、Get-Date コマンドレットを使用して DateTime オブジェクトを作成します。 そのオブジェクトは、現在の UTC 時刻を指定します。 このコマンドは、その日付を$NotBefore変数に格納します。 最後のコマンドは、HSM で保護されたキーである ITHsmNonDefault という名前のキーを作成します。 このコマンドは、$KeyOperations格納される許可されるキー操作の値を指定します。 このコマンドでは、前のコマンドで作成した Expires パラメーターと NotBefore パラメーターの時刻と、重要度と IT の高いタグを指定します。 新しいキーは無効になっています。 これを有効にするには、 Set-AzureKeyVaultKey コマンドレットを使用します。

例 4: HSM で保護されたキーをインポートする

PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITByok' -KeyFilePath 'C:\Contoso\ITByok.byok' -Destination 'HSM'

Vault Name     : contoso
Name           : ITByok
Version        : 67da57e9cadf48a2ad8d366b115843ab
Id             : https://contoso.vault.azure.net:443/keys/ITByok/67da57e9cadf48a2ad8d366b115843ab
Enabled        : True
Expires        :
Not Before     :
Created        : 5/21/2018 11:10:58 PM
Updated        : 5/21/2018 11:10:58 PM
Purge Disabled : False
Tags           :

このコマンドは、 KeyFilePath パラメーターが指定した場所から ITByok という名前のキーをインポートします。 インポートされたキーは、HSM で保護されたキーです。 独自のハードウェア セキュリティ モジュールからキーをインポートするには、まず、Azure Key Vault BYOK ツールセットを使用して BYOK パッケージ (.byok ファイル名拡張子を持つファイル) を生成する必要があります。 詳細については、「Azure Key Vault のHSM-Protected キーを生成および転送する方法」を参照してください

例 5: ソフトウェアで保護されたキーをインポートする

PS C:\> $Password = ConvertTo-SecureString -String 'Password' -AsPlainText -Force
PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITPfx' -KeyFilePath 'C:\Contoso\ITPfx.pfx' -KeyFilePassword $Password

Vault Name     : contoso
Name           : ITPfx
Version        : 67da57e9cadf48a2ad8d366b115843ab
Id             : https://contoso.vault.azure.net:443/keys/ITPfx/67da57e9cadf48a2ad8d366b115843ab
Enabled        : True
Expires        :
Not Before     :
Created        : 5/21/2018 11:10:58 PM
Updated        : 5/21/2018 11:10:58 PM
Purge Disabled : False
Tags           :

最初のコマンドは 、ConvertTo-SecureString コマンドレットを使用して文字列をセキュリティで保護された文字列に変換し、その文字列を $Password 変数に格納します。 詳細を表示するには「Get-Help ConvertTo-SecureString」を入力します。 2 番目のコマンドは、Contoso キー コンテナーにソフトウェア パスワードを作成します。 このコマンドは、キーの場所と、$Passwordに格納されているパスワードを指定します。

例 6: キーをインポートして属性を割り当てる

PS C:\> $Password = ConvertTo-SecureString -String 'password' -AsPlainText -Force
PS C:\> $Expires = (Get-Date).AddYears(2).ToUniversalTime()
PS C:\> $Tags = @{ 'Severity' = 'high'; 'Accounting' = "true" }
PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITPfxToHSM' -Destination 'HSM' -KeyFilePath 'C:\Contoso\ITPfx.pfx' -KeyFilePassword $Password -Expires $Expires -Tag $Tags

Vault Name     : contoso
Name           : ITPfxToHSM
Version        : 929bfc14db84439b823ffd1bedadaf5f
Id             : https://contoso.vault.azure.net:443/keys/ITPfxToHSM/929bfc14db84439b823ffd1bedadaf5f
Enabled        : True
Expires        : 5/21/2020 11:12:43 PM
Not Before     : 
Created        : 5/21/2018 11:13:17 PM
Updated        : 5/21/2018 11:13:17 PM
Purge Disabled : False
Tags           : Name        Value
                 Severity    high
                 Accounting  true

最初のコマンドは 、ConvertTo-SecureString コマンドレットを使用して文字列をセキュリティで保護された文字列に変換し、その文字列を $Password 変数に格納します。 2 番目のコマンドは、Get-Date コマンドレットを使用して DateTime オブジェクトを作成し、そのオブジェクトを $Expires 変数に格納します。 3 番目のコマンドでは、重大度と IT の重要度が高いタグを設定する$tags変数を作成します。 最後のコマンドは、指定した場所から HSM キーとしてキーをインポートします。 このコマンドは、$Expiresに格納されている有効期限と、$Passwordに格納されているパスワードを指定し、$tagsに格納されているタグを適用します。

パラメーター

-Confirm

コマンドレットの実行前に確認を求めるメッセージが表示されます。

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

-DefaultProfile

Azure との通信に使用される資格情報、アカウント、テナント、サブスクリプション

Type:IAzureContextContainer
Aliases:AzureRmContext, AzureCredential
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Destination

キーをソフトウェアで保護されたキーとして追加するか、HSM で保護されたキーとして Key Vault サービスに追加するかを指定します。 有効な値は、HSM とソフトウェアです。 注: HSM を宛先として使用するには、HSM をサポートするキー コンテナーが必要です。 Azure Key Vault のサービス レベルと機能の詳細については、Azure Key Vault 価格 Web サイトを参照してください。 このパラメーターは、新しいキーを作成するときに必要です。 KeyFilePath パラメーターを使用してキーをインポートする場合、このパラメーターは省略可能です。

  • このパラメーターを指定せず、このコマンドレットが .byok ファイル名拡張子を持つキーをインポートすると、そのキーが HSM で保護されたキーとしてインポートされます。 コマンドレットでは、そのキーをソフトウェアで保護されたキーとしてインポートできません。
  • このパラメーターを指定せず、このコマンドレットが .pfx ファイル名拡張子を持つキーをインポートすると、ソフトウェアで保護されたキーとしてキーがインポートされます。
Type:String
Accepted values:HSM, Software, HSM, Software
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Disable

追加するキーが初期状態の無効に設定されていることを示します。 キーを使用しようとすると失敗します。 後で有効にするキーを事前に読み込む場合は、このパラメーターを使用します。

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

-Expires

このコマンドレットによって追加されるキーの有効期限を DateTime オブジェクトとして指定します。 このパラメーターは世界協定時刻 (UTC) を使用します。 DateTime オブジェクトを取得するには、Get-Date コマンドレットを使用します。 詳細を表示するには「Get-Help Get-Date」を入力します。 このパラメーターを指定しない場合、キーは期限切れになりません。

Type:Nullable<T>[DateTime]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

コンテナー オブジェクト。

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

-KeyFilePassword

インポートしたファイルのパスワードを SecureString オブジェクトとして指定します。 SecureString オブジェクトを取得するには、ConvertTo-SecureString コマンドレットを使用します。 詳細を表示するには「Get-Help ConvertTo-SecureString」を入力します。 ファイル名拡張子が .pfx のファイルをインポートするには、このパスワードを指定する必要があります。

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

-KeyFilePath

このコマンドレットがインポートするキー マテリアルを含むローカル ファイルのパスを指定します。 有効なファイル名拡張子は .byok と .pfx です。

  • ファイルが .byok ファイルの場合、インポート後に HSM によってキーが自動的に保護されるため、この既定値をオーバーライドすることはできません。
  • ファイルが .pfx ファイルの場合、キーはインポート後にソフトウェアによって自動的に保護されます。 この既定値をオーバーライドするには、キーが HSM で保護されるように 、Destination パラメーターを HSM に設定します。 このパラメーターを指定すると、 Destination パラメーターは省略可能です。
Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-KeyOps

このコマンドレットによって追加されるキーを使用して実行できる操作の配列を指定します。 このパラメーターを指定しない場合、すべての操作を実行できます。 このパラメーターの値には、JSON Web Key (JWK) 仕様で定義されたキー操作のリストをコンマ区切りで指定できます。

  • Encrypt
  • 復号化
  • ラップ
  • ラップ解除
  • 署名
  • 確認
Type:String[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Name

キー コンテナーに追加するキーの名前を指定します。 このコマンドレットは、このパラメーターで指定する名前、キー コンテナーの名前、および現在の環境に基づいて、キーの完全修飾ドメイン名 (FQDN) を構築します。 名前は、0 から 9 文字、a から z、A から Z、および - (ダッシュ記号) のみを含む長さの 1 ~ 63 文字の文字列である必要があります。

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

-NotBefore

キーを使用できない時刻を DateTime オブジェクトとして指定します。 このパラメーターは UTC を使用します。 DateTime オブジェクトを取得するには、Get-Date コマンドレットを使用します。 このパラメーターを指定しない場合は、キーをすぐに使用できます。

Type:Nullable<T>[DateTime]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ResourceId

コンテナーのリソース ID。

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

-Size

RSA キー サイズ (ビット単位)。 指定しない場合、サービスは安全な既定値を提供します。

Type:Nullable<T>[Int32]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-Tag

ハッシュ テーブルの形式のキーと値のペア。 例: @{key0="value0";key1=$null;key2="value2"}

Type:Hashtable
Aliases:Tags
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-VaultName

このコマンドレットがキーを追加するキー コンテナーの名前を指定します。 このコマンドレットは、このパラメーターが指定する名前と現在の環境に基づいて、キー コンテナーの FQDN を構築します。

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

-WhatIf

コマンドレットの実行時に発生する内容を示します。 このコマンドレットは実行されません。

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

入力

PSKeyVault

パラメーター: InputObject (ByValue)

String

出力

PSKeyVaultKey