{"id":495,"library":"google-cloud-kms","title":"Google Cloud Key Management Service","description":"The `google-cloud-kms` client library provides an interface for interacting with Google Cloud Key Management Service (KMS). KMS is a cloud-hosted key management service that allows you to manage cryptographic keys for your cloud services. It enables generation, usage, rotation, and destruction of various cryptographic keys (AES256, RSA, EC) and integrates with Cloud IAM and Cloud Audit Logging. The library is actively maintained with frequent releases, currently at version 3.12.0, supporting Python 3.9 and higher.","status":"active","version":"3.12.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-kms","tags":["google cloud","kms","key management","cryptography","security"],"install":[{"cmd":"pip install google-cloud-kms","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"KeyManagementServiceClient","correct":"from google.cloud import kms\nclient = kms.KeyManagementServiceClient()"}],"quickstart":{"code":"import os\nfrom google.cloud import kms\nimport base64\n\nproject_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id')\nlocation_id = os.environ.get('KMS_KEY_LOCATION', 'global') # e.g., 'global', 'us-central1'\nkey_ring_id = os.environ.get('KMS_KEY_RING_ID', 'my-key-ring')\nkey_id = os.environ.get('KMS_KEY_ID', 'my-symmetric-key')\n\n# Construct the key resource name\nkey_name = (\n    f\"projects/{project_id}/locations/{location_id}/keyRings/\"\n    f\"{key_ring_id}/cryptoKeys/{key_id}\"\n)\n\n# Initialize the KMS client\ntry:\n    client = kms.KeyManagementServiceClient()\n    print(\"KMS client initialized.\")\nexcept Exception as e:\n    print(f\"Error initializing KMS client: {e}\")\n    print(\"Ensure GOOGLE_APPLICATION_CREDENTIALS is set or running in a GCP environment.\")\n    exit(1)\n\n# Data to encrypt\nplaintext = b\"This is a super secret message.\"\n\ntry:\n    # Encrypt the plaintext\n    encrypt_response = client.encrypt(request={'name': key_name, 'plaintext': plaintext})\n    ciphertext = encrypt_response.ciphertext\n    print(f\"Plaintext encrypted. Ciphertext (base64): {base64.b64encode(ciphertext).decode('utf-8')}\")\n\n    # Decrypt the ciphertext\n    decrypt_response = client.decrypt(request={'name': key_name, 'ciphertext': ciphertext})\n    decrypted_text = decrypt_response.plaintext\n    print(f\"Ciphertext decrypted. Decrypted text: {decrypted_text.decode('utf-8')}\")\n\n    assert plaintext == decrypted_text\n    print(\"Encryption and decryption successful!\")\n\nexcept Exception as e:\n    print(f\"An error occurred during KMS operation: {e}\")\n    print(\"Make sure the key exists, has appropriate IAM permissions, and billing is enabled.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `google-cloud-kms` client and perform a symmetric encryption and decryption operation. Ensure your GCP project ID, KMS key location, key ring ID, and key ID are set as environment variables or replaced. You also need to authenticate to Google Cloud, for example, by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path or by running in a GCP environment with appropriate permissions."},"warnings":[{"fix":"Review your application's error handling for KMS API calls. Implement custom retry logic using `google.api_core.retry` if automatic retries are needed for resilience against transient failures.","message":"Starting with version 3.0.0 (released 2024-09-23), the default retry policy has been removed from all API calls. This affects both synchronous and asynchronous clients, meaning calls will no longer automatically retry on transient errors unless a custom retry policy is explicitly configured.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For data larger than 64 KiB, use envelope encryption. This involves generating a data encryption key (DEK) locally, encrypting your large data with the DEK, and then encrypting only the DEK with Cloud KMS. The DEK can then be stored alongside the encrypted data.","message":"Cloud KMS has a plaintext size limit of 64 KiB (65,536 bytes) for direct encryption operations. Attempting to encrypt larger data directly will result in an error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify that the principal making the API call has the `Cloud KMS CryptoKey Encrypter/Decrypter` role (`roles/cloudkms.cryptoKeyEncrypterDecrypter`) on the specific cryptographic key being used. Use `gcloud iam roles describe roles/cloudkms.cryptoKeyEncrypterDecrypter` to see the contained permissions.","message":"Incorrect IAM permissions are a frequent source of `Permission Denied` errors. Ensure the service account or user calling KMS has the necessary roles (e.g., `roles/cloudkms.viewer`, `roles/cloudkms.cryptoKeyEncrypterDecrypter`) on the specific key, key ring, or project, and that roles are applied to the correct resource type (e.g., KMS keys, not a GCS bucket when encrypting GCS objects with a CMEK).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always construct resource names carefully, preferably using variables for the project, location, key ring, and key IDs, and ensure they match your existing Cloud KMS resources. Double-check the region for your key ring/key.","message":"Resource names (key paths) must be precisely formatted using `projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID`. Mismatched IDs or incorrect segment ordering will result in `NOT_FOUND` or `INVALID_ARGUMENT` errors. The location can be global or a specific region.","severity":"gotcha","affected_versions":"All versions"},{"fix":"It is recommended to use automatic key wrapping if possible. If manual wrapping is necessary, carefully review the key formatting requirements and ensure the correct wrapping key from the import job is used.","message":"When manually importing key material, issues with key formatting or wrapping can lead to the imported key version having an `IMPORT_FAILED` status.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that Application Default Credentials are configured correctly. If running locally, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file, or run `gcloud auth application-default login`. If deploying to Google Cloud, ensure the service has an associated service account with appropriate roles.","message":"The client failed to initialize because Application Default Credentials (ADC) were not found. This occurs when the `GOOGLE_APPLICATION_CREDENTIALS` environment variable is not set, or when the application is not running in a Google Cloud environment (e.g., GCE, GKE, Cloud Run, Cloud Functions) with an associated service account.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure your environment is correctly set up for Application Default Credentials. This typically involves: 1. Setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file. 2. Running your application in a Google Cloud environment (e.g., Compute Engine, Cloud Run, GKE) where an appropriate service account is attached to the resource. Refer to https://cloud.google.com/docs/authentication/external/set-up-adc for detailed setup instructions.","message":"The client failed to initialize due to missing or improperly configured Application Default Credentials (ADC). This error ('Your default credentials were not found') indicates the client could not locate any credentials to authenticate with Google Cloud services.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:20:15.104Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Grant the `Cloud KMS CryptoKey Encrypter/Decrypter` role to the appropriate service account or user on the KMS key, its containing keyring, or the project. For Google-managed service agents (e.g., `service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com` for Cloud Storage), ensure that specific service agent has the role.","cause":"The service account (e.g., for Cloud Storage, BigQuery, or your application) or user account attempting the operation lacks the necessary IAM permission `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the specified KMS key resource. This is particularly common for Google-managed service agents when using Customer-Managed Encryption Keys (CMEK).","error":"PERMISSION_DENIED: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied on resource projects/<PROJECT>/locations/<LOCATION>/keyRings/<KEYRING>/cryptoKeys/<KEY>."},{"fix":"Enable the Cloud KMS API for your project by navigating to the provided URL (e.g., `https://console.developers.google.com/apis/library/cloudkms.googleapis.com`) or by running `gcloud services enable cloudkms.googleapis.com` in your terminal, then wait a few minutes before retrying the operation.","cause":"The Cloud KMS API has not been explicitly enabled for the Google Cloud project you are using, or there is a temporary propagation delay after enabling it.","error":"FAILED_PRECONDITION: Google Cloud KMS API has not been used in this project before, or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview?project=xxxx then retry."},{"fix":"Include the `version_template.algorithm` parameter in your key creation request with an appropriate algorithm that matches the key's purpose, such as `RSA_SIGN_PKCS1_2048_SHA256` for signing keys.","cause":"When creating a cryptographic key, if its purpose is not `ENCRYPT_DECRYPT` (e.g., it's intended for `ASYMMETRIC_SIGN` or `ASYMMETRIC_DECRYPT`), you must explicitly specify the `version_template.algorithm` field with a valid algorithm.","error":"INVALID_ARGUMENT: Request field version_template.algorithm is required if purpose is not ENCRYPT_DECRYPT."},{"fix":"Ensure that the Cloud KMS key is created and located in the exact same Google Cloud region as the resource (e.g., storage bucket, log bucket) that it is intended to protect. If locations do not match, create a new key in the correct region.","cause":"When using Customer-Managed Encryption Keys (CMEK) with certain Google Cloud services (like Cloud Logging or Cloud Storage), the geographic location (region) of the KMS key must match the location of the resource it is encrypting.","error":"INVALID_ARGUMENT: The KMS key location must match the storage location. Received KMS key location: <KMS_LOCATION>, storage location: <STORAGE_LOCATION>"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.35,"mem_mb":31,"disk_size":"71.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.22,"mem_mb":25,"disk_size":"69M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.98,"mem_mb":33.3,"disk_size":"76.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.84,"mem_mb":27.7,"disk_size":"75M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.99,"mem_mb":33,"disk_size":"68.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.4,"mem_mb":27.4,"disk_size":"66M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.89,"mem_mb":33.4,"disk_size":"67.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.33,"mem_mb":27.7,"disk_size":"66M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.04,"mem_mb":30.9,"disk_size":"71.9M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.43,"mem_mb":24.9,"disk_size":"70M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}