HSM PKCS11 seal 구성

HSM PKCS11 seal 구성

PKCS11 seal은 Vault가 PKCS11을 사용하는 HSM을 seal wrapping 메커니즘으로 사용하도록 구성합니다. Vault Enterprise의 HSM PKCS11 지원은 다음 중 하나로 활성화됩니다:

출처: 문서

본문

Auto-unseal 및 seal wrapping에는 Vault Enterprise가 필요합니다 PKCS11의 auto-unseal 및 seal wrapping은 Vault Enterprise가 필요합니다. Vault Enterprise는 기본적으로 seal wrapping을 활성화하므로 KMS 서비스가 봉인 해제 과정 중뿐만 아니라 런타임에도 사용 가능해야 합니다. 자세한 내용은 Seal wrap overview를 참고하세요.

  • Vault 구성 파일에 seal "pkcs11" 블록이 있는 경우
  • 환경 변수 VAULT_HSM_LIB가 라이브러리 경로로 설정되고 VAULT_SEAL_TYPE이 pkcs11로 설정된 경우. 환경 변수로 활성화한다면 다른 필수 값(즉 VAULT_HSM_SLOT)도 제공해야 합니다.

중요: Vault가 자체 키를 생성하게 하는 것이 가장 쉽게 시작하는 방법이지만, 보안상 Vault는 키를 비내보내기(non-exportable)로 표시합니다. HSM 키 백업 전략에 키가 내보내기 가능해야 한다면 직접 키를 생성해야 합니다. Vault가 키를 생성하는 데 사용하는 생성 속성 목록은 이 문서 끝에 나와 있습니다.

요구 사항

Vault Enterprise HSM에는 다음 소프트웨어 패키지가 필요합니다:

  • PKCS#11 호환 HSM 통합 라이브러리. Vault는 PKCS#11 버전 2.2 이상을 대상으로 합니다. 특정 HSM에 따라 일부 함수(예: 키 생성)는 수동으로 수행해야 할 수 있습니다.
  • GNU libltdl 라이브러리 — 서버의 올바른 아키텍처용으로 설치되었는지 확인하세요.

기본 pkcs11 예시

이 예시는 모든 필수 값을 제공해 Vault 구성 파일을 통해 HSM PKCS11 seal을 구성합니다:

seal "pkcs11" {
  lib            = "/usr/vault/lib/libCryptoki2_64.so"
  slot           = "2305843009213693953"
  pin            = "AAAA-BBBB-CCCC-DDDD"
  key_label      = "vault-hsm-key"
  hmac_key_label = "vault-hsm-hmac-key"
}

IBM EP11 토큰과 pkcs11 사용

IBM EP11 토큰과 함께 pkcs11 seal을 사용하려면 opencryptoki가 설치되어 있어야 하며, LinuxOne 또는 Linux on IBM Z 인스턴스에서 Crypto Express 어댑터가 활성화되어 있어야 합니다. 자세한 내용은 IBM EP11 Token Documentation을 참고하세요.

seal "pkcs11" {
  lib                 = "/usr/local/lib/opencryptoki/libopencryptoki.so"
  slot                = "4"
  pin                 = "12345678"
  key_label           = "vault_hsm_key"
  hmac_key_label      = "vault_hsm_hmac_key"
  generate_key        = true
}

pkcs11 파라미터

