Create and use encrypted configurations - Microservices Engine

Configuration data in Microservices Registry of Microservices Engine (MSE) is stored in plaintext. MSE is integrated with Key Management Service (KMS) to allow you to encrypt and decrypt configuration data, such as data sources, tokens, usernames, and passwords. This helps reduce the risk of sensitive data leaks.

Prerequisites

MSE is activated. For more information, see Activate MSE.
A Nacos engine that uses the Developer Edition or Professional Edition is created. For more information, see Create a Nacos engine.
KMS is activated.
Important
To ensure data security, MSE uses Alibaba Cloud KMS to encrypt and decrypt data. If you activate KMS after March 31, 2022, you must purchase Dedicated KMS. For more information, see [Upgrade Announcement] KMS is upgraded to Dedicated KMS. For more information about KMS billing, see Billing of KMS.

Create encrypted configurations

To create encrypted configurations in the MSE console, perform the following steps:

Note

You must use the AccessKey pair of your Alibaba Cloud account or a RAM user to use the configuration encryption and decryption features of MSE.

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance.
In the left-side navigation pane, choose Configuration Management > Configurations.
In the upper-left corner of the Configurations page, select a namespace from the Namespace drop-down list, and click Add Configuration.

In the Add Configuration panel, turn on the Data Encryption switch.

In the Data Encryption section, check whether KMS is activated. If KMS is not activated, activate it first.
If you activate KMS in the Data Encryption section after March 31, 2022, you must select the ID of a key that is used for encryption and associate the key with the MSE Nacos instance. This way, all subsequent configurations are encrypted by using the key. You can create and use a key in KMS.
Important
Do not delete or disable the key that is associated with the MSE Nacos instance. Otherwise, encrypted configurations cannot be decrypted.

Refresh the Add Configuration panel and select an encryption method for KMS.

Parameter	Description
KMS AES-256	The envelope encryption and decryption method of KMS. This method uses the 256-bit key that has high encryption strength. The encryption configuration content cannot exceed 50 KB. The configuration data in plaintext is not transmitted to KMS. We recommend that you select this option for higher security. Select an encryption method based on your business requirements.
KMS AES-128	The encryption method that uses the 128-bit key and has medium encryption strength.
KMS	We recommend that you do not select this option. This is because special characters may result in compatibility issues. For example, an ampersand (`&`) is escaped as `\u0026`.

Note

For users who use KMS V3.0, KMS AES-256 is displayed. For users who use KMS V1.0, the three encryption methods are displayed in consideration of version compatibility issues. We recommend that you do not select KMS or KMS AES-128 .

Select a configuration format in the Configuration Format section, enter the configuration content in the Description section, and then click Release.

Use an encrypted configuration based on KMS V1.0

Nacos SDK for Java

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance.
In the left-side navigation pane, choose Configuration Management > Configurations.
Select a Namespace, find the desired configuration, and then click the data ID of the configuration in the Data ID column. On the configuration details page, click the Sample Code tab.

Use an encrypted configuration.

Use an encrypted configuration by assuming a RAM role

Add the following dependencies to the code:
```
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>1.4.3</version>
</dependency>
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <version>1.0.4</version>
</dependency>
```
Version description
Important
Stability issues may occur if the encryption and decryption plug-in version does not match the Nacos client version. We recommend that you use recommended versions.
Nacos client major version
Nacos client version
Recommended plug-in version
1.x
V1.4.3 or later
1.0.2 or later
2.x
V2.1.1 or later
1.0.4 or later

Select the valid code that you want to configure based on the framework type that you use.

If you use the Nacos client framework to obtain configurations, you must configure the following sample code.

Configure the serverAddr, ramRoleName, regionId, dataid, and group parameters in the code based on your business requirements.

