Skip to main content

Create key store

POST 
/v2/config/digital-wallet/openid/key-management/key-stores

Adds a key store of a provider to the organisation: an external OpenBao or HashiCorp Vault (vault), a key ring in Google Cloud KMS (gcp-kms), one region of AWS KMS (aws-kms), an Azure key vault or managed HSM (azure-key-vault), a Thales Luna Cloud HSM partition (dpod), or a remote signing service with the Cloud Signature Consortium (CSC) API (csc), for example a qualified trust service provider. Give the provider in provider: an id of the providers of the list key store types operation, of the same type. The type local cannot be added: each organisation can already use the key store of the installation.

The wallet checks the format of the settings and of the credentials, then does a connection test. It saves the key store only when the test passes.

TypeConnection test
vaultLog in with the authentication method, read the health of the vault and list the keys of the Transit mount.
gcp-kmsList the keys of the key ring.
aws-kmsList the keys of the region.
azure-key-vaultGet a token of the application from Microsoft Entra ID and list the keys of the vault.
dpodPut the key store on a signer shard, give the partition to the HSM signer of the platform, wait (at most 90 seconds) until the partition is active, then sign and verify with a session key that does not stay in the partition. When the test fails, the wallet deletes the key store again.
cscGet an OAuth 2.0 token and list the credentials.

A right that the key store does not give to the wallet gives The connection test failed: Key management service refused the request. The wallet refuses an address in a private network, unless the installation allows private addresses. The cloud KMS types use only the official endpoints of the provider.

The credentials are write-only. No answer returns them. An organisation can have at most one key store of each provider. A sandbox organisation cannot add a key store.

Request​

Body

required

The type, the name, the settings and the credentials of the key store.

    type stringrequired

    Possible values: [vault, gcp-kms, aws-kms, azure-key-vault, dpod, csc]

    Type of the key store.

    provider stringrequired

    Possible values: <= 64 characters

    The provider of the key store, an id of the providers of the list key store types operation. Required. The provider must not be hidden by the installation, and its type must be type.

    name stringrequired

    Possible values: <= 100 characters

    Name of the key store, at most 100 characters. It must be unique in the organisation.

    settings object required

    Settings of the type. The wallet refuses an unknown member and checks the format of each value (for example the AWS region, the Azure tenant ID and vault URL, the Google Cloud project ID). An invalid value gives 400 with <field>: <problem>.

    oneOf
    address stringrequired

    Base address of the vault, with https://. The wallet refuses http:// and private network addresses, unless the installation allows private addresses (for example on premises).

    namespace stringnullable

    Namespace in the vault. Leave it out or send null when the vault has no namespaces.

    transitMount stringnullable

    Mount path of the Transit secrets engine. The default is transit.

    caCertificate stringnullable

    PEM bundle of the certificate authorities that the wallet trusts for the TLS certificate of the vault. Without it, the wallet uses the system certificate authorities.

    clientCertificate stringnullable

    PEM client certificate for mutual TLS. Required for the authentication method cert. With another method, send it when the listener of the vault requires mutual TLS. The private key of the certificate goes in the credential clientPrivateKey.

    authentication objectrequired

    How the wallet logs in to the vault.

    method stringrequired

    Possible values: [userpass, approle, cert, token]

    Authentication method. userpass needs username and the credential password. approle needs roleId and the credential secretId. cert needs clientCertificate and the credential clientPrivateKey, and can have role. token needs the credential token.

    mount stringnullable

    Mount path of the authentication method. The default is the name of the method (userpass, approle or cert).

    username stringnullable

    User name, for the method userpass.

    roleId stringnullable

    Role ID, for the method approle.

    role stringnullable

    Name of the certificate role, for the method cert. Optional.

    credentials object

    Write-only credentials of the type. Give the credentials that the settings use (for vault and azure-key-vault, the credentials of the authentication method).

    oneOf
    password string

    Password, for the method userpass.

    secretId string

    Secret ID, for the method approle.

    token string

    Vault token, for the method token.

    clientPrivateKey string

    PEM private key of clientCertificate, without a password. Required for the method cert, and when you give clientCertificate with another method.

Responses​

The service tested and saved the key store, and returned it.

