翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS CloudHSM クライアント SDK 3 でサポートされている Java キー属性
このトピックでは、Java ライブラリバージョン 3.1 の独自の拡張機能を使用して、 AWS CloudHSM クライアント SDK 3 のキー属性を設定する方法について説明します。この拡張機能を使用して、これらのオペレーション中にサポートされるキー属性とその値を設定します。
+ キー生成
+ キーのインポート
+ キーのラップ解除
**注記**
カスタムキー属性を設定するための拡張機能は、オプション機能です。Java ライブラリバージョン 3.0 で機能するコードがすでにある場合、そのコードを変更する必要はありません。作成したキーには、以前と同じ属性が引き続き含まれます。
**Topics**
+ [属性について](#java-understanding-attributes)
+ [サポートされている 属性](#java-attributes)
+ [キーの属性設定](#java-setting-attributes)
+ [まとめ](#java-attributes-summary)
## 属性について
キー属性を使用して、パブリックキー、プライベートキー、シークレットキーなど、キーオブジェクトで許可されるアクションを指定します。キー属性と値は、キーオブジェクトの作成オペレーション中に定義します。
ただし、Java Cryptography Extension (JCE) では、キー属性に値を設定する方法が指定されていないため、ほとんどのアクションがデフォルトで許可されていました。これに対して、PKCS \$1 11 標準では、より制限の厳しいデフォルトのある包括的な属性のセットが定義されています。Java ライブラリバージョン 3.1 以降、CloudHSM は、一般的に使用される属性に対してより制限の厳しい値を設定できる独自の拡張機能を提供します。
## サポートされている 属性
次の表に示す属性の値を設定できます。ベストプラクティスとして、制限する属性の値のみを設定してください。値を指定しない場合、CloudHSM は次の表で指定されたデフォルト値を使用します。デフォルト値の列のセルが空の場合は、属性に割り当てられている特定のデフォルト値がないことを示します。
****
| 属性 | デフォルト値 | 注意事項 |
| --- | --- | --- |
| | 対称キー | キーペアのパブリックキー | キーペアのプライベートキー | |
| CKA\$1TOKEN | FALSE | FALSE | FALSE | クラスター内のすべての HSM にレプリケートされ、バックアップに含まれる永続的なキー。CKA\$1TOKEN = FALSE は、セッションキーを意味します。セッションキーは 1 つの HSM にのみロードされ、HSM への接続が切断されると自動的に消去されます。 |
| CKA\$1LABEL | | | | ユーザー定義の文字列。これにより、HSM のキーを簡単に識別できます。 |
| CKA\$1EXTRACTABLE | TRUE | | TRUE | True は、このキーを HSM からエクスポートできることを示します。 |
| CKA\$1ENCRYPT | TRUE | TRUE | | True は、キーを使用して任意のバッファを暗号化できることを示します。 |
| CKA\$1DECRYPT | TRUE | | TRUE | True は、キーを使用して任意のバッファを復号できることを示します。通常は、CKA\$1WRAP が true に設定されているキーに対して、これを FALSE に設定します。 |
| CKA\$1WRAP | TRUE | TRUE | | True は、キーを使用して別のキーをラップできることを示します。通常、プライベートキーの場合、これを FALSE に設定します。 |
| CKA\$1UNWRAP | TRUE | | TRUE | True は、キーを使用して別のキーをラップ解除 (インポート) できることを示します。 |
| CKA\$1SIGN | TRUE | | TRUE | True は、キーを使用してメッセージダイジェストに署名できることを示します。パブリックキーおよびアーカイブしたプライベートキーの場合、通常 FALSE に設定されます。 |
| CKA\$1VERIFY | TRUE | TRUE | | True は、キーを使用して署名を検証できることを示します。これは通常、プライベートキーの場合、FALSE に設定されます。 |
| CKA\$1PRIVATE | TRUE | TRUE | TRUE | True は、ユーザーが認証されるまで、ユーザーがキーにアクセスできないことを示します。わかりやすくするために、この属性が FALSE に設定されている場合でも、ユーザーが認証されるまで CloudHSM のどのキーにもアクセスできません。 |
**注記**
PKCS \$111 ライブラリでは、より広範な属性がサポートされます。詳細については、「[サポートされている PKCS \$111 属性](pkcs11-attributes.md)」を参照してください。
## キーの属性設定
`CloudHsmKeyAttributesMap` は [Java Map](https://devdocs.io/openjdk~8/java/util/map) のようなオブジェクトで、キーオブジェクトの属性値を設定するために使用できます。`CloudHsmKeyAttributesMap` 関数のメソッドは、Java マップ操作のメソッドと同様です。
属性にカスタム値を設定するには、次の 2 つのオプションがあります。
+ 次の表に示す方法を使用します。
+ このドキュメントの後半で説明するビルダーパターンの使用
属性マップオブジェクトは、属性を設定するための次のメソッドをサポートしています。
****
| 運用 | 戻り値 | `CloudHSMKeyAttributesMap` 方法 |
| --- | --- | --- |
| 既存のキーのキー属性の値を取得する | オブジェクト (値を含む) または null | **get**(keyAttribute) |
| 1 つのキー属性の値を入力します。 | キー属性のマッピングがなかった場合、キー属性に関連付けられた以前の値、または null | **put**(keyAttribute, value) |
| 複数のキー属性の値を設定する | 該当なし | **putAll**(keyAttributesMap) |
| 属性マップからキーと値のペアを削除する | キー属性のマッピングがなかった場合、キー属性に関連付けられた以前の値、または *null* | **remove**(keyAttribute) |
**注記**
明示的に指定しない属性は、上記の [サポートされている 属性](#java-attributes) の表に示したデフォルトに設定されます。
### ビルダーパターンの例
通常、開発者にとっては、ビルダーパターンを介してクラスを利用する方がより便利です。例:
```
import com.amazonaws.cloudhsm.CloudHsmKeyAttributes;
import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap;
import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap;
CloudHsmKeyAttributesMap keyAttributesSessionDecryptionKey =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "ExtractableSessionKeyEncryptDecrypt")
.put(CloudHsmKeyAttributes.CKA_WRAP, false)
.put(CloudHsmKeyAttributes.CKA_UNWRAP, false)
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_VERIFY, false)
.build();
CloudHsmKeyAttributesMap keyAttributesTokenWrappingKey =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "TokenWrappingKey")
.put(CloudHsmKeyAttributes.CKA_TOKEN, true)
.put(CloudHsmKeyAttributes.CKA_ENCRYPT, false)
.put(CloudHsmKeyAttributes.CKA_DECRYPT, false)
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_VERIFY, false)
.build();
```
開発者は、キーテンプレートのベストプラクティスを実施するための便利な方法として、事前に定義された属性セットを利用することもできます。例:
```
//best practice template for wrapping keys
CloudHsmKeyAttributesMap commonKeyAttrs = new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, false)
.put(CloudHsmKeyAttributes.CKA_DECRYPT, false)
.build();
// initialize a new instance of CloudHsmKeyAttributesMap by copying commonKeyAttrs
// but with an appropriate label
CloudHsmKeyAttributesMap firstKeyAttrs = new CloudHsmKeyAttributesMap(commonKeyAttrs);
firstKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, "key label");
// alternatively, putAll() will overwrite existing values to enforce conformance
CloudHsmKeyAttributesMap secondKeyAttrs = new CloudHsmKeyAttributesMap();
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_DECRYPT, true);
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_ENCRYPT, true);
secondKeyAttrs.put(CloudHsmKeyAttributes.CKA_LABEL, “safe wrapping key”);
secondKeyAttrs.putAll(commonKeyAttrs); // will overwrite CKA_DECRYPT to be FALSE
```
### キーペアの属性設定
Java クラス `CloudHsmKeyPairAttributesMap` を使用して、キーペアのキー属性を処理します。`CloudHsmKeyPairAttributesMap` は、2 つの `CloudHsmKeyAttributesMap` オブジェクトをカプセル化します。1 つはパブリックキー用ともう 1 つはプライベートキー用です。
パブリックキーとプライベートキーの個々の属性を個別に設定するには、そのキーの対応する `CloudHsmKeyAttributes` マップオブジェクトで `put()` メソッドを使用できます。`getPublic()` メソッドを使用してパブリックキーの属性マップを取得し、`getPrivate()` を使用してプライベートキーの属性マップを取得します。引数としてキーペア属性マップを使用する `putAll()` を使用して、パブリックキーペアとプライベートキーペアの両方に、複数のキー属性の値を一緒に入力します。
### ビルダーパターンの例
通常、開発者にとっては、ビルダーパターンを介してキー属性を設定する方がより便利です。例：
```
import com.amazonaws.cloudhsm.CloudHsmKeyAttributes;
import com.amazonaws.cloudhsm.CloudHsmKeyAttributesMap;
import com.amazonaws.cloudhsm.CloudHsmKeyPairAttributesMap;
//specify attributes up-front
CloudHsmKeyAttributesMap keyAttributes =
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_SIGN, false)
.put(CloudHsmKeyAttributes.CKA_LABEL, "PublicCertSerial12345")
.build();
CloudHsmKeyPairAttributesMap keyPairAttributes =
new CloudHsmKeyPairAttributesMap.Builder()
.withPublic(keyAttributes)
.withPrivate(
new CloudHsmKeyAttributesMap.Builder() //or specify them inline
.put(CloudHsmKeyAttributes.CKA_LABEL, "PrivateCertSerial12345")
.put (CloudHSMKeyAttributes.CKA_WRAP, FALSE)
.build()
)
.build();
```
**注記**
この独自の拡張機能の詳細については、GitHub の [Javadoc](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Docs/CloudHsm_CustomKeyAttributes_Javadoc.zip) アーカイブと [sample](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/master/src/main/java/com/amazonaws/cloudhsm/examples/CustomKeyAttributesRunner.java) を参照してください。Javadoc を調べるには、アーカイブをダウンロードして展開します。
## まとめ
キーオペレーションでキー属性を指定するには、次の手順に従います。
1. 対称キーの `CloudHsmKeyAttributesMap`、またはキーペアの `CloudHsmKeyPairAttributesMap` をインスタンス化します。
1. 必要なキー属性と値を使用して、ステップ 1 からの属性オブジェクトを定義します。
1. 特定のキータイプに対応する `Cavium*ParameterSpec` クラスをインスタンス化し、この設定された属性オブジェクトをコンストラクタに渡します。
1. この `Cavium*ParameterSpec` オブジェクトを対応する暗号クラスまたはメソッドに渡します。
参考のために、次の表に、カスタムキー属性をサポートする `Cavium*ParameterSpec` クラスとメソッドを示します。
****
| キータイプ | パラメータ仕様クラス | コンストラクタの例 |
| --- | --- | --- |
| 基本クラス | CaviumKeyGenAlgorithmParameterSpec | CaviumKeyGenAlgorithmParameterSpec(CloudHsmKeyAttributesMap keyAttributesMap) |
| DES | CaviumDESKeyGenParameterSpec | CaviumDESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) |
| RSA | CaviumRSAKeyGenParameterSpec | CaviumRSAKeyGenParameterSpec(int keysize, BigInteger publicExponent, CloudHsmKeyPairAttributesMap keyPairAttributesMap) |
| シークレット | CaviumGenericSecretKeyGenParameterSpec | CaviumGenericSecretKeyGenParameterSpec(int size, CloudHsmKeyAttributesMap keyAttributesMap) |
| AES | CaviumAESKeyGenParameterSpec | CaviumAESKeyGenParameterSpec(int keySize, byte[] iv, CloudHsmKeyAttributesMap keyAttributesMap) |
| EC | CaviumECGenParameterSpec | CaviumECGenParameterSpec(String stdName, CloudHsmKeyPairAttributesMap keyPairAttributesMap) |
### サンプルコード: キーの生成とラップ
次の簡単なコードサンプルは、キー生成とキーラップの 2 つの異なるオペレーションの手順を示しています。
```
// Set up the desired key attributes
KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec keyAttributes = new CaviumAESKeyGenParameterSpec(
256,
new CloudHsmKeyAttributesMap.Builder()
.put(CloudHsmKeyAttributes.CKA_LABEL, "MyPersistentAESKey")
.put(CloudHsmKeyAttributes.CKA_EXTRACTABLE, true)
.put(CloudHsmKeyAttributes.CKA_TOKEN, true)
.build()
);
// Assume we already have a handle to the myWrappingKey
// Assume we already have the wrappedBytes to unwrap
// Unwrap a key using Custom Key Attributes
CaviumUnwrapParameterSpec unwrapSpec = new CaviumUnwrapParameterSpec(myInitializationVector, keyAttributes);
Cipher unwrapCipher = Cipher.getInstance("AESWrap", "Cavium");
unwrapCipher.init(Cipher.UNWRAP_MODE, myWrappingKey, unwrapSpec);
Key unwrappedKey = unwrapCipher.unwrap(wrappedBytes, "AES", Cipher.SECRET_KEY);
```