unWrapKey

key_mgmt_util 도구의 unWrapKey 명령은 래핑(암호화)된 대칭 또는 프라이빗 키를 파일에서 HSM으로 가져옵니다. key_mgmt_util의 WrapKey 명령으로 래핑된 암호화된 키를 가져오도록 설계되었지만 다른 도구로 래핑된 키를 언래핑하는 데에도 사용할 수 있습니다. 하지만 이런 상황에서는 PKCS#11 또는 JCE 소프트웨어 라이브러리를 사용하여 키를 언래핑하는 것이 좋습니다.

가져온 AWS CloudHSM키는 에서 생성한 키와 동일하게 작동합니다. 하지만 OBJ_ATTR_LOCAL 속성 값은 0입니다. 이는 객체가 로컬에서 생성되지 않았음을 의미합니다.

키를 가져온 후 키 파일을 마킹 또는 삭제해야 합니다. 이 명령은 동일한 키 자료를 여러 번 가져오도록 허용합니다. 여러 개의 키가 고유한 키 핸들이고 동일한 키 자료라는 결과는 키 자료의 사용을 추적하기 어렵게 하고 암호화 한도를 초과하는 것을 방지합니다.

key_mgmt_util 명령을 실행하려면 먼저 key_mgmt_util을 시작하고 HSM에 암호화 사용자(crypto user)로 로그인해야 합니다.

구문


unWrapKey -h

unWrapKey -f <key-file-name> 
          -w <wrapping-key-handle> 
          [-sess]
          [-min_srv <minimum-number-of-HSMs>]          
          [-timeout <number-of-seconds>]
          [-aad <additional authenticated data filename>]
          [-tag_size <tag size>]
          [-iv_file <IV file>]
          [-attest]
          [-m <wrapping-mechanism>]
          [-t <hash-type>]
          [-nex]
          [-u <user id list>]
          [-m_value <number of users needed for approval>]
          [-noheader]
          [-l <key-label>]
          [-id <key-id>]
          [-kt <key-type>]
          [-kc <key-class]
          [-i <unwrapping-IV>]

예

이 예제에서는 unWrapKey를 사용하여 파일에서 HSM으로 래핑된 키를 가져오는 방법을 보여줍니다. 첫 번째 예시에서는 wrapKey key_mgmt_util 명령으로 래핑되어 헤더가 있는 키를 언래핑합니다. 두 번째 예시에서는 key_mgmt_util 외부에서 래핑되어 헤더가 없는 키를 언래핑합니다.

예 : 키 언래핑하기(헤더 있음)

이 명령은 3DES 대칭 키의 래핑된 복사본을 HSM으로 가져옵니다. 키는 레이블이 6인 AES 키로 언래핑됩니다. 3DES 키를 래핑하는 데 사용한 것과 암호화 방식에 있어 동일합니다. 출력은 파일의 키를 언래핑하고 가져왔으며 가져온 키의 핸들이 29임을 보여줍니다.


        Command:  unWrapKey -f 3DES.key -w 6 -m 4

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Key Unwrapped.  Key Handle: 29

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

예 : 키 언래핑하기(헤더 없음)

이 명령은 3DES 대칭 키의 래핑된 복사본을 HSM으로 가져옵니다. 키는 레이블이 6인 AES 키로 언래핑됩니다. 3DES 키를 래핑하는 데 사용한 것과 암호화 방식에 있어 동일합니다. 이 3DES 키는 key_mgmt_util로 래핑되지 않았으므로 함께 제공되는 필수 파라미터인 키 레이블(unwrapped3DES), 키 클래스(4) 및 키 유형(21)과 함께 noheader 파라미터가 지정됩니다. 출력은 파일의 키를 언래핑하고 가져왔으며 가져온 키의 핸들이 8임을 보여줍니다.


Command: unWrapKey -f 3DES.key -w 6 -noheader -l unwrapped3DES -kc 4 -kt 21 -m 4
      
      Cfm3CreateUnwrapTemplate2 returned: 0x00 : HSM Return: SUCCESS
       Cfm2UnWrapWithTemplate3 returned: 0x00 : HSM Return: SUCCESS

       Key Unwrapped. Key Handle: 8

       Cluster Error Status
       Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
       Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

파라미터

-h

명령에 대한 도움말을 표시합니다.

필수 여부: 예

-f

래핑된 키를 포함하는 파일의 경로 및 이름입니다.

필수 여부: 예

-w

래핑 키를 지정합니다. HSM에서 AES 키 또는 RSA 키의 키 핸들을 입력합니다. 이 파라미터는 필수 사항입니다. 키 핸들을 찾으려면 findKey 명령을 사용하십시오.

래핑 키를 생성하려면 AES 키 (유형 31) 를 생성하거나 KeyPairGenRSA를 사용하여 genSymKeyRSA 키 쌍 (유형 0) 을 생성합니다. RSA 키 페어를 사용하는 경우 키 중 하나로 키를 래핑하고 다른 키로 언래핑해야 합니다. 키를 래핑 키로 사용할 수 있는지 확인하려면 getAttribute를 사용하여 262라는 상수로 표시되는 OBJ_ATTR_WRAP 속성의 값을 가져옵니다.

필수 여부: 예

-sess

현재 세션에만 존재하는 키를 생성합니다. 세션이 종료된 후에는 키를 복구할 수 없습니다.

