pr feedback

docs/index.rst

@@ -31,14 +31,15 @@ Nuts documentation
     pages/deployment/configuration.rst
     pages/deployment/migration.rst
     pages/deployment/recommended-deployment.rst
+    pages/deployment/certificates.rst
     pages/deployment/docker.rst
     pages/deployment/storage.rst
     pages/deployment/verifiable-credentials.rst
     pages/deployment/logging.rst
     pages/deployment/monitoring.rst
     pages/deployment/cli-reference.rst
     pages/deployment/discovery.rst
-    pages/deployment/pex.rst
+    pages/deployment/policy.rst
     pages/deployment/key-rotation.rst
     pages/deployment/audit-logging.rst
     pages/deployment/oauth.rst

docs/pages/deployment/certificates.rst

@@ -0,0 +1,34 @@
+.. _certificates:
+
+Certificates
+############
+
+client authentication
+*********************
+
+Nuts-node versions before v6 only use TLS certificates for client authentication on the ``/n2n`` endpoints and in the ``gRPC Nuts network``.
+The Nuts-node also validates the client certificates used by its peers on the ``gRPC network`` when a new connection is established, and periodically after that as long as the connection exists.
+To do this, all trusted certificate chains must be configured in ``tls.truststorefile``.
+The Certificate Revocation List (CRL) of the CAs in the truststore are periodically downloaded to confirm a peer's client certificate is not revoked.
+To prevent a CA with downtime on its CRL endpoint from bringing down the network, the Nuts-node uses a soft-fail strategy that does not reject certificates if it cannot download the CRL.
+This behavior can be changed to hard-fail (fail if certificate is invalid, expired, of revoked, or if any of the previous cannot be determined) using the ``pki.softfail`` config flag.
+The ``gRPC Nuts network`` and ``/n2n`` endpoints are deprecated and will be removed in the future.
+
+did:x509
+********
+
+In ``did:x509`` a certificate is converted to a DID Document (that includes its entire certificate chain) so it can be used in the Verifiable Credentials ecosystem.
+This DID Method provides a temporary bridge between the 'old' world of CAs/Certificates and the 'new' Verifiable Credential world.
+With other DID Methods, certificates are only used to create an secure channel for communication and optionally for client authentication.
+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.
+
+Trust in specific certificate CAs is configured per use-case in a :ref:`Discovery <discovery>` and :ref:`Policy <policy>` definition file.
+In addition, all trusted CA chains must also be added to the ``tls.truststorefile``.
+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``.
+
+.. note::
+
+    Since the configured truststore file is now used for multiple purposes, it is no longer possible for the Nuts-node to determine what certificate chain is accepted/trusted for what purpose.
+    This means that all incoming TLS connections (including gRPC) must be offloaded in a proxy and validated against the expected certificate chain.

docs/pages/deployment/pex.rst → docs/pages/deployment/policy.rst

@@ -1,11 +1,14 @@
-.. _pex:
+.. _policy:
+
+Access Token Policy
+###################
 
 Presentation Definition mapping
-###############################
+*******************************
 
 Wallet functionality uses `Presentation Definitions <https://identity.foundation/presentation-exchange/>`_ to determine the required credentials for a given presentation request.
 An OAuth2 authorization request uses scopes to determine the required permissions for a given request.
-The mapping between scopes and presentation definitions is defined in a configuration file.
+The mapping between scopes and presentation definitions is defined in a policy definition file.
 
 Configuration
 *************
@@ -14,7 +17,7 @@ The Nuts config supports the mapping between OAuth2 scopes and presentation defi
 The file-based configuration is a simple way to define the mapping between scopes and presentation definitions.
 It can be used for simple use cases where the mapping is static and does not change often.
 
-To use file-based configuration, you need to define the path to a directory that contains policy configuration files:
+To use file-based configuration, you need to define the path to a directory that contains policy definition files:
 
 .. code-block:: yaml