Skip to main content

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} 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​

FieldRequiredType / allowed valuesDescription
defaultProvidernostringID of the default KMS provider. Defaults to "db" if not set.
providersyesarray of one of 6 shapesList 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)​

FieldRequiredType / allowed valuesDescription
idyesstringUnique identifier for this provider instance. Used when generating keys to specify which provider to use.
typeyesstring: dbType of the KMS provider.
descriptionnostringHuman-readable description of this provider instance.
algorithmsnoarray of string: ES256 | ES384 | ES512Signing 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.
defaultAlgorithmnostring: ES256 | ES384 | ES512Algorithm 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)​

FieldRequiredType / allowed valuesDescription
idyesstringUnique identifier for this provider instance. Used when generating keys to specify which provider to use.
typeyesstring: vaultType of the KMS provider.
descriptionnostringHuman-readable description of this provider instance.
algorithmsnoarray of string: ES256 | ES384 | ES512Signing 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.
defaultAlgorithmnostring: ES256 | ES384 | ES512Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms.
vaultUrlyesstringURL of the HashiCorp Vault instance. Supports ${ENV_VAR} placeholders.
vaultTokenyesstringAuthentication token for HashiCorp Vault. Supports ${ENV_VAR} placeholders.

AWS KMS (aws-kms)​

FieldRequiredType / allowed valuesDescription
idyesstringUnique identifier for this provider instance. Used when generating keys to specify which provider to use.
typeyesstring: aws-kmsType of the KMS provider.
descriptionnostringHuman-readable description of this provider instance.
algorithmsnoarray of string: ES256 | ES384 | ES512Signing 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.
defaultAlgorithmnostring: ES256 | ES384 | ES512Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms.
regionyesstringAWS region for KMS. Supports ${ENV_VAR} placeholders.
accessKeyIdnostringAWS access key ID. Optional — uses SDK credential chain if not provided. Supports ${ENV_VAR} placeholders.
secretAccessKeynostringAWS secret access key. Optional — uses SDK credential chain if not provided. Supports ${ENV_VAR} placeholders.

PKCS#11 (pkcs11)​

FieldRequiredType / allowed valuesDescription
idyesstringUnique identifier for this provider instance. Used when generating keys to specify which provider to use.
typeyesstring: pkcs11Type of the KMS provider.
descriptionnostringHuman-readable description of this provider instance.
algorithmsnoarray of string: ES256 | ES384 | ES512Signing 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.
defaultAlgorithmnostring: ES256 | ES384 | ES512Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms.
libraryyesstringAbsolute path to the PKCS#11 module library (.so/.dll/.dylib). Supports ${ENV_VAR} placeholders.
slotyesnumber | stringSlot selection. Either the numeric slot index (as a string for ENV interpolation, or a number) or the token label. Supports ${ENV_VAR} placeholders.
pinyesstringUser PIN used for C_Login. Supports ${ENV_VAR} placeholders.
readOnlynobooleanOpen the PKCS#11 session in read-only mode. Defaults to false.

Remote HTTP service (http)​

FieldRequiredType / allowed valuesDescription
idyesstringUnique identifier for this provider instance. Used when generating keys to specify which provider to use.
typeyesstring: httpType of the KMS provider.
descriptionnostringHuman-readable description of this provider instance.
algorithmsnoarray of string: ES256 | ES384 | ES512Signing 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.
defaultAlgorithmnostring: ES256 | ES384 | ES512Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms.
baseUrlyesstringBase URL of the remote KMS microservice (no trailing slash). Supports ${ENV_VAR} placeholders.
authnoone of 4 shapesAuthentication 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.typeyesstring: oauth2-client-credentialsOnly when type is oauth2-client-credentials. OAuth 2.0 Client Credentials — EUDIPLO fetches and caches short-lived tokens.
auth.tokenUrlyesstringOnly when type is oauth2-client-credentials. Token endpoint URL (e.g. Keycloak, Entra ID). Supports ${ENV_VAR} placeholders.
auth.clientIdyesstringOnly when type is oauth2-client-credentials. OAuth 2.0 client ID. Supports ${ENV_VAR} placeholders.
auth.clientSecretyesstringOnly when type is oauth2-client-credentials. OAuth 2.0 client secret. Supports ${ENV_VAR} placeholders.
auth.scopenostringOnly when type is oauth2-client-credentials. Space-separated list of OAuth 2.0 scopes to request. Optional.
auth.typeyesstring: mtlsOnly when type is mtls. Mutual TLS — EUDIPLO presents a client certificate on every connection.
auth.certFileyesstringOnly when type is mtls. Absolute path to the PEM-encoded client certificate file. Supports ${ENV_VAR} placeholders.
auth.keyFileyesstringOnly when type is mtls. Absolute path to the PEM-encoded private key file for the client certificate. Supports ${ENV_VAR} placeholders.
auth.caFilenostringOnly 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.typeyesstring: bearerOnly when type is bearer. Static Bearer token sent as Authorization: Bearer <token>.
auth.tokenyesstringOnly when type is bearer. Bearer token value. Supports ${ENV_VAR} placeholders.
auth.typeyesstring: noneOnly when type is none. No authentication — suitable for services on a trusted private network.
keysPathnostringPath prefix for key endpoints on the remote service. Defaults to /keys.
healthPathnostringPath for the health check endpoint on the remote service. Defaults to /health.
canImportnobooleanWhether 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.

RequestBodyResponse
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)​

FieldRequiredType / allowed valuesDescription
idyesstringUnique identifier for this provider instance. Used when generating keys to specify which provider to use.
typeyesstring: cscType of the KMS provider.
descriptionnostringHuman-readable description of this provider instance.
algorithmsnoarray of string: ES256 | ES384 | ES512Signing 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.
defaultAlgorithmnostring: ES256 | ES384 | ES512Algorithm used when a key chain is created without one. Must be in algorithms. Defaults to ES256 if allowed, otherwise the first entry of algorithms.
baseUrlyesstringBase URL of the CSC service (without trailing slash). Supports ${ENV_VAR} placeholders.
tokenUrlyesstringOAuth2 token endpoint URL for client-credentials flow. Supports ${ENV_VAR} placeholders.
clientIdyesstringOAuth2 client ID. Supports ${ENV_VAR} placeholders.
clientSecretyesstringOAuth2 client secret. Supports ${ENV_VAR} placeholders.
scopenostringOAuth2 scope to request during token acquisition.
credentialIdnostringDefault CSC credential ID. If omitted, the adapter calls credentials/list and picks the first entry.
userIdnostringOptional CSC user ID used in credentials/list requests.
apiPathnostringCSC API path prefix appended to baseUrl. Defaults to /csc/v2.
hashAlgorithmOidnostringHash algorithm OID for signatures/signHash and credentials/authorize. Defaults to SHA-256 OID.
signAlgorithmOidnostringSignature algorithm OID for signatures/signHash. Defaults to ecdsa-with-SHA256 OID.
sadnostringStatic SAD token. If set, the adapter sends it directly in signatures/signHash requests.
useAuthorizeEndpointnobooleanWhen true and no static SAD is provided, the adapter calls credentials/authorize to obtain SAD before signatures/signHash.
authorizeAuthDatanoarray of objectOptional authData array passed to credentials/authorize (e.g., PIN/OTP factors).
authorizeAuthData[].idyesstringAuthentication factor identifier expected by the CSC provider (e.g., PIN, OTP).
authorizeAuthData[].valueyesstringAuthentication factor value sent to CSC credentials/authorize.