翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS CloudHSM クライアント SDK 5 の JCE プロバイダー
AWS CloudHSM JCE プロバイダーは、Java 暗号化拡張 (JCE) プロバイダーフレームワークから構築されたプロバイダー実装です。JCE では、Java 開発キット (JDK) を使用して暗号化操作を実行できます。このガイドでは、 AWS CloudHSM JCE プロバイダーは JCE プロバイダーと呼ばれることがあります。JCE プロバイダーと JDK を使用して、HSM に暗号化操作をオフロードします。トラブルシューティングについては、「[JCE SDK for の既知の問題 AWS CloudHSM](ki-jce-sdk.md)」を参照してください。
クライアント SDK 3 の使用の詳細については、「[以前の SDK バージョンを使用して を操作する AWS CloudHSM](choose-client-sdk.md)」を参照してください。
**Topics**
+ [AWS CloudHSM クライアント SDK 5 の JCE プロバイダーをインストールする](java-library-install_5.md)
+ [AWS CloudHSM クライアント SDK 5 の JCE プロバイダーでサポートされているキータイプ](java-lib-keys_5.md)
+ [AWS CloudHSM クライアント SDK 5 の JCE プロバイダーにおけるキー管理の基本](java-library-key-basics_5.md)
+ [AWS CloudHSM クライアント SDK 5 の JCE プロバイダーでサポートされているメカニズム](java-lib-supported_5.md)
+ [AWS CloudHSM クライアント SDK 5 でサポートされている Java キー属性](java-lib-attributes_5.md)
+ [Java for Client SDK 5 用の AWS CloudHSM ソフトウェアライブラリのコードサンプル](java-samples.md)
+ [AWS CloudHSM JCE プロバイダー Javadocs](java-javadocs_5.md)
+ [クライアント SDK 5 のAWS CloudHSM KeyStore Java クラス](alternative-keystore_5.md)
+ [AWS CloudHSM JCE for Client SDK 5 の詳細設定](java-lib-configs.md)
# AWS CloudHSM クライアント SDK 5 の JCE プロバイダーをインストールする
AWS CloudHSM クライアント SDK 5 の JCE プロバイダーは、OpenJDK 8、OpenJDK 11、OpenJDK 17、OpenJDK 21、および OpenJDK 25 と互換性があります。どちらも [OpenJDK のウェブサイト](https://openjdk.java.net/)からダウンロードできます。
以下のセクションを使用して、プロバイダーをインストールし、認証情報をプロバイダーに提供します。
**注記**
クライアント SDK 5 で単一の HSM クラスターを実行するには、まず `disable_key_availability_check` を `True` に設定してクライアントキーの耐久性の設定を管理する必要があります。詳細については、[キーの同期](manage-key-sync.md) と [クライアント SDK 5 設定ツール](configure-sdk-5.md) を参照してください。
**Topics**
+ [ステップ 1: JCE プロバイダーをインストールする](#install-java-library_5)
+ [ステップ 2: JCE プロバイダーに認証情報を提供する](#java-library-credentials_5)
## ステップ 1: JCE プロバイダーをインストールする
1. 以下のコマンドを使用して、JCE プロバイダーをダウンロードし,インストールします。
------
#### [ Amazon Linux 2023 ]
X86\$164 アーキテクチャ上で Amazon Linux 2023 用の JCE プロバイダーをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.x86_64.rpm
```
Amazon Linux 2023 用の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
X86\$164 アーキテクチャ上で Amazon Linux 2 用の JCE プロバイダーをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.x86_64.rpm
```
Amazon Linux 2 用の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-jce-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
RHEL 10 の JCE プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.x86_64.rpm
```
RHEL 10 の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-jce-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
RHEL 9 (9.2 以降) 用の JCE プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.x86_64.rpm
```
RHEL 9 (9.2 以降) 用の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-jce-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
RHEL 8 用の JCE プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.x86_64.rpm
```
RHEL 8 の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-jce-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-jce-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Ubuntu 24.04 LTS 用の JCE プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_amd64.deb
```
Ubuntu 24.04 LTS 用の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-jce_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Ubuntu 22.04 LTS 用の JCE プロバイダーを X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_amd64.deb
```
Ubuntu 22.04 LTS 用の JCE プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-jce_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-jce_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
Windows Server 用の JCE プロバイダーを x86\$164 アーキテクチャにインストールし、管理者として PowerShell を開き、以下のコマンドを実行します。
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMJCE-latest.msi -Outfile C:\AWSCloudHSMJCE-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMJCE-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
------
1. クライアント SDK 5 をブートストラップします。ブートストラップの詳細については、[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to) を参照してください。
1. 次の JCE プロバイダーファイルを見つけます。
------
#### [ Linux ]
+ `/opt/cloudhsm/java/cloudhsm-.jar`
+ `/opt/cloudhsm/bin/configure-jce`
+ `/opt/cloudhsm/bin/jce-info`
------
#### [ Windows ]
+ `C:\Program Files\Amazon\CloudHSM\java\cloudhsm-.jar>`
+ `C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe`
+ `C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe`
------
## ステップ 2: JCE プロバイダーに認証情報を提供する
HSM では、Java アプリケーションが HSM を使用する前に、Java アプリケーションを認証する必要があります。HSM は、明示的なログインと暗黙的なログイン方法のいずれかを使用して認証します。
**明示的なログイン** - この方法では、 AWS CloudHSM 認証情報をアプリケーションに直接渡すことができます。CU ユーザー名とパスワードを PIN パターンで渡す [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html) を使用します。詳細については、「[Login to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)」のコード例を参照してください。
**暗黙的なログイン** - この方法では、 AWS CloudHSM 認証情報を、新しいプロパティファイルまたはシステムプロパティで設定するか、環境変数として設定することができます。
+ **System properties** - アプリケーションの実行時に、システムプロパティを通して認証情報を設定します。次の例は、これを行うための 2 つの異なる方法を示しています。
------
#### [ Linux ]
```
$ java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
#### [ Windows ]
```
PS C:\> java -DHSM_USER= -DHSM_PASSWORD=
```
```
System.setProperty("HSM_USER","");
System.setProperty("HSM_PASSWORD","");
```
------
+ **Environment variables** - 認証情報を環境変数として設定します。
**注記**
環境変数を設定するときは、シェルによって解釈される可能性のある特殊文字をエスケープする必要があります。
------
#### [ Linux ]
```
$ export HSM_USER=
$ export HSM_PASSWORD=
```
------
#### [ Windows ]
```
PS C:\> $Env:HSM_USER=""
PS C:\> $Env:HSM_PASSWORD=""
```
------
アプリケーションで設定されない場合、または HSM でセッションを認証する前にユーザーが操作を行った場合は、認証情報を使用できない場合があります。このような場合は、Java 用の CloudHSM ソフトウェアライブラリによって、次の順序で認証情報が検索されます。
1. システムプロパティ
1. 環境変数
# AWS CloudHSM クライアント SDK 5 の JCE プロバイダーでサポートされているキータイプ
Java 用の AWS CloudHSM ソフトウェアライブラリでは、次のキータイプを生成できます。
****
| キータイプ | 説明 |
| --- | --- |
| AES | 128、192、256 ビットの AES キーを生成します。 |
| Triple DES (3DES、DESede) | 192 ビットトリプル DES キー を生成します[*](#java-lib-keys_5-note-1)。 |
| EC | EC キーペア — NIST 曲線 secp224r1 (P-224)、secp256r1 (P-256)、secp256k1 (ブロックチェーン)、secp384r1 (P-384)、secp521r1 (P-521) を生成します。 |
| [GENERIC\$1SECRET] | 1～800 バイトの汎用シークレットを生成します。 |
| HMAC | SHA1、SHA224、SHA256、SHA384、SHA512 のハッシュサポート。 |
| RSA | 256 ビットの増分で、2,048～4,096 ビットの RSA キーを生成します。 |
\$1 NIST のガイダンスに従い、2023 年以降の FIPS モードのクラスターでは、これは許可されません。FIPS 以外のモードのクラスターでは、2023 年以降も許可されます。詳細については、「[FIPS 140 コンプライアンス: 2024 年 メカニズムの非推奨](compliance-dep-notif.md#compliance-dep-notif-1)」を参照してください。
# AWS CloudHSM クライアント SDK 5 の JCE プロバイダーにおけるキー管理の基本
JCE プロバイダー中のキー管理の基本には、キーのインポート、キーのエクスポート、ハンドルによるキーのロード、またはキーの削除などがあります。キーの管理の詳細については、「[キーの管理](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)」のサンプルコードを参照してください。
また、JCE プロバイダーのサンプルコードについては、[コードサンプル](java-samples.md) で参照できます。
# AWS CloudHSM クライアント SDK 5 の JCE プロバイダーでサポートされているメカニズム
このトピックでは、 AWS CloudHSM クライアント SDK 5 で JCE プロバイダーでサポートされているメカニズムについて説明します。でサポートされている Java 暗号化アーキテクチャ (JCA) インターフェイスとエンジンクラスの詳細については AWS CloudHSM、以下のトピックを参照してください。
**Topics**
+ [キーとキーペアの関数を生成する](#java-gen-key-pairs-5)
+ [暗号関数](#java-ciphers_5)
+ [署名および検証](#java-sign-verify_5)
+ [ダイジェスト関数](#java-digests_5)
+ [Hash-based Message Authentication Code (HMAC) 関数](#java-mac_5)
+ [暗号ベースのメッセージ認証コード (CMAC) 関数](#java-cmac_5)
+ [キー共有機能](#java-key-derivation_5)
+ [キーファクトリを使用してキーをキー仕様に変換します](#java-key-factories)
+ [メカニズムの注釈](#w2aac25c21c25c15c23)
## キーとキーペアの関数を生成する
Java 用 AWS CloudHSM ソフトウェアライブラリでは、次のオペレーションを使用してキーとキーペア関数を生成できます。
+ `RSA`
+ `EC`
+ `AES`
+ `DESede (Triple DES)`注記「[1](#java-gen-key-pairs-5-note-1)」を参照
+ `GenericSecret`
## 暗号関数
Java 用 AWS CloudHSM ソフトウェアライブラリは、次のアルゴリズム、モード、パディングの組み合わせをサポートしています。
| アルゴリズム | モード | [Padding] (パディング) | 注意事項 |
| --- | --- | --- | --- |
| AES | CBC | `AES/CBC/NoPadding` `AES/CBC/PKCS5Padding` | `Cipher.ENCRYPT_MODE` および `Cipher.DECRYPT_MODE` を実装します。 `Cipher.UNWRAP_MODE for AES/CBC NoPadding` を実装します |
| AES | ECB | `AES/ECB/PKCS5Padding` `AES/ECB/NoPadding` | `Cipher.ENCRYPT_MODE` および `Cipher.DECRYPT_MODE` を実装します。 |
| AES | CTR | `AES/CTR/NoPadding` | `Cipher.ENCRYPT_MODE` および `Cipher.DECRYPT_MODE` を実装します。 |
| AES | GCM | `AES/GCM/NoPadding` | `Cipher.WRAP_MODE`、`Cipher.UNWRAP_MODE`、`Cipher.ENCRYPT_MODE`、および `Cipher.DECRYPT_MODE` を実装します。AES-GCM 暗号化の実行時に、HSM はリクエスト内の初期化ベクトル (IV) を無視し、独自に IV を生成して使用します。オペレーションが完了したら、`Cipher.getIV()` を呼び出して IV を取得する必要があります。 |
| AESWrap | ECB | `AESWrap/ECB/NoPadding` `AESWrap/ECB/PKCS5Padding` `AESWrap/ECB/ZeroPadding` | `Cipher.WRAP_MODE` および `Cipher.UNWRAP_MODE` を実装します。 |
| DESede (Triple DES) | CBC | `DESede/CBC/PKCS5Padding` `DESede/CBC/NoPadding` | `Cipher.ENCRYPT_MODE` および `Cipher.DECRYPT_MODE` を実装します。今後の変更については、以下の注記「[1](#java-gen-key-pairs-5-note-1)」を参照してください。 |
| DESede (Triple DES) | ECB | `DESede/ECB/NoPadding` `DESede/ECB/PKCS5Padding` | `Cipher.ENCRYPT_MODE` および `Cipher.DECRYPT_MODE` を実装します。今後の変更については、以下の注記「[1](#java-gen-key-pairs-5-note-1)」を参照してください。 |
| RSA | ECB | `RSA/ECB/PKCS1Padding` **注記「[1](#java-gen-key-pairs-5-note-1)」を参照** `RSA/ECB/OAEPPadding` `RSA/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSA/ECB/OAEPWithSHA-512ANDMGF1Padding` | `Cipher.WRAP_MODE`、`Cipher.UNWRAP_MODE`、`Cipher.ENCRYPT_MODE`、および `Cipher.DECRYPT_MODE` を実装します。 |
| RSA | ECB | `RSA/ECB/NoPadding` | `Cipher.ENCRYPT_MODE` および `Cipher.DECRYPT_MODE` を実装します。 |
| RSAAESWrap | ECB | `RSAAESWrap/ECB/OAEPPadding` `RSAAESWrap/ECB/OAEPWithSHA-1ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-224ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-256ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-384ANDMGF1Padding` `RSAAESWrap/ECB/OAEPWithSHA-512ANDMGF1Padding` | `Cipher.WRAP_MODE` および `Cipher.UNWRAP_MODE` を実装します。 |
## 署名および検証
Java 用 AWS CloudHSM ソフトウェアライブラリは、次のタイプの署名と検証をサポートしています。クライアント SDK 5 とハッシュ機能付きの署名アルゴリズムでは、データはソフトウェアでローカルにハッシュされてから、署名/検証のために HSM に送信されます。つまり、SDK でハッシュできるデータのサイズに制限はありません。
**RSA 署名タイプ**
+ `NONEwithRSA`
+ `RSASSA-PSS`
+ `SHA1withRSA`
+ `SHA1withRSA/PSS`
+ `SHA1withRSAandMGF1`
+ `SHA224withRSA`
+ `SHA224withRSAandMGF1`
+ `SHA224withRSA/PSS`
+ `SHA256withRSA`
+ `SHA256withRSAandMGF1`
+ `SHA256withRSA/PSS`
+ `SHA384withRSA`
+ `SHA384withRSAandMGF1`
+ `SHA384withRSA/PSS`
+ `SHA512withRSA`
+ `SHA512withRSAandMGF1`
+ `SHA512withRSA/PSS`
**ECDSA 署名タイプ**
+ `NONEwithECDSA`
+ `SHA1withECDSA`
+ `SHA224withECDSA`
+ `SHA256withECDSA`
+ `SHA384withECDSA`
+ `SHA512withECDSA`
## ダイジェスト関数
Java 用 AWS CloudHSM ソフトウェアライブラリは、次のメッセージダイジェストをサポートしています。クライアント SDK 5 では、データはソフトウェアでローカルにハッシュされます。つまり、SDK でハッシュできるデータのサイズに制限はありません。
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## Hash-based Message Authentication Code (HMAC) 関数
Java 用の AWS CloudHSM ソフトウェアライブラリは、次の HMAC アルゴリズムをサポートしています。
+ `HmacSHA1` (最大データサイズ (バイト): 16288)
+ `HmacSHA224` (最大データサイズ (バイト): 16256)
+ `HmacSHA256` (最大データサイズ (バイト): 16288)
+ `HmacSHA384` (最大データサイズ (バイト): 16224)
+ `HmacSHA512` (最大データサイズ (バイト): 16224)
## 暗号ベースのメッセージ認証コード (CMAC) 関数
CMAC (暗号ベースのメッセージ認証コード) は、ブロック暗号とシークレットキーを使用してメッセージ認証コード (MAC) を作成します。HMAC とは異なり、MAC にはハッシュ方式ではなくブロック対称キーメソッドを使用します。
Java 用 AWS CloudHSM ソフトウェアライブラリは、次の CMAC アルゴリズムをサポートしています。
+ `AESCMAC`
## キー共有機能
Java 用の AWS CloudHSM ソフトウェアライブラリは、Key Derivation Functions (KDF) を使用した ECDH をサポートしています。サポートされている KDF の種類は次のとおりです。
+ `ECDHwithX963SHA1KDF` X9.63 KDF (SHA1 アルゴリズム) をサポート[2](#kdf2)
+ `ECDHwithX963SHA224KDF` X9.63 KDF (SHA224 アルゴリズム) をサポート[2](#kdf2)
+ `ECDHwithX963SHA256KDF` X9.63 KDF (SHA256 アルゴリズム) をサポート[2](#kdf2)
+ `ECDHwithX963SHA384KDF` X9.63 KDF (SHA384 アルゴリズム) をサポート[2](#kdf2)
+ `ECDHwithX963SHA512KDF` X9.63 KDF (SHA512 アルゴリズム) をサポート[2](#kdf2)
## キーファクトリを使用してキーをキー仕様に変換します
キーファクトリを使用してキーをキー仕様に変換できます。 AWS CloudHSM には、JCE 用の 2 種類のキーファクトリがあります。
**SecretKeyFactory:** 対称キーをインポートまたは派生させるために使用されます。SecretKeyFactory を使用すると、サポートされているキーまたはサポートされている KeySpec を渡して、対称キーを AWS CloudHSMにインポートまたは派生させることができます。KeyFactory でサポートされている仕様は次のとおりです。
+ SecretKeyFactory `generateSecret` のメソッドでは、以下の [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) クラスがサポートされています。
+ **KeyAttributesMap** を使用すると、追加の属性を含むキーバイトを CloudHSM キーとしてインポートできます。例は[こちら](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)からご覧いただけます。
+ **[SecretKeySpec](https://docs.oracle.com/javase/8/docs/api/javax/crypto/spec/SecretKeySpec.html)** を使用すると、対称キースペックを CloudHSM キーとしてインポートできます。
+ **AESCMackDFParameterSpec** を使用すると、別の CloudHSM AES キーを使用して対称キーを派生できます。
**注記**
SecretKeyFactory の `translateKey` メソッドは、[キー](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)インターフェイスを実装する任意のキーを受け取ります。
**KeyFactory:** 非対称キーのインポートに使用されます。SecretKeyFactory を使用すると、サポートされているキーまたはサポートされている KeySpec を渡して、非対称キーを AWS CloudHSMにインポートすることができます。詳細については、以下のリソースを参照してください。
+ KeyFactory `generatePublic` のメソッドでは、次の [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) クラスがサポートされています。
+ RSA と EC の両方の KeyTypes に対応する CloudHSM KeyAttributesMap には以下が含まれます。
+ RSA と EC の両方のパブリック KeyTypes に対応する CloudHSM KeyAttributesMap。例は[こちら](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)からご覧いただけます
+ RSA と EC パブリックキー両方向け [X509EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/X509EncodedKeySpec.html)
+ RSA パブリックキー向け [RSAPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPublicKeySpec.html)
+ EC パブリックキー向け [ECPublicKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPublicKeySpec.html)
+ KeyFactory `generatePrivate` のメソッドでは、次の [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) クラスがサポートされています。
+ RSA と EC の両方の KeyTypes に対応する CloudHSM KeyAttributesMap には以下が含まれます。
+ RSA と EC の両方のパブリック KeyTypes に対応する CloudHSM KeyAttributesMap。例は[こちら](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)からご覧いただけます
+ EC と RSA の両方のプライベートキー向け [PKCS8EncodedKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/PKCS8EncodedKeySpec.html)
+ RSA プライベートキー向け [RSAPrivateCrtKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/RSAPrivateCrtKeySpec.html)
+ EC プライベートキー向け [ECPrivateKeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/ECPrivateKeySpec.html)
KeyFactory の `translateKey` メソッドでは、[キーインターフェイス](https://docs.oracle.com/javase/8/docs/api/java/security/Key.html)を実装する任意のキーが取り込まれます。
## メカニズムの注釈
[1] NIST ガイダンスに従い、2023 年以降の FIPS モードのクラスターでは、これは許可されません。FIPS 以外のモードのクラスターでは、2023 年以降も許可されます。詳細については、「[FIPS 140 コンプライアンス: 2024 年 メカニズムの非推奨](compliance-dep-notif.md#compliance-dep-notif-1)」を参照してください。
[2] キー取得関数 (KDFs) は [NIST Special Publication 800-56A Revision 3 ](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf)で指定されています。
# AWS CloudHSM クライアント SDK 5 でサポートされている Java キー属性
このトピックでは、 AWS CloudHSM クライアント SDK 5 でサポートされている Java キー属性について説明します。このトピックでは、JCE プロバイダーの独自の拡張機能を使用してキーの属性を設定する方法について説明します。この拡張機能を使用して、これらのオペレーション中にサポートされるキー属性とその値を設定します。
+ キー生成
+ キーのインポート
キーアトリビュートの使用方法の例については、「[Java for Client SDK 5 用の AWS CloudHSM ソフトウェアライブラリのコードサンプル](java-samples.md)」を参照してください。
**Topics**
+ [属性について](#java-understanding-attributes_5)
+ [サポートされている 属性](#java-attributes_5)
+ [キーの属性設定](#java-setting-attributes_5)
## 属性について
キー属性を使用して、パブリックキー、プライベートキー、シークレットキーなど、キーオブジェクトで許可されるアクションを指定します。キー属性と値は、キーオブジェクトの作成オペレーション中に定義されます。
Java Cryptography Extension (JCE) では、キー属性に値を設定する方法が指定されていないため、ほとんどのアクションがデフォルトで許可されていました。これに対して、PKCS \$1 11 標準では、より制限の厳しいデフォルトのある包括的な属性のセットが定義されています。JCE プロバイダー 3.1 以降、 は一般的に使用される属性に対してより制限の厳しい値を設定できる独自の拡張機能 AWS CloudHSM を提供します。
## サポートされている 属性
次の表に示す属性の値を設定できます。ベストプラクティスとして、制限する属性の値のみを設定してください。値を指定しない場合、 は以下の表で指定されたデフォルト値 AWS CloudHSM を使用します。デフォルト値の列のセルが空の場合は、属性に割り当てられている特定のデフォルト値がないことを示します。
****
| 属性 | デフォルト値 | 注意事項 | | 対称キー | キーペアのパブリックキー | キーペアのプライベートキー | |
| --- | --- | --- | --- | --- | --- | --- | --- |
| DECRYPT | TRUE | | TRUE | True は、キーを使用して任意のバッファを復号できることを示します。通常、WRAP「true」に設定されているキーに対しては、これを「FALSE」に設定します。 |
| DERIVE | | | | キーを使用して他のキーを派生させることができます。 |
| ENCRYPT | TRUE | TRUE | | True は、キーを使用して任意のバッファを暗号化できることを示します。 |
| EXTRACTABLE | TRUE | | TRUE | True は、このキーを HSM からエクスポートできることを示します。 |
| ID | | | | キーを識別するためにユーザーが定義する値。 |
| KEY\$1TYPE | | | | キーのタイプ (AES、DESede、ジェネリックシークレット、EC、RSA) を識別するために使用されます。 |
| LABEL | | | | HSM 上のキーを簡単に識別できるユーザー定義の文字列。ベストプラクティスに従うには、後で見つけやすいように、各キーに固有のラベルを付けてください。 |
| LOCAL | | | | HSM によって生成されたキーを示します。 |
| OBJECT\$1CLASS | | | | キー (SecretKey、PublicKey、またはPrivateKey) のオブジェクトクラスを識別するために使用されます。 |
| PRIVATE | TRUE | TRUE | TRUE | True は、ユーザーが認証されるまで、ユーザーがキーにアクセスできないことを示します。わかりやすくするために、この属性が FALSE に設定されている場合でも、ユーザーは認証 AWS CloudHSM されるまで のキーにアクセスできません。 |
| SIGN | TRUE | | TRUE | True は、キーを使用してメッセージダイジェストに署名できることを示します。パブリックキーおよびアーカイブしたプライベートキーの場合、通常 FALSE に設定されます。 |
| SIZE | | | | キーのサイズを定義する属性。サポートされているキーサイズの詳細については、「[クライアント SDK 5 でサポートされているメカニズム](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-lib-supported_5.html#java-keys_5)」を参照してください。 |
| TOKEN | FALSE | FALSE | FALSE | クラスター内のすべての HSM にレプリケートされ、バックアップに含まれる永続的なキー。TOKEN = FALSE は、HSM への接続が切断されるかログアウトされると自動的に消去される一時キーを意味します。 |
| UNWRAP | TRUE | | TRUE | True は、キーを使用して別のキーをラップ解除 (インポート) できることを示します。 |
| VERIFY | TRUE | TRUE | | True は、キーを使用して署名を検証できることを示します。これは通常、プライベートキーの場合、FALSE に設定されます。 |
| WRAP | TRUE | TRUE | | True は、キーを使用して別のキーをラップできることを示します。通常、プライベートキーの場合、これを FALSE に設定します。 |
| WRAP\$1WITH\$1TRUSTED | FALSE | | FALSE | True は、TRUSTED 属性が true に設定されているキーでのみキーのラップとラップ解除ができることを示します。キーが true に WRAP\$1WITH\$1TRUSTED 設定されると、その属性は読み取り専用になり、false に設定できなくなります。トラストラッピングについて詳しくは、「[信頼できるキーを使ってキーのアンラップを制御する](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_using_trusted_keys_control_key_wrap.html)」をご覧ください。 |
**注記**
PKCS \$111 ライブラリでは、より広範な属性がサポートされます。詳細については、「[サポートされている PKCS \$111 属性](pkcs11-attributes.md)」を参照してください。
## キーの属性設定
`KeyAttributesMap` は Java Map のようなオブジェクトで、キーオブジェクトの属性値を設定するために使用できます。`KeyAttributesMap` 関数のメソッドは、Java マップ操作のメソッドと同様です。
属性にカスタム値を設定するには、次の 2 つのオプションがあります。
+ 次の表に示す方法を使用します。
+ このドキュメントの後半で説明するビルダーパターンの使用
属性マップオブジェクトは、属性を設定するための次のメソッドをサポートしています。
****
| 運用 | 戻り値 | `KeyAttributesMap` 方法 |
| --- | --- | --- |
| 既存のキーのキー属性の値を取得する | オブジェクト (値を含む) または null | **get**(keyAttribute) |
| 1 つのキー属性の値を入力します。 | キー属性のマッピングがなかった場合、キー属性に関連付けられた以前の値、または null | **put**(keyAttribute, value) |
| 複数のキー属性の値を設定する | 該当なし | **putAll**(keyAttributesMap) |
| 属性マップからキーと値のペアを削除する | キー属性のマッピングがなかった場合、キー属性に関連付けられた以前の値、または *null* | **remove**(keyAttribute) |
**注記**
明示的に指定しない属性は、上記の [サポートされている 属性](#java-attributes_5) の表に示したデフォルトに設定されます。
### キーペアの属性設定
Java クラス `KeyPairAttributesMap` を使用して、キーペアのキー属性を処理します。`KeyPairAttributesMap` は、2 つの `KeyAttributesMap` オブジェクトをカプセル化します。1 つはパブリックキー用ともう 1 つはプライベートキー用です。
パブリックキーとプライベートキーの個々の属性を個別に設定するには、そのキーの対応する `KeyAttributes` マップオブジェクトで `put()` メソッドを使用できます。`getPublic()` メソッドを使用してパブリックキーの属性マップを取得し、`getPrivate()` を使用してプライベートキーの属性マップを取得します。引数としてキーペア属性マップを使用する `putAll()` を使用して、パブリックキーペアとプライベートキーペアの両方に、複数のキー属性の値を一緒に入力します。
# Java for Client SDK 5 用の AWS CloudHSM ソフトウェアライブラリのコードサンプル
このトピックでは、 AWS CloudHSM クライアント SDK 5 の Java コードサンプルに関するリソースと情報を提供します。
## 前提条件
サンプルを実行する前に、環境をセットアップする必要があります。
+ [Java Cryptographic Extension (JCE) provider](java-library-install_5.md#install-java-library_5) をインストールして設定します。
+ 有効な [HSM ユーザー名とパスワード](manage-hsm-users.md)を設定します。これらのタスクには、暗号化ユーザー (CU) のアクセス権限で十分です。アプリケーションは、それぞれの例でこの認証情報を使用して HSM にログインします。
+ [JCE provider](java-library-install_5.md#java-library-credentials_5) へのクレデンシャルを提供する方法を決定します。
## コードサンプル
次のコードサンプルでは、基本タスクを実行するために、[AWS CloudHSM JCE provider](java-library.md) を使用する方法を示します。その他の例は [GitHub](https://github.com/aws-samples/aws-cloudhsm-jce-examples/tree/sdk5) から入手できます。
+ [HSM へのログイン](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)
+ [キーの管理](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)
+ [対称キーの生成](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)
+ [非対称キーの生成](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java)
+ [AES GCM による暗号化と復号](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java)
+ [Encrypt and decrypt with AES-CTR](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESCTREncryptDecryptRunner.java)
+ [DESede-ECB による暗号化と復号化](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/DESedeECBEncryptDecryptRunner.java) 注記 [1](#java-samples-code-5-note-1) 参照
+ [Sign and Verify with RSA Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [Sign and Verify with EC Keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/ECOperationsRunner.java)
+ [サポートされているキー属性の使用](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyAttributesRunner.java)
+ [CloudHSM キーストアの使用](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyStoreExampleRunner.java)
[1] NIST ガイダンスに従い、2023 年以降の FIPS モードのクラスターでは、これは許可されません。FIPS 以外のモードのクラスターでは、2023 年以降も許可されます。詳細については、「[FIPS 140 コンプライアンス: 2024 年 メカニズムの非推奨](compliance-dep-notif.md#compliance-dep-notif-1)」を参照してください。
# AWS CloudHSM JCE プロバイダー Javadocs
JCE プロバイダーの Javadocs を使用して、AWS CloudHSM JCE SDK で定義されている Java タイプとメソッドに関する使用情報を取得します。の最新の Javadocs をダウンロードするには AWS CloudHSM、ダウンロードページの [AWS CloudHSM 最新のクライアント SDK リリース](latest-releases.md)セクションを参照してください。
Javadocs は統合開発環境 (IDE) にインポートしたり、ウェブブラウザで表示することができます。
# クライアント SDK 5 のAWS CloudHSM KeyStore Java クラス
クラスは AWS CloudHSM `KeyStore`、専用 PKCS12 キーストアを提供します。このキーストアでは、証明書をキーデータとともに保存し、 AWS CloudHSMに保存されているキーデータに関連付けることができます。`KeyStore` クラスは、Java AWS CloudHSM Cryptography Extension (JCE) の`KeyStore`サービスプロバイダーインターフェイス (SPI) を実装します。`KeyStore` の使用の詳細については、「[Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore)」を参照してください。
**注記**
証明書は公開情報であり、暗号化キーのストレージ容量を最大化するため、 AWS CloudHSM は HSMs への証明書の保存をサポートしていません。
## AWS CloudHSM クライアント SDK 5 に適したキーストアを選択する
AWS CloudHSM Java Cryptographic Extension (JCE) プロバイダーは、専用 AWS CloudHSM KeyStore を提供しています。クラスは、HSM AWS CloudHSM `KeyStore`へのキーオペレーションのオフロード、証明書のローカルストレージ、および証明書ベースのオペレーションをサポートしています。
次のように、特殊目的の CloudHSM KeyStore をロードします。
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## AWS CloudHSM KeyStoreクライアント SDK 5 を初期化する
JCE プロバイダーにログインするのと同じ方法で、 AWS CloudHSM KeyStore にログインします。環境変数またはシステムプロパティファイルを使用できます。CloudHSM KeyStore を使用する前にログインする必要があります。JCE プロバイダーを使用して HSM にログインする例については、[Login to an HSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java) を参照してください。
必要に応じて、パスワードを指定して、キーストアデータを保持するローカル PKCS12 ファイルを暗号化できます。 AWS CloudHSM Keystore を作成するときは、パスワードを設定し、ロード、設定、取得の方法を使用するときに指定します。
新しい CloudHSM KeyStore オブジェクトを次のようにインスタンス化します。
```
ks.load(null, null);
```
`store` メソッドを使用して、キーストアデータをファイルに書き込みます。その後は、次のように、ソースファイルとパスワードを使用し、`load` メソッドを使用して既存のキーストアをロードできます。
```
ks.load(inputStream, password);
```
## Use AWS CloudHSM KeyStore または AWS CloudHSM クライアント SDK 5
AWS CloudHSM KeyStore は JCE [Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore) 仕様に準拠しており、以下の関数を提供します。
+ `load`
指定された入力ストリームからキーストアをロードします。キーストアの保存時にパスワードが設定されている場合、ロードを成功させるには、この同じパスワードを指定する必要があります。新しい空のキーストアを初期化するには、両方のパラメータを null に設定します。
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
ks.load(inputStream, password);
```
+ `aliases`
指定されたキーストアインスタンス内に含まれるすべてのエントリのエイリアス名の列挙を返します。結果には、PKCS12 ファイルにローカルに保存されたオブジェクトと、HSM 上に存在するオブジェクトが含まれます。
**サンプルコード:**
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
for(Enumeration entry = ks.aliases(); entry.hasMoreElements();) {
String label = entry.nextElement();
System.out.println(label);
}
```
+ `containsalias`
キーストアが、指定されたエイリアスを持つ少なくとも 1 つのオブジェクトにアクセスできる場合は true を返します。キーストアは、PKCS12 ファイルにローカルに保存されているオブジェクトと、HSM 上に存在するオブジェクトをチェックします。
+ `deleteEntry`
ローカル PKCS12 ファイルから証明書エントリを削除します。HSM に保存されているキーデータの削除は、 AWS CloudHSM KeyStore ではサポートされていません。[Destroyable](https://devdocs.io/openjdk~8/javax/security/auth/destroyable#destroy--) インターフェースの `destroy` メソッドを使用してキーを削除できます。
```
((Destroyable) key).destroy();
```
+ `getCertificate`
使用可能な場合、エイリアスに関連付けられた証明書を返します。エイリアスが存在しないか、証明書ではないオブジェクトを参照している場合、関数は NULL を返します。
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
Certificate cert = ks.getCertificate(alias);
```
+ `getCertificateAlias`
指定された証明書とデータが一致する最初のキーストアエントリの名前 (エイリアス) を返します。
```
KeyStore ks = KeyStore.getInstance("CloudHSM");
String alias = ks.getCertificateAlias(cert);
```
+ `getCertificateChain`
指定されたエイリアスに関連付けられた証明書チェーンを返します。エイリアスが存在しないか、証明書ではないオブジェクトを参照している場合、関数は NULL を返します。
+ `getCreationDate`
指定されたエイリアスによって識別されるエントリの作成日を返します。作成日が使用できない場合、この関数は証明書が有効になった日付を返します。
+ `getKey`
GetKey が HSM に渡され、指定されたラベルに対応するキーオブジェクトを返します。`getKey` が HSM を直接照会すると、KeyStore によって生成されたかどうかに関係なく、HSM 上の任意のキーに使用できます。
```
Key key = ks.getKey(keyLabel, null);
```
+ `isCertificateEntry`
指定されたエイリアスを持つエントリが証明書エントリを表すかどうかをチェックします。
+ `isKeyEntry`
指定されたエイリアスを持つエントリがキーエントリを表すかどうかをチェックします。このアクションは、PKCS12 ファイルと HSM の両方でエイリアスを検索します。
+ `setCertificateEntry`
指定された証明書を指定されたエイリアスに割り当てます。指定されたエイリアスがキーまたは証明書の識別にすでに使用されている場合は、`KeyStoreException` がスローされます。JCE コードを使用してキーオブジェクトを取得し、KeyStore `SetKeyEntry` メソッドを使用して証明書をキーに関連付けることができます。
+ `byte[]` キーのある `setKeyEntry`
**この API は現在、クライアント SDK 5 ではサポートされていません。**
+ `Key` オブジェクトのある `setKeyEntry`
指定されたキーを指定されたエイリアスに割り当て、HSM 内に保存します。キーが HSM 内にまだ存在しない場合は、抽出可能なセッションキーとして HSM にインポートされます。
`Key` オブジェクトが `PrivateKey` のタイプの場合、対応する証明書チェーンが添付されている必要があります。
エイリアスが既に存在する場合、`SetKeyEntry` 呼び出しは `KeyStoreException` をスローし、キーが上書きされるのを防ぎます。キーを上書きする必要がある場合は、そのために KMU または JCE を使用します。
+ `engineSize`
キーストア内のエントリの数を返します。
+ `store`
キーストアを指定された出力ストリームに PKCS12 ファイルとして保存し、指定されたパスワードで保護します。さらに、ロードされたすべてのキー (`setKey` 呼び出しを使用して設定される) が保持されます。
# AWS CloudHSM JCE for Client SDK 5 の詳細設定
AWS CloudHSM JCE プロバイダーには、ほとんどのお客様が使用する一般的な設定の一部ではない、以下の高度な設定が含まれています。
+ [複数のクラスターへの接続](java-lib-configs-multi.md)
+ [JCE を使用したキー抽出](java-lib-configs-getencoded.md)
+ [JCE の設定を再試行](java-lib-configs-retry.md)
# JCE プロバイダーを使用した複数の AWS CloudHSM クラスターへの接続
この構成では、1 つのクライアントインスタンスが複数の AWS CloudHSM クラスターと通信できます。1 つのインスタンスが 1 つのクラスターとしか通信しない場合と比較して、これは一部のユースケースではコスト削減機能となる可能性があります。`CloudHsmProvider` クラスは、Java セキュリティのプロバイダークラスの AWS CloudHSM実装です。 [https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html](https://docs.oracle.com/javase/8/docs/api/java/security/Provider.html)このクラスの各インスタンスは、 AWS CloudHSM クラスター全体への接続を表します。このクラスをインスタンス化して Java セキュリティプロバイダのリストに追加すると、標準 JCE クラスを使用して操作できるようになります。
次の例では、このクラスをインスタンス化して Java セキュリティプロバイダのリストに追加します。
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
`CloudHsmProvider` は 2 つの方法で設定できます。
1. ファイルによる設定 (デフォルト設定)
1. コードを使用して設定
以下のトピックでは、これらの設定と、複数のクラスターに接続する方法について説明します。
**Topics**
+ [ファイルによる AWS CloudHSM `CloudHsmProvider` クラスの設定 (デフォルト設定)](java-lib-configs-default.md)
+ [コードを使用して AWS CloudHSM `CloudHsmProvider` クラスを設定する](java-lib-configs-using-code.md)
+ [複数の AWS CloudHSM クラスターに接続する](java-lib-connecting-to-multiclusters.md)
# ファイルによる AWS CloudHSM `CloudHsmProvider` クラスの設定 (デフォルト設定)
クラスを設定するデフォルトの方法は、 AWS CloudHSM `CloudHsmProvider` ファイルを使用することです。
デフォルトのコンストラクタを使用して `CloudHsmProvider` をインスタンス化すると、デフォルトでは、Linux の `/opt/cloudhsm/etc/cloudhsm-jce.cfg` パスで構成ファイルが検索されます。この設定ファイルは、`configure-jce` を使用して設定できます。
デフォルトコンストラクターを使用して作成されたオブジェクトは、デフォルトの CloudHSM プロバイダー名 `CloudHSM` を使用します。プロバイダー名は JCE とやり取りして、さまざまなオペレーションにどのプロバイダーを使用するかを判断するのに役立ちます。Cipher オペレーションに CloudHSM プロバイダー名を使用する例は次のとおりです。
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHSM");
```
# コードを使用して AWS CloudHSM `CloudHsmProvider` クラスを設定する
クライアント SDK バージョン 5.8.0 以降では、Java コードを使用して クラスを設定 AWS CloudHSM `CloudHsmProvider`することもできます。そのための方法は、`CloudHsmProviderConfig` クラスのオブジェクトを使用することです。`CloudHsmProviderConfigBuilder` を使用してこのオブジェクトを構築することができます。
`CloudHsmProvider` には、次の例のように、`CloudHsmProviderConfig` オブジェクトを取得する別のコンストラクターがあります。
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider = new CloudHsmProvider(config);
```
この例では、JCE プロバイダーの名前は `CloudHsmCluster1` です。これは、アプリケーションが JCE とやり取りするために使用できる名前です。
**Example**
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "CloudHsmCluster1");
```
あるいは、アプリケーションは上記で作成したプロバイダーオブジェクトを使用して、そのプロバイダーをオペレーションに使用することを JCE に知らせることもできます。
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider);
```
`withClusterUniqueIdentifier` メソッドで一意の識別子が指定されていない場合は、ランダムに生成されたプロバイダー名が自動的に作成されます。このランダムに生成された識別子を取得するには、アプリケーションは `provider.getName()` を呼び出して識別子を取得できます。
# 複数の AWS CloudHSM クラスターに接続する
各 AWS CloudHSM は、クラスターへの接続`CloudHsmProvider`を表します。同じアプリケーションから別のクラスターと通信したい場合は、別のクラスターの設定を使用して `CloudHsmProvider` のオブジェクトをもう1つ作成し、次の例に示すように、プロバイダーオブジェクトまたはプロバイダー名を使用してこの他のクラスターとやり取りできます。
**Example**
```
CloudHsmProviderConfig config = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath)
.withClusterUniqueIdentifier("CloudHsmCluster1")
.withServer(CloudHsmServer.builder().withHostIP(hostName).build())
.build())
.build();
CloudHsmProvider provider1 = new CloudHsmProvider(config);
if (Security.getProvider(provider1.getName()) == null) {
Security.addProvider(provider1);
}
CloudHsmProviderConfig config2 = CloudHsmProviderConfig.builder()
.withCluster(
CloudHsmCluster.builder()
.withHsmCAFilePath(hsmCAFilePath2)
.withClusterUniqueIdentifier("CloudHsmCluster2")
.withServer(CloudHsmServer.builder().withHostIP(hostName2).build())
.build())
.build();
CloudHsmProvider provider2 = new CloudHsmProvider(config2);
if (Security.getProvider(provider2.getName()) == null) {
Security.addProvider(provider2);
}
```
上記の両方のプロバイダー (両方のクラスター) を設定したら、プロバイダーオブジェクトまたはプロバイダー名を使用してプロバイダーを操作できます。
`cluster1` と通信する方法を示すこの例を拡張すると、AES/GCM/NoPadding オペレーションに次のサンプルを使用できます。
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider1);
```
同じアプリケーションで、プロバイダー名を使用して 2 番目のクラスターで「AES」キー生成を行う場合は、次のサンプルを使用することもできます。
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# の JCE を使用したキー抽出 AWS CloudHSM
Java Cryptography Extension (JCE) は、さまざまな暗号化実装をプラグインできるアーキテクチャを使用します。 は、暗号化オペレーションを HSM にオフロードする 1 つの JCE プロバイダーを AWS CloudHSM 出荷します。他のほとんどの JCE プロバイダーが AWS CloudHSM に保存されているキーを操作するには、HSM のキーバイトをクリアテキストでマシンのメモリに抽出して使用する必要があります。HSM では通常、キーを ラップされたオブジェクト としてのみ抽出でき、クリアテキストとして抽出することはできません。ただし、プロバイダー間の統合のユースケースをサポートするために、 では、クリアでキーバイトの抽出を有効にするオプトイン設定オプション AWS CloudHSM を許可します。
**重要**
JCE は、AWS CloudHSM プロバイダーが指定されるか、 AWS CloudHSM キーオブジェクトが使用される AWS CloudHSM たびに、オペレーションを にオフロードします。HSM 内でオペレーションが行われることが予想される場合は、キーを明確に抽出する必要はありません。クリアテキストでのキー抽出が必要なのは、サードパーティのライブラリや JCE プロバイダーの制限により、アプリケーションがキーのラップやラップ解除などの安全なメカニズムを使用できない場合のみです。
AWS CloudHSM JCE プロバイダーは、デフォルトで外部 JCE プロバイダーと連携する**パブリックキー**の抽出を許可します。以下の方法は常に許可されています。
| Class | 方法 | Format (getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded () | X.509 |
| | getW() | 該当なし |
| RSAPublicKey | getEncoded () | X.509 |
| | getPublicExponent() | 該当なし |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | 該当なし |
AWS CloudHSM JCE プロバイダーは、デフォルトで**プライベート**キーまたは**シー**クレットキーに対してクリアなキーバイトの抽出を許可しません。ユースケースで必要な場合は、以下の条件で **プライベート** または **シークレット** キーのキーバイトを消去して抽出できます。
1. プライベートまたはシークレットキーの `EXTRACTABLE` 属性は「**true**」に設定されています。
+ デフォルトでは、プライベートキーとシークレットキーの `EXTRACTABLE` 属性は「**true**」に設定されています。`EXTRACTABLE` キーは HSM からのエクスポートが許可されているキーです。詳細については、「[クライアント SDK 5 向け](java-lib-attributes_5.md)サポートされている Java 属性」を参照してください。
1. プライベートキーとシークレットキーの `WRAP_WITH_TRUSTED` 属性は「**false**」に設定されます。
+ `getEncoded`、`getPrivateExponent`、`getS`およびクリアでエクスポートできないプライベートキーでは使用できません。`WRAP_WITH_TRUSTED` は、プライベートキーを HSM からクリアにエクスポートすることはできません。詳細については、「[信頼できるキーを使ったキーのアンラップの制御](manage-keys-using-trusted-keys.md)」を参照してください。
# JCE プロバイダーがプライベートキーシークレットを から抽出することを許可する AWS CloudHSM
次の手順を使用して、 AWS CloudHSM JCE プロバイダーがプライベートキーシークレットを抽出できるようにします。
**重要**
この設定変更により、HSM クラスターからすべてのクリアの `EXTRACTABLE` キーバイトを抽出できるようになります。セキュリティを高めるには、[キーラッピング方法](java-lib-supported_5.md)を使用して HSM から安全にキーを抽出することを検討してください。これにより、HSM からキーバイトが意図せず抽出されるのを防ぐことができます。
1. 以下のコマンドを使用して、**プライベート** キーと **シークレット** キーを JCE で抽出できるようにします。
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --enable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --enable-clear-key-extraction-in-software
```
------
1. クリアキー抽出を有効にすると、以下の方法でプライベートキーをメモリーに抽出できるようになります。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/get-encoded-take-out-private-keys.html)
JCE がキーをクリアでエクスポートできないようにして、デフォルトの動作に戻したい場合は、以下のコマンドを実行します。
------
#### [ Linux ]
```
$ /opt/cloudhsm/bin/configure-jce --disable-clear-key-extraction-in-software
```
------
#### [ Windows ]
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --disable-clear-key-extraction-in-software
```
------
# の JCE の再試行コマンド AWS CloudHSM
AWS CloudHSM クライアント SDK 5.8.0 以降には、HSM スロットリングされたオペレーションをクライアント側から再試行する自動再試行戦略が組み込まれています。HSM が以前のオペレーションが多すぎてそれ以上リクエストを受け付けられないためにオペレーションをスロットリングすると、Client SDK はスロットリングされたオペレーションを最大 3 回再試行しますが、その間、エクスポネンシャルバックオフします。この自動再試行戦略は、**オフ**と**スタンダード**の 2 つのモードのいずれかに設定できます。
+ **オフ**: クライアント SDK は、HSM によってスロットリングされたオペレーションに対しては再試行戦略を一切実行しません。
+ **スタンダード**: これはクライアント SDK 5.8.0 以降のデフォルトモードです。このモードでは、クライアント SDK はエクスポネンシャルバックオフすることで、スロットリングされた操作を自動的に再試行します。
詳細については、「[HSM スロットリング](troubleshoot-hsm-throttling.md)」を参照してください。
## 再試行コマンドをオフモードに設定する
------
#### [ Linux ]
**Linux でクライアント SDK 5 向けに再試行コマンドを **off** に設定するには**
+ 次のコマンドを使用して再試行設定を **off** モードに設定できます。
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**Windows 上の クライアント SDK 5 向けに再試行コマンドを **off** に設定するには**
+ 次のコマンドを使用して再試行設定を **off** モードに設定できます。
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------