翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# クライアント SDK 5 を使用して を操作する AWS CloudHSM
AWS CloudHSM には、2 つの主要なクライアント SDK バージョンが含まれています。
+ クライアント SDK 5: これは最新かつデフォルトの クライアント SDK です。クライアント SDK 5 による利点については、「[AWS CloudHSM クライアント SDK 5 の利点](client-sdk-5-benefits.md)」を参照してください。
+ クライアント SDK 3: これは古いクライアント SDK です。プラットフォームおよび言語ベースのアプリケーションの互換性および管理ツール用のコンポーネントの完全なセットが含まれています。
クライアント SDK 3 から クライアント SDK 5 に移行する手順については、「[AWS CloudHSM クライアント SDK 3 からクライアント SDK 5 への移行](client-sdk-migration.md)」を参照してください。
このトピックでは、クライアント SDK 5 について説明します。使用しているクライアント SDK のバージョンを確認するには、次を参照してください。
**Topics**
+ [AWS CloudHSM クライアント SDK 5 の利点](client-sdk-5-benefits.md)
+ [AWS CloudHSM クライアント SDK 5 でサポートされているプラットフォーム](client-supported-platforms.md)
+ [AWS CloudHSM クライアント SDK 5 用の PKCS \$111 ライブラリ](pkcs11-library.md)
+ [AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine](openssl-library.md)
+ [AWS CloudHSM クライアント SDK 5 の OpenSSL プロバイダー](openssl-provider-library.md)
+ [AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP)](ksp-library.md)
+ [AWS CloudHSM クライアント SDK 5 の JCE プロバイダー](java-library.md)
# AWS CloudHSM クライアント SDK 5 の利点
AWS CloudHSM Client SDK 3 と比較して、Client SDK 5 は管理が容易で、優れた設定可能性と信頼性を提供します。クライアント SDK 5 には、クライアント SDK 3 には他にも主要な利点がいくつかあります。
**サーバーレスアーキテクチャ向けの設計**
クライアント SDK 5 にはクライアントデーモンが必要ないため、バックグラウンドサービスを管理する必要がなくなりました。これは、ユーザーにとって次に挙げる重要なポイントで役立ちます。
+ アプリケーションの起動プロセスを簡素化します。CloudHSM を使い始めるために必要なことは、アプリケーションを実行する前に SDK を設定することだけです。
+ プロセスを常に実行する必要がないため、Lambda や Elastic Container Service (ECS) などのサーバーレスコンポーネントとの統合が容易になります。
**サードパーティとの統合が強化され、ポータビリティが容易に**
クライアント SDK 5 は JCE 仕様に厳密に準拠しており、異なる JCE プロバイダー間のポータビリティが容易で、サードパーティとの統合も良好です。
**ユーザーエクスペリエンスと設定可能性が向上**
クライアント SDK 5 では、ログメッセージの読みやすさが向上し、例外やエラー処理メカニズムが明確になり、ユーザーによるセルフサービスのトリアージがはるかに簡単になりました。SDK 5 にはさまざまな設定も用意されており、[設定ツールページ](https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sdk-5.html)に一覧表示されています。
**より広範なプラットフォームサポート**
クライアント SDK 5 は、最新のオペレーティングプラットフォームにより幅広いサポートを提供しています。これには、ARM テクノロジーのサポートのほか、[JCE](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-library_5.html)、[PKCS \$111](https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library.html)、および [OpenSSL](https://docs.aws.amazon.com/cloudhsm/latest/userguide/openssl-library.html) のサポートの強化が含まれます。詳細については、「[Supported platforms](client-supported-platforms.md)」を参照してください。
**IPv6 接続のサポート**
クライアント SDK 5.14 以降では、IPv6 を使用したデュアルスタック HSM への接続がサポートされています。
**その他の機能やメカニズム**
クライアント SDK 5 には、クライアント SDK 3 にはない機能やメカニズムが追加されており、クライアント SDK 5 には今後もメカニズムが追加されていく予定です。
# AWS CloudHSM クライアント SDK 5 でサポートされているプラットフォーム
基本サポートは、 AWS CloudHSM クライアント SDK のバージョンごとに異なります。SDK 内のコンポーネントのプラットフォームのサポートは通常、基本サポートと一致しますが、必ずしもそうとは限りません。特定のコンポーネントのプラットフォームのサポートを確認するには、まず目的のプラットフォームが SDK のベースセクションに表示されていることを確認し、コンポーネントセクションで除外項目やその他の関連情報がないか確認します。
AWS CloudHSM は 64 ビットオペレーティングシステムのみをサポートします。
プラットフォームのサポートは時間の経過とともに変化します。以前のバージョンの CloudHSM クライアント SDK では、ここに記載されているすべてのオペレーティングシステムがサポートされていない場合があります。リリースノートを使用して、以前のバージョンの CloudHSM クライアント SDK に対するオペレーティングシステムサポートを確認します。詳細については、「[AWS CloudHSM クライアント SDK のダウンロード](client-history.md)」を参照してください。
以前の クライアント SDK でサポートされるプラットフォームについては、「[AWS CloudHSM クライアント SDK 3 でサポートされているプラットフォーム](sdk3-support.md)」を参照してください。
クライアント SDK 5 にはクライアントデーモンは必要ありません。
**Topics**
+ [クライアント SDK 5 の Linux サポート](sdk8-linux.md)
+ [クライアント SDK 5 の Windows サポート](sdk8-windows.md)
+ [クライアント SDK 5 のサーバーレスサポート](sdk8-serverless.md)
+ [クライアント SDK 5 の HSM 互換性](sdk5-hsm-types.md)
# AWS CloudHSM クライアント SDK 5 の Linux サポート
AWS CloudHSM クライアント SDK 5 では、次の Linux オペレーティングシステムとプラットフォームがサポートされています。
| サポートされているプラットフォーム | x86\$164 アーキテクチャ | ARM アーキテクチャ |
| --- | --- | --- |
| Amazon Linux 2 | はい | はい |
| Amazon Linux 2023 | はい | はい |
| Red Hat Enterprise Linux 8 (8.3 以降) | はい | はい |
| Red Hat Enterprise Linux 9 (9.2 以降) | はい | はい |
| Red Hat Enterprise Linux 10 (10.0 以降) | はい | はい |
| Ubuntu 22.04 LTS | はい | はい |
| Ubuntu 24.04 LTS | はい | はい |
+ SDK 5.16 は、Ubuntu 20.04 LTS プラットフォームをサポートする最後のリリースでした。詳細については、「[Ubuntu のウェブサイト](https://ubuntu.com/blog/ubuntu-20-04-lts-end-of-life-standard-support-is-coming-to-an-end-heres-how-to-prepare)」を参照してください。
+ SDK 5.12 は、CentOS 7 (7.8 以降) プラットフォームをサポートする最後のリリースでした。詳細については、「[CentOS のウェブサイト](https://blog.centos.org/2023/04/end-dates-are-coming-for-centos-stream-8-and-centos-linux-7/)」を参照してください。
+ SDK 5.12 は、Red Hat Enterprise Linux 7 (7.8 以降) プラットフォームをサポートする最後のリリースでした。詳細については、[Red Hat のウェブサイト](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/rhel-7-end-of-maintenance)を参照してください。
+ SDK 5.4.2 は、CentOS 8 プラットフォームをサポートする最後のリリースでした。詳細については、「[CentOS のウェブサイト](https://www.centos.org/centos-linux-eol/)」を参照してください。
# AWS CloudHSM クライアント SDK 5 の Windows サポート
AWS CloudHSM クライアント SDK 5 では、次のバージョンの Windows Server がサポートされています。
+ Microsoft Windows Server 2016
+ Microsoft Windows Server 2019
+ Microsoft Windows Server 2022
+ Microsoft Windows Server 2025
# AWS CloudHSM クライアント SDK 5 のサーバーレスサポート
AWS CloudHSM クライアント SDK 5 は、次の AWS サーバーレスサービスをサポートしています。
+ AWS Lambda
+ Docker および ECS
# AWS CloudHSM クライアント SDK 5 の HSM 互換性
次の表に、HSMs の AWS CloudHSM クライアント SDK 5 の互換性を示します。
| hsm1.medium | hsm2m.medium |
| --- | --- |
| クライアント SDK バージョン 5.0.0 以降と互換性があります。 | Client SDK バージョン 5.9.0 以降と互換性があります。 |
# AWS CloudHSM クライアント SDK 5 用の PKCS \$111 ライブラリ
PKCS \$111 は、ハードウェアセキュリティモジュール (HSM) で暗号化オペレーションを実行するための標準です。 AWS CloudHSM は、PKCS \$111 バージョン 2.40 に準拠した PKCS \$111 ライブラリの実装を提供します。
ブートストラップの詳細については、「[クラスターへの接続](cluster-connect.md)」を参照してください。トラブルシューティングについては、「[の PKCS \$111 ライブラリの既知の問題 AWS CloudHSMPKCS\$111 ライブラリの既知の問題](ki-pkcs11-sdk.md)」を参照してください。
クライアント SDK 3 の使用の詳細については、「[以前の SDK バージョンを使用して を操作する AWS CloudHSM](choose-client-sdk.md)」を参照してください。
**Topics**
+ [PKCS \$111 ライブラリのインストール](pkcs11-library-install.md)
+ [PKCS \$111 ライブラリの認証](pkcs11-pin.md)
+ [キータイプ](pkcs11-key-types.md)
+ [メカニズム](pkcs11-mechanisms.md)
+ [API オペレーション](pkcs11-apis.md)
+ [キー属性](pkcs11-attributes.md)
+ [コードサンプル](pkcs11-samples.md)
+ [詳細設定](pkcs11-library-configs.md)
+ [証明書ストレージ](pkcs11-certificate-storage.md)
# AWS CloudHSM クライアント SDK 5 用の PKCS \$111 ライブラリをインストールする
このトピックでは、 AWS CloudHSM クライアント SDK 5 バージョンシリーズの最新バージョンの PKCS \$111 ライブラリをインストールする方法について説明します。クライアント SDK または PKCS \$111 ライブラリの詳細については、[[クライアント SDK の使用](use-hsm.md)] と [[PKCS \$111 ライブラリ](pkcs11-library.md)] を参照してください。
クライアント SDK 5 では、クライアントデーモンをインストールまたは実行する必要はありません。
クライアント SDK 5 で単一の HSM クラスターを実行するには、まず `disable_key_availability_check` を `True` に設定してクライアントキーの耐久性の設定を管理する必要があります。詳細については、[キーの同期](manage-key-sync.md) と [クライアント SDK 5 設定ツール](configure-sdk-5.md) を参照してください。
クライアント SDK 5 の PKCS \$111 ライブラリの詳細については、[[PKCS \$111 ライブラリ](pkcs11-library.md)] を参照してください。
**注記**
クライアント SDK 5 で単一の HSM クラスターを実行するには、まず `disable_key_availability_check` を `True` に設定してクライアントキーの耐久性の設定を管理する必要があります。詳細については、[キーの同期](manage-key-sync.md) と [クライアント SDK 5 設定ツール](configure-sdk-5.md) を参照してください。
**PKCS \$111 ライブラリをインストールおよび設定するには**
1. 次のコマンドを使用して、PKCS \$111 ライブラリのダウンロードとインストールを行います。
------
#### [ Amazon Linux 2023 ]
X86\$164 アーキテクチャ上で Amazon Linux 2023 用の PKCS \$111 ライブラリをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.x86_64.rpm
```
ARM64 アーキテクチャ上で Amazon Linux 2023 用の PKCS \$111 ライブラリをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
X86\$164 アーキテクチャ上で Amazon Linux 2 用の PKCS \$111 ライブラリをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.x86_64.rpm
```
ARM64 アーキテクチャ上で Amazon Linux 2 用の PKCS \$111 ライブラリをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el7.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
RHEL 10 用の PKCS \$111 ライブラリを X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.x86_64.rpm
```
RHEL 10 用の PKCS \$111 ライブラリを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el10.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
RHEL 9 用の PKCS \$111 ライブラリーを X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.x86_64.rpm
```
RHEL 9 用の PKCS \$111 ライブラリーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
RHEL 8 用の PKCS \$111 ライブラリーを X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.x86_64.rpm
```
RHEL 8 用の PKCS \$111 ライブラリを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-pkcs11-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
Ubuntu 24.04 LTS 用の PKCS \$111 ライブラリを X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_amd64.deb
```
Ubuntu 24.04 LTS 用の PKCS \$111 ライブラリを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Ubuntu 22.04 LTS 用の PKCS \$111 ライブラリを X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_amd64.deb
```
Ubuntu 22.04 LTS 用の PKCS \$111 ライブラリを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-pkcs11_latest_u22.04_arm64.deb
```
------
#### [ Windows Server ]
Windows Server 用の PKCS \$111 ライブラリを X86\$164 アーキテクチャにインストールします。
1. [[クライアント SDK 5 用の PKCS \$111 ライブラリ](https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMPKCS11-latest.msi)] をダウンロードします。
1. Windows の管理権限を持つ PKCS \$111 ライブラリインストーラ (**AWSCloudHSMPKCS11-latest.msi**) を実行します。
------
1. 構成ツールを使用して、証明書の発行場所を指定します。手順については、「[発行証明書の場所を指定する](cluster-connect.md#specify-cert-location)」を参照してください。
1. クラスターに接続して使用するには、「[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to)」を参照してください。
1. PKCS \$111 ライブラリのファイルは、次の場所にあります。
+ Linuxのバイナリ、設定スクリプト、およびログファイル:
```
/opt/cloudhsm
```
Windows のバイナリ:
```
C:\Program Files\Amazon\CloudHSM
```
Windows の設定スクリプトとログファイル:
```
C:\ProgramData\Amazon\CloudHSM
```
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリへの認証
PKCS \$111 ライブラリを使用すると、アプリケーションは AWS CloudHSMで特定の [Crypto User (CU)](manage-hsm-users.md) として実行されます。アプリケーションは、CU が所有して共有するキーのみを表示および管理できます。既存の CU を HSM で使用することも、アプリケーションに新しい CU を作成することもできます。CU の管理については、「[CloudHSM CLI による HSM ユーザーの管理](manage-hsm-users-chsm-cli.md)」および「[CloudHSM 管理ユーティリティ (CMU) による HSM ユーザーの管理](manage-hsm-users-cmu.md)」を参照してください
PKCS \$111 に CU を指定するには、PKCS \$111 [[C\$1Login 関数](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc385057915)] のピンパラメーターを使用します。の場合 AWS CloudHSM、ピンパラメータの形式は次のとおりです。
```
:
```
たとえば、次のコマンドでユーザー名 `CryptoUser` とパスワード `CUPassword123!` を使用して PKCS \$111 ライブラリのピンを CU に設定します。
```
CryptoUser:CUPassword123!
```
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリでサポートされているキータイプ
AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリは、次のキータイプをサポートしています。
****
| キータイプ | 説明 |
| --- | --- |
| AES | 128、192、256 ビットの AES キーを生成します。 |
| Triple DES (3DES、DESede) | 192 ビットのトリプル DES キーを生成します。今後の変更については、以下の注記「[1](#key-types-1)」を参照してください。 |
| EC | secp224r1 (P-224)、secp256r1 (P-256)、secp256k1 (ブロックチェーン)、secp384r1 (P-384)、secp521r1 (P-521) のカーブを使用してキーを生成します。 |
| [GENERIC\$1SECRET] | 1～800 バイトの汎用シークレットを生成します。 |
| 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 の PKCS \$111 ライブラリでサポートされているメカニズム
PKCS \$111 ライブラリは PKCS \$111 仕様のバージョン 2.40 に準拠しています。PKCS\$111 を使用して暗号化機能を呼び出すには、指定されたメカニズムで関数を呼び出します。以下のセクションでは、 AWS CloudHSM クライアント SDK 5 でサポートされている関数とメカニズムの組み合わせをまとめます。
PKCS \$111 ライブラリは、次のアルゴリズムをサポートしています。
+ [**暗号化と復号化**] AES-CBC、AES-CTR、AES-ECB、AES-GCM、DES3-CBC、DES3-ECB、RSA-OAEP、RSA-PKCS
+ [**署名と確認**] RSA、HMAC、ECDSA (ハッシュあり、なし)
+ [**ハッシュ/ダイジェスト**] SHA1、SHA224、SHA256、SHA384、SHA512
+ [**キーラップ**] AES キーラップ、[[1](#mech1)] AES-GCM、RSA-AES、RSA-OAEP
+ **キー導出** — SP800-108 Counter KDF、および KDF 付き ECDH (サポートされている KDF アルゴリズムは、X9.63 with SHA1、SHA224、SHA256、SHA384、SHA512 です)
**Topics**
+ [キーとキーペアの関数を生成する](#pkcs11-mech-function-genkey)
+ [署名および検証](#pkcs11-mech-function-signverify)
+ [リカバリ機能への署名、リカバリ、検証](#pkcs11-mech-function-sr-vr)
+ [ダイジェスト関数](#pkcs11-mech-function-digest)
+ [暗号化と復号](#pkcs11-mech-function-enc-dec)
+ [キー機能の導出](#pkcs11-mech-function-derive-key)
+ [ラップ関数とアンラップ関数](#pkcs11-mech-function-wrap-unwrap)
+ [各メカニズムの最大データサイズ](#pkcs11-mech-max)
+ [メカニズムの注釈](#pkcs11-mech-annotations)
## キーとキーペアの関数を生成する
PKCS \$111 ライブラリ用の AWS CloudHSM ソフトウェアライブラリを使用すると、キーとキーペアの生成関数に次のメカニズムを使用できます。
+ `CKM_RSA_PKCS_KEY_PAIR_GEN`
+ `CKM_RSA_X9_31_KEY_PAIR_GEN` – このメカニズムは機能的には `CKM_RSA_PKCS_KEY_PAIR_GEN` メカニズムと似ていますが、`p` と `q` の生成に関してより強力な保証を提供します。
+ `CKM_EC_KEY_PAIR_GEN`
+ `CKM_GENERIC_SECRET_KEY_GEN`
+ `CKM_AES_KEY_GEN`
+ `CKM_DES3_KEY_GEN`— 今後の変更は脚注 [5](#mech5) に記載されています。
## 署名および検証
PKCS \$111 ライブラリ用の AWS CloudHSM ソフトウェアライブラリを使用すると、署名および検証関数に次のメカニズムを使用できます。クライアント SDK 5 では、データはソフトウェアでローカルにハッシュされます。つまり、SDK でハッシュできるデータのサイズに制限はありません。
クライアント SDK 5 では、RSA と ECDSA のハッシュはローカルで行われるため、データ制限はありません。HMAC にはデータ制限があります。詳細については、脚注 [2](#mech2) を参照してください。
**RSA**
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS` – シングルパートのオペレーションのみ。
+ `CKM_RSA_PKCS_PSS` – シングルパートのオペレーションのみ。
+ `CKM_SHA1_RSA_PKCS`
+ `CKM_SHA224_RSA_PKCS`
+ `CKM_SHA256_RSA_PKCS`
+ `CKM_SHA384_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA512_RSA_PKCS`
+ `CKM_SHA1_RSA_PKCS_PSS`
+ `CKM_SHA224_RSA_PKCS_PSS`
+ `CKM_SHA256_RSA_PKCS_PSS`
+ `CKM_SHA384_RSA_PKCS_PSS`
+ `CKM_SHA512_RSA_PKCS_PSS`
**ECDSA**
+ `CKM_ECDSA` – シングルパートのオペレーションのみ。
+ `CKM_ECDSA_SHA1`
+ `CKM_ECDSA_SHA224`
+ `CKM_ECDSA_SHA256`
+ `CKM_ECDSA_SHA384`
+ `CKM_ECDSA_SHA512`
**HMAC**
+ `CKM_SHA_1_HMAC`[2](#mech2)
+ `CKM_SHA224_HMAC`[2](#mech2)
+ `CKM_SHA256_HMAC`[2](#mech2)
+ `CKM_SHA384_HMAC`[2](#mech2)
+ `CKM_SHA512_HMAC`[2](#mech2)
**CMAC**
+ `CKM_AES_CMAC`
## リカバリ機能への署名、リカバリ、検証
クライアント SDK 5 は、署名と復号機能をサポートしていません。
## ダイジェスト関数
PKCS \$111 ライブラリ用の AWS CloudHSM ソフトウェアライブラリを使用すると、ダイジェスト関数に次のメカニズムを使用できます。クライアント SDK 5 では、データはソフトウェアでローカルにハッシュされます。つまり、SDK でハッシュできるデータのサイズに制限はありません。
+ `CKM_SHA_1`
+ `CKM_SHA224`
+ `CKM_SHA256`
+ `CKM_SHA384`
+ `CKM_SHA512`
## 暗号化と復号
PKCS \$111 ライブラリ用の AWS CloudHSM ソフトウェアライブラリを使用すると、暗号化および復号関数に次のメカニズムを使用できます。
+ `CKM_RSA_X_509`
+ `CKM_RSA_PKCS` – シングルパートのオペレーションのみ。今後の変更は脚注 [5](#mech5) に記載されています。
+ `CKM_RSA_PKCS_OAEP` – シングルパートのオペレーションのみ。
+ `CKM_AES_ECB`
+ `CKM_AES_CTR`
+ `CKM_AES_CBC`
+ `CKM_AES_CBC_PAD`
+ `CKM_DES3_CBC`— 今後の変更は脚注 [5](#mech5) に記載されています。
+ `CKM_DES3_ECB`— 今後の変更は脚注 [5](#mech5) に記載されています。
+ `CKM_DES3_CBC_PAD`— 今後の変更は脚注 [5](#mech5) に記載されています。
+ `CKM_AES_GCM` [1](#mech1), [2](#mech2)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
## キー機能の導出
PKCS \$111 ライブラリ用の AWS CloudHSM ソフトウェアライブラリは、次のキー取得メカニズムをサポートしています。
+ `CKM_SP800_108_COUNTER_KDF`
+ `CKM_ECDH1_DERIVE` - 次のベンダー定義の KDF タイプを使用した ECDH キー導出をサポートします[6](#kdf6)。
+ `CKD_CLOUDHSM_X963_SHA1_KDF` - X9.63 KDF with SHA1[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA224_KDF` - X9.63 KDF with SHA224[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA256_KDF` - X9.63 KDF with SHA256[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA384_KDF` - X9.63 KDF with SHA384[7](#kdf7)
+ `CKD_CLOUDHSM_X963_SHA512_KDF` - X9.63 KDF with SHA512[7](#kdf7)
## ラップ関数とアンラップ関数
PKCS \$111 ライブラリ用の AWS CloudHSM ソフトウェアライブラリを使用すると、ラップ関数とラップ解除関数に次のメカニズムを使用できます。
AES キーラップに関する追加情報については、[[AES キーラップ](manage-aes-key-wrapping.md)] を参照してください。
+ `CKM_RSA_PKCS` – シングルパートのオペレーションのみ。今後の変更は、脚注 [5](#mech5) に記載されています。
+ `CKM_RSA_PKCS_OAEP`[4](#mech4)
+ `CKM_AES_GCM`[1](#mech1), [3](#mech3)
+ `CKM_CLOUDHSM_AES_GCM`[3](#mech3)
+ `CKM_RSA_AES_KEY_WRAP`
+ `CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`[3](#mech3)
+ `CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`[3](#mech3)
## 各メカニズムの最大データサイズ
次の表は、各メカニズムに設定されている最大データサイズを示します:
**最大データセットサイズ**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-mechanisms.html)
## メカニズムの注釈
+ [1] AES-GCM の暗号化を実行している際、HSM はアプリケーションからの初期化ベクトル (IV) データを受け入れません。HSM が生成した IV を使用する必要があります。HSM で生成された 12 バイトの IV は、指定した `CK_GCM_PARAMS` パラメータ構造の pIV 要素が指すメモリ参照に書き込まれます。ユーザーが混乱しないよう、バージョン 1.1.1 以降の PKCS\$111 SDK では、AES-GCM 暗号化が初期化されると、pIV はゼロ化されたバッファを指し示すようになっています。
+ [2] 以下の仕組みでデータをオペレーションする場合、データバッファが最大データサイズを超えるとオペレーションがエラーとなります。これらのメカニズムでは、すべてのデータ処理が HSM 内で行われる必要があります。各メカニズムの最大データサイズセットについては、「[各メカニズムの最大データサイズ](#pkcs11-mech-max)」を参照してください。
+ [3] ベンダー定義のメカニズム。CloudHSM ベンダー定義のメカニズムを使用するには、コンパイル時に PKCS \$111 アプリケーションに `/opt/cloudhsm/include/pkcs11/pkcs11t.h` を含める必要があります。
`CKM_CLOUDHSM_AES_GCM`: この独自のメカニズムは、標準 `CKM_AES_GCM` よりもプログラム的に安全な代替手段です。これは、HSM によって生成された IV を、暗号の初期化中に提供される `CK_GCM_PARAMS` 構造体に書き戻すのではなく、暗号文の先頭に付加します。このメカニズムは `C_Encrypt`、`C_WrapKey`、`C_Decrypt`、`C_UnwrapKey` 関数で使用できます。このメカニズムを使用する場合は、`CK_GCM_PARAMS` 構造体内の pIV 変数を `NULL` に設定する必要があります。このメカニズムを `C_Decrypt` および `C_UnwrapKey` と共に使用する場合、IV は、ラップ解除される暗号文の前に付加されることが想定されます。
`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`: PKCS \$15 パディングを使用する AES キーラップ。
`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`: ゼロパディングを使用する AES キーラップ。
+ [4] 次の `CK_MECHANISM_TYPE` および `CK_RSA_PKCS_MGF_TYPE` は、`CK_RSA_PKCS_OAEP_PARAMS` の `CKM_RSA_PKCS_OAEP` としてサポートされています:
+ `CKG_MGF1_SHA1` を使用する `CKM_SHA_1`
+ `CKG_MGF1_SHA224` を使用する `CKM_SHA224`
+ `CKG_MGF1_SHA256` を使用する `CKM_SHA256`
+ `CKM_MGF1_SHA384` を使用する `CKM_SHA384`
+ `CKM_MGF1_SHA512` を使用する `CKM_SHA512`
+ [5] NIST ガイダンスに従い、2023 年以降の FIPS モードのクラスターでは、これは許可されません。FIPS 以外のモードのクラスターでは、2023 年以降も許可されます。詳細については、「[FIPS 140 コンプライアンス: 2024 年 メカニズムの非推奨](compliance-dep-notif.md#compliance-dep-notif-1)」を参照してください。
+ [6] ベンダー定義タイプ。CloudHSM ベンダー定義タイプを使用するには、コンパイル時に PKCS \$111 アプリケーションに `cloudhsm_pkcs11_vendor_defs.h` を含める必要があります。これは、Linux ベースのプラットフォームでは `/opt/cloudhsm/include/pkcs11/cloudhsm_pkcs11_vendor_defs.h` に、Windows ベースのプラットフォームでは `C:\Program Files\Amazon\CloudHSM\include\pkcs11\cloudhsm_pkcs11_vendor_defs.h` にあります。
+ [7] キー取得関数 (KDFs) は [NIST Special Publication 800-56A Revision 3 ](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar3.pdf)で指定されています。
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリでサポートされている API オペレーション
PKCS \$111 ライブラリは、 AWS CloudHSM クライアント SDK 5 の次の PKCS \$111 API オペレーションをサポートしています。
+ `C_CloseAllSessions`
+ `C_CloseSession`
+ `C_CreateObject`
+ `C_Decrypt`
+ `C_DecryptFinal`
+ `C_DecryptInit`
+ `C_DecryptUpdate`
+ `C_DeriveKey`
+ `C_DestroyObject`
+ `C_Digest`
+ `C_DigestFinal`
+ `C_DigestInit`
+ `C_DigestUpdate`
+ `C_Encrypt`
+ `C_EncryptFinal`
+ `C_EncryptInit`
+ `C_EncryptUpdate`
+ `C_Finalize`
+ `C_FindObjects`
+ `C_FindObjectsFinal`
+ `C_FindObjectsInit`
+ `C_GenerateKey`
+ `C_GenerateKeyPair`
+ `C_GenerateRandom`
+ `C_GetAttributeValue`
+ `C_GetFunctionList`
+ `C_GetInfo`
+ `C_GetMechanismInfo`
+ `C_GetMechanismList`
+ `C_GetSessionInfo`
+ `C_GetSlotInfo`
+ `C_GetSlotList`
+ `C_GetTokenInfo`
+ `C_Initialize`
+ `C_Login`
+ `C_Logout`
+ `C_OpenSession`
+ `C_Sign`
+ `C_SignFinal`
+ `C_SignInit`
+ `C_SignUpdate`
+ `C_UnWrapKey`
+ `C_Verify`
+ `C_VerifyFinal`
+ `C_VerifyInit`
+ `C_VerifyUpdate`
+ `C_WrapKey`
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリの主な属性
AWS CloudHSM キーオブジェクトは、パブリックキー、プライベートキー、シークレットキーのいずれかです。キーオブジェクトで許可されているアクションは属性で指定されます。属性は、キーオブジェクトの作成時に定義されます。PKCS \$111 ライブラリを に使用すると AWS CloudHSM、PKCS \$111 標準で指定されたデフォルト値が割り当てられます。
AWS CloudHSM は、PKCS \$111 仕様に記載されているすべての属性をサポートしているわけではありません。サポートするすべての属性の仕様に準拠しています。これらの属性は、それぞれのテーブルにリストされています。
オブジェクトを作成、変更、またはコピーする `C_CreateObject`、`C_GenerateKey`、`C_GenerateKeyPair`、`C_UnwrapKey`、`C_DeriveKey` などの暗号化関数は、属性テンプレートをパラメータの 1 つとして使用します。オブジェクトの作成中に属性テンプレートを渡す方法の詳細については、「[PKCS \$111 ライブラリを使用したキーの生成](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate)」のサンプルを参照してください。
以下のトピックでは、 AWS CloudHSM キー属性について詳しく説明します。
**Topics**
+ [属性テーブル](pkcs11-attributes-interpreting.md)
+ [属性の変更](modify-attr.md)
+ [エラーコードの解釈](attr-errors.md)
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリ属性テーブル
の PKCS \$111 ライブラリテーブルには、キータイプによって異なる属性のリスト AWS CloudHSM が含まれています。特定の暗号化関数を で使用するときに、特定のキータイプで特定の属性がサポートされるかどうかを示します AWS CloudHSM。
**凡例:**
+ ✔ CloudHSM が特定のキータイプの属性をサポートしていることを示します。
+ ✖ CloudHSM が特定のキータイプの属性をサポートしていないこと示します。
+ R は、属性値が特定のキータイプに対して読み取り専用に設定されていることを示します。
+ S は、属性が機密であるため、`GetAttributeValue` で読み取れないことを示します。
+ [Default Value] 列のセルが空の場合は、属性に割り当てられている特定のデフォルト値がないことを示します。
## GenerateKeyPair
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GenerateKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## CreateObject
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## UnwrapKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## DeriveKey
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
## GetAttributeValue
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/pkcs11-attributes-interpreting.html)
**属性注釈**
+ [1] この属性はファームウェアによって部分的にサポートされており、デフォルト値にのみ明示的に設定する必要があります。
+ [2] 必須属性。
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリ属性の変更
AWS CloudHSM オブジェクトの PKCS \$111 ライブラリ属性の中には、オブジェクトの作成後に変更できるものもあれば、できないものもあります。属性を修正するには、CloudHSM CLI の [key set-attribute](cloudhsm_cli-key-set-attribute.md) コマンドを使用します。CloudHSM CLI の [key list](cloudhsm_cli-key-list.md) コマンドを使用して属性のリストを導出することもできます。
次のリストで、オブジェクトの作成後に変更が許可荒れている許可されている属性が表示されます。
+ `CKA_LABEL`
+ `CKA_TOKEN`
**注記**
変更が許可されるには、セッションキーをトークンキーに変更する場合のみです。CloudHSM CLI の [key set-attribute](cloudhsm_cli-key-set-attribute.md) コマンドを使用して属性値を変更します。
+ `CKA_ENCRYPT`
+ `CKA_DECRYPT`
+ `CKA_SIGN`
+ `CKA_VERIFY`
+ `CKA_WRAP`
+ `CKA_UNWRAP`
+ `CKA_LABEL`
+ `CKA_SENSITIVE`
+ `CKA_DERIVE`
**注記**
この属性ではキー取得がサポートされています。すべてのパブリックキーで `False` を指定する必要があります。`True` に設定することはできません。シークレットキーまたは EC プライベートキーに対しては、`True` または `False` に設定できます。
+ `CKA_TRUSTED`
**注記**
この属性は Crypto Officer (CO) のみによって `True` または `False` に設定できます。
+ `CKA_WRAP_WITH_TRUSTED`
**注記**
この属性をエクスポート可能なデータキーに適用して、このキーを `CKA_TRUSTED` としてマークされたキーでのみラップできるように指定します。1度 `CKA_WRAP_WITH_TRUSTED` を true に設定すると属性は読み取り専用になり、属性を変更または削除することはできません。
# AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリエラーコードの解釈
特定のキーでサポートされていない PKCS \$111 ライブラリ属性をテンプレートで指定すると、エラーが発生します。次の表には、仕様に違反した場合に生成されるエラーコードが含まれています。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/attr-errors.html)
# AWS CloudHSM クライアント SDK 5 用の PKCS \$111 ライブラリのコードサンプル
GitHub のコードサンプルは、 AWS CloudHSM クライアント SDK 5 の PKCS \$111 ライブラリを使用して基本的なタスクを実行する方法を示しています。
## 前提条件
サンプルを実行する前に、以下のステップを実行して環境をセットアップします。
+ クライアント SDK 5 用の [PKCS \$111 ライブラリ](pkcs11-library-install.md) のインストールと設定をします。
+ [暗号化ユーザー (CU)](manage-hsm-users.md) の設定をします。アプリケーションは、この HSM アカウントを使用して HSM でコードサンプルを実行します。
## コードサンプル
PKCS\$111 用 AWS CloudHSM ソフトウェアライブラリのコードサンプルは、[GitHub](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples) で入手できます。このリポジトリには、暗号化、復号化、署名、検証など、PKCS \$111 を使用して一般的な操作を行う方法の例が含まれています。
+ [キーの生成 (AES、RSA、EC)](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/generate)
+ [キー属性のリスト化](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/attributes/)
+ [AES GCM を使用したデータの暗号化および復号](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/encrypt/aes_gcm.c)
+ [AES\$1CTR を使用したデータの暗号化および復号](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/aes_ctr.c)
+ [3DES を使用したデータの暗号化および復号](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/encrypt/des_ecb.c)
+ [RSAを使用したデータの署名と検証](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/sign/rsa_sign.c)
+ [HMAC KDFを使用したキーの取得](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/derivation/hmac_kdf.c)
+ [PKCS \$15 パディングありの AES を使用したキーのラップとラップ解除](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_wrapping.c)
+ [パディングなしの AES を使用したキーのラップとラップ解除](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_no_padding_wrapping.c)
+ [ゼロパディングありの AES を使用したキーのラップとラップ解除](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_zero_padding_wrapping.c)
+ [AES-GCM を使用したキーのラップとラップ解除](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/tree/master/src/wrapping/aes_gcm_wrapping.c)
+ [RSA を使用したキーのラップとラップ解除](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/rsa_wrapping.c)
# の PKCS \$111 ライブラリの詳細設定 AWS CloudHSM
AWS CloudHSM PKCS \$111 プロバイダーには、ほとんどのお客様が使用する一般的な設定の一部ではない、次の高度な設定が含まれています。これらの設定には追加機能があります。
+ [PKCS \$111 による複数のスロットへの接続](pkcs11-library-configs-multi-slot.md)
+ [PKCS \$111 の設定を再試行します](pkcs11-library-configs-retry.md)
# 用の PKCS \$111 ライブラリを使用した複数のスロット設定 AWS CloudHSM
クライアント SDK 5 PKCS \$111 ライブラリ内の 1 つのスロットは、 AWS CloudHSM内のクラスターへの 1 つの接続を表します。クライアント SDK 5 では、1 つの PKCS \$111 アプリケーションから複数のスロットでユーザーを複数の CloudHSM クラスターに接続できるように PKCS11 ライブラリを設定できます。
このトピックで説明されている手順に従って、アプリケーションがマルチスロット機能を使用して複数のクラスターに接続するようにします。
**Topics**
+ [の PKCS \$111 ライブラリのマルチスロット前提条件 AWS CloudHSM](#pkcs11-multi-slot-prereqs)
+ [のマルチスロット機能用に PKCS \$111 ライブラリを設定する AWS CloudHSM](pkcs11-multi-slot-config-run.md)
+ [のマルチスロット機能を持つクラスターを追加する AWS CloudHSM](pkcs11-multi-slot-add-cluster.md)
+ [のマルチスロット機能を持つクラスターを削除する AWS CloudHSM](pkcs11-multi-slot-remove-cluster.md)
## の PKCS \$111 ライブラリのマルチスロット前提条件 AWS CloudHSM
PKCS \$111 ライブラリの複数のスロットに を設定する前に AWS CloudHSM、次の前提条件を完了してください。
+ 接続先の 2 つ以上の AWS CloudHSM クラスターとそのクラスター証明書。
+ セキュリティグループが上記のすべてのクラスターに接続するように正しく設定された EC2 インスタンス。クラスターとクライアントインスタンスのセットアップ方法の詳細については、[「 の開始方法 AWS CloudHSM](getting-started.md)」を参照してください。
+ マルチスロット機能を設定するには、PKCS \$111 ライブラリを事前にダウンロードしてインストールしておく必要があります。これをまだ確認していない場合は、「[AWS CloudHSM クライアント SDK 5 用の PKCS \$111 ライブラリをインストールする](pkcs11-library-install.md)」の手順を参照してください。
# のマルチスロット機能用に PKCS \$111 ライブラリを設定する AWS CloudHSM
のマルチスロット機能用に PKCS \$111 ライブラリを設定するには AWS CloudHSM、次の手順に従います。
1. マルチスロット機能を使用して接続するクラスターを特定します。
1. [のマルチスロット機能を持つクラスターを追加する AWS CloudHSM](pkcs11-multi-slot-add-cluster.md) の手順に従って、これらのクラスターを PKCS \$111 設定に追加します。
1. 次回 PKCS \$111 アプリケーションを実行するときには、マルチスロット機能が使用できるようになります。
# のマルチスロット機能を持つクラスターを追加する AWS CloudHSM
[PKCS \$111 for を使用して複数のスロットに接続する](pkcs11-library-configs-multi-slot.md)場合は AWS CloudHSM、 **configure-pkcs11 add-cluster** コマンドを使用して設定にクラスターを追加します。
## 構文
```
configure-pkcs11 add-cluster [OPTIONS]
--cluster-id
[--region ]
[--endpoint ]
[--hsm-ca-cert ]
[--client-cert-hsm-tls-file ]
[--client-key-hsm-tls-file ]
[-h, --help]
```
## 例
### `cluster-id` パラメータを使用してクラスターを追加する
**Example**
**configure-pkcs11 add-cluster** とともに `cluster-id` パラメータを使用して、クラスター (`cluster-1234567` の ID) を設定に追加します。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id
```
**ヒント**
**configure-pkcs11 add-cluster** を `cluster-id` パラメータと一緒に使用してもクラスターが追加されない場合は、以下の例を参照して、追加するクラスターを識別するための `--region` と `--endpoint` パラメータも必要な、より長いバージョンのこのコマンドを参照してください。例えば、クラスターのリージョンが AWS CLI のデフォルトとして設定されているものと異なる場合、適切なリージョンを使用するように `--region` パラメータを使用する必要があります。さらに、呼び出しに使用する AWS CloudHSM API エンドポイントを指定することもできます。これは、デフォルトの DNS ホスト名を使用しない VPC インターフェイスエンドポイントを使用するなど、さまざまなネットワーク設定に必要な場合があります AWS CloudHSM。
### `cluster-id`、`endpoint`、および `region` パラメータを使用してクラスターを追加する
**Example**
**configure-pkcs11 add-cluster** とともに `cluster-id`、`endpoint`、`region` のパラメータを使用して、クラスター (`cluster-1234567` の ID) を設定に追加します。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 add-cluster --cluster-id --region --endpoint
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" add-cluster --cluster-id --region --endpoint
```
`--cluster-id`、`--region`、`--endpoint` パラメータの詳細については、[AWS CloudHSM クライアント SDK 5 設定パラメータ](configure-tool-params5.md)を参照してください。
## パラメータ
**--cluster-id ****
`DescribeClusters` を呼び出して、クラスターIDに関連付けられたクラスターのすべての HSM Elastic Network Interface（ENI）IPアドレスを検索します。システムは ENI IP アドレスを設定 AWS CloudHSM ファイルに追加します。
パブリックインターネットにアクセスできない VPC 内の EC2 インスタンスから `--cluster-id`パラメータを使用する場合は、接続するインターフェイス VPC エンドポイントを作成する必要があります AWS CloudHSM。VPC エンドポイントの詳細については、「[AWS CloudHSM および VPC エンドポイント](cloudhsm-vpc-endpoint.md)」を参照してください。
必須: はい
**--endpoint ****
`DescribeClusters` 呼び出しに使用する AWS CloudHSM API エンドポイントを指定します。このオプションは `--cluster-id` と組み合わせて設定する必要があります。
必須: いいえ
**--hsm-ca-cert ****
HSM CA 証明書ファイルへのファイルパスを指定します。
必須: いいえ
**--region ****
クラスターのリージョンを指定します。このオプションは `--cluster-id` と組み合わせて設定する必要があります。
この `--region` パラメータを指定しない場合、システムは `AWS_DEFAULT_REGION` または `AWS_REGION` の環境変数の読み取りを試みてリージョンを選択します。これらの変数が設定されていない場合、環境変数で別のファイルを指定しない限り、AWS Config (通常は `~/.aws/config`) のプロファイルに関連付けられたリージョンをチェックします`AWS_CONFIG_FILE`。いずれも設定されていない場合は、`us-east-1` デフォルトでリージョンが設定されます。
必須: いいえ
**--client-cert-hsm-tls-file *<クライアント証明書の hsm tls パス>***
TLS クライアントと HSM の相互認証に使用するクライアント証明書へのパス。
このオプションは、CloudHSM CLI で HSM に少なくとも 1 つのトラストアンカーを登録している場合にのみ使用します。このオプションは `--client-key-hsm-tls-file` と組み合わせて設定する必要があります。
必須: いいえ
**--client-key-hsm-tls-file *<クライアントキー hsm tls のパス＞***
TLS クライアントと HSM の相互認証に使用されるクライアントキーへのパス。
このオプションは、CloudHSM CLI で HSM に少なくとも 1 つのトラストアンカーを登録している場合にのみ使用します。このオプションは `--client-cert-hsm-tls-file` と組み合わせて設定する必要があります。
必須: いいえ
# のマルチスロット機能を持つクラスターを削除する AWS CloudHSM
[PKCS \$111 を使用して複数のスロットに接続する](pkcs11-library-configs-multi-slot.md)場合は、**configure-pkcs11 remove-cluster** コマンドを使用して使用可能な PKCS\$111 スロットからクラスターを削除します。
## 構文
```
configure-pkcs11 remove-cluster [OPTIONS]
--cluster-id
[-h, --help]
```
## 例
### `cluster-id` パラメータを使用してクラスターを削除します
**Example**
**configure-pkcs11 remove-cluster** とともに `cluster-id` パラメータを使用して、クラスター (`cluster-1234567` の ID) を設定から削除します。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 remove-cluster --cluster-id
```
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" remove-cluster --cluster-id
```
`--cluster-id` パラメータの詳細については、「[AWS CloudHSM クライアント SDK 5 設定パラメータ](configure-tool-params5.md)」をご参照ください。
## パラメータ
**--cluster-id ****
設定から削除するクラスターの ID
必須: はい
# の PKCS \$111 ライブラリのコマンドを再試行する 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-pkcs11 --default-retry-mode off
```
------
#### [ Windows ]
**Windows 上の クライアント SDK 5 向けに再試行コマンドを **off** に設定するには**
+ 次のコマンドを使用して再試行設定を **off** モードに設定できます。
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --default-retry-mode off
```
------
# PKCS \$111 ライブラリを使用した証明書ストレージ
AWS CloudHSM の PKCS \$111 ライブラリは、hsm2m.medium クラスター上でパブリックキー証明書を「パブリックオブジェクト」(PKCS \$111 2.40 で定義) として保存することをサポートしています。この機能により、パブリック PKCS \$111 セッションとプライベート PKCS \$111 セッションの両方で、パブリックキー証明書の作成、取得、変更、および削除が可能になります。
PKCS \$111 ライブラリで証明書ストレージを使用するには、クライアント設定でこの機能を有効にする必要があります。有効化すると、PKCS \$111 アプリケーションから証明書オブジェクトを管理できるようになります。証明書とキーの両方に適用されるオペレーション ([C\$1FindObjects](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html#_Toc323205461) など) は、キーと証明書の両方のストレージから結果を返します。
**Topics**
+ [証明書ストレージを有効にする](pkcs11-certificate-storage-configuration.md)
+ [証明書ストレージ API](pkcs11-certificate-storage-api.md)
+ [証明書の属性](pkcs11-certificate-storage-attributes.md)
+ [証明書ストレージの監査ログ](pkcs11-certificate-storage-audit-logs.md)
# 証明書ストレージの有効化
PKCS \$111 ライブラリの設定ツールを使用して、hsm2m.medium クラスターで証明書ストレージを有効化できます。この機能は、SDK バージョン 5.13 以降で利用可能です。証明書オブジェクトタイプをサポートするオペレーションの一覧については、[証明書ストレージ API オペレーション](pkcs11-certificate-storage-api.md) を参照してください。
証明書ストレージを有効にするには、使用しているオペレーティングシステムに応じて次の手順に従ってください。
------
#### [ Linux ]
+
****証明書ストレージを有効にする****
次のコマンドを実行します。
```
$ sudo /opt/cloudhsm/bin/configure-pkcs11 --enable-certificate-storage
```
------
#### [ Windows ]
+
****証明書ストレージを有効にする****
コマンドプロンプトを開き、次のコマンドを実行します。
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-pkcs11.exe" --enable-certificate-storage
```
------
# 証明書ストレージ API オペレーション
次の PKCS \$111 オペレーションは、証明書オブジェクトタイプ (`CKO_CERTIFICATE`) をサポートしています。
## 一般的な証明書オペレーション
**`C_CreateObject`**
新しい証明書オブジェクトを作成します。
**`C_DestroyObject`**
既存の証明書オブジェクトを削除します。
**`C_GetAttributeValue`**
証明書オブジェクトの 1 つ以上の属性の値を取得します。
**`C_SetAttributeValue`**
証明書オブジェクトの 1 つ以上の属性の値を更新します。
## 証明書オブジェクトの検索オペレーション
**`C_FindObjectsInit`**
証明書オブジェクトの検索を開始します。
**`C_FindObjects`**
証明書オブジェクトの検索を続行します。
**`C_FindObjectsFinal`**
証明書オブジェクトの検索を終了します。
# 証明書ストレージの属性
次の表に、サポートされている証明書オブジェクトの属性とその値を示します。
| 属性 | デフォルトの 値 | 説明 |
| --- | --- | --- |
| `CKA_CLASS` | 必須 | `CKO_CERTIFICATE` を指定してください。 |
| `CKA_TOKEN` | 正 | `True` を指定してください。 |
| `CKA_MODIFIABLE` | 正 | `True` を指定してください。 |
| `CKA_PRIVATE` | 誤 | `False` を指定してください。 |
| `CKA_LABEL` | 空 | 最大 127 文字。 |
| `CKA_COPYABLE` | 誤 | `False` を指定してください。 |
| `CKA_DESTROYABLE` | 正 | `True` を指定してください。 |
| `CKA_CERTIFICATE_TYPE` | 必須 | `CKC_X_509` を指定してください。 |
| `CKA_TRUSTED` | 誤 | `False` を指定してください。 |
| `CKA_CERTIFICATE_CATEGORY` | `CK_CERTIFICATE_CATEGORY_UNSPECIFIED` | `CK_CERTIFICATE_CATEGORY_UNSPECIFIED` を指定してください。 |
| `CKA_CHECK_VALUE` | `CKA_VALUE` から派生 | `CKA_VALUE` に基づいて自動的に設定されます。 |
| `CKA_START_DATE` | 空 | 証明書の「Not Before」日付。 |
| `CKA_END_DATE` | 空 | 証明書の「Not After」日付。 |
| `CKA_PUBLIC_KEY_INFO` | 空 | 最大サイズは 16 キロバイトです。 |
| `CKA_SUBJECT` | 必須 | 証明書のサブジェクト。 |
| `CKA_ID` | 空 | 最大サイズは 128 バイトです。一意性は強制されません。 |
| `CKA_ISSUER` | 空 | 証明書の発行者。 |
| `CKA_SERIAL_NUMBER` | 空 | 証明書のシリアル番号。 |
| `CKA_VALUE` | 必須 | 最大サイズは 32 キロバイトです。 |
# 証明書ストレージの監査ログ
AWS CloudHSM は、データを変更する証明書ストレージのオペレーションについて、クラスターの CloudWatch ロググループ内にある Amazon CloudWatch Events の個別ログストリームに監査ログを書き込みます。このログストリームは、クラスター単位で命名され、クラスタ内の特定の HSM ごとには作成されません。
CloudWatch で監査ログにアクセスする方法については、[Amazon CloudWatch Logs と AWS CloudHSM 監査ログの使用](get-hsm-audit-logs-using-cloudwatch.md) を参照してください。
## ログエントリフィールド
`object_handle`
証明書オブジェクトの一意の識別子。
`op_code`
実行または試行されたオペレーション。使用できる値:
+ `CreateObject`
+ `DestroyObject`
+ `SetAttributeValues`
`response`
オペレーションが成功した場合は `OK`、または次のいずれかのエラータイプ。
+ `DuplicateAttribute`
+ `InvalidAttributeValue`
+ `ObjectNotFound`
+ `MaxObjectsReached`
+ `InternalFailure`
`attributes`
変更された属性 (存在する場合)。
`timestamp`
オペレーションが発生した時刻 (Unix エポックからの経過ミリ秒)。
## 監査ログの例
### CreateObject の例
```
{
"object_handle": 463180677312929947,
"op_code": "CreateObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482483671
}
```
### DestroyObject の例
```
{
"object_handle": 463180677312929947,
"op_code": "DestroyObject",
"response": "OK",
"attributes": null,
"timestamp": 1725482484559
}
```
### SetAttributeValues の例
```
{
"object_handle": 463180678453346687,
"op_code": "SetAttributeValues",
"response": "OK",
"attributes": [
"Label"
],
"timestamp": 1725482488004
}
```
### 失敗した CreateObject の例
```
{
"object_handle": null,
"op_code": "CreateObject",
"response": "MaxObjectsReached",
"attributes": null,
"timestamp": 1726084937125
}
```
# AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine
AWS CloudHSM OpenSSL Dynamic Engine を使用すると、OpenSSL API を使用して暗号化オペレーションを CloudHSM OpenSSL クラスターにオフロードできます。
AWS CloudHSM には OpenSSL Dynamic Engine が用意されています。このエンジンは、 [AWS CloudHSM JSSE で Tomcat を使用した Linux での SSL/TLS オフロード](third-offload-linux-jsse.md)または で確認できます[AWS CloudHSM NGINX または Apache with OpenSSL を使用した Linux での SSL/TLS オフロード](third-offload-linux-openssl.md)。OpenSSL AWS CloudHSM で を使用する例については、[この AWS セキュリティブログ](https://aws.amazon.com/blogs/security/automate-the-deployment-of-an-nginx-web-service-using-amazon-ecs-with-tls-offload-in-cloudhsm/)を参照してください。SDK のプラットフォームサポートトの詳細については、「[AWS CloudHSM クライアント SDK 5 でサポートされているプラットフォーム](client-supported-platforms.md)」を参照してください。トラブルシューティングについては、「[の OpenSSL Dynamic Engine の既知の問題 AWS CloudHSM](ki-openssl-sdk.md)」を参照してください。
クライアント SDK 5 を使用して OpenSSL の AWS CloudHSM 動的エンジンをインストールおよび設定するには、以下のセクションを使用します。
クライアント SDK 3 の使用の詳細については、「[以前の SDK バージョンを使用して を操作する AWS CloudHSM](choose-client-sdk.md)」を参照してください。
**Topics**
+ [AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine をインストールする](openssl5-install.md)
+ [OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5 でサポートされているキータイプ](openssl-key-types.md)
+ [AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine でサポートされているメカニズム](openssl-mechanisms.md)
+ [OpenSSL for の詳細設定 AWS CloudHSM](openssl-library-configs.md)
# AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine をインストールする
以下のセクションを使用して、 AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine をインストールします。
**注記**
クライアント SDK 5 で単一の HSM クラスターを実行するには、まず `disable_key_availability_check` を `True` に設定してクライアントキーの耐久性の設定を管理する必要があります。詳細については、[キーの同期](manage-key-sync.md) と [クライアント SDK 5 設定ツール](configure-sdk-5.md) を参照してください。
**OpenSSL Dynamic Engine をインストールして設定するには**
1. 以下のコマンドを使用して、OpenSSL エンジンをダウンロードしてインストールします。
------
#### [ Amazon Linux 2023 ]
Amazon Linux 2023 用 OpenSSL Dynamic Engine を X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.x86_64.rpm
```
Amazon Linux 2023 用 OpenSSL Dynamic Engine を ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.amzn2023.aarch64.rpm
```
------
#### [ Amazon Linux 2 ]
Amazon Linux 2 用 OpenSSL Dynamic Engine を x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.x86_64.rpm
```
Amazon Linux 2 用 OpenSSL Dynamic Engine を ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-dyn-latest.el7.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el7.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
RHEL 9 用 OpenSSL Dynamic Engine を X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.x86_64.rpm
```
RHEL 9 用 OpenSSL Dynamic Engine を ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-dyn-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el9.aarch64.rpm
```
------
#### [ RHEL 8 (8.3\$1) ]
RHEL 8 用 OpenSSL Dynamic Engine を X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.x86_64.rpm
```
OpenSSL Dynamic Engine for RHEL 8 を ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL8/cloudhsm-dyn-latest.el8.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-dyn-latest.el8.aarch64.rpm
```
------
#### [ Ubuntu 24.04 LTS ]
OpenSSL Dynamic Engine for Ubuntu 24.04 LTS を x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_amd64.deb
```
OpenSSL Dynamic Engine for Ubuntu 24.04 LTS を ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-dyn_latest_u24.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u24.04_arm64.deb
```
------
#### [ Ubuntu 22.04 LTS ]
Ubuntu 22.04 LTS 用 OpenSSL Dynamic Engine を X86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_amd64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_amd64.deb
```
Ubuntu 22.04 LTS 用 OpenSSL Dynamic Engine をARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Jammy/cloudhsm-dyn_latest_u22.04_arm64.deb
```
```
$ sudo apt install ./cloudhsm-dyn_latest_u22.04_arm64.deb
```
------
ダイナミックエンジン用の共有ライブラリが `/opt/cloudhsm/lib/libcloudhsm_openssl_engine.so` にインストールされました。
1. クライアント SDK 5 をブートストラップします。ブートストラップの詳細については、[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to) を参照してください。
1. Crypto User (CU) の認証情報を使用して環境変数を設定します。CU の詳細については、「[CloudHSM CLI を使用して AWS CloudHSM ユーザーを作成する](cloudhsm_cli-user-create.md)」を参照してください。
```
$ export CLOUDHSM_PIN=:
```
**注記**
クライアント SDK 5 では CU の認証情報を保存するための `CLOUDHSM_PIN` 環境変数が導入されています。クライアント SDK 3 では、CU の認証情報を `n3fips_password` 環境変数に保存します。クライアント SDK 5 は両方の環境変数をサポートしますが、`CLOUDHSM_PIN` を使用することを推奨します。
`CLOUDHSM_PIN` 環境変数を設定するときは、シェルによって解釈される可能性のある特殊文字をエスケープする必要があります。
1. OpenSSL Dynamic Engine のインストールをクラスターに接続します。詳細については、[クラスターへの接続](cluster-connect.md) を参照してください。
1. クライアント SDK 5 をブートストラップします。詳細については、「[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to)」を参照してください。
## クライアント SDK 5 用 [OpenSSL 動的エンジン] を確認します。
次のコマンドを使用して [OpenSSL 動的エンジン] のインストールを確認します。
```
$ openssl engine -t cloudhsm
```
次の出力により設定が検証されます。
```
(cloudhsm) CloudHSM OpenSSL Engine
[ available ]
```
# OpenSSL Dynamic Engine for AWS CloudHSM Client SDK 5 でサポートされているキータイプ
AWS CloudHSM OpenSSL Dynamic Engine は、クライアント SDK 5 で次のキータイプをサポートしています。
****
| キータイプ | 説明 |
| --- | --- |
| EC | P-256、P-384、および secp256k1 キータイプの ECDSA 署名/検証。OpenSSL エンジンと相互運用可能な EC キーを生成するには、[CloudHSM CLI で非対称キーをエクスポートする](cloudhsm_cli-key-generate-file.md) を参照してください。 |
| RSA | 2,048、3,072、および 4,096 ビットキーの RSA キーの生成および RSA 署名/検証 検証は OpenSSL ソフトウェアにオフロードされます。 |
# AWS CloudHSM クライアント SDK 5 用の OpenSSL Dynamic Engine でサポートされているメカニズム
AWS CloudHSM OpenSSL Dynamic Engine は、クライアント SDK 5 で関数に署名および検証するための以下のメカニズムをサポートしています。
## 署名および検証
クライアント SDK 5 では、データはソフトウェアでローカルにハッシュされます。これは、ハッシュできるデータのサイズに制限がないことを意味します。
RSA 署名タイプ
+ SHA1withRSA
+ SHA224withRSA
+ SHA256withRSA
+ SHA384withRSA
+ SHA512withRSA
ECDSA 署名タイプ
+ SHA1 (ECDSA 搭載)
+ SHA224 (ECDSA 搭載)
+ SHA256 (ECDSA 搭載)
+ SHA384 (ECDSA 搭載)
+ SHA512 (ECDSA 搭載)
# OpenSSL for の詳細設定 AWS CloudHSM
AWS CloudHSM OpenSSL プロバイダーには次の詳細設定が含まれていますが、これはほとんどのお客様が使用する一般的な設定の一部ではありません。これらの設定には追加機能があります。
+ [OpenSSL の再試行コマンド](openssl-library-configs-retry.md)
# の OpenSSL の再試行コマンド 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)」を参照してください。
## 再試行コマンドをオフモードに設定する
再試行コマンドを **off** モードに設定するには以下のコマンドを使用できます。
```
$ sudo /opt/cloudhsm/bin/configure-dyn --default-retry-mode off
```
# AWS CloudHSM クライアント SDK 5 の OpenSSL プロバイダー
AWS CloudHSM OpenSSL プロバイダーを使用すると、OpenSSL プロバイダー API を使用して TLS 暗号化オペレーションを CloudHSM OpenSSL クラスターにオフロードできます。プロバイダーインターフェイスは、OpenSSL 3.2 以降を使用する新しいデプロイに推奨されるアプローチです。
クライアント SDK 5 を使用して AWS CloudHSM OpenSSL プロバイダーをインストールおよび設定するには、以下のセクションを使用します。
**警告**
OpenSSL CLI との統合は現在、 AWS CloudHSM OpenSSL プロバイダーではサポートされていません。サポートされている統合[AWS CloudHSM OpenSSL プロバイダーで NGINX または HAProxy を使用した Linux での OpenSSL/TLS オフロード](third-offload-linux-openssl-provider.md)については、「」を参照してください。
## サポートされているプラットフォーム
OpenSSL プロバイダーには、EL9\$1、Ubuntu 24.04\$1、および Amazon Linux 2023\$1 で利用可能な OpenSSL 3.2 以降が必要です。
互換性を確認します。 `openssl version`
**Topics**
+ [サポートされているプラットフォーム](#openssl-provider-supported-platforms)
+ [AWS CloudHSM クライアント SDK 5 用の OpenSSL プロバイダーをインストールする](openssl-provider-install.md)
+ [AWS CloudHSM クライアント SDK 5 の OpenSSL プロバイダーでサポートされているキータイプ](openssl-provider-key-types.md)
+ [OpenSSL プロバイダーがサポートするメカニズム](openssl-provider-mechanisms.md)
+ [OpenSSL プロバイダーの詳細設定](openssl-provider-advanced-config.md)
# AWS CloudHSM クライアント SDK 5 用の OpenSSL プロバイダーをインストールする
以下のセクションを使用して、AWS CloudHSM Client SDK 5 用の OpenSSL プロバイダーをインストールします。
**注記**
クライアント SDK 5 で単一の HSM クラスターを実行するには、まず `disable_key_availability_check` を `True` に設定してクライアントキーの耐久性の設定を管理する必要があります。詳細については、[キーの同期](working-client-sync.md#client-sync-sdk8) と [クライアント SDK 5 設定ツール](configure-sdk-5.md) を参照してください。
## 要件
OpenSSL プロバイダーには、**hsm2m.medium** クラスタータイプと最小 CloudHSM Client SDK バージョン 5.17.0 以降が必要です。
## OpenSSL プロバイダーをインストールする
**OpenSSL プロバイダーをインストールするには**
1. 次のコマンドを使用して、OpenSSL プロバイダーをダウンロードしてインストールします。
------
#### [ Amazon Linux 2023 ]
Amazon Linux 2023 用の OpenSSL プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.x86_64.rpm
```
Amazon Linux 2023 用の OpenSSL プロバイダーを ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Amzn2023/cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.amzn2023.aarch64.rpm
```
------
#### [ RHEL 9 (9.2\$1) ]
RHEL 9 用の OpenSSL プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.x86_64.rpm
```
ARM64 アーキテクチャに RHEL 9 用の OpenSSL プロバイダーをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL9/cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el9.aarch64.rpm
```
------
#### [ RHEL 10 (10.0\$1) ]
RHEL 10 用の OpenSSL プロバイダーを x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.x86_64.rpm
```
ARM64 アーキテクチャに RHEL 10 用の OpenSSL プロバイダーをインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL10/cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
```
$ sudo yum install ./cloudhsm-openssl-provider-latest.el10.aarch64.rpm
```
------
#### [ Ubuntu 24.04 ]
OpenSSL Provider for Ubuntu 24.04 を x86\$164 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_amd64.deb
```
OpenSSL Provider for Ubuntu 24.04 を ARM64 アーキテクチャにインストールします。
```
$ wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Noble/cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
```
$ sudo dpkg -i ./cloudhsm-openssl-provider_latest_u24.04_arm64.deb
```
------
OpenSSL プロバイダーの共有ライブラリが にインストールされています`/opt/cloudhsm/lib/licloudhsm_openssl_provider.so`。
1. クライアント SDK 5 をブートストラップします。ブートストラップの詳細については、[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to) を参照してください。
1. Crypto User (CU) 認証情報を使用して `CLOUDHSM_PIN` 環境変数を設定します。
```
$ export CLOUDHSM_PIN=:
```
1. OpenSSL プロバイダーのインストールをクラスターに接続します。詳細については、[クラスターへの接続](cluster-connect.md) を参照してください。
## インストールの検証
OpenSSL プロバイダーが正しくインストールされていることを確認します。
```
$ CLOUDHSM_PIN=: openssl list -providers -provider cloudhsm
```
次のような出力が表示されます。
```
Providers:
cloudhsm
name: AWS CloudHSM OpenSSL Provider
version: 5.17.0
status: active
default
name: OpenSSL Default Provider
version: 3.2.2
status: active
```
# AWS CloudHSM クライアント SDK 5 の OpenSSL プロバイダーでサポートされているキータイプ
AWS CloudHSM OpenSSL プロバイダーは、クライアント SDK 5 で次のキータイプをサポートしています。
****
| キータイプ | 説明 |
| --- | --- |
| RSA | RSA 署名/検証および非対称暗号化オペレーション。検証は OpenSSL ソフトウェアにオフロードされます。OpenSSL プロバイダーと相互運用可能な RSA キーを生成するには、「」を参照してください[CloudHSM CLI で非対称キーをエクスポートする](cloudhsm_cli-key-generate-file.md)。 |
| EC | PP-256, P-384P-521曲線の ECDSA 署名/検証。検証は OpenSSL ソフトウェアにオフロードされます。OpenSSL プロバイダーと相互運用可能な EC キーを生成するには、「」を参照してください[CloudHSM CLI で非対称キーをエクスポートする](cloudhsm_cli-key-generate-file.md)。 |
# OpenSSL プロバイダーがサポートするメカニズム
AWS CloudHSM OpenSSL プロバイダー SDK は、デジタル署名、非対称暗号化、対称暗号化、キー交換など、さまざまなオペレーションのための包括的な暗号化メカニズムのセットをサポートしています。
## RSA 署名タイプ
OpenSSL プロバイダーは、複数のハッシュアルゴリズムとパディングスキームを持つ RSA デジタル署名をサポートしています。
SHA1withRSA
SHA-1 ハッシュアルゴリズムを使用した RSA 署名
+ PKCS\$11 v1.5 パディング
+ PSS (確率的署名スキーム) パディング
SHA224withRSA
SHA-224 ハッシュアルゴリズムを使用した RSA 署名
+ PKCS\$11 v1.5 パディング
+ PSS パディング
SHA256withRSA
SHA-256 ハッシュアルゴリズムを使用した RSA 署名
+ PKCS\$11 v1.5 パディング
+ PSS パディング
SHA384withRSA
SHA-384 ハッシュアルゴリズムを使用した RSA 署名
+ PKCS\$11 v1.5 パディング
+ PSS パディング
SHA512withRSA
SHA-512 ハッシュアルゴリズムを使用した RSA 署名
+ PKCS\$11 v1.5 パディング
+ PSS パディング
## ECDSA 署名タイプ
OpenSSL プロバイダーは、複数のハッシュアルゴリズムによる ECDSA デジタル署名をサポートしています。
SHA1 (ECDSA 搭載)
SHA-1 ハッシュアルゴリズムを使用した ECDSA 署名
SHA224 (ECDSA 搭載)
SHA-224 ハッシュアルゴリズムを使用した ECDSA 署名
SHA256 (ECDSA 搭載)
SHA-256 ハッシュアルゴリズムを使用した ECDSA 署名
SHA384 (ECDSA 搭載)
SHA-384 ハッシュアルゴリズムを使用した ECDSA 署名
SHA512 (ECDSA 搭載)
SHA-512 ハッシュアルゴリズムを使用した ECDSA 署名
# OpenSSL プロバイダーの詳細設定
AWS CloudHSM OpenSSL プロバイダー SDK には、さまざまなユースケースや環境に合わせて動作をカスタマイズするための高度な設定オプションが用意されています。設定ツールを使用して、これらのオプションを設定します。
+ [OpenSSL プロバイダーの設定を再試行する](openssl-provider-configs-retry.md)
# の OpenSSL プロバイダーの再試行コマンド 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-openssl-provider --default-retry-mode off
```
------
# AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP)
キーストレージプロバイダー (KSP) は、Microsoft Windows オペレーティングシステム固有の暗号 API です。キーストレージプロバイダー (KSP) を使用すると、開発者は暗号化技術を使用して Windows ベースのアプリケーションを保護できます。
ブートストラップの詳細については、「[クラスターへの接続](cluster-connect.md)」を参照してください。
Client SDK 3 の使用の詳細については、「[以前の SDK バージョンを使用して を操作する AWS CloudHSM](choose-client-sdk.md)」を参照してください。
**Topics**
+ [AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) をインストールする](ksp-library-install.md)
+ [AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) への認証](ksp-library-authentication.md)
+ [AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) でサポートされているキータイプ](ksp-library--key-types.md)
+ [サポートされている API オペレーション AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP)](ksp-library-apis.md)
+ [の KSP の詳細設定 AWS CloudHSM](ksp-library-configs.md)
# AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) をインストールする
以下のセクションを使用して、 AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) をインストールします。
**注記**
クライアント SDK 5 で単一の HSM クラスターを実行するには、まず `disable_key_availability_check` を `True` に設定してクライアントキーの耐久性の設定を管理する必要があります。詳細については、[キーの同期](manage-key-sync.md) と [クライアント SDK 5 設定ツール](configure-sdk-5.md) を参照してください。
**キーストレージプロバイダー (KSP) をインストールして設定するには**
1. Windows Server 用のキーストレージプロバイダー (KSP) を x86\$164 アーキテクチャにインストールし、管理者として PowerShell を開き、以下のコマンドを実行します。
```
PS C:\> wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Windows/AWSCloudHSMKSP-latest.msi -Outfile C:\AWSCloudHSMKSP-latest.msi
```
```
PS C:\> Start-Process msiexec.exe -ArgumentList '/i C:\AWSCloudHSMKSP-latest.msi /quiet /norestart /log C:\client-install.txt' -Wait
```
1. 構成ツールを使用して、証明書の発行場所を指定します。手順については、「[発行証明書の場所を指定する](cluster-connect.md#specify-cert-location)」を参照してください。
1. クラスターに接続して使用するには、「[クライアント SDK をブートストラップする](cluster-connect.md#connect-how-to)」を参照してください。
1. キーストレージプロバイダー (KSP) ファイルは、次の場所にあります。
+ Windows のバイナリ:
```
C:\Program Files\Amazon\CloudHSM
```
Windows の設定スクリプトとログファイル:
```
C:\ProgramData\Amazon\CloudHSM
```
# AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) への認証
AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) を使用する前に、システムで HSM のログイン認証情報を設定する必要があります。これには 2 つのオプションがあります。
+ Windows 資格情報マネージャー (より高いセキュリティのため推奨)
+ システム環境変数 (より簡単なセットアップ)
## Windows 資格情報マネージャー
認証情報は、`set_cloudhsm_credentials` ユーティリティまたは Windows 資格情報マネージャーのインターフェイスを使用して設定できます。
+ **`set_cloudhsm_credentials` ユーティリティの使用**:
Windows インストーラには `set_cloudhsm_credentials` ユーティリティが含まれています。このユーティリティを使用して、HSM ログイン認証情報を Windows 資格情報マネージャーに簡単に渡すことができます。このユーティリティをソースからコンパイルする場合は、インストーラに含まれている Python コードを使用できます。
1. `C:\Program Files\Amazon\CloudHSM\tools\` に移動します。
1. 次のコマンドを実行します。
```
set_cloudhsm_credentials.exe --username --password
```
+ **資格情報マネージャーのインターフェイスの使用**:
1. 認証情報マネージャーを開く:
+ タスクバーの検索ボックスに `credential manager` と入力します
+ [**資格情報マネージャー**] を選択します
1. [**Windows 資格情報**] を選択して、Windows 資格情報を管理します。
1. [**汎用資格情報を追加**] を選択します
1. 次の詳細情報を入力します。
+ **インターネットまたはネットワークアドレス**: `CLOUDHSM_PIN`。
+ **ユーザー名**: **。
+ **パスワード**: **。
1. **[OK]** をクリックします。
## システム環境変数
ご使用の HSM および [Crypto User](understanding-users.md#crypto-user-chsm-cli) (CU) を識別するシステム環境変数を設定できます。
**警告**
システム環境変数を使用して認証情報を設定すると、パスワードがシステム上にプレーンテキストで保存されます。セキュリティを向上させるには、代わりに Windows 資格情報マネージャーを使用してください。
以下のいずれかを使用して環境変数を設定できます。
+ [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx)。
+ Windows の [**システムプロパティ**] コントロールパネル ([**詳細設定**] タブ)。
+ [プログラム](https://msdn.microsoft.com/en-us/library/system.environment.setenvironmentvariable(v=vs.110).aspx)によるシステム環境変数の永続的な設定方法。
システム環境変数を設定する方法
**`CLOUDHSM_PIN=:`**
HSM の [Crypto User](understanding-users.md#crypto-user-chsm-cli) (CU) を識別し、必要なすべてのログイン情報を提供します。アプリケーションはこの CU として認証および実行します。このアプリケーションには、この CU のアクセス権限があり、CU が所有および共有しているキーのみを表示および管理できます。新しい CU を作成するには、CloudHSM CLI で[user create](cloudhsm_cli-user-create.md) コマンドを使用します。既存の CU を検索するには、CloudHSM CLI で [user list](cloudhsm_cli-user-list.md) コマンドを使用します。
例えば、次のようになります。
```
setx /m CLOUDHSM_PIN test_user:password123
```
**注記**
CLOUDHSM\$1PIN 環境変数を設定するときは、シェルによって解釈される可能性のある特殊文字をエスケープする必要があります。
# AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP) でサポートされているキータイプ
AWS CloudHSM キーストレージプロバイダー (KSP) は、クライアント SDK 5 で次のキータイプをサポートしています。
****
| キータイプ | 説明 |
| --- | --- |
| EC | secp256r1 (P-256)、secp384r1 (P-384)、secp521r1 (P-521) 曲線を使用してキーを生成します。 |
| RSA | 2,048 ビット、3,072 ビット、および 4,096 ビットの RSA キーを生成します。 |
# サポートされている API オペレーション AWS CloudHSM クライアント SDK 5 のキーストレージプロバイダー (KSP)
KSP のパラメータは、Microsoft KSP によって定義されます。詳細については、[Microsoft のドキュメント](https://learn.microsoft.com/en-us/windows/win32/api/ncrypt/)を参照してください。
キーストレージプロバイダー (KSP) は、 AWS CloudHSM クライアント SDK 5 の次の KSP API オペレーションをサポートしています。
+ [`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md)
+ [NCryptOpenKey](ksp-library-apis-open-key.md)
+ [NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md)
+ [NCryptGetProperty](ksp-library-apis-get-property.md)
+ [NCryptSetProperty](ksp-library-apis-set-property.md)
+ [NCryptFinalizeKey](ksp-library-apis-finalize-key.md)
+ [NCryptDeleteKey](ksp-library-apis-delete-key.md)
+ [NCryptFreeObject](ksp-library-apis-free-object.md)
+ [NCryptFreeBuffer](ksp-library-apis-free-buffer.md)
+ [NCryptIsAlgSupported](ksp-library-apis-is-alg-supported.md)
+ [NCryptEnumAlgorithms](ksp-library-apis-enum-algorithms.md)
+ [NCryptEnumKeys](ksp-library-apis-enum-keys.md)
+ [NCryptExportKey](ksp-library-apis-export-key.md)
+ [NCryptSignHash](ksp-library-apis-sign-hash.md)
+ [NCryptVerifySignature](ksp-library-apis-verify-signature.md)
# キーストレージプロバイダー (KSP) を使用した NCryptOpenStorageProvider 関数
`NCryptOpenStorageProvider` 関数は、キーストレージプロバイダー (KSP) をロードして初期化します。
## パラメータ
`phProvider` [out]
プロバイダーハンドルを保存する `NCRYPT_PROV_HANDLE` 変数へのポインタ。
`pszProviderName` [in]
キーストレージプロバイダーを識別する、null 終端された Unicode 文字列へのポインタ。AWS CloudHSM キーストレージプロバイダー (KSP) は以下の値をサポートしています。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-open-provider.html)
値は、リテラルの前に L が付いていることからわかるように、ワイド文字列リテラルです。
`dwFlags` [in]
関数の動作を変更するフラグ。この関数にはフラグが定義されていません。
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
# キーストレージプロバイダー (KSP) を使用した NCryptOpenKey
`NCryptOpenKey` 関数は、キーストレージプロバイダー (KSP) に存在するキーを開きます。
## パラメータ
`hProvider` [in]
キーを含む KSP ハンドル。このハンドルは、[`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) を使用して取得します。
`phKey` [out]
キーハンドルを保存する `NCRYPT_KEY_HANDLE` 変数へのポインタ。
`pszKeyName` [in]
キー名を含む、null 終端された Unicode 文字列へのポインタ。
`dwLegacyKeySpec` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) はこのパラメータを使用しません。
`dwFlags` [in]
関数の動作を変更するフラグ。この関数にはフラグが定義されていません。
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hProvider` のハンドルが無効です。 |
| NTE\$1BAD\$1KEYSET | 指定されたキー名は一意の結果を返しませんでした。 |
# キーストレージプロバイダー (KSP) を使用した NCryptCreatePersistedKey
`NCryptCreatePersistedKey` 関数は、新しいキーを作成し、それをキーストレージプロバイダー (KSP) に保存します。キーを作成した後、[`NCryptSetProperty`](ksp-library-apis-set-property.md) 関数を使用してそのプロパティを設定できます。キーを使用する前に、[`NCryptFinalizeKey`](ksp-library-apis-finalize-key.md) を呼び出す必要があります。
## パラメータ
`hProvider` [in]
キーを作成するキーストレージプロバイダーのハンドル。このハンドルは、[`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) を使用して取得します。
`phKey` [out]
キーハンドルを収納する `NCRYPT_KEY_HANDLE` 変数のアドレス。
`pszAlgId` [in]
キーを作成するための暗号アルゴリズム識別子を指定する、null 終端された Unicode 文字列へのポインタ。
AWS CloudHSM Key Storage Provider (KSP) は、次のアルゴリズムをサポートしています。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
`pszKeyName` [in, optional]
キー名を含む null 終端された Unicode 文字列へのポインタ。このパラメータが NULL の場合、この関数は永続化されない一時キーを作成します。
`dwLegacyKeySpec` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) はこのパラメータを使用しません。
`dwFlags` [in]
関数の動作を変更するためのフラグ。以下の値を 0 個以上使用します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-create-persisted-key.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | 関数は正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1NOT\$1SUPPORTED | `pszAlgId` パラメータにサポートされていない値が含まれています。 |
| NTE\$1EXISTS | 指定された名前のキーは既に存在し、オペレーションは ` NCRYPT_OVERWRITE_KEY_FLAG` を使用しませんでした。 |
# キーストレージプロバイダー (KSP) を使用した NCryptGetProperty
`NCryptGetProperty` 関数は、キーストレージオブジェクトのプロパティ値を取得します。
## パラメータ
`hObject` [in]
プロパティを取得する対象のオブジェクトのハンドル。次を使用できます。
+ プロバイダーハンドル (`NCRYPT_PROV_HANDLE`)
+ キーハンドル (`NCRYPT_KEY_HANDLE`)
`pszProperty ` [in]
取得するプロパティ名を含む null 終端 Unicode 文字列へのポインタ。
を使用する場合`NCRYPT_PROV_HANDLE`、 AWS CloudHSM キーストレージプロバイダー (KSP) は次の KSP 識別子をサポートします。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
を使用する場合`NCRYPT_KEY_HANDLE`、 AWS CloudHSM キーストレージプロバイダー (KSP) は次の KSP 識別子をサポートします。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
値は、リテラルの前に L が付いていることからわかるように、ワイド文字列リテラルです。
`pbOutput` [out]
プロパティ値を保存するバッファのアドレス。`cbOutput` を使用してバッファサイズを指定します。
必要なバッファサイズを決定するには、このパラメータを NULL に設定します。この関数は、必要なサイズ (バイト単位) を `pcbResult` が指す場所に保存します。
`cbOutput` [in]
`pbOutput` バッファのサイズ (バイト単位)。
`pcbResult` [out]
`pbOutput` バッファにコピーされたバイト数を保存する DWORD 変数へのポインタ。
`pbOutput` が NULL の場合、必要なサイズ (バイト単位) が保存されます。
`dwFlags` [in]
関数の動作を変更するためのフラグ。ゼロまたは以下の値を使用できます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
pszProperty が `NCRYPT_SECURITY_DESCR_PROPERTY` の場合、次のいずれかまたは組み合わせを使用します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-get-property.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1NOT\$1SUPPORTED | `pszAlgId` パラメータには、サポートされていない値が含まれています。 |
| NTE\$1INVALID\$1HANDLE | `hObject` のハンドルが無効です。 |
| NTE\$1BUFFER\$1TOO\$1SMALL | `cbOutput` パラメータが、戻り値を格納するには小さすぎます。 |
# キーストレージプロバイダー (KSP) を使用した NCryptSetProperty
`NCryptSetProperty` 関数は、キーストレージオブジェクトのプロパティ値を設定します。
## パラメータ
`hObject` [in]
プロパティを設定する対象のオブジェクトのハンドル。次を使用できます。
+ プロバイダーハンドル (`NCRYPT_PROV_HANDLE`)
+ キーハンドル (`NCRYPT_KEY_HANDLE`)
`pszProperty ` [in]
取得するプロパティ名を含む null 終端 Unicode 文字列へのポインタ。
を使用する場合`NCRYPT_PROV_HANDLE`、 AWS CloudHSM キーストレージプロバイダー (KSP) は次の KSP 識別子をサポートします。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
を使用する場合`NCRYPT_KEY_HANDLE`、 AWS CloudHSM キーストレージプロバイダー (KSP) は次の KSP 識別子をサポートします。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-set-property.html)
値は、リテラルの前に L が付いていることからわかるように、ワイド文字列リテラルです。
`pbInput` [in]
新しいプロパティ値を含むバッファのアドレス。`cbInput` にはバッファのサイズが含まれます。
`cbInput` [in]
`pbInput` バッファのサイズ (バイト単位)。
`dwFlags` [in]
関数の動作を変更するフラグ。この関数にはフラグが定義されていません。
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1NOT\$1SUPPORTED | `pszProperty` パラメータには、サポートされていない値が含まれています。 |
| NTE\$1INVALID\$1HANDLE | `hObject` のハンドルが無効です。 |
| NTE\$1BAD\$1DATA | `pbInput` および `cbInput` が指すデータは有効ではありません。 |
# キーストレージプロバイダー (KSP) を使用した NCryptFinalizeKey
`NCryptFinalizeKey` 関数は KSP キーを完了します。キーを使用する前に、この関数を呼び出す必要があります。
## パラメータ
`hKey` [in]
完了するキーのハンドル。[NCryptCreatePersistedKey](ksp-library-apis-create-persisted-key.md) 関数を呼び出して、このハンドルを取得します。
`dwFlags` [in]
関数の動作を変更するためのフラグ。0 または次の値を使用できます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-finalize-key.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hKey` のハンドルが無効です。 |
| NTE\$1NOT\$1SUPPORTED | `dwFlags` パラメータには、サポートされていない値が含まれています。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
# キーストレージプロバイダー (KSP) を使用した NCryptDeleteKey
`NCryptDeleteKey` 関数は、キーストレージプロバイダー (KSP) から KSP キーを削除します。
## パラメータ
`hKey` [in]
削除するキーのハンドル。
`dwFlags` [in]
関数の動作を変更するためのフラグ。以下の値を 0 個以上使用できます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-delete-key.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | 関数は成功しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hKey` のハンドルが無効です。 |
| NTE\$1INTERNAL\$1ERROR | キーの削除中に内部エラーが発生しました。 |
# キーストレージプロバイダー (KSP) を使用した NCryptFreeObject
`NCryptFreeObject` 関数は、キーストレージプロバイダー (KSP) からプロバイダーまたはキーハンドルを解放します。
## パラメータ
`hObject` [in]
解放するオブジェクトのハンドル。次を使用できます。
+ プロバイダーハンドル (`NCRYPT_PROV_HANDLE`)
+ キーハンドル (`NCRYPT_KEY_HANDLE`)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1HANDLE | `hObject` のハンドルが無効です。 |
# キーストレージプロバイダー (KSP) を使用した NCryptFreeBuffer
`NCryptFreeBuffer` 関数は、キーストレージプロバイダー (KSP) によって割り当てられたメモリのブロックを解放します。
## パラメータ
`pvInput` [in]
解放するメモリのアドレス。
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
# キーストレージプロバイダー (KSP) を使用した NCryptIsAlgSupported
NCryptIsAlgSupported 関数は、キーストレージプロバイダー (KSP) が特定の暗号アルゴリズムをサポートしているかどうかを判定します。
## パラメータ
`hProvider` [in]
キーストレージプロバイダーのハンドル。このハンドルは、[`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) を使用して取得します。
`pszAlgId` [in]
キーを作成するための暗号アルゴリズムの識別子を含む、null 終端された Unicode 文字列へのポインタ。AWS CloudHSM キーストレージプロバイダー (KSP) がサポートするアルゴリズムは以下のとおりです。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
`dwFlags` [in]
関数の動作を変更するフラグ。これには、ゼロまたは次のいずれかの値を指定できます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-is-alg-supported.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1NOT\$1SUPPORTED | `pszAlgId` パラメータにサポートされていない値が含まれています。 |
| NTE\$1INVALID\$1HANDLE | `hProvider` のハンドルが無効です。 |
# キーストレージプロバイダー (KSP) を使用した NCryptEnumAlgorithms
`NCryptEnumAlgorithms` 関数は、キーストレージプロバイダー (KSP) がサポートするアルゴリズムの名前を取得します。
## パラメータ
`hProvider` [in]
アルゴリズムを列挙するキーストレージプロバイダーのハンドル。このハンドルを取得するには、[`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) 関数を使用します。
`dwAlgOperations` [in]
列挙するアルゴリズムクラスを指定する値のセット。ゼロを使用してすべてのアルゴリズムを列挙することも、1 つ以上の値を結合することもできます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
`pdwAlgCount` [out]
`ppAlgList` 配列内の要素の数を保存する DWORD のアドレス。
`ppAlgList` [out]
登録されたアルゴリズム名の配列を保存する `NCryptAlgorithmName` 構造ポインタのアドレス。`pdwAlgCount` パラメータは、この配列内の要素の数を示します。
`dwFlags` [in]
関数の動作を変更するためのフラグ。ゼロまたは次の値を使用します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-enum-algorithms.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1NOT\$1SUPPORTED | `dwAlgOperations` パラメータにサポートされていない値が含まれています。 |
# キーストレージプロバイダー (KSP) を使用した NCryptEnumKeys
NCryptEnumKeys 関数は、キーストレージプロバイダー (KSP) に保存されているキーを一覧表示します。
## パラメータ
`hProvider` [in]
キーストレージプロバイダーハンドル。このハンドルは、[`NCryptOpenStorageProvider`](ksp-library-apis-open-provider.md) を使用して取得します。
`pszScope` [in, unused]
このパラメータは NULL に設定します。
`ppKeyName` [out]
キー名を保存する `NCryptKeyName` 構造へのポインタアドレス。使用後にこのメモリを解放するには、`NCryptFreeBuffer` を呼び出します。
`ppEnumState` [in, out]
列挙の進行状況を追跡する VOID ポインタアドレス。キーストレージプロバイダーは、この情報を内部的に使用して列挙シーケンスを管理します。新しい列挙を最初から開始するには、このポインタを NULL に設定します。
列挙の完了後にこのメモリを解放するには、このポインタを `NCryptFreeBuffer` に渡します。
`dwFlags` [in]
関数の動作を変更するためのフラグ。この関数にはフラグはありません。
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hProvider` のハンドルが無効です。 |
| NTE\$1NO\$1MORE\$1ITEMS | 列挙には、使用可能なすべてのキーが一覧表示されています。 |
# キーストレージプロバイダー (KSP) を使用した NCryptExportKey
`NCryptExportKey` 関数は KSP キーをメモリ BLOB にエクスポートします。この関数は、パブリックキーのエクスポートのみをサポートします。
## パラメータ
`hKey` [in]
エクスポートするキーのハンドル。
`hExportKey` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) はこのパラメータを使用しません。
`pszBlobType` [in]
エクスポートするBLOBタイプを指定する NULL 終了 Unicode 文字列。 AWS CloudHSM キーストレージプロバイダー (KSP) は次の値をサポートします。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
`pParameterList` [in, unused]
AWS CloudHSM Key Storage Provider (KSP) はこのパラメータを使用しません。
`pbOutput` [out, optional]
キー BLOB を保存するバッファアドレス。`cbOutput` を使用してバッファサイズを指定します。NULL に設定すると、関数は `pcbResult` が指す DWORD に必要なサイズ (バイト単位) を保存します。
`cbOutput` [in]
`pbOutput` バッファのサイズ (バイト単位)。
`pcbResult` [out]
`pbOutput` バッファにコピーされたバイト数を保存する DWORD 変数アドレス。`pbOutput` が NULL の場合、関数は必要なバッファサイズをバイト単位で保存します。
`dwFlags` [in]
関数の動作を変更するためのフラグ。ゼロまたは以下の値を使用できます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-export-key.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hProvider` のハンドルが無効です。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1BAD\$1KEY\$1STATE | キーの状態が無効です。 |
| NTE\$1NOT\$1SUPPORTED | `pszBlobType` または `dwFlags` パラメータにサポートされていない値が含まれています。 |
| STATUS\$1INTERNAL\$1ERROR | オペレーション中に内部エラーが発生しました。 |
# キーストレージプロバイダー (KSP) を使用した NCryptSignHash
`NCryptSignHash` 関数はハッシュ値の署名を作成します。
## パラメータ
`hKey` [in]
ハッシュの署名に使用するキーのハンドル。
`pPaddingInfo` [in, optional]
パディング情報を含む構造へのポインタ。構造タイプは `dwFlags` 値によって異なります。このパラメータは非対称キーでのみ使用し、その他のキータイプでは NULL に設定します。
`pbHashValue` [in]
署名するハッシュ値を含むバッファへのポインタ。`cbHashValue` を使用してバッファサイズを指定します。
`cbHashValue` [in]
署名する `pbHashValue` バッファのサイズ (バイト単位)。
`pbSignature` [out]
署名を保存するバッファのアドレス。`cbSignature` を使用してバッファサイズを指定します。
必要なバッファサイズを決定するには、このパラメータを NULL に設定します。この関数は、必要なサイズ (バイト単位) を `pcbResult` が指す場所に保存します。
`cbSignature` [in]
`pbSignature` バッファのサイズ (バイト単位)。この関数は、`pbSignature` が NULL の場合、このパラメータを無視します。
`pcbResult` [out]
`pbSignature` バッファにコピーされたバイト数を保存する DWORD 変数へのポインタ。
`pbSignature` が NULL の場合、必要なバッファサイズ (バイト単位) が保存されます。
`dwFlags` [in]
関数の動作を変更するためのフラグ。許可されるフラグは、キータイプによって異なります。次の値のいずれかを使用してください。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-sign-hash.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hKey` のハンドルが無効です。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1BUFFER\$1TOO\$1SMALL | `pcbOutput` パラメータが、戻り値を格納するには小さすぎます。 |
| NTE\$1BAD\$1KEY\$1STATE | キーの状態が無効です。 |
| NTE\$1INTERNAL\$1ERROR | ハッシュの署名時に内部エラーが発生しました。 |
# キーストレージプロバイダー (KSP) を使用した NCryptVerifySignature
`NCryptVerifySignature` 関数は、署名が指定されたハッシュと一致するかどうかを確認します。
## パラメータ
`hKey` [in]
署名を復号するために使用するキーのハンドル。[`NCryptSignHash`](ksp-library-apis-sign-hash.md) でデータの署名に使用されたキーペアのパブリックキー部分を使用する必要があります。
`pPaddingInfo` [in, optional]
パディング情報を含む構造へのポインタ。構造タイプは `dwFlags` 値によって異なります。このパラメータは非対称キーでのみ使用し、その他のキータイプでは NULL に設定します。
`pbHashValue` [in]
署名するハッシュ値を含むバッファへのポインタ。`cbHashValue` を使用してバッファサイズを指定します。
`cbHashValue` [in]
`pbHashValue` バッファのサイズ (バイト単位)。
`pbSignature` [out]
データの署名付きハッシュを含むバッファのアドレス。この署名を作成するには [`NCryptSignHash`](ksp-library-apis-sign-hash.md) を使用します。`cbSignature` を使用してバッファサイズを指定します。
`cbSignature` [in]
`pbSignature` バッファのサイズ (バイト単位)。この署名を作成するには [`NCryptSignHash`](ksp-library-apis-sign-hash.md) を使用します。
`dwFlags` [in]
関数の動作を変更するためのフラグ。許可されるフラグは、キータイプによって異なります。次の値のいずれかを使用してください。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/cloudhsm/latest/userguide/ksp-library-apis-verify-signature.html)
## 戻り値
この関数は、成功または失敗を示すステータスコードを返します。
一般的なリターンコードは次のとおりです。
****
| リターンコード | 説明 |
| --- | --- |
| ERROR\$1SUCCESS | オペレーションが正常に完了しました。 |
| NTE\$1INVALID\$1PARAMETER | 1 つ以上のパラメータが無効です。 |
| NTE\$1FAIL | オペレーションを完了できませんでした。 |
| NTE\$1INVALID\$1HANDLE | `hKey` のハンドルが無効です。 |
| NTE\$1BAD\$1FLAGS | `dwFlags` パラメータに無効な値が含まれています。 |
| NTE\$1BAD\$1SIGNATURE | 署名は検証されませんでした。 |
| NTE\$1BAD\$1KEY\$1STATE | キーの状態が無効です。 |
| NTE\$1INTERNAL\$1ERROR | 署名の検証中に内部エラーが発生しました。 |
# の KSP の詳細設定 AWS CloudHSM
AWS CloudHSM キーストレージプロバイダー (KSP) には、次の高度な設定が含まれています。これは、ほとんどのお客様が使用する一般的な設定の一部ではありません。これらの設定には追加機能があります。
+ [KSP の SDK3 互換モード](ksp-library-configs-sdk3-compatibility-mode.md)
# のキーストレージプロバイダー (KSP) の SDK3 互換性モード AWS CloudHSM
キーストレージプロバイダー (KSP) は、HSM キーとの連携に対して異なるアプローチを実装しています。
+ クライアント SDK 5: HSM に保存されたキーと直接通信し、ローカルの参照ファイルが不要
+ クライアント SDK 3: Windows サーバー上に、HSM に保存されたキーを参照するローカルファイルを保持し、これらのファイルを使用してキーに関するオペレーションを実行
クライアント SDK 3 からクライアント SDK 5 へ移行するお客様向けに、SDK3 互換モードを有効にすると、HSM のキー保管アーキテクチャを保持したまま、既存のキー参照ファイルを使用したオペレーションをサポートできます。
## SDK3 互換モードを有効にする
------
#### [ Windows ]
**Windows でクライアント SDK 5 用キーストレージプロバイダー (KSP) の SDK3 互換モードを有効にするには**
+ 次のコマンドを使用して SDK3 互換モードを有効にできます。
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --enable-sdk3-compatibility-mode
```
------
## SDK3 互換モードを無効にする
------
#### [ Windows ]
**Windows でクライアント SDK 5 用キーストレージプロバイダー (KSP) の SDK3 互換モードを無効にするには**
+ 次のコマンドを使用して SDK3 互換モードを無効にできます。
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-ksp.exe" --disable-sdk3-compatibility-mode
```
------
# 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
```
------