AWS CloudHSM クライアント SDK 3 でサポートされる Java キー属性

このトピックでは、Java ライブラリバージョン 3.1 の独自の拡張機能を使用して、AWS CloudHSM クライアント SDK 3 のキー属性を設定する方法について説明します。この拡張機能を使用して、これらのオペレーション中にサポートされるキー属性とその値を設定します。

属性について

キー属性を使用して、パブリックキー、プライベートキー、シークレットキーなど、キーオブジェクトで許可されるアクションを指定します。キー属性と値は、キーオブジェクトの作成オペレーション中に定義します。

ただし、Java Cryptography Extension (JCE) では、キー属性に値を設定する方法が指定されていないため、ほとんどのアクションがデフォルトで許可されていました。これに対して、PKCS # 11 標準では、より制限の厳しいデフォルトのある包括的な属性のセットが定義されています。Java ライブラリバージョン 3.1 以降、CloudHSM は、一般的に使用される属性に対してより制限の厳しい値を設定できる独自の拡張機能を提供します。

サポートされている属性

次の表に示す属性の値を設定できます。ベストプラクティスとして、制限する属性の値のみを設定してください。値を指定しない場合、CloudHSM は次の表で指定されたデフォルト値を使用します。デフォルト値の列のセルが空の場合は、属性に割り当てられている特定のデフォルト値がないことを示します。

キーの属性設定

CloudHsmKeyAttributesMap は Java Map のようなオブジェクトで、キーオブジェクトの属性値を設定するために使用できます。CloudHsmKeyAttributesMap 関数のメソッドは、Java マップ操作のメソッドと同様です。

属性にカスタム値を設定するには、次の 2 つのオプションがあります。

属性マップオブジェクトは、属性を設定するための次のメソッドをサポートしています。

ビルダーパターンの例

通常、開発者にとっては、ビルダーパターンを介してクラスを利用する方がより便利です。例:

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();						

まとめ

キーオペレーションでキー属性を指定するには、次の手順に従います。

参考のために、次の表に、カスタムキー属性をサポートする Cavium*ParameterSpec クラスとメソッドを示します。

サンプルコード: キーの生成とラップ

次の簡単なコードサンプルは、キー生成とキーラップの 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);