From fa9672f7a582d595ac82de4ac745551e93e7041d Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Thu, 27 Oct 2022 18:34:25 +0200
Subject: [PATCH] Document remote host validation for app devs

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 developer_manual/digging_deeper/security.rst | 29 ++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/developer_manual/digging_deeper/security.rst b/developer_manual/digging_deeper/security.rst
index 4ff169715..7c78ce72b 100644
--- a/developer_manual/digging_deeper/security.rst
+++ b/developer_manual/digging_deeper/security.rst
@@ -4,6 +4,35 @@
 Security
 ========
 
+Remote Host Validation
+----------------------
+
+Nextcloud can help validating a remote host so that no internal infrastructure is contacted by user-provided host names or IPs. The validator ``\OCP\Security\IRemoteHostValidator`` can be :ref:`injected<dependency-injection>` into any app class:
+
+.. code-block:: php
+
+    <?php
+
+    use OCP\Security\IRemoteHostValidator;
+
+    class MyRemoteServerIntegration {
+        private IRemoteHostValidator $hostValidator;
+
+        public function __construct(IRemoteHostValidator $hostValidator) {
+            $this->hostValidator = $hostValidator;
+        }
+
+        public function contactRemoteServer(string $hostname): void {
+            if (!$this->hostValidator->isValid($hostname)) {
+                // ABORT
+            }
+
+            // Contact the server
+        }
+    }
+
+.. note:: Nextcloud's HTTP clients obtained from ``\OCP\Http\Client\IClientService`` have this validation built in so you don't have to check hosts of HTTP requests as long as you use this provided abstraction.
+
 Trusted domain
 ----------------