rustfs/docs/kms/http-api.md

KMS Admin HTTP API Reference

The RustFS KMS admin API is exposed under the admin prefix (/rustfs/admin/v3). Requests must be signed with SigV4 credentials that have the ServerInfoAdminAction permission. All request and response bodies use JSON, and all endpoints return standard HTTP status codes.

• Base URL examples: http://localhost:9000/rustfs/admin/v3, https://rustfs.example.com/rustfs/admin/v3.
• Headers: set Content-Type: application/json for requests with bodies.
• Authentication: sign with SigV4 (awscurl, aws-signature-v4, or the official SDKs).

Service Lifecycle

Endpoint	Method	Description
/kms/configure	POST	Apply the initial backend configuration. Does not start the service.
/kms/reconfigure	POST	Merge a new configuration on top of the existing one.
/kms/start	POST	Start the configured backend.
/kms/stop	POST	Stop the backend; configuration is kept.
/kms/status	GET	Lightweight status summary (Running, Configured, etc.).
/kms/service-status	GET	Backward-compatible alias for /kms/status.
/kms/config	GET	Returns the cached configuration summary.
/kms/clear-cache	POST	Clears in-memory DEK and metadata caches.

Configure / Reconfigure

Request

{
  "backend_type": "vault",
  "address": "https://vault.example.com:8200",
  "auth_method": { "token": "s.XYZ" },
  "mount_path": "transit",
  "kv_mount": "secret",
  "key_path_prefix": "rustfs/kms/keys",
  "default_key_id": "rustfs-master",
  "enable_cache": true,
  "cache_ttl_seconds": 600,
  "timeout_seconds": 30,
  "retry_attempts": 3
}

Response

{
  "success": true,
  "message": "KMS configured successfully",
  "status": "Configured"
}

Partial updates: /kms/reconfigure updates only the fields present in the payload. Use this to rotate tokens or adjust cache parameters without resubmitting the full configuration.

Start / Stop

Start response

{
  "success": true,
  "message": "KMS service started successfully",
  "status": "Running"
}

Stop response

{
  "success": true,
  "message": "KMS service stopped successfully",
  "status": "Configured"
}

Status & Config

GET /kms/status

{
  "status": "Running",
  "backend_type": "vault",
  "healthy": true,
  "config_summary": {
    "backend_type": "vault",
    "default_key_id": "rustfs-master",
    "timeout_seconds": 30,
    "retry_attempts": 3,
    "enable_cache": true,
    "cache_summary": {
      "max_keys": 1024,
      "ttl_seconds": 600,
      "enable_metrics": true
    },
    "backend_summary": {
      "backend_type": "vault",
      "address": "https://vault.example.com:8200",
      "auth_method_type": "token",
      "namespace": null,
      "mount_path": "transit",
      "kv_mount": "secret",
      "key_path_prefix": "rustfs/kms/keys"
    }
  }
}

GET /kms/config

{
  "backend": "vault",
  "cache_enabled": true,
  "cache_max_keys": 1024,
  "cache_ttl_seconds": 600,
  "default_key_id": "rustfs-master"
}

POST /kms/clear-cache returns HTTP 204 with an empty body when successful.

Key Management

Endpoint	Method	Description
/kms/keys	POST	Create a new master key in the backend.
/kms/keys	GET	List master keys (paginated).
/kms/keys/{key_id}	GET	Retrieve metadata for a specific key.
/kms/keys/delete	DELETE	Schedule key deletion.
/kms/keys/cancel-deletion	POST	Cancel a pending deletion request.

Create Key

Request

{
  "KeyUsage": "ENCRYPT_DECRYPT",
  "Description": "project-alpha",
  "Tags": {
    "owner": "security",
    "env": "prod"
  }
}

Response

{
  "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
  "key_metadata": {
    "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
    "description": "project-alpha",
    "enabled": true,
    "key_usage": "ENCRYPT_DECRYPT",
    "creation_date": "2024-09-18T07:10:42.012345Z",
    "rotation_enabled": false
  }
}

List Keys

GET /kms/keys?limit=50&marker=<token>

{
  "keys": [
    { "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85", "description": "project-alpha" }
  ],
  "truncated": false,
  "next_marker": null
}

Describe Key

GET /kms/keys/fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85

{
  "key_metadata": {
    "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
    "description": "project-alpha",
    "enabled": true,
    "key_usage": "ENCRYPT_DECRYPT",
    "creation_date": "2024-09-18T07:10:42.012345Z",
    "deletion_date": null
  }
}

Delete & Cancel Deletion

Delete request

{
  "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
  "pending_window_in_days": 7
}

Cancel deletion

{
  "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85"
}

Both endpoints respond with the updated key_metadata.

Data Key Operations

POST /kms/generate-data-key

Request

{
  "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
  "key_spec": "AES_256",
  "encryption_context": {
    "bucket": "analytics-data",
    "object": "2024/09/18/report.parquet"
  }
}

Response

{
  "key_id": "fa5bac0e-2a2c-4f9a-a09d-2f5b8a59ed85",
  "plaintext_key": "sQW6qt0yS7CqD6c8hY7GZg==",
  "ciphertext_blob": "gAAAAABlLK..."
}

• plaintext_key is Base64-encoded and must be zeroised after use.
• ciphertext_blob can be stored alongside object metadata for future re-wraps.

Error Handling

Code	Meaning	Example payload
400 Bad Request	Malformed JSON or missing required fields.	{ "code": "InvalidRequest", "message": "invalid JSON" }
401 Unauthorized	Request was not signed or credentials are invalid.	{ "code": "AccessDenied", "message": "authentication required" }
403 Forbidden	Caller lacks admin permissions.	{ "code": "AccessDenied", "message": "unauthorised" }
409 Conflict	Backend already configured in an incompatible way.	{ "code": "Conflict", "message": "KMS already running" }
500 Internal Server Error	Backend failure or transient issue. Logs include details.	{ "code": "InternalError", "message": "failed to create key: ..." }

Useful Utilities

• awscurl for quick SigV4 requests.
• The scripts/ directory contains example shell scripts to configure local and Vault backends automatically.
• The e2e test harness (cargo test -p e2e_test kms:: -- --nocapture) demonstrates end-to-end API usage against both backends.

For dynamic workflows and automation strategies, continue with dynamic-configuration-guide.md.