--- title: "BYOK(키 주입) CLI 예제" slug: "hsm-byok-cli-guide" updated: 2026-10-22T09:08:02Z published: 2026-10-22T09:08:02Z canonical: "guide-gov.ncloud-docs.com/hsm-byok-cli-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://guide-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # BYOK(키 주입) CLI 예제 VPC 환경에서 이용 가능합니다. 이 문서는 보유하고 계신 AES-256 대칭키, RSA/EC 개인키와 공개키를 코드 작성 없이 CLI 도구(`cmu`, `ckdemo`, OpenSSL)만으로 NCP Hardware Security Module(HSM) 파티션에 주입(BYOK)하는 절차를 안내합니다. 주입 원리와 지원 범위는 [BYOK(키 주입) 개요](/docs/hsm-byok-overview)에서 먼저 확인해 주십시오. :::(info) (참고) 이 문서는 위에서부터 순서대로 실행하면 전 과정이 완료되도록 구성했습니다. 1. [실행 공통값](/docs/hsm-byok-cli-guide#%EC%8B%A4%ED%96%89%EA%B3%B5%ED%86%B5%EA%B0%92) — 슬롯, 비밀번호, 파일 이름 타임스탬프 설정 2. [샘플 키 준비](/docs/hsm-byok-cli-guide#%EC%83%98%ED%94%8C%ED%82%A4%EC%A4%80%EB%B9%84) — 주입해 볼 키 생성 (보유한 키가 있으면 생략) 3. [1단계 — wrapping 키쌍 생성과 공개키 반출](/docs/hsm-byok-cli-guide#1%EB%8B%A8%EA%B3%84wrapping%ED%82%A4%EC%8C%8D%EC%83%9D%EC%84%B1%EA%B3%BC%EA%B3%B5%EA%B0%9C%ED%82%A4%EB%B0%98%EC%B6%9C) 4. [ckdemo 준비](/docs/hsm-byok-cli-guide#ckdemo%EC%A4%80%EB%B9%84) — unwrap에 사용하는 ckdemo의 공통 설정 5. [AES-256 대칭키 주입](/docs/hsm-byok-cli-guide#AES256%EB%8C%80%EC%B9%AD%ED%82%A4%EC%A3%BC%EC%9E%85) 6. [RSA 키 주입](/docs/hsm-byok-cli-guide#RSA%ED%82%A4%EC%A3%BC%EC%9E%85) / [EC 키 주입](/docs/hsm-byok-cli-guide#EC%ED%82%A4%EC%A3%BC%EC%9E%85) 7. [주입한 키 조회](/docs/hsm-byok-cli-guide#%EC%A3%BC%EC%9E%85%ED%95%9C%ED%82%A4%EC%A1%B0%ED%9A%8C) / [정리](/docs/hsm-byok-cli-guide#%EC%A0%95%EB%A6%AC) 특정 키 유형만 필요하시면 1~4를 수행한 뒤 해당 절로 건너뛰셔도 됩니다. 공개키만 주입한다면 wrapping 키쌍과 `ckdemo`가 필요 없으므로 1을 수행한 뒤 [RSA 공개키 주입](/docs/hsm-byok-cli-guide#RSA%EA%B3%B5%EA%B0%9C%ED%82%A4%EC%A3%BC%EC%9E%85) 또는 [EC 키 주입](/docs/hsm-byok-cli-guide#EC%ED%82%A4%EC%A3%BC%EC%9E%85%EB%AA%85%EB%A0%B9)의 공개키 부분으로 건너뛰십시오. 같은 절차를 Java 코드로 수행하려면 [BYOK(키 주입) Java 예제](/docs/hsm-byok-java-guide)를 참고해 주십시오. `lunacm`과 `ckdemo`의 기본 사용법(세션 열기, 로그인, 메뉴 구성)은 [HSM CLI 도구 사용 가이드](/docs/hsm-cli-tools-guide)에서 안내합니다. `cmu`(Certificate Management Utility)는 LunaClient와 함께 `/usr/safenet/lunaclient/bin/cmu`에 설치되며, `cmu <명령> -<옵션>=<값> ...` 형식의 한 줄 명령으로 키 생성·조회·속성 변경·삭제를 수행합니다. 명령별 옵션은 `cmu help -cmd <명령>`으로 확인할 수 있습니다. 이 문서에서는 BYOK에 필요한 명령만 다룹니다. **이 문서의 절차는 접근이 통제된 서버 한 대에서 실행하는 것을 전제로 합니다.** 각 명령 블록 앞에는 운영 환경에서 그 작업이 **어느 쪽에 속하는지**를 실행 위치로 표시했습니다. 운영 환경에서 두 시스템을 분리한다면, "키 보유 측 작업"으로 표시된 단계는 키를 보유한 시스템에서 수행하고 HSM 클라이언트 서버로는 감싼 결과물(`.oaep.bin`, `.kwp.bin`)과 공개키(`.pub.pem`)만 전달하십시오. 평문 키 파일은 HSM 클라이언트 서버에 두지 마십시오. ::: ## 지원 환경 ### 전제 조건 시작하기 전, 다음의 전제 조건을 준수해 주십시오. - HSM 클라이언트 서버에 Luna HSM Client(LunaClient)가 설치되어 있음 — [LunaClient 설치 가이드](/docs/hsm-client) - HSM 클라이언트 서버 인스턴스와 HSM 파티션 간에 연결 생성 완료 - HSM 파티션 초기 설정 완료 - 파티션 정책 확인 완료 — [파티션 정책 요구사항](/docs/hsm-byok-overview#%ED%8C%8C%ED%8B%B0%EC%85%98%EC%A0%95%EC%B1%85%EC%9A%94%EA%B5%AC%EC%82%AC%ED%95%AD) ### 지원 버전 | 구분 | 버전 | 비고 | | --- | --- | --- | | HSM 클라이언트(Luna Client) | 10.9.3 | `cmu`, `ckdemo`가 함께 설치됩니다. | | OpenSSL (키 보유 측) | 3.0 이상 | RSA/EC 개인키를 AES-KWP로 감쌀 때 필요합니다. | 이 문서의 절차는 Linux 서버의 bash를 기준으로 작성했습니다. 키 보유 측에서는 OpenSSL로 키를 감쌉니다. AES 키를 RSA-OAEP로 감싸는 작업은 OpenSSL 1.1.1에서도 되지만, RSA/EC 개인키를 AES-KWP로 감싸는 `openssl enc -id-aes256-wrap-pad`는 **OpenSSL 3.0 이상**에서만 동작합니다. 이 문서의 예제는 OpenSSL 3.0.15에서 확인했습니다. :::(info) (참고) 키 보유 측에서 OpenSSL 3.0 이상을 사용할 수 없다면, 개인키 감싸기만 Java로 수행할 수 있습니다. [BYOK(키 주입) Java 예제의 `KwpWrap.java`](/docs/hsm-byok-java-guide#KwpWrapjava%EC%9E%91%EC%84%B1)를 사용하십시오(JDK 17 이상 필요). ::: ## 실행 공통값 **실행 위치 — HSM 클라이언트 서버** 이후의 모든 명령에서 사용할 값입니다. `SLOT`과 `CO_PW`를 실제 파티션의 슬롯 번호와 Crypto Officer(CO) 비밀번호로 교체하십시오. 키 생성·주입·속성 변경은 CO 권한이 필요합니다. Crypto User(CU)로 로그인하면(`cmu`의 `-cu` 옵션) 조회는 되지만 키쌍 생성(`Key pair generation failed`), 공개키 주입(`Create object failed`), 속성 변경(`Failed to set attribute value`)이 모두 실패합니다. ```bash export SLOT=0 read -rsp "CO password: " CO_PW; echo; export CO_PW export TS=${TS:-$(date +%Y%m%d%H%M%S)}; echo "TS=$TS" export PATH=/usr/safenet/lunaclient/bin:$PATH ``` `CO_PW`는 화면과 셸 기록에 남지 않도록 입력받습니다. `TS`는 이 문서의 예제에서 label과 파일 이름이 겹치지 않도록 붙이는 타임스탬프입니다. 이미 `TS`가 설정되어 있으면(예: [BYOK(키 주입) 키 준비](/docs/hsm-byok-key-prep)를 먼저 진행한 경우) 그 값을 그대로 사용합니다. 아래 절차를 이어서 진행하는 동안 값을 바꾸지 마십시오. **셸을 하나 더 열어 두십시오.** 이후 절차에서는 한 셸에서 `ckdemo`를 실행해 둔 채, 다른 셸에서 `cmu`와 OpenSSL 명령을 실행합니다. 새로 연 셸에는 위 변수가 없으므로, 새 셸에서도 위 블록을 실행하되 `TS`는 첫 셸에 출력된 값으로 지정하십시오(`export TS=<첫 셸의 값>`을 먼저 실행한 뒤 위 블록을 실행). 키 보유 측을 다른 시스템에서 작업할 때도 같은 `TS` 값을 지정해야 파일 이름이 맞습니다. `SLOT`이 대상 파티션을 가리키는지 확인합니다. 로그인에 성공하고 그 파티션의 객체 목록(비어 있으면 출력 없음)이 나오면 정상입니다. ```bash cmu list -slot=$SLOT -password="$CO_PW" -display=handle,label public handle(488), private handle(703) ``` `cmu`는 지정한 속성을 키 종류에 맞게 나누어 적용합니다. 공개키에는 `wrap`·`encrypt`가, 개인키에는 `unwrap`·`decrypt`·`extractable=false`가 지정됩니다. 위 출력의 handle 번호는 예시이며 실제 값은 파티션마다 다릅니다. **출력된 두 handle을** 변수로 기록해 두십시오. 이후 명령에서 사용하며, 셸을 두 개 쓰는 경우 양쪽 셸에서 모두 지정하십시오. ```bash export WRAP_PUB=<출력된 public handle> export WRAP_PRV=<출력된 private handle> ``` 개인키의 속성을 확인합니다. ```bash cmu getattribute -slot=$SLOT -password="$CO_PW" -handle=$WRAP_PRV cmu getattribute -slot=$SLOT -password="$CO_PW" -handle=$KEK "/tmp/rsa-prv-$TS.modulus" ``` 원래 공개키의 modulus와 비교합니다. 공개키만 있으면 되므로 HSM 클라이언트 서버에서도 실행할 수 있습니다. 두 시스템을 분리했다면 `/tmp/rsa-prv-$TS.modulus` 파일을 키 보유 측으로 옮겨 비교해도 됩니다. **실행 위치 — HSM 클라이언트 서버** 또는 **키 보유 측 작업** ```bash # 준비한 키 사용 시: -in 을 보유한 RSA 공개키 PEM 파일로 openssl rsa -pubin -in "/tmp/sample-rsa-$TS.pub.pem" -noout -modulus | sed 's/^Modulus=//' \ | diff - "/tmp/rsa-prv-$TS.modulus" && echo SAME ``` ``` SAME ``` ### 파티션에 RSA 공개키 주입 공개키는 공개 정보이므로 감쌀 필요 없이 PEM 파일을 그대로 주입합니다. **실행 위치 — HSM 클라이언트 서버** ```bash # 준비한 키 사용 시: -inputfile 을 보유한 RSA 공개키 PEM 파일로 cmu import -slot=$SLOT -password="$CO_PW" \ -inputfile="/tmp/sample-rsa-$TS.pub.pem" -pubkey=rsa -label="rsa-pub-$TS" handle(439) ``` `cmu import`로 주입한 공개키는 `verify=true`, `encrypt=false`, `wrap=false`로 만들어집니다. RSA 공개키로 암호화도 수행하려면 출력된 handle로 속성을 켜십시오. 먼저 그 handle이 방금 주입한 공개키(`label=rsa-pub-$TS`)가 맞는지 확인하십시오. ```bash export RSA_PUB=<출력된 handle> cmu getattribute -slot=$SLOT -password="$CO_PW" -handle=$RSA_PUB cmu getattribute -slot=$SLOT -password="$CO_PW" -handle=$EC_PRV