try {
        Properties properties = new Properties();
        properties.put("serverAddr", "mse-xxxxxx-p.nacos-ans.mse.aliyuncs.com");
        properties.put("ramRoleName", "<RAM role assigned to an Elastic Compute Service (ECS) instance or a Container Service for Kubernetes (ACK) cluster>");
        properties.put("keyId", "alias/acs/mse"); // This is the fixed value for KMS V1.0.
        properties.put("kms_region_id", "cn-hangzhou");
        properties.put("kmsVersion", "v1.0");
        ConfigService configService = NacosFactory.createConfigService(properties);
        System.out.println("content:::"+configService.getConfig("cipher-kms-aes-256-dataid", "group", 6000));
    } catch (Exception e) {
        e.printStackTrace();
    }

If you use the Spring Cloud Nacos Config framework to obtain configurations, you must add the following configurations:

kms_region_id=cn-hangzhouspring.cloud.nacos.config.server-addr=mse-xxxxxxx-p.nacos-ans.mse.aliyuncs.com:8848
spring.cloud.nacos.config.name=cipher-kms-aes-256-dataid
spring.cloud.nacos.config.group=group
spring.cloud.nacos.config.ramRoleName=<RAM role assigned to an ECS instance or an ACK cluster>
spring.cloud.nacos.config.kms_region_id=cn-hangzhou
spring.cloud.nacos.config.keyId=alias/acs/mse
spring.cloud.nacos.config.kmsVersion=v1.0

Note

Before you encrypt configuration data by assuming a RAM role, you must attach the AliyunACMFullAccess and AliyunKMSFullAccess policies to the RAM role. For more information, see Grant permissions to a RAM role.

Use an encrypted configuration as a RAM user

Add the following dependencies to the code:
```
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>1.4.3</version>
</dependency>
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <version>1.0.4</version>
</dependency>
```
Version description
Important
Stability issues may occur if the encryption and decryption plug-in version does not match the Nacos client version. We recommend that you use recommended versions.
Nacos client major version
Nacos client version
Recommended plug-in version
1.x
V1.4.3 or later
1.0.2 or later
2.x
V2.1.1 or later
1.0.3
Select the valid code that you want to configure based on the framework type that you use.
- If you use the Nacos client framework to obtain configurations, you must configure the following sample code.
  Configure the serverAddr, accessKey, secretKey, regionId, dataid, and group parameters in the code based on your business requirements.
  Note
  The environment variables for the AccessKey ID and AccessKey secret that are used to log on to MSE are MSE_AK and MSE_SK.
```
try {
        Properties properties = new Properties();
        properties.put("serverAddr", "mse-xxxxxx-p.nacos-ans.mse.aliyuncs.com");
        properties.put("accessKey", "MSE_AK");
        properties.put("secretKey", "MSE_SK");
        properties.put("keyId", "alias/acs/mse");
        properties.put("kms_region_id", "cn-hangzhou");
        properties.put("kmsVersion", "v1.0");
        ConfigService configService = NacosFactory.createConfigService(properties);
        System.out.println("content:::"+configService.getConfig("cipher-kms-aes-256-dataid", "group", 6000));
    } catch (Exception e) {
        e.printStackTrace();
    }
```
- If you use the Spring Cloud Nacos Config framework to obtain configurations, you must add the following configurations. You must also use the JVM system parameter -D or environment variables to specify the region where the MSE instance resides. For example, if the MSE instance resides in the China (Hangzhou) region, set -Dkms_region_id to cn-hangzhou.
```
spring.cloud.nacos.config.server-addr=mse-xxxxxxx-p.nacos-ans.mse.aliyuncs.com:8848
spring.cloud.nacos.config.name=cipher-kms-aes-256-dataid
spring.cloud.nacos.config.group=group
spring.cloud.nacos.config.access-key=MSE_AK
spring.cloud.nacos.config.secret-key=MSE_SK
spring.cloud.nacos.config.kms_region_id=cn-hangzhou
spring.cloud.nacos.config.keyId=alias/acs/mse
spring.cloud.nacos.config.kmsVersion=v1.0
```
Note
You can use the AccessKey ID and AccessKey secret of your Alibaba Cloud account to obtain configuration data. However, we recommend that you use the AccessKey ID and AccessKey secret of a RAM user to obtain configuration data. Before you encrypt configuration data as a RAM user, you must attach the AliyunACMFullAccess and AliyunKMSFullAccess policies to the RAM user. For more information, see RAM users.

