Skip to main content

Create key

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

Adds a signing key to the organisation in one of two ways:

  • Create a key in a key store that can create keys (capability create: local, vault, gcp-kms, aws-kms, azure-key-vault and dpod). The key is an ECDSA P-256 key with the algorithm ES256, and it cannot be exported. All fields are optional: without keyStoreId the wallet uses the local key store that takes new keys, so the empty body {} creates a key there. The API never returns the private key of a key.
  • Reference a key that the provider already has (capability reference: vault, gcp-kms, aws-kms, azure-key-vault, dpod and csc). Give keyStoreId and providerKeyRef. Get the references with the list provider keys operation. The wallet reads the public key from the provider. For every type except csc, it also signs a test message and verifies the signature. For a QTSP key (csc), give the PIN of the CSC credential in providerSecret, or leave it out to use the userPin of the key store. For a key store of a provider with qualified true, the wallet checks the leaf certificate of the credential against the EU trusted lists and returns the result in trust of the key.

What the wallet makes when it creates a key: vault, a Transit key ecdsa-p256 with the key ID as its name; gcp-kms, the crypto key ows-<keyId> (purpose ASYMMETRIC_SIGN, algorithm EC_SIGN_P256_SHA256, the protection level of the key store); aws-kms, a key ECC_NIST_P256 SIGN_VERIFY with the alias alias/ows-<keyId>; azure-key-vault, the key ows-<keyId> (P-256, the key type of the key store); dpod, a P-256 key pair in the partition with the label ows:<keyId>.

Give the key a name in name, for example what it signs. The key list and the dashboard show it, and the update key operation changes it later. The wallet refuses an unknown field. A call with a sandbox API key acts on the key stores and keys of the main organisation.

Request​

Body

The key store and the name of the new key, or the key store and the reference of a provider key.

    keyStoreId string

    Possible values: <= 64 characters

    Key store of the key. Optional when you create a key (the default is the local key store that takes new keys). Required when you reference a provider key.

    name string

    Possible values: <= 100 characters

    Name of the key, for example what it signs. Optional, at most 100 characters.

    algorithm string

    Possible values: [ES256]

    Signature algorithm of a new key. Optional. ES256 is the only value.

    providerKeyRef string

    Possible values: <= 512 characters

    Reference of a key that the provider has, from the list provider keys operation. Give it only to reference a key. For vault, the name of the Transit key. For gcp-kms, a crypto key version of the key ring of the key store (projects/<project>/locations/<location>/keyRings/<keyRing>/cryptoKeys/<key>/cryptoKeyVersions/<version>). For aws-kms, a key ARN of the region of the key store, a key ID, or an alias (alias/<name>); the wallet keeps the key ARN. For azure-key-vault, a key ID of the vault of the key store with its version (<vaultUrl>/keys/<name>/<version>). For dpod, the label of a key pair in the partition (1 to 128 characters, no control character, no /). For csc, the ID of the CSC credential. A reference of another form gives 400.

    providerSecret string

    Possible values: <= 256 characters

    Write-only secret of a referenced key, only for csc, the PIN of the CSC credential. Optional. Without it, the wallet uses the userPin of the key store. No answer returns it.

Responses​

The service added the key and returned it.

Response Headers
    Schema
      keyId string

      Unique identifier of the new key. The value is the same as jwk.kid and key.keyId.

      jwk objectrequired

      Public key of the new key in JSON Web Key (JWK) format.

      kty string

      Key type. The value is EC.

      crv string

      Elliptic curve identifier.

      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.

      property name* any

      Public key of the new key in JSON Web Key (JWK) format.

      key objectrequired

      One signing key of the organisation, with the key store that holds it and the DIDs that come from it. The answer has public key material only. It never has the private part of the key, the reference of the key in the provider or a secret.

      keyId string

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

      name stringnullable

      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 string

      Unique identifier of the key store.

      type string

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

      Type of the key store.

      name string

      Name of the key store.

      origin stringnullable

      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 stringnullable

      Signature algorithm of the key.

      status string

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

      isDefault boolean

      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 string

      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[]

      DIDs that come from this key.

      hasCertificateChain boolean

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

      certificateSource stringnullable

      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 boolean

      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 stringnullable

      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 stringnullable

      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[]

      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[]

      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 boolean

      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 string

      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 string

      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 string

      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[]
      pid string[]
      eaa string[]
      qeaa string[]
      pub-eaa string[]
      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[]
      pid string[]
      eaa string[]
      qeaa string[]
      pub-eaa string[]
      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 boolean
      reason stringnullable
      qscd

      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 string

      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 stringnullable

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

      detail stringnullable

      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 integer

      Number of credential definitions that sign with the key.

      presentationDefinitions integer

      Number of presentation definitions that sign with the key.

      createdAt date-timenullable

      Creation time of the key, in UTC.

      updatedAt date-timenullable

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

    Loading...
    Last updated on