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

Author: woutslakhorst

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::

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.

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.
+