Nginx 연동

VPC 환경에서 이용 가능합니다.

Nginx 웹 서버 SSL용 인증 키를 HSM으로 관리하기 위해 HSM 클라이언트와 Nginx를 연동하는 방법을 설명합니다.

지원 환경

HSM 클라이언트와 Nginx를 연동하기 위한 환경은 다음과 같습니다.

전제 조건

Nginx 연동을 시작하기 전, 다음의 전제 조건을 준수해 주십시오.

• HSM 클라이언트 서버에 Nginx가 설치 및 구동되고 있음
• HSM 클라이언트 서버는 VPC 상에 위치
• HSM 클라이언트 서버 인스턴스와 HSM 파티션 간에 연결 생성 완료
• HSM 클라이언트 서버에 OpenSSL GemEngine 설치

OpenSSL 툴킷 호환 버전

Nginx 웹 서버별 호환되는 OpenSSL 툴킷(GemEngine)의 버전을 확인해 주십시오.

OpenSSL 설정

GemEngine을 사용하도록 Nginx OpenSSL을 설정해 주십시오. 설정 방법은 다음과 같습니다.

1. Nginx 서버에 루트 사용자 또는 관리 권한이 있는 다른 사용자로 로그인해 주십시오.
2. GemEngine을 다운로드하여 home 폴더 하위에 압축 해제해 주십시오.
   • 다운로드 링크: OpenSSL GemEngine 다운로드

     # cd /home/gemengine-1.2
     

3. gembuild 명령을 사용하여 OpenSSL 엔진 디렉터리를 찾아 주십시오.

   # ./gembuild locate-engines
   

4. GemEngine이 참조하는 라이브러리 파일(libgem.so)을 OpenSSL 엔진 디렉터리로 복사해 주십시오.

   # cp builds/linux/rhel/64/1.0.2/libgem.so /usr/lib64/openssl/engines/
   

5. GemEngine이 설치되어 있고, OpenSSL에서 지원되는지 확인해 주십시오.

   # openssl engine gem -v
   (gem) Gem engine support
   enginearg, openSession, closeSession, login, logout, engineinit,
   CONF_PATH, ENGINE_INIT, ENGINE2_INIT, engine2init, DisableCheckFinalize,
   SO_PATH, GET_HA_STATE, SET_FINALIZE_PENDING, SKIP_C_INITIALIZE,
   IntermediateProcesses
   

6. 암호화 관리자(Crypto User)의 비밀번호를 저장한 파일을 생성해 주십시오.

   # vim passfile
   
   myofficerpassword
   

7. Chrystoki.conf 파일에 다음의 설정을 추가해 주십시오.

   vim /etc/Chrystoki.conf
   
   GemEngine = {
   LibPath = /usr/safenet/lunaclient/lib/libCryptoki2.so;
   LibPath64 = /usr/safenet/lunaclient/lib/libCryptoki2_64.so;
   EnableDsaGenKeyPair = 1;
   EnableRsaGenKeyPair = 1;
   DisablePublicCrypto = 1;
   EnableRsaSignVerify = 1;
   EnableLoadPubKey = 1;
   EnableLoadPrivKey = 1;
   DisableCheckFinalize = 1;
   DisableEcdsa = 1;
   DisableDsa = 0;
   DisableRand = 0;
   EngineInit = "<myTokenLabel>":0:0:passfile=</path/to/my/passfile>;
   EnableLoginInit = 1;
   }
   

   변수	내용
   myTokenLabel	hsm 라벨
   </path/to/my/passfile>	6번 절차에서 설정한 passfile 절대 경로

8. OpenSSL에서 GemEngine을 이용하도록 설정되었는지 확인해 주십시오.

   # openssl engine gem -t
   (gem) Gem engine support[ available ]
   

HSM-Nginx 연동 설정

Nginx 웹 서버에서 사용할 SSL 인증서를 생성하고, Nginx가 해당 인증서를 사용하도록 설정해 주십시오.

인증서 생성

HSM 사용을 위한 신규 인증서를 생성해 주십시오. CA Signed SSL 인증서 또는 Self-Signed SSL 인증서를 생성해야 합니다.

• CA Signed SSL 인증서 생성
• Self-Signed SSL 인증서 생성

CA Signed SSL 인증서 생성

CA Signed SSL 인증서를 생성하는 방법은 다음과 같습니다.

