Use KMS keys to encrypt and decrypt data - Key Management Service

Use the KMS instance SDK client to call the Encrypt and Decrypt APIs for symmetric key encryption and decryption. This topic provides a complete C# example and a step-by-step walkthrough.

Prerequisites

Before you begin, ensure that you have:

A KMS instance with a symmetric key
The KMS instance SDK installed
A client key file and its password
The KMS instance endpoint in the format <KMS Instance ID>.cryptoservice.kms.aliyuncs.com
The CA certificate file for your KMS instance

Complete example

The following example shows the full AesEncryptDecryptSample class. All methods used in the walkthrough below are included here.

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

using Tea;
using Tea.Utils;


namespace AlibabaCloud.Dkms.Gcs.Sdk.Example
{
    public class AesEncryptDecryptSample
    {

        public static AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config CreateKmsInstanceConfig(string clientKeyFile, string password, string endpoint, string caFilePath)
        {
            AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config config = new AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config();
            config.ClientKeyFile = clientKeyFile;
            config.Password = password;
            config.Endpoint = endpoint;
            config.CaFilePath = caFilePath;
            return config;
        }

        public static async Task<AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config> CreateKmsInstanceConfigAsync(string clientKeyFile, string password, string endpoint, string caFilePath)
        {
            AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config config = new AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config();
            config.ClientKeyFile = clientKeyFile;
            config.Password = password;
            config.Endpoint = endpoint;
            config.CaFilePath = caFilePath;
            return config;
        }

        public static AlibabaCloud.Dkms.Gcs.Sdk.Client CreateClient(AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config kmsInstanceConfig)
        {
            return new AlibabaCloud.Dkms.Gcs.Sdk.Client(kmsInstanceConfig);
        }

        public static async Task<AlibabaCloud.Dkms.Gcs.Sdk.Client> CreateClientAsync(AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config kmsInstanceConfig)
        {
            return new AlibabaCloud.Dkms.Gcs.Sdk.Client(kmsInstanceConfig);
        }

        public static AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptResponse Encrypt(AlibabaCloud.Dkms.Gcs.Sdk.Client client, byte[] plaintext, string keyId, byte[] aad)
        {
            AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptRequest request = new AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptRequest
            {
                Plaintext = plaintext,
                KeyId = keyId,
                Aad = aad,
            };
            // Ignore CA certificate authentication.
            //AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions runtime = new AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions();
            //runtime.IgnoreSSL = true;
            //return client.EncryptWithOptions(request,runtime);
            return client.Encrypt(request);
        }

        public static async Task<AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptResponse> EncryptAsync(AlibabaCloud.Dkms.Gcs.Sdk.Client client, byte[] plaintext, string keyId, byte[] aad)
        {
            AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptRequest request = new AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptRequest
            {
                Plaintext = plaintext,
                KeyId = keyId,
                Aad = aad,
            };
            // Ignore CA certificate authentication.
            //AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions runtime = new AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions();
            //runtime.IgnoreSSL = true;
            //return await client.EncryptWithOptionsAsync(request,runtime);
            return await client.EncryptAsync(request);
        }

        public static AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptResponse Decrypt(AlibabaCloud.Dkms.Gcs.Sdk.Client client, string keyId, byte[] ciphertextBlob, byte[] aad, string algorithm, byte[] iv)
        {
            AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptRequest request = new AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptRequest
            {
                KeyId = keyId,
                CiphertextBlob = ciphertextBlob,
                Algorithm = algorithm,
                Aad = aad,
                Iv = iv,
            };
            // Ignore CA certificate authentication.
            //AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions runtime = new AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions();
            //runtime.IgnoreSSL = true;
            //return client.DecryptWithOptions(request,runtime);
            return client.Decrypt(request);
        }

        public static async Task<AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptResponse> DecryptAsync(AlibabaCloud.Dkms.Gcs.Sdk.Client client, string keyId, byte[] ciphertextBlob, byte[] aad, string algorithm, byte[] iv)
        {
            AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptRequest request = new AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptRequest
            {
                KeyId = keyId,
                CiphertextBlob = ciphertextBlob,
                Algorithm = algorithm,
                Aad = aad,
                Iv = iv,
            };
            // Ignore CA certificate authentication.
            //AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions runtime = new AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions();
            //runtime.IgnoreSSL = true;
            //return await client.DecryptWithOptionsAsync(request,runtime);
            return await client.DecryptAsync(request);
        }

