Skip to main content

List keys

GET 
/v2/config/digital-wallet/openid/key-management/keys

Lists one page of the signing keys of the organisation, from all key stores or from one key store. The wallet uses these keys to sign OID4VCI credentials, status lists, signed issuer metadata and OpenID4VP requests. This operation returns public key material only. It never returns the private part of a key.

Each key has its name, its key store, its public JWK, its DIDs, isDefault (the wallet signs with this key by default) and usage: the number of credential definitions and presentation definitions that sign with the key. The read key usage operation gives the details.

Filter with keyStoreId, search and withCertificateChain, order with sortBy and sortOrder, and page with limit and offset. Without sortBy the last updated key comes first. An offset past the end gives the last page. The search and the usage counts read the definitions of the organisation and its sandbox organisations only. A sandbox organisation gets the keys of its main organisation.

Request​

Query Parameters

    keyStoreId stringrequired

    Possible values: <= 64 characters

    Keeps the keys of one key store. Without it, the answer has the keys of all key stores.

    Example: local-openbao
    search stringrequired

    Possible values: <= 128 characters

    Keeps the keys whose key ID or name contains the text, and the keys that a credential or presentation definition whose name or ID contains the text signs with. An ID also matches without its hyphens. Case insensitive, at most 128 characters.

    withCertificateChain booleanrequired

    Default value: false

    With true, keeps the keys that have an X.509 certificate chain.

    sortBy stringrequired

    Possible values: [name, createdAt, updatedAt]

    Default value: updatedAt

    Order of the keys. Without it the last updated key comes first. With name, keys without a name come last in both directions. The key ID ends every order, so the order stays the same from one page to the next.

    sortOrder stringrequired

    Possible values: [asc, desc]

    Ascending or descending order. The default is asc for sortBy name and desc for the times.

    offset integerrequired

    Default value: 0

    Number of records to skip for pagination. A negative or unreadable value falls back to 0.

    limit integerrequired

    Default value: 10

    Maximum number of records to return per page.

Responses​

The service returned one page of the keys of the organisation.

