or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

autokey-service.mdexternal-key-management.mdindex.mdkey-management-service.mdtypes-and-enums.md
tile.json

tessl/pypi-google-cloud-kms

Google Cloud Key Management Service client library for managing cryptographic keys in the cloud

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/google-cloud-kms@3.5.x

To install, run

npx @tessl/cli install tessl/pypi-google-cloud-kms@3.5.0

index.mddocs/

Google Cloud KMS

Google Cloud Key Management Service (KMS) client library for Python that enables developers to manage cryptographic keys in the cloud with the same ease as on-premises systems. It provides comprehensive support for symmetric and asymmetric encryption, digital signing, MAC operations, key lifecycle management, external key management, and automated key provisioning through Google's Cloud KMS service.

Package Information

  • Package Name: google-cloud-kms
  • Language: Python
  • Installation: pip install google-cloud-kms
  • Version: 3.5.1

Core Imports

from google.cloud import kms

Alternative version-specific import:

from google.cloud import kms_v1

Basic Usage

from google.cloud import kms

# Initialize the Key Management Service client
client = kms.KeyManagementServiceClient()

# Create a key ring
project_id = "your-project-id"
location_id = "global"
key_ring_id = "example-keyring"

# Format the parent name
location_name = f"projects/{project_id}/locations/{location_id}"

# Create key ring
key_ring = {}
key_ring_name = client.create_key_ring(
    request={
        "parent": location_name,
        "key_ring_id": key_ring_id,
        "key_ring": key_ring,
    }
)

# Create a crypto key
crypto_key_id = "example-key"
purpose = kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT
crypto_key = {
    "purpose": purpose,
}

crypto_key_name = client.create_crypto_key(
    request={
        "parent": key_ring_name.name,
        "crypto_key_id": crypto_key_id,
        "crypto_key": crypto_key,
    }
)

# Encrypt data
plaintext = b"Hello, World!"
encrypt_response = client.encrypt(
    request={
        "name": crypto_key_name.name,
        "plaintext": plaintext,
    }
)

# Decrypt data
decrypt_response = client.decrypt(
    request={
        "name": crypto_key_name.name,
        "ciphertext": encrypt_response.ciphertext,
    }
)

print(f"Decrypted: {decrypt_response.plaintext.decode('utf-8')}")

Architecture

Google Cloud KMS provides a comprehensive cryptographic key management system built on Google's infrastructure:

  • Service Clients: High-level client interfaces (KeyManagementServiceClient, AutokeyClient, etc.)
  • Resource Hierarchy: KeyRings contain CryptoKeys, which have CryptoKeyVersions
  • Cryptographic Operations: Encrypt/decrypt, sign/verify, MAC operations using managed keys
  • Protection Levels: Software, HSM, and external key manager options
  • Lifecycle Management: Automated key rotation, destruction scheduling, and recovery
  • Integration: Seamless integration with Google Cloud IAM, audit logging, and VPC

Capabilities

Key Management Service

Core key and cryptographic operations including key ring management, crypto key lifecycle, encryption/decryption, asymmetric signing, and MAC operations. This is the primary interface for most KMS operations.

class KeyManagementServiceClient:
    def create_key_ring(self, request: CreateKeyRingRequest) -> KeyRing: ...
    def create_crypto_key(self, request: CreateCryptoKeyRequest) -> CryptoKey: ...
    def encrypt(self, request: EncryptRequest) -> EncryptResponse: ...
    def decrypt(self, request: DecryptRequest) -> DecryptResponse: ...
    def asymmetric_sign(self, request: AsymmetricSignRequest) -> AsymmetricSignResponse: ...
    def generate_random_bytes(self, request: GenerateRandomBytesRequest) -> GenerateRandomBytesResponse: ...

Key Management Service

Autokey Service

Automated key provisioning for Customer-Managed Encryption Keys (CMEK) that creates and manages keys automatically based on resource needs. Includes both key handle management and administrative configuration.

class AutokeyClient:
    def create_key_handle(self, request: CreateKeyHandleRequest) -> KeyHandle: ...
    def get_key_handle(self, request: GetKeyHandleRequest) -> KeyHandle: ...
    def list_key_handles(self, request: ListKeyHandlesRequest) -> ListKeyHandlesResponse: ...

class AutokeyAdminClient:
    def update_autokey_config(self, request: UpdateAutokeyConfigRequest) -> AutokeyConfig: ...
    def get_autokey_config(self, request: GetAutokeyConfigRequest) -> AutokeyConfig: ...

