My Awesome Project

Appearance

Cloud KMS Key Hierarchy — Key Ring, CryptoKey, CryptoKeyVersion ​

Tại sao hierarchy quan trọng ​

Cloud KMS không phải một "kho keys" đơn giản — nó là một hệ thống quản lý key với hierarchy ba tầng và nhiều loại resource có quan hệ phức tạp. Hiểu sai hierarchy này dẫn đến hai vấn đề phổ biến:

  1. Overly broad IAM: Cấp quyền ở tầng quá cao (Project hoặc Key Ring) thay vì tầng cần thiết (CryptoKey), vi phạm least-privilege
  2. Wrong location: Tạo key ở wrong location làm tăng latency cho encrypt/decrypt operations và có thể vi phạm data residency

Quan trọng hơn, nhiều property của key — purpose, protection level, algorithm — là immutable sau khi tạo. Không có "undo" button. Hiểu rõ hierarchy trước khi create key tránh được costly mistakes.

Internal model — Ba tầng tài nguyên ​

Tầng 1: Key Ring ​

Key Ring là container tổ chức cho keys. Nó không chứa key material, không thực hiện cryptographic operations — chức năng duy nhất của nó là:

  1. Nhóm keys theo mục đích, application, hoặc team
  2. Gắn với một location cụ thể (region hoặc global)
  3. Làm điểm gắn IAM cho nhóm keys
Resource ID:
projects/{project}/locations/{location}/keyRings/{key-ring-name}

Ví dụ:
projects/my-project/locations/us-central1/keyRings/production-keys
projects/my-project/locations/global/keyRings/signing-keys

Đặc điểm quan trọng nhất của Key Ring: Không thể xóa. Một khi tạo, Key Ring tồn tại vĩnh viễn trong project. Đây là thiết kế có chủ đích — xóa Key Ring sẽ xóa tất cả keys trong đó, có thể gây mất dữ liệu không phục hồi được.

Location của Key Ring quyết định nơi key material được lưu và nơi cryptographic operations xảy ra. Không thể thay đổi sau khi tạo.

Locations phổ biến:

  • us-central1, europe-west1, asia-northeast1 — regional key rings
  • us, europe, asia — multi-regional key rings (data stored in geographic area)
  • global — keys available globally, nhưng không phù hợp cho data residency compliance

Về IAM trên Key Ring: Gắn IAM binding lên Key Ring cấp quyền trên tất cả keys trong ring đó (kế thừa xuống). Thực tế production: nên cấp IAM ở cấp CryptoKey khi có thể.

Tầng 2: CryptoKey (Key) ​

CryptoKey là key logic — nó định nghĩa mục đích, thuật toán, và protection level. CryptoKey là đơn vị bạn tham chiếu khi gọi encrypt/decrypt/sign.

Resource ID:
projects/{project}/locations/{location}/keyRings/{ring}/cryptoKeys/{key-name}

Ví dụ:
projects/my-project/locations/us-central1/keyRings/prod/cryptoKeys/database-encryption-key

Các property immutable sau khi tạo:

  • Purpose (mục đích sử dụng)
  • Protection Level (SOFTWARE, HSM, EXTERNAL, EXTERNAL_VPC)
  • Algorithm (cho version đầu tiên, nhưng version mới có thể khác — trong giới hạn)

Các property mutable:

  • nextRotationTime và rotationPeriod
  • Labels
  • IAM policy
  • VersionDestroyTtl (thời gian trước khi version bị destroy)

Primary version: Đối với symmetric keys (ENCRYPT_DECRYPT purpose), CryptoKey luôn có một "primary version" — version được dùng mặc định khi gọi Encrypt() mà không specify version. Primary version chỉ có nghĩa với symmetric keys; asymmetric keys không có khái niệm primary.

Tầng 3: CryptoKeyVersion ​

CryptoKeyVersion là nơi key material thực sự tồn tại. Mỗi version chứa:

  • Key material (không thể export ra ngoài KMS, ngoại trừ khi dùng import jobs)
  • Algorithm (AES-256-GCM, RSA-2048, EC-P256, ...)
  • Protection level của version đó
  • State của version
Resource ID:
projects/{project}/locations/{location}/keyRings/{ring}/cryptoKeys/{key}/cryptoKeyVersions/{version}

Ví dụ:
projects/my-project/locations/us-central1/keyRings/prod/cryptoKeys/db-key/cryptoKeyVersions/3

Mỗi rotation tạo ra một CryptoKeyVersion mới. Version có số thứ tự tự động tăng (1, 2, 3...). Version cũ không bị xóa tự động — chúng vẫn available để decrypt data đã được mã hoá bằng chúng, cho đến khi bị explicitly destroy.

Key Purposes ​

Purpose quyết định operation nào được phép với key, và không thể thay đổi sau khi tạo. Hiểu purposes là điều kiện tiên quyết để chọn đúng key type.