1. GemEngine 명령을 실행하여 개인 키와 CSR을 생성해 주십시오.

   # openssl req -engine gem -new -newkey rsa:2048 -nodes -sha256 -keyout server.key -out server.csr
   

2. SafeNet Luna Client cmu 유틸리티를 사용하여 생성된 개인 키 값을 확인해 주십시오.

   # /usr/safenet/lunaclient/bin/cmu list
   Certificate Management Utility (64-bit) v10.0.0-275. Copyright (c) 2020 SafeNet. All rights reserved. 
   
   Please enter password for token in slot 0 : **********
   
   handle=97        label=rsa-private-cwe8f9aef8a8d9ef8we9a
   handle=96        label=rsa-public-cwe8f9aef8a8d9ef8we9a
   

3. 생성된 CSR 파일을 보유한 CA 혹은 서명 기관을 통해 서명해 주십시오.
   • 서명된 인증서 또는 인증서 체인, CA 서명된 인증서를 서버 폴더에 저장해 주십시오.

Self-Signed SSL 인증서 생성

Self-Signed SSL 인증서를 생성하는 방법은 다음과 같습니다.

1. GemEngine 명령을 실행하여 개인 키와 CSR을 생성해 주십시오.
   • 명령어 인자 중 {Common Name} 부분은 서버의 호스트명을 지정해 주십시오.

   # openssl genrsa -engine gem -out {Common Name}.key 2048
   
   # openssl req -new -engine gem -x509 -key {Common Name}.key -sha256 -out {Common Name}.pem
   

2. SafeNet Luna Client cmu 유틸리티를 사용하여 생성된 개인 키 값을 확인해 주십시오.

   # /usr/safenet/lunaclient/bin/cmu list
   Certificate Management Utility (64-bit) v10.0.0-275. Copyright (c) 2020 SafeNet. All rights reserved. 
   
   Please enter password for token in slot 0 : **********
   
   handle=97        label=rsa-private-cwe8f9aef8a8d9ef8we9a
   handle=96        label=rsa-public-cwe8f9aef8a8d9ef8we9a
   

인증서 사용 설정

생성된 인증서를 Nginx 서버가 사용하도록 설정해 주십시오. 신규 SSL 인증서를 사용할 경우와 기존 SSL 인증서를 사용할 경우에 설정 방법이 다릅니다.

• 신규 인증서 사용 설정
• 기존 인증서 사용 설정

신규 인증서 사용 설정

신규 SSL 인증서를 사용하도록 설정하는 방법은 다음과 같습니다.

1. nginx.conf 파일을 열어 http section 설정 최하단에 다음의 ssl 설정을 추가해 주십시오.

   server {
       listen 443 ssl;
       server_name <Server Hostname or IP Address>;
   
       ssl_certificate <path to CA signed or self-signed certificate>;
       ssl_certificate_key <path to the private key file>;
   
       ssl_session_cache shared:SSL:1m;
       ssl_session_timeout 5m;
   
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_ciphers HIGH:!aNULL:!MD5;
       ssl_prefer_server_ciphers on;
   
       location / {
           root html;
           index index.html index.htm;
       }
   }
   

   변수	내용
   Server Hostname or IP Address	서버의 호스트명, 도메인
   path to CA signed or self-signed certificate	CA 파일 절대 경로
   path to the private key file	개인 키 절대 경로

