Fields of the global <CONFIG_FOLDER>/kms.json, of a tenant's
<CONFIG_FOLDER>/<tenant-id>/kms.json and of the body of
PUT /api/key-chain/providers/config, generated from the backend's validation
schema. How to choose and set up a provider is described in
Key management (KMS).
Every object is strict: unknown fields are rejected. String values accept
${VAR} placeholders (upper-case letters, digits and _), resolved from the
backend's environment; a file that references an unset or empty variable is
rejected. Unlike configuration import files, kms.json has no
${VAR:default} syntax. defaultProvider must match a provider id, and
provider IDs must be unique.
Both files are either the bare content below or a KmsConfig document with
$schema (https://eudiplo.dev/schemas/v2/KmsConfigFile.schema.json, older
versions are migrated) and the content in spec; see
Document envelope. A document of
another kind is rejected.
File
| Field | Required | Type / allowed values | Description |
|---|
defaultProvider | no | string | ID of the default KMS provider. Defaults to "db" if not set. |
providers | yes | array of one of 6 shapes | List of KMS provider configurations. Each provider must have a unique id and a type. |
Each entry of providers has one of the shapes below, selected by type.
Database (db)
| Field | Required | Type / allowed values | Description |
|---|
id | yes | string | Unique identifier for this provider instance. Used when generating keys to specify which provider to use. |
type | yes | string: db | Type of the KMS provider. |
description | no | string | Human-readable description of this provider instance. |
algorithms | no | array of string: ES256 | ES384 | ES512 | Signing algorithms new and imported key chains of this provider may use: ES256 (P-256), ES384 (P-384), ES512 (P-521). An import through the API, the config folder or a configuration bundle whose key uses another algorithm is refused. Defaults to all three for db, vault and aws-kms. For pkcs11, http and csc, whose backends may not support every curve, it defaults to defaultAlgorithm (ES256 unless set). Existing keys keep signing with their own algorithm. |
defaultAlgorithm | no | string: ES256 | ES384 | ES512 | Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms. |
HashiCorp Vault (vault)
| Field | Required | Type / allowed values | Description |
|---|
id | yes | string | Unique identifier for this provider instance. Used when generating keys to specify which provider to use. |
type | yes | string: vault | Type of the KMS provider. |
description | no | string | Human-readable description of this provider instance. |
algorithms | no | array of string: ES256 | ES384 | ES512 | Signing algorithms new and imported key chains of this provider may use: ES256 (P-256), ES384 (P-384), ES512 (P-521). An import through the API, the config folder or a configuration bundle whose key uses another algorithm is refused. Defaults to all three for db, vault and aws-kms. For pkcs11, http and csc, whose backends may not support every curve, it defaults to defaultAlgorithm (ES256 unless set). Existing keys keep signing with their own algorithm. |
defaultAlgorithm | no | string: ES256 | ES384 | ES512 | Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms. |
vaultUrl | yes | string | URL of the HashiCorp Vault instance. Supports ${ENV_VAR} placeholders. |
vaultToken | yes | string | Authentication token for HashiCorp Vault. Supports ${ENV_VAR} placeholders. |
AWS KMS (aws-kms)
| Field | Required | Type / allowed values | Description |
|---|
id | yes | string | Unique identifier for this provider instance. Used when generating keys to specify which provider to use. |
type | yes | string: aws-kms | Type of the KMS provider. |
description | no | string | Human-readable description of this provider instance. |
algorithms | no | array of string: ES256 | ES384 | ES512 | Signing algorithms new and imported key chains of this provider may use: ES256 (P-256), ES384 (P-384), ES512 (P-521). An import through the API, the config folder or a configuration bundle whose key uses another algorithm is refused. Defaults to all three for db, vault and aws-kms. For pkcs11, http and csc, whose backends may not support every curve, it defaults to defaultAlgorithm (ES256 unless set). Existing keys keep signing with their own algorithm. |
defaultAlgorithm | no | string: ES256 | ES384 | ES512 | Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms. |
region | yes | string | AWS region for KMS. Supports ${ENV_VAR} placeholders. |
accessKeyId | no | string | AWS access key ID. Optional — uses SDK credential chain if not provided. Supports ${ENV_VAR} placeholders. |
secretAccessKey | no | string | AWS secret access key. Optional — uses SDK credential chain if not provided. Supports ${ENV_VAR} placeholders. |
PKCS#11 (pkcs11)
| Field | Required | Type / allowed values | Description |
|---|
id | yes | string | Unique identifier for this provider instance. Used when generating keys to specify which provider to use. |
type | yes | string: pkcs11 | Type of the KMS provider. |
description | no | string | Human-readable description of this provider instance. |
algorithms | no | array of string: ES256 | ES384 | ES512 | Signing algorithms new and imported key chains of this provider may use: ES256 (P-256), ES384 (P-384), ES512 (P-521). An import through the API, the config folder or a configuration bundle whose key uses another algorithm is refused. Defaults to all three for db, vault and aws-kms. For pkcs11, http and csc, whose backends may not support every curve, it defaults to defaultAlgorithm (ES256 unless set). Existing keys keep signing with their own algorithm. |
defaultAlgorithm | no | string: ES256 | ES384 | ES512 | Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms. |
library | yes | string | Absolute path to the PKCS#11 module library (.so/.dll/.dylib). Supports ${ENV_VAR} placeholders. |
slot | yes | number | string | Slot selection. Either the numeric slot index (as a string for ENV interpolation, or a number) or the token label. Supports ${ENV_VAR} placeholders. |
pin | yes | string | User PIN used for C_Login. Supports ${ENV_VAR} placeholders. |
readOnly | no | boolean | Open the PKCS#11 session in read-only mode. Defaults to false. |
Remote HTTP service (http)
| Field | Required | Type / allowed values | Description |
|---|
id | yes | string | Unique identifier for this provider instance. Used when generating keys to specify which provider to use. |
type | yes | string: http | Type of the KMS provider. |
description | no | string | Human-readable description of this provider instance. |
algorithms | no | array of string: ES256 | ES384 | ES512 | Signing algorithms new and imported key chains of this provider may use: ES256 (P-256), ES384 (P-384), ES512 (P-521). An import through the API, the config folder or a configuration bundle whose key uses another algorithm is refused. Defaults to all three for db, vault and aws-kms. For pkcs11, http and csc, whose backends may not support every curve, it defaults to defaultAlgorithm (ES256 unless set). Existing keys keep signing with their own algorithm. |
defaultAlgorithm | no | string: ES256 | ES384 | ES512 | Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms. |
baseUrl | yes | string | Base URL of the remote KMS microservice (no trailing slash). Supports ${ENV_VAR} placeholders. |
auth | no | one of 4 shapes | Authentication method for the remote KMS service. Supports bearer token, OAuth 2.0 client credentials, and mutual TLS. Omit (or set type to "none") for unauthenticated services. |
auth.type | yes | string: oauth2-client-credentials | Only when type is oauth2-client-credentials. OAuth 2.0 Client Credentials — EUDIPLO fetches and caches short-lived tokens. |
auth.tokenUrl | yes | string | Only when type is oauth2-client-credentials. Token endpoint URL (e.g. Keycloak, Entra ID). Supports ${ENV_VAR} placeholders. |
auth.clientId | yes | string | Only when type is oauth2-client-credentials. OAuth 2.0 client ID. Supports ${ENV_VAR} placeholders. |
auth.clientSecret | yes | string | Only when type is oauth2-client-credentials. OAuth 2.0 client secret. Supports ${ENV_VAR} placeholders. |
auth.scope | no | string | Only when type is oauth2-client-credentials. Space-separated list of OAuth 2.0 scopes to request. Optional. |
auth.type | yes | string: mtls | Only when type is mtls. Mutual TLS — EUDIPLO presents a client certificate on every connection. |
auth.certFile | yes | string | Only when type is mtls. Absolute path to the PEM-encoded client certificate file. Supports ${ENV_VAR} placeholders. |
auth.keyFile | yes | string | Only when type is mtls. Absolute path to the PEM-encoded private key file for the client certificate. Supports ${ENV_VAR} placeholders. |
auth.caFile | no | string | Only when type is mtls. Absolute path to the PEM-encoded CA bundle to trust for the remote server's certificate. Omit to use the system CA store. |
auth.type | yes | string: bearer | Only when type is bearer. Static Bearer token sent as Authorization: Bearer <token>. |
auth.token | yes | string | Only when type is bearer. Bearer token value. Supports ${ENV_VAR} placeholders. |
auth.type | yes | string: none | Only when type is none. No authentication — suitable for services on a trusted private network. |
keysPath | no | string | Path prefix for key endpoints on the remote service. Defaults to /keys. |
healthPath | no | string | Path for the health check endpoint on the remote service. Defaults to /health. |
canImport | no | boolean | Whether the remote service supports key import via POST {keysPath}/{kid}/import. Defaults to false. |
HTTP provider API
A service used as http provider implements these endpoints relative to
baseUrl. Bodies are JSON; requests carry the authentication configured in
auth. A reference service that keeps keys in memory and supports only ES256, for
development only, is in EUDIPLO/examples.
| Request | Body | Response |
|---|
POST {keysPath} | { "kid": "<key id>", "alg": "ES256" } | 200 { "publicJwk": { "kty": "EC", "crv": "<curve of alg>", … } } |
POST {keysPath}/{kid}/sign | { "data": "<base64 bytes>", "alg": "ES256" } | 200 { "signature": "<base64url raw r‖s, 64, 96 or 132 bytes>" } |
DELETE {keysPath}/{kid} | - | 204 |
GET {healthPath} | - | 200 (for example { "ok": true }) |
POST {keysPath}/{kid}/import | { "privateJwk": { … }, "alg": "ES256" } | 200 { "publicJwk": { … } }; only called with canImport: true |
keysPath defaults to /keys, healthPath to /health.
alg is ES256, ES384 or ES512; the provider's algorithms decide which
ones EUDIPLO sends for new and imported keys (only defaultAlgorithm, ES256
unless set, if algorithms is missing). The returned publicJwk must be on the matching curve
(P-256, P-384 or P-521), otherwise the key is refused. sign hashes data with
SHA-256, SHA-384 or SHA-512 and returns the raw r‖s of 64, 96 or 132 bytes.
Cloud Signature Consortium (csc)
| Field | Required | Type / allowed values | Description |
|---|
id | yes | string | Unique identifier for this provider instance. Used when generating keys to specify which provider to use. |
type | yes | string: csc | Type of the KMS provider. |
description | no | string | Human-readable description of this provider instance. |
algorithms | no | array of string: ES256 | ES384 | ES512 | Signing algorithms new and imported key chains of this provider may use: ES256 (P-256), ES384 (P-384), ES512 (P-521). An import through the API, the config folder or a configuration bundle whose key uses another algorithm is refused. Defaults to all three for db, vault and aws-kms. For pkcs11, http and csc, whose backends may not support every curve, it defaults to defaultAlgorithm (ES256 unless set). Existing keys keep signing with their own algorithm. |
defaultAlgorithm | no | string: ES256 | ES384 | ES512 | Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms. |
baseUrl | yes | string | Base URL of the CSC service (without trailing slash). Supports ${ENV_VAR} placeholders. |
tokenUrl | yes | string | OAuth2 token endpoint URL for client-credentials flow. Supports ${ENV_VAR} placeholders. |
clientId | yes | string | OAuth2 client ID. Supports ${ENV_VAR} placeholders. |
clientSecret | yes | string | OAuth2 client secret. Supports ${ENV_VAR} placeholders. |
scope | no | string | OAuth2 scope to request during token acquisition. |
credentialId | no | string | Default CSC credential ID. If omitted, the adapter calls credentials/list and picks the first entry. |
userId | no | string | Optional CSC user ID used in credentials/list requests. |
apiPath | no | string | CSC API path prefix appended to baseUrl. Defaults to /csc/v2. |
hashAlgorithmOid | no | string | Hash algorithm OID for signatures/signHash and credentials/authorize. Defaults to SHA-256 OID. |
signAlgorithmOid | no | string | Signature algorithm OID for signatures/signHash. Defaults to ecdsa-with-SHA256 OID. |
sad | no | string | Static SAD token. If set, the adapter sends it directly in signatures/signHash requests. |
useAuthorizeEndpoint | no | boolean | When true and no static SAD is provided, the adapter calls credentials/authorize to obtain SAD before signatures/signHash. |
authorizeAuthData | no | array of object | Optional authData array passed to credentials/authorize (e.g., PIN/OTP factors). |
authorizeAuthData[].id | yes | string | Authentication factor identifier expected by the CSC provider (e.g., PIN, OTP). |
authorizeAuthData[].value | yes | string | Authentication factor value sent to CSC credentials/authorize. |