Response Headers
    Schema
      keys object[]required

      The keys on this page. The list is empty when no key agrees with the filters.

    • Array [
      • keyId stringrequired

      Unique identifier of the key. The wallet makes it, and it cannot change. The value is the same as jwk.kid.

      name stringnullablerequired

      Possible values: <= 100 characters

      Name of the key, given by an administrator when the key is created or with the update key operation. null when the key has no name.

      keyStore objectrequired

      The key store that holds the key.

      id stringrequired

      Unique identifier of the key store.

      type stringrequired

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

      Type of the key store.

      name stringrequired

      Name of the key store.

      origin stringnullablerequired

      Possible values: [created, imported, referenced]

      How the key came to the organisation. created, the wallet created the key in the key store (also in a cloud KMS or a DPoD partition of the organisation). imported, the import key operation imported the key, with or without a certificate chain. referenced, the key was already in the key store of the provider, and the wallet signs with it there.

      algorithm stringnullablerequired

      Signature algorithm of the key.

      status stringrequired

      Status of the key. The wallet signs with a key that has the status active.

      isDefault booleanrequired

      Shows true when the wallet signs with this key by default.

      jwk objectrequired

      Public key in JSON Web Key (JWK) format. The service sends only public members. It never sends the private key member d.

      kty stringrequired

      Key type. The service always sends this member. The keys are elliptic curve keys, so the value is EC.

      crv string

      Elliptic curve identifier. The keys are P-256 keys, so the value is P-256.

      x string

      X coordinate of the elliptic curve point, in base64url format.

      y string

      Y coordinate of the elliptic curve point, in base64url format.

      kid string

      Key identifier. The value is the same as keyId.

      alg string

      Signature algorithm for the key, for example ES256 for a P-256 key.

      x5c string[]

      Certificate chain of the key as it is stored, in leaf to root order (for a test certificate, the leaf and the test root). Each item is a base64 encoded DER certificate. The service adds this member only when the key has a certificate chain. The x5c header of a signature and the mdoc x5chain have the leaf and the intermediate certificates, without the trust anchor.

      x5t string

      SHA-1 thumbprint of the leaf certificate. The service adds this member only when the key has a certificate chain.

      x5t#S256 string

      SHA-256 thumbprint of the leaf certificate. Note the # in the member name. The upload certificate chain operation gives the same value as x5t_s256.

      x5c_expiry string

      Expiry time of the leaf certificate, in UTC. The service adds this member only when the key has a certificate chain.

      dids string[]required

      DIDs that come from this key.

      hasCertificateChain booleanrequired

      Shows true when the key has an X.509 certificate chain. Then the key can sign with the x509 format.

      certificateSource stringnullablerequired

      Possible values: [uploaded, imported, test-ca, qtsp, null]

      Where the certificate chain of the key comes from. uploaded, the upload certificate chain operation. imported, the import key operation with a certificate. test-ca, the built-in test CA (the create test certificate operation), for development and testing only. qtsp, the certificate of the QTSP credential. null when the key has no certificate chain.

      testCertificate booleanrequired

      Shows true only when certificateSource is test-ca. The built-in test CA issued the certificate, which is for development and testing only. Wallets and verifiers outside this platform do not trust it.

      certificatePreset stringnullablerequired

      The preset of the certificate chain of the key (the list certificate presets operation). For a test certificate, the preset of its request. For an uploaded chain, the preset of the newest CSR of the key. null when there is none.

      certificateAssessment object

      What the leaf certificate of the key allows: its key usage type, the credential categories that it fits, the mDL Document Signer profile, its QcPSB statement, and the texts of the save check for each category. The wallet reads the certificate chain of the key. A key without a certificate chain, or with a leaf that the wallet cannot read, gives keyUsageType null, empty lists, mdlDocumentSigner false, qcPsb null and texts such as An EAA needs a seal certificate of a legal person. This key has no certificate. Request a certificate with the preset EAA provider (eaa-provider). The texts do not count the trusted-list exemption of the key: an exempt key is never refused.

      keyUsageType stringnullablerequired

      Possible values: [A, B, C, D, E, F, null]

      The key usage type of the leaf certificate (ETSI EN 319 412-2 clause 4.3.2, table 1). A: nonRepudiation. B: nonRepudiation and digitalSignature. C: digitalSignature. D: digitalSignature and keyEncipherment or keyAgreement. E: keyEncipherment or keyAgreement. F: nonRepudiation, digitalSignature and keyEncipherment or keyAgreement. null when the certificate has another key usage (for example with keyCertSign) or no key usage.

      fitsCredentialCategories CredentialCategoryId[]required

      Possible values: [none, pid, eaa, qeaa, pub-eaa]

      The credential categories that the certificate fits (the list credential categories operation), without none. A PID certificate fits only pid, and a PID certificate with another key usage type fits no category.

      fitsCredentialCategoriesForMdl CredentialCategoryId[]required

      Possible values: [none, pid, eaa, qeaa, pub-eaa]

      The credential categories that the certificate fits for an mDL configuration, without none. The rules are the same as for fitsCredentialCategories, but eaa, qeaa and pub-eaa also accept key usage Type C. A key signs an mDL configuration only when mdlDocumentSigner is true and the category of the configuration is in this list.

      mdlDocumentSigner booleanrequired

      Shows true when the certificate has the Document Signer profile of ISO/IEC 18013-5 Table B.3 (key usage digitalSignature and extended key usage 1.0.18013.5.1.2, both critical). A key signs an mDL (doctype org.iso.18013.5.1.mDL) only with this profile.

      qcPsb objectnullablerequired

      The QcPSB statement (0.4.0.194126.1.3) of a PuB-EAA provider, with all three values. null when the certificate has no QcPSB statement. A key with this statement signs only the attestations under its law (legislationIdentification, countryOfLegislation) and from its authentic source (authSourceIdentification), ETSI TS 119 412-6 clause 8.3.

      countryOfLegislation stringrequired

      The country of the law, an ISO 3166-1 alpha-2 code, or EU for European Union law (ETSI TS 119 412-6 PSB-8.3-05). A PrintableString of two characters in the certificate.

      authSourceIdentification stringrequired

      The unambiguous identification of the authentic source (PSB-8.3-04), for example a list of relative distinguished names. At most 2048 characters, no control character.

      legislationIdentification stringrequired

      The identification of the law under which the public sector body is responsible for the authentic source (PSB-8.3-02). Use a URI (RFC 3986) when one exists (PSB-8.3-03). At most 2048 characters, no control character.

      categoryMessages objectrequired

      For each credential category, the texts of the save check for a configuration that is not an mDL. none is always an empty list.

      none string[]required
      pid string[]required
      eaa string[]required
      qeaa string[]required
      pub-eaa string[]required
      mdlConfigurationMessages objectrequired

      For each credential category, the texts of the save check for an mDL configuration (mso_mdoc with doctype org.iso.18013.5.1.mDL) of that category. First the category rule (with key usage Type C also allowed for eaa, qeaa and pub-eaa), then the ISO/IEC 18013-5 Document Signer rule. none has only the Document Signer rule.

      none string[]required
      pid string[]required
      eaa string[]required
      qeaa string[]required
      pub-eaa string[]required
      trustedListExemption objectnullable

      The trusted-list exemption of a key: the certificate of the key is in a trusted list, or chains to a listed CA. While the exemption applies, a rule of the signing key check that the key does not fit gives the check result exempt and no refusal. The exemption is bound to the leaf certificate that the key had when the exemption was set (leafSha256): with another leaf, applies is false and reason says why and what to do (null while it applies). listUri is the source of the exemption: the URL of the trusted list, or a text, for example a recorded decision. Only the platform operator sets or removes it; the API cannot change it. The other members: listUri (the trusted list), service (the service of the list), certificateSha256 (the SHA-256 fingerprint of the certificate of the list), match (how the certificate of the key matched the list), setAt (the time, in UTC) and setBy (who set it). Each of them can be null.

      listUri stringnullable
      service stringnullable
      certificateSha256 stringnullable
      leafSha256 stringnullable
      match stringnullable
      setAt date-timenullable
      setBy stringnullable
      applies booleanrequired
      reason stringnullable
      qscd required

      Shows if the key store keeps the key in a qualified signature creation device (QSCD). false, or provider for a key of a qualified trust service provider (key store type csc): the provider decides. The value comes from the key store.

      trust objectnullable

      The qualified status of a key of a key store of a qualified trust service provider: its leaf certificate against the EU trusted lists. The wallet checks it when the key is referenced and when the connection of the key store is tested.

      status stringrequired

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

      qualified: the certificate chains to a qualified certificate authority (service type CA/QC with the status granted) on the EU trusted list, and it is a qualified certificate for electronic signatures or electronic seals whose private key is in a qualified signature or seal creation device (QSCD). not-qualified: the trusted lists say no. unknown: the installation has no EU trusted list source, a list cannot be read, or the key was not checked yet.

      checkedAt stringnullablerequired

      Time of the check, in UTC. null when the key was not checked yet.

      detail stringnullablerequired

      The facts that gave the result, for example the certificate authority and the trusted list, and whether the trusted list or the certificate says that the key is in a QSCD.

      usage object

      The number of credential definitions and presentation definitions that sign with the key. Only the list keys operation returns this member. A credential definition counts once, also when several of its configurations or its status lists use the key. The read key usage operation gives the details.

      credentialDefinitions integerrequired

      Number of credential definitions that sign with the key.

      presentationDefinitions integerrequired

      Number of presentation definitions that sign with the key.

      createdAt date-timenullablerequired

      Creation time of the key, in UTC.

      updatedAt date-timenullablerequired

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

    • ]
      • pagination objectrequired

      Page details of the key list.

      totalItems integerrequired

      Number of keys that agree with the filters, on all pages.

      limit integerrequired

      Maximum number of keys on the page.

      offset integerrequired

      Number of keys before this page. An offset past the end gives the last page, and this value is the offset of that page.

      hasNext booleanrequired

      Shows true when there is a next page.

    Loading...
    Last updated on