다음 파라미터는 Vault 구성 파일의 seal 스탠자에 적용됩니다:

  • lib (string: <required>): PKCS#11 라이브러리 공유 객체 파일의 경로입니다. VAULT_HSM_LIB 환경 변수로도 지정할 수 있습니다.

    참고: HSM에 따라 lib 파라미터의 값은 바이너리 또는 동적 라이브러리일 수 있으며, Vault 바이너리가 현재 실행 중인 시스템에 따라 다른 라이브러리가 필요할 수 있습니다(예: Linux 시스템이 Windows .dll 파일을 해석하기 위해 다른 라이브러리가 필요할 수 있음).

  • slot (string: <slot or token label required>): 사용할 슬롯 번호로, 문자열로 지정합니다(예: "2305843009213693953"). VAULT_HSM_SLOT 환경 변수로도 지정할 수 있습니다.

    참고: 슬롯은 보통 OS 설정 유틸리티에서 16진수 값으로 나열되지만, 이 구성은 10진수 등가값을 사용합니다. 예를 들어 HSM 명령줄 pkcs11-tool을 사용하면 16진수 0x2000000000000001로 나열된 슬롯은 10진수 2305843009213693953과 같습니다. 이 값들은 사용 중인 HSM에 따라 더 짧게 또는 다르게 나열될 수 있습니다.

  • token_label (string: <slot or token label required>): 사용할 슬롯 토큰 라벨입니다. VAULT_HSM_TOKEN_LABEL 환경 변수로도 지정할 수 있습니다.

  • pin (string: <required>): 로그인용 PIN입니다. VAULT_HSM_PIN 환경 변수로도 지정할 수 있습니다. 환경 변수로 설정하면 Vault를 다시 시작할 때 다시 설정해야 합니다.

  • key_label (string: <required>): 사용할 키의 라벨입니다. 키가 없고 생성이 활성화되어 있다면 이 라벨이 생성된 키에 부여됩니다. VAULT_HSM_KEY_LABEL 환경 변수로도 지정할 수 있습니다.

  • default_key_label (string: ""): 복호화 작업을 위한 기본 키 라벨입니다. 0.10.1 이전에는 키 라벨이 암호문과 함께 저장되지 않았습니다. 이제 seal 항목은 암호화 작업에 사용된 라벨을 추적합니다. 이 필드의 기본값은 key_label입니다. key_label이 회전되고 이 값이 설정되지 않으면 복호화가 실패할 수 있습니다. VAULT_HSM_DEFAULT_KEY_LABEL 환경 변수로도 지정할 수 있습니다. 이 값은 새 설치에서는 무시됩니다.

  • key_id (string: ""): 사용할 키의 ID입니다. 값은 16진수 문자열이어야 합니다(예: "0x33333435363434373537"). VAULT_HSM_KEY_ID 환경 변수로도 지정할 수 있습니다.

  • hmac_key_label (string: <required>): HMAC에 사용할 키의 라벨입니다. 적절한 유형이어야 합니다. Vault가 이를 만들려 하면 CKK_GENERIC_SECRET_KEY를 사용하려 시도합니다. 키가 없고 생성이 활성화되어 있다면 이 라벨이 생성된 키에 부여됩니다. VAULT_HSM_HMAC_KEY_LABEL 환경 변수로도 지정할 수 있습니다.

  • default_hmac_key_label (string: ""): 서명 작업을 위한 기본 HMAC 키 라벨입니다. 0.10.1 이전에는 HMAC 키 라벨이 서명과 함께 저장되지 않았습니다. 이제 seal 항목은 서명 작업에 사용된 라벨을 추적합니다. 이 필드의 기본값은 hmac_key_label입니다. hmac_key_label이 회전되고 이 값이 설정되지 않으면 서명 검증이 실패할 수 있습니다. VAULT_HSM_HMAC_DEFAULT_KEY_LABEL 환경 변수로도 지정할 수 있습니다. 이 값은 새 설치에서는 무시됩니다.

  • hmac_key_id (string: ""): 사용할 HMAC 키의 ID입니다. 값은 16진수 문자열이어야 합니다(예: "0x33333435363434373537"). VAULT_HSM_HMAC_KEY_ID 환경 변수로도 지정할 수 있습니다.

  • mechanism (string: <best available>): 사용할 암호화/복호화 메커니즘으로, 10진수 또는 16진수(0x 접두사) 문자열로 지정합니다. VAULT_HSM_MECHANISM 환경 변수로도 지정할 수 있습니다. 현재 지원되는 메커니즘(우선순위 순서):

    • 0x1085 CKM_AES_CBC_PAD (HMAC 메커니즘 필요)
    • 0x1082 CKM_AES_CBC (HMAC 메커니즘 필요)
    • 0x1087 CKM_AES_GCM
    • 0x0009 CKM_RSA_PKCS_OAEP
    • 0x0001 CKM_RSA_PKCS

    경고: CKM_RSA_PKCS는 OAEP보다 덜 안전한 것으로 간주되는 PKCS #1 v1.5 패딩 방식을 지정합니다. 가능하면 CKM_RSA_PKCS보다 CKM_RSA_PKCS_OAEP 사용을 권장합니다.

  • hmac_mechanism (string: "0x0251"): 사용할 암호화/복호화 메커니즘으로, 10진수 또는 16진수(0x 접두사) 문자열로 지정합니다. 현재 0x0251(사양의 CKM_SHA256_HMAC에 해당)만 지원됩니다. VAULT_HSM_HMAC_MECHANISM 환경 변수로도 지정할 수 있습니다. 이 값은 특정 메커니즘에만 필요합니다.

  • generate_key (string: "false"): Vault 초기화 시 key_label로 지정된 라벨의 기존 키를 찾을 수 없으면 Vault가 키를 생성하도록 지시합니다. 문자열로 표현된 부울입니다(예: "true"). VAULT_HSM_GENERATE_KEY 환경 변수로도 지정할 수 있습니다. 적절한 유형의 키를 만들기 위해 독점 벤더 확장이 필요한 경우처럼 일부 상황에서는 Vault가 키를 성공적으로 생성하지 못할 수 있습니다.

    참고: 클러스터 초기화 후 초기 키 생성이 발생하면, 향후 의도하지 않은 키 생성을 방지하기 위해 이 플래그를 비활성화하는 것이 좋습니다.

  • force_rw_session (string: "false"): 모든 작업이 HSM에 대한 읽기-쓰기 세션을 열도록 강제합니다. 문자열로 표현된 부울입니다(예: "true"). VAULT_HSM_FORCE_RW_SESSION 환경 변수로도 지정할 수 있습니다. 이 키는 주로 AWS CloudHSM v5 pkcs11 구현 내의 제한을 우회하기 위한 것입니다.

  • max_parallel (int: 1) - 특정 시점에 HSM으로 진행 중일 수 있는 동시 요청 수입니다.

  • disabled (string: ""): Vault가 auto seal 구성에서 마이그레이션 중이라면 true로 설정하세요. 그렇지 않으면 false로 설정하세요.

