xff: add support for configuring a list of trusted CIDRs (#31831)

Commit Message: xff: add support for configuring a list of trusted CIDRs

The original client IP address can be determined from the
x-forwarded-for header either by a fixed number of trusted hops, or by
evaluating the client IP address against a list of trusted addresses.

This adds support for configuring a list of CIDRs in the xff original IP
detection extension. The remote IP address is evaluated against these,
and optionally recurses through XFF to find the last non-trusted
address.

Additional Description:
This feature is generally used by people with a CDN in front of their
edge proxy to ensure that XFF is only parsed when the remote connection
comes from a CDN server.

The behaviour of the new functionality should be the same as Nginx's
`realip` module.

Disclaimer: This is my first time writing C++ so I'm not certain my
changes are completely idiomatic, but I've tried to stick with existing
style in the codebase. Feedback very welcome!

Risk Level: Medium
Testing: Unit tests, manual tests
Docs Changes: Updates to HTTP Connection Manager header manipulation
docs, and proto docs.
Release Notes: Added to changelogs/current.yaml
Platform Specific Features: None
Fixes #21639
Relates to #31296

---------

Signed-off-by: James O'Gorman <james@netinertia.co.uk>

Mirrored from https://github.com/envoyproxy/envoy @ fbc6ee2ed5b858c842999c688504fd133008868a

envoy/extensions/http/original_ip_detection/xff/v3/BUILD

@@ -5,5 +5,8 @@ load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
 licenses(["notice"])  # Apache 2
 
 api_proto_package(
-    deps = ["@com_github_cncf_xds//udpa/annotations:pkg"],
+    deps = [
+        "//envoy/config/core/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+    ],
 )

envoy/extensions/http/original_ip_detection/xff/v3/xff.proto

@@ -2,6 +2,10 @@ syntax = "proto3";
 
 package envoy.extensions.http.original_ip_detection.xff.v3;
 
+import "envoy/config/core/v3/address.proto";
+
+import "google/protobuf/wrappers.proto";
+
 import "udpa/annotations/status.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.http.original_ip_detection.xff.v3";
@@ -22,5 +26,45 @@ message XffConfig {
   // determining the origin client's IP address. The default is zero if this option
   // is not specified. See the documentation for
   // :ref:`config_http_conn_man_headers_x-forwarded-for` for more information.
+  //
+  // Only one of ``xff_num_trusted_hops`` and ``xff_trusted_cidrs`` can be set.
   uint32 xff_num_trusted_hops = 1;
+
+  // The `CIDR <https://tools.ietf.org/html/rfc4632>`_ ranges to trust when
+  // evaluating the remote IP address to determine the original client's IP address.
+  // This is used instead of
+  // :ref:`use_remote_address <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`.
+  // When the remote IP address matches a trusted CIDR and the
+  // :ref:`config_http_conn_man_headers_x-forwarded-for` header was sent, each entry
+  // in the ``x-forwarded-for`` header is evaluated from right to left and the first
+  // public non-trusted address is used as the original client address. If all
+  // addresses in ``x-forwarded-for`` are within the trusted list, the first (leftmost)
+  // entry is used.
+  //
+  // This is typically used when requests are proxied by a
+  // `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_.
+  //
+  // Only one of ``xff_num_trusted_hops`` and ``xff_trusted_cidrs`` can be set.
+  XffTrustedCidrs xff_trusted_cidrs = 2;
+
+  // If set, Envoy will not append the remote address to the
+  // :ref:`config_http_conn_man_headers_x-forwarded-for` HTTP header.
+  //
+  // .. attention::
+  //
+  //   For proper proxy behaviour it is not recommended to set this option.
+  //   For backwards compatibility, if this option is unset it defaults to true.
+  //
+  // This only applies when :ref:`use_remote_address
+  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`
+  // is false, otherwise :ref:`skip_xff_append
+  // <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.skip_xff_append>`
+  // applies.
+  google.protobuf.BoolValue skip_xff_append = 3;
+}
+
+message XffTrustedCidrs {
+  // The list of `CIDRs <https://tools.ietf.org/html/rfc4632>`_ from which remote
+  // connections are considered trusted.
+  repeated config.core.v3.CidrRange cidrs = 1;
 }