All Products
Search
Document Center

Key Management Service:KMS Instance SDK for Python

Last Updated:Oct 23, 2023

Key Management Service (KMS) Instance SDK for Python allows you to call KMS Instance API operations in a convenient manner. You can use KMS Instance SDK for Python to encrypt and decrypt data, sign data, verify signatures, and retrieve secret values. This topic describes how to install KMS Instance SDK for Python and call operations to encrypt and decrypt data, sign data, verify signatures, and retrieve secret values.

Background information

KMS provides various types of SDKs. Before you use an SDK, you must get familiar with the scenarios of the SDK. For more information, see SDK user guide.

If you use KMS Instance SDK for Python 3, you can view the source code and sample code of the SDK in the open source code repository for Python 3. For more information, see Python 3 open source code repository. If you use KMS Instance SDK for Python 2, you can view the source code and sample code of the SDK in the open source code repository for Python 2. For more information, see Python2 open source code repository. You are welcome to share your comments or provide your sample code.

Prerequisites

  • A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.

  • A key and a secret are created. For more information, see Software-protected keys, Hardware-protected keys, and Create a secret.

    Note

    If your business does not require a secret, you do not need to create a secret.

  • An application access point (AAP) is created, the client key that is bound to the AAP is saved, and a certificate authority (CA) certificate is obtained for the KMS instance. For more information, see Access a KMS instance by using an AAP.

  • Make sure that the application runtime environment and the VPC of the KMS instance can communicate with each other.

    Business scenario

    Description

    The application runtime environment and the KMS instance reside in the same region and belong to the same VPC.

    By default, the application runtime environment and the KMS instance can communicate with each other. No manual configuration is required.

    The application runtime environment and the KMS instance reside in the same region but belong to different VPCs.

    You must configure multiple VPCs to access the same KMS instance. For more information, see Access a KMS instance from multiple VPCs in the same region.

Install KMS Instance SDK for Python

  • If you use KMS Instance SDK for Python 3, run the following command to install the alibabacloud-dkms-gcs module:

    pip install alibabacloud-dkms-gcs
  • If you use KMS Instance SDK for Python 2, run the following command to install the alibabacloud-dkms-gcs-python2 module:

    pip install alibabacloud-dkms-gcs-python2

Initialize KMS Instance SDK for Python

To use KMS Instance SDK for Python to initiate a request, you must create a client.

  1. Create a client.

    # -*- coding: utf-8 -*-
    from openapi.models import Config
    from sdk.client import Client
    
    config = Config()
    # The connection protocol. Set the value to https. KMS supports connections only over HTTPS. 
    config.protocol = "https"
    # The endpoint of your KMS instance. Set the value in the following format: <ID of your KMS instance >.cryptoservice.kms.aliyuncs.com. 
    config.endpoint = "<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com"
    # The client key. 
    config.client_key_content = "<your-client-key-content>"
    # The password of the client key file. 
    config.password = "<your-password>"
    client = Client(config)
  2. Configure the certificate authority (CA) certificate of your KMS instance by using RuntimeOptions.

    Important

    To ensure communication security in the production environment, we recommend that you verify the validity of SSL/TLS certificates. If you do not need to verify the validity of SSL/TLS certificates in specific scenarios such as testing scenarios, set the ignore_ssl field of RuntimeOptions to True.

    Set the verify field of RuntimeOptions to the path of the CA certificate of the KMS instance. The following code provides an example:

    # -*- coding: utf-8 -*-
    from openapi_util.models import RuntimeOptions
    
    runtime_options = RuntimeOptions()
    # The CA certificate path
    runtime_options.verify = "<your-ca-certificate-file-path>"                        

Use the client to call an operation

After you create a client, you can use the client to call KMS Instance API operations. The following sample codes provide examples on how to call operations in different scenarios. For more information about KMS Instance API, see List of operations by function.

  • Call the Encrypt operation to encrypt data by using a symmetric key

    For more information about the sample code, see Python 3 source code or Python 2 source code.

    # -*- coding: utf-8 -*-
    
    from sdk.models import EncryptRequest
    
    request = EncryptRequest()
    # The data that you want to encrypt. 
    request.plaintext = "<your-plaintext>".encode("utf-8")
    # The ID or alias of the key. 
    request.key_id = "<your-key-id>"
    encrypt_response = client.encrypt_with_options(request, runtime_options)
    # The encrypted data or ciphertext. 
    ciphertext_blob = encrypt_response.ciphertext_blob
    # The initial vector of Cipher, which is used to decrypt data. 
    iv = encrypt_response.iv
    # The request ID. 
    request_id = encrypt_response.request_id
  • Call the Decrypt operation to decrypt data by using a symmetric key

    For more information about the sample code, see Python 3 source code or Python 2 source code.

    # -*- coding: utf-8 -*-
    
    from sdk.models import DecryptRequest
    
    request = DecryptRequest()
    # The ciphertext that you want to decrypt. 
    request.ciphertext_blob = "<your-ciphertext-blob>"
    # The ID or alias of the key. 
    request.key_id = "<your-key-id>"
    # The initial vector of Cipher. The initial vector must be the same as the initial vector that is specified for data encryption. 
    request.iv = "<your-iv>"
    decrypt_response = client.decrypt_with_options(request, runtime_options)
    # The plaintext. 
    plaintext = decrypt_response.plaintext;
    # The request ID. 
    request_id = decrypt_response.request_id;
  • Call the Sign operation to sign data by using an asymmetric key

    For more information about the sample code, see Python 3 source code or Python 2 source code.

    # -*- coding: utf-8 -*-
    
    from sdk.models import SignRequest
    
    request = SignRequest()
    # The ID or alias of the key. 
    request.key_id = "<your-key-id>"
    # The data that you want to sign. 
    request.message = "<your-raw-message>"
    # The signature algorithm. 
    request.algorithm = "<your-algorithm>"
    sign_response = client.sign_with_options(request, runtime_options)
    # The signature value. 
    signature = sign_response.signature
    # The request ID. 
    request_id = sign_response.request_id
  • Call the Verify operation to verify a signature by using an asymmetric key

    For more information about the sample code, see Python 3 source code or Python 2 source code.

    # -*- coding: utf-8 -*-
    
    from sdk.models import SignRequest
    
    request = VerifyRequest()
    # The ID or alias of the key. 
    request.key_id = "<your-key-id>"
    # The data for which you want to verify the signature. 
    request.message = "<your-raw-message>"
    # The signature algorithm. 
    request.algorithm = "<your-algorithm>"
    # The signature value. 
    request.signature = "<your-signature>"
    verify_response = client.verify_with_options(request, runtime_options)
    # The verification result. 
    valid = verify_response.valid
    # The request ID. 
    request_id = verify_response.request_id
  • Call the GetSecretValue operation to retrieve a secret value

    For more information about the sample code, see Python 3 source code or Python 2 source code.

    Important
    • If you use KMS Instance SDK for Python 3, this operation is supported only for KMS Instance SDK for Python V0.0.3 or later.

    • If you use KMS Instance SDK for Python 2, this operation is supported only for KMS Instance SDK for Python 2 V0.0.5 or later.

    # -*- coding: utf-8 -*-
    
    from sdk.models import GetSecretValueRequest
    
    request = GetSecretValueRequest()
    # The secret name. 
    request.secret_name = "<your-secret-name>"
    response = client.get_secret_value_with_options(request, runtime_options)
    # The secret value. 
    secret_data = response.secret_data
    # The request ID. 
    request_id = response.request_id