Skip to main content

Upload certificate chain

POST 
/v2/config/digital-wallet/openid/key-management/keys/:keyId/certificate-chain

Uploads a certificate chain and links it to a key. The wallet then adds the chain as the x5c value of the key, and the key can sign with the x509 format. A chain that the key already has is replaced.

This operation is for keys in a key store with the capability certificateChain: local, vault, gcp-kms, aws-kms, azure-key-vault and dpod. A key of a QTSP (csc) gets its certificate from the QTSP. To add a key and its chain in one step, use the import key operation (local and vault only).

The file must be UTF-8 text in PEM format. Put the leaf certificate first, then the intermediate certificates, then the root certificate. The service refuses the file when it holds a private key, when the leaf certificate does not use the P-256 curve, when a certificate is expired or not yet valid, or when a chain signature is not correct.

The wallet checks the leaf certificate against the preset of the newest CSR of the key (the generate CSR operation): the extended key usage, the key usage, the subject alternative names, the validity and, for an ISO/IEC 18013-5 preset, the issuer. A difference gives the warning profile-mismatch, not an error: the wallet refuses only a chain that it cannot use to sign. After the upload, certificateSource of the key is uploaded and certificatePreset is the preset of that CSR (null when the key has no CSR with a preset). When the key had a test certificate, the test CA revokes it (CRL). Exception: an upload of the current test certificate of the key itself (the leaf that the built-in test CA issued for this key, not revoked) keeps certificateSource test-ca and the certificatePreset of the key, the test CA does not revoke that leaf, and the first warning is test-certificate.

A new chain can break a credential configuration that signs with the key: its certificate no longer fits the credential category of the configuration, or no longer has the ISO/IEC 18013-5 Document Signer profile of an mDL. The upload still succeeds, and affectedCredentialConfigurations lists these configurations. They then show does-not-fit in their signingKeyCheck, and issuance does not stop.

Request​

Path Parameters

    keyId stringrequired

    Unique identifier of the key

Body

required

PEM file that holds the certificate chain.

    certificate_file binaryrequired

    PEM file that holds the certificate chain in leaf, intermediate and root order. The file must not hold a private key.

Responses​

Certificate chain uploaded successfully.

Response Headers
    Schema
      key_id string

      Unique identifier of the key that the certificate chain belongs to.

      certificates_count integer

      Number of certificates in the uploaded chain.

      x5t string

      SHA-1 thumbprint of the leaf certificate, in base64url format.

      x5t_s256 string

      SHA-256 thumbprint of the leaf certificate, in base64url format.

      csrId stringnullable

      Unique identifier of the newest CSR of the key, the CSR of the check. null when the key has no stored CSR.

      preset stringnullable

      The preset of the check, the preset of the newest CSR of the key. null when there is none.

      warnings object[]required

      The warnings of the upload (profile-mismatch, purpose-reuse). An empty list when there is none. When the uploaded leaf is the current test certificate of the key, the first warning is test-certificate.

    • Array [
      • code string

      Possible values: [test-certificate, preset-override, profile-mismatch, purpose-reuse]

      The kind of warning. test-certificate, the answer issues or shows a certificate of the built-in test CA: the text is always the text of the example. preset-override, a value of the request is not the fixed value of the preset; the request value applies. profile-mismatch, the certificate does not agree with the preset of the key. purpose-reuse, the certificate chain of the key has a preset, and the new CSR, test certificate or chain upload has another preset: use one key for each purpose.

      message string

      The text of the warning, for a person.

    • ]
      • affectedCredentialConfigurations object[]required

      The credential configurations whose signing key check fitted with the old chain and gives does-not-fit with the new chain. An empty list when there is none.

    • Array [
      • credentialDefinitionId string

      The credential definition of the configuration.

      credentialConfigurationId string

      The credential configuration id, as in the OID4VCI Credential Issuer Metadata.

      name string

      The label of the configuration, else its display.name, else the label of the credential definition.

      credentialCategory object

      The id of a credential category (the list credential categories operation): the eIDAS category of a credential configuration. none (no certificate rule), pid (person identification data), eaa (non-qualified attestation), qeaa (qualified attestation) or pub-eaa (attestation issued by or for a public sector body).

      messages string[]

      The rules that the new certificate does not fit, with the fix, as in signingKeyCheck.messages.

    • ]
    Loading...
    Last updated on