2. nginx.conf 파일을 열어 http section 설정 시작 지점에 다음의 설정을 추가해 주십시오.

   ssl_engine gem;
   http {
   ...
   

3. 다음 명령어를 입력하여 nginx 설정 파일을 검증해 주십시오.

   # ./nginx -t
   nginx: the configuration file /usr/local/nginx/nginx.conf syntax is ok
   nginx: configuration file /usr/local/nginx/nginx.conf test is successful
   

4. 검증 결과로 nginx.conf 파일이 정상이라면 nginx를 재시작해 주십시오.

   # ./nginx -s quit
   # ./nginx
   

5. 브라우저에 접속하여 인증서를 확인해 주십시오.
   • Nginx 설정이 정상적으로 완료되면 다음과 같이 인증서 정보가 정상적으로 표시됩니다.
     

기존 인증서 사용 설정

기존 SSL 인증서를 사용하도록 설정하는 방법은 다음과 같습니다.

1. 기존 SSL 인증서의 공개 키를 추출해 주십시오.

   # openssl rsa -in server.key -pubout -out pubkey.pem
   

2. 기존 SSL 인증서 개인 키를 추출해 주십시오.
   • 개인 키는 PKCS#8 형식을 따릅니다.

   # openssl pkcs8 -in server.key -topk8 -nocrypt -out privatekey.pem
   

3. SafeNet Luna Client cmu 유틸리티를 사용하여 공개 키와 개인 키를 HSM 클라이언트로 가져와 주십시오.

   # /usr/safenet/lunaclient/bin/cmu import -inputFile pubkey.pem -label nginx_public_key -pubkey=rsa
   
   # /usr/safenet/lunaclient/bin/cmu importkey -PKCS8 -in privatekey.pem -keyalg RSA
   

   
4. HSM 파티션에 키가 생성되었는지 확인한 후, 개인 키 핸들을 기록해 주십시오.

   # /usr/safenet/lunaclient/bin/cmu list
   

   
5. 개인 키가 여러 개인 경우 개인 키별로 레이블을 붙여 주십시오.
   • 개인 키 레이블을 설정함으로써 HSM 클라이언트가 개별 개인 키를 인식할 수 있습니다.

   #  /usr/safenet/lunaclient/bin/cmu setattribute -handle=46 -label=nginx_private_key
   

6. OpenSSL 툴킷과 함께 제공된 sautil 유틸리티를 로컬 bin 폴더로 복사해 주십시오.

   cp /home/gemengine-1.2/builds/linux/rhel/64/1.0.2/sautil /usr/bin/
   

7. sautil 유틸리티를 실행하여 HSM으로 가져온 실제 개인 키에 대한 개인 키 참조를 생성해 주십시오.

   # sautil -v -s 0 -i 0:0 -a 0:RSA -f HSMKey_ref.pem -o -q –c
   

   
8. 3번 절차를 수행하기 전에 해당 키를 사용하던 OpenSSL에서 개인 키를 제거해 주십시오.
9. 7번 절차에서 생성한 개인 키 참조 파일인 HSMKey_ref.pem을 nginx.conf의 ssl_certificate_key로 정의해 주십시오.

   server {
       listen 443 ssl;
       server_name <Server Hostname or IP Address>;
   
       ssl_certificate <path to CA signed or self-signed certificate>;
       ssl_certificate_key <path to the private key file>;
   
       ssl_session_cache shared:SSL:1m;
       ssl_session_timeout 5m;
   
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_ciphers HIGH:!aNULL:!MD5;
   
       ssl_prefer_server_ciphers on;
       location / {
           root html;
           index index.html index.htm;
       }
   }
   

   변수	내용
   Server Hostname or IP Address	서버의 호스트명, 도메인
   path to CA signed or self-signed certificate	CA 파일 절대 경로
   path to the private key file	HSMKey_ref.pem 절대 경로

10. nginx.conf 파일을 열어 http section 시작 지점에 다음 내용을 추가해 주십시오.

# ssl_engine gem;
http {
...

11. nginx를 재시작해 주십시오.

# ./nginx -s quit
# ./nginx

12. 브라우저에 접속하여 인증서를 확인해 주십시오.
    

문제 해결

Nginx를 이용하면서 사용자가 만날 수 있는 문제 상황과 원인 및 해결 방법을 안내합니다.

서버에서 올바르지 않은 응답을 수신했습니다.

Nginx 서버에서 브라우저에서 접속하여 인증서를 확인했을 때 '서버에서 올바르지 않은 응답을 수신했습니다' 에러가 발생한 경우 원인과 해결 방법은 다음과 같습니다.

• 원인: myTokenLabel의 값이 partition label과 다름
• 해결 방법: Chrystoki.conf 파일에서 정의한 myTokenLabel 값을 partition label과 동일하게 수정

2021/02/19 14:30:18 [crit] 72806#0: *9 SSL_do_handshake() failed (SSL: error:8006B08C:Luna CA3 engine:LUNA_INIT:engine error:token not found "intg-hsm" error:8006907A:Luna CA3 engine:LUNA_CMDARG:invalid argument error:8006B08C:Luna CA3 engine:LUNA_INIT:engine error:ENGINE_CMD_LUNA_ENGINEINIT error:8009D07A:Luna CA3 engine:LUNACA3_F_RSA_SIGN:invalid argument error:1409B006:SSL routines:ssl3_send_server_key_exchange:EVP lib) while SSL handshaking, client: 220.120.244.198, server: 0.0.0.0:443