Google Cloud KMS 시크릿 엔진

Google Cloud KMS 시크릿 엔진

Google Cloud KMS Vault 시크릿 엔진은 Google Cloud KMS를 통해 암호화와 키 관리를 제공해요. 키의 생성·회전·폐기를 포함한 키 관리를 지원하고, 관리 키로 데이터를 암호화·복호화하는 것도 지원해요. 덕분에 KMS 키를 Vault의 정책(policy)과 IAM 시스템을 통해 관리할 수 있어요.

출처: 문서

본문

설정(Setup)

대부분의 시크릿 엔진은 기능을 수행하기 전에 미리 구성해야 해요. 이 단계는 보통 운영자 또는 구성 관리 도구가 수행해요.

먼저 Google Cloud KMS 시크릿 엔진을 활성화해요.

$ vault secrets enable gcpkms
Success! Enabled the gcpkms secrets engine at: gcpkms/

기본적으로 시크릿 엔진은 엔진 이름 그대로의 경로에 마운트돼요. 다른 경로에 두고 싶다면 -path 인자를 사용하면 됩니다.

계정 자격 증명 및/또는 스코프로 시크릿 엔진을 구성해요.

$ vault write gcpkms/config \
    [email protected]
Success! Data written to: gcpkms/config

Vault를 Google Compute Engine이나 Google Kubernetes Engine 안에서 실행 중이라면, credentials JSON 파일을 지정하는 대신 인스턴스 또는 파드의 서비스 계정을 사용할 수 있어요. 인증에 대한 자세한 내용은 아래 인증 섹션을 참고하세요.

Google Cloud KMS 키를 생성해요.

$ vault write gcpkms/keys/my-key \
    key_ring=projects/my-project/locations/my-location/keyRings/my-keyring \
    rotation_period=72h

key_ring 파라미터는 projects/<project>/locations/<location>/keyRings/<keyring> 형식으로 지정하며, 각각은 다음을 의미해요.

  • <project> — GCP 프로젝트 이름 (예: "my-project")
  • <location> — KMS 키 링의 위치 (예: "us-east1", "global")
  • <keyring> — KMS 키 링의 이름 (예: "my-keyring")

사용법(Usage)

시크릿 엔진을 구성하고 사용자/머신이 적절한 권한을 가진 Vault 토큰을 갖고 있으면 키를 암호화·복호화·관리하는 데 사용할 수 있어요. 키를 관리하는 다양한 방법을 아래 섹션에서 살펴봐요.

대칭 암호화/복호화(Symmetric Encryption/Decryption)

Cloud KMS 키를 대칭 암호화/복호화에 사용하는 방법을 설명할게요. 이는 가장 흔한 암호화 유형 중 하나예요. Google Cloud는 데이터를 암호화·복호화하는 데 사용되는 키 링을 관리해요.

용도 지원 알고리즘
encrypt_decrypt symmetric_encryption

대칭 암호화/복호화에 적합한 키를 생성하거나 기존 키를 사용해요.

$ vault write gcpkms/keys/my-key \
    key_ring=projects/.../my-keyring \
    purpose=encrypt_decrypt \
    algorithm=symmetric_encryption

/encrypt 엔드포인트와 지정한 키로 평문 데이터를 암호화해요.

$ vault write gcpkms/encrypt/my-key plaintext="hello world"
Key            Value
---            -----
ciphertext     CiQAuMv0lTiKjrF43Lgr4...
key_version    1

Vault의 transit 백엔드와 달리 평문 데이터를 base64로 인코딩할 필요는 없어요. 엔드포인트가 자동으로 데이터를 변환해요. 참고로 Vault는 이 데이터를 저장하지 않아요. 결과 ciphertext를 저장하는 책임은 호출자에게 있어요.

/decrypt 엔드포인트와 지정한 키로 ciphertext를 복호화해요.

$ vault write gcpkms/decrypt/my-key ciphertext=CiQAuMv0lTiKjrF43Lgr4...
Key          Value
---          -----
plaintext    hello world

스크립팅을 더 쉽게 하려면 평문을 직접 추출할 수도 있어요.

$ vault write -field=plaintext gcpkms/decrypt/my-key ciphertext=CiQAuMv0lTiKjrF43Lgr4...
hello world

기반이 되는 암호화 키를 회전시켜요. 그러면 Google Cloud KMS에 새 crypto key version이 생성되고 이 버전이 활성 키로 설정돼요.

$ vault write -f gcpkms/keys/rotate/my-key
WARNING! The following warnings were returned from Vault:
* The crypto key version was rotated successfully, but it can take up to 2 hours for the new crypto key version to become the primary. In practice, it is usually much shorter. Be sure to issue a read operation and verify the key version if you require new data to be encrypted with this key.
Key            Value
---            -----
key_version    2

