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

Setup Key Service

In the following section, we will setup a KMS service inside of a tenant. If you don't have a tenant yet, you can learn how to create one here.

CURL

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 named test, your default Base URL will be test.enterprise-sandbox.walt.dev when 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 case kms

Response Codes

  • 201 - Service created successfully.

Create Key

CURL

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 named test, your default Base URL will be test.enterprise-sandbox.walt.dev when 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. jwk means 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.

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"
}
OverviewHashicorp Vault