Skip to content

docs: describe did:x509 validation, link the wiki for certificate use in use cases #4680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
reinkrul wants to merge 2 commits into from
Open

docs: describe did:x509 validation, link the wiki for certificate use in use cases #4680

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
46a7039
docs: move did:x509 background to the wiki
reinkrul Nov 5, 2026
3a1551f
docs: keep the did:x509 explanation and describe how the node validat…
reinkrul Nov 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion docs/pages/deployment/certificates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,23 @@ With other DID Methods, certificates are only used to create an secure channel f
In ``did:x509`` the certificates are also used in the cryptographic proofs to obtain access-tokens.
This means the certificate chain now provides the root of trust and has stricter requirements than connection certificates.

The Nuts node resolves ``did:x509`` DIDs but doesn't create them.
When resolving, the Nuts node:

- takes the certificate chain from the ``x5c`` header of the credential's JWT and validates it using only the certificates in that chain;
- checks that the CA fingerprint in the DID matches a CA certificate (root or intermediate) in that chain;
- checks that the other fields in the DID (e.g. ``san`` or ``subject``) match the leaf certificate.

It does not use the TLS trust store (``tls.truststorefile``) or the operating system's CA bundle for this.

How use cases use certificates this way is described on the wiki:
`UZI certificates as a source of identity <https://wiki.nuts.nl/link/111>`_ and `X509Credential with UZI server certificates <https://wiki.nuts.nl/link/124>`_.

Certificates and CRLs in the chain may be signed with RSA (PKCS #1 v1.5 or RSASSA-PSS, with SHA-256, SHA-384 or SHA-512), ECDSA or Ed25519.
This includes the PKIoverheid G4 profile used for UZI server certificates issued from 12 November 2026: RSA 4096 keys with RSASSA-PSS/SHA-512 signatures.

Trust in specific certificate CAs is configured per use-case in a :ref:`Discovery <discovery>` and :ref:`Policy <policy>` definition file.
Trust in specific certificate CAs is configured per use-case in a :ref:`Discovery <discovery>` and :ref:`Policy <policy>` definition file:
their presentation definitions only accept ``did:x509`` DIDs with a specific CA fingerprint.
CRLs from trusted chains (per the above definition files) are consulted when evaluating ``did:x509`` Verifiable Credentials.
For certificate chains used in ``did:x509`` the Nuts-node always uses a hard-fail strategy, i.e., the ``pki.softfail`` config value is ignored during certificate validation for ``did:x509``.
This means that the Nuts-node will not be able to verify a ``did:x509`` DID or Verifiable Credential signed by this DID Method if the CRL cannot be downloaded and the CRL in the cache is older than ``pki.maxupdatefailhours``.
Loading