Alibaba Cloud Key Management Service (KMS) SDK

Common errors

• alibabacloud_tea_util.models.ClientException: Code: InvalidAccessKeyId.NotFound, Message: The Access Key ID provided does not exist.

  cause The Alibaba Cloud Access Key ID is incorrect, expired, or does not exist.
  fix Verify your `ALIBABA_CLOUD_ACCESS_KEY_ID` environment variable or the `access_key_id` passed to `Config` is correct and active. Ensure there are no leading/trailing spaces.

• alibabacloud_tea_util.models.ClientException: Code: SignatureDoesNotMatch, Message: The request signature does not conform to Aliyun standards.

  cause The Alibaba Cloud Access Key Secret is incorrect, leading to a signature mismatch during authentication.
  fix Verify your `ALIBABA_CLOUD_ACCESS_KEY_SECRET` environment variable or the `access_key_secret` passed to `Config` is correct. This is often caused by typos or outdated secrets.

• alibabacloud_tea_util.models.ClientException: Could not connect to the endpoint URL: "https://kms.cn-hangzhou.aliyuncs.com/"

  cause Network connectivity issue, incorrect region ID, or firewall blocking access to the Alibaba Cloud KMS endpoint.
  fix Check your internet connection. Ensure `ALIBABA_CLOUD_REGION_ID` or `config.region_id` is set to a valid and reachable Alibaba Cloud region (e.g., 'cn-hangzhou'). If behind a firewall, ensure `*.aliyuncs.com` is allowed. You can also try setting `config.endpoint` explicitly.

• alibabacloud_tea_util.models.ServerException: Code: Forbidden.NoPermission, Message: User not authorized to perform this operation.

  cause The IAM user or RAM role associated with the Access Key ID/Secret does not have the necessary permissions to perform the requested KMS operation.
  fix Review the IAM policy attached to your Alibaba Cloud account/user/role. Grant the required permissions for KMS actions (e.g., `kms:CreateKey`, `kms:Encrypt`) to allow the operation.

Warnings

• gotcha Incorrect or missing Access Key ID/Secret and Region ID are the most common causes of `ClientException` errors (e.g., `InvalidAccessKeyId.NotFound`, `SignatureDoesNotMatch`).
  Fix: Ensure `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`, and `ALIBABA_CLOUD_REGION_ID` environment variables are correctly set, or pass valid credentials directly to `Config`.
• gotcha The SDK is tied to KMS API version 2016-01-20. If you need features from a newer KMS API version, you might need a different SDK package or to check if the specific features are backported.
  Fix: Verify the required KMS API features against the 2016-01-20 documentation. If newer features are needed, search for alternative SDKs (if available) or use a different Alibaba Cloud SDK if it encompasses the desired functionality.
• gotcha Network connectivity issues or incorrect endpoint configurations can lead to `Could not connect to the endpoint URL` errors. While `region_id` is usually sufficient, specific scenarios (e.g., private links) might require setting a custom `endpoint`.
  Fix: Check network connectivity to Alibaba Cloud. If `region_id` is insufficient, you can explicitly set `config.endpoint = 'kms.<your-region>.aliyuncs.com'` (e.g., `kms.cn-hangzhou.aliyuncs.com`).
• breaking The core `alibabacloud-tea-openapi` and `alibabacloud-tea-util` libraries, which this SDK depends on, can introduce breaking changes in their own major version updates, potentially affecting how `Config` or `RuntimeOptions` are used.
  Fix: Pin your `alibabacloud-tea-*` dependencies to specific versions (e.g., in `requirements.txt`). When upgrading, review their release notes carefully for breaking changes to `Config` initialization or API call patterns.

Install

• pip install alibabacloud-kms20160120 Install with pip

Imports

• Client
  wrong:

  from aliyun_python_sdk_kms.client import Client

  correct:

  from alibabacloud_kms20160120.client import Client

  This SDK has a specific package name reflecting the API version; older or generic Aliyun SDKs use different import paths.
• Config

  from alibabacloud_tea_openapi.models import Config

  The `Config` object for client initialization is provided by the `alibabacloud-tea-openapi` dependency.
• RuntimeOptions

  from alibabacloud_tea_util.models import RuntimeOptions

  Optional runtime configurations for API calls are from `alibabacloud-tea-util`.

Quickstart

This quickstart demonstrates how to initialize the KMS client using Access Key ID and Secret, and then make a basic API call to create an encryption key. It's recommended to retrieve credentials from environment variables for security. Replace `YOUR_ACCESS_KEY_ID` and `YOUR_ACCESS_KEY_SECRET` with your actual Alibaba Cloud credentials.

import os
from alibabacloud_kms20160120.client import Client as KmsClient
from alibabacloud_tea_openapi.models import Config
from alibabacloud_kms20160120.models import CreateKeyRequest
from alibabacloud_tea_util.models import RuntimeOptions

# Ensure you set these environment variables or replace with actual values
ACCESS_KEY_ID = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID')
ACCESS_KEY_SECRET = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'YOUR_ACCESS_KEY_SECRET')
REGION_ID = os.environ.get('ALIBABA_CLOUD_REGION_ID', 'cn-hangzhou')

try:
    # Initialize client configuration
    config = Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=REGION_ID
    )

    # Create KMS client
    client = KmsClient(config)

    # Example: Create a new encryption key
    create_key_request = CreateKeyRequest(
        description='My Test Key via Python SDK',
        key_usage='ENCRYPT/DECRYPT'
    )

    runtime = RuntimeOptions()
    response = client.create_key_with_options(create_key_request, runtime)

    print(f"Key created successfully: {response.body.key_id}")
    print(f"Key ARN: {response.body.key_arn}")

except Exception as e:
    print(f"An error occurred: {e}")
    # In production, handle specific exceptions like ClientException, ServerException