Key Management Service:Visão geral do KMS Agent

# All configuration items
[Server]
# Optional, default value is 2025. Agent listens on 127.0.0.1:2025.
HttpPort = 2025
# Optional, default value is ["X-KMS-Token", "X-Vault-Token"].
# Requests to the agent must include an SSRF header; requests without one are rejected.
SSRFHeaders = ["X-KMS-Token"]
# Optional, default value is ["KMS_TOKEN", "KMS_SESSION_TOKEN", "KMS_CONTAINER_AUTHORIZATION_TOKEN"].
# The value can be a literal string or a file path, such as file:///var/run/awssmatoken.
# The agent reads the SSRF token from the specified environment variable and compares it
# against the token in the application's request header. Access is granted only on a match.
SSRFEnvVariables = ["KMS_TOKEN"]
# Optional, default value is "/v1/". URI prefix for path-based requests.
PathPrefix = "/v1/"
# Optional, default value is 800. Maximum number of concurrent requests.
MaxConn = 800
# Optional, default value is 0.
# 0: KMS GetSecretValue response format
# 1: AWS Secrets Manager GetSecretValue response format
# 2: HashiCorp Vault KV structure
ResponseType = 0
# Optional, default value is true.
# When true, the agent returns expired cached values if KMS is temporarily unreachable.
IgnoreTransientErrors = true

[Kms]
# Optional, default value is cn-hangzhou.
Region = "cn-hangzhou"
# Optional, default value is kms.cn-hangzhou.aliyuncs.com.
# Accepts both shared and dedicated gateway endpoints.
Endpoint = "kms.cn-hangzhou.aliyuncs.com"

[Cache]
# Optional, default value is InMemory. Only in-memory caching is currently supported.
CacheType = "InMemory"
# Optional, default value is 1000. When set to 0, caching is disabled and every
# request goes directly to KMS.
CacheSize = 1000
# Optional, default value is 300s.
TtlSeconds = 300
# Optional, default value is false.
# false: evicts the oldest cached secret when the cache is full.
# true: evicts the least recently used secret (LRU) based on access frequency.
EnableLRU = false

[Log]
# Optional, default value is Debug.
LogLevel = "Debug"
# Optional, default value is ./logs/ relative to the application startup directory.
LogPath = "./logs/"
# Optional, default value is 100 (MB). Maximum size per log file.
MaxSize = 100
# Optional, default value is 2. Number of log files to retain.
MaxBackups = 2

Servidor HTTP

O servidor HTTP processa as solicitações das aplicações para recuperação de segredos. Por padrão, as respostas usam o formato GetSecretValue do KMS. Defina ResponseType para retornar os formatos do AWS Secrets Manager ou do HashiCorp Vault KV.

Formatos de solicitação suportados:

• Baseado em caminho:

  GET /v1/<secret-name>

• Baseado em consulta:

  GET /secretsmanager/get?secretId=<secret-name>

Exemplo de solicitação usando curl (lê o token SSRF de um arquivo):

curl -s \
  -H "X-KMS-Token: $(cat /var/run/kmstoken)" \
  "http://127.0.0.1:2025/v1/<secret-name>"

Exemplo de solicitação usando Python:

with open("/var/run/kmstoken") as f:
    token = f.read().strip()

headers = {"X-KMS-Token": token}
response = requests.get("http://127.0.0.1:2025/v1/<secret-name>", headers=headers)
print(response.json())

Substitua <secret-name> pelo nome do segredo a ser recuperado.

Formatos de resposta suportados:

O agent é compatível com os formatos de resposta do AWS Secrets Manager e do HashiCorp Vault KV. Se seu código já integra o Spring Vault, altere o endpoint de acesso para o endereço do KMS Agent e conclua a adaptação da configuração por meio do agent para migrar rapidamente para a plataforma Alibaba Cloud.

• Alibaba Cloud KMS (padrão, ResponseType=0):

  {
     "CreateTime": "2025-01-03T07:59:17Z",
     "RequestId": "cc315250-04c9-4caf-a055-6648f36598b9",
     "SecretData": "{\"k3\":\"v3\"}",
     "SecretDataType": "text",
     "SecretName": "agent-test",
     "SecretType": "Generic",
     "VersionId": "v2",
     "VersionStages": {
        "VersionStage": [
           "ACSCurrent"
        ]
     }
  }

• AWS Secrets Manager (ResponseType=1):

  {
     "ARN": "",
     "Name": "agent-test",
     "VersionId": "v2",
     "SecretString": "{\"k3\":\"v3\"}",
     "VersionStages": [
        "ACSCurrent"
     ],
     "CreatedDate": "2025-01-03T07:59:17Z"
  }

• HashiCorp Vault (ResponseType=2):

  {
     "data": {
        "k3": "v3"
     }
  }

Cache

O agent armazena valores de segredos em cache na memória, reduzindo o número de solicitações enviadas ao KMS. Configure o TTL, o tamanho e a política de evicção do cache para corresponder aos seus padrões de acesso e ao cronograma de rotação de segredos.

Cliente KMS

O cliente KMS conecta o agent ao KMS. Defina Region e Endpoint para corresponder à sua implantação do KMS. Tanto endpoints de gateway compartilhados quanto dedicados são suportados.

Log

O agent utiliza o framework de logging Zap para emitir logs estruturados em JSON. Configure o nível de log, o limite de tamanho do arquivo e a contagem de retenção para atender aos seus requisitos operacionais.

Autenticação e autorização

Autenticação do agent no KMS

O agent usa o Alibaba Cloud default credential provider chain, que verifica as seguintes fontes nesta ordem: variáveis de ambiente, função RAM do IdP OIDC, config.json, função RAM do ECS e URI de credencial — a menos que um método de inicialização específico seja fornecido em credentials.NewDefaultCredentialsProvider().

Conceda ao agent apenas as permissões necessárias para recuperar e descriptografar segredos. Siga o princípio do menor privilégio ao configurar políticas RAM.

Autenticação das aplicações no agent

O agent gera um arquivo de token SSRF (por exemplo, /var/run/kmstoken) na inicialização. As aplicações devem incluir esse token nos cabeçalhos de suas solicitações. Solicitações sem um token válido são rejeitadas.

O acesso ao arquivo de token é restrito por padrão:

• Linux: Apenas o processo do agent e o usuário do sistema operacional da aplicação podem ler o arquivo de token.

• Contêiner sidecar: O acesso ao arquivo de token é limitado ao escopo do pod.

Segurança da comunicação

• Do agent para o KMS: Todo o tráfego usa Transport Layer Security (TLS). Para maior isolamento, utilize um endpoint de gateway dedicado — o tráfego permanece dentro da sua VPC e não é exposto à internet pública.

• Do agent para a aplicação: O agent escuta apenas em 127.0.0.1, restringindo o acesso à máquina local.

Auditoria e logging

Todas as operações de recuperação de segredos são registradas em formato JSON usando o framework Zap. Os logs permitem configurar o tamanho do arquivo e a contagem de retenção, fornecendo um registro auditável da atividade do agent.