Key Management Service:Use KMS Agent to retrieve secrets

Local deployment

1. Create access credentials.

   Use a RAM user's AccessKey pair as an example. Alibaba Cloud accounts have default administrator privileges for all resources, which cannot be modified. Because compromised AccessKeys risk significant security vulnerabilities, we strongly recommend against creating AccessKeys for Alibaba Cloud accounts. Instead, create a RAM user solely for API access, generate its AccessKey, and implement the principle of least privilege.

   1. Log on to the RAM console. In the left-side navigation pane, choose Identities > Users, and click on the desired RAM user.

   2. In the Authentication tab, click Create Accesskey and follow the instructions to complete the creation.

   3. Grant the RAM user permissions to retrieve KMS secrets.

      The agent requires permissions to retrieve secrets values from KMS during the secrets caching process. If the secret value is encrypted by using a key, the kms:Decrypt access must also be granted on the key.

      • Method 1: Through identity-based policies

        For details, see Create custom policies and Grant permissions to a RAM user.

        Permission policy example

        Replace the following parameters with the actual values:

        • ${region} : The region of the resource.

        • ${account}: The Alibaba Cloud account owning the resource.

        • example-secret: The secret name.

        • keyId-example: The key ID.

        {
            "Version": "1",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": "kms:GetSecretValue",
                    "Resource": "acs:kms:${region}:${account}:secret/example-secret"
                },
                {
                    "Effect": "Allow",
                    "Action": "kms:Decrypt",
                    "Resource": "acs:kms:${region}:${account}:key/keyId-example"
                }
            ]
        }

      • Method 2: Through resource-based policies

        KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. For more information, see Key policies and Secret policies.

2. Set environment variables and configure the authentication details required for agent operation.

   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=***
   export ALIBABA_CLOUD_ACCESS_KEY_ID=***
   export KMS_TOKEN='file:///var/run/kmstoken'

3. Generate the SSRF Token and store it in the specified file.

   # Generate an SSRF token and store it in the file /var/run/kmstoken
   ./alibabacloud-kms-agent token /var/run/kmstoken

4. Modify the configuration file based on your business needs.

   config.toml

   [Server]
   HttpPort = 2025
   
   [Kms]
   Region = "ap-southeast-1"
   
   [Cache]
   CacheType = "InMemory"
   CacheSize = 1000
   TtlSeconds = 300
   
   [Log]
   LogLevel = "Debug"
   LogPath = "./logs/"
   MaxSize = 100
   MaxBackups = 2

5. Start the agent.

   ./alibabacloud-kms-agent agent ./config.toml

Linux environment (ECS) deployment

1. Create identity credentials.

   We recommend using the ECSRole to access KMS.

   Use ECS instance RAM role

   1. Log on to the RAM console, and create an instance RAM role whose trusted entity is an Alibaba Cloud service.

      • Select Trusted Entity: Select Alibaba Cloud Service.

      • Role Type: Select Normal Service Role.

      • Select Trusted Service: Select Elastic Compute Service.

   2. Grant the RAM role access to retrieve KMS secrets.

      The agent requires permissions to retrieve secrets values from KMS during the secrets caching process. If the secret value is encrypted by using a key, the kms:Decrypt access must also be granted on the key.

      • Method 1: Through identity-based policies

        For details, see Create custom policies and Grant permissions to a RAM role.

        Permission policy example

        Replace the following parameters with the actual values:

        • ${region} : The region of the resource.

        • ${account}: The Alibaba Cloud account owning the resource.

        • example-secret: The secret name.

        • keyId-example: The key ID.

        {
            "Version": "1",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": "kms:GetSecretValue",
                    "Resource": "acs:kms:${region}:${account}:secret/example-secret"
                },
                {
                    "Effect": "Allow",
                    "Action": "kms:Decrypt",
                    "Resource": "acs:kms:${region}:${account}:key/keyId-example"
                }
            ]
        }

      • Method 2: Through resource-based policies

        KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. For more information, see Key policies and Secret policies.

   3. Log on to the ECS console, and attach the instance RAM role to an ECS instance.

