Key Management Service:Dedicated KMS SDK for Python

Prerequisites

• A dedicated KMS instance is purchased and connected to a hardware security module (HSM) cluster. A customer master key (CMK) and an application access endpoint (AAP) are created for the instance, and the client key and certification authority (CA) certificate of the instance are saved. For more information, see Connect applications to the dedicated KMS instance of the Standard edition.
  Note The downloaded CA certificate is named in the PrivateKmsCA_kst-******.pem format and the downloaded client key file is named in the ClientKey_******.json format.
• The virtual private cloud (VPC) address that is used to access the dedicated KMS instance is obtained. The VPC address must meet the following requirements:
  • The VPC address is specified when the HSM cluster is activated.
  • The VPC address can be accessed from your computer.

  For more information, see Query a dedicated KMS instance of the Standard edition.

Install Dedicated KMS SDK

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

  pip install alibabacloud-dkms-gcs

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

  pip install alibabacloud-dkms-gcs-python2

Initialize Dedicated KMS SDK

You can create a Python client for a dedicated KMS instance of the Standard edition to call resources that are managed by the dedicated KMS instance. For example, you can use the client to call the keys that are managed by the instance. Before you can use Dedicated KMS SDK for Python to initiate an API request, you must create a client and modify the default settings of Config based on your business requirements.

1. Configure a certification authority (CA) certificate.

   To ensure secure communications in the production environment, you must configure a trusted certificate.

   Set the verify filed in the RuntimeOptions option to the path of the CA certificate.

   # -*- coding: utf-8 -*-
   from openapi_util.models import RuntimeOptions
   
   runtime_options = RuntimeOptions()
   # Ignore SSL verification.
   # runtime_options.ignore_ssl = True
   # CA certificate path
   runtime_options.verify = "<your-ca-certificate-file-path>"
   ...
   response = client.encrypt_with_options(request, runtime_options)
                           

2. Create a client for the dedicated KMS instance of the Standard edition.

   When you create a client for the dedicated KMS instance of the Standard edition, you must specify the endpoint of the instance. The endpoint excludes the scheme https. For more information about the endpoint of a dedicated KMS instance of the Standard edition, see Query a dedicated KMS instance of the Standard edition.

   # -*- coding: utf-8 -*-
   from openapi.models import Config
   from sdk.client import Client
   
   config = Config()
   # The connection protocol. Set the value to https.
   config.protocol = "https"
   # The client key of the dedicated KMS instance of the Standard edition.
   config.client_key_content = "<your-client-key-content>"
   # The password that is used to decrypt the client key of the dedicated KMS instance of the Standard edition.
   config.password = "<your-password>"
   # The endpoint of the dedicated KMS instance of the Standard edition. The value excludes the scheme https.
   config.endpoint = "<your-endpoint>"
   client = Client(config)

Examples

• Use the client of a dedicated KMS instance of the Standard edition to call the Encrypt operation to encrypt data by using a symmetric CMK.

  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 CMK of the dedicated KMS instance of the Standard edition.
  request.key_id = "<your-key-id>"
  encrypt_response = client.encrypt_with_options(request, runtime_options)
  # The ciphertext.
  ciphertext_blob = encrypt_response.ciphertext_blob
  # The initial vector of Cipher, which is used to decrypt data.
  iv = encrypt_response.iv
  # The ID of the request.
  request_id = encrypt_response.request_id

• Use the client of a dedicated KMS instance of the Standard edition to call the Decrypt operation to decrypt the ciphertext by using a symmetric CMK.

  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 CMK of the dedicated KMS instance of the Standard edition.
  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 encryption.
  request.iv = "<your-iv>"
  decrypt_response = client.decrypt_with_options(request, runtime_options)
  # The plaintext.
  plaintext = decrypt_response.plaintext;
  # The ID of the request.
  request_id = decrypt_response.request_id;

• Use the client of a dedicated KMS instance of the Standard edition to call the Sign operation to generate a signature by using an asymmetric CMK.

  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 CMK of the dedicated KMS instance of the Standard edition.
  request.key_id = "<your-key-id>"
  # The data 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 ID of the request.
  request_id = sign_response.request_id

• Use the client of a dedicated KMS instance of the Standard edition to call the Verify operation to verify a signature by using an asymmetric CMK.

  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 CMK of the dedicated KMS instance of the Standard edition. 
  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 ID of the request.
  request_id = verify_response.request_id

• Use the client of a dedicated KMS instance of the Standard edition to call the GetSecretValue operation to query a secret value.

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

  Important

  • Dedicated KMS SDK for Python V0.0.3 and later support the GetSecretValue operation.
  • Dedicated KMS SDK for Python 2 V0.0.5 and later support the GetSecretValue operation.

  # -*- 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
  # Display the request ID. 
  request_id = response.request_id