All Products
Search
Document Center

Microservices Engine:Configuration encryption

Last Updated:Oct 25, 2024

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

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.

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

      Important

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

    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 encryption 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 encryption 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 encryption configuration content cannot exceed 6 KB in size.

      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 .

  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 based on KMS V1.0

Nacos SDK For Java

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

  6. Use an encrypted configuration.

    Use an encrypted configuration by assuming a RAM role

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

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

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

    2. 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:

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

  6. 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.)

  7. 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",
    }
    
  8. 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 Getting started with keys and Getting started with secrets.

  • 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

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

  6. Use an encrypted configuration.

    Use an encrypted configuration by assuming a RAM role

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

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

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

    2. 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");
                // 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 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:

        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

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

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

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

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

Keywords 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

  1. The initialization parameter kmsVersion is not set to v3.0.

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

References