Nacos SDK for Go

Use an encrypted configuration as a RAM user

To obtain the sample code that uses encrypted configurations and initialize parameters in the code as a RAM user, perform the following steps:

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance.
In the left-side navigation pane, choose Configuration Management > Configurations.
Select a Namespace, find the desired configuration, and then click the data ID of the configuration in the Data ID column. On the configuration details page, click the Sample Code tab. In the left-side navigation pane of the Sample Code tab, click Go. Use the displayed sample code in your project.
Run the go get command to download dependencies in the Nacos client SDK for Go.
```
go get -u github.com/nacos-group/nacos-sdk-go/v2@v2.2.5
```
Version description
Stability issues may occur if the encryption and decryption plug-in version does not match the Nacos client version. We recommend that you use recommended versions.
Version supported by the plug-in
Nacos client version
KMS 1.0
V2.0.0 or later (The latest version is recommended.)

Modify the initial configuration of the Nacos client.

Configure the {server - addr}, {AK}, and {SK} parameters in the code based on your business requirements, and specify the OpenKMS: true and KMSVersion: KMSv1 configurations to enable KMS-based encryption.

sc := []constant.ServerConfig{
  {
    IpAddr: "{server-addr}", // Configure the IP address of your MSE Nacos instance. 
    Port:   8848,
  },
}
var accessKey = "{AK}" // Configure the AccessKey ID of your account for MSE Nacos instance and KMS authentication. 
var secretKey = "{SK}" // Configure the AccessKey secret of your account for MSE Nacos instance and KMS authentication. 

cc := constant.ClientConfig{
  NamespaceId: "public", // Configure the ID of the namespace. 
  OpenKMS:              true, // Enable configuration encryption by using KMS. 
  KMSVersion:           KMSv1, // Use KMS V1.0. 
  AccessKey:      accessKey, 
  SecretKey:      secretKey,
  TimeoutMs:           5000,
  NotLoadCacheAtStart: true,
  LogDir:              "/tmp/nacos/log",
  CacheDir:            "/tmp/nacos/cache",
  RotateTime:          "1h",
  MaxAge:              3,
  LogLevel:            "debug",
  RegionId: 						"cn-hangzhou",
}

Publish the encrypted configuration.

keyId: the ID of the KMS key that is used to encrypt configurations. This parameter can be ignored if KMS V1.0 is used.

configParam := vo.ConfigParam{
      DataId:   "cipher-kms-aes-256-crypt",
      Group:    "default",
      Content:  "cipher-aes-256",
}

published, err := client.PublishConfig(configParam)

if published && err == nil {
  fmt.Printf("successfully publish: group[%s], dataId[%s], data[%s]\n", configParam.Group, configParam.DataId, configParam.Content)
} else {
  fmt.Printf("failed to publish: group[%s], dataId[%s], data[%s]\n with error: %s\n",
    configParam.Group, configParam.DataId, configParam.Content, err)
}

Use an encrypted configuration based on KMS V3.0

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 key in the "Getting started with Key Management" topic and Getting started with Secrets Manager.
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 Create an AAP.
You must make sure that the application runtime environment can connect to the MSE instance over the Internet or an internal network and to a KMS instance that is in the same virtual private cloud (VPC). If your application runtime environment needs to connect to a KMS instance from another VPC, see Access a KMS instance from multiple VPCs in the same region.

Nacos SDK for Java

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance.
In the left-side navigation pane, choose Configuration Management > Configurations.
Select a Namespace, find the desired configuration, and then click the data ID of the configuration in the Data ID column. On the configuration details page, click the Sample Code tab.

Use an encrypted configuration.

Use an encrypted configuration by assuming a RAM role

