--- title: "CLI 도구 활용" slug: "hsm-cli-tools-guide" updated: 2026-10-22T09:08:02Z published: 2026-10-22T09:08:02Z canonical: "guide-gov.ncloud-docs.com/hsm-cli-tools-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. # CLI 도구 활용 Hardware Security Module(HSM) 상품은 Thales Luna HSM을 기반으로 하며, HSM 클라이언트(LunaClient)를 설치하면 `lunacm`, `ckdemo`, `multitoken` 등의 CLI 도구가 함께 설치됩니다. 이 문서에서는 별도의 코드 작성 없이 이 CLI 도구들만으로 파티션 상태를 조회하고, 기본적인 암호 연산(키 생성·암복호화·서명)과 처리량(TPS) 측정을 실습하는 방법을 안내합니다. 참고 코드로 직접 연동하려면 [Java 연동 Quickstart](/docs/java-quickstart-guide) 또는 [C++(Cryptoki) 연동 Quickstart](/docs/cpp-quickstart-guide)를 참고해 주십시오. 이 문서에서 인용한 명령어 문법은 Thales 공식 문서를 기준으로 작성되었습니다. - [LunaCM Commands (Luna SDK Reference)](https://www.thalesdocs.com/gphsm/luna/7/docs/network/Content/lunacm/commands/commands.htm) - [CKdemo (Luna SDK Reference)](https://www.thalesdocs.com/gphsm/luna/7/docs/network/Content/Utilities/ckdemo/ckdemo.htm) - [multitoken (Luna SDK Reference)](https://www.thalesdocs.com/gphsm/luna/7/docs/network/Content/Utilities/multitoken.htm) ## 지원 환경 지원 환경을 설명합니다. ### 전제 조건 실습을 시작하기 전, 다음의 전제 조건을 준수해 주십시오. - HSM 클라이언트 서버에 Luna HSM Client(LunaClient) 10.9.3이 설치되어 있음 — [LunaClient 설치 가이드](/docs/hsm-client) - HSM 클라이언트 서버 인스턴스와 HSM 파티션 간에 연결 생성 완료 - HSM 파티션 초기 설정 완료 ### 지원 버전 | 구성 요소 | 버전 | 비고 | | --- | --- | --- | | HSM 클라이언트(Luna Client) | 10.9.3 | [LunaClient 설치 가이드](/docs/hsm-client) | ## lunacm — 슬롯·파티션 조회 및 로그인 `lunacm`은 클라이언트에 등록된 슬롯(파티션) 목록을 확인하고, 역할(role)로 로그인하는 대화형 CLI입니다. ``` /usr/safenet/lunaclient/bin/lunacm ``` ### 슬롯 목록 조회 ``` lunacm:> slot list Slot Id -> 0 Label -> par0 Serial Number -> 1234567890123 Model -> LunaSA 7.9.1 Firmware Version -> 7.9.3 Bootloader Version -> 1.1.5 Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode Slot Description -> Net Token Slot FM HW Status -> FM Ready Slot Id -> 1 Label -> par1 Serial Number -> 1234567890124 Model -> LunaSA 7.9.1 Firmware Version -> 7.9.3 Bootloader Version -> 1.1.5 Configuration -> Luna User Partition With SO (PW) Key Export With Cloning Mode Slot Description -> Net Token Slot FM HW Status -> FM Ready Current Slot Id: 0 Command Result : No Error ``` 여러 파티션이 등록되어 있다면 `slot set -slot <슬롯번호>`로 이후 명령어들이 대상으로 삼을 슬롯을 바꿀 수 있습니다. ``` lunacm:> slot set -slot 0 Command Result : No Error ``` ### 파티션 정보 조회 ``` lunacm:> partition showinfo ``` 현재 슬롯(파티션)의 상세 정보를 표시합니다. ### 역할 로그인/로그아웃 파티션의 키 객체를 조회·생성하려면 역할(role)로 로그인해야 합니다. 이 상품은 비밀번호 인증 방식이므로 `-name` 뒤에 역할 축약형을 지정하면 비밀번호를 프롬프트로 입력받습니다. ``` lunacm:> role login -name co Please enter password for token in slot 0 : ********* Command Result : No Error ``` | 역할 | 축약형 | | --- | --- | | Crypto Officer | `co` | | Crypto User | `cu` | 로그아웃은 `role logout` 명령어를 사용합니다. ### lunacm으로 할 수 있는 다른 작업 여기서 다룬 슬롯/파티션 조회 외에도 lunacm은 FIPS 모드 활성화, HA(고가용성) 구성 등 파티션 운영에 필요한 여러 작업에 사용됩니다. 이 문서에서는 다루지 않으므로 아래 기존 가이드를 참고해 주십시오. - FIPS 모드 활성화 — [FIPS 모드 활성화 가이드](https://guide-fin.ncloud-docs.com/beta/docs/hsm-fips-vpc) - HA(고가용성) 구성 — [HA 구성 가이드](https://guide-fin.ncloud-docs.com/beta/docs/hsm-ha) 참고 스크립트에서 비대화형으로 lunacm 명령을 실행해야 한다면 `lunacmu`(unattended 버전)를, 클라이언트-파티션 연결 자체에 문제가 있다면 `lunadiag`(진단 도구)를 함께 살펴보십시오. 이 문서에서는 다루지 않습니다. ## ckdemo — PKCS#11 연산 데모 `ckdemo`는 PKCS#11(Cryptoki) API의 각 함수를 번호로 된 메뉴에서 직접 호출해볼 수 있는 대화형 데모 도구입니다. C++ 코드로 옮기기 전에 어떤 API 호출이 필요한지 손으로 먼저 확인해보는 용도입니다. ``` /usr/safenet/lunaclient/bin/ckdemo ``` ### 메뉴 구성 LunaClient 10.9.3 기준 실제 메뉴이며, 실습에 필요한 카테고리만 추렸습니다. | 카테고리 | 대표 메뉴 번호대 | 내용 | | --- | --- | --- | | TOKEN | 1~19, 33~39, 58~59, 140, 160~163 | 세션 오픈/클로즈, 로그인/로그아웃, 슬롯/토큰 정보 등 | | OBJECT MANAGEMENT | 20~27, 30~32, 35 | 객체 생성·조회·속성 관리 | | SECURITY | 40~46 | 암호화/복호화, 서명/검증, 키 생성(Simple Generate Key) | | KEY | 60~69, 150~151 | 키 래핑, 난수 생성, Create Known Keys 등 | ### 실습 — AES256 키 생성부터 암복호화까지 ckdemo 메뉴는 위 표에서 보듯 매우 많지만, 여기서는 세션 열기 → 로그인 → AES256 키 생성 → 암호화 → 복호화 확인 → 로그아웃 → 세션 종료로 이어지는 한 가지 흐름만 끝까지 해봅니다. 나머지 메뉴는 이 흐름에 익숙해진 뒤 자유롭게 눌러보면서 확인해 보십시오. `40`/`41`(Encrypt file/Decrypt file)은 파일 단위로 동작하므로, 시작하기 전에 암호화할 평문 파일을 하나 만들어 둡니다. ``` echo "hsm ckdemo test data" > plain.txt ``` 1. **세션 열기** — TOKEN 메뉴 `1` (Open Session), 슬롯 번호 입력(`lunacm:> slot list`로 확인한 값) 2. **로그인** — TOKEN 메뉴 `3` (Login). 이후 단계에서 키를 생성해야 하므로 **Crypto Officer**로 로그인합니다(Crypto User는 키 생성 권한이 없습니다). 파티션 비밀번호를 입력합니다. 3. **키 생성** — SECURITY 메뉴 `45` (Simple Generate Key), 키 타입으로 AES 선택 → 키 길이 `32`(bytes, 256bit) 입력 → 아래 attribute 질문에 순서대로 답합니다. ``` Enter Is Token Attribute [0-1]: 1 # 세션 종료 후에도 파티션에 영구 저장(CKA_TOKEN) Enter Is Sensitive Attribute [0-1]: 1 # 키 값을 평문으로 조회 불가(CKA_SENSITIVE) Enter Is Private Attribute [0-1]: 1 # 로그인(인증)해야 접근 가능(CKA_PRIVATE) Enter Is Modifiable Attribute [0-1]: 1 # 이후 속성 변경 허용(CKA_MODIFIABLE) Enter Encrypt Attribute [0-1]: 1 # 암호화 연산에 사용 허용(CKA_ENCRYPT) Enter Decrypt Attribute [0-1]: 1 # 복호화 연산에 사용 허용(CKA_DECRYPT) Enter Sign Attribute [0-1]: 1 # MAC 서명에 사용 허용(CKA_SIGN) Enter Verify Attribute [0-1]: 1 # MAC 검증에 사용 허용(CKA_VERIFY) Enter Wrap Attribute [0-1]: 1 # 다른 키를 감싸서 반출하는 데 사용 허용(CKA_WRAP) Enter Unwrap Attribute [0-1]: 1 # 감싸인 키를 반입하는 데 사용 허용(CKA_UNWRAP) Enter Derive Attribute [0-1]: 1 # 다른 키 유도(derive)의 기반으로 사용 허용(CKA_DERIVE) Enter Extractable Attribute [0-1]: 0 # 키 자체를 HSM 밖으로 반출하지 않음(CKA_EXTRACTABLE) ``` 이 실습에서는 `Extractable Attribute`만 `0`으로 두고, 나머지는 위 예시처럼 입력합니다. 완료되면 생성된 키의 객체 핸들(key handle) 번호가 출력되며, 다음 단계(암호화/복호화)에서 이 핸들 번호를 그대로 입력합니다. 4. **암호화** — SECURITY 메뉴 `40` (Encrypt file). mechanism 목록이 뜨면 그중 `[29] AES-CBC-PAD`를 선택하고, 입력 파일명으로 `plain.txt`, 이어서 3번에서 생성된 키 핸들 번호를 입력합니다. 출력 파일명은 따로 묻지 않고 `ENCRYPT.BIN`으로 자동 생성됩니다. 5. **복호화** — SECURITY 메뉴 `41` (Decrypt file). 같은 방식으로 mechanism `[29] AES-CBC-PAD`, 입력 파일명 `ENCRYPT.BIN`, 같은 키 핸들을 입력합니다. 출력 파일은 `DECRYPT.TXT`로 자동 생성되며, `plain.txt`와 내용을 비교(`diff plain.txt DECRYPT.TXT`)해서 같은지 확인합니다. 6. **로그아웃** — TOKEN 메뉴 `4` (Logout) 7. **세션 종료** — TOKEN 메뉴 `2` (Close Session) ## multitoken — 처리량(TPS) 측정 `multitoken`은 지정한 슬롯(들)에 스레드를 띄워 반복적으로 암호 연산을 수행하고 처리량을 측정하는 벤치마크 도구입니다. 슬롯/토큰 자체의 목록 조회 기능은 없으므로, 대상 슬롯 번호는 앞서 [lunacm의 slot list](/docs/hsm-cli-tools-guide#%EC%8A%AC%EB%A1%AF%EB%AA%A9%EB%A1%9D%EC%A1%B0%ED%9A%8C)로 먼저 확인합니다. ### 문법 ``` /usr/safenet/lunaclient/bin/multitoken -mode {-slots | -nslots } [options...] ``` | 옵션 | 단축형 | 설명 | | --- | --- | --- | | `-mode <mode>` | | 수행할 연산 종류 (예: `rsasigver`, `aesenc`, `aesenccbc`, `symgen`, `mlkemkeygen`, `mldsasigver` 등) | | `-slots <slots>` | `-s` | 대상 슬롯 번호 목록(쉼표 구분) | | `-nslots <slot_threads>` | `-ns` | 슬롯별 스레드 수 지정 | | `-duration <seconds>` | `-d` | 지정한 시간(초) 동안 반복 실행 | | `-key <key_size>` | `-k` | 키 크기 | | `-verbose` | `-v` | 스레드별 처리량 상세 출력 | | `-force` | `-f` | 확인 프롬프트 생략 | | `-password <pw>` | `-pwd` | 파티션 비밀번호를 인자로 지정(생략하면 대화형으로 물어봄) | | `-packet <size>` | `-p` | 패킷(데이터) 크기 지정(생략하면 기본값 16바이트 사용, 경고 출력) | ### 실행 예시 ``` # 슬롯 0에서 RSA-2048 서명/검증을 10초간 반복 수행해 처리량 측정 /usr/safenet/lunaclient/bin/multitoken -mode rsasigver -key 2048 -slots 0 -duration 10 ``` 실행하면 계속 진행할지 확인(`y`/`n`)한 뒤, 대상 슬롯의 파티션 비밀번호를 물어보고 로그인합니다(`-password`를 지정하지 않으면 대화형 프롬프트). 로그인 후 지정한 시간(`-duration`) 동안 스레드를 돌려 아래처럼 결과를 표로 출력합니다. ``` Do you wish to continue? Enter 'y' or 'n': y Logging in to tokens... slot 0... Enter password: ************** Serial Number 1234567890123 Please wait, creating test threads. Test threads created successfully. Test will run for 10 secs RSA sign/verify 2048-bit : (packet size = 16 bytes) Using token objects. Logged in as Crypto Officer. + operations/second | elapsed 0, 0 | total average | time (secs) ------ | ------- ---------- | ------------ XXX | XXX XXX* | 10 ``` `total`/`average` 열이 초당 처리량(operations/second), `elapsed`가 실제 수행 시간(초)입니다. 측정되는 수치는 파티션·키 크기·패킷 크기에 따라 달라집니다. `-packet` 옵션을 지정하지 않으면 기본 패킷 크기(16바이트)로 실행된다는 경고가 먼저 출력됩니다. `-mode` 값은 `rsasigver`, `aesenc`, `aesenccbc`, `symgen`, `mlkemkeygen`, `mldsasigver` 등 80여 가지를 제공하며, 전체 목록과 각 모드 설명은 인자 없이 `/usr/safenet/lunaclient/bin/multitoken`만 실행하거나 [multitoken 공식 문서](https://www.thalesdocs.com/gphsm/luna/7/docs/network/Content/Utilities/multitoken.htm)에서 확인할 수 있습니다. ## 문제 해결 ### 명령을 찾을 수 없는 경우 `lunacm`/`ckdemo`/`multitoken` 명령을 찾을 수 없는 경우 #### 원인 LunaClient가 설치되어 있지 않거나 `/usr/safenet/lunaclient/bin`이 `PATH`에 없는 경우 발생합니다. #### 해결 방법 절대경로(`/usr/safenet/lunaclient/bin/lunacm` 등)로 직접 실행하거나 `PATH`를 확인하십시오. ### 로그인 후 실패 `role login` 후에도 슬롯 정보 조회/키 생성이 실패합니다. #### 원인 파티션 비밀번호가 틀렸거나, HSM 클라이언트 서버와 HSM 파티션 간의 연결·초기 설정이 완료되지 않은 경우 발생할 수 있습니다. #### 해결 방법 [전제 조건](/docs/hsm-cli-tools-guide#%EC%A0%84%EC%A0%9C%EC%A1%B0%EA%B1%B4)을 다시 확인하십시오. ## 다음 단계 - 코드로 직접 연동: [Java 연동 Quickstart](/docs/java-quickstart-guide), [C++(Cryptoki) 연동 Quickstart](/docs/cpp-quickstart-guide)