ENCRYPT_DECRYPT (Symmetric Encryption) ​

Dùng để mã hoá và giải mã dữ liệu với symmetric key (AES-GCM).

Operation: Encrypt(plaintext) → ciphertext
           Decrypt(ciphertext) → plaintext

Use case: CMEK, envelope encryption (DEK wrapping), data encryption
Algorithm: AES-256-GCM (default và recommended)
Ciphertext size: plaintext size + overhead (~50 bytes cho GCM tag)

Giới hạn kích thước: Plaintext tối đa 64 KiB (SOFTWARE protection level). HSM giới hạn ở 8 KiB. Đây là lý do tại sao KMS không được dùng để encrypt large data trực tiếp — thay vào đó dùng envelope encryption (mã hoá DEK bằng KMS key, dùng DEK để mã hoá data lớn).

Đây là purpose duy nhất hỗ trợ automatic rotation.

ASYMMETRIC_SIGN (Asymmetric Signing) ​

Dùng để ký và verify chữ ký số với asymmetric key.

Operation: Sign(message_digest) → signature
           (Verify được thực hiện bằng public key, không cần KMS)

Use case: Binary Authorization attestation, JWT signing, code signing
Algorithms: EC_SIGN_P256_SHA256, EC_SIGN_P384_SHA384,
            RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PSS_4096_SHA512, ...

Chỉ signature operation cần KMS (private key không bao giờ rời KMS). Public key có thể được export và distribute.

Không hỗ trợ automatic rotation — vì public key được distribute rộng rãi, rotation cần coordinated update ở phía verify.

ASYMMETRIC_DECRYPT (Asymmetric Decryption) ​

Dùng để encrypt với public key và decrypt với private key trong KMS.

Operation: Encrypt (bên ngoài KMS, dùng public key)
           Decrypt(ciphertext) → plaintext (trong KMS, dùng private key)

Use case: Key wrapping, credential exchange
Algorithm: RSA-OAEP-2048-SHA256, RSA-OAEP-4096-SHA512

Ít dùng hơn trong modern architectures vì envelope encryption thường dùng symmetric DEK.

MAC (Message Authentication Code) ​

Dùng để generate và verify HMAC, đảm bảo tính toàn vẹn của data (không phải bí mật).

Operation: GenerateMac(data) → mac_tag
           VerifyMac(data, mac_tag) → valid/invalid

Use case: Webhook signature verification, API request signing
Algorithm: HMAC-SHA256

Protection Levels ​

Protection level quyết định nơi và cách key material được lưu trữ. Đây là một trong những quyết định quan trọng nhất khi thiết kế key management strategy.

SOFTWARE ​

Key material được lưu trong Google's software-based key management infrastructure (Keystore), được bảo vệ bởi hardware security infrastructure của Google nhưng không phải trong dedicated HSM.

Plaintext limit: 64 KiB
Latency: Thấp nhất
Cost: Thấp nhất
Compliance: Meets most requirements
FIPS 140-2: Level 1

Phù hợp cho: Hầu hết use cases production không có strict hardware requirement. Data encryption, CMEK cho GCP services, JWT signing.

HSM (Hardware Security Module) ​

Key material được lưu trong FIPS 140-2 Level 3 certified HSM clusters do Google quản lý. Operations xảy ra inside HSM hardware.

Plaintext limit: 8 KiB (giới hạn HSM hardware)
Latency: Cao hơn SOFTWARE (thêm ~1-5ms cho asymmetric operations)
Cost: Cao hơn (~$1/key/month vs $0.06/key/month cho SOFTWARE)
FIPS 140-2: Level 3

Lý do giới hạn 8 KiB: HSM hardware có internal buffer size giới hạn. Để encrypt data lớn hơn 8 KiB với HSM protection, cần dùng envelope encryption (wrap DEK với HSM key, dùng DEK để encrypt data).

Khi nào HSM bắt buộc:

  • PCI DSS Level 1 (yêu cầu hardware-based key protection)
  • FIPS 140-2 Level 3 compliance
  • Regulated financial services với audit requirement về physical key protection

Cạm bẫy latency với HSM: Asymmetric operations (RSA sign/verify) với HSM key có thể chậm hơn SOFTWARE 5-10x. Nếu signing path của bạn cần <1ms latency ở p99, HSM có thể không phù hợp.

HSM_SINGLE_TENANT ​

Giống HSM nhưng dùng dedicated HSM không shared với customers khác. Dành cho regulated workloads với isolation requirement cao nhất.

Cost: Cao nhất (dedicated hardware)
Isolation: Complete physical isolation
Availability: Limited regions

EXTERNAL (Cloud EKM) ​

Key material được lưu bên ngoài Google infrastructure, trong external key management system của customer hoặc third-party.