2. Install and start the agent.

   1. Enter the installation directory.

      cd alibabacloud-kms-agent/deploy/linux

   2. Check the following files are present in the installation directory:

      • alibabacloud-kms-agent: The agent binary file.

      • config.toml: The agent's configuration file, as shown below.

        config.toml

        [Server]
        HttpPort = 2025
        
        [Kms]
        Region = "ap-southeast-1"
        
        [Cache]
        CacheType = "InMemory"
        CacheSize = 1000
        TtlSeconds = 300
        
        [Log]
        LogLevel = "Debug"
        LogPath = "./logs/"
        MaxSize = 100
        MaxBackups = 2

      • alibabacloud-kms-agent.service: The systemd service file for managing the agent.

   3. Run the install.sh command as the root user.

      sudo bash -x ./install.sh

      The install.sh script automatically generates an SSRF Token file for identity authentication between the application and agent, preventing SSRF attacks.

   4. Configure the alibabacloud-kms-agent.service User parameter to match the application user, enabling access to KMS.

Sidecar container deployment

1. Create access credentials.

   Use a RAM user's AccessKey pair as an example. Alibaba Cloud accounts have default administrator privileges for all resources, which cannot be modified. Because compromised AccessKeys risk significant security vulnerabilities, we strongly recommend against creating AccessKeys for Alibaba Cloud accounts. Instead, create a RAM user solely for API access, generate its AccessKey, and implement the principle of least privilege.

   1. Log on to the RAM console. In the left-side navigation pane, choose Identities > Users, and click on the desired RAM user.

   2. In the Authentication tab, click Create Accesskey and follow the instructions to complete the creation.

   3. Grant the RAM user permissions to retrieve KMS secrets.

      The agent requires permissions to retrieve secrets values from KMS during the secrets caching process. If the secret value is encrypted by using a key, the kms:Decrypt access must also be granted on the key.

      • Method 1: Through identity-based policies

        For details, see Create custom policies and Grant permissions to a RAM user.

        Permission policy example

        Replace the following parameters with the actual values:

        • ${region} : The region of the resource.

        • ${account}: The Alibaba Cloud account owning the resource.

        • example-secret: The secret name.

        • keyId-example: The key ID.

        {
            "Version": "1",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Action": "kms:GetSecretValue",
                    "Resource": "acs:kms:${region}:${account}:secret/example-secret"
                },
                {
                    "Effect": "Allow",
                    "Action": "kms:Decrypt",
                    "Resource": "acs:kms:${region}:${account}:key/keyId-example"
                }
            ]
        }

      • Method 2: Through resource-based policies

        KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. For more information, see Key policies and Secret policies.

2. Create Dockerfiles.

   Navigate to the deploy/docker-compose/ directory, and create two Dockerfiles:

   • Dockerfile.agent: Builds the agent sidecar container. Dockerfile.agent reference.

   • Dockerfile.app: Builds your application container. Dockerfile.app reference.

3. Create the container orchestration file.

   docker-compose.yaml reference.

4. Modify the configuration file based on your business needs.

   config.toml

   [Server]
   HttpPort = 2025
   
   [Kms]
   Region = "ap-southeast-1"
   
   [Cache]
   CacheType = "InMemory"
   CacheSize = 1000
   TtlSeconds = 300
   
   [Log]
   LogLevel = "Debug"
   LogPath = "./logs/"
   MaxSize = 100
   MaxBackups = 2

5. Build and start containers.

   1. Place the following files in the same directory as your docker-compose.yaml file:

      • alibabacloud-kms-agent (binary)

      • config.toml (configuration file)

      • Dockerfile.agent

      • Dockerfile.app

   2. Run the command docker-compose up --build.

6. Log on to your application container and access the agent from within the container.

ACK deployment

1. Create identity credentials.

   We recommend using RAM Roles for Service Accounts (RRSA) to access KMS. For instructions, see Enable RRSA.

2. Create a RAM role.

   If you want to use an existing RAM role, you must grant the required permissions to the RAM role.

   The following table describes the parameters. For details, see Create a RAM role for an OIDC IdP.

   Parameter	Description
   Identity Provider Type	Select OIDC.
   Identity Provider	Select an IdP. The IdP is named in the ack-rrsa-<cluster_id> format. <cluster_id> indicates the ID of your cluster.
   Conditions	oidc:iss: Use the default value. oidc:aud: Use the default value. oidc:sub: Manually add this condition. Key: Select oidc:sub. Operator: Select StringEquals. Value: Enter system:serviceaccount:<namespace>:<serviceAccountName>. <namespace>: Specify the namespace of the application. <serviceAccountName>: Specify the name of the service account.
   RAM Role Name	Set a name for the RAM role.