Add the following dependencies to the code:
```
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>1.4.3</version>
</dependency>
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <version>1.0.4</version>
</dependency>
```
Note
Only plug-ins of 1.0.4 and later allow you to create encrypted configurations based on KMS V3.0.
Version description
Stability issues may occur if the encryption and decryption plug-in version does not match the Nacos client version. We recommend that you use recommended versions.
Nacos client major version
Nacos client version
Recommended plug-in version
1.x
V1.4.3 or later
1.0.4 or later
2.x
V2.1.1 or later
1.0.4 or later

Select the valid code that you want to configure based on the framework type that you use.

If you use the Nacos client framework to obtain configurations, you must configure the following sample code.

Configure the serverAddr, accessKey, secretKey, regionId, kms_region_id, kmsEndpoint, keyId, kmsVersion, kmsClientKeyFilePath, kmsPasswordKey, and kmsCaFilePath parameters in the code based on your business requirements.

try {
        Properties properties = new Properties();
        properties.put("serverAddr", "mse-xxxxxx-p.nacos-ans.mse.aliyuncs.com");
        properties.put("ramRoleName", "<RAM role assigned to an ECS instance or an ACK cluster>");
        properties.put("regionId", "cn-hangzhou");

        properties.put("kms_region_id", "cn-hangzhou");
      	properties.put("kmsEndpoint", "kst-hzz6xxxr.cryptoservice.kms.aliyuncs.com");
        properties.put("keyId", "yourKeyIdOrKeyAlias");
      	properties.put("kmsVersion", "v3.0");
        properties.put("kmsClientKeyContent", "clientKey_content");
        // Configure one of the kmsClientKeyContent and kmsClientKeyFilePath parameters. The kmsClientKeyContent parameter takes precedence. 
      	// properties.put("kmsClientKeyFilePath", "clientKey_hangzhou.json");
      	properties.put("kmsPasswordKey", "10xxxd1d");
      	properties.put("kmsCaFileContent", "ca_content");
        // Configure one of the kmsCaFileContent and kmsCaFilePath parameters. The kmsCaFileContent parameter takes precedence. 
      	// properties.put("kmsCaFilePath", "ca.pem");
        ConfigService configService = NacosFactory.createConfigService(properties);
        System.out.println("content:::"+configService.getConfig("cipher-kms-aes-256-dataid", "group", 6000));
    	} catch (Exception e) {
            e.printStackTrace();
      }

Parameters

The following table describes the parameters. Make sure that the values you configure are valid.

Parameter	Description
serverAddr	The IP address of your MSE Nacos instance.
ramRoleName	The RAM role that is assigned to the ECS instance or ACK cluster.
regionId	Optional. The ID of the region where your MSE Nacos instance resides.
kms_region_id	Optional. The ID of the region where your KMS instance resides. If this parameter is left empty, the value of `regionId` is used.
kmsEndpoint	The VPC endpoint of your KMS instance. Do not include the https:// prefix in the endpoint.
keyId	The ID of the KMS key that is used to encrypt configurations. You can create and use a KMS key in the KMS console. If no modification is required for the encrypted configurations, you do not need to configure this parameter.
kmsVersion	The KMS version. Set this parameter to v3.0.
kmsClientKeyFilePath	The path of the file that stores the client key of the KMS instance. You can obtain the path when you create an AAP for the KMS instance.
kmsClientKeyContent	The client key of the KMS instance. You can obtain the client key when you create an AAP for the KMS instance. Note Configure one of the `kmsClientKeyContent` and `kmsClientKeyFilePath` parameters. The `kmsClientKeyContent` parameter takes precedence.
kmsPasswordKey	The password that corresponds to the client key of the KMS instance. You can obtain the password when you create an AAP for the KMS instance.
kmsCaFilePath	The path of the CA certificate that is used by the KMS instance. You can obtain the path when you create an AAP for the KMS instance.
kmsCaFileContent	The content of the CA certificate that is used by the KMS instance. You can obtain the content when you create an AAP for the KMS instance. Note Configure one of the `kmsCaFileContent` and `kmsCaFilePath` parameters. The `kmsCaFileContent` parameter takes precedence.

If you use the Spring Cloud Nacos Config framework to obtain configurations, you must add the following configurations:

# Specify the data ID and group of the configurations that you want to load from the Nacos instance. If the refreshEnabled parameter is set to true, dynamic refresh is supported.
spring.config.import=nacos:cipher-kms-aes-256-****.properties?group=****&refreshEnabled=true

## Nacos-related configurations

# Configure the endpoint of your MSE Nacos instance.
spring.cloud.nacos.config.server-addr=mse-*****.nacos-ans.mse.aliyuncs.com

# Configure the namespace that you want to access. If you want to access the public namespace, you do not need to configure this parameter.
spring.cloud.nacos.config.namespace=5babe1ee-****-****-****-7e7ce892e2ab

# If authentication is enabled for your Nacos instance, you must configure the client identity information.
spring.cloud.nacos.config.ramRoleName=<RAM role assigned to an ECS instance or an ACK cluster>

# If an AccessKey pair is used to access your Nacos instance, we recommend that you specify the AccessKey pair by using Java Virtual Machine (JVM) parameters or environment variables. 
# JVM parameters.
-Dspring.cloud.nacos.config.accessKey=LTA*************
-Dspring.cloud.nacos.config.secretKey=*************
# Environment variables.
spring_cloud_nacos_config_accessKey=LTA*************
spring_cloud_nacos_config_secretKey=*************

## KMS-related configurations

# The region where your KMS instance resides.
spring.cloud.nacos.config.kms_region_id=cn-hangzhou

# The VPC endpoint of your KMS instance. Do not include the https:// prefix in the endpoint.
spring.cloud.nacos.config.kmsEndpoint=kst-xxx.cryptoservice.kms.aliyuncs.com

