Microservices Engine:Configuration encryption

Create an encrypted configuration

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

1. Log on to the MSE console, and select a region in the top navigation bar.

2. In the left-side navigation pane, choose Microservices Registry > Instances.

3. On the Instances page, click the name of the instance.

4. In the left-side navigation pane, choose Configuration Management > Configurations.

5. In the upper-left corner of the Configurations page, select a namespace from the Namespace drop-down list, and click Add Configuration.

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

   1. In the Data Encryption section, check whether KMS is activated. If KMS is not activated, activate it first.

   2. If you activate Dedicated KMS 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 in the Data Encryption section. This way, all subsequent configurations are encrypted by using the key. You can create and use a key in the KMS console.

      Important

      • Do not delete or disable the key that is associated with the MSE Nacos instance. Otherwise, encrypted configurations cannot be decrypted.

      • If you activated KMS before March 31, 2022, a prompt to bind the key ID of the Dedicated KMS instance is not displayed and you can use the Shared KMS. The configuration methods for applications to access the Shared KMS are different.

   3. 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 encrypted configuration content cannot exceed 50 KB in size. 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. The encrypted configuration content cannot exceed 50 KB in size.
      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. The encrypted configuration content cannot exceed 6 KB in size.

      Note

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

7. In the Configuration Format section, select a configuration format, enter the configuration content in the Configuration Content editor on the right, and then click Release.

Use an encrypted configuration in the Nacos SDK for Java

