Key Management Service:KMS Instance SDK for Python

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