기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # JCE 공급자를 AWS CloudHSM 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션 이 주제를 사용하여 [JCE 공급자](java-library.md)를 AWS CloudHSM 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션합니다. 마이그레이션의 이점은 [AWS CloudHSM 클라이언트 SDK 5의 이점](client-sdk-5-benefits.md) 섹션을 참조하세요. 에서 AWS CloudHSM고객 애플리케이션은 AWS CloudHSM 클라이언트 소프트웨어 개발 키트(SDK)를 사용하여 암호화 작업을 수행합니다. 클라이언트 SDK 5는 새로운 기능과 플랫폼 지원이 지속적으로 추가되는 기본 SDK입니다. 클라이언트 SDK 3 JCE 공급자는 표준 JCE 사양에 포함되지 않은 사용자 지정 클래스 및 API를 사용합니다. JCE 공급자용 클라이언트 SDK 5는 JCE 사양을 준수하며 특정 영역에서는 클라이언트 SDK 3과 역호환되지 않습니다. 고객 애플리케이션은 클라이언트 SDK 5로의 마이그레이션의 일환으로 변경이 필요할 수 있습니다. 이 섹션에서는 성공적인 마이그레이션에 필요한 변경 사항을 간략하게 설명합니다. 모든 공급자에 대한 마이그레이션 지침을 검토하려면 [AWS CloudHSM 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션](client-sdk-migration.md) 섹션을 참조하세요. **Topics** + [변경 사항을 해결하여 준비](#jce-migration-preparation-sdk5) + [클라이언트 SDK 5로 마이그레이션](#w2aac25c19c21c15) + [관련 주제](#java-lib-migrate_to_sdk5-seealso) ## 변경 사항을 해결하여 준비 이러한 중단된 변경 사항을 검토하고 그에 따라 개발 환경에서 애플리케이션을 업데이트합니다. ### 공급자 클래스 및 이름 변경됨 **** | 변경된 사항 | 클라이언트 SDK 3에서의 내용 | 클라이언트 SDK 5에서의 내용 | 예제 | | --- | --- | --- | --- | | 공급자 클래스 및 이름 | 클라이언트 SDK 3의 JCE 공급자 클래스는 `CaviumProvider`라고 불리며 공급자 이름은 `Cavium`입니다. | 클라이언트 SDK 5에서 공급자 클래스는 `CloudHsmProvider`라고 하며 공급자 이름은 `CloudHSM`입니다. | `CloudHsmProvider` 객체를 초기화하는 방법의 예는 [AWS CloudHSM GitHub 샘플 리포지토리](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50)에서 확인할 수 있습니다. | ### 명시적 로그인 변경됨, 암시적 로그인 변경되지 않음 **** | 변경된 사항 | 클라이언트 SDK 3에서의 내용 | 클라이언트 SDK 5에서의 내용 | 예제 | | --- | --- | --- | --- | | 명시적 로그인 | 클라이언트 SDK 3은 명시적 로그인에 `LoginManager` 클래스를 사용합니다[1](#explicit_login_sdk3_note). | 클라이언트 SDK 5에서 `CloudHSM` 공급자는 명시적 로그인을 위해 `AuthProvider`를 구현합니다. `AuthProvider`는 표준 Java 클래스이며 공급자에 로그인하는 Java의 관용적인 방법을 따릅니다. 클라이언트 SDK 5의 로그인 상태 관리가 개선되면 애플리케이션이 재연결 중에 더 이상 로그인을 모니터링하고 수행할 필요가 없습니다[2](#explicit_login_sdk5_note). | 클라이언트 SDK 5에서 명시적 로그인을 사용하는 방법에 대한 예는 [AWS CloudHSM GitHub 샘플 리포지토리](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141)의 LoginRunner 샘플을 참조하세요. | | 암시적 로그인 | 암시적 로그인에는 변경이 필요하지 않습니다. 동일한 속성 파일과 모든 환경 변수는 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션할 때 암시적 로그인에 계속 작동합니다. | 클라이언트 SDK 5에서 암시적 로그인을 사용하는 방법에 대한 예는 AWS CloudHSM GitHub [샘플 리포지토리의 LoginRunner ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202) 샘플을 참조하세요. | + [1] 클라이언트 SDK 3 코드 조각은 다음과 같습니다. ``` LoginManager lm = LoginManager.getInstance(); lm.login(partition, user, pass); ``` + [2] 클라이언트 SDK 5 코드 조각은 다음과 같습니다. ``` // Construct or get the existing provider object AuthProvider provider = new CloudHsmProvider(); // Call login method on the CloudHsmProvider object // Here loginHandler is a CallbackHandler provider.login(null, loginHandler); ``` 클라이언트 SDK 5에서 명시적 로그인을 사용하는 방법에 대한 예는 AWS CloudHSM GitHub [샘플 리포지토리의 LoginRunner ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) 샘플을 참조하세요. ### 키 생성 변경됨 **** | 변경된 사항 | 클라이언트 SDK 3에서의 내용 | 클라이언트 SDK 5에서의 내용 | 예제 | | --- | --- | --- | --- | | 키 생성 | 클라이언트 SDK 3에서 `Cavium[Key-type]AlgorithmParameterSpec`은 키 생성 파라미터를 지정하는 데 사용됩니다. 코드 조각은 각주 [1](#key_generation_sdk3_note)를 참조하세요. | 클라이언트 SDK 5에서 `KeyAttributesMap`은 키 생성 속성을 지정하는 데 사용됩니다. 코드 조각은 각주 [2](#key_generation_sdk5_note)를 참조하세요. | `KeyAttributesMap`를 사용하여 대칭 키를 생성하는 방법에 대한 예는 AWS CloudHSM Github 샘플 리포지토리의 [SymmetricKeys 샘플](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java)을 참조하세요. | | 키 페어 생성 | 클라이언트 SDK 3에서 `Cavium[Key-type]AlgorithmparameterSpec`은 키 페어 생성 파라미터를 지정하는 데 사용됩니다. 코드 조각은 각주 [3](#key_pair_generation_sdk3_note)를 참조하세요. | 클라이언트 SDK 5에서 `KeyPairAttributesMap`은 이러한 파라미터를 지정하는 데 사용됩니다. 코드 조각은 각주 [4](#key_pair_generation_sdk5_note)를 참조하세요. | 를 사용하여 비대칭 키를 `KeyAttributesMap` 생성하는 방법에 대한 예는 AWS CloudHSM GitHub [샘플 리포지토리의 AsymmetricKeys ](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java) 샘플을 참조하세요. | + [1] 클라이언트 SDK 3 키 생성 코드 조각은 다음과 같습니다. ``` KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium"); CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec( keySizeInBits, keyLabel, isExtractable, isPersistent); keyGen.init(aesSpec); SecretKey aesKey = keyGen.generateKey(); ``` + [2] 클라이언트 SDK 5 키 생성 코드 조각은 다음과 같습니다. ``` KeyGenerator keyGen = KeyGenerator.getInstance("AES", CloudHsmProvider.PROVIDER_NAME); final KeyAttributesMap aesSpec = new KeyAttributesMap(); aesSpec.put(KeyAttribute.LABEL, keyLabel); aesSpec.put(KeyAttribute.SIZE, keySizeInBits); aesSpec.put(KeyAttribute.EXTRACTABLE, isExtractable); aesSpec.put(KeyAttribute.TOKEN, isPersistent); keyGen.init(aesSpec); SecretKey aesKey = keyGen.generateKey(); ``` + [3] 클라이언트 SDK 3 키 페어 생성 코드 조각은 다음과 같습니다. ``` KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("rsa", "Cavium"); CaviumRSAKeyGenParameterSpec spec = new CaviumRSAKeyGenParameterSpec( keySizeInBits, new BigInteger("65537"), label + ":public", label + ":private", isExtractable, isPersistent); keyPairGen.initialize(spec); keyPairGen.generateKeyPair(); ``` + [4] 클라이언트 SDK 5 키 페어 생성 코드 조각은 다음과 같습니다. ``` KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("RSA", providerName); // Set attributes for RSA public key final KeyAttributesMap publicKeyAttrsMap = new KeyAttributesMap(); publicKeyAttrsMap.putAll(additionalPublicKeyAttributes); publicKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Public"); publicKeyAttrsMap.put(KeyAttribute.MODULUS_BITS, keySizeInBits); publicKeyAttrsMap.put(KeyAttribute.PUBLIC_EXPONENT, new BigInteger("65537").toByteArray()); // Set attributes for RSA private key final KeyAttributesMap privateKeyAttrsMap = new KeyAttributesMap(); privateKeyAttrsMap.putAll(additionalPrivateKeyAttributes); privateKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Private"); // Create KeyPairAttributesMap and use that to initialize the // keyPair generator KeyPairAttributesMap keyPairSpec = new KeyPairAttributesMapBuilder() .withPublic(publicKeyAttrsMap) .withPrivate(privateKeyAttrsMap) .build(); keyPairGen.initialize(keyPairSpec); keyPairGen.generateKeyPair(); ``` ### 키 찾기, 삭제 및 참조 변경됨 에서 이미 생성된 키를 찾으려면 KeyStore를 AWS CloudHSM 사용합니다. 클라이언트 SDK 3에는 `Cavium` 및 `CloudHSM`, 두 가지 KeyStore 유형이 있습니다. 클라이언트 SDK 5에는 `CloudHSM`, 한 가지 KeyStore 유형만 있습니다. `Cavium` KeyStore에서 `CloudHSM` KeyStore로 이동하려면 KeyStore 유형을 변경해야 합니다. 또한 클라이언트 SDK 3는 키 핸들을 사용하여 키를 참조하는 반면 클라이언트 SDK 5는 키 레이블을 사용합니다. 결과 동작 변경 사항은 다음과 같습니다. | 변경된 사항 | 클라이언트 SDK 3에서의 내용 | 클라이언트 SDK 5에서의 내용 | 예제 | | --- | --- | --- | --- | | 키 참조 | 클라이언트 SDK 3를 사용하면 애플리케이션이 키 레이블 또는 키 핸들을 사용하여 HSM에서 키를 참조합니다. KeyStore에서 레이블을 사용하여 키를 찾거나 핸들을 사용하여 `CaviumKey` 객체를 생성합니다. | 클라이언트 SDK 5에서 애플리케이션은 [클라이언트 SDK 5용AWS CloudHSM KeyStore Java 클래스](alternative-keystore_5.md)를 사용하여 레이블별로 키를 찾을 수 있습니다. 핸들별로 키를 찾으려면를 AWS CloudHSM `KeyStoreWithAttributes`와 함께 사용합니다 AWS CloudHSM `KeyReferenceSpec`. | | | 여러 항목 찾기 | `Cavium` KeyStore에 동일한 기준을 가진 여러 항목이 있는 시나리오에서 `getEntry`, `getKey` 또는 `getCertificate`를 사용하여 키를 검색하면 발견된 첫 번째 항목만 반환됩니다. | 및를 AWS CloudHSM `KeyStore` 사용하면 `KeyStoreWithAttributes`동일한 시나리오에서 예외가 발생합니다. 이 문제를 해결하려면 CloudHSM CLI에서 [CloudHSM CLI를 사용하여 키 속성 설정](cloudhsm_cli-key-set-attribute.md) 명령을 사용하여 키에 고유한 레이블을 설정하는 것이 좋습니다. 또는 `KeyStoreWithAttributes#getKeys`를 사용하여 기준과 일치하는 모든 키를 반환합니다. | | | 모든 키 찾기 | 클라이언트 SDK 3에서는 `Util.findAllKeys()`를 사용하여 HSM의 모든 키를 찾을 수 있습니다. | 클라이언트 SDK 5를 사용하면 `KeyStoreWithAttributes` 클래스를 사용하여 키를 더 간단하고 효율적으로 찾을 수 있습니다. 가능하면 키를 캐시하여 지연 시간을 최소화합니다. 자세한 내용은 [애플리케이션의 키를 효과적으로 관리](bp-application-integration.md#bp-manage-application) 단원을 참조하십시오. HSM에서 모든 키를 검색해야 하는 경우 를 빈 `KeyAttributesMap`과 함께 `KeyStoreWithAttributes#getKeys`를 사용합니다. | `KeyStoreWithAttributes` 클래스를 사용하여 키를 찾는 예제는 [AWS CloudHSM GitHub sample repository](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223)에서 사용할 수 있으며 코드 조각은 [1](#using_keystore_att_note)에 나와 있습니다. | | 키 삭제 | 클라이언트 SDK 3는 `Util.deleteKey()`를 사용하여 키를 삭제합니다. | 클라이언트 SDK 5의 `Key` 객체는 이 `Destroyable` 인터페이스의 `destroy()` 메서드를 사용하여 키를 삭제할 수 있는 인터페이스를 구현합니다. | 삭제 키 기능을 보여주는 예제 코드는 [CloudHSM GitHub sample repository](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234)에서 찾을 수 있습니다. 각 SDK에 대한 샘플 조각은 [2](#delete_key_note)에 나와 있습니다. | + [1] 조각은 다음과 같습니다. ``` KeyAttributesMap findSpec = new KeyAttributesMap(); findSpec.put(KeyAttribute.LABEL, label); findSpec.put(KeyAttribute.KEY_TYPE, keyType); KeyStoreWithAttributes keyStore = KeyStoreWithAttributes.getInstance("CloudHSM"); keyStore.load(null, null); keyStore.getKey(findSpec); ``` + [2] 클라이언트 SDK 3에서 키 삭제는 다음과 같습니다. ``` Util.deleteKey(key); ``` 클라이언트 SDK 5에서 키 삭제: ``` ((Destroyable) key).destroy(); ``` ### 암호화 래핑 해제 작업 변경됨, 다른 암호화 작업 변경되지 않음 **참고** 암호화/복호화/래핑 작업에는 변경이 필요하지 않습니다. 래핑 해제 작업을 수행하려면 클라이언트 SDK 3 `CaviumUnwrapParameterSpec` 클래스를 나열된 암호화 작업과 관련된 다음 클래스 중 하나로 교체해야 합니다. + `AES/GCM/NoPadding` 래핑 해제의 `GCMUnwrapKeySpec` + `AESWrap unwrap` 및 `AES/CBC/NoPadding unwrap`의 `IvUnwrapKeySpec` + `RSA OAEP unwrap`용 `OAEPUnwrapKeySpec` `OAEPUnwrapkeySpec`에 대한 코드 조각 예: ``` OAEPParameterSpec oaepParameterSpec = new OAEPParameterSpec( "SHA-256", "MGF1", MGF1ParameterSpec.SHA256, PSpecified.DEFAULT); KeyAttributesMap keyAttributesMap = new KeyAttributesMap(KeyAttributePermissiveProfile.KEY_CREATION); keyAttributesMap.put(KeyAttribute.TOKEN, true); keyAttributesMap.put(KeyAttribute.EXTRACTABLE, false); OAEPUnwrapKeySpec spec = new OAEPUnwrapKeySpec(oaepParameterSpec, keyAttributesMap); Cipher hsmCipher = Cipher.getInstance( "RSA/ECB/OAEPPadding", CloudHsmProvider.PROVIDER_NAME); hsmCipher.init(Cipher.UNWRAP_MODE, key, spec); ``` ### 서명 작업 변경되지 않음 서명 작업에는 변경이 필요하지 않습니다. ## 클라이언트 SDK 5로 마이그레이션 이 섹션의 지침에 따라 클라이언트 SDK 3에서 클라이언트 SDK 5로 마이그레이션합니다. **참고** Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8 및 RHEL 6은 현재 클라이언트 SDK 5에서 지원되지 않습니다. 현재 클라이언트 SDK 3에서 이러한 플랫폼 중 하나를 사용하는 경우 클라이언트 SDK 5로 마이그레이션할 때 다른 플랫폼을 선택해야 합니다. 1. 클라이언트 SDK 3용 JCE 공급자를 제거합니다. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ 1. 클라이언트 SDK 3용 클라이언트 대몬을 중지합니다. ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ 1. 클라이언트 SDK 3용 클라이언트 대몬을 제거합니다. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ **참고** 사용자 지정 구성을 다시 활성화해야 합니다. 1. [AWS CloudHSM 클라이언트 SDK 5용 JCE 공급자 설치](java-library-install_5.md)의 단계에 따라 클라이언트 SDK JCE 공급자를 설치합니다. 1. 클라이언트 SDK 5에는 새로운 구성 파일 형식과 명령줄 부트스트랩 도구가 도입되었습니다. 클라이언트 SDK 5 JCE 공급자를 부트스트랩하려면 [클라이언트 SDK 부트스트랩](cluster-connect.md#connect-how-to)의 사용 설명서에 나열된 지침을 따릅니다. 1. 개발 환경에서 애플리케이션을 테스트합니다. 기존 코드를 업데이트하여 최종 마이그레이션 전에 중단되는 변경 사항을 해결합니다. ## 관련 주제 + [의 모범 사례 AWS CloudHSM](best-practices.md)