KMS Config (kms.json)

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} and ${VAR:default} placeholders, resolved from the backend's environment. defaultProvider must match a provider id, and provider IDs must be unique.

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.

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.
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.
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.
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.
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 in shape 1 of 4. OAuth 2.0 Client Credentials — EUDIPLO fetches and caches short-lived tokens.
auth.tokenUrl	yes	string	Only in shape 1 of 4. Token endpoint URL (e.g. Keycloak, Entra ID). Supports ${ENV_VAR} placeholders.
auth.clientId	yes	string	Only in shape 1 of 4. OAuth 2.0 client ID. Supports ${ENV_VAR} placeholders.
auth.clientSecret	yes	string	Only in shape 1 of 4. OAuth 2.0 client secret. Supports ${ENV_VAR} placeholders.
auth.scope	no	string	Only in shape 1 of 4. Space-separated list of OAuth 2.0 scopes to request. Optional.
auth.type	yes	string: mtls	Only in shape 2 of 4. Mutual TLS — EUDIPLO presents a client certificate on every connection.
auth.certFile	yes	string	Only in shape 2 of 4. Absolute path to the PEM-encoded client certificate file. Supports ${ENV_VAR} placeholders.
auth.keyFile	yes	string	Only in shape 2 of 4. Absolute path to the PEM-encoded private key file for the client certificate. Supports ${ENV_VAR} placeholders.
auth.caFile	no	string	Only in shape 2 of 4. 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 in shape 3 of 4. Static Bearer token sent as Authorization: Bearer <token>.
auth.token	yes	string	Only in shape 3 of 4. Bearer token value. Supports ${ENV_VAR} placeholders.
auth.type	yes	string: none	Only in shape 4 of 4. 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.

Request	Body	Response
POST {keysPath}	{ "kid": "<key id>", "alg": "ES256" }	200 { "publicJwk": { "kty": "EC", "crv": "P-256", … } }
POST {keysPath}/{kid}/sign	{ "data": "<base64 bytes>", "alg": "ES256" }	200 { "signature": "<base64url raw r‖s, 64 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.

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.
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.