pin은 간접 값 참조(indirect value references)일 수 있습니다.

seal 마이그레이션 과정에 대한 자세한 내용은 Seal Migration 문서를 참고하세요.

메커니즘별 플래그

  • rsa_encrypt_local (string: "false"): RSA 키에 대한 암호화를 지원하지 않는 HSM의 경우 암호화를 로컬로 수행합니다. CKM_RSA_PKCS_OAEP 및 CKM_RSA_PKCS 메커니즘에 사용 가능합니다. VAULT_HSM_RSA_ENCRYPT_LOCAL 환경 변수로도 지정할 수 있습니다.

  • rsa_oaep_hash (string: "sha256"): OAEP 패딩과 함께 RSA에 사용할 해시 알고리즘을 지정합니다. 유효한 값은 sha1, sha224, sha256, sha384, sha512입니다. CKM_RSA_PKCS_OAEP 메커니즘에 사용 가능합니다. VAULT_HSM_RSA_OAEP_HASH 환경 변수로도 지정할 수 있습니다.

참고: 구성 파일에서 VAULT_HSM_PIN을 seal 파라미터로 전달할 수 있지만, 이 값을 환경 변수로 설정하는 것을 강력히 권장합니다.

pkcs11 환경 변수

또는 다음 환경 변수를 제공해 HSM seal을 활성화할 수 있습니다:

VAULT_SEAL_TYPE
VAULT_HSM_LIB
VAULT_HSM_SLOT
VAULT_HSM_TOKEN_LABEL
VAULT_HSM_PIN
VAULT_HSM_KEY_LABEL
VAULT_HSM_DEFAULT_KEY_LABEL
VAULT_HSM_KEY_ID
VAULT_HSM_HMAC_KEY_LABEL
VAULT_HSM_HMAC_DEFAULT_KEY_LABEL
VAULT_HSM_HMAC_KEY_ID
VAULT_HSM_MECHANISM
VAULT_HSM_HMAC_MECHANISM
VAULT_HSM_GENERATE_KEY
VAULT_HSM_RSA_ENCRYPT_LOCAL
VAULT_HSM_RSA_OAEP_HASH
VAULT_HSM_FORCE_RW_SESSION

Vault 키 생성 속성

Vault가 HSM 키를 생성한다면 다음은 Vault가 사용하는 속성 목록입니다. 이 식별자는 공식 PKCS#11 식별자에 해당합니다.

