Upgrading from 9.x to 10.0
Each section below says what changed in EUDIPLO 10.0 and what to do; skip the sections that do not apply to you.
Before you upgrade
- Upgrade from any 9.x release. On 8.x or older, upgrade to 9.x first.
- If clients or people revoke or suspend credentials with only
issuance:offer, plan when they getcredentials:status(Credential status). - If you import a configuration folder at startup (
CONFIG_IMPORT_MODE=upsertorreplace), read Configuration files: unchanged key chains are no longer applied again, and unchanged!generateclients keep their secret. - If you rely on OpenID Federation trust anchors, check your federation before you upgrade (OpenID Federation): self-asserted membership is no longer accepted.
- List your tenants (
GET /api/tenant). A tenant whose ID is.or.., iskms.jsonin any letter case or contains/or\loses its configuration folder, including its ownkms.json: move it to a tenant with a valid ID while you still run 9.x (Tenants: IDs must be a folder name). If two tenants have IDs that differ only in case andCONFIG_FOLDERis on a case-insensitive file system (macOS, Windows), they share one folder: move one of them to a new tenant. - If you require wallet or key attestations, check that every wallet provider signs them under a certificate its wallet-provider trust list (managed or published by others) lists as
WalletSolution/Issuance: attestations signed under a certificate listed only asWalletSolution/Revocationare rejected (Wallet and key attestations). - If you require or accept wallet or key attestations, check that the certificates wallet providers sign them under, and the certificates your wallet-provider trust lists name for those providers, have not expired: attestations under a certificate that has expired or is not yet valid are now rejected (Wallet and key attestations: validity periods).
- If you check the status of wallet or key attestations (
walletAttestationStatusCheckModestrictorbest_effort, the default), check that the revocation certificates your wallet-provider trust lists name have not expired and that wallet providers sign their status lists under current certificates: status lists signed under a certificate that has expired or is not yet valid are now rejected (Wallet and key attestations: status list signers). - If you accept key attestations, check that every wallet provider serves the status list its key attestations name and signs it as for wallet attestations: the credential endpoint now checks it (Key attestations).
- If you trust issuers or wallet providers through trust lists that others publish, check the
ServiceStatusof their services: withdrawn services, and services whose status the list type does not approve, are now ignored (Trust lists). - If you verify credentials against trust lists, check that each issuer signs its credentials under its PID, Pub-EAA or EAA issuance certificate and its status lists under the revocation certificate of the same type and entity (Presentations). For mDOCs this applies to managed lists too.
- If you issue or verify mDOCs with status lists of more than 8,388,608 statuses at one bit (1,048,576 at eight), or verify credentials whose status lists are gzip-compressed, split or recompress those lists: presentations with them now fail (Presentations: status list size).
- If you verify credentials from issuers whose certificate, or the CA it is issued under, is listed with a
PID/Issuanceservice, check that every credential they issue that is valid for more than 24 hours carries a status list reference: withstatusCheckMode: strict(the default) such credentials without one are now rejected (Presentations). - If you accept wallet or key attestations, check that every wallet provider signs them with an
x5ccertificate chain, not only ajwkheader (Wallet and key attestations). - If wallets send
jwtproofs, check their clocks: proofs with aniatolder than 300 seconds or ahead by more thanCRYPTO_TOLERANCEare rejected (Credential endpoint). - If you verify SD-JWT VCs from other issuers, check that their credentials carry
typ: dc+sd-jwt:vc+sd-jwtand credentials withouttypare rejected (Presentations). - If you verify mDOCs with status checks, check that the certificates their status lists are signed under have not expired; if you issue mDOCs with EUDIPLO, check the certificate of the key chain that signs your status lists (Presentations: mDOC status list signers).
- Check that every trust list you reference has a valid
NextUpdatein the future and aLoTESequenceNumberthat is a whole number from 1: outdated lists are now discarded in every position, also as wallet-provider lists (Trust lists, older versions). Ask the publishers of external lists to renew them before it passes. For managed lists, look forFailed to renew trust listin the 9.x log: 9.x kept accepting attestations under a managed wallet-provider list whose renewal failed. - If you verify credentials or attestations against trust lists, check that the lists of each
etsi_tlentry, and yourwalletProviderTrustLists, hold at most 1,000 certificates together, and that their CA certificates carry a Subject Key Identifier (Trust lists). - If you create
dc-apioriso-18013-7presentation requests, check that every call setsexpected_originto your own origin (Digital Credentials API); theOriginheader of the call is no longer used, and a call without origin fails with400. - If you import credential configuration files, check that no file has two
config.display[]entries for one locale (Configuration files): such a file blocks the import of its tenant's configuration. - With Keycloak (
OIDCset), setOIDC_UI_URLto the URL of your web client, or add<web client URL>/*as a redirect URI ofeudiplo-uiin Keycloak; otherwise nobody can sign in to the web client with SSO after the upgrade (Keycloak). - With Keycloak, check that scripts and services calling the management API send Keycloak's access token, not its ID token (Management API with Keycloak).
- With Keycloak and without
OIDC_AUDIENCE, check that scripts and services calling the management API get their tokens witheudiplo-ui, theAUTH_CLIENT_IDclient (withAUTH_CLIENT_SECRETset) or a client created through EUDIPLO: tokens of other clients in the realm are refused (Management API with Keycloak). - With Keycloak, check that every client file in a tenant folder whose
clientIdexists in Keycloak but not among EUDIPLO's clients, and everyPOST /api/tenantyou send again for an existing tenant, lists all EUDIPLO roles the client should keep: the others are removed (Client and user management). - If you use transaction data, check that every entry's
credential_idsname onlydc+sd-jwtqueries of the DCQL query (Transaction data). - If verifiers of your SD-JWT VCs or status lists check the extended key usage of the signing certificate, read Attestation key chains before your attestation key chains rotate.
- If a tenant uses the sandbox registrar (a registrar configuration,
registration_cert.idor.body, or an issuer registration certificate ingeneratemode), request its certificates from the EUDI Hub, or note when the generated ones expire: 10.0 no longer creates or renews them (Registrar). - Follow the upgrade procedure.
Operators
Registrar: the sandbox registrar integration is removed
Changed: the integration of the German sandbox registrar is removed; the EUDI Hub is the registrar EUDIPLO requests access and registration certificates from. EUDIPLO no longer creates, reuses or renews registration certificates itself: a presentation configuration and the issuance configuration hold the certificate as a JWT, issued by the EUDI Hub or imported (Registration certificates). The Web Client drops the Registrar pages, Registrar Enrollment of access key chains, the schema catalog and Regenerate now. schemaMeta of credential configurations stays stored and exported; nothing publishes it. The API changes are listed under Integrators.
- The database migration
RemoveSandboxRegistrardrops every registrar configuration with its stored credentials, and the ownership records of registrar configurations imported from a folder or bundle. A registration certificate the sandbox registrar issued forregistration_cert.idor.body, or ingeneratemode (the default), is kept asregistration_cert.jwtorregistrationCertificate.jwtwhile it is valid, so presentations and issuer metadata keep it until it expires; an expired one is dropped. Such a certificate was issued for the access certificate that was current when it was requested, and 10.0 attaches it whichever access key chain signs the request: if you change an access key chain before it expires, request a new certificate from the EUDI Hub.body.purposeandbody.privacy_policybecomepurposeandprivacy_policy, which the next EUDI Hub request reuses; the otherbodyfields,id,modeandrenewalare dropped, and so is aregistrationCertificate.jwtstored ingeneratemode, which 9.x did not serve. Request objects and issuer metadata then carry no registration certificate, so wallets that require one refuse the request until you store a new one. The migration logs every removed registrar configuration and every certificate it keeps or can no longer provide ([Migration] ...). - A
registrar.jsonin a tenant folder and aRegistrarConfigdocument in a bundle are skipped with the warningREGISTRAR_CONFIG_REMOVED; the other files of the tenant are imported.eudiplo config validateprints the warning without failing. Presentation and issuance files move to format v5 and v7 (Configuration files).
Do:
- Before the upgrade, note which presentation configurations and issuers use the sandbox registrar and when their certificates expire (the
expofregistrationCertCache.jwtandregistrationCertificateCache.jwtin 9.x). After the upgrade, request new certificates from the EUDI Hub (EUDI Hub) before they expire, and an access certificate for access key chains enrolled at the sandbox registrar (EUDI Hub). Certificates from the EUDI Hub are not renewed automatically either. What fails when a kept certificate expires: Integrators. - Search the log of the first start for
[Migration]lines naming a certificate that the sandbox registrar no longer creates. - Remove
registrar.jsonfrom configuration folders and runeudiplo config upgradewith@eudiplo/cli@10on them (Configuration files).
Keycloak: the web client needs OIDC_UI_URL
Changed: 9.x set the redirect URIs and web origins of the public Keycloak client eudiplo-ui (OIDC_UI_CLIENT_ID) to * on every start, so Keycloak sent authorization codes to any website that asked, and anyone can exchange a code of a public client for the signed-in person's tokens. 10.0 takes the redirect URIs from the new variable OIDC_UI_URL: the pages under each web client URL, and their origins as web origins. Without it, the redirect URIs set in Keycloak stay, without *, and are no longer overwritten; a web origin * becomes + (the origins of the redirect URIs), as does an empty list of web origins. A client that only had * is left without redirect URIs: the backend logs a warning at startup, and Keycloak answers Login with SSO with "Invalid parameter: redirect_uri".
Do: set OIDC_UI_URL to the address the web client is served from, for example OIDC_UI_URL=https://console.example.com, with its path if it uses CLIENT_BASE_HREF, and several addresses separated by commas. To manage the redirect URIs in Keycloak instead, leave it unset and add <web client URL>/* to eudiplo-ui. Details: Keycloak SSO.
Web Client: links that choose an instance ask before signing in
Changed: a link to the login page with ?apiUrl= chooses the EUDIPLO Instance. The instance receives the access token after a single sign-on, or the client secret, and nothing ties it to the identity provider its discovery document names. When the link chose an instance other than the one the Web Client's API_BASE_URL names or the one this browser last signed in to, the Web Client now asks before signing in there, also for a link with clientId, clientSecret and apiUrl that 9.x signed in with at once. After a sign-in with single sign-on or a client secret the user entered, the Web Client remembers that instance and does not ask about it again until it signs in to another one; a sign-in with the link's own credentials is not remembered. The Web Client image now sends Referrer-Policy: strict-origin-when-cross-origin instead of no-referrer-when-downgrade, so other sites learn only its origin, never a page address; a reverse proxy that sets its own Referrer-Policy should not send a weaker one. It also sends the access token only to the instance it is signed in to; 9.x sent it with every request, also to instance URLs typed on the login page.
Do: nothing. If you hand out links to the login page, set API_BASE_URL of the Web Client to the instance they name, so the login page does not ask the first time (links to the login page). Automated browser flows that open such links, for example in Playwright, which dismisses page dialogs, must accept the question or run against the instance API_BASE_URL names.
Web Client: menus and pages need GET /api/auth/me
Changed: the Web Client no longer reads roles and tenant from the access token. After each sign-in and token renewal it asks the backend which roles and tenant the token grants (GET /api/auth/me), so menus follow OIDC_ROLES_CLAIM, OIDC_SUB and, with the built-in server, the client's current roles. While that request fails, the Web Client shows no menu entries and opens no page that needs a role, and offers Retry. A 9.x backend does not have the endpoint.
Do: upgrade the backend before the Web Client, or both together. A reverse proxy or WAF in front of the backend must let /api/auth/me through (troubleshooting).
Client and user management: callers grant only their own roles
Changed: in 9.x, a token with clients:manage could give a client every role except tenants:manage and tenant:admin, whether it held that role or not. It could also change, delete or rotate the secret of any client of its tenant, including clients with more roles, such as the tenant's <tenant>-admin client. users:manage could do the same for people, including setting their password. 10.0 applies the granting rules to POST /api/client, PATCH /api/client/{id}, DELETE /api/client/{id}, POST /api/client/{id}/rotate-secret, POST /api/user, PATCH /api/user/{id}, DELETE /api/user/{id} and configuration bundle imports:
- a caller grants only the roles it holds; with
tenant:adminit grants every role excepttenants:manageandtenant:admin, and onlytenants:managegrants those two; - a caller changes, deletes or rotates the secret of a client or person only if it holds or can grant each of its roles. With Keycloak, the roles assigned there count too, including those from groups, and a
realm-managementrole or any other client role mapped directly to the account blocks the change.
Other requests answer HTTP 403; a bundle plan already reports them. With Keycloak, a client that exists in Keycloak but not among EUDIPLO's clients of the tenant can no longer be changed, rotated or deleted through the API. Creating a client with its ID through POST /api/client or a bundle still takes it over if it has the tenant's tenant_id, but now needs the right to manage it. Such a takeover, one by a client file in a tenant configuration folder, and POST /api/tenant sent again for <tenant>-admin now replace the EUDIPLO realm roles mapped directly to the client in Keycloak with the requested ones instead of adding to them, so EUDIPLO roles the request leaves out are removed; roles from groups and other realm roles stay (Keycloak SSO).
Do: before you upgrade, give every client or person that creates or changes clients or people each role it hands out, or tenant:admin to let it hand out every role except tenants:manage and tenant:admin. Manage accounts with Keycloak client roles in Keycloak. If a tenant's admin client misses a role after the upgrade, send POST /api/tenant again with the root client, the tenant's name and all roles it needs (Tenants and access); with the built-in authorization server this returns a new secret. With Keycloak you can also assign the role there; without it, a client file with the roles in the tenant's configuration folder and one start with CONFIG_IMPORT_MODE=create adds a client that has them (Configuration as code). With Keycloak, before the first start of 10.0, check that every client file whose clientId exists in Keycloak with the tenant's tenant_id, and every repeated POST /api/tenant, lists all EUDIPLO roles that client should keep; the start or request removes the others.
Client IDs are unique across tenants
Changed: a client ID identifies one client across all tenants. In 9.x, creating a client with a taken ID could replace the existing client: with the built-in authorization server also one of another tenant or the root client, with Keycloak a client without tenant_id, such as the backend's own admin client. In 10.0, POST /api/client answers HTTP 409 for every taken ID, and POST /api/tenant when <tenant>-admin belongs to another tenant or the root client. A bundle plan blocks a client whose ID another tenant uses (CLIENT_ID_TAKEN), so the import stops before it changes anything; this includes the startup import of a tenant folder. Creating an existing tenant again still updates its own admin client.
Do: give clients of different tenants different IDs. Check startup configuration folders for the same clientId in two tenants. In scripts, treat 409 on POST /api/client as "ID taken".
Deleting a client or changing its secret ends its access; JWT_EXPIRES_IN removed
Changed: with the built-in authorization server, deleting a client or its tenant ends the client's API access at once, and role changes apply to the tokens it already has; in 9.x its tokens worked until they expired. A new client secret also ends the tokens issued with the old one: POST /api/client/{id}/rotate-secret, POST /api/tenant with roles for an existing tenant (new secret for <tenant>-admin), a configuration bundle import with another secret or !generate, and a startup import with another secret, including a client file without secret, which gets a new random secret on every start in upsert or replace mode. In 9.x, the old tokens kept working for up to 24 hours. Creating a deleted client or tenant again with the same ID does not revive the old tokens either. Importing the secret a client already has keeps its tokens. With Keycloak, a deleted client's tokens get 401 at once without OIDC_AUDIENCE (only EUDIPLO's clients); with it, they stay valid until the realm's access token lifespan ends. JWT_EXPIRES_IN is removed: 9.x documented it as the token lifetime, but tokens always lived 24 hours. 10.0 ignores a leftover value.
Do: to cut off a leaked token, rotate its client's secret or delete the client; with Keycloak, a new secret leaves issued tokens valid until the realm's access token lifespan ends, so delete the client instead, which ends them at once unless OIDC_AUDIENCE is set (Revoke access). If an integration relied on its old token to keep working after a secret rotation, have it request a new token right after the rotation, or create a second client, switch the integration to it and delete the first one. Remove JWT_EXPIRES_IN from your .env, Compose files and Kubernetes manifests.
CRYPTO_ALG removed
Changed: CRYPTO_ALG is removed. 9.x accepted only ES256 for it; in 10.0 each key chain signs with the algorithm of its curve, chosen when it is created or with defaultAlgorithm in kms.json (Signing algorithms). 10.0 ignores a leftover value.
Do: remove CRYPTO_ALG from your .env, Compose files and Kubernetes manifests.
Access tokens: signed by their own key chain
Changed: the built-in, chained and OID4VP authorization servers sign access tokens only with a key chain of the new usage type authorizationServer, and their JWKS publishes only its keys. 9.x used token.signingKeyId, then (built-in server only) the issuance configuration's signingKeyId, then whichever signing key chain the database returned first: often the registrar access certificate or a credential signing key, and a token request failed with Failed to create access token response when that key chain could not sign. Now an authorization server without token.signingKeyId uses the authorizationServer entry of the tenant's key chain defaults, else the tenant's oldest authorization server key chain; on the first token request after the upgrade, EUDIPLO creates a standalone key chain authorization-server for it with the tenant's default KMS provider. Its key in an external KMS is named <random UUID>-active, so a KMS policy that limits key names or creation must allow it. Its key replaces the key in the JWKS, so an access token issued by 9.x and presented after the upgrade is refused once; the wallet requests a new one. The JWKS keeps the previous key for one token lifetime after a rotation of the key chain (Authorization server key chain).
The issuance configuration's signingKeyId is removed: the database migration drops a stored value and logs it. token.signingKeyId must name a key chain with usage type authorizationServer. The migration does not change a stored token.signingKeyId, and every value from 9.x names another usage type: until you change it, that authorization server answers token requests with 500 while the backend log names the key chain. If a tenant already has a key chain with ID authorization-server and another usage type, EUDIPLO cannot create its key chain, and token requests fail the same way.
Do:
- Remove
token.signingKeyIdfrom the authorization servers of your issuance configurations, or point it to a key chain with usage typeauthorizationServer(in the Web Client: Authorization Server Key of the authorization server). - To choose one key chain for all authorization servers of a tenant, set
authorizationServerinkey-chain-defaults.json. - If a tenant has a key chain with ID
authorization-serverthat is not an authorization server key chain, create an authorization server key chain for it. - Access certificates and credential signing key chains no longer need to be kept for access tokens.
Wallet attestations: unreadable status lists are rejected
Changed: when a wallet attestation has a status claim, the PAR and token endpoints of the built-in, chained and OID4VP authorization servers reject it if the claim is malformed (not a JSON object, an empty object, or a status_list without a uri that is an absolute URI or without a non-negative integer idx; 9.x treated it as absent), if its status list was fetched but cannot be read, is not typed statuslist+jwt, does not carry the attestation's status list URI as sub, has no iat or has expired, or if its index is outside the list. A status list whose signature does not verify is rejected too; 9.x accepted a forged signature under a genuine x5c. A status list must also be signed under one of the provider's revocation certificates (any of its WalletSolution/Revocation services, or else any of its EAA/Revocation services), or under its attestation certificate if it lists neither; 9.x accepted any key in the list's own x5c for a provider without a revocation certificate. The answer says Wallet attestation status list rejected: ... with the reason, Status list JWT signature verification failed ... for a bad signature or signer, or Wallet attestation status check failed for other errors, including a malformed claim. This is the answer of the built-in token endpoint; the PAR endpoints and the token endpoints of chained and OID4VP authorization servers answer invalid_client with Client attestation validation failed (below), and the server log has the reason there. 9.x rejected revoked and suspended attestations, status lists without x5c and lists chained to a certificate other than the provider's revocation certificate, but logged every other status check failure and accepted the attestation. A status list that cannot be fetched (network error, timeout, non-2xx answer, URL blocked by the outbound URL policy) is still accepted with a warning: that is the default mode best_effort of the new setting walletAttestationStatusCheckMode, on the issuance configuration and on each authorization server. strict also rejects a list that cannot be fetched; disabled skips the status check, so revoked and suspended attestations are accepted as well. There is no mode that accepts an unreadable list but still rejects revoked attestations.
Do: if wallets fail with one of these messages, look up the reason in the server log and check the wallet provider's list at the attestation's status.status_list.uri. Set walletAttestationStatusCheckMode: "disabled" only if you accept revoked wallet instances. Details: Wallet and key attestation.
Key attestations: the status list is checked
Changed: the credential endpoint checks the status claim of a key attestation (an attestation proof, or the key_attestation of a jwt proof) as it checks that of a wallet attestation (above), in the issuance configuration's walletAttestationStatusCheckMode (default best_effort). 9.x did not read the status of key attestations, so it issued credentials for revoked and suspended wallet units. A rejected key attestation answers invalid_proof with Key attestation is not valid: ..., Key attestation status list rejected: ..., Status list JWT signature verification failed ... or Key attestation status check failed; the server log has the reason.
Do: if wallets fail with one of these messages, check the wallet provider's list at the key attestation's status.status_list.uri. Set walletAttestationStatusCheckMode: "disabled" on the issuance configuration only if you accept revoked wallet units; it also turns off the status check of wallet attestations at authorization servers without their own mode. Details: Wallet and key attestation.
Wallet and key attestations: the attester is named by x5c
Changed: a wallet attestation (PAR and token endpoints) or key attestation (credential endpoint) that names its signer only with a jwk header is rejected, also when no wallet-provider trust list is configured: such an attestation is signed by whatever key it carries, so a wallet could attest itself. The attester must be named by x5c, which EUDIPLO checks against the wallet-provider trust lists. The credential endpoint answers invalid_proof with Error verifying credential request proof attestation, whose description names the signer method that is not allowed; the PAR and token endpoints reject it as any other invalid wallet attestation (Integrators). 9.x accepted a jwk-signed attestation when no trust list was configured.
Do: if wallets fail with one of these errors, ask the wallet provider to sign its attestations with an x5c certificate chain (Wallet and key attestation).
Credential endpoint: jwt proofs must be recent
Changed: the credential endpoint rejects a jwt proof whose iat is more than 300 seconds in the past or more than CRYPTO_TOLERANCE seconds (default 5) in the future, with invalid_proof (OpenID4VCI 1.0 Appendix F.4). A client attestation PoP needs an iat and is rejected when it is more than 300 seconds old. 9.x did not check how old a proof was. Empty values that the specifications do not allow, such as an empty pre-authorized_code, client_id, nonce or c_nonce, are now refused as malformed instead of failing their lookup.
Do: if wallets fail with invalid_proof and the reason names iat, check the wallet's clock, or raise CRYPTO_TOLERANCE if its clock runs a few seconds ahead.
Wallet and key attestations: WalletSolution/Revocation certificates no longer sign them
Changed: a wallet attestation (PAR and token endpoints) or key attestation (credential endpoint) must be signed under a certificate that a wallet-provider trust list lists as http://uri.etsi.org/19602/SvcType/WalletSolution or .../WalletSolution/Issuance. 9.x also accepted a certificate listed only as .../WalletSolution/Revocation, the service that signs a provider's status lists (ETSI TS 119 602 Annex E), or under any other .../WalletSolution/... type. The built-in token endpoint answers Wallet provider certificate is not trusted - no matching entity in trust list, the PAR endpoints and the token endpoints of chained and OID4VP authorization servers answer invalid_client with Client attestation validation failed, and the credential endpoint answers invalid_proof with Attestation proof signer is not trusted by configured wallet provider trust lists.
Do: in a managed wallet-provider list, the entity's issuer key chain is published as WalletSolution/Issuance: make sure the provider signs its attestations under that key chain, not under the revocation key chain. Ask the publisher of an external list to list the provider's attestation certificate as WalletSolution/Issuance. Details: Wallet and key attestation.
Wallet and key attestations: certificates must be within their validity period
Changed: a wallet attestation (PAR and token endpoints) or key attestation (credential endpoint) is rejected when a certificate of its path, from the one in x5c that signs it to the one a wallet-provider trust list names as WalletSolution or WalletSolution/Issuance, has expired or is not yet valid at the time of the request. Both ends of a validity period count as valid; CRYPTO_TOLERANCE does not apply. 9.x did not check the validity periods of these certificates. The built-in token endpoint answers Wallet attestation certificate chain is not valid: ..., the PAR endpoints and the token endpoints of chained and OID4VP authorization servers answer invalid_client with Client attestation validation failed (the server log has the reason), and the credential endpoint answers invalid_proof with Attestation proof certificate chain is not valid: .... The message names the certificate (Signing certificate, Intermediate certificate or Trust list certificate), its notAfter or notBefore, and the time of the check. A certificate a list names now takes the place of a certificate in the attestation's x5c with the same subject and key, and when a list names a provider's CA and its renewal, attestations are chained to the valid one, whichever the list names first. An attestation whose x5c carries a CA the list no longer names is therefore accepted under its listed renewal; 9.x rejected it. The wallet unit status check of credentials issued with revokeWithWalletUnit does not check the periods of the attestation's path again; it does check those of its status list's path (below).
Do: check that the certificates your wallet providers sign attestations under, and the ones your wallet-provider trust lists name for them, have not expired. If attestations fail with has expired, ask the provider to sign under a current certificate, or the publisher of the list to list a current one; with is not yet valid, check the clocks of the server and of the wallet provider. Details: Wallet and key attestation.
Wallet and key attestations: status list signers must be within their validity period
Changed: with walletAttestationStatusCheckMode strict or best_effort (the default), a wallet attestation (PAR and token endpoints) or key attestation (credential endpoint) with a status claim is rejected when a certificate of its status list's path, from the one in the list's x5c that signs it to the provider's revocation certificate (WalletSolution/Revocation, else EAA/Revocation) or, if the provider lists neither, its attestation certificate, has expired or is not yet valid at the time of the check. best_effort does not accept it, because the list was fetched; disabled is unchanged. For a listed end-entity certificate that signs the list itself, only that certificate is checked. Both ends of a validity period count as valid; CRYPTO_TOLERANCE does not apply. 9.x did not check the validity periods of these certificates. The built-in token endpoint and the credential endpoint (invalid_proof) answer Status list JWT signature verification failed - certificate chain is not valid: ..., with the certificate (Signing certificate, Intermediate certificate or Trust list certificate), its notAfter or notBefore and the time of the check; the PAR endpoints and the token endpoints of chained and OID4VP authorization servers answer invalid_client with Client attestation validation failed (the server log has the reason). The wallet unit status check of credentials issued with revokeWithWalletUnit reads nothing from such a list: it revokes nothing, logs the reason as a warning and tries again on its next run, so that a list signed under a retired key cannot revoke credentials; for a provider without a revocation certificate, whose list is signed under its attestation certificate, that means no wallet unit is revoked once the attestation certificate has expired. A status list signer a list names (the revocation certificate, or the attestation certificate if there is none) now takes the place of a certificate in the status list's x5c with the same subject and key, and when a list names such a CA and its renewal, the status list is chained to the valid one, whichever the list names first. A status list whose x5c carries a CA the list no longer names is therefore accepted under its listed renewal; 9.x rejected it for a provider with a revocation certificate (for one without, 9.x accepted any status list).
Do: check that the revocation certificates your wallet-provider trust lists name have not expired; in a managed wallet-provider list, that is the certificate of each internal entity's revocation key chain (revocationKeyChainId) and each external entity's revocationCertPem. If attestations fail with Status list JWT signature verification failed - certificate chain is not valid: ... has expired, or the wallet unit status check logs it, ask the wallet provider to sign its status list under a current certificate, or the publisher of the list to list a current revocation certificate; with is not yet valid, check the clocks of the server and of the wallet provider. Details: Wallet and key attestation.
Trust lists: services are read by their status and list type
Changed: EUDIPLO reads a trust list service by the rules of the list's LoTEType (ETSI TS 119 602 V1.1.1). 9.x ignored ServiceStatus. A service is now left out when its ServiceStatus does not approve it: PID lists accept none or .../PidProvidersList/SvcStatus/notified (which PID lists in use set), wallet-provider, WRPAC, WRPRC and registrar lists accept no status at all, Pub-EAA lists accept only .../PubEAAProvidersList/SvcStatus/notified (or none, with a warning), and other lists accept none, notified or http://uri.etsi.org/19602/commons/schemeApprovalGranted. The full table is in Service status and type.
An entity whose services are all left out is left out too. A status URI that a scheme defines itself (TS 119 602 §6.6.4) is not known to EUDIPLO, so the services that carry it are not trusted. A credential under a service that is left out fails with trust_chain_not_trusted, like one of an issuer that is not listed. A wallet or key attestation under a wallet provider that is left out is rejected as above, or with No trusted wallet providers found in configured trust lists when no provider of the lists is left. A status list signed under a revocation service that is left out is rejected: it must be signed under one of the entity's remaining revocation services of the type paired with the matched service (below) or, if none is left, under the certificate the credential or wallet attestation matched. The aki values of presentation requests leave out those issuers too. Lists managed in EUDIPLO set no ServiceStatus and are not affected. An older version of the list from before a withdrawal is discarded once its NextUpdate has passed (below).
Services without ServiceTypeIdentifier, which 9.x skipped, are now read in a list where no service has a type (§6.6.0, NOTE 2): they get the issuance type of the list's profile, SvcType/PID/Issuance, SvcType/WalletSolution/Issuance, SvcType/PubEAA/Issuance or SvcType/EAA/Issuance for EUEAAProvidersList. They are still skipped in a list whose other services have a type, and in a list whose type implies none.
For each list, one warning in the log names the services left out or read despite a missing status (at most ten of each, then a count), with entity, service type, status and reason, for example Trust list https://trust.example.org/lists/pid.jwt: left out 1 service(s): entity "Example PID Provider", type "http://uri.etsi.org/19602/SvcType/PID/Issuance", status "http://uri.etsi.org/19602/commons/schemeApprovalGranted": the list type does not approve services with this ServiceStatus.
Do: look for warnings starting with Trust list in the log after the upgrade: they name the services left out or read ... despite a missing status. If a provider you rely on is left out for its status, ask the list publisher whether it was withdrawn or replaced, or whether the list should follow its profile. Details: Service status and type.
Presentations: credentials and status lists match trust list services by type
Changed: a presented credential, SD-JWT VC or mDOC, must chain to a certificate that the trust list lists as http://uri.etsi.org/19602/SvcType/PID/Issuance, .../PubEAA/Issuance or .../EAA/Issuance. 9.x accepted the certificate of any service type ending in /Issuance of an entity that also had a PID or EAA issuance service, for example its .../WalletSolution/Issuance or .../WRPAC/Issuance certificate. Such a credential now fails with trust_chain_not_trusted.
With status checks enabled, the credential's status list must be signed under a revocation certificate of the same entity whose type belongs to the matched issuance service: .../PID/Revocation for .../PID/Issuance, .../PubEAA/Revocation for .../PubEAA/Issuance and .../EAA/Revocation for .../EAA/Issuance. An entity without a revocation service of that type uses its .../EAA/Revocation services, and one without those must sign under the certificate the credential matched. For an SD-JWT VC, 9.x did not check the status list signer at all when the issuer's entity listed no .../EAA/Revocation service, for example a PID provider listed with .../PID/Issuance and .../PID/Revocation; otherwise it accepted a status list under any /Revocation service of an entity with the same entityId, for example .../WalletSolution/Revocation. For an mDOC it accepted a revocation certificate of any entity in the query's trust lists, or any listed issuance certificate if they had no revocation certificate. A status list with another signer now fails the presentation.
Lists managed in EUDIPLO list an issuer's key chains as .../EAA/Issuance and .../EAA/Revocation, so their service types match. An mDOC's status list, however, must now be signed under the revocation key chain of the entity whose issuer key chain signs the credential; 9.x accepted the revocation key chain of any entity in the lists, for example one key chain that signs the status lists of several issuer entities.
Do: check that each issuer signs its credentials under a certificate listed as PID, Pub-EAA or EAA issuance service, and its status lists under the revocation service of the same type and entity. In a managed list, give each issuer entity the key chain that signs its status lists as revocation key chain. For lists that others publish, ask the publisher to list missing services. Details: Trust lists.
Presentations: malformed status references are rejected
Changed: with statusCheckMode strict (the default) or best_effort, a presented credential whose status reference is malformed fails with verification_error, HTTP 400 to the wallet and session failed, and its status list is not fetched (Token Status List, Section 6). For an SD-JWT VC, that is a status claim that is not a non-empty JSON object, a status_list that is not an object, a uri that is not an absolute URI (a scheme followed by ASCII URI characters only, RFC 3986) or an idx that is not a non-negative integer. 9.x read an idx of "7" as index 7 and accepted status_list: null without a check, and best_effort accepted a status claim that is empty or not an object; a missing or invalid uri failed in 9.x too, but without a failure code. For an mDOC, a status list or identifier list uri that is not an absolute URI is rejected, which 9.x accepted in best_effort as an unavailable list, and so is an MSO status that names no mechanism; in strict, an MSO status that names only another mechanism is rejected as for SD-JWT VCs. 9.x accepted both.
With disabled, an SD-JWT VC's status list is no longer fetched or checked; 9.x still fetched it, with a plain request outside the outbound URL policy, and rejected the credential when that request or the list check failed or the credential was revoked. In best_effort, an SD-JWT VC whose status list cannot be fetched is now accepted with a warning, as documented; 9.x requested the list a second time outside the policy and rejected the credential when that failed too. disabled is unchanged for mDOCs.
In strict, an SD-JWT VC whose status names only another status mechanism now fails with the failure code verification_error as well; 9.1 rejected it without a failure code, 9.0 accepted it. Its session's errorReason, the webhook's outcome.message and the redirect's error_description now carry the short message The credential could not be verified.; the reason is in the server log.
Do: if presentations fail with verification_error, look for The status, The MSO references or The MSO's status in the server log and ask the issuer to correct the credential's status reference. Details: statusCheckMode.
Presentations: status lists have a size limit
Changed: with statusCheckMode strict (the default) or best_effort, a presented credential fails, HTTP 400 to the wallet and session failed, when its status list decompresses to more than 16 MiB for an SD-JWT VC (a status list JWT, 134,217,728 statuses at one bit) or 1 MiB for an mDOC (a status list CWT, 8,388,608 statuses at one bit or 1,048,576 at eight). It also fails when the list is not DEFLATE data in the ZLIB format that Token Status List, Section 4.1 requires (9.x also read gzip), or when an SD-JWT VC's status list has a typ other than statuslist+jwt or application/statuslist+jwt (9.x ignored media type parameters such as ; charset=utf-8). 9.x read lists of any size, so a signed list of about a megabyte that decompresses to a gigabyte could exhaust the server's memory. The mDOC limit is lower because the mDOC library holds every status of the list in memory. An mDOC fails with verification_error. Lists created through the API since 9.0 hold at most 1,000,000 statuses and stay within both limits; lists created on 8.x or imported from status list configuration files can be larger.
Do: if presentations fail with Status list cannot be decompressed in the session error or the server log, ask the issuer to split the list into smaller ones or to compress it in the ZLIB format instead of gzip. If you issue mDOCs, check capacity and bits of your status lists (GET /api/status-lists and your status list configuration files): for a list above 8,388,608 statuses at one bit (1,048,576 at eight), create smaller lists for new credentials. Details: statusCheckMode, Manage status lists.
Presentations: PIDs without status information are rejected
Changed: with statusCheckMode strict (the default), a presented PID whose validity period is longer than 24 hours and that carries no status information fails with verification_error, HTTP 400 to the wallet and session failed (ARF Annex 2, VCR_01, VCR_01b and VCR_14). A credential counts as a PID when its certificate chain matches a certificate listed with a http://uri.etsi.org/19602/SvcType/PID/Issuance service in the trust lists (a CA it was issued under, or its own end-entity certificate), also if that certificate is listed with an EAA service as well. Issuers listed only with EAA or Pub-EAA services, issuers trusted through OpenID Federation and lists managed in EUDIPLO (which list issuers as EAA) are not affected: EAAs and Pub-EAAs without status are left to the relying party's policy. The validity period runs from nbf (else iat) to exp of an SD-JWT VC, where a selectively disclosable iat counts only if the wallet discloses it, and from validFrom to validUntil of an mDOC; a PID without a start or an end counts as longer than 24 hours. best_effort accepts such a PID and logs a warning; disabled accepts it. 9.x accepted it in every mode.
Do: if PID presentations fail with verification_error and the server log says The PID carries no status information, ask the PID provider to add a status list reference, or set statusCheckMode: "best_effort" on the presentation configuration if you accept PIDs whose revocation you cannot check. Details: statusCheckMode.
Presentations: SD-JWT VCs need typ dc+sd-jwt
Changed: a presented SD-JWT VC whose header typ is not dc+sd-jwt (also with the application/ prefix, in any case) fails verification: SD-JWT VC requires it (draft 27 Section 2.2.1), and without the check another JWT the issuer signed, such as its Status List Token, would pass as a credential. This includes the vc+sd-jwt of earlier drafts and credentials without typ. The server log names Invalid typ header. 9.x accepted any typ. Credentials EUDIPLO issues carry dc+sd-jwt.
Do: if SD-JWT VC presentations fail with Invalid typ header, ask the issuer to issue with typ: dc+sd-jwt; wallets have to obtain the credential again.
Presentations: mDOC status list signers must be within their validity period
Changed: with statusCheckMode strict (the default) or best_effort, a presented mDOC fails with certificate_expired, HTTP 400 to the wallet and session failed, when a certificate from the signer of its status list or identifier list up to the certificate the trust list requires it to be signed under is expired or not yet valid. best_effort does not accept it, because the list was fetched. 9.x did not check the validity period of these certificates; SD-JWT VCs were already rejected in this case. disabled is unchanged. Without a trust list (SKIP_TRUST_AUTHORITY=true), an mDOC whose own certificate chain is expired or not yet valid is now rejected with certificate_expired as well; with a trust list it already was. Both ends of a validity period count as valid.
Do: if you issue mDOCs with EUDIPLO, check that the certificate of the key chain that signs their status lists (the list's keyChainId, by default the tenant's status list key chain, else its attestation key chain) has not expired: rotate the key chain (POST /api/key-chain/{id}/rotate) or enable its rotationPolicy (certValidityDays defaults to 365), or import a renewed certificate if an external CA issued it (Keys and certificates). If mDOC presentations fail with certificate_expired and the server log names the status list signer (X.509 chain verification failed ... cause=Certificate has expired), ask the issuer to sign its status lists under a valid certificate. Details: How a trust list is used.
Presentations: responses must return state
Changed: an OID4VP response to a request with state (every request except over the Digital Credentials API) must return that state in the encrypted response. 9.x accepted a response without state and only rejected a different value. Such a response now answers HTTP 400 and the session is set to failed with Presentation validation failed: State missing: .... In interactive authorization, such a presentation step answers access_denied and its presentation session is set to failed. An encrypted error response that also carries vp_token, or whose state or error_uri is not a string, now answers HTTP 400 and leaves the session open; 9.x answered HTTP 200 and set the session failed with the wallet's error code.
Do: check that the wallets you support return state in their responses. Details: Presentation.
Presentations: response JWE limited to ECDH-ES with A128GCM or A256GCM
Changed: an encrypted OID4VP response (direct_post.jwt or dc_api.jwt) must use the encryption the request advertises: alg ECDH-ES, the alg of the key in client_metadata.jwks, and an enc of A128GCM or A256GCM from encrypted_response_enc_values_supported. 9.x decrypted any alg and enc it could, such as ECDH-ES+A128KW or A128CBC-HS256. Another one now answers HTTP 400 with Could not decrypt the authorization response: ... and leaves the session open; in interactive authorization, such a presentation step answers access_denied.
Do: check that the wallets you support encrypt OID4VP responses with alg ECDH-ES and enc A128GCM or A256GCM. Details: Presentation.
Transaction data: hash checks follow OpenID4VP 1.0
Changed: the key binding JWT of an SD-JWT VC must hash transaction data with an algorithm the entry's transaction_data_hashes_alg lists, sha-256 when the entry does not set it. 9.x accepted sha-384 and sha-512 for every entry, and sha-256 for an entry that listed only other algorithms. Such a presentation now fails. The hashes may come in any order; 9.x required request order. An entry whose transaction_data_hashes_alg is not a non-empty array of strings makes every response that presents an SD-JWT VC it references fail with Presentation validation failed: Transaction data entry <index> cannot be parsed, where <index> is the entry's zero-based position in transaction_data; 9.x ignored the field.
An entry whose credential_ids list several presented credentials now needs its hash in only one of them, as OpenID4VP 1.0 requires; 9.x required it in each, and the TS12 key binding claims in each. The TS12 claims are now required in the key binding JWTs that carry the hash. A credential query with several presentations (multiple: true) still needs the hash in each of them when it authorizes the entry, and the hash in only some of them fails the response. A key binding JWT that repeats an entry's hash is now accepted; 9.x rejected it because the number of hashes had to equal the number of entries.
An entry for which the response contains no SD-JWT VC it references now fails the response with Presentation validation failed: Transaction data entry <index> references no presented SD-JWT VC (...). 9.x accepted such an entry unchecked, so a TS12 payment could complete without the holder authorizing it, for example when it referenced an mDOC query and the wallet presented only the mDOC, or when the wallet answered credential_sets with an option that leaves out every credential the entry references. A presentation configuration stored by 9.x whose transaction data no SD-JWT VC can authorize stays in the database, but requests with it answer 400 (Integrators), and a change to it is refused until the entries are fixed.
Do: if your wallets hash with sha-384 or sha-512, list the algorithms in the entry, for example "transaction_data_hashes_alg": ["sha-256", "sha-384"], and correct entries where the field is not a non-empty array. Check that every entry's credential_ids name only dc+sd-jwt queries of the DCQL query, in the presentation configurations and in the transaction_data your backend sends with POST /api/verifier/offer. Details: Transaction data.
Trust lists: outdated lists are discarded everywhere
Changed: a trust list without a valid NextUpdate, or whose NextUpdate has passed, is discarded as expired (ETSI TS 119 602 §6.3.15) wherever it is used, also a closed list whose NextUpdate is null. 9.x checked only the first list of a credential query's etsi_tl entry that had a NextUpdate (and then failed the whole check), accepted a list without NextUpdate or with one that is not a valid date, and never checked wallet-provider lists. Whoever served an older, still validly signed list could thereby undo a removal or a withdrawn service. Now the issuers and wallet providers of a discarded list are not trusted, while the lists referenced with it still count:
- a credential whose issuer is listed only in a discarded list fails with
trust_chain_not_trustedorno_trust_chain_to_root; the server log names the discarded lists, and so does the session log when it is enabled; - a wallet or key attestation whose provider is listed only in a discarded list is rejected as if the provider were not listed, and the message ends with
(<n> outdated trust list(s) left out; the server log names them); - when every list referenced together is discarded, a credential fails with
trust_list_unavailable, the built-in token endpoint answersWallet attestation verification failed: No configured trust list is current ..., the PAR endpoints and the token endpoints of chained and OID4VP authorization servers answerinvalid_clientwithClient attestation validation failed, and the credential endpoint answersinvalid_proofwithNo configured trust list is current ...; - the
trusted_authoritiesof a presentation request leave out a discarded list, external or managed: 9.x sent theakivalues of its issuers. Only when every list of anetsi_tlentry is discarded are their URLs sent asetsi_tl.
The server log names each discarded list and its NextUpdate (Discarded outdated trust list(s) ...). A cached list is fetched again once its NextUpdate has passed, even within the five minutes of the cache; lists that are all outdated are not fetched again for one minute. Managed lists are renewed 10 days before their NextUpdate and are not affected as long as renewal works.
Do: check that every list you reference by url, also in walletProviderTrustLists, has a valid NextUpdate in the future, and that its publisher renews it before then. Watch the log for Discarded outdated trust list(s); for a managed list, also for Failed to renew trust list. Details: Trust lists.
Trust lists: older versions are discarded by their sequence number
Changed: for each tenant and list URL, EUDIPLO remembers the highest LoTESequenceNumber (ETSI TS 119 602 §6.3.2) of a trust list it accepted, in the new database table trust_list_sequence_number, so the numbers hold after a restart and for every instance. A list numbered lower is discarded like an outdated list, even while its NextUpdate is ahead, and so is a list whose LoTESequenceNumber is missing or not a whole number from 1. 9.x read neither, and the NextUpdate check only bounds a replay: whoever served an older, still validly signed list could undo a removal or a withdrawn service until that list's NextUpdate passed, up to 30 days for a list managed in EUDIPLO. A managed list of the same instance, referenced by trustListId or by a URL below PUBLIC_URL or INTERNAL_URL such as <TENANT_URL>/trust-list/<id>, is compared with the number it has in storage instead, which stays exact also when a list is deleted and created again and so starts at 1. The numbers are remembered from the first list accepted after the upgrade. The log names a discarded list with its number, for example ... (LoTESequenceNumber 3 is lower than 5 accepted before), and the wallet-facing message No configured trust list is current ... now also names sequence numbers as a reason.
Do: nothing for lists whose publisher numbers them as ETSI requires. If a publisher numbers a list from 1 again, for example another EUDIPLO instance whose managed list was deleted and created again or imported into an empty database, the list stays discarded until its number is higher than before. Once the publisher has confirmed the new numbering, call DELETE /api/cache/trust-list/sequence-numbers with a token of the tenant that references the list (role issuance:manage or presentation:manage): it forgets that tenant's numbers. Details: Older versions of a list.
OpenID Federation: trust chains are verified
Changed: 9.x trusted any entity whose entity configuration named a configured trust anchor in authority_hints, without checking a signature against the trust anchor, and accepted unsigned entity configurations. 10.0 resolves and verifies the whole trust chain (OpenID Federation):
- An external or upstream authorization server with a
federationpolicy must be listed in a signed subordinate statement by the trust anchor or an intermediate below it, and its entity configuration must haveoauth_authorization_serveroropenid_providermetadata whoseissueris its entity ID. - A presented SD-JWT VC whose query has only an
openid_federationtrusted authority must have anissclaim naming the issuer entity and akidheader naming a key in the entity'sopenid_credential_issuermetadata (jwks), and be signed with that key. 9.x took the entity ID from thex5cleaf certificate and never checked that the certificate's key belongs to the entity, so anyone could present a credential under a member's name; that certificate is no longer used. Its status list must be signed with a key of the same entity's metadata. - An mDOC whose query has only an
openid_federationtrusted authority is rejected. A query with anetsi_tlentry as well keeps working through the trust list. - Federation requests verify TLS certificates also outside
NODE_ENV=production, and an entity configuration or fetch endpoint must answer withapplication/entity-statement+jwt. - Session outcomes and webhooks report a federation trust failure of an SD-JWT VC as
no_trust_chain_to_root(no valid chain, or no keykid) ortrust_list_unavailable(federation unreachable) instead ofverification_error. - A failed verification is no longer replaced by a cached result from the last hour; only when the federation cannot be reached is the last successful resolution reused, for at most 15 minutes and until its chain expires.
- Every trust anchor must be registered with its federation keys (
POST /api/federation-trust-anchor, orfederation-trust-anchors/<id>.jsonin the config folder), and its entity configuration must be signed with one of them. Configurations stored before the upgrade keep loading, but nothing is trusted through an unregistered trust anchor: authorization servers are refused and credentials fail withno_trust_chain_to_root, and the log saysno trust anchor of <entity IDs> is registered with pinned keys. Importing or creating an issuance configuration whosefederation.trustAnchors, or a presentation configuration whoseopenid_federationvalues (in queries without anetsi_tlentry), name an unregistered entity ID is rejected with400, also at startup import; so is a change that adds one. Other changes to a stored configuration keep working.
Do: before you upgrade, get each trust anchor's federation keys from its operator through a channel you trust. If you import configuration from a config folder, add a federation-trust-anchors/<id>.json file for each trust anchor to every tenant folder that names it before you start 10.0, or the plan of that tenant's startup import is blocked, and applies nothing, as soon as a new or changed document names an unregistered trust anchor. Otherwise register them right after the upgrade with POST /api/federation-trust-anchor (Register trust anchors). Check that every federation entity you rely on is registered with its trust anchor (or an intermediate) and publishes signed statements; test with GET {entityId}/.well-known/openid-federation and the superior's fetch endpoint. Issuers whose SD-JWT VCs you verify through federation must set kid and publish the key in their openid_credential_issuer metadata. Add an etsi_tl trust list to mDOC queries that only name a trust anchor. Update alerting or code that matched verification_error for federation failures. For federation entities with test certificates outside production, use certificates EUDIPLO trusts (NODE_EXTRA_CA_CERTS). To delegate resolution to a trust engine, set FEDERATION_RESOLVER=http (Choose the resolver).
HTTP request log: wallet references redacted, req.walletNonce removed
Changed: the HTTP request log no longer has the req.walletNonce field that 9.0 added for the OID4VP routes. Logged URLs replace the wallet reference in /issuers/{tenant}/vci/credential-offers/{walletNonce}, /presentations/{walletNonce}/oid4vp/..., /presentations/{walletNonce}/iso-18013-7 and /issuers/{tenant}/authorize/interactive/complete-web-auth/{auth_session} with [redacted], and so does the url.path span attribute. The values of the query parameters issuer_state, request_uri, code and response_code are [redacted] in logged URLs and in url.query, like q in 9.x. Whoever read these values in a log or trace could fetch the offer, answer the presentation request or continue the authorization.
Do: change log queries, dashboards and alerts that use req.walletNonce or these path and query values to sessionId and tenantId, which every log line of a request carries once it resolved its session (Correlate logs with sessions).
Trust lists: stored entity info fixed at startup
Changed: the database migration of 10.0 puts the entity country codes of stored trust lists in capital letters and their lang tags in lower case, and replaces GB and GR with UK and EL (ETSI TS 119 602). Values it cannot fix, such as Germany, a uri the API now refuses, such as one with a space, and a missing or invalid e-mail address (contactUri) or web site (website), which every entity now needs, stay and are logged once in a line that starts with [Migration] Trust list entity info the API now refuses or requires, followed by the fields as <tenant>/<list> entities.<index>.info.<field>, separated by commas. Since 9.x had no website field, every stored entity is listed with info.website. Such a list keeps being published and renewed, but its next update through the API, the Web Client or a configuration file answers 400 until the fields are fixed, and its export (GET /api/trust-list/{id}/export, a bundle or a config folder) is a v2 document that 10.0 refuses to import until then. The Web Client edit page opens such entities with the missing fields marked (under Integrators).
Do: after the first start of 10.0, search the log for that line, fix the named fields and add the e-mail address and web site of each listed entity with the next update of its list.
Attestation key chains: mDL document signer extended key usage
Changed: certificates that EUDIPLO creates follow the X.509 profiles of ISO/IEC 18013-5 Annex B (Certificate profile). New and renewed signing certificates of attestation key chains carry the critical extended key usage 1.0.18013.5.1.2 (mDL document signer) and an IssuerAlternativeName; under an imported CA, their subject takes country and state from the CA certificate. Root CA certificates that EUDIPLO creates have key usage keyCertSign and cRLSign (no longer digitalSignature), path length 0, a random serial number and an IssuerAlternativeName with PUBLIC_URL. Existing key chains get the new signing certificate at their next rotation, also an automatic one, or at an import that makes EUDIPLO create it (a key without crt, or an external CA chain); existing root CA certificates stay. The same certificate signs SD-JWT VCs, status lists whose keyChainId names an attestation key chain, and status lists without keyChainId in tenants without a statusList key chain. A verifier that enforces the extended key usage (RFC 5280), such as one built on Go crypto/x509 without ExtKeyUsageAny, rejects them.
Do: check that the verifiers of your SD-JWT VCs accept the extended key usage before your attestation key chains rotate, or import an attestation certificate of your own PKI. Give tenants whose status lists are verified that way a statusList key chain, and point status lists that name an attestation key chain in keyChainId to it with PATCH /api/status-lists/{listId} (Revocation). A new root CA can sign no intermediate CA: if you export a key chain's CA key to issue intermediates elsewhere, use a CA of your own (External CA chain).
Credential and deferred credential endpoints: response encryption needs an encrypted request
Changed: the credential and deferred credential endpoints apply the encryption rules of OpenID4VCI 1.0 (Sections 8.2, 9.1 and 10) and answer invalid_encryption_parameters when a request breaks them:
- A plain (
application/json) request that containscredential_response_encryptionis rejected; a wallet that wants an encrypted response must encrypt the request. WithcredentialResponseEncryption: true, wallets therefore have to encrypt in both directions. 9.x accepted the plain request and encrypted the response. - With
credentialRequestEncryption: true, plain requests are rejected. 9.x only advertisedencryption_required. - The JWE header of an encrypted request must name the key in
credential_request_encryption.jwksbykid, use itsalg(ECDH-ES) and anencofA128GCMorA256GCM, and carry noziporcrit. 9.x accepted any JWE it could decrypt, also one withoutkid. The advertised key now always hasalg: "ECDH-ES"; a tenant whose encryption key is a signing key chain with usage typeencryptadvertised its signing algorithm before. - The deferred credential endpoint accepts encrypted (
application/jwt) requests andcredential_response_encryption, and encrypts the credential when an encrypted request asks for it. WithcredentialRequestEncryption: true, plain polls are rejected. WithcredentialResponseEncryption: true, a poll must be encrypted and carrycredential_response_encryption; 9.x answered a plain poll with a plain credential under either flag. 9.x accepted only a plain{"transaction_id": "…"}, so a wallet that encrypted its poll or asked for an encrypted response could not retrieve a deferred credential. A request withouttransaction_idor with an empty one is answered with an OAuth errorinvalid_credential_request(9.x answered a missing one with a validation error body and an empty one withinvalid_transaction_id), and unknown members are ignored instead of rejected.
Do: check that the wallets you serve encrypt the credential request whenever they ask for an encrypted response. A wallet that cannot encrypt requests, such as one built on an OpenID4VCI draft, no longer gets an encrypted response, and with credentialResponseEncryption: true no credential at all. Set the two encryption flags only if every wallet supports encryption. Details: Encryption flags.
Deferred credential response: credentials array
Changed: a ready deferred credential is returned as {"credentials": [{"credential": "…"}]}, the Deferred Credential Response of OpenID4VCI 1.0 (Section 9.2), plain or inside the encrypted response. 9.x returned {"credential": "…"}, which OpenID4VCI 1.0 wallets do not read. This also applies to transactions created by 9.x that are still pending or ready at the upgrade. A pending transaction is still answered with HTTP 400 issuance_pending.
Do: if a wallet you serve reads credential from the deferred credential response, update it to read credentials[0].credential. Details: Deferred issuance.
Certificates: trailing bytes after the DER structure are rejected
Changed: a certificate whose DER encoding has bytes after the end of the certificate is rejected with "Unexpected data after the ASN.1 structure". This applies wherever EUDIPLO reads a certificate: key chain imports, trust lists, and the x5c of credentials, presentations and wallet and key attestations. 9.x ignored the extra bytes.
Do: if an import, a trust list or a wallet fails with this message, ask the certificate's issuer for a correctly encoded certificate.
Certificates: x5c and x5chain hold at most 10 certificates
Changed: EUDIPLO rejects an x5c or x5chain of more than 10 certificates, a trust anchor included if it is sent, before it builds a certificate path from it: the chain of a presented credential (SD-JWT VC or mDOC; an SD-JWT VC verified through OpenID Federation does not use x5c) or of its status list or identifier list, and the chain of a wallet attestation (PAR and token endpoints), a key attestation (credential endpoint) or their status lists. 9.x accepted chains of any length, and the work of building a certificate path grows with the square of the chain's length: a status list from a host an attacker controls, or a key attestation in a request body of up to 10 MB, could keep the server busy for minutes. A presented credential with such a chain fails with verification_error, HTTP 400 to the wallet and session failed, also when no trust list is configured (SKIP_TRUST_AUTHORITY=true). With a trust list, one whose status list carries such a chain fails too, also with statusCheckMode: best_effort: an mDOC with verification_error, an SD-JWT VC with Presentation validation failed: Status List JWT verification failed: ... and no failure code, as for a status list with another signer. The server log names the number of certificates. The built-in token endpoint answers Wallet attestation certificate chain is not valid: x5c holds ... certificates; at most 10 are accepted, the credential endpoint invalid_proof with Attestation proof certificate chain is not valid: ..., and for an attestation's status list both answer Status list JWT signature verification failed - certificate chain is not valid: ...; the PAR endpoints and the token endpoints of chained and OID4VP authorization servers answer invalid_client with Client attestation validation failed. The wallet unit status check of credentials issued with revokeWithWalletUnit reads nothing from a status list with such a chain and revokes nothing.
Do: nothing for chains that hold the signing certificate and its intermediates without the trust anchor, which stay far below the limit. If presentations fail with verification_error or Status List JWT verification failed and the server log says holds ... certificates; at most 10 are accepted, or attestations fail with that message, ask the issuer or wallet provider to send only the signing certificate and its intermediates. Details: How a trust list is used, Wallet and key attestation.
Trust lists: at most 1,000 certificates, and limits on certificate paths
Changed: the trust lists used together, those of a credential query's etsi_tl entry or the walletProviderTrustLists of wallet and key attestations, may hold at most 1,000 certificates of the entities EUDIPLO keeps from them. Lists that hold more are not used: a presented credential fails with trust_list_unavailable, a wallet or key attestation with Wallet provider trust lists could not be loaded or Attestation proof x5c chain could not be validated, and the server log says Trust list ... brings the certificates of its source to ...; at most 1000 are accepted; such lists are not fetched again for one minute. For such an etsi_tl entry, also when one of its lists alone holds more, presentation requests send only the plain URLs of its lists in trusted_authorities, where 9.x sent the aki values of their issuers. A certificate path, from the certificate that signs a credential, status list or attestation to the one it ends at, may hold at most 16 certificates, and EUDIPLO stops looking for it after 64 signature checks: a presented SD-JWT VC past either limit fails with no_trust_chain_to_root, an mDOC with verification_error or no_trust_chain_to_root, an SD-JWT VC whose status list is past it with Status List JWT verification failed, and a wallet or key attestation or its status list with ... certificate chain is not valid: Certificate path not found within 64 signature checks (or ... is longer than 16 certificates). 9.x used every certificate of the lists it read, and checked a signature against every listed certificate whose subject was the issuer's name: a list with thousands of certificates of one subject name and no Subject Key Identifier made every check under that name take seconds on the shared instance, and parsing 20,000 listed certificates took almost three seconds per check.
Do: nothing for lists of up to 1,000 certificates whose CA certificates carry a Subject Key Identifier. If checks fail with one of these messages, ask the list's publisher to list fewer certificates, each CA once and with its Subject Key Identifier, or reference fewer lists together. Details: Size limits.
Integrators
Registration certificates: stored JWTs only, registrar endpoints removed
Changed: with the sandbox registrar integration removed:
- These endpoints are gone:
/api/registrar/config(GET,POST,PATCH,DELETE),POST /api/registrar/access-certificate,POST /api/registrar/access-key-chain, every/api/schema-metadata/*endpoint (TS11 schema metadata catalog and publishing),GET /api/verifier/config/schema-metadata/catalog,POST /api/verifier/config/{id}/registration-cert/reissueandPOST /api/issuer/config/registration-cert/reissue.RegistrarConfigis no longer a resource kind of/api/config-bundles/resources/{kind}and of the document export (/api/config-bundles/resources/{kind}/{id}/document). registration_certof a presentation configuration accepts onlyjwt,purposeandprivacy_policy;id,bodyand the flatregistrationCert*form fields answer400, and so does an emptyjwt("jwt": ""): sendnullforregistration_certor leavejwtout.registrationCertificateof the issuance configuration answers400formodeandrenewal; itsjwtis published while it is valid.- Responses no longer contain
registrationCertCache(presentation configurations) andregistrationCertificateCache(issuance configuration).POST /api/issuer/configstill ignores an echoedregistrationCertificateCacheuntil the next major version. - When a stored certificate expires, nothing renews it:
POST /api/verifier/offerfor that presentation configuration answers400("Registration certificate is expired"), a save or import that sends the configuration'sregistration_certordcql_queryfails untilregistration_cert.jwtis replaced or removed, and the issuer metadata leaves outissuer_info. @eudiplo/sdk-coredrops the functions and types of the removed endpoints and fields;RegistrationCertificateRequestis nowPresentationRegistrationCertificate.
Do: remove calls of the removed endpoints and the removed fields from scripts and integrations, send null instead of an empty jwt, and replace registration_cert.jwt before it expires, from the EUDI Hub (EUDI Hub) or another registrar.
Presentation configurations: etsi_tl values typed by format in @eudiplo/sdk-core
Changed: an etsi_tl value of a credential query can name an ETSI TS 119 612 Trusted List for QEAAs: format: "trusted-list" with url, signingCertificates and the optional schemeTerritories (Trusted Lists for QEAAs). Values without format, or with format: "lote", are LoTE references as before; the API accepts every value it accepted in 9.x. In @eudiplo/sdk-core, an etsi_tl value of PresentationConfigCreateDto and PresentationConfigUpdateDto is therefore a union keyed by format, and TypeScript code that reads trustListId, verifierKey or verifierX509Der from such a value no longer compiles until it narrows it. Code that builds these values compiles unchanged.
Do: narrow the value before reading LoTE fields, for example with !('format' in value) || value.format === 'lote'.
Session outcomes: outdated trust lists
Changed: a credential whose issuer is listed only in an outdated trust list fails with trust_chain_not_trusted or no_trust_chain_to_root when other lists of its query are current, and with trust_list_unavailable only when every list is outdated. 9.x answered trust_list_unavailable when the first list was outdated and ignored the others (Trust lists: outdated lists are discarded everywhere). A list discarded for its LoTESequenceNumber counts as outdated in the same way (Trust lists: older versions).
Do: if you branch on trust_list_unavailable to detect outdated lists, also watch the server log for Discarded outdated trust list(s), which names lists left out while others are current.
OpenID Federation: SD-JWT VCs need iss and kid, new failure codes
Changed: a presented SD-JWT VC whose query names only an OpenID Federation trust anchor is verified with the key kid of its issuer's federation metadata, not with its x5c certificate; mDOCs are rejected for such queries. Session outcomes and webhooks report these federation failures as no_trust_chain_to_root or trust_list_unavailable instead of verification_error.
Do: see OpenID Federation: trust chains are verified under Operators.
Wallet attestations: chained and OID4VP authorization servers answer invalid_client
Changed: the PAR and token endpoints of chained and OID4VP authorization servers answer a rejected wallet attestation, including a missing one where it is required, with an OAuth error (RFC 6749 Section 5.2), as the built-in authorization server does: error: "invalid_client" and error_description: "Client attestation validation failed", with HTTP 400 at the PAR endpoint and HTTP 401 at the token endpoint. 9.x answered HTTP 401 at both endpoints with error: "Unauthorized" and a message that named the reason. The reason is now only in the server log.
The built-in token endpoint still answers invalid_client (HTTP 401) with the reason when it is about the attestation or its provider, for example Wallet provider certificate is not trusted ... or Wallet attestation is not valid: .... When the server fails, the reason is now only in the server log line Client attestation validation failed for ..., which the built-in token endpoint now writes as well, and the error_description is fixed: Wallet provider trust lists could not be loaded when a wallet-provider trust list cannot be fetched, read or verified, Wallet attestation status check failed when the attestation's status list cannot be checked (above), Wallet attestation verification failed for any other server-side error. 9.x answered Wallet attestation verification failed: <reason>, and the reason named the trust list URL and, for a managed list, the address from INTERNAL_URL.
Do: if a wallet or test client of a chained or OID4VP authorization server checks the HTTP status or message of a rejected attestation, check for error: "invalid_client" instead. If a wallet or test client of the built-in authorization server matches Failed to fetch trust list or Trust list JWT verification failed in the error_description, match Wallet provider trust lists could not be loaded instead. Look up the reason in the server log (troubleshooting).
Key attestations: a reference without verifier material answers invalid_proof
Changed: at the credential endpoint, a key attestation checked against a walletProviderTrustLists reference whose verifierX509Der, verifierKey or verifierKeyPem has no content, for example only whitespace, is answered invalid_proof with Attestation proof x5c chain could not be validated. 9.x answered credential_request_denied with Trust list reference '<url>' must define ..., which named the reference URL. The reason of every Attestation proof x5c chain could not be validated answer is now in the server log line Key attestation validation failed for tenant ....
Do: give each walletProviderTrustLists reference with a url a verifierX509Der, verifierKey or verifierKeyPem with content. If a wallet or test client matches credential_request_denied or Trust list reference for this case, match invalid_proof instead. Look up the reason in the server log (troubleshooting).
Issuance configuration: signingKeyId removed, authorizationServer key chains
Changed:
POST /api/issuer/configrefuses the top-levelsigningKeyIdwith400,GETno longer returns it, and the@eudiplo/sdk-coretypesIssuanceConfigandUpdateIssuanceDtodrop it.- A
token.signingKeyIdthat a request sets or changes must name a key chain with usage typeauthorizationServer, else400. - Key chain
usageTypegainsauthorizationServer, and key chain lists can contain theauthorization-serverkey chain EUDIPLO creates (Access tokens). DefaultKeyChains(key-chain-defaults.json) gainsauthorizationServer.
Do: stop sending signingKeyId in issuance configuration requests, create authorization server key chains for token.signingKeyId (POST /api/key-chain with "usageType": "authorizationServer"), and handle authorizationServer wherever your code switches on usageType.
Presentation requests: transaction data must reference an SD-JWT VC query
Changed: saving a presentation configuration (POST and PATCH /api/verifier/config) and POST /api/verifier/offer answer 400 for transaction data whose credential_ids are empty (transaction_data[<index>].credential_ids names no credential query), name an ID that is not a query of the DCQL query (... names ids that are not in the DCQL query: <ids>), or name an mso_mdoc query (... names credential queries that are not dc+sd-jwt: <ids>; ...). The offer checks the request's transaction_data, else the configured list, so a configuration stored by 9.x that breaks the rule answers 400 for every request that does not send its own. Issuance with a presentation step that uses such a configuration fails as well: the interactive authorization endpoint answers server_error with Failed to create presentation request: ..., and the authorize request of an OID4VP-based authorization server answers 400. An iso-18013-7 request, which cannot carry transaction data, now answers 400 when the request sets entries, or the configuration has some and the request does not send "transaction_data": []; 9.x dropped them and completed the session without the holder authorizing them.
Do: make every entry's credential_ids name only dc+sd-jwt queries of the DCQL query, in your presentation configurations and in the transaction_data you send. For iso-18013-7 requests with a configuration that has transaction data, send "transaction_data": []. Details: Transaction data.
Issuance: offers name their session with a random value, not the session ID
Changed: in 9.x, the credential_offer_uri ended with the session ID, an authorization code offer carried the session ID as issuer_state, and an external authorization server copied it into its access tokens. The session ID is also what POST /api/issuer/offer returns, GET /api/session lists, and webhooks and the audit log contain, so anyone who saw it could fetch the offer before the holder's wallet or start its authorization. In 10.0, each new issuance session gets a random walletNonce: the credential_offer_uri ends with it, issuer_state is it, and the offer URI endpoint, pushed authorization requests of the built-in, chained and OID4VP-based authorization servers, interactive authorization and external token bindings find the session only by it. The session ID answers 404 at the offer URI endpoint HTTP 400 "Invalid issuer_state" at the chained and OID4VP-based authorization servers and invalid_request at interactive authorization; the built-in server's pushed authorization request treats it like any unknown issuer_state and starts a wallet-initiated authorization without the offer; an external token whose binding claim holds the session ID gets credential_request_denied at the credential endpoint (9.x answered an external token bound to no offer with HTTP 500). The migration sets walletNonce to the session ID for offers that exist before the upgrade, so they keep working. Offers that a 9.x instance creates after the migration ran get no walletNonce, so do not run 9.x and 10.0 instances against the same database at the same time. Built-in access tokens keep the session ID as sub, and chained tokens keep it as issuer_state claim.
Do: pass the wallet only the offer URI from POST /api/issuer/offer. If your code builds a credential_offer_uri or an issuer_state from the session ID, take the value from the offer URI instead (walletNonce of GET /api/session/{id}). If your external authorization server maps issuer_state to EUDIPLO session IDs, look the session up by walletNonce or stop relying on that mapping.
Digital Credentials API: the request names its origin
Changed: a dc-api or iso-18013-7 request binds the wallet's answer to the origin of the page that calls the wallet: OpenID4VP requests carry it in the signed expected_origins claim, ISO 18013-7 requests in the session transcript. The wallet refuses the request on any other page. In 9.x, POST /api/verifier/offer took that origin from expected_origin, else from the request's Origin and then its Host header, read a value without scheme such as localhost:8080 as http://localhost:8080, and signed whatever the caller sent; without a usable origin it signed the request without expected_origins. A backend that passed the browser's request on, or forwarded its Origin header, got a request signed by your verifier for any website, which wallets then accept there under your verifier's name; the wallet's origin check proved nothing. In 10.0, only expected_origin in the body names the origin; the Origin and Host headers of the call are not used. A dc-api or iso-18013-7 call without expected_origin answers HTTP 400 "needs expected_origin" ("lists several allowedOrigins" when the configuration lists more than one), and a value without http:// or https:// answers 400 "it is not an http or https origin". Presentation configurations have the new, optional allowedOrigins: when set, a call may only name one of these origins ("does not allow the origin …"), and a call without expected_origin uses the only listed origin. The origin is fixed when the request is created: the wallet-facing request endpoint no longer uses the Origin header of whoever fetches the request object. uri requests are unchanged. DC API sessions created before the upgrade keep their signed request object.
Do: send expected_origin with every dc-api and iso-18013-7 call, as a full origin such as https://shop.example.com, taken from your own configuration. Never take it from the end user's request, such as a forwarded Origin header (Digital Credentials API). The Web Client sends its own origin. @eudiplo/sdk-core sends location.origin in a browser; on a server, pass origin to createPresentationRequest({ responseType: 'dc-api' }) and createDcApiPresentationRequest(). To limit the origins any caller may name, for example when a client secret is used in a browser, set allowedOrigins on the presentation configuration (Allowed origins); in the Web Client, under Request and verification options. Configuration files need format v4 for the field (Configuration files).
ISO 18013-7: the page posts to the response_uri, not to the session ID
Changed: in 9.x, the page posted the wallet's encrypted response to POST /presentations/{session}/iso-18013-7 with the session ID from POST /api/verifier/offer. The session ID is also what GET /api/session lists and webhooks and the audit log contain, so anyone who saw it could post a response in the holder's place and end the session as failed. In 10.0, an offer with response_type: "iso-18013-7" returns org_iso_mdoc.response_uri, which ends with a random walletNonce, and the endpoint finds the session only by it. The session ID answers 404. The migration sets walletNonce to the session ID for ISO 18013-7 sessions that exist before the upgrade, so pages that already hold an offer can finish it. ISO 18013-7 sessions that a 9.x instance creates after the migration ran get no walletNonce and answer 404, so do not run 9.x and 10.0 instances against the same database at the same time. The OpenID4VP endpoints do not answer an ISO 18013-7 walletNonce.
Do: post the encrypted response to org_iso_mdoc.response_uri from the offer response instead of building the URL from session. Keep using session for GET /api/session/{id} and webhooks.
Issuance: presentation steps have their own session ID
Changed: in 9.x, the presentation session of an interactive authorization step had the auth_session as ID, and GET /api/session lists it, so anyone who saw it could send the follow-up request after the wallet had answered at the response_uri and take the only authorization code. In 10.0, each presentation step gets a presentation session with a random ID; GET /api/session/{auth_session} answers 404. The migration keeps auth sessions that are open during the upgrade working; presentation steps that a 9.x instance starts after the migration ran fail with invalid_request on 10.0, so do not run both versions against the same database at the same time. The callback of the OID4VP-based authorization server (…/vp-callback?cas=…) now answers HTTP 400 and leaves the authorization pending when it gets no matching response_code while the presentation is open or has completed; 9.x ended the authorization and redirected with an error. It still redirects with an error once the presentation failed or expired.
Do: if your backend reads the presentation session of an interactive authorization step by its auth_session, look it up by the walletNonce of the step's request_uri instead (GET /api/session?q=…).
Issuance configuration: federation.entityId checked on save
Changed: POST /api/issuer/config answers 400 for a non-empty federation.entityId that is no https URL with a host and without query, fragment, credentials or whitespace (http only with OUTBOUND_URL_ALLOW_HTTP=true), also when the request changes other fields and sends the stored value back.
Do: see Issuance configuration: federation.entityId must be an https URL under Configuration files.
Credential configurations: claim patterns run on RE2
Changed: claim constraints patterns (pattern, patternProperties keys, propertyNames.pattern) are matched with RE2 in linear time; 9.x used the JavaScript engine, where a pattern like ^(a+)+$ could block issuance for all tenants. POST /api/issuer/credentials and PATCH /api/issuer/credentials/{id} answer 400 with "Claim patterns are matched with RE2" for a pattern RE2 cannot run: lookarounds ((?=, (?!, (?<=, (?<!), backreferences (\1, \k<name>), inline flags such as (?i), unknown escapes such as \e, \S inside a character class, the empty classes [] and [^], long Unicode property names such as \p{Letter} or \p{Script=Latin}, patterns over 1000 characters and patterns with too many or too large repetitions. \s, \S and . keep their JavaScript meaning. A configuration stored by 9.x keeps its pattern: until it is replaced, offers with claims for it answer 409 and credential requests fail with credential_request_denied, both with "has a claim pattern that cannot be used", and a save that sends it back, as the Web Client does, answers 400.
Do: search your credential configurations for the constructs above and rewrite them, for example \p{L} for \p{Letter}, \p{Latin} for \p{Script=Latin} or an explicit character class for a lookahead; see Constraints. Configuration files: see Credential configurations: claim patterns must suit RE2.
SD-JWT VC: protected claims cannot be selectively disclosable
Changed: an SD-JWT VC credential configuration whose fields[] has an entry with disclosable: true and a path of ["vct#integrity"] or below iss, nbf, exp, cnf, vct, vct#integrity or status can no longer issue: credential requests fail with credential_request_denied and "Cannot disclose protected field". 9.x refused this only for the top-level claims other than vct#integrity. The configuration is still accepted on save. Presentations of SD-JWT VCs that disclose one of these claims selectively, or a part of it, are now rejected at the signature and trust check. Presentations whose issuer-signed JWT or key binding JWT has a crit header are rejected too (RFC 7515: EUDIPLO supports no critical header parameters).
Do: set disclosable: false on such fields. Details: Credential configuration.
Credential status: issuance:offer no longer revokes or suspends
Changed: POST /api/session/revoke needs the new role credentials:status or issuance:manage. In 9.x, issuance:offer could also revoke, suspend and reinstate the credentials of every issuance session of its tenant, so every client that creates offers could invalidate credentials. A token with issuance:offer but neither of the two roles now gets HTTP 403. Reading the status with GET /api/session/{id}/credential-status still works with issuance:offer. In the Web Client, the Revoke, Suspend and Reinstate buttons of a session's Credential Status card need credentials:status or issuance:manage. With Keycloak, EUDIPLO creates the realm role at the first start of 10.0, together with the new roles audit:read, sessions:read and keys:manage, which need no action (roles).
Do: give credentials:status to every client and person that changes credential status with only issuance:offer, for example your application backend. A caller grants it only if it holds it or has tenant:admin (granting roles); to give it to a tenant's admin client first, see Client and user management. Client files with the new roles need file format v2 (Configuration files).
- Built-in authorization server: 9.x rejects the new role, so you can grant it only once 10.0 runs. Until then, revocations of those clients answer
403. Grant it right after the first 10.0 instance is healthy and before it takes traffic, or plan for that window. - Keycloak: create the realm role
credentials:statusand assign it before the upgrade; 9.x passes it through, and 10.0 keeps the existing role. Until 10.0 runs, do not edit these clients or people through EUDIPLO 9.x, in the API or the Web Client: 9.x removes realm roles it does not know when it saves them.
Tenants: IDs must be a folder name
Changed: a tenant ID is also the name of the tenant's folder in CONFIG_FOLDER. 9.x accepted any non-blank ID in POST /api/tenant, so an ID such as x/../acme pointed to the folder of the tenant acme: its admin could read and change that tenant's kms.json and reattach its file-managed resources, with their secrets, into its own tenant. IDs that differ only in case, such as Acme, share that folder on case-insensitive file systems, and the ID kms.json named the global KMS file. In 10.0, POST /api/tenant answers 400 unless the ID uses only lowercase letters, digits, - and _, starts with a letter or digit and has at most 63 characters, the rule eudiplo config tenant create already applied; leading and trailing spaces are still trimmed. Existing tenants keep their ID, but sending POST /api/tenant again for one whose ID breaks the rule, for example to give its <tenant>-admin client other roles, answers 400. The startup import still creates tenants from folder names that break the rule, except a folder whose name contains \ or is kms.json, which it skips with a warning. A tenant whose ID is ., .. or kms.json (in any letter case) or contains /, \ or NUL has no configuration folder: EUDIPLO uses the global kms.json for it and no longer reads <CONFIG_FOLDER>/<id>/kms.json, GET /api/key-chain/providers/config returns tenantConfig: null, PUT and DELETE answer 400, a bundle plan with a KmsConfig document is blocked (KMS_CONFIG_FOLDER_MISSING), and reattaching a resource answers 409. With the startup import enabled (CONFIG_IMPORT_MODE other than disabled), the backend logs a warning for such a tenant at startup.
Do: use IDs such as acme or acme-test when you create tenants, and treat 400 from POST /api/tenant as an invalid ID. For an existing tenant whose ID breaks the rule, change its admin client with PATCH /api/client/<tenant>-admin and POST /api/client/<tenant>-admin/rotate-secret instead of sending POST /api/tenant again. Before you upgrade, move each tenant that will have no configuration folder to a new tenant with a valid ID: export its configuration bundle on 9.x and import it into the new tenant. After the upgrade, 10.0 no longer loads the providers of its own kms.json, so key chains that use them stop working.
Client API: 404 for unknown clients
Changed: with the built-in authorization server, PATCH /api/client/{id} for a client the tenant does not have answers 404 instead of 200. With Keycloak, POST /api/client/{id}/rotate-secret for such a client answers 404 instead of 500. For 403 and 409 from the client and user endpoints, see Client and user management and Client IDs are unique across tenants.
Do: treat 404 as "no such client" in scripts that update clients or rotate their secrets.
Management API tokens: no refresh token, checked against the client
Changed: with the built-in authorization server, POST /api/oauth2/token no longer returns refresh_token, and the property is gone from TokenResponse in the OpenAPI document and @eudiplo/sdk-core. In 9.x it was a second token with the same claims, valid for 30 days; the endpoint never accepted it for a refresh, but the API accepted it as a bearer token. 10.0 answers 401 to it, also to those issued by 9.x; access tokens issued by 9.x stay valid until they expire. Tokens of deleted clients, of clients with a new secret and roles removed from a client stop working at once (Deleting a client or changing its secret ends its access). With Keycloak, nothing changes besides a 401 for a token whose client ID now belongs to another tenant, for ID tokens (Management API with Keycloak) and, without OIDC_AUDIENCE, for tokens of clients EUDIPLO does not manage, which include deleted ones (only EUDIPLO's clients).
Do: request a new token with the client credentials when the old one expires, as the Web Client, the CLI and @eudiplo/sdk-core do, and stop using refresh_token. Details: Revoke access.
Management API with Keycloak: ID tokens refused
Changed: with Keycloak (OIDC set, OIDC_PROVIDER unset or keycloak), 9.x accepted any JWT that the realm signed and that named its issuer, so the ID token of any client in the realm worked as a bearer token whenever OIDC_AUDIENCE was unset, which is the default. 10.0 accepts only bearer access tokens. With Keycloak, the management API answers 401 "Not an access token: …" to a token whose typ claim is present and not Bearer (Keycloak's ID tokens carry ID, access tokens bound to a DPoP key DPoP, whose proof EUDIPLO does not check), to one that carries at_hash, c_hash or s_hash, and to one whose JWS header names another typ than JWT or at+jwt; OIDC_PROVIDER=generic applies the last two checks too. A token without exp, which never expires, now gets 401 "Access token has no expiry" with Keycloak too. Keycloak's bearer access tokens, which always carry exp, pass these checks; which clients' tokens are accepted is the next section. The Web Client, the CLI and @eudiplo/sdk-core send access tokens.
Do: in scripts and services that call the management API with a Keycloak token, send access_token from Keycloak's token response, not id_token. Details: Keycloak.
Management API with Keycloak: only EUDIPLO's clients without OIDC_AUDIENCE
Changed: every client of a Keycloak realm gets access tokens with aud: account and the realm roles of its person or service account. Without OIDC_AUDIENCE, which is the default, 9.x accepted the access token of any client in the realm with those roles, so another application in the realm, or Keycloak's account console, could call the management API with a person's tokens. 10.0 accepts a token only when its azp (or, without it, client_id) is the web client's client (OIDC_UI_CLIENT_ID, default eudiplo-ui), the AUTH_CLIENT_ID client when AUTH_CLIENT_SECRET is set too (EUDIPLO creates it only then), or a client EUDIPLO manages, that is one created through EUDIPLO (POST /api/client, <tenant>-admin from POST /api/tenant with roles, the web client or a configuration import) and not deleted since. Other tokens get 401 "This token was issued to a client of the realm that EUDIPLO does not manage". Tokens of a deleted client now get it at once instead of when they expire. With OIDC_AUDIENCE set, nothing changes: every client whose tokens carry the audience is accepted. OIDC_PROVIDER=generic is not affected.
Do: if a script or service calls the management API with a token of a client you created in Keycloak yourself, create a client for it through EUDIPLO and switch to that one, or set OIDC_AUDIENCE and add an audience mapper to the clients that may call EUDIPLO. Other setups that are refused too:
- the admin client
OIDC_CLIENT_ID(eudiplo-admin) used as an API caller: create a client through EUDIPLO for that caller; - the bootstrap client after
AUTH_CLIENT_IDorAUTH_CLIENT_SECRETwas removed from the environment: set both again, and EUDIPLO updates the client with that secret on the next start; - several EUDIPLO instances that share one realm: each instance refuses the clients created through another one. People's tokens of
eudiplo-uiand a sharedAUTH_CLIENT_IDstill pass everywhere; to keep the instances apart, give each a realm of its own, or setOIDC_AUDIENCEwith a different audience per instance; - a client created through EUDIPLO that is missing from its client list (
GET /api/client), for example after the database was reset: create it again through EUDIPLO.
Details: Keycloak.
Webhooks and attribute providers: time and size limits, checked redirects
Changed: 9.x waited without limit for a webhook or attribute provider, read answers of any size, followed up to 21 redirects without checking their targets against the outbound URL policy, and sent the API key header to every redirect target. 10.0 ends a delivery after 60 seconds, redirects included, and reads at most 5 MiB of the answer. It follows up to 5 redirects (301, 302, 303, 307, 308); each target must pass the outbound URL policy, and the API key header is only sent to the origin of the configured URL.
Do: configure the final URL of the webhook instead of one that redirects, for example https:// instead of an http:// URL that redirects, or the trailing slash your framework expects. Answer within 60 seconds; an attribute provider that needs longer answers {"deferred": true} (Deferred issuance). Keep answers under 5 MiB. Details: Webhooks.
Inline webhooks: empty URL, header name or API key rejected
Changed: the inline webhook of POST /api/verifier/offer and a webhook claim source in credentialClaims of POST /api/issuer/offer are validated like stored webhooks. An empty url, auth.config.headerName or auth.config.value now answers HTTP 400. In 9.x the request was accepted; an empty URL or header name failed later at delivery, and an empty API key was sent as an empty header.
Do: send a non-empty url, header name and API key, or use "auth": { "type": "none" } for a webhook without authentication.
Key chains: enabled rotation needs intervalDays
Changed: POST /api/key-chain with "rotationPolicy": { "enabled": true } and without intervalDays answers HTTP 400. So does PUT /api/key-chain/{id} with "rotationPolicy": { "enabled": true } when neither the request nor the key chain has a rotation interval, also for a key chain whose rotation is already enabled. 9.x accepted both and stored rotation as enabled, but the daily rotation job skips a key chain without an interval, so such a key chain was only rotated on request.
Do: send intervalDays whenever you enable rotation, or leave rotation off for key chains you rotate by hand. Key chains that already have rotation enabled without an interval keep their settings; GET /api/key-chain lists them with rotationPolicy.enabled: true, intervalDays: null and no nextRotationAt. Their export from GET /api/key-chain/{id}/export is imported again with a 90-day interval. Decide for each of them:
- Turn rotation off with
PUT /api/key-chain/{id}and"rotationPolicy": { "enabled": false }, in particular for key chains whose certificate comes from a registrar or an external PKI: rotating a standalone or imported key chain replaces its certificate with a self-signed one. - Or give it an interval with
"rotationPolicy": { "intervalDays": 90 }. The daily job counts the interval from the last rotation or, without one, from creation, so a key chain older than the interval rotates in the next run.
Details: Keys and certificates.
Key chains: ES384 and ES512, and the algorithm lists in metadata
Changed: key chains can sign with ES384 (P-384) or ES512 (P-521) besides ES256, chosen with alg when they are created (Keys and certificates); ES256 stays the default. EUDIPLO accepts ES384 and ES512 from wallets and other issuers: proof_signing_alg_values_supported in the issuer metadata and the algorithm lists in vp_formats_supported of OID4VP requests now list ES256, ES384 and ES512 (mdoc: their COSE identifiers).
Do: nothing for ES256 key chains. Before you create ES384 or ES512 key chains, check that the wallets and relying parties you serve support them; wallets only have to support ES256.
mdoc: algorithm identifiers in metadata and signature checks
Changed: three things follow OpenID4VCI 1.0, OpenID4VP 1.0 and RFC 9053 more closely for mdoc credentials:
credential_signing_alg_values_supportedof an mdoc credential configuration lists only the COSE identifier that EUDIPLO writes into the IssuerAuthalgheader, for example[-7]instead of[-7, -9]for an ES256 key chain (OpenID4VCI 1.0 Appendix A.2.2). The credentials themselves are unchanged.- In OID4VP requests,
client_metadata.vp_formats_supported.mso_mdocreplacesalg, which OpenID4VP does not define, withissuerauth_alg_values([-7, -35, -36]) anddeviceauth_alg_values([-7, -35, -36, -9, -51, -52]) (OpenID4VP 1.0 Appendix B.2.2). Wallets that read the oldalgmember no longer find it; wallets that follow OpenID4VP 1.0 now see the algorithms EUDIPLO accepts. - A presented mdoc fails verification when its IssuerAuth or DeviceSignature has no
algin the protected header (ISO/IEC 18013-5 requires it), or when thealgnames a different curve than the key, for example-7(ES256) on a P-384 key. The same applies to the status list and identifier list CWTs its MSO refers to. 9.x picked the hash from the key's curve and ignored thealg. The verification error names the mismatch.
Do: nothing for wallets that follow ISO/IEC 18013-5 and OpenID4VP 1.0. If a wallet relied on vp_formats_supported.mso_mdoc.alg, or omitted alg in its DeviceSignature, or an mdoc issuer omits alg in its status list CWTs, test it against 10.0 before you upgrade.
Key chains: activeCertificate must be a PEM chain for the active key
Changed: PUT /api/key-chain/{id} with activeCertificate answers HTTP 400 for a value without a -----BEGIN CERTIFICATE----- block (an empty string included), for a block that is not a certificate, for a first certificate that does not hold the public key of the active key, and for a chain in which a certificate did not issue the one before it. 9.x stored any string, but EUDIPLO signs with the active key, so wallets could not verify a chain whose leaf belongs to another key. A certificate from the EUDI Hub is stored the same way; one issued for a key that was rotated in the meantime is refused and revoked at the EUDI Hub.
Do: send PEM, the certificate for the active key first, each certificate followed by the one that issued it; convert DER with openssl x509 -inform der -in cert.der. After a rotation, the key is new: create a certificate signing request with GET /api/key-chain/{id}/csr and store the certificate issued for it instead of the old one.
Details: Keys and certificates.
Key chains: the tenant's encryption key chain answers 404 and 409
Changed: every tenant has an encryption key chain with usage type encrypt, which EUDIPLO creates itself and uses to decrypt encrypted credential requests and ISO 18013-7 responses. Its ID is the kid of the published encryption key. GET /api/key-chain never listed it, but 9.x let the other key chain endpoints change, rotate, delete and export it, and an import with its ID replaced it. In 10.0, PUT /api/key-chain/{id}, POST /api/key-chain/{id}/rotate, DELETE /api/key-chain/{id} and GET /api/key-chain/{id}/export answer HTTP 404 for its ID, and POST /api/key-chain/import with its ID answers 409. GET /api/key-chain/{id} still returns its public key. The daily rotation job no longer rotates it, even if rotation was enabled for it.
Do: leave the encryption key chain to EUDIPLO; there is no replacement for rotating, deleting or exporting it. If GET /api/key-chain?usageType=encrypt lists a key chain whose ID is the kid of the published encryption key, a 9.x import replaced the encryption key chain. EUDIPLO still decrypts with it, but it is a normal key chain that the API can change. Details: Keys and certificates.
Trust lists: DELETE refuses lists that configurations use
Changed: DELETE /api/trust-list/{id} answers HTTP 409 while a presentation config, a credential config or the issuance configuration of the tenant still references the list. 9.x deleted the list anyway, and the presentation requests, wallet and key attestation checks and schema metadata publications that used it failed afterwards. The 409 body has code: "TRUST_LIST_IN_USE", a message that names the configurations, and references with the kind of each and, for presentation and credential configs, its id and description; configurations the caller's roles cannot read are only counted. Configuration bundles and config folders imported in replace mode no longer delete such a list either: in 9.x their plan only stopped for a document of the bundle that named the list by trustListId. Now the plan item of the list is blocked with TRUST_LIST_IN_USE while any configuration that survives the import references it, also one outside the bundle or a reference by URL, so the import applies nothing; a startup import in replace mode skips the tenant and logs the issue (details).
Do: remove the references, or point them to another list, before you delete a list, through the API or by leaving the list out of a bundle or config folder. In scripts, treat 409 with code: "TRUST_LIST_IN_USE" as "still in use". If a replace import or CONFIG_IMPORT_MODE=replace stops with TRUST_LIST_IN_USE, keep the list in the bundle or folder, or remove the references it names, then plan again. Details: Trust lists.
Trust lists: internal entities need key chains of the matching usage type
Changed: POST /api/trust-list and PUT /api/trust-list/{id} answer 400 when an internal entity names in issuerKeyChainId a key chain whose usage type is not attestation, or in revocationKeyChainId one that is neither statusList nor attestation (a status list is signed with the attestation key chain when it is pinned to one or the tenant has no status list key chain). errors[].path names the field, for example ["entities", 0, "issuerKeyChainId"], with errors[].code key_chain_usage_mismatch; for the other field errors see below. 9.x published the certificate of any key chain of the tenant, so a list could name the status list certificate as the issuer's, and wallets and verifiers using the list then rejected the issuer's credentials. A key chain that the stored list already names in the same field is still accepted, so a list saved by 9.x can be updated without changing it (Trust lists).
Do: point issuerKeyChainId to the attestation key chain that signs the issuer's credentials and revocationKeyChainId to the key chain that signs its status lists, and show the error at the field named in errors[].path.
Trust lists: an update keeps only a trustList key chain
Changed: PUT /api/trust-list/{id} without keyChainId still keeps the key chain the list is signed with, but now answers HTTP 409 when that key chain no longer has usage type trustList, with the message Key chain <id> of this trust list is not valid for Trust List usage (key lacks TrustList usage). Name a key chain with usage type trustList in keyChainId. This happens, for example, after a key chain import that reused the ID of the list's key chain with another usage type; 9.x went on signing the list with that key, for example an attestation or access key. A keyChainId in the request was already checked in 9.x, and the scheduled renewal still signs the list with its stored key chain. The plan of a configuration bundle or config folder now checks both: a TrustList document that would change a list whose key chain, named in keyChainId or kept, has no usage type trustList is blocked with KEY_CHAIN_USAGE_MISMATCH: the import answers HTTP 400 CONFIG_APPLY_BLOCKED and applies nothing, eudiplo config plan exits with 1, and a startup import skips the tenant and logs the issue. 9.x planned such a document as applicable: with keyChainId, the import stopped at it with HTTP 500 CONFIG_APPLY_FAILED after the documents before it, for example a KeyChain document that changed the usage type, were applied; without keyChainId, the import applied it and signed the list with the kept key chain. A document that leaves the list unchanged gets the issue only as a warning in the plan, which a startup import does not log.
Do: compare the keyChainId of each list in GET /api/trust-list with the usageType of that key chain in GET /api/key-chain. For each list whose key chain is not a trustList key chain, send keyChainId with a trustList key chain on the next update, through the API, the Web Client or the TrustList document. In a bundle plan (eudiplo config plan or Plan and validate in the Web Client), a warning KEY_CHAIN_USAGE_MISMATCH on a TrustList document points to such a list. Details: Trust lists.
Trust lists: field errors answer 400, unknown lists 404
Changed: 9.x answered every failure of POST /api/trust-list and PUT /api/trust-list/{id} after the schema validation of the body with 409 and only a message. 10.0 answers 400 with an entry per refused field in errors, as for schema errors: key_chain_not_found when keyChainId, entities.<index>.issuerKeyChainId or revocationKeyChainId names a key chain the tenant does not have, key_chain_usage_mismatch at keyChainId for a key chain whose usage type is not trustList, invalid_certificate at entities.<index>.issuerCertPem or revocationCertPem without an X.509 certificate, and invalid_entity_info at entities.<index>.info for other entity data the LoTE format does not take, reported once no other field is refused; info.country, info.lang and info.uri are refused by the body schema (below). PUT /api/trust-list/{id}, GET /api/trust-list/{id}, GET /api/trust-list/{id}/export, GET /api/trust-list/{id}/versions and GET /api/trust-list/{id}/versions/{versionId} answer 404 for a list or version the tenant does not have; 9.x answered 409, and 200 with an empty array for the versions of an unknown list. 409 remains for an update that another update or a renewal overtook, for an update without keyChainId whose kept key chain lost usage type trustList (above), and for a POST without keyChainId when the tenant has no trustList key chain or the one EUDIPLO picks has no valid certificate. Other failures, for example of the key management system, answer 500 instead of 409, and in production the message no longer names their cause; the backend log does (Trust lists).
Do: in scripts, read errors[].path on 400, treat 404 as "no such trust list", and retry a 409 of PUT only after reading the list again.
Trust lists: entity country and language held to ETSI TS 119 602
Changed: POST /api/trust-list and PUT /api/trust-list/{id} answer 400 when an entity's info.country is not an ISO 3166-1 alpha-2 code in capital letters (with UK for the United Kingdom, EL for Greece and EU for the European Union, ETSI TS 119 602 clause 6.1.5), when info.lang is not an IETF RFC 5646 language tag in lower case (clause 6.1.4), or when info.uri is not an absolute URI in the form a URL parser writes it (spaces percent-encoded, no backslashes; ETSI TS 119 602 clause 6.1.2). errors[].path names the field, for example ["entities", 0, "info", "country"]. 9.x accepted any two characters as country, such as de, GB or 12, and any language tag, and published them in the list; a longer country such as Germany or a relative uri failed with 409. The database migration of 10.0 fixes the case of country and lang in stored trust lists and replaces GB and GR with UK and EL, so their exports and the Web Client edit page show country and lang values the API accepts; it logs values it cannot fix and entities without the e-mail address and web site that 10.0 requires (below). The published list keeps its values until the list is updated. The postal address of an entity now carries the full language tag, for example de-at, instead of its first subtag de. An entity whose lang is not en now also publishes its name, information URI, postal address and electronic address under en with the same text, after the entry in its own language, since ETSI TS 119 602 clause 6.1.4 requires every list to support English; 9.x published them in lang only. Service names are published under en only; 9.x tagged them with lang. A stored list gets these entries when it is next updated through the API, the Web Client or a changed TrustList document in a configuration file; importing the same file again and the scheduled renewal keep the published entities as they are. Managed lists now carry ListIssueDateTime and NextUpdate in whole seconds (2026-11-06T12:00:00Z, clause 6.1.3) instead of with milliseconds.
Do: send country codes in capital letters and language tags in lower case, and show the error at the field named in errors[].path. After the upgrade, look for [Migration] Trust list entity info the API now refuses in the log and fix the named fields with the next update. A client that parses ListIssueDateTime or NextUpdate as an ISO 8601 date-time needs no change. A relying party that reads TEName, TEInformationURI, TEPostalAddress or TEElectronicAddress of a list must pick the entry by lang instead of expecting one entry, and find service names under en. Details: Trust lists.
Trust lists: entities need an e-mail address and a web site
Changed: POST /api/trust-list and PUT /api/trust-list/{id} answer 400 when an entity's info.contactUri or the new info.website is missing, because ETSI TS 119 602 clause 6.5.3.2 makes an e-mail address and a web site mandatory in TEElectronicAddress. contactUri must be one e-mail address in ASCII characters, bare ([email protected]) or as a mailto: URI, and is published as a mailto: URI; website must be an absolute http or https URI in serialized form, for example https://example.com/. The new optional info.phone takes a telephone number in international form without spaces, such as +49-30-1234567, and is published as a tel: URI. errors[].path names the field, for example ["entities", 0, "info", "website"]. In @eudiplo/sdk-core, TrustListEntityInfo marks contactUri and website as required, so TypeScript code that builds entities without them no longer compiles. 9.x accepted any contactUri and published it with mailto: in front, so a URL there became mailto:https://…, and a list without contactUri had an empty TEElectronicAddress. Lists stored by 9.x keep being published and renewed unchanged until their next update. In the Web Client, the trust list form has the required fields E-mail Address and Website and the optional Telephone; the former Contact URI field is now E-mail Address, and the former Website URI field, which sets info.uri, is now called Information URI.
Do: send contactUri and website for every entity, and update each stored list once with them; the [Migration] log line (under Operators) names the entities. Show the error at the field named in errors[].path. Details: Trust lists.
Key chains: DELETE refuses key chains that configurations name
Changed: DELETE /api/key-chain/{id} answers HTTP 409 while a configuration of the tenant names the key chain: the access or authorizationServer entry of the tenant's key chain defaults (key-chain-defaults.json), token.signingKeyId of an authorization server of the issuance configuration, keyChainId of a credential configuration, a status list or a trust list, accessKeyChainId of a presentation configuration, or issuerKeyChainId or revocationKeyChainId of an internal trust list entity. 9.x deleted the key chain anyway: the configurations that named it failed to sign afterwards, and deleting the signing key chain of a trust list also deleted the trust list. A configuration that names no key chain and uses the tenant's default one does not count, except a trust list, which stores the key chain picked at creation. The 409 body has code: "KEY_CHAIN_IN_USE", a message that names the configurations, and references with the kind of each and, except for the issuance configuration and the key chain defaults, its id and description; configurations the caller's roles cannot read are only counted. Configuration bundles and config folders imported in replace mode no longer delete such a key chain either: the plan item of the key chain is blocked with KEY_CHAIN_IN_USE while a configuration that survives the import names it, also one outside the bundle, so the import applies nothing; a startup import in replace mode skips the tenant and logs the issue (details).
Do: point the configurations to another key chain, or remove the field so they use the default key chain, before you delete a key chain, through the API or by leaving the key chain out of a bundle or config folder. Delete a trust list before its signing key chain. In scripts, treat 409 with code: "KEY_CHAIN_IN_USE" as "still in use". If a replace import or CONFIG_IMPORT_MODE=replace stops with KEY_CHAIN_IN_USE, keep the key chain in the bundle or folder, or remove the references it names, then plan again. Details: Keys and certificates.
Attribute providers: DELETE refuses providers that credential configurations name
Changed: DELETE /api/issuer/attribute-providers/{id} answers HTTP 409 while a credential configuration of the tenant names the provider in attributeProviderId. 9.x deleted the provider anyway, and issuing that credential then failed because its attributes could not be fetched. The 409 body has code: "ATTRIBUTE_PROVIDER_IN_USE", a message that names the credential configurations, and references with kind (CredentialConfig), id and description of each. Configuration bundles and config folders imported in replace mode still delete a left-out provider without this check.
Do: remove attributeProviderId from the credential configurations, or point it to another provider, before you delete a provider. In scripts, treat 409 with code: "ATTRIBUTE_PROVIDER_IN_USE" as "still in use". Details: Attribute providers.
Presentation configurations: an unknown ID answers 404
Changed: an unknown presentation configuration answers HTTP 404 with the message Presentation config "<id>" not found instead of 409 Request ID <id> not found. This applies to GET, PATCH and DELETE /api/verifier/config/{id}, to POST /api/verifier/offer with an unknown requestId, and to POST /api/eudi-hub/registration-certificate/presentation with an unknown presentationConfigId. The wallet-facing request object and response endpoints of a session whose presentation configuration was deleted meanwhile answer 404 instead of 409 too. A database error during the lookup now answers 500 instead of being reported as not found.
Do: check for 404 instead of 409 where you handle a missing presentation configuration.
Issuance notifications: the first event finishes the session
Changed: the first OpenID4VCI notification of an issuance session sets its status (completed or failed) and its outcome, failureCode and errorReason. Later notifications, for another credential of the offer or a repeated one, are still stored in notifications, sent to the webhook and answered as before, but no longer change the finished session. In 9.x the latest event decided, so for example credential_accepted after credential_failure turned a failed session into completed (details).
Do: if you derive a per-credential result from later events, read them from the notification webhook or from notifications of GET /api/session/{id} instead of the session status.
Credential configurations: constraints accept only JSON Schema keywords
Changed: POST /api/issuer/credentials and the other writes of credential configurations answer HTTP 400 when a claim field's constraints, or a subschema in it, has a key that is not in the list under Constraints, for example format, $ref, nullable, an x- extension or a form hint such as widget; the error names the field and the keyword. 9.x stored any key. In the Web Client, the offer form rendered formly's widget.formlyConfig from these keys, so a stored configuration could inject HTML and scripts into the page of everyone who opened the offer form for it.
10.0 ignores such keys in configurations stored by 9.x: claim validation at issuance, the offer form and exports leave them out. For most of them nothing changes, because since 9.0 issuance with them already failed (claims are validated with a strict JSON Schema validator that refuses unknown keywords such as format, x- extensions or widget). The validator did apply a few: nullable, dependencies, $ref with $defs or definitions and $id. A configuration that relies on them validates claims differently after the upgrade; for example, a claim with nullable: true no longer accepts null.
The generated API types of @eudiplo/sdk-core type ClaimFieldDefinitionDto.constraints as ClaimConstraints instead of an open object, and its buildJsonSchema and deriveRuntimeArtifacts leave out the other keys too.
Do: remove those keys from your credential configurations. Leave out a claim instead of sending null, write dependencies as dependentRequired or dependentSchemas, and put the subschema of a $ref in place. A configuration stored by 9.x is used without them, but sending its fields back through the API answers 400 until they are gone; files are covered under Configuration files.
Credential configurations: display colors and locales checked on save
Changed: POST /api/issuer/credentials and PATCH /api/issuer/credentials/{id} answer 400 when a config.display[] entry has a background_color or text_color that is not a CSS Color Level 3 numerical value (#rgb, #rrggbb, rgb(), rgba(), hsl(), hsla() or transparent, with lowercase function names and comma-separated arguments), or when two entries have the same locale, compared case-insensitively. OID4VCI 1.0 publishes these values in the issuer metadata, defines the colors as such values and allows one display entry per language; 9.x stored any string, such as navy or #12107c80, and several entries per locale. A configuration stored by 9.x keeps such values until it is saved again, and GET still returns them. The issuer metadata and exports trim colors and lowercase their function names, and leave out the colors that still do not fit and every entry after the first for a locale. The Web Client shows the errors when you open the configuration and saves only once they are fixed. The issuer metadata now leaves out display when the list is empty instead of publishing an empty array.
Do: replace other color forms with a hex value, for example #000080 for navy, or remove the color so the wallet uses its own, and keep one display entry per locale. Configuration files: see Credential configurations: display colors and one entry per locale.
Cache endpoints: only the caller's tenant
Changed: in 9.x, GET /api/cache/stats listed the status lists cached for every tenant, and DELETE /api/cache, /api/cache/trust-list and /api/cache/status-list cleared the caches of all tenants, for any caller with issuance:manage or presentation:manage. In 10.0, these callers see and clear only their tenant's entries: its trust lists, and the status lists and OpenID Federation resolutions it used. A token with tenants:manage, such as the root client's, now has access too and covers all tenants. DELETE /api/cache/trust-list/sequence-numbers clears only the caller's trust lists.
Do: if you cleared another tenant's caches with a tenant's token, for example after revoking credentials of an issuer tenant that a separate verifier tenant checks, use that verifier tenant's token or a tenants:manage token instead. Details: Caching.
Configuration files
Changed: clients, KMS configurations, the key chain defaults and trust lists have file format v2, credential configurations, tenants (info.json) and key chains v4, presentation configurations v5 and issuance configurations v7, and registrar configurations are no longer read:
- Trust lists (
https://eudiplo.dev/schemas/v2/TrustListConfigFile.schema.json) accept only conforming entity info:countryin capital letters,langin lower case, an absoluteuri, and need an e-mail address incontactUriand the newwebsite(below). - Presentation configurations (
https://eudiplo.dev/schemas/v4/PresentationConfigFile.schema.json) acceptallowedOrigins(Digital Credentials API) and, inetsi_tlvalues,formatwith ETSI TS 119 612 Trusted Lists for QEAAs (format: "trusted-list",signingCertificates,schemeTerritories; Trusted Lists for QEAAs). A v3 file is a valid v4 file (etsi_tlvalues typed byformat). Format v5 (https://eudiplo.dev/schemas/v5/PresentationConfigFile.schema.json) keeps onlyjwt,purposeandprivacy_policyinregistration_certand drops theregistrationCert*form fields (above). - Credential configurations (
https://eudiplo.dev/schemas/v2/CredentialConfigFile.schema.json) acceptx509asframeworkTypeofschemaMeta.trustedAuthoritiesentries. In 9.x, publishing schema metadata with anx509trusted authority andcredentialConfigIdwrote such an entry, and the export of that credential configuration then failed to import again. Format v3 (https://eudiplo.dev/schemas/v3/CredentialConfigFile.schema.json) accepts only JSON Schema validation and annotation keywords infields[].constraints(above) and only claim patterns RE2 can run (below). Format v4 (https://eudiplo.dev/schemas/v4/CredentialConfigFile.schema.json) accepts only CSS Color Level 3 numerical display colors and one display entry per locale (below), and acceptsrevokeWithWalletUnit(Revoke credentials with their wallet unit). - Key chains (
https://eudiplo.dev/schemas/v2/KeyChainConfigFile.schema.json) accepttype(standaloneorinternalChain), whichGET /api/key-chain/{id}/exportand configuration bundle exports now write. In 9.x the export of an internal chain without rotation was imported again as a standalone key chain that signed with the former root CA key. A 10.0 export of such a key chain carries"type": "internalChain"and is imported again as an internal chain with the same root CA certificate and a new signing key (Keys and certificates); a 9.x export withouttypeis still imported as before. Key chains with format v3 (https://eudiplo.dev/schemas/v3/KeyChainConfigFile.schema.json) also accept the usage typefederation(OpenID Federation), and format v4 (https://eudiplo.dev/schemas/v4/KeyChainConfigFile.schema.json) the usage typeauthorizationServer(Access tokens). - Clients (
https://eudiplo.dev/schemas/v2/ClientConfigFile.schema.json) accept the new rolesaudit:read,sessions:read,credentials:statusandkeys:manage(Credential status). - KMS configurations (
https://eudiplo.dev/schemas/v2/KmsConfigFile.schema.json) acceptalgorithmsanddefaultAlgorithmon providers (Signing algorithms). - Registrar configurations (
registrar.json,RegistrarConfigdocuments) are skipped with the warningREGISTRAR_CONFIG_REMOVED(above). - Tenants have format v4 (
https://eudiplo.dev/schemas/v4/TenantConfigFile.schema.json), which adds no field to 9.x files. The new filekey-chain-defaults.json(https://eudiplo.dev/schemas/v1/KeyChainDefaultsConfigFile.schema.json, resourceKeyChainDefaults/defaults) holds the tenant's key chain per usage type; itsaccessentry is the default access key chain. Format v2 (https://eudiplo.dev/schemas/v2/KeyChainDefaultsConfigFile.schema.json) adds theauthorizationServerentry (Authorization server key chain). - Issuance configurations (
https://eudiplo.dev/schemas/v4/IssuanceConfigFile.schema.json) acceptwalletAttestationStatusCheckModeon the configuration and its authorization servers (Wallet and key attestation). A v3 file is a valid v4 file. Format v5 (https://eudiplo.dev/schemas/v5/IssuanceConfigFile.schema.json) adds the entity configuration fields offederation(OpenID Federation) and requiresfederation.entityIdto be a URL (below); any other v4 file is a valid v5 file. Format v6 (https://eudiplo.dev/schemas/v6/IssuanceConfigFile.schema.json) removes the top-levelsigningKeyId: the upgrade drops a set value with the warningISSUANCE_SIGNING_KEY_ID_REMOVEDand warns about everytoken.signingKeyIdwithAUTHORIZATION_SERVER_KEY_CHAIN_REQUIRED(below). Format v7 (https://eudiplo.dev/schemas/v7/IssuanceConfigFile.schema.json) removesregistrationCertificate.modeand.renewal(above).
10.0 imports files of older format versions and upgrades them unchanged, except trust list files, which it refuses (below); key chain files without type are imported as in 9.x. These files change: issuance configurations lose a top-level signingKeyId with the warning ISSUANCE_SIGNING_KEY_ID_REMOVED and registrationCertificate.mode and .renewal (ISSUER_REGISTRATION_CERTIFICATE_JWT_DROPPED for a jwt that generate mode did not serve, ISSUER_REGISTRATION_CERTIFICATE_NOT_GENERATED for a certificate that was generated), presentation configurations lose the registrar fields of registration_cert (REGISTRATION_CERT_FIELD_REMOVED, REGISTRATION_CERT_PURPOSE_INCOMPLETE, REGISTRATION_CERT_NOT_REQUESTED), registrar.json is left out (REGISTRAR_CONFIG_REMOVED), Tenant v2 and v3 files, which development builds of 10.0 wrote, lose their defaultAccessKeyChainId or defaultKeyChains with the warning DEFAULT_KEY_CHAINS_MOVED (set the value in key-chain-defaults.json instead), and credential configurations lose every key in constraints that v3 does not accept, each with the warning CLAIM_CONSTRAINT_KEYWORD_REMOVED at its path, and every display color wallets cannot read, with the warning DISPLAY_COLOR_REMOVED; a credential configuration with a claim pattern RE2 cannot run (CLAIM_PATTERN_UNSUPPORTED) or with two display entries for one locale (DISPLAY_LOCALE_DUPLICATE) is not upgraded. Trust lists are not upgraded at all: v1 has no website field, which v2 requires, so every trust list file needs one written by hand. Files and bundles exported from 10.0, including key chain exports, cannot be imported into 9.x.
Do:
-
Update the CLI you use for
eudiplo config validate,config upgradeandconfig editor setup, for example in CI, to 10.x; a 9.x CLI rejects v2 files and v4 issuance configurations. A 10.x CLI'sinit,demoandconfig tenant createwriteconfig/kms.jsonand tenant files at these versions, so run them with an image of the CLI's version or newer. -
Rewrite configuration folders kept in Git once; otherwise
eudiplo config upgrade --checkreports every credential configuration below v4, every tenant (info.json) and key chain below v4, every client and KMS configuration below v2, every presentation configuration below v5, every issuance configuration below v7 and every trust list below v2 asupgrade required, andregistrar.jsonfiles with a warning;--checkkeeps exiting1until you delete them:eudiplo config upgrade ./config --dry-run # show the changeseudiplo config upgrade ./config --output ./config-v10 # then replace ./config with itconfig upgradestops at every v1 trust list file withTRUST_LIST_WEBSITE_MISSING; rewrite those files by hand first (Trust lists: v1 files must be rewritten). -
If a 9.x export contains a credential configuration with an
x509trusted authority, export it again after the upgrade, or set its$schemato the v2 URL; as a v1 file it still fails validation. -
Before you import a 9.x export of an internal or external CA chain without rotation, export it again after the upgrade, or add
"type": "internalChain"and, in a v1 document, set$schemato the v2 URL. Withouttype, its root CA key becomes the signing key. Add the field to such files inCONFIG_FOLDER/<tenant>/key-chains/before you start 10.0; in a bundle,eudiplo config plan --difflists such a document with a/spec/typechange frominternalChaintostandalonewhen the stored key chain is an internal chain. A key chain that was already imported that way has the root CA certificate as its active certificate (GET /api/key-chain/{id}, norootCertificate); import the 9.x export again with"type": "internalChain"to restore it. -
eudiplo config upgradedrops unsupportedconstraintskeys from v1 and v2 credential configurations. A v3 file with such keys fails validation; remove them, asCLAIM_CONSTRAINT_KEYWORD_REMOVEDwarnings or the validation errors list them. Exports from 10.0 leave them out. -
Keep a 9.x export from before the upgrade if you might need to restore 9.x.
See Config bundle format.
Issuance configuration: token.signingKeyId names an authorization server key chain
Changed: a bundle or config folder whose issuance configuration sets a token.signingKeyId that names no key chain with usage type authorizationServer is blocked with KEY_CHAIN_USAGE_MISMATCH (or MISSING_RESOURCE_REFERENCE), and a startup import then skips the tenant and logs the issue. A value the stored issuance configuration already has gets the same code as a warning, so an unchanged folder still imports; that authorization server's token requests fail until the value is fixed (Access tokens). eudiplo config upgrade reports such values with the warning AUTHORIZATION_SERVER_KEY_CHAIN_REQUIRED and drops a top-level signingKeyId with ISSUANCE_SIGNING_KEY_ID_REMOVED.
Do: before the first start of 10.0, remove token.signingKeyId from issuance/issuance.json, or point it to a key chain file with "usageType": "authorizationServer".
Trust lists: the key chain of a changed list must have usage type trustList
Changed: a bundle or config folder whose trust-lists/<id>.json would change a list while its key chain, in keyChainId or the one the stored list is signed with, has no usage type trustList is blocked with KEY_CHAIN_USAGE_MISMATCH, and a startup import then skips the tenant and logs the issue. A file that leaves the list unchanged still imports (Trust lists).
Do: before the first start of 10.0, set keyChainId in each such file to a key chain with "usageType": "trustList".
Trust lists: imports check the usage types of entity key chains
Changed: a bundle or config folder with a trust list whose internal entity names a key chain of another usage type (above) is blocked with KEY_CHAIN_USAGE_MISMATCH at /spec/entities/<index>/issuerKeyChainId or /spec/entities/<index>/revocationKeyChainId, and a startup import then skips the tenant and logs the issue. A key chain that the stored list already names in that field gets the same code as a warning, so an unchanged folder still imports into an instance that has the list; so does a list the import skips, for example a detached one. A bundle exported from an instance whose list keeps such a value is blocked on an instance without that list.
Do: before the first start of 10.0 on a new database, fix such entities in trust-lists/*.json; fix them in folders for existing instances as well.
Presentation configurations: transaction data must reference an SD-JWT VC query
Changed: a bundle or config folder with a presentation configuration whose transaction_data entry has empty credential_ids, names an ID that is not a query of its DCQL query, or names an mso_mdoc query is blocked with TRANSACTION_DATA_UNCHECKABLE at /spec/transaction_data, and a startup import then skips the tenant and logs the issue (Transaction data). 9.x imported such a file.
Do: before the first start of 10.0, fix such entries in presentation/*.json.
Issuance configuration: federation.entityId must be an https URL
Changed: federation.entityId is the entity identifier of the tenant in an OpenID Federation and, from 10.0, also iss and sub of its published entity configuration and the openid_federation: client identifier. When set, it must be an https URL with a host and without query, fragment, credentials or whitespace (OpenID Federation 1.0 Section 1.2); http is accepted only with OUTBOUND_URL_ALLOW_HTTP=true. An empty value still means "not set". 9.x accepted any string. An issuance.json with another value fails its import on every start. A configuration bundle or document with one fails its plan, except an http value without OUTBOUND_URL_ALLOW_HTTP=true, which passes the plan and fails when it is applied. eudiplo config upgrade stops with the required input FEDERATION_ENTITY_ID_INVALID and writes nothing until the value is fixed; eudiplo config validate gives a v4 document the full check except OUTBOUND_URL_ALLOW_HTTP; for issuance.json files and v5 documents it only rejects values that are no http(s) URL or have a query, fragment or whitespace. A value stored by 9.x stays in the database until federation.entityId is replaced; a save that sends it back, as the Web Client does, answers 400. Meanwhile issuer metadata keeps using it, federation SD-JWT VCs fall back to x5c, the entity configuration endpoint answers 404 and openid_federation presentation requests answer 400.
Do: set federation.entityId to <PUBLIC_URL>/issuers/<tenant>, the URL your entity is registered under with its trust anchor, in issuance.json, bundles and stored configurations (Issuer Settings in the Web Client).
Clients: another secret ends the client's tokens
Changed: a Client document or a file in CONFIG_FOLDER/<tenant>/clients/ that gives an existing client another secret, or !generate in a bundle, ends the tokens issued with the old secret (Deleting a client or changing its secret ends its access). A client file without secret gets a new random secret at every start in upsert or replace mode, so its tokens now end at every restart; 9.x kept them for up to 24 hours. The same secret as stored keeps the tokens.
Do: set secret in every client file that an integration uses with CONFIG_IMPORT_MODE=upsert or replace.
Key chains: imports remove an omitted description and rotation settings
Changed: a KeyChain document replaces the stored key chain, and the plan already listed a description it left out as removed, but with a private-jwk or external-reference key source 9.x kept the stored description. In upsert and replace mode, 10.0 removes an omitted description, as the plan lists. The plan now also lists the rotation policy as the import stores it: without rotationPolicy rotation is disabled, null in intervalDays or certValidityDays means the same as leaving it out, and a private key without activeJwk gets the import defaults of 90 and 365 days when rotation is enabled. A key chain of an external KMS exported without rotation interval therefore plans as unchanged instead of update. 10.0 exports leave unset rotation values out instead of writing null.
A key chain whose document has not changed since it was last applied keeps its stored description and rotation settings until the document changes (Key chains: an unchanged document is not applied again).
Do: add description to every key chain in a bundle or in CONFIG_FOLDER/<tenant>/key-chains/ that should keep it. Details: Config bundle format.
Key chains: an unchanged document is not applied again
Changed: in upsert and replace mode, 9.x planned a key chain with a private key or regenerate as update on every import, because the stored keys never equal the document, and applied it again: a CA key got a new signing key, a rotation since the import was undone, regenerate created new key material, and certificates EUDIPLO creates during an import were issued again. With CONFIG_IMPORT_MODE=upsert or replace, this happened at every startup. In 10.0, a KeyChain document that is identical to the one last applied from the same source plans unchanged while the key chain is file-managed, also when 9.x applied it and also after you replaced the file with the output of eudiplo config upgrade, and the key chain stays as it is. A changed document is compared and applied as before, and reattaching always applies the folder version. So certificates EUDIPLO created during the import are no longer renewed at each start, for example the self-signed certificate of a key without crt (valid 365 days), the signing certificate of a CA key and the certificate of a regenerate key chain (valid certValidityDays). A changed PUBLIC_URL or tenant name reaches them only at the next rotation or re-import.
Do:
- Renew every certificate EUDIPLO created during an import before it expires. For a key chain with rotation, set an
intervalDaysbelow itscertValidityDays; the demo configuration now rotates its attestation and status list keys every 20 days. For aprivate-jwkkey withoutcrtand without rotation, raisemetadata.generationto get a new self-signed certificate for the same key, or supply your owncrt; enabling rotation there would make the key the CA of a new signing key (key chain types).POST /api/key-chain/{id}/rotaterenews a certificate with a new key. - To apply an unchanged key chain document again, for example a bundle with
regeneratethat you import to create new key material, raisemetadata.generationin the document; in a bundle, also update the document'ssha256inmanifest.json. Details: Config bundle format.
Key chains: bundles leave out the encryption key chain
Changed: 9.x exports contained the tenant's encryption key chain as a KeyChain document with usageType: "encrypt" and the requirement PRIVATE_KEY_REQUIRED; supplying a key or regenerate replaced the tenant's decryption key. 10.0 exports leave it out, and imports neither change nor delete it. A plan skips a KeyChain document with the ID of the tenant's encryption key chain and warns with KEY_CHAIN_ID_RESERVED, in every mode and in the startup import of CONFIG_FOLDER/<tenant>/key-chains/.
Do: nothing for a 9.x export imported into the tenant it came from. Before you import it into another tenant, remove that document: there it would ask for a private key and create a key chain that EUDIPLO never uses. The same applies to 10.0 exports of a tenant whose encryption key chain a 9.x import replaced (see the encryption key chain section under Integrators): they still contain it. Details: Config bundle format.
Clients: an unchanged !generate document keeps its secret
Changed: in upsert and replace mode, 9.x planned a Client document with "secret": "!generate" as update on every import and gave the client a new secret each time, returned in generatedSecrets; a startup import with CONFIG_IMPORT_MODE=upsert or replace did so at every start without showing it, so the client could no longer authenticate after a restart. In 10.0, such a document that is identical to the one last applied from the same source plans unchanged while the client is file-managed, also when 9.x applied it and also after you replaced the file with the output of eudiplo config upgrade, and the client keeps its secret. With Keycloak (OIDC set and OIDC_PROVIDER unset or keycloak), such a client is still applied on every import, which undoes changes made in Keycloak, but it keeps its secret. A changed document, another source or reattaching generates a new secret as before.
Do: to get a new secret from an unchanged document, raise metadata.generation; in a bundle, also update the document's sha256 in manifest.json. A startup import still does not show the secret it generates; it logs a warning naming the client. To get the secret of such a client, apply it with Apply from file under Settings > Config Portability or reattach it (clients with generated secrets). Details: Config bundle format.
Credential configurations: display colors and one entry per locale
Changed: a credential configuration file of format v3 or older, in issuance/credentials/*.json or in a bundle or document, is upgraded on import. Display colors are trimmed and their function names lowercased; a color that still is not a CSS Color Level 3 numerical value (see under Integrators) is removed with the warning DISPLAY_COLOR_REMOVED, so wallets use their own color, and an empty one is removed without a warning. A second display entry for one locale stops the upgrade with the required input DISPLAY_LOCALE_DUPLICATE and fails the import plan, so no configuration file of that tenant is applied on any start until the file is fixed. eudiplo config upgrade reports both the same way. eudiplo config validate refuses a repeated locale in every credential configuration file. It refuses such colors in v4 files and in files without $schema, which it checks as the current format; in v1 to v3 files it accepts them, because the upgrade removes them, and the import reads a file without $schema as v1. A 10.0 export of a configuration stored by 9.x leaves out such colors and repeated locales, as the issuer metadata does, so it imports again.
Do: before upgrading, replace or remove such colors and keep one display entry per locale in your configuration files and exports.
Credential configurations: claim patterns must suit RE2
Changed: a credential configuration in issuance/credentials/*.json or in a bundle or document whose claim pattern RE2 cannot run (see under Integrators) fails its import plan, so no configuration file of that tenant is applied on any start until the file is fixed. eudiplo config upgrade stops at such a pattern in a v1 or v2 file with the required input CLAIM_PATTERN_UNSUPPORTED at its path and writes nothing until it is rewritten; eudiplo config validate reports it the same way for v1 and v2 documents, but does not check patterns in v3 and v4 files or files without $schema. A 10.0 export of a configuration stored by 9.x keeps such a pattern, so importing it again is blocked as well.
Do: before upgrading, rewrite such patterns in your configuration files and exports.
Trust lists: v1 files must be rewritten
Changed: a trust list file of format v1, in trust-lists/*.json or in a bundle or document, is no longer imported: v2 requires an e-mail address (info.contactUri) and a web site (info.website) for every entity (under Integrators), and v1 has no website field. The upgrade to v2 stops with the required input TRUST_LIST_WEBSITE_MISSING at /spec/entities/<index>/info/website for each entity and fails the import plan, so no configuration file of that tenant is applied on any start until the file is rewritten; reattaching a trust list of that tenant answers 400 CONFIG_FOLDER_INVALID with the file and these issues, while resources of other kinds reattach (reattach). It names the other values to fix as well: a missing contactUri (TRUST_LIST_CONTACT_URI_MISSING) or one that is no e-mail address (TRUST_LIST_CONTACT_URI_INVALID), and entity info that does not fit ETSI TS 119 602 (under Integrators), such as Germany or en_US, or a uri that is no absolute URI (TRUST_LIST_COUNTRY_INVALID, TRUST_LIST_LANGUAGE_INVALID, TRUST_LIST_URI_INVALID). A country or lang that differs only in letter case, and GB or GR, get the same codes, with the value to write in the message, for example UK for gb. 9.x planned a file with such entity info as applicable and failed while applying it with 500 CONFIG_APPLY_FAILED. eudiplo config upgrade and eudiplo config validate report these issues the same way for v1 files; eudiplo config validate also refuses such values, and a missing contactUri or website, in v2 files and in files without $schema, which it checks as the current format.
Do: before upgrading, rewrite each trust list file as v2: set $schema to https://eudiplo.dev/schemas/v2/TrustListConfigFile.schema.json, add contactUri and website to every entity's info, write country as a code such as DE (UK and EL for the United Kingdom and Greece) and lang as a lower-case tag such as en. 9.x cannot import the rewritten files, so do it together with the upgrade.