Availability: Phụ thuộc vào external KMS availability
Latency: Thêm network round-trip đến external KMS
Risk: Data inaccessible nếu external key bị mất/unavailable

Chi tiết về EXTERNAL và EXTERNAL_VPC được phân tích trong file 06.cloud-ekm.md.

So sánh trade-offs ​

Protection    FIPS Level   Latency    Cost      Data Residency    Use Case
──────────────────────────────────────────────────────────────────────────
SOFTWARE      L1           Thấp nhất  Thấp      Google controls   90% cases
HSM           L3           Trung bình Cao hơn   Google controls   Regulated
HSM_SINGLE    L3           Trung bình Cao nhất  Google controls   Strict isolation
EXTERNAL      Tùy EKM      Cao nhất   Variable  Customer controls HYOK requirement
EXTERNAL_VPC  Tùy EKM      Cao        Variable  Customer controls HYOK via VPC

Primary Version — cơ chế và ý nghĩa ​

Primary version là khái niệm chỉ tồn tại cho ENCRYPT_DECRYPT keys (symmetric). Nó xác định version nào được dùng khi caller không specify version number.

Cách KMS resolve primary version ​

Khi bạn gọi:

Encrypt(key: "projects/p/keyRings/r/cryptoKeys/my-key", plaintext: ...)

Không có version trong resource path → KMS dùng primary version của my-key.

Khi rotation xảy ra (tự động hoặc thủ công), KMS:

  1. Tạo CryptoKeyVersion mới
  2. Set version mới làm primary
  3. Version cũ vẫn tồn tại ở trạng thái ENABLED (có thể decrypt ciphertext cũ)

Ciphertext tạo ra bởi Encrypt() embed version information — khi giải mã, KMS tự động dùng đúng version, không cần caller track version.

Điều này có nghĩa gì: Sau rotation, data cũ vẫn decrypt được (vì version cũ vẫn tồn tại). Data mới sẽ được encrypt bằng version mới. Cả hai coexist cho đến khi bạn chủ động destroy version cũ.

Ciphertext cấu trúc và version binding ​

Mọi ciphertext từ Cloud KMS bao gồm key version reference nhúng bên trong. Khi decrypt, KMS parse ciphertext để xác định version cần dùng và check version còn ENABLED hay không.

Đây là lý do:

  • Bạn không cần track "ciphertext này được mã hoá bằng version nào"
  • Nhưng nếu version bị DESTROYED, ciphertext tương ứng không thể decrypt được mãi mãi

Số lượng keys và granularity ​

Một quyết định kiến trúc phổ biến: nên dùng một key cho nhiều purposes hay nhiều keys granular?

Anti-pattern: One key for everything ​

prod-master-key  → mã hoá database, storage, backups, logs, everything

Vấn đề:

  • Nếu key bị compromise, mọi thứ bị ảnh hưởng
  • Không có audit granularity (log chỉ nói "my-key được dùng", không biết bởi service nào)
  • Không thể revoke access cho một service cụ thể mà không ảnh hưởng đến tất cả

Best practice: Purpose-specific keys với IAM isolation ​

database-encryption-key      → Cloud SQL CMEK (Cloud SQL service account có access)
storage-encryption-key       → Cloud Storage CMEK
backup-encryption-key        → Backup encryption
signing-key                  → JWT/attestation signing

Mỗi key có IAM binding riêng cho service account tương ứng. IAM audit log sẽ show chính xác "Cloud SQL service account dùng database-encryption-key lúc 14:32:01".

Constraints và giới hạn thực tế ​

Giới hạn số tài nguyên ​

  • Key Rings per project per location: Không có hard limit (practical limit: hàng nghìn)
  • CryptoKeys per Key Ring: 10,000
  • CryptoKeyVersions per CryptoKey: Không có hard limit, nhưng nhiều versions destroyed tích lũy → tăng API response time cho list operations
  • Concurrent cryptographic operations: Depends on quota (default thường đủ, tăng được)

Giới hạn rotation period ​

  • Tối thiểu: 24 giờ
  • Tối đa: 876,000 giờ (~100 năm)

Key name immutability ​

Tên Key Ring và CryptoKey không thể thay đổi sau khi tạo. Cũng không thể move key sang key ring khác hay location khác. Nếu thiết kế sai, phải tạo mới và re-encrypt data.

Không thể export key material (trừ một ngoại lệ) ​

SOFTWARE và HSM keys không thể export. Key material không bao giờ rời Cloud KMS. Đây là thiết kế bảo mật cốt lõi.

Ngoại lệ: Import Jobs cho phép import key material từ outside vào KMS. Khi import, key material được wrap bằng ephemeral key để đảm bảo an toàn trong transit. Sau khi import, key material vẫn được lưu trong KMS — không thể export lại.

References ​