X509: discuss new setURLFetchCallback method

Author: terrafrost

docs/x509.md

@@ -122,6 +122,28 @@ echo $x509->validateSignature() ? 'valid' : 'invalid';
 
 Certificate authority certificates can be downloaded from [curl - SSL CA Certificates](https://curl.haxx.se/docs/caextract.html). Parsing that is left as an exercise to the reader.
 
+Note that when the certificate being validated is issued by a CA that isn't already in your trust store, phpseclib will, by default, read any caIssuers URL from the certificate's Authority Information Access (AIA) extension and connect to it to try to download the missing intermediate. Because that URL comes from the certificate itself, a maliciously crafted certificate can point it at an address on the host's own network (eg. loopback, a cloud metadata endpoint such as 169.254.169.254, an internal-only service, etc) turning validation into a [server-side request forgery](https://en.wikipedia.org/wiki/Server-side_request_forgery) vector.
+
+You can disable this behavior entirely with `X509::disableURLFetch()`. As of 3.0.54 you can instead keep fetching enabled but restrict where phpseclib will connect, by registering a callback that approves or rejects each destination:
+
+```php
+X509::setURLFetchCallback(function (string $host, string $ip, int $port, string $scheme): bool {
+    if ($scheme !== 'http' && $scheme !== 'https') {
+        return false;
+    }
+
+    $public = filter_var(
+        $ip,
+        FILTER_VALIDATE_IP,
+        FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE
+    );
+
+    return $public !== false; // public address -> allow; internal/reserved -> deny
+});
+```
+
+The callback receives the resolved IP, host, port, and scheme, and returns true to allow the connection or false to block it. The example above permits only publicly-routable addresses. If instead you run an internal CA (eg. its AIA endpoint lives on 10.x.x.x) you'd invert the logic and allow only your specific internal range.
+
 ### Self-signed Signatures
 
 ```php
@@ -423,4 +445,4 @@ $result = $x509->sign($issuer, $subject);
 #-----[ BEFORE, ADD ]-----------------------------------
 #
 $x509->setExtensionValue($customExtensionName, $customExtensionData);
-```
+```