기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS CloudHSM 클라이언트 SDK 5용 JCE 공급자
AWS CloudHSM JCE 공급자는 Java 암호화 확장(JCE) 공급자 프레임워크를 기반으로 구축된 공급자 구현입니다. JCE를 사용하면 자바 개발자 키트(Java Development Kit)를 사용하여 암호화 작업을 수행할 수 있습니다. 이 가이드에서는 AWS CloudHSM JCE 공급자를 JCE 공급자라고도 합니다. JCE 공급자와 JDK를 사용하여 암호화 작업을 HSM으로 오프로드하십시오. 문제 해결은 [용 JCE SDK에 대해 알려진 문제 AWS CloudHSM](ki-jce-sdk.md) 섹션을 참조하세요.
Client 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)
+ [클라이언트 SDK 5용 AWS CloudHSM JCE의 고급 구성](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
```
ARM64 아키텍처 기반 Amazon Linux 2023용 JCE 공급자를 설치합니다.
```
$ 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
```
ARM64 아키텍처 기반 Amazon Linux 2용 JCE 공급자를 설치합니다.
```
$ 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) ]
x86\$164 아키텍처에 RHEL 10용 JCE 공급자를 설치합니다.
```
$ 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
```
ARM64 아키텍처에 RHEL 10용 JCE 공급자를 설치합니다.
```
$ 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) ]
x86\$164 아키텍처 기반 RHEL 9(9.2\$1)용 JCE 공급자를 설치합니다.
```
$ 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
```
ARM64 아키텍처 기반 RHEL 9(9.2\$1)용 JCE 공급자를 설치합니다.
```
$ 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) ]
x86\$164 아키텍처 기반 RHEL 8용 JCE 공급자를 설치합니다.
```
$ 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
```
ARM64 아키텍처에 RHEL 8용 JCE 공급자를 설치합니다.
```
$ 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 ]
x86\$164 아키텍처 기반 Ubuntu 24.04 LTS용 JCE 공급자를 설치합니다.
```
$ 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
```
ARM64 아키텍처 기반 Ubuntu 24.04 LTS용 JCE 공급자를 설치합니다.
```
$ 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 ]
x86\$164 아키텍처 기반 Ubuntu 22.04 LTS용 JCE 공급자를 설치합니다.
```
$ 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
```
ARM64 아키텍처 기반 Ubuntu 22.04 LTS용 JCE 공급자를 설치합니다.
```
$ 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 ]
x86\$164 아키텍처 기반 Windows Server용 JCE 공급자의 경우 관리자 권한으로 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 공급자에게 자격 증명 제공
Java 애플리케이션이 HSM을 사용하려면 먼저 HSM이 애플리케이션을 인증해야 합니다. HSM은 명시적 로그인 또는 암시적 로그인 메서드를 사용하여 인증한다.
**명시적 로그인** - 이 메서드를 사용하면 애플리케이션에서 직접 AWS CloudHSM 자격 증명을 제공할 수 있습니다. [https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html](https://docs.oracle.com/javase/8/docs/api/java/security/AuthProvider.html)의 메서드를 사용하며, 여기서 CU 사용자 이름과 비밀번호를 핀 패턴으로 전달합니다. 자세한 내용은 [HSM 코드 예로 로그인](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java)을 참조하십시오.
**암시적 로그인** - 이 메서드를 사용하면 새 속성 파일, 시스템 속성 또는 환경 변수로 AWS CloudHSM 자격 증명을 설정할 수 있습니다.
+ **시스템 속성** – 애플리케이션을 실행할 때 시스템 속성을 통해 자격 증명을 설정합니다. 다음 예제와 같이 이 작업을 두 가지 방법으로 수행할 수 있습니다.
------
#### [ 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","");
```
------
+ **환경 변수** – 자격 증명을 환경 변수로 설정합니다.
**참고**
환경 변수를 설정할 때는 쉘에서 해석할 수 있는 특수 문자를 이스케이프 처리해야 합니다.
------
#### [ 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 키를 생성합니다. |
| 트리플 DES(3DES, DESede) | 192비트 트리플 DES 키를 생성합니다[*](#java-lib-keys_5-note-1). |
| EC | EC 키 쌍 생성하기 — NIST curves secp224r1 (P-224), secp256r1 (P-256), secp256k1 (블록체인), secp384r1 (P-384) 및 secp521r1 (P-521). |
| GENERIC\$1SECRET | 1\$1800바이트의 일반 보안을 생성합니다. |
| HMAC | SHA1, SHA224, SHA256, SHA384, SHA512에 대한 해시 지원. |
| RSA | 2048비트\$14096비트의 RSA 키를 생성합니다(256비트 증가). |
\$1 NIST 지침에 따라 2023년 이후 FIPS 모드의 클러스터에는 허용되지 않습니다. 비FIPS 모드의 클러스터의 경우 2023년 이후에도 허용됩니다. 세부 정보는 [FIPS 140 규정 준수: 2024 메커니즘 지원 중단](compliance-dep-notif.md#compliance-dep-notif-1) 섹션을 참조하세요.
# AWS CloudHSM 클라이언트 SDK 5용 JCE 공급자의 키 관리 기본 사항
JCE 공급자의 키 관리에 대한 기본 사항은 키 가져오기, 키 내보내기, 핸들별 키 로드 또는 키 삭제를 포함합니다. 키 관리에 대한 자세한 내용은 [Manage keys](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java) 코드 예제를 참조하십시오.
또한 [코드 샘플](java-samples.md)에서 JCE 제공자 코드 예시를 더 확인할 수 있습니다.
# 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)
+ [해시 기반 메시지 인증 코드(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 소프트웨어 라이브러리는 다음 알고리즘, 모드 및 패딩 조합을 지원합니다.
| Algorithm | Mode | 패딩 | 참고 |
| --- | --- | --- | --- |
| 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)를 무시하고 HSM이 생성하는 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 소프트웨어 라이브러리는 다음 메시지 다이제스트를 지원합니다. Client SDK 5를 사용하면 데이터가 소프트웨어에서 로컬로 해시됩니다. 즉, SDK로 해시할 수 있는 데이터 크기에는 제한이 없습니다.
+ `SHA-1`
+ `SHA-224`
+ `SHA-256`
+ `SHA-384`
+ `SHA-512`
## 해시 기반 메시지 인증 코드(HMAC) 함수
Java용 AWS CloudHSM 소프트웨어 라이브러리는 다음 HMAC 알고리즘을 지원합니다.
+ `HmacSHA1`(최대 데이터 크기(바이트): 16288)
+ `HmacSHA224`(최대 데이터 크기(바이트): 16256)
+ `HmacSHA256`(최대 데이터 크기(바이트): 16288)
+ `HmacSHA384`(최대 데이터 크기(바이트): 16224)
+ `HmacSHA512`(최대 데이터 크기(바이트): 16224)
## 암호 기반 메시지 인증 코드(CMAC) 함수
CMAC(암호 기반 메시지 인증 코드) 는 블록 암호와 비밀 키를 사용하여 메시지 인증 코드(MAC) 를 생성합니다. MAC에서는 해싱 방법이 아닌 블록 대칭 키 방법을 사용한다는 점에서 HMAC과 다릅니다.
Java용 AWS CloudHSM 소프트웨어 라이브러리는 다음 CMAC 알고리즘을 지원합니다.
+ `AESCMAC`
## 키 계약 함수
Java용 AWS CloudHSM 소프트웨어 라이브러리는 키 파생 함수(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를 위한 두 가지 유형의 키 팩토리가 있습니다.
**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:** 비대칭 키를 가져오는 데 사용됩니다. KeyFactory를 사용하면 지원되는 키 또는 지원되는 KeySpec을 전달하여 AWS CloudHSM에 비대칭 키를 가져올 수 있습니다. 자세한 정보는 다음 리소스를 참조하세요.
+ KeyFactory의 `generatePublic` 메서드에는 다음과 같은 [KeySpec](https://docs.oracle.com/javase/8/docs/api/java/security/spec/KeySpec.html) 클래스가 지원됩니다.
+ 다음을 포함하여 RSA 및 EC KeyType 모두에 대한 CloudHSM KeyAttributesMap입니다.
+ RSA 및 EC 퍼블릭 KeyType 모두에 대한 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 KeyType 모두에 대한 CloudHSM KeyAttributesMap입니다.
+ RSA 및 EC 퍼블릭 KeyType 모두에 대한 CloudHSM KeyAttributesMap입니다. 예제는 [여기](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java)에서 확인할 수 있습니다.
+ EC 및 RSA 프라이빗 키 모두에 대한 [PKCS8로 인코딩된 키 사양](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 개정 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 | | | | 키 크기를 정의하는 속성입니다. 지원되는 키 크기에 대한 자세한 내용은 [Client 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 Map 조작에 사용되는 메서드와 비슷합니다.
속성에 대한 사용자 지정 값을 설정하기 위해 다음 두 가지 옵션이 제공됩니다.
+ 다음 표에 나열된 메서드 사용
+ 이 문서 뒷부분에 설명된 빌더 패턴 사용
속성 맵 객체는 속성을 설정하기 위한 다음과 같은 메서드를 지원합니다:
****
| 연산 | 반환 값 | `KeyAttributesMap` 메서드 |
| --- | --- | --- |
| 기존 키에 대한 키 속성 값 가져오기 | 객체(값 포함) 또는 null | **get**(keyAttribute) |
| 키 속성 하나의 값 채우기 | 키 속성과 연결된 이전 값 또는 키 속성에 대한 매핑이 없는 경우에는 null | **put**(keyAttribute, 값) |
| 여러 키 속성에 대한 값 채우기 | 해당 사항 없음 | **putAll**(keyAttributesMap) |
| 속성 맵에서 키-값 페어 제거 | 키 속성과 연결된 이전 값 또는 키 속성에 대한 매핑이 없는 경우에는 *null* | **remove**(keyAttribute) |
**참고**
명시적으로 지정하지 않은 속성은 [지원되는 속성](#java-attributes_5)의 이전 표에 나열된 기본값으로 설정됩니다.
### 키 페어에 대한 속성 설정
Java 클래스 `KeyPairAttributesMap`을 사용하여 키 페어에 대한 키 속성을 처리합니다. `KeyPairAttributesMap`은 두 개의 `KeyAttributesMap` 객체를 캡슐화합니다. 하나는 퍼블릭 키용이고 다른 하나는 개인 키용입니다.
퍼블릭 키와 개인 키에 대해 별도로 개별 속성을 설정하려면 키의 해당하는 `KeyAttributes` 맵 객체에 `put()` 메서드를 사용하면 됩니다. `getPublic()` 메서드를 사용하여 공개 키에 대한 속성 맵을 검색하고 `getPrivate()`을 사용하여 개인 키에 대한 속성 맵을 검색합니다. 키 페어 속성 맵에 `putAll()`을 인수로 사용하여 퍼블릭 및 개인 키 페어에 대한 여러 키 속성 값을 함께 채웁니다.
# Java for Client SDK 5용 AWS CloudHSM 소프트웨어 라이브러리의 코드 샘플
이 주제에서는 AWS CloudHSM 클라이언트 SDK 5용 Java 코드 샘플에 대한 리소스와 정보를 제공합니다.
## 사전 조건
샘플을 실행하기 전에 사용자 환경을 설정해야 합니다.
+ [Java 암호화 확장(Java Cryptographic Extension) 공급자](java-library-install_5.md#install-java-library_5)를 설치하고 구성합니다.
+ 유효한 [HSM 사용자 이름과 암호](manage-hsm-users.md)를 설정합니다. 이러한 작업을 수행하기 위해서는 CU(Cryptographic User) 권한이면 충분합니다. 각 예제에서 애플리케이션은 이러한 자격 증명을 사용하여 HSM에 로그인합니다.
+ [JCE 공급자](java-library-install_5.md#java-library-credentials_5)에게 자격 증명을 제공하는 방법을 결정하십시오.
## 코드 샘플
다음 코드 샘플은 [AWS CloudHSM JCE 공급자](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)
+ [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) 참고 참조)
+ [RSA 키로 서명 및 확인](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/RSAOperationsRunner.java)
+ [EC 키를 사용한 서명 및 확인](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 최신 클라이언트 SDK 릴리스](latest-releases.md) 섹션을 AWS CloudHSM참조하세요.
Javadocs를 통합 개발 환경(IDE)으로 가져오거나 웹 브라우저에서 볼 수 있습니다.
# 클라이언트 SDK 5용AWS CloudHSM KeyStore Java 클래스
클래스는 AWS CloudHSM `KeyStore` 특수 목적의 PKCS12 키 스토어를 제공합니다. 이 키 스토어는 키 데이터와 함께 인증서를 저장하고 AWS CloudHSM에 저장된 키 데이터와 상호 연관시킬 수 있습니다. `KeyStore` 클래스는 AWS CloudHSM Java 암호화 확장(JCE)의 `KeyStore` 서비스 공급자 인터페이스(SPI)를 구현합니다. `KeyStore` 사용에 대한 자세한 내용은 [Class KeyStore](https://devdocs.io/openjdk~8/java/security/keystore)를 참조하십시오.
**참고**
인증서는 퍼블릭 정보이므로 암호화 키의 스토리지 용량을 최대화하기 위해 AWS CloudHSM 는 HSMs에 인증서 저장을 지원하지 않습니다.
## AWS CloudHSM 클라이언트 SDK 5에 적합한 키 스토어 선택
AWS CloudHSM Java 암호화 확장(JCE) 공급자는 특수 용도의 AWS CloudHSM KeyStore를 제공합니다. 클래스는 AWS CloudHSM `KeyStore` HSM으로 키 작업 오프로드, 인증서의 로컬 스토리지 및 인증서 기반 작업을 지원합니다.
다음과 같이 특수 용도의 CloudHSM KeyStore를 로드합니다.
```
KeyStore ks = KeyStore.getInstance("CloudHSM")
```
## AWS CloudHSM KeyStore 클라이언트 SDK 5 초기화
JCE 공급자에 로그인하는 것과 동일한 방식으로 AWS CloudHSM KeyStore에 로그인합니다. 환경 변수 또는 시스템 속성 파일을 사용할 수 있으며 CloudHSM KeyStore의 사용을 시작하기 전에 로그인해야 합니다. JCE 공급자를 사용하여 HSM에 로그인하는 예는 [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 [클래스 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`
키 스토어가 지정된 별칭이 있는 객체에 최소 하나 이상 액세스할 수 있는 경우 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` 호출을 사용하여 설정됨)를 유지합니다.
# 클라이언트 SDK 5용 AWS CloudHSM JCE의 고급 구성
AWS CloudHSM JCE 공급자에는 대부분의 고객이 활용하는 일반 구성의 일부가 아닌 다음과 같은 고급 구성이 포함되어 있습니다.
+ [여러 클러스터에 연결](java-lib-configs-multi.md)
+ [JCE를 사용한 키 추출](java-lib-configs-getencoded.md)
+ [JCE 구성 재시도](java-lib-configs-retry.md)
# JCE 공급자를 사용하여 여러 AWS CloudHSM 클러스터에 연결
이 구성을 사용하면 단일 클라이언트 인스턴스가 여러 AWS CloudHSM 클러스터와 통신할 수 있습니다. 단일 인스턴스가 단일 클러스터와만 통신하는 것과 비교하면 일부 사용 사례에서는 이 기능을 통해 비용을 절감할 수 있습니다. `CloudHsmProvider` 클래스는 Java Security의 공급자 클래스를 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 Security 공급자 목록에 추가하면 표준 JCE 클래스를 사용하여 이 클래스와 상호 작용할 수 있습니다.
다음 예제는 이 클래스를 인스턴스화하여 Java Security 공급자 목록에 추가합니다.
```
if (Security.getProvider(CloudHsmProvider.PROVIDER_NAME) == null) {
Security.addProvider(new CloudHsmProvider());
}
```
`CloudHsmProvider` 다음 두 가지 방법으로 구성할 수 있습니다:
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와 상호 작용하여 다양한 작업에 사용할 공급자를 알려주는 데 유용합니다. 암호화 작업에 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` 클러스터와 통신하려는 경우 다른 클러스터의 구성을 사용하여 다른 객체를 생성하고 다음 예와 같이 공급자 객체 또는 공급자 이름을 사용하여 이 다른 클러스터와 상호 작용할 수 있습니다.
**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);
```
또한 동일한 애플리케이션에서 공급자 이름을 사용하여 두 번째 클러스터에서 “AES” 키 생성을 수행하는 경우 다음 샘플을 사용할 수도 있습니다.
```
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", provider2.getName());
```
# 용 JCE를 사용한 키 추출 AWS CloudHSM
Java Cryptography Extension(JCE)은 다양한 암호화 구현을 연결할 수 있는 아키텍처를 사용합니다.는 암호화 작업을 HSM으로 오프로드하는 JCE 공급자를 AWS CloudHSM 제공합니다. 대부분의 다른 JCE 공급자가 AWS CloudHSM에 저장된 키를 사용하려면 HSM에서 일반 텍스트 형식의 키 바이트를 추출하여 시스템 메모리로 사용해야 합니다. HSM은 일반적으로 키를 래핑된 객체로만 추출하고 일반 텍스트로는 추출할 수 없습니다. 그러나 공급자 간 통합 사용 사례를 지원하기 위해는 옵트인 구성 옵션을 AWS CloudHSM 허용하여 일반에서 키 바이트를 추출할 수 있습니다.
**중요**
JCE는 AWS CloudHSM 공급자가 지정되거나 AWS CloudHSM 키 객체가 사용될 AWS CloudHSM 때마다 작업을 로 오프로드합니다. 작업이 HSM 내에서 수행될 것으로 예상되는 경우 키를 명확하게 추출할 필요가 없습니다. 일반 텍스트로 키를 추출하는 것은 타사 라이브러리 또는 JCE 공급자의 제한으로 인해 애플리케이션에서 키 래핑 및 래핑 해제와 같은 보안 메커니즘을 사용할 수 없는 경우에만 필요합니다.
AWS CloudHSM JCE 공급자를 사용하면 기본적으로 외부 JCE 공급자와 함께 작동하도록 **퍼블릭 키를** 추출할 수 있습니다. 항상 허용되는 방법은 다음과 같습니다.
| Class | 메서드 | 형식(getEncoded) |
| --- | --- | --- |
| EcPublicKey | getEncoded() | X.509 |
| | GetW () | 해당 사항 없음 |
| RSA 퍼블릭 키 | getEncoded() | X.509 |
| | getPublicExponent() | 해당 사항 없음 |
| CloudHsmRsaPrivateCrtKey | getPublicExponent() | 해당 사항 없음 |
AWS CloudHSM JCE 공급자는 기본적으로 **프라이빗** 또는 **보안** 키에 대해 키 바이트의 추출을 허용하지 않습니다. 사용 사례에 필요한 경우 다음과 같은 조건에서 **프라이빗** 또는 **비밀** 키에 대해 키 바이트를 선명하게 추출할 수 있습니다.
1. 프라이빗 및 비밀 키의 `EXTRACTABLE` 속성은 **true**로 설정됩니다.
+ 기본적으로 프라이빗 및 비밀 키의 `EXTRACTABLE` 속성은 **true로** 설정됩니다. `EXTRACTABLE`키는 HSM에서 내보낼 수 있는 키입니다. 지원되는 Java 속성에 대한 자세한 내용은 [Client SDK 5](java-lib-attributes_5.md)를 참조하십시오.
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/ko_kr/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회까지 재시도하고 기하급수적으로 백오프합니다. 이 자동 재시도 전략은 **끄기 모드**와 **표준 모드** 중 하나로 설정할 수 있습니다.
+ **끄기 모드**: Client SDK는 HSM에서 병목 현상이 발생한 작업에 대해 재시도 전략을 수행하지 않습니다.
+ **표준 모드**: Client SDK 5.8.0 이상의 기본 모드입니다. 이 모드에서는 Client SDK가 기하급수적으로 백오프를 수행하여 병목 현상이 발생한 작업을 자동으로 재시도합니다.
자세한 내용은 [HSM 스로틀링](troubleshoot-hsm-throttling.md) 단원을 참조하십시오.
## 재시도 명령을 끄기 모드로 설정합니다.
------
#### [ Linux ]
**Linux용 Client SDK 5의 재시도 명령을 **off**로 설정하려면**
+ 다음 명령을 사용하여 재시도 구성을 **off** 모드로 설정할 수 있습니다.
```
$ sudo /opt/cloudhsm/bin/configure-jce --default-retry-mode off
```
------
#### [ Windows ]
**Client SDK 5 on Windows에 대한 재시도 명령을 **off**로 설정하려면**
+ 다음 명령을 사용하여 재시도 구성을 **off** 모드로 설정할 수 있습니다.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe" --default-retry-mode off
```
------