Hardware Security Module(HSM) 상품은 Thales Luna HSM을 기반으로 하며, HSM 클라이언트(LunaClient)를 설치하면 lunacm, ckdemo, multitoken 등의 CLI 도구가 함께 설치됩니다. 이 문서에서는 별도의 코드 작성 없이 이 CLI 도구들만으로 파티션 상태를 조회하고, 기본적인 암호 연산(키 생성·암복호화·서명)과 처리량(TPS) 측정을 실습하는 방법을 안내합니다.
코드로 직접 연동하려면 Java 연동 Quickstart 또는 C++(Cryptoki) 연동 Quickstart를 참고해 주십시오.
이 문서에서 인용한 명령어 문법은 Thales 공식 문서를 기준으로 작성되었습니다.
지원 환경
지원 환경을 설명합니다.
전제 조건
실습을 시작하기 전, 다음의 전제 조건을 준수해 주십시오.
- HSM 클라이언트 서버에 Luna HSM Client(LunaClient) 10.9.3이 설치되어 있음 — LunaClient 설치 가이드
- HSM 클라이언트 서버 인스턴스와 HSM 파티션 간에 연결 생성 완료
- HSM 파티션 초기 설정 완료
지원 버전
| 구성 요소 | 버전 | 비고 |
|---|---|---|
| HSM 클라이언트(Luna Client) | 10.9.3 | LunaClient 설치 가이드 |
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 모드 활성화 가이드
- HA(고가용성) 구성 — 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
-
세션 열기 — TOKEN 메뉴
1(Open Session), 슬롯 번호 입력(lunacm:> slot list로 확인한 값) -
로그인 — TOKEN 메뉴
3(Login). 이후 단계에서 키를 생성해야 하므로 Crypto Officer로 로그인합니다(Crypto User는 키 생성 권한이 없습니다). 파티션 비밀번호를 입력합니다. -
키 생성 — 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) 번호가 출력되며, 다음 단계(암호화/복호화)에서 이 핸들 번호를 그대로 입력합니다. -
암호화 — SECURITY 메뉴
40(Encrypt file). mechanism 목록이 뜨면 그중[29] AES-CBC-PAD를 선택하고, 입력 파일명으로plain.txt, 이어서 3번에서 생성된 키 핸들 번호를 입력합니다. 출력 파일명은 따로 묻지 않고ENCRYPT.BIN으로 자동 생성됩니다. -
복호화 — SECURITY 메뉴
41(Decrypt file). 같은 방식으로 mechanism[29] AES-CBC-PAD, 입력 파일명ENCRYPT.BIN, 같은 키 핸들을 입력합니다. 출력 파일은DECRYPT.TXT로 자동 생성되며,plain.txt와 내용을 비교(diff plain.txt DECRYPT.TXT)해서 같은지 확인합니다. -
로그아웃 — TOKEN 메뉴
4(Logout) -
세션 종료 — TOKEN 메뉴
2(Close Session)
multitoken — 처리량(TPS) 측정
multitoken은 지정한 슬롯(들)에 스레드를 띄워 반복적으로 암호 연산을 수행하고 처리량을 측정하는 벤치마크 도구입니다. 슬롯/토큰 자체의 목록 조회 기능은 없으므로, 대상 슬롯 번호는 앞서 lunacm의 slot list로 먼저 확인합니다.
문법
/usr/safenet/lunaclient/bin/multitoken -mode <mode> {-slots <slot_list> | -nslots <slot_threads>} [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 공식 문서에서 확인할 수 있습니다.
문제 해결
명령을 찾을 수 없는 경우
lunacm/ckdemo/multitoken 명령을 찾을 수 없는 경우
원인
LunaClient가 설치되어 있지 않거나 /usr/safenet/lunaclient/bin이 PATH에 없는 경우 발생합니다.
해결 방법
절대경로(/usr/safenet/lunaclient/bin/lunacm 등)로 직접 실행하거나 PATH를 확인하십시오.
로그인 후 실패
role login 후에도 슬롯 정보 조회/키 생성이 실패합니다.
원인
파티션 비밀번호가 틀렸거나, HSM 클라이언트 서버와 HSM 파티션 간의 연결·초기 설정이 완료되지 않은 경우 발생할 수 있습니다.
해결 방법
전제 조건을 다시 확인하십시오.
다음 단계
- 코드로 직접 연동: Java 연동 Quickstart, C++(Cryptoki) 연동 Quickstart