Key Management Service:KMS Agent overview

# 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

Serveur HTTP

Le serveur HTTP gère les requêtes des applications pour la récupération des secrets. Par défaut, les réponses utilisent le format KMS GetSecretValue. Définissez ResponseType pour renvoyer plutôt les formats AWS Secrets Manager ou HashiCorp Vault KV.

Formats de requête pris en charge :

• Basé sur le chemin :

  GET /v1/<secret-name>

• Basé sur la requête :

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

Exemple de requête avec curl (lit le jeton SSRF depuis un fichier) :

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

Exemple de requête avec 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())

Remplacez <secret-name> par le nom du secret à récupérer.

Formats de réponse pris en charge :

L'agent est compatible avec les formats de réponse AWS Secrets Manager et HashiCorp Vault KV. Si votre code intègre déjà Spring Vault, modifiez le point d'accès vers l'adresse de KMS Agent et adaptez la configuration via l'agent pour basculer rapidement vers la plateforme Alibaba Cloud.

• Alibaba Cloud KMS (par défaut, 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

L'agent met en cache les valeurs des secrets en mémoire, ce qui réduit le nombre de requêtes envoyées à KMS. Configurez la TTL du cache, sa taille et sa politique d'éviction pour les adapter à vos modèles d'accès et à votre calendrier de rotation des secrets.

Client KMS

Le client KMS connecte l'agent à KMS. Définissez Region et Endpoint pour correspondre à votre déploiement KMS. Les points de terminaison de passerelle partagés et dédiés sont pris en charge.

Journalisation

L'agent utilise le framework de journalisation Zap pour émettre des journaux JSON structurés. Configurez le niveau de journalisation, la limite de taille des fichiers et le nombre de rétention pour répondre à vos exigences opérationnelles.

Authentification et autorisation

Authentification de l'agent auprès de KMS

L'agent utilise la chaîne de fournisseurs d'identifiants par défaut d'Alibaba Cloud, qui vérifie les sources suivantes dans l'ordre : variables d'environnement, rôle RAM OIDC IdP, config.json, rôle RAM ECS et URI d'identifiant, sauf si une méthode d'initialisation spécifique est fournie dans credentials.NewDefaultCredentialsProvider().

Accordez à l'agent uniquement les autorisations nécessaires pour récupérer et déchiffrer les secrets. Suivez le principe du moindre privilège lors de la configuration des politiques RAM.

Authentification des applications auprès de l'agent

L'agent génère un fichier de jeton SSRF (par exemple, /var/run/kmstoken) au démarrage. Les applications doivent inclure ce jeton dans leurs en-têtes de requête. Les requêtes sans jeton valide sont rejetées.

L'accès au fichier de jeton est restreint par défaut :

• Linux : Seul le processus de l'agent et l'utilisateur OS de l'application peuvent lire le fichier de jeton.

• Conteneur sidecar : L'accès au fichier de jeton est limité au pod.

Sécurité des communications

• Agent vers KMS : Tout le trafic utilise Transport Layer Security (TLS). Pour une isolation plus forte, utilisez un point de terminaison de passerelle dédié ; le trafic reste dans votre VPC et n'est pas exposé à l'Internet public.

• Agent vers application : L'agent écoute uniquement sur 127.0.0.1, limitant l'accès à la machine locale.

Audit et journalisation

Toutes les opérations de récupération de secrets sont journalisées au format JSON à l'aide du framework Zap. Les journaux sont configurables en termes de taille de fichier et de nombre de rétention, fournissant un registre auditable de l'activité de l'agent.