Local
When using the local configuration for the Key Management Service (KMS), all key information is stored in the Enterprise Stack database. This option is ideal for getting started since it doesn't require any external dependencies. However, for production use cases, we recommend using an external KMS solution. This approach ensures that your secrets remain secure and are not exposed outside of a protected environment, which helps reduce the risk of key compromises.
Key Algorithms Supported
The local KMS configuration allows the creation of these key types:
- ed25519
- secp256k1
- secp256r1
- RSA
Endpoint: /v1/{target}/resource-api/services/create | API Reference
Example Request
curl -X 'POST' \
'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
-H 'accept: */*' \
-H 'Authorization: Bearer {yourToken}' \
-H 'Content-Type: application/json' \
-d '{
"type": "kms"
}'
Body
{
"type": "kms"
}
Path Parameters
orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is namedtest, your default Base URL will betest.enterprise-sandbox.walt.devwhen using the sandbox environment.target: resourceIdentifier - The target indicates the organization + tenant in which to create the new KMS service and the service's ID ({organizationID}.{tenantID}.[NewKmsServiceID]), e.g.waltid.tenant1.kms1
Body Parameters
type: serviceType - Specifies the type of service to create. In our casekms
Response Codes
201- Service created successfully.
Create Key
Endpoint: /v1/{target}/kms-service-api/keys/generate | API Reference
Example Request
curl -X 'POST' \
'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/generate' \
-H 'accept: */*' \
-H 'Authorization: Bearer {yourToken}' \
-H 'Content-Type: application/json' \
-d '{
"backend": "jwk",
"keyType": "Ed25519"
}'
Body
{
"backend": "jwk",
"keyType": "Ed25519"
}
Path Parameters
orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is namedtest, your default Base URL will betest.enterprise-sandbox.walt.devwhen using the sandbox environment.target: resourceIdentifier - The target indicates the organization + tenant + kmsService in which to create the new key and the key's ID ({organizationID}.{tenantID}.{kmsServiceID}.[newKeyID]), e.g.waltid.tenant1.kms1.key1
Body Parameters
backend: String - Specifies the storage type of key.jwkmeans the local storage option is used and the key is stored in the Enterprise Stack backend.keyType: String - the algorithm used to generate the key. For local, it can be ed25519, secp256k1, secp256r1, or RSA. Generation does not setuse, so the key may perform every operation that key type supports. Import a JWK withusewhen the key must be limited to signing or to encryption.
Response
201 - Key created successfully.
{
"_id": "waltid.tenant1.kms1.key1",
"key": {
"type": "jwk",
"jwk": {
"kty": "OKP",
"d": "ywmoRVTD9fexMtGW0lKE3o9_0ulfzGXr9xHGL0lPhhA",
"crv": "Ed25519",
"kid": "IQO7DILxtagpTLXkuHkRkJURb2GqcUIwXYZAcGwW1AU",
"x": "JOsiIE7ME9UZ8y2H-P5RSuYAUiIfs1ywtdBjMGN7I5s"
}
},
"parent": "waltid.tenant1.kms1"
}
Restrict a JWK with use
use is optional. When it is absent, Enterprise allows every operation the key type supports. A P-256 key can then
sign and perform key agreement. Ed25519 can sign and verify.
Set use on an imported or stored JWK to limit those operations:
use | Permitted operations |
|---|---|
sig | Sign and verify. The key cannot perform key agreement. |
enc | Encryption operations. A P-256 key can perform ECDH-ES key agreement and cannot sign. |
| omitted | Every operation supported by the key type. |
Endpoint: /v1/{target}/kms-service-api/keys/import/jwk | API Reference
Example Request
curl -X 'POST' \
'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/import/jwk' \
-H 'accept: */*' \
-H 'Authorization: Bearer {yourToken}' \
-H 'Content-Type: application/json' \
-d '{
"kty": "EC",
"crv": "P-256",
"use": "sig",
"d": "sSyXzIV_SAqDcG1Zh-XY18-pVNuIXVOqGUDMpRKFrWs",
"x": "vY_bjQpiaM52LRcL25_Agv1D2ypmJiyDDsIsYqCDoIc",
"y": "eWPx0z1AizI04weurWEaVb3I0iRCITdKuLP6gnUpGWU"
}'
Body
{
"kty": "EC",
"crv": "P-256",
"use": "sig",
"d": "sSyXzIV_SAqDcG1Zh-XY18-pVNuIXVOqGUDMpRKFrWs",
"x": "vY_bjQpiaM52LRcL25_Agv1D2ypmJiyDDsIsYqCDoIc",
"y": "eWPx0z1AizI04weurWEaVb3I0iRCITdKuLP6gnUpGWU"
}
Body Parameters
use: String -sigallows signing and verification only.
Response Codes
200- Key imported successfully.