AES 키

  • CKA_CLASS: CKO_SECRET_KEY (시크릿 키)
  • CKA_KEY_TYPE: CKK_AES (키 유형은 AES)
  • CKA_VALUE_LEN: 32 (키 크기는 256비트)
  • CKA_LABEL: Vault 구성에 설정된 키 라벨로 설정됨
  • CKA_ID: 무작위 32비트 부호 없는 정수로 설정됨
  • CKA_PRIVATE: true (키는 이 슬롯/토큰에 개인)
  • CKA_TOKEN: true (키는 단일 세션만이 아니라 슬롯/토큰에 유지됨)
  • CKA_SENSITIVE: true (키는 민감한 값)
  • CKA_ENCRYPT: true (키는 암호화에 사용 가능)
  • CKA_DECRYPT: true (키는 복호화에 사용 가능)
  • CKA_WRAP: true (키는 래핑에 사용 가능)
  • CKA_UNWRAP: true (키는 언래핑에 사용 가능)
  • CKA_EXTRACTABLE: false (키는 내보낼 수 없음)

RSA 키

공개 키(Public Key)

  • CKA_CLASS: CKO_PUBLIC_KEY (공개 키)
  • CKA_KEY_TYPE: CKK_RSA (키 유형은 RSA)
  • CKA_LABEL: Vault 구성에 설정된 키 라벨로 설정됨
  • CKA_ID: 무작위 32비트 부호 없는 정수로 설정됨
  • CKA_ENCRYPT: true (키는 암호화에 사용 가능)
  • CKA_WRAP: true (키는 래핑에 사용 가능)
  • CKA_MODULUS_BITS: 2048 (키 크기는 2048비트)
  • CKA_PUBLIC_EXPONENT: 0x10001 (공개 지수 65537)
  • CKA_TOKEN: true (키는 단일 세션만이 아니라 슬롯/토큰에 유지됨)

개인 키(Private Key)

  • CKA_CLASS: CKO_PRIVATE_KEY (개인 키)
  • CKA_KEY_TYPE: CKK_RSA (키 유형은 RSA)
  • CKA_LABEL: Vault 구성에 설정된 키 라벨로 설정됨
  • CKA_ID: 무작위 32비트 부호 없는 정수로 설정됨
  • CKA_DECRYPT: true (키는 복호화에 사용 가능)
  • CKA_UNWRAP: true (키는 언래핑에 사용 가능)
  • CKA_TOKEN: true (키는 단일 세션만이 아니라 슬롯/토큰에 유지됨)
  • CKA_EXTRACTABLE: false (키는 내보낼 수 없음)

HMAC 키

  • CKA_CLASS: CKO_SECRET_KEY (시크릿 키)
  • CKA_KEY_TYPE: CKK_GENERIC_SECRET_KEY (키 유형은 일반 시크릿 키)
  • CKA_VALUE_LEN: 32 (키 크기는 256비트)
  • CKA_LABEL: Vault 구성에 설정된 HMAC 키 라벨로 설정됨
  • CKA_ID: 무작위 32비트 부호 없는 정수로 설정됨
  • CKA_PRIVATE: true (키는 이 슬롯/토큰에 개인)
  • CKA_TOKEN: true (키는 단일 세션만이 아니라 슬롯/토큰에 유지됨)
  • CKA_SENSITIVE: true (키는 민감한 값)
  • CKA_SIGN: true (키는 서명에 사용 가능)
  • CKA_VERIFY: true (키는 검증에 사용 가능)
  • CKA_EXTRACTABLE: false (키는 내보낼 수 없음)

키 회전

이 seal은 서로 다른 키 라벨을 사용해 키 버전을 추적함으로써 키를 회전하는 것을 지원합니다. 키 값을 회전하려면 HSM의 다른 키 라벨에 새 키를 생성하고 Vault 구성을 새 키 라벨 값으로 갱신하세요. Vault 인스턴스를 다시 시작해 새 키 라벨을 적용하면 모든 새 암호화 작업이 갱신된 키 라벨을 사용합니다. 이전 키는 비활성화하거나 삭제해서는 안 되며 이전 데이터를 복호화하는 데 사용됩니다. 이전 키를 비활성화하거나 삭제하려면 Vault가 seal-rewrap을 수행해 이전 키로 암호화된 데이터를 새 키로 복호화할 수 있도록 해야 합니다.

참고: 0.10.1 이전 버전에서는 키 정보가 암호문과 함께 추적되지 않았습니다. 이 버전 이전에 seal wrapping된 데이터에 대해 회전을 원한다면 default_key_label과 hmac_default_key_label도 설정해 이전 값을 복호화할 수 있게 해야 합니다.

튜토리얼

HSM Integration - Seal Wrap 튜토리얼을 참고해 데이터를 보호하기 위해 Seal Wrap 기능을 활성화하는 방법을 알아보세요.

더 알아보기