Skip to main content
KMS (Key Management Service) methods let you interact with the Phala Cloud key management infrastructure. You use these to retrieve encryption keys for securing environment variables and to get on-chain KMS details for compose hash verification.

​
get_kms_info

GET /kms/{kmsId} Retrieves information about a specific KMS instance. Parameters:
FieldTypeRequiredDescription
kms_idstrYesKMS identifier (e.g., "phala")
Returns: KMS info object. Example: 
kms = client.get_kms_info({"kms_id": "phala"})
print(kms.model_dump())

​
get_kms_list

GET /kms Lists all available KMS instances. Supports optional filtering. Parameters: Optional dictionary of query parameters. Returns: GetKmsListResponse with a list of KMS instances. Example: 
kms_list = client.get_kms_list()
for kms in kms_list.items:
    print(kms.id, kms.name)

​
get_kms_on_chain_detail

GET /kms/on-chain/{chain} Retrieves the on-chain KMS details for a specific blockchain. This is needed for compose hash verification during CVM provisioning and updates. Parameters:
FieldTypeRequiredDescription
chainstrYesBlockchain identifier (e.g., "phala")
Returns: On-chain KMS detail response. Example: 
detail = client.get_kms_on_chain_detail({"chain": "phala"})
print(detail.model_dump())

​
get_app_env_encrypt_pub_key

GET /kms/{kms}/pubkey/{appId} Retrieves the public key used to encrypt environment variables for a specific app. You need this key before calling encrypt_env_vars(). Parameters:
FieldTypeRequiredDescription
kmsstrYesKMS identifier (e.g., "phala")
app_idstrYesApp identifier
Returns: Response containing the app_env_encrypt_pubkey field. Example: 
pubkey = client.get_app_env_encrypt_pub_key({
    "kms": "phala",
    "app_id": "my-app-id",
})
print(pubkey.app_env_encrypt_pubkey)

​
next_app_ids

GET /kms/phala/next_app_id Reserves the next available app IDs from the Phala KMS. Useful when you need to know the app ID before provisioning. Parameters:
FieldTypeRequiredDescription
countsintNoNumber of IDs to reserve (default: 1, max: 20)
Returns: Response with the reserved app IDs. Example: 
ids = client.next_app_ids({"counts": 3})
print(ids.model_dump())

​
Encrypting Environment Variables

The SDK provides utility functions for encrypting environment variables using the KMS public key. Here is the typical workflow: 
from phala_cloud import (
    create_client,
    encrypt_env_vars,
    verify_env_encrypt_public_key,
)

client = create_client()

# 1. Get the encryption public key
pubkey_resp = client.get_app_env_encrypt_pub_key({
    "kms": "phala",
    "app_id": "my-app-id",
})

# 2. Optionally verify the public key
verify_env_encrypt_public_key(pubkey_resp.app_env_encrypt_pubkey)

# 3. Encrypt your environment variables
encrypted = encrypt_env_vars(
    env_vars=[
        {"key": "DATABASE_URL", "value": "postgres://..."},
        {"key": "API_SECRET", "value": "s3cr3t"},
    ],
    public_key=pubkey_resp.app_env_encrypt_pubkey,
)

# 4. Update the CVM with encrypted env vars
client.update_cvm_envs({
    "id": "my-app",
    "encrypted_env": encrypted,
    "env_keys": ["DATABASE_URL", "API_SECRET"],
})
The encrypt_env_vars, get_compose_hash, and verify_env_encrypt_public_key functions require the dstack-sdk package, which is included as a dependency of phala-cloud.