다른 키를 암호화한 후 다시 재빨리 암호를 해독하는 래핑 키와 같이 키가 일시적으로 필요한 경우 이 파라미터를 사용합니다. 세션 종료 후에 암호를 해독해야 할 수 있는 데이터를 암호화하는 데 세션 키를 사용해서는 안 됩니다.

세션 키를 영구적인 (토큰) 키로 변경하려면 setAttribute를 사용합니다.

기본값: 키는 영구적입니다.

필수 여부: 아니요

-min_srv

-timeout 파라미터의 값이 만료되기 전에 키가 동기화되는 HSM의 최소 개수를 지정합니다. 할당된 시간에 지정된 서버 개수에 키가 동기화되지 않으면 키가 생성되지 않습니다.

AWS CloudHSM 모든 키를 클러스터의 모든 HSM과 자동으로 동기화합니다. 이 과정을 더 빠르게 진행하려면 min_srv의 값을 클러스터의 HSM 개수보다 적게 설정하고 낮은 제한 시간 값을 설정합니다. 그러나 일부 요청은 키를 생성하지 않을 수 있음을 주의하십시오.

기본값: 1

필수 여부: 아니요

-timeout

명령이 min_srv 파라미터에서 지정한 HSM의 수에 키가 동기화하기를 기다리는 시간(단위: 초)을 지정합니다.

이 파라미터는 명령에서 min_srv 파라미터도 사용되는 경우에만 유효합니다.

기본값: 제한 시간 없음. 명령은 무기한 기다리다가 최소 서버 개수에 키가 동기화될 때만 복귀합니다.

필수 여부: 아니요

-attest

클러스터가 실행되는 펌웨어가 변조되지 않았는지 확인하는 무결성 점검을 실행합니다.

기본값: 증명 점검은 없음.

필수 여부: 아니요

-nex

키를 추출할 수 없도록 합니다. 생성된 키는 HSM에서 내보내기를 수행할 수 없습니다.

기본값: 키를 추출할 수 있습니다.

필수 여부: 아니요

-m

래핑 메커니즘을 나타내는 값입니다. CloudHSM은 다음과 같은 메커니즘을 지원합니다.

메커니즘	값
`AES_KEY_WRAP_PAD_PKCS5`	4
`NIST_AES_WRAP_NO_PAD`	5
`NIST_AES_WRAP_PAD`	6
`RSA_AES`	7
`RSA_OAEP`(최대 데이터 크기는 이 단원 뒷부분의 참고 참조)	8
`AES_GCM`	10
`CLOUDHSM_AES_GCM`	11
`RSA_PKCS` (최대 데이터 크기는 이 섹션 뒷부분의 참고 사항을 참조하십시오). 예정된 변경 사항은 1 아래 참고를 참조하세요.	12

필수 여부: 예

참고

RSA_OAEP래핑 메커니즘을 사용할 때 래핑할 수 있는 최대 키 크기는 다음과 같이 RSA 키의 모듈러스와 지정된 해시의 길이에 따라 결정됩니다. 최대 키 크기 = modulusLengthIn 바이트- (2* Bytes) -2. hashLengthIn

RSA_PKCS 래핑 메커니즘을 사용하는 경우 래핑할 수 있는 최대 키 크기는 다음과 같이 RSA 키의 모듈러스에 의해 결정됩니다. 최대 키 크기 = (modulusLengthIn바이트 -11).

-t

해시 알고리즘	값
`SHA1`	2
`SHA256`	3
`SHA384`	4
`SHA512`	5
`SHA224`(`RSA_AES` 및 `RSA_OAEP` 메커니즘에 대해 유효함)	6

필수 여부: 아니요

-noheader

key_mgmt_util 외부에서 래핑된 키를 언래핑하는 경우 이 파라미터 및 연관된 다른 모든 파라미터를 지정해야 합니다.

필수 여부: 아니요

참고

이 파라미터를 지정할 경우 반드시 다음의 -noheader 파라미터도 지정해야 합니다.

-l

언래핑된 키에 추가할 레이블을 지정합니다.

필수 여부: 예
-kc

언래핑할 키의 클래스를 지정합니다. 사용할 수 있는 값은 다음과 같습니다.

3 = 퍼블릭-프라이빗 키 페어에서 프라이빗 키

4 = 보안(대칭) 키

필수 여부: 예
-kt

언래핑할 키의 유형을 지정합니다. 사용할 수 있는 값은 다음과 같습니다.

0 = RSA

1 = DSA

3 = ECC

16 = GENERIC_SECRET

21 = DES3

31 = AES

필수 여부: 예

선택적으로 다음 -noheader 파라미터를 지정할 수도 있습니다.

-id

언래핑된 키에 추가할 ID입니다.

필수 여부: 아니요
-i

사용할 언래핑 IV(초기화 벡터)입니다.

필수 여부: 아니요

[1] NIST 지침에 따라 2023년 이후 FIPS 모드의 클러스터에서는 허용되지 않습니다. 비 FIPS 모드의 클러스터의 경우 2023년 이후에도 여전히 허용됩니다. 세부 정보는 FIPS140 규정 준수: 2024 메커니즘 지원 중단를 참조하세요.

unWrapKey

구문

예

예 : 키 언래핑하기(헤더 있음)

예 : 키 언래핑하기(헤더 없음)

파라미터

참고

참고

관련 주제