diff --git a/docs/index.rst b/docs/index.rst index 7e8f86468..bcef238e6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,6 +31,7 @@ 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 @@ -38,7 +39,7 @@ Nuts documentation 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 diff --git a/docs/pages/deployment/certificates.rst b/docs/pages/deployment/certificates.rst new file mode 100644 index 000000000..91e537656 --- /dev/null +++ b/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 ` and :ref:`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. \ No newline at end of file diff --git a/docs/pages/deployment/pex.rst b/docs/pages/deployment/policy.rst similarity index 96% rename from docs/pages/deployment/pex.rst rename to docs/pages/deployment/policy.rst index 4efa271d5..d2abaa117 100644 --- a/docs/pages/deployment/pex.rst +++ b/docs/pages/deployment/policy.rst @@ -1,11 +1,14 @@ -.. _pex: +.. _policy: + +Access Token Policy +################### Presentation Definition mapping -############################### +******************************* Wallet functionality uses `Presentation Definitions `_ 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