1. Add the following dependencies to the pom.xml file in the project:

   <dependency>
       <groupId>com.alibaba.nacos</groupId>
       <artifactId>nacos-client</artifactId>
       <version>{nacos-client-version}</version>
   </dependency>
   <dependency>
       <groupId>com.alibaba.nacos</groupId>
       <artifactId>nacos-client-mse-extension</artifactId>
       <version>{nacos-client-mse-extension-version}</version>
   </dependency>

   Version description

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

   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.

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

   Use the Nacos client framework

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

   try {
       Properties properties = new Properties();
       // The address of your Nacos server.
       properties.put("serverAddr", "{serverAddr}");
       // Configure the RAM role of the ECS instance as the access credential.
       properties.put("ramRoleName", "{ramRoleName}");
       // The endpoint of the KMS instance.
       properties.put("kmsEndpoint", "{kmsEndpoint}");
       ConfigService configService = NacosFactory.createConfigService(properties);
       System.out.println("content:::"+configService.getConfig("{dataId}", "{group}", 6000));
   } catch (Exception e) {
       e.printStackTrace();
   }

   kmsEndpoint indicates the endpoint of the KMS instance. If the access environment and the KMS instance are in the same VPC, the value of kmsEndpoint is the VPC endpoint of the instance. If you access the KMS instance over the Internet, the value of kmsEndpoint is the public endpoint or VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?

   If you use an AccessKey pair as a credential to access the KMS instance, replace the following configuration:

   properties.put("ramRoleName", "{ramRoleName}");

   Use the following configuration:

   properties.put("accessKey", "{accessKey}"); 
   properties.put("secretKey", "{secretKey}");

   The Nacos SDK for Java can use encrypted configurations by using multiple access credentials, such as Security Token Service (STS) tokens and the Alibaba Cloud Resource Name (ARN) of a RAM role. For more information about the supported access credentials and client configuration methods, see Supported access credentials for configuration encryption of the Nacos SDK for Java.

   If your KMS is activated after March 31, 2022, and you want to release encrypted configurations in the SDK, add the following code:

   properties.put("keyId", "{keyId}");

   Replace the serverAddr, ramRoleName, accessKey, secretKey, kmsEndpoint, dataId, group, and keyId parameters in the code with the actual service parameters.

   Use the Spring Cloud Nacos Config framework

   Note

   • 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.

   • Make sure that the version mappings among Spring Cloud Alibaba, Spring Cloud, and Spring Boot are correct. For more information about the version mappings, see the release notes for the related version on the Spring Cloud Alibaba official website.

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

   spring.cloud.nacos.config.server-addr={serverAddr}
   spring.config.import=nacos:{dataId}?group={group}&refreshEnabled=true
   # Use the RAM role of an ECS instance as the access credential.
   spring.cloud.nacos.config.ramRoleName={ramRoleName}
   spring.cloud.nacos.config.kmsEndpoint={kmsEndpoint}

   kmsEndpoint indicates the endpoint of the KMS instance. If the access environment and the KMS instance are in the same VPC, the value of kmsEndpoint is the VPC endpoint of the instance. If you access the KMS instance over Internet, the value of kmsEndpoint is the public endpoint or VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?

   If you use an AccessKey pair as a credential to access the KMS instance, replace the following configuration:

   spring.cloud.nacos.config.ramRoleName={ramRoleName}

   Use the following configurations:

   spring.cloud.nacos.config.accesskey={accessKey}
   spring.cloud.nacos.config.secretkey={secretKey}
   
   # 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={accessKey}
   -Dspring.cloud.nacos.config.secretKey={secretKey}
   # Environment variables.
   spring_cloud_nacos_config_accessKey={accessKey}
   spring_cloud_nacos_config_secretKey={secretKey}

   The Nacos SDK for Java can use encrypted configurations by using multiple access credentials, such as Security Token Service (STS) tokens and the Alibaba Cloud Resource Name (ARN) of a RAM role. For more information about the supported access credentials and client configuration methods, see Supported access credentials for configuration encryption of the Nacos SDK for Java.

   If your KMS is activated after March 31, 2022, and you want to release encrypted configurations in the SDK, add the following code:

   spring.cloud.nacos.config.keyId={keyId}

   Replace the serverAddr, ramRoleName, accessKey, secretKey, kmsEndpoint, dataId, group, and keyId parameters in the code with the actual service parameters.

   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 instance. Example: mse-*****.nacos-ans.mse.aliyuncs.com.
   ramRoleName	The RAM role that is assigned to the ECS instance or ACK cluster.
   accessKey and secretKey	The AccessKey ID and AccessKey secret of the current Alibaba Cloud account. You must specify the accessKey and secretKey parameters. Otherwise, you must specify the ramRoleName parameter.
   kmsEndpoint	The endpoint of the KMS instance. If the access environment and the KMS instance are in the same VPC, the value of kmsEndpoint is the VPC endpoint of the instance. If you access the KMS instance over the Internet, the value of kmsEndpoint is the public endpoint or VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?
   dataId	The data ID of the encrypted configuration. Example: cipher-kms-aes-256-****.properties.
   group	The group name of the encrypted configuration.
   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. Example: alia/*** or key-***.

Use an encrypted configuration in the Nacos SDK for Go

1. 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.8

2. Modify the initial configurations of the Nacos client.

   In the Nacos SDK for Go, only an AccessKey pair can be used as the credential to access the KMS instance. Replace the serverAddr, accessKey, secretKey, and kmsEndpoint parameters in the code with the parameters used in your business and make sure that the OpenKMS parameter is set to true for configuration encryption.

   sc := []constant.ServerConfig{
     {
       IpAddr: "{serverAddr}", // Configure the IP address of your MSE Nacos instance. 
       Port:   8848,
     },
   }
   var accessKey = "{accessKey}" 
   var secretKey = "{secretKey}" 
   
   cc := constant.ClientConfig{
     NamespaceId: "public", // Configure the ID of the namespace. 
     OpenKMS: true, // Enable KMS-based encryption. 
     AccessKey:            accessKey, 
     SecretKey:            secretKey,
     KMSConfig:            &constant.KMSConfig{Endpoint: "{kmsEndpoint}",},
     TimeoutMs:           5000,
     NotLoadCacheAtStart: true,
     LogDir:              "/tmp/nacos/log",
     CacheDir:            "/tmp/nacos/cache",
     RotateTime:          "1h",
     MaxAge:              3,
   }

   kmsEndpoint indicates the endpoint of the KMS instance. If the access environment and the KMS instance are in the same VPC, the value of kmsEndpoint is the VPC endpoint of the instance. If you access the KMS instance over Internet, the value of kmsEndpoint is the public endpoint or VPC endpoint of the public gateway. For more information about how to obtain the endpoint, see How do I obtain the endpoint of a KMS instance?

3. Publish the encrypted configurations.

   keyId: The ID of the KMS key that is used to encrypt configurations.

   configParam := vo.ConfigParam{
       DataId:   "{dataId}",
       Group:    "{group}",
       Content:  "content",
       KmsKeyId: "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. 
   }
   
   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)
   }

Parameters

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

Supported access credentials for configuration encryption of the Nacos SDK for Java

The Nacos SDK for Java supports multiple access credentials to encrypt configurations. You can select a method to initialize the credential provider based on the authentication and authorization requirements of your business scenario.

Supported access credentials:

• Use an AccessKey pair

• Use an STS token

• Use the ARN of a RAM role

• Use the RAM role of an ECS instance

• Use the RAM role of an OIDC IdP

• Use credentials URIs

For more information about how to configure access credentials on the client, see the "Configure access credentials on the client" section in Access authentication by the Nacos client. Select the following system policy to grant the related permission on the access credential. This way, a coarse-grained authorization operation is performed to grant the read and write permissions on all KMS instances.

FAQ

properties.put("kmsEndpoint", "{kmsEndpoint}");

properties.put("kms_region_id", "{kmsRegionId}");

spring.cloud.nacos.config.kmsEndpoint={kmsEndpoint}

spring.cloud.nacos.config.kms_region_id={kmsRegionId}

cc := constant.ClientConfig{
  NamespaceId:         "public", 
  OpenKMS:              true, 
  AccessKey:            accessKey, 
  SecretKey:            secretKey,
  KMSConfig:            &constant.KMSConfig{Endpoint: "{kmsEndpoint}",},
  TimeoutMs:            5000,
  NotLoadCacheAtStart:  true,
  LogDir:               "/tmp/nacos/log",
  CacheDir:             "/tmp/nacos/cache",
  RotateTime:           "1h",
  MaxAge:               3,
}

cc := constant.ClientConfig{
  NamespaceId:         "public", 
  OpenKMS:              true, 
  AccessKey:            accessKey, 
  SecretKey:            secretKey,
  TimeoutMs:            5000,
  NotLoadCacheAtStart:  true,
  LogDir:               "/tmp/nacos/log",
  CacheDir:             "/tmp/nacos/cache",
  RotateTime:           "1h",
  MaxAge:                3,
  RegionId:             "{kmsRegionId}",	
}

Troubleshooting

References

• System policies for MSE

• Custom policies for MSE