Response Headers
    Schema
      id stringrequired

      Unique identifier of the key store. local-openbao, local-database or local-hsm for a key store of the installation, else a UUID.

      type stringrequired

      Possible values: [local, vault, gcp-kms, aws-kms, azure-key-vault, dpod, csc]

      Type of the key store. local is a key store of the installation (OpenBao Transit, the wallet database, or the hardware security module of the installation). Each organisation can use it, and the API cannot add, change or delete it. vault is an external OpenBao or HashiCorp Vault of the organisation. gcp-kms is a key ring in Google Cloud KMS. aws-kms is one region of an AWS account (AWS KMS). azure-key-vault is an Azure key vault or managed HSM. dpod is a partition of a Thales Luna Cloud HSM service (DPoD). csc is a remote signing service with the Cloud Signature Consortium (CSC) API, for example a qualified trust service provider (QTSP).

      provider stringnullablerequired

      The provider of the key store, an id of the providers of the list key store types operation (for example openbao, hashicorp-vault, google-cloud-kms or intesi). null for a local key store. It cannot change. An organisation has at most one key store of each provider.

      name stringrequired

      Possible values: <= 100 characters

      Name of the key store. It is unique in the organisation.

      local booleanrequired

      Shows true for a key store of the installation (type local).

      status stringrequired

      Possible values: [active, disabled, error]

      Status of the key store. active when the key store works. error after a connection test that failed. disabled is reserved.

      protection stringnullablerequired

      Possible values: [software, hsm, hsm-backed, dedicated-hsm, provider]

      Where the private keys of this key store are. software: in the software of a key management service (local with the backend openbao or database, vault, gcp-kms with the protection level SOFTWARE, azure-key-vault with the key type EC). hsm: in the hardware security module of the installation (local with the backend hsm). hsm-backed: in a cloud KMS that keeps the keys in hardware security modules of the cloud provider (gcp-kms with HSM, aws-kms, azure-key-vault with EC-HSM). dedicated-hsm: in a hardware security module partition of the organisation (dpod). provider: at the provider, which decides how it protects the keys (csc). An organisation key store has the protection of its provider, unless its settings decide.

      settings object required

      Settings of the key store type. Never a secret.

      oneOf
      backend string

      Possible values: [openbao, database, hsm]

      Where the installation keeps the keys. openbao for OpenBao Transit (local-openbao), database for the wallet database (local-database, legacy, no new keys), hsm for the hardware security module of the installation (local-hsm). With hsm, the new local keys of the organisations go to the HSM; the keys in local-openbao stay there and keep working.

      protection string

      Possible values: [software, hsm]

      How the key store protects the keys. software for the backends openbao and database, hsm for the backend hsm.

      credentialsConfigured objectrequired

      For each credential field of the key store type, true when the wallet has a value. The answer never has the value. Empty for the type local. The fields: vault password, secretId, token, clientPrivateKey; gcp-kms serviceAccountKey; aws-kms accessKeyId, secretAccessKey; azure-key-vault clientSecret, clientCertificate, clientPrivateKey; dpod authTokenConfigUri, authTokenClientId, authTokenClientSecret, pin; csc clientSecret, userPin.

      property name* boolean
      capabilities string[]required

      Possible values: [create, import, reference, sign, csr, certificateChain, listProviderKeys, test, edit, delete]

      What the key store can do. The type sets them. local (the key store that takes new keys): create, import, sign, csr, certificateChain, test (no import with the backend hsm). local (the other key store of the installation): sign, csr, certificateChain, test. vault: create, import, reference, sign, csr, certificateChain, listProviderKeys, test, edit, delete. gcp-kms, aws-kms, azure-key-vault and dpod: create, reference, sign, csr, certificateChain, listProviderKeys, test, edit, delete (no import). csc: reference, sign, listProviderKeys, test, edit, delete.

      qscd required

      Shows if the key store keeps the keys in a qualified signature creation device (QSCD). false, or provider for the type csc, where the QTSP decides.

      keyCount integerrequired

      Number of keys of the organisation in the key store.

      qualifiedStatus stringnullablerequired

      Possible values: [qualified, not-qualified, unknown]

      Only for a key store of a provider with qualified true (category qtsp): qualified when every key of the key store is qualified and there is at least one key, not-qualified when a key is not, else unknown. null for every other key store: no other key store claims a qualified status. See trust of the key.

      lastCheckedAt stringnullablerequired

      Time of the last connection test, in UTC. null before the first test.

      lastCheckResult objectnullable

      Result of a connection test of a key store.

      ok booleanrequired

      Shows true when the connection test passed.

      message stringnullablerequired

      Why the connection test failed, as a safe text. It never has a secret or the detail of the provider. null when the test passed.

      checkedAt stringnullablerequired

      Time of the connection test, in UTC.

      createdAt stringnullablerequired

      Creation time of the key store, in UTC.

      updatedAt stringnullablerequired

      Time of the last change of the key store, in UTC.

    Loading...
    Last updated on