Autokey Service

External Key Management

Integration with external key management systems (EKM) for keys stored and managed outside of Google Cloud, supporting both VPC and direct connection patterns.

class EkmServiceClient:
    def create_ekm_connection(self, request: CreateEkmConnectionRequest) -> EkmConnection: ...
    def get_ekm_connection(self, request: GetEkmConnectionRequest) -> EkmConnection: ...
    def verify_connectivity(self, request: VerifyConnectivityRequest) -> VerifyConnectivityResponse: ...
    def update_ekm_config(self, request: UpdateEkmConfigRequest) -> EkmConfig: ...

External Key Management

Types and Enums

Comprehensive type system including resource types (CryptoKey, KeyRing, CryptoKeyVersion), request/response objects, enums for algorithms and states, and configuration options.

class CryptoKey:
    purpose: CryptoKeyPurpose
    version_template: CryptoKeyVersionTemplate
    
class CryptoKeyVersion:
    algorithm: CryptoKeyVersionAlgorithm
    state: CryptoKeyVersionState
    
class ProtectionLevel(Enum):
    SOFTWARE = 1
    HSM = 2
    EXTERNAL = 3

Types and Enums

Client Configuration

All service clients support flexible configuration for authentication, endpoints, and transport options.

Authentication Methods

from google.cloud import kms

# Using Application Default Credentials (recommended)
client = kms.KeyManagementServiceClient()

# Using service account file
client = kms.KeyManagementServiceClient.from_service_account_file(
    "path/to/service-account-key.json"
)

# Using service account info dictionary
service_account_info = {
    "type": "service_account",
    "project_id": "your-project-id",
    "private_key_id": "key-id",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...",
    "client_email": "service-account@your-project.iam.gserviceaccount.com",
    "client_id": "client-id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token"
}

client = kms.KeyManagementServiceClient.from_service_account_info(service_account_info)

Client Options and Transport Configuration

from google.cloud import kms
from google.api_core import client_options

# Custom endpoint configuration
options = client_options.ClientOptions(
    api_endpoint="https://custom-kms-endpoint.googleapis.com"
)
client = kms.KeyManagementServiceClient(client_options=options)

# Universe domain configuration (for multi-tenant scenarios)
options = client_options.ClientOptions(
    universe_domain="custom.universe.domain"
)
client = kms.KeyManagementServiceClient(client_options=options)

# Transport configuration with custom gRPC channel
from google.api_core import grpc_helpers
import grpc

channel = grpc_helpers.create_channel(
    target="kms.googleapis.com:443",
    credentials=None,
    options=[
        ("grpc.keepalive_time_ms", 30000),
        ("grpc.keepalive_timeout_ms", 5000),
    ]
)

client = kms.KeyManagementServiceClient(transport="grpc", channel=channel)

Context Manager Usage

# Automatic resource cleanup using context manager
with kms.KeyManagementServiceClient() as client:
    # Create resources
    key_ring = client.create_key_ring(request={
        "parent": f"projects/{project_id}/locations/{location_id}",
        "key_ring_id": "example-keyring",
        "key_ring": {},
    })
    
    # Use resources
    crypto_key = client.create_crypto_key(request={
        "parent": key_ring.name,
        "crypto_key_id": "example-key",
        "crypto_key": {
            "purpose": kms.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT,
        },
    })
    
# Client resources automatically cleaned up here

Client Properties

client = kms.KeyManagementServiceClient()

# Access client configuration
print(f"API Endpoint: {client.api_endpoint}")
print(f"Universe Domain: {client.universe_domain}")

# Access transport layer
transport = client.transport
print(f"Transport Type: {type(transport)}")

Common Client Features

All service clients provide:

Authentication and Configuration:

  • Service account authentication via JSON key files or application default credentials
  • Custom endpoint configuration for private Google Access or testing
  • Universe domain configuration for multi-tenant scenarios

IAM Integration:

  • get_iam_policy(), set_iam_policy(), test_iam_permissions() for fine-grained access control
  • Integration with Google Cloud IAM roles and permissions

Operations and Location Support:

  • Long-running operation management via get_operation()
  • Multi-region support via list_locations() and get_location()
  • Path helper methods for constructing resource names

Client Lifecycle:

  • Context manager support for automatic resource cleanup
  • Async client variants for all service clients
  • Transport customization (gRPC, REST) with configurable timeouts and retries