Add VDR API version usage with regards to DID methods to docs (#3400)

nuts-foundation · Sep 23, 2024 · 6a03263 · 6a03263
1 parent 7460f4a
commit 6a03263
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 1 deletion.
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,6 +13,7 @@ Nuts documentation
     pages/integrating/api-authentication.rst
     pages/integrating/vc.rst
     pages/integrating/supported-protocols-formats.rst
+    pages/integrating/version-incompatibilities.rst
     pages/release_notes.rst
 
 .. toctree::

diff --git a/docs/pages/deployment/security-considerations.rst b/docs/pages/deployment/security-considerations.rst
@@ -45,4 +45,15 @@ Key rotation
 ************
 
 It's important to have a key rotation policy in place. The Nuts node uses keys for various signing operations.
-These operations are numerous and therefore keys should be rotated regularly.
+These operations are numerous and therefore keys should be rotated regularly.
+
+Using did:web
+*************
+
+The ``did:web`` method allows for easier integration with existing web infrastructure. However, it's also less secure and vulnerable to domain takeover.
+When using ``did:web``, you should consider the following:
+
+- Protect your domain from takeover. Make sure it's locked for a year after cancelling the domain.
+- Monitor calls to ``**/did.json`` on the domain and make sure they are handled by the Nuts Node.
+- Using Hashicorp Vault or Microsoft Azure Key Vault to store the private keys is even more important when using ``did:web``.
+- Use DNS over HTTPS and enable DNSSEC.
diff --git a/docs/pages/integrating/version-incompatibilities.rst b/docs/pages/integrating/version-incompatibilities.rst
@@ -0,0 +1,19 @@
+.. _version-incompatibilities:
+
+Version Incompatibilities
+#########################
+
+V5/V6, DID methods and API versions
+***********************************
+
+V6 introduced the support for multiple DID methods. To enable this, a new version of the VDR API has been added.
+There's also a config parameter that allows you to limit the DID methods in use.
+Not all combinations of API usage and DID methods are supported.
+There are basically two options.
+
+1. Keep using the VDR V1 API (for now) and set ``vdr.did_methods`` to ``["nuts"]``.
+2. Use the VDR V2 API and set ``vdr.did_methods`` to include other methods or leave blank for default setting.
+
+Do not use the VDR V1 and VDR V2 API at the same time. This will lead to unexpected behavior.
+Once you use the VDR V2 API, you cannot go back to the VDR V1 API. The VDR V1 API has also been marked as deprecated.
+