3. Grant permissions to the RAM role.

   The agent requires permissions to retrieve secrets values from KMS during the secrets caching process. If the secret value is encrypted by using a key, the kms:Decrypt access must also be granted on the key.

   • Method 1: Through identity-based policies

     For details, see Create custom policies and Grant permissions to a RAM role.

     Permission policy example

     Replace the following parameters with the actual values:

     • ${region} : The region of the resource.

     • ${account}: The Alibaba Cloud account owning the resource.

     • example-secret: The secret name.

     • keyId-example: The key ID.

     {
         "Version": "1",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": "kms:GetSecretValue",
                 "Resource": "acs:kms:${region}:${account}:secret/example-secret"
             },
             {
                 "Effect": "Allow",
                 "Action": "kms:Decrypt",
                 "Resource": "acs:kms:${region}:${account}:key/keyId-example"
             }
         ]
     }

   • Method 2: Through resource-based policies

     KMS supports resource-based policies, which allow you to set access permissions for keys and secrets. For more information, see Key policies and Secret policies.

4. Modify the configuration file based on your business needs.

   config.toml

   [Server]
   HttpPort = 2025
   
   [Kms]
   Region = "ap-southeast-1"
   
   [Cache]
   CacheType = "InMemory"
   CacheSize = 1000
   TtlSeconds = 300
   
   [Log]
   LogLevel = "Debug"
   LogPath = "./logs/"
   MaxSize = 100
   MaxBackups = 2

5. Build the agent sidecar container image.

   1. Navigate to the alibabacloud-kms-agent/deploy/ack/agent directory, and create a Dockerfile.

      Dockerfile reference.

   2. Build the agent container image.

   cd alibabacloud-kms-agent/deploy/ack/agent
   # Test upload to Alibaba Cloud container registry.
   docker build -t registry.<REGION_ID>.aliyuncs.com/<NAMESPACE>/<REPOSITORY>
   docker push registry.<REGION_ID>.aliyuncs.com/<NAMESPACE>/<REPOSITORY>:kmsagent-1.0

6. Build the application container image.

   1. Navigate to the alibabacloud-kms-agent/deploy/ack/app directory, and create a Dockerfile.

      Dockerfile reference.

   2. Build the application container image.

   The example below pushes to an Alibaba Cloud container registry. Replace placeholders with your actual values.

   cd alibabacloud-kms-agent/deploy/ack/app
   # Test upload to Alibaba Cloud container registry.
   docker build -t registry.<REGION_ID>.aliyuncs.com/<NAMESPACE>/<REPOSITORY>
   docker push registry.<REGION_ID>.aliyuncs.com/<NAMESPACE>/<REPOSITORY>:app-1.0

7. Create a Kubernetes YAML file to deploy the application and agent containers to ACK.

   Use the alibabacloud-kms-agent/deploy/ack/demo.yaml file as a template. Modify it as needed and deploy both containers to your ACK cluster using kubectl apply -f <YAML_FILE_NAME>.yaml.

curl

The agent defaults to retrieving secrets from the current ACSC version, as shown in the example below.

To retrieve secrets from other versions, append versionStage or versionId parameters after secretId=<SecretId>. The command will look like this: curl -v -H ... secretId=<SecretId>&versionStage=<versionStage>&versionId=<versionId>'.

 # Read the token from a file.
 curl -v -H "X-KMS-Token:$(</var/run/kmstoken)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
 
 # Directly specify the token.
 curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'

Go

The agent defaults to retrieving secrets from the current ACSC version, as shown in the example below. In actual use, replace agent-test in the example code with your actual secret name.

You can specify versionStage or versionId to retrieve specific secret values. For example, to retrieve secrets for a specified versionId, replace the line url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test") in the code below with url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id").

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

	token, err := ioutil.ReadFile("/var/run/kmstoken")
	if err != nil {
		fmt.Printf("error reading token file: %v\n", err)
	}

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		fmt.Printf("error creating request: %v\n", err)
	}

	req.Header.Add("X-KMS-Token", string(token))

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Printf("error sending request: %v \n", err)
	}
	defer resp.Body.Close()

	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}