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.
NoteIf 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.
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)
Configure the certificate authority (CA) certificate of your KMS instance by using
RuntimeOptions
.ImportantTo 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 ofRuntimeOptions
to True.Set the
verify
field ofRuntimeOptions
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.
ImportantIf 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