Skip to main content

Update key store

PUT 
/v2/config/digital-wallet/openid/key-management/key-stores/:keyStoreId

Changes the name, the settings or the credentials of a key store that the organisation added. The operation changes only the members that the body gives. settings, when given, replaces all the settings. A credential field that the body does not give keeps the stored value.

The credentials follow the authentication method. When settings.authentication.method changes (vault, aws-kms, azure-key-vault), the wallet deletes the stored credentials of the old method in the same change, so a stale secret never stays. Give the credentials of the new method, unless the wallet already has them. For example, an Azure key store that changes from clientSecret to clientCertificate needs clientCertificate and clientPrivateKey, and the wallet deletes the stored clientSecret.

The wallet checks the settings and does the connection test again. It saves the change only when the test passes. For dpod, a new PIN or new credentials make the HSM signer log in again, one time. When the test of a dpod key store fails and the key store worked before, the text of the 400 ends with The key store keeps its earlier settings and credentials.; else the new values stay and the key store has the status error. The provider of a key store cannot change. A local key store is read only. A sandbox organisation cannot change a key store.

Request​

Path Parameters

    keyStoreId stringrequired

    Possible values: <= 64 characters

    Unique identifier of the key store. local-openbao, local-database or local-hsm for a key store of the installation, else the identifier that the create key store operation returned.

    Example: local-openbao

Body

required

The members to change.

    name string

    Possible values: <= 100 characters

    New name of the key store, at most 100 characters. It must be unique in the organisation. A key store always has a name, so null is not accepted.

    provider string

    Possible values: <= 64 characters

    The provider of the key store. It cannot change, so a given value must be the stored one (another value gives 400).

    settings object

    All the settings of the type. They replace the stored settings.

    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 to change. A field of the same authentication method that you leave out keeps the stored value.

    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 change, and returned the key store.

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