이 가이드에서는 Debian 11(Bullseye)에서 Cloud HSM 키를 사용하도록 OpenSSL을 설정하는 방법을 제공합니다. 이 안내는 일반적으로 다른 OS 또는 환경을 사용하는 경우에도 적용될 수 있지만 약간의 차이가 있을 수 있습니다.
요구사항
시작하려면 라이브러리의 출시 버전을 다운로드하세요. PKCS #11 라이브러리에 대한 자세한 내용은 사용자 가이드를 참조하세요.
시작하기 전에 libengine-pkcs11-openssl 패키지를 설치합니다.
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
구성
PKCS11_MODULE_PATH 환경 변수 설정
openssl가 PKCS #11 라이브러리를 사용하도록 하려면 PKCS11_MODULE_PATH 환경 변수를 설정합니다.
export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
환경 변수를 영구적으로 설정하려면 다음 명령어를 실행하여 export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"를 /etc/profile에 추가합니다.
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile
PKCS #11 라이브러리 구성
PKCS #11 라이브러리에는 Cloud KMS 리소스를 찾기 위한 YAML 구성 파일이 필요합니다. YAML은 최소한 단일 PKCS #11 토큰을 구성해야 합니다.
포크를 수행할 수도 있는 다른 프로세스(예: Apache 또는 Nginx)로 OpenSSL을 사용하는 경우 refresh_interval_secs 필드가 설정되지 않거나 0으로 설정되었는지 확인해야 합니다.
다음은 샘플 구성 파일입니다.
---
tokens:
- key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
이 구성을 사용하면 my-keyring의 모든 비대칭 서명 및 복호화 키를 라이브러리에서 사용할 수 있습니다.
파일 소유자만 쓰기 가능하도록 구성 파일에 대한 권한을 설정해야 합니다. KMS_PKCS11_CONFIG가 구성 파일을 가리키도록 합니다.
export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"
이 설정을 /etc/profile에 추가하여 영구적으로 설정할 수 있습니다.
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
OpenSSL 명령어 실행
엔진과 라이브러리가 올바르게 구성되었으면 이제 OpenSSL 명령어에 엔진을 사용할 수 있습니다.
비대칭 서명을 만들 때 Cloud KMS 키는 단일 다이제스트를 사용하도록 제한됩니다. 예를 들어 알고리즘 EC_SIGN_P256_SHA256이 있는 CryptoKeyVersion은 항상 SHA-256 다이제스트와 함께 사용되어야 합니다. 이는 OpenSSL의 -sha256 플래그에 해당합니다. SHA-384 또는 SHA-512 다이제스트가 필요한 키는 -sha384 또는 -sha512 플래그와 함께 사용되어야 합니다.
새 서명 만들기
구성된 키링에 foo라는 키가 있다고 가정하고 다음 명령어를 사용하여 bar.txt 위에 서명을 만듭니다.
openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt
이 명령어의 출력은 형식이 지정되지 않은 바이너리입니다.
이 명령어에서는 SHA-256 다이제스트를 사용하는 키가 사용된다고 가정하므로 -sha256 인수가 사용됩니다. -sha384 또는 -sha512 옵션은 이러한 다이제스트 유형을 사용하는 Cloud HSM 키에 적합합니다.
RSA-PSS 키의 경우 앞에서 설명한 -sigopt 옵션을 사용해야 합니다.
새 인증서 서명 요청 만들기
Cloud HSM 서명 키에 대한 인증서 서명 요청(CSR)을 생성할 수도 있습니다. 이 기능은 인증 기관에서 코드 서명에 사용할 새 인증서를 생성하거나 TLS 웹 세션을 보호하기 위해 CSR이 필요한 경우 유용합니다.
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.csr
새 자체 서명 인증서 생성
로컬 개발 및 테스트의 경우 Cloud HSM 서명 키에 자체 서명 인증서를 사용할 수 있습니다. 자체 서명 인증서는 SAML 토큰 서명에도 유용합니다.
openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.crt
PKCS #11 Spy로 문제 해결
PKCS #11 Spy는 PKCS #11 인터페이스를 통해 상호작용 콘텐츠를 로깅하는 오픈소스 도구입니다. 이를 위해서는 애플리케이션과 PKCS #11 라이브러리 사이에 배치하고 수행되는 모든 호출을 로깅해야 합니다. 이는 문제 해결에 유용할 수 있습니다.
PKCS #11 Spy를 사용하려면 opensc 패키지가 설치되어 있어야 합니다. opensc 패키지에는 PKCS #11 Spy가 포함되어 있습니다. opensc가 설치되었는지 확인하려면 다음 명령어를 실행합니다.
sudo apt-get install opensc
그 후 다음 명령어를 실행하여 PKCS #11 Spy 라이브러리에서 OpenSSL을 가리키도록 PKCS11_MODULE_PATH 환경 변수를 설정합니다.
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
마지막으로 PKCS11SPY 및 PKCS11SPY_OUTPUT 환경 변수를 설정하여 PKCS #11 Spy가 Cloud HSM PKCS #11 라이브러리를 가리키도록 합니다. 이러한 환경 변수를 설정하려면 다음 명령어를 실행합니다.
export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"