# The key ID or key ID alias of your KMS instance. The key ID starts with key, and the key ID alias starts with alias. If you do not need to publish the encrypted configurations by using a program, you do not need to configure this parameter. The decryption process does not depend on this parameter. 
spring.cloud.nacos.config.keyId=alias/***

# The KMS version, which is a fixed value.
spring.cloud.nacos.config.kmsVersion=v3.0

# The path of the file that stores the client key of your KMS instance. You can obtain the path when you create an AAP for the KMS instance.
spring.cloud.nacos.config.kmsClientKeyFilePath=clientKey_hangzhou.json

# The password that corresponds to the client key of your KMS instance. You must specify the content of clientKey_KAAP.***_Password.t. We recommend that you specify the password by using JVM parameters or environment variables. 
# JVM parameters.
-Dspring.cloud.nacos.config.kmsPasswordKey=10xxxd1d
# Environment variables
spring.cloud.nacos.config.kmsPasswordKey=10xxxd1d
spring_cloud_nacos_config_kmsPasswordKey=10xxxd1d

# The path of the CA certificate that is used by your KMS instance. You can obtain the path when you create an AAP for the KMS instance. This configuration is used to verify the validity of the value of the kmsEndpoint parameter and prevent identity impersonation. 
spring.cloud.nacos.config.kmsCaFilePath=clientKey_hangzhou.json

Note

If RAM authentication is not enabled for your MSE Nacos instance, ignore the MSE_AK and MSE_SK configurations.
If you use Spring Cloud Alibaba 2022.x or 2023.x, upgrade the version to 2023.0.1.2.
If you use Spring Cloud Alibaba 2021.x, upgrade the version to 2021.0.6.1.
If you use Spring Cloud Alibaba 2.x, upgrade the version to 2.2.10.

Use an encrypted configuration as a RAM user

Add the following dependencies to the code:
```
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>1.4.3</version>
</dependency>
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client-mse-extension</artifactId>
    <version>1.0.4</version>
</dependency>
```
Note
Only plug-ins of 1.0.3 and later support KMS V3.0 for creating encrypted configurations.
Version description
Stability issues may occur if the encryption and decryption plug-in version does not match the Nacos client version. We recommend that you use recommended versions.
Nacos client major version
Nacos client version
Recommended plug-in version
1.x
V1.4.3 or later
1.0.4 or later
2.x
V2.1.1 or later
1.0.4 or later

Select the valid code that you want to configure based on the framework type that you use.

If you use the Nacos client framework to obtain configurations, you must configure the following sample code.

try {
        Properties properties = new Properties();
        properties.put("serverAddr", "mse-xxxxxx-p.nacos-ans.mse.aliyuncs.com");
        // The AccessKey ID and AccessKey secret are used for authentication for the MSE Nacos instance. If RAM authentication is not enabled for your MSE Nacos instance, ignore the MSE_AK and MSE_SK configurations. 
        properties.put("accessKey", "MSE_AK"); 
        properties.put("secretKey", "MSE_SK");
        properties.put("regionId", "cn-hangzhou");

        properties.put("kms_region_id", "cn-hangzhou");
      	properties.put("kmsEndpoint", "kst-hzz6xxxr.cryptoservice.kms.aliyuncs.com");
        properties.put("keyId", "alias/acs/mse");
      	properties.put("kmsVersion", "v3.0");
        properties.put("kmsClientKeyContent", "clientKey_content");
        // Configure one of the kmsClientKeyContent and kmsClientKeyFilePath parameters. The kmsClientKeyContent parameter takes precedence. 
      	// properties.put("kmsClientKeyFilePath", "clientKey_hangzhou.json");
      	properties.put("kmsPasswordKey", "10xxxd1d");
      	properties.put("kmsCaFileContent", "ca_content");
        // Configure one of the kmsCaFileContent and kmsCaFilePath parameters. The kmsCaFileContent parameter takes precedence. 
      	// properties.put("kmsCaFilePath", "ca.pem");
        ConfigService configService = NacosFactory.createConfigService(properties);
        System.out.println("content:::"+configService.getConfig("cipher-kms-aes-256-dataid", "group", 6000));
    	} catch (Exception e) {
            e.printStackTrace();
      }

Parameters

The following table describes the parameters. Make sure that the values you configure are valid.

Parameter	Description
serverAddr	The IP address of the MSE Nacos instance.
accessKey	The AccessKey ID of your account. Note If RAM authentication is not enabled for your MSE Nacos instance, ignore this parameter.
secretKey	The AccessKey secret of your account. Note If RAM authentication is not enabled for your MSE Nacos instance, ignore this parameter.
regionId	Optional. The ID of the region where your MSE Nacos instance resides.
kms_region_id	Optional. The ID of the region where your KMS instance resides. If this parameter is left empty, the value of `regionId` is used.
kmsEndpoint	The endpoint of your KMS instance.
keyId	The ID of the KMS key that is used to encrypt configurations. You can create and use a KMS key in the KMS console.
kmsVersion	The KMS version. Set this parameter to v3.0.
kmsClientKeyFilePath	The path of the file that stores the client key of the KMS instance. You can obtain the path when you create an AAP for the KMS instance.
kmsClientKeyContent	The client key of the KMS instance. You can obtain the client key when you create an AAP for the KMS instance. Note Configure one of the `kmsClientKeyContent` and `kmsClientKeyFilePath` parameters. The `kmsClientKeyContent` parameter takes precedence.
kmsPasswordKey	The password that corresponds to the client key of the KMS instance. You can obtain the password when you create an AAP for the KMS instance.
kmsCaFilePath	The path of the CA certificate that is used by the KMS instance. You can obtain the content when you create an AAP for the KMS instance.
kmsCaFileContent	The content of the CA certificate that is used by the KMS instance. You can obtain the content when you create an AAP for the KMS instance. Note Configure one of the `kmsCaFileContent` and `kmsCaFilePath` parameters. The `kmsCaFileContent` parameter takes precedence.

If you use the Spring Cloud Nacos Config framework to obtain configurations, you must add the following configurations:

spring.cloud.nacos.config.server-addr=mse-xxxxxxx-p.nacos-ans.mse.aliyuncs.com:8848
spring.cloud.nacos.config.name=cipher-kms-aes-256-dataid
spring.cloud.nacos.config.group=group
spring.cloud.nacos.config.access-key=MSE_AK
spring.cloud.nacos.config.secret-key=MSE_SK
spring.cloud.nacos.config.kms_region_id=cn-hangzhou
spring.cloud.nacos.config.kmsEndpoint=kst-hzz6xxxr.cryptoservice.kms.aliyuncs.com
spring.cloud.nacos.config.keyId=yourKeyIdOrKeyAlias
spring.cloud.nacos.config.kmsVersion=v3.0
spring.cloud.nacos.config.kmsClientKeyFilePath=clientKey_hangzhou.json
spring.cloud.nacos.config.kmsCaFilePath=clientKey_hangzhou.json
spring.cloud.nacos.config.kmsPasswordKey=10xxxd1d

Note

If RAM authentication is not enabled for your MSE Nacos instance, ignore the MSE_AK and MSE_SK configurations.

Nacos SDK for Go

Log on to the MSE console, and select a region in the top navigation bar.
In the left-side navigation pane, choose Microservices Registry > Instances.
On the Instances page, click the name of the instance.
In the left-side navigation pane, choose Configuration Management > Configurations.
Select a Namespace, find the desired configuration, and then click the data ID of the configuration in the Data ID column. On the configuration details page, click the Sample Code tab. In the left-side navigation pane of the Sample Code tab, click Go. Use the displayed sample code in your project.
Run the go get command to download dependencies in the Nacos client SDK for Go.
```
go get -u github.com/nacos-group/nacos-sdk-go/v2@v2.2.5
```
Version description
Stability issues may occur if the encryption and decryption plug-in version does not match the Nacos client version. We recommend that you use recommended versions.
Version supported by the plug-in
Nacos client version
KMS 3.0
V2.2.5 or later

Modify the initial configuration of the Nacos client.

Configure the {server - addr}, {AK}, {SK}, {client_key_content}, {password}, {endpoint}, and {ca.pem_content} parameters in the code based on your business requirements. Specify the OpenKMS: true and KMSVersion: KMSv3 configurations to enable KMS-based encryption.

sc := []constant.ServerConfig{
  {
    IpAddr: "{server-addr}", // Configure the IP address of your MSE Nacos instance. 
    Port:   8848,
  },
}
var accessKey = "{AK}" // If RAM authentication is not enabled for your MSE Nacos instance, ignore this configuration. 
var secretKey = "{SK}" // If RAM authentication is not enabled for your MSE Nacos instance, ignore this configuration. 

cc := constant.ClientConfig{
  NamespaceId: "public", // Configure the ID of the namespace. 
  OpenKMS: true, // Enable KMS-based encryption. 
  KMSVersion: KMSv3, // Use KMS V3.0. 
  KMSv3Config:          &KMSv3Config{
    ClientKeyContent: "client_key.json"),
    Password:         "password"),
    Endpoint:         "endpoint"),
    CaContent:        "ca.pem"),
  },
  AccessKey:      accessKey, 
  SecretKey:      secretKey,
  TimeoutMs:           5000,
  NotLoadCacheAtStart: true,
  LogDir:              "/tmp/nacos/log",
  CacheDir:            "/tmp/nacos/cache",
  RotateTime:          "1h",
  MaxAge:              3,
  LogLevel:            "debug",
}

Parameters

The following table describes the parameters. Make sure that the values you configure are valid.

Parameter	Description
serverAddr	The IP address of the MSE Nacos instance.
AK	The AccessKey ID of your account. Note If RAM authentication is not enabled for your MSE Nacos instance, ignore this parameter.
SK	The AccessKey secret of your account. Note If RAM authentication is not enabled for your MSE Nacos instance, ignore this parameter.
KMSv3Config.Endpoint	The endpoint of your KMS instance.
KMSVersion	The KMS version. Set this parameter to v3.0.
KMSv3Config.ClientKeyContent	The client key of the KMS instance. You can obtain the client key when you create an AAP for the KMS instance.
KMSv3Config.Password	The password that corresponds to the client key of the KMS instance. You can obtain the password when you create an AAP for the KMS instance.
KMSv3Config.CaContent	The content of the CA certificate that is used by the KMS instance. You can obtain the content when you create an AAP for the KMS instance.

Publish encrypted configurations.

configParam := vo.ConfigParam{
    DataId:   "cipher-kms-aes-256-crypt",
    Group:    "default",
    Content:  "cipher-aes-256",
    KmsKeyId: "key-xxx", // The ID of the KMS key that is used to encrypt configurations. You can create and use a KMS key in the KMS console. 
}

published, err := client.PublishConfig(configParam)

if published && err == nil {
	fmt.Printf("successfully publish: group[%s], dataId[%s], data[%s]\n", configParam.Group, configParam.DataId, configParam.Content)
} else {
  fmt.Printf("failed to publish: group[%s], dataId[%s], data[%s]\n with error: %s\n",
    configParam.Group, configParam.DataId, configParam.Content, err)
}

Troubleshooting

Troubleshooting of common errors

Perform the following steps:

Check whether the application runtime environment can connect to the VPC in which the MSE instance resides and the VPC in which the KMS instance resides.
Note
You do not need to ensure the connectivity between the MSE instance and KMS instance.
Check whether KMS V1.0 or V3.0 is used. If KMS V1.0 is used, you must make sure that KMS was activated before March 31, 2022.
Note
If you activate KMS after March 31, 2022, you must purchase Dedicated KMS. The encryption feature of KMS V1.0 is no longer available for new users.
Check whether the Nacos client version matches the version of the encryption and decryption plug-in. For more information, see version descriptions in this topic.

Troubleshooting of Nacos SDK for Java issues

Keyword of exception stacks in Nacos logs	Cause
`keyId is not set up yet`	The initialization parameter `keyId` is left empty or not specified.
`Forbidden.KeyNotFound : The specified Key is not found.`	The key ID specified by the initialization parameter `keyId` does not exist in the KMS instance.
`kmsEndpoint is empty`	The initialization parameter `kmsEndpoint` is left empty.
`test-kst-xxxx.cryptoservice.kms.aliyuncs.com: unknown name or service`	The endpoint specified by the initialization parameter `kmsEndpoint` is inaccessible.
`kmsPasswordKey is empty`	The initialization parameter `kmsPasswordKey` is left empty.
`keystore password was incorrect`	The value of the initialization parameter `kmsPasswordKey` is invalid.
`SDK.ServerUnreachable : Server unreachable: connection https://kst-xxx.cryptoservice.kms.aliyuncs.com`	The initialization parameter `kmsVersion` is not set to `v3.0`.
`None of the TrustManagers trust this certificate chain`	The initialization parameter `kmsVersion` is not set to `v3.0`. The initialization parameter `kmsCaFilePath` is left empty.
`kmsClientKeyFilePath is empty`	The initialization parameter `kmsClientKeyFilePath` is left empty.
`unable to find valid certification path to requested target`	The file that is specified by the initialization parameter `kmsCaFilePath` cannot be found.

Microservices Engine：Configuration encryption

Prerequisites

Create encrypted configurations

Use an encrypted configuration based on KMS V1.0

Nacos SDK for Java

Use an encrypted configuration by assuming a RAM role

Use an encrypted configuration as a RAM user

Nacos SDK for Go

Use an encrypted configuration as a RAM user

Use an encrypted configuration based on KMS V3.0

Prerequisites

Nacos SDK for Java

Use an encrypted configuration by assuming a RAM role

Use an encrypted configuration as a RAM user

Nacos SDK for Go

Troubleshooting

Troubleshooting of common errors

Troubleshooting of Nacos SDK for Java issues

References

Nacos client major version	Nacos client version	Recommended plug-in version
1.x	V1.4.3 or later	1.0.2 or later
2.x	V2.1.1 or later	1.0.4 or later

Version supported by the plug-in	Nacos client version
KMS 1.0	V2.0.0 or later (The latest version is recommended.)

Version supported by the plug-in	Nacos client version
KMS 3.0	V2.2.5 or later