        public static void Main(string[] args)
        {
            string regionId = "your-regionId";
            string caFilePath = "your-caFilePath";
            string endpoint = "your-endpoint";
            AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config kmsInstanceConfig = CreateKmsInstanceConfig(AlibabaCloud.DarabonbaEnv.Client.GetEnv("ClientKeyFile"), AlibabaCloud.DarabonbaEnv.Client.GetEnv("Password"), endpoint, caFilePath);
            AlibabaCloud.Dkms.Gcs.Sdk.Client client = CreateClient(kmsInstanceConfig);
            //Encryption.
            byte[] plaintext = AlibabaCloud.DarabonbaEncodeUtil.Encoder.Base64Decode("your-plaintext-base64");
            string keyId = "your-keyId";
            byte[] aad = AlibabaCloud.DarabonbaEncodeUtil.Encoder.Base64Decode("your-aad-base64");
            AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptResponse encryptRes = Encrypt(client, plaintext, keyId, aad);
            //Decryption.
            AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptResponse decryptRes = Decrypt(client, encryptRes.KeyId, encryptRes.CiphertextBlob, aad, encryptRes.Algorithm, encryptRes.Iv);
            string decryptResJson = AlibabaCloud.TeaUtil.Common.ToJSONString(AlibabaCloud.TeaUtil.Common.ToMap(decryptRes));
            AlibabaCloud.TeaConsole.Client.Log("decryptRes:" + decryptResJson);
        }


    }
}

Walkthrough

Initialize the client

Call CreateKmsInstanceConfig to build the SDK configuration, then pass it to CreateClient. The client key file path and password are read from environment variables to avoid hardcoding credentials.

using System;

string regionId = "<REGION_ID>";

// The CA certificate of the KMS instance.
string caFilePath = "<CA_CERTIFICATE>";

// Set the endpoint to <your KMS Instance Id>.cryptoservice.kms.aliyuncs.com.
string endpoint = "<ENDPOINT>";

// Set the Client Key and the security token of the Client Key.
AlibabaCloud.Dkms.Gcs.OpenApi.Models.Config kmsInstanceConfig = CreateKmsInstanceConfig(AlibabaCloud.DarabonbaEnv.Client.GetEnv("ClientKeyFile"), AlibabaCloud.DarabonbaEnv.Client.GetEnv("Password"), endpoint, caFilePath);
AlibabaCloud.Dkms.Gcs.Sdk.Client client = CreateClient(kmsInstanceConfig);

For details, see Initialize the C# SDK client.

Encrypt data

Call the Encrypt API with the plaintext, a key ID, and optional additional authenticated data (AAD). AAD binds the ciphertext to a specific context — the same AAD value must be provided at decryption time.

The response includes the ciphertext blob, the encryption algorithm, and the initialization vector (IV). Store all three values alongside the ciphertext — they are all required for decryption.

public static AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptResponse Encrypt(AlibabaCloud.Dkms.Gcs.Sdk.Client client, byte[] plaintext, string keyId, byte[] aad)
{
    AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptRequest request = new AlibabaCloud.Dkms.Gcs.Sdk.Models.EncryptRequest
    {
        Plaintext = plaintext,
        KeyId = keyId,
        Aad = aad,
    };
    // Ignore CA certificate authentication.
    //AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions runtime = new AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions();
    //runtime.IgnoreSSL = true;
    //return client.EncryptWithOptions(request,runtime);
    return client.Encrypt(request);
}

Encrypt request parameters

Parameter	Type	Description
`Plaintext`	`byte[]`	The data to encrypt, as a byte array
`KeyId`	`string`	The ID of the symmetric key to use
`Aad`	`byte[]`	Additional authenticated data (AAD). Optional. Must match the value used at decryption time

Decrypt data

Call the Decrypt API. Pass the KeyId, CiphertextBlob, Algorithm, Aad, and Iv values from the encrypt response.

public static AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptResponse Decrypt(AlibabaCloud.Dkms.Gcs.Sdk.Client client, string keyId, byte[] ciphertextBlob, byte[] aad, string algorithm, byte[] iv)
{
    AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptRequest request = new AlibabaCloud.Dkms.Gcs.Sdk.Models.DecryptRequest
    {
        KeyId = keyId,
        CiphertextBlob = ciphertextBlob,
        Algorithm = algorithm,
        Aad = aad,
        Iv = iv,
    };
    // Ignore CA certificate authentication.
    //AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions runtime = new AlibabaCloud.Dkms.Gcs.OpenApiUtil.Models.RuntimeOptions();
    //runtime.IgnoreSSL = true;
    //return client.DecryptWithOptions(request,runtime);
    return client.Decrypt(request);
}

Decrypt request parameters

Parameter	Type	Source
`KeyId`	`string`	`encryptRes.KeyId`
`CiphertextBlob`	`byte[]`	`encryptRes.CiphertextBlob`
`Algorithm`	`string`	`encryptRes.Algorithm`
`Aad`	`byte[]`	The same AAD value used during encryption
`Iv`	`byte[]`	`encryptRes.Iv` (initialization vector)