메시지가 말해주듯 회전은 즉시 이뤄지지 않아요. 여러 요인에 따라 새 키의 전파는 꽤 오래 걸릴 수 있어요. 이 새 키로 즉시 데이터를 암호화해야 한다면 API를 조회해 키가 primary가 되길 기다려야 해요. 또는 key_version 파라미터를 지정해 암호화에 사용할 정확한 키로 고정할 수도 있어요.

이미 암호화된 ciphertext를 새 버전의 crypto key로 다시 암호화할 수 있어요. Vault가 키 링의 적절한 키로 값을 복호화한 다음, 결과 평문을 키 링의 가장 새로운 키로 암호화해요.

$ vault write gcpkms/reencrypt/my-key ciphertext=CiQAuMv0lTiKjrF43Lgr4...
Key            Value
---            -----
ciphertext     CiQAuMv0lZTTozQA/ElqM...
key_version    2

이 과정은 평문 데이터를 드러내지 않아요. 그래서 Vault 정책으로 신뢰할 수 없는 프로세스에 ciphertext를 다시 암호화(re-encrypt)할 권한을 줄 수도 있어요 — 그 프로세스는 평문 데이터에 접근할 수 없으니까요.

키에 허용된 min_version보다 오래된 Cloud KMS crypto key version을 삭제해 이전 키 버전을 정리해요.

$ vault write gcpkms/keys/config/my-key min_version=10

그런 다음 버전 10보다 오래된 키를 모두 삭제해요. 이러면 기존 방식으로는 이전 키로 값을 암호화·복호화·서명할 수 없게 돼요.

$ vault write -f gcpkms/keys/trim/my-key

키를 삭제하면 모든 키 버전과 Vault의 키 기록이 삭제돼요. 이러면 기존 방식으로 값을 암호화·복호화·서명할 수 없게 돼요.

$ vault delete gcpkms/keys/my-key

비대칭 복호화(Asymmetric decryption)

Cloud KMS 키를 비대칭 복호화에 사용하는 방법을 설명할게요. 이 모델에서는 Google Cloud가 키 링을 관리하고 공개 키를 API 엔드포인트로 노출해요. 공개 키로 데이터를 오프라인에서 암호화해 ciphertext를 만들고, 평문이 필요해지면 사용자가 ciphertext를 Cloud KMS에 제출하면 Cloud KMS가 해당 개인 키로 복호화해요.

용도 지원 알고리즘
asymmetric_decrypt rsa_decrypt_oaep_2048_sha256, rsa_decrypt_oaep_3072_sha256, rsa_decrypt_oaep_4096_sha256

비대칭 복호화에 적합한 키를 생성하거나 기존 키를 사용해요.

$ vault write gcpkms/keys/my-key \
    key_ring=projects/.../my-keyring \
    purpose=asymmetric_decrypt \
    algorithm=rsa_decrypt_oaep_4096_sha256

Cloud KMS에서 공개 키를 가져와요.

$ gcloud kms keys versions get-public-key <crypto-key-version> \
    --location <location> \
    --keyring <key-ring> \
    --key <key> \
    --output-file ~/mykey.pub

공개 키로 평문 데이터를 암호화해요. 구현 방법은 프로그래밍 언어마다 크게 달라요. 아래 예시는 OpenSSL을 사용하지만, 언어의 내장 기능을 사용해도 돼요.

$ openssl pkeyutl -in ~/my-secret-file \
    -encrypt -pubin \
    -inkey ~/mykey.pub \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256

이 암호화는 오프라인(즉 Vault 밖에서)으로 일어나고, 공개 키로 이뤄진다는 점을 알아 두세요. 대응하는 개인 키는 오직 Cloud KMS만 갖고 있어요.

/decrypt 엔드포인트와 지정한 키로 ciphertext를 복호화해요.

$ vault write gcpkms/decrypt/my-key key_version=1 ciphertext=CiQAuMv0lTiKjrF43Lgr4...
Key          Value
---          -----
plaintext    hello world

비대칭 서명(Asymmetric signing)

Cloud KMS 키를 비대칭 서명에 사용하는 방법을 설명할게요. 이 모델에서는 Google Cloud가 키 링을 관리하고 공개 키를 API 엔드포인트로 노출해요. 메시지나 다이제스트(digest)는 대응하는 개인 키로 서명되며, 대응하는 공개 키를 가진 누구나 검증할 수 있어요.

용도 지원 알고리즘
asymmetric_sign rsa_sign_pss_2048_sha256, rsa_sign_pss_3072_sha256, rsa_sign_pss_4096_sha256, rsa_sign_pkcs1_2048_sha256, rsa_sign_pkcs1_3072_sha256, rsa_sign_pkcs1_4096_sha256, ec_sign_p256_sha256, ec_sign_p384_sha384

비대칭 서명에 적합한 키를 생성하거나 기존 키를 사용해요.

$ vault write gcpkms/keys/my-key \
    key_ring=projects/.../my-keyring \
    purpose=asymmetric_sign \
    algorithm=ec_sign_p384_sha384

base64 인코딩된 바이너리 다이제스트를 계산해요. 키 유형에 대응하는 해싱 알고리즘을 사용해요.

$ export DIGEST=$(openssl dgst -sha384 -binary /my/file | base64)

Cloud KMS에 다이제스트 서명을 요청해요.

$ vault write gcpkms/sign/my-key key_version=1 digest=$DIGEST
Key          Value
---          -----
signature    MGYCMQDbOS2462SKMsGdh2GQ...

다이제스트의 서명을 검증해요.

$ vault write gcpkms/verify/my-key key_version=1 digest=$DIGEST signature=$SIGNATURE
Key      Value
---      -----
valid    true

참고로 Vault 없이도 이 서명을 검증할 수 있어요. Cloud KMS에서 공개 키를 내려받아 OpenSSL 같은 도구나 프로그래밍 언어의 기본 기능으로 서명을 검증하면 됩니다.

인증(Authentication)

Google Cloud KMS Vault 시크릿 백엔드는 공식 Google Cloud Golang SDK를 사용해요. 즉 Google Cloud에 자격 증명을 제공하는 일반적인 방법을 지원해요. Vault 구성으로 직접 자격 증명을 지정하는 것 외에도, Vault 서버에서 다음 값으로 구성을 가져올 수 있어요.

  1. GOOGLE_APPLICATION_CREDENTIALS 환경 변수 — Google Cloud 자격 증명 파일(보통 서비스 계정용)의 경로로 지정돼요. 이 환경 변수가 있으면 그 자격 증명이 사용돼요. 자격 증명이 유효하지 않으면 오류가 반환돼요.
  2. 기본 인스턴스 자격 증명 — 환경 변수가 없으면 기본 서비스 계정 자격 증명이 사용돼요. Vault를 Google Compute Engine이나 Google Kubernetes Engine에서 실행할 때 유용해요.

서비스 계정에 대한 자세한 내용은 Google Cloud Service Accounts 문서를 참고하세요.

이 시크릿 엔진을 사용하려면 서비스 계정이 다음 최소 스코프를 가져야 해요.

https://www.googleapis.com/auth/kms

필요 권한 — Vault에 주어지는 자격 증명은 다음 역할을 가져야 해요.

roles/cloudkms.admin

Vault가 키를 생성하지 않을 거라면 권한을 줄일 수 있어요. 예를 들어 키를 별도로 생성하고 Vault는 암호화/복호화만 관리하게 하려면 다음 권한만 있으면 돼요.

roles/cloudkms.cryptoKeyEncrypterDecrypter

서명과 검증만 하려면 다음 권한만 있으면 돼요.

roles/cloudkms.signerVerifier

자세한 내용은 Google Cloud KMS IAM 문서를 참고하세요.

자주 묻는 질문(FAQ)

이건 Vault의 transit 시크릿 엔진과 뭐가 다른가요? Vault의 transit 시크릿 엔진은 인메모리 키로 키를 암호화/복호화해요. 일반적으로 더 빠르고 성능이 좋아요. 하지만 물리적·오프사이트·대역 외(out-of-band) 키 관리를 원하는 사용자는 Google Cloud KMS 시크릿 엔진으로 그 이점을 얻으면서 Vault의 정책과 identity 시스템도 함께 활용할 수 있어요.

Vault가 기존 KMS 키를 쓸 수 있나요? /register 엔드포인트로 Vault가 기존 Google Cloud KMS 키와 대화하도록 구성할 수 있어요. IAM 권한만 올바르면 Vault는 데이터를 암호화/복호화하고 키를 회전시킬 수 있어요. 자세한 내용은 API 문서를 참고하세요.

HSM 같은 하드웨어 키와 함께 쓸 수 있나요? 네! 키를 만들 때 protection_level을 "hsm"으로 설정하거나, HSM이 뒷받침하는 기존 Cloud KMS 키를 사용하면 돼요.

비용은 얼마인가요? 플러그인은 무료이고 오픈소스예요. KMS 비용은 키 유형과 작업 수에 따라 달라져요. 자세한 내용은 Cloud KMS pricing 페이지를 참고하세요.

도움말 및 지원(Help & support)

Google Cloud KMS Vault 시크릿 엔진은 외부 Vault 플러그인으로 작성됐어요. 코드는 메인 Vault 저장소 밖에 있고, Vault 릴리스에 자동으로 번들되지만 관리는 별도로 이뤄져요.

이슈 보고, 기능 요청, 기여는 GitHub의 vault-plugin-secrets-gcpkms 저장소로 해주세요.

API

Google Cloud KMS 시크릿 엔진은 완전한 HTTP API를 갖고 있어요. 자세한 내용은 Google Cloud KMS 시크릿 엔진 API 문서를 참고하세요.

더 알아보기 (Learn more)

  • Google Cloud KMS 시크릿 엔진 API 문서에서 HTTP API를 확인해 보세요.
  • GitHub vault-plugin-secrets-gcpkms 저장소에 이슈나 기여를 남겨 보세요.