diff --git a/docs/pages/deployment/certificates.rst b/docs/pages/deployment/certificates.rst index f4fe280f1..18dd776cd 100644 --- a/docs/pages/deployment/certificates.rst +++ b/docs/pages/deployment/certificates.rst @@ -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 `_ and `X509Credential with UZI server certificates `_. + 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 ` and :ref:`Policy ` definition file. +Trust in specific certificate CAs is configured per use-case in a :ref:`Discovery ` and :ref:`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``.