RFC0055 Identity-Aware Routing

.gitignore

@@ -34,3 +34,8 @@ tags
 src/golang.org/x/tools/
 src/github.com/kisielk/
 src/golang.org/x/sync/
+
+# Devbox local development environment
+devbox.json
+devbox.lock
+.devbox/

jobs/gorouter/spec

@@ -160,6 +160,8 @@ properties:
       none - Gorouter will not request client certificates in TLS handshakes, and will ignore them if presented. Incompatible with `forwarded_client_cert: forward` or `sanitize_set`.
       request - Gorouter will request client certificates in TLS handshakes, and will validate them when presented, but will not require them.
       require - Gorouter will fail a TLS handshake if the client does not provide a certificate signed by a CA it trusts. Select this option if your load balancer terminates TLS and does not require client certificates, and the load balancer provides a compatible client certificate of its own to Gorouter in an independent TLS handshake. This option may also be selected for Isolation Segments when Gorouter is the first point of TLS termination. Many clients of CF platform APIs do not present client certificates in TLS handshakes, so the first point of TLS termination for requests to the system domain must not require them. This option has no effect on the HTTP listener; to disable HTTP support set `disable_http: true`.
+
+      Note: This property applies to the default TLS listener. Domains configured in `router.domains` enforce their own mTLS requirement independently — client certificates are always required for those domains regardless of this setting.
     default: request
   router.disable_http:
     description: Disables the http listener on port specified by router.port. This cannot be set to true if enable_ssl is false.
@@ -200,6 +202,33 @@ properties:
   router.only_trust_client_ca_certs:
     description: "When router.only_trust_client_ca_certs is true, router.client_ca_certs are the only trusted CA certs for client requests. When router.only_trust_client_ca_certs is false, router.client_ca_certs are trusted in addition to router.ca_certs and the CA certificates installed on the filesystem. This will have no affect if the `router.client_cert_validation` property is set to none."
     default: false
+  router.domains:
+    description: |
+      Array of domains requiring mutual TLS authentication. Each domain can have its own CA certificate pool, forwarded_client_cert mode, and xfcc_format.
+      For non-wildcard domains, the domain must match the request host exactly.
+      For wildcard domains (e.g., *.apps.identity), the wildcard must be the leftmost label and matches any single label.
+
+      These domains enforce client certificate validation independently of `router.client_cert_validation` — clients connecting to these domains are always required to present a valid certificate signed by the domain's configured CA.
+
+      xfcc_format controls the format of the X-Forwarded-Client-Cert header:
+      - "raw" (default): Full base64-encoded certificate (~1.5KB)
+      - "envoy": Compact Hash=<sha256>;Subject="<DN>" format (~300 bytes)
+    default: []
+    example:
+    - name: "*.apps.identity"
+      ca_certs: |
+        -----BEGIN CERTIFICATE-----
+        <CA certificate for apps.identity domain>
+        -----END CERTIFICATE-----
+      forwarded_client_cert: sanitize_set
+      xfcc_format: envoy
+    - name: "secure.example.com"
+      ca_certs: |
+        -----BEGIN CERTIFICATE-----
+        <CA certificate for secure.example.com>
+        -----END CERTIFICATE-----
+      forwarded_client_cert: forward
+      xfcc_format: raw
   router.backends.max_attempts:
     description: |
       Maximum number of attempts on failing requests against backend routes.
@@ -339,7 +368,7 @@ properties:
       this property and operators have to explicitly enable them. This is done to prevent breaking
       log parsing in existing setups by the introduction of new fields. Does not affect stdout /
       stderr logs.
-      Available fields are: backend_time, dial_time, dns_time, failed_attempts, failed_attempts_time, local_address, tls_time
+      Available fields are: backend_time, caller_cf_app, caller_cf_org, caller_cf_space, dial_time, dns_time, failed_attempts, failed_attempts_time, local_address, route_policy, tls_sni, tls_time
     default: []
   router.enable_proxy:
     description: "Enables support for the popular PROXY protocol, allowing downstream load balancers that do not support HTTP to pass along client information."

jobs/gorouter/templates/gorouter.yml.erb

@@ -505,6 +505,57 @@ if p('router.client_ca_certs')
   params['client_ca_certs'] = client_ca_certs
 end
 
+if_p('router.domains') do |domains|
+  if !domains.is_a?(Array)
+    raise 'router.domains must be provided as an array'
+  end
+
+  processed_domains = []
+  domains.each do |domain_config|
+    if !domain_config.is_a?(Hash)
+      raise 'Each entry in router.domains must be a hash'
+    end
+
+    if !domain_config.key?('name') || domain_config['name'].nil? || domain_config['name'].strip.empty?
+      raise 'Each entry in router.domains must have a "name" key'
+    end
+
+    if !domain_config.key?('ca_certs') || domain_config['ca_certs'].nil? || domain_config['ca_certs'].strip.empty?
+      raise 'Each entry in router.domains must have a "ca_certs" key with certificate content'
+    end
+
+    processed_entry = {
+      'domain' => domain_config['name'],
+      'ca_certs' => domain_config['ca_certs']
+    }
+
+    if domain_config.key?('forwarded_client_cert') && !domain_config['forwarded_client_cert'].nil?
+      valid_modes = ['always_forward', 'forward', 'sanitize_set']
+      mode = domain_config['forwarded_client_cert'].downcase
+      unless valid_modes.include?(mode)
+        raise "Invalid forwarded_client_cert mode '#{mode}' for domain '#{domain_config['name']}'. Must be one of: #{valid_modes.join(', ')}"
+      end
+      processed_entry['forwarded_client_cert'] = mode
+    end
+
+    if domain_config.key?('xfcc_format') && !domain_config['xfcc_format'].nil?
+      valid_formats = ['raw', 'envoy']
+      format = domain_config['xfcc_format'].downcase
+      unless valid_formats.include?(format)
+        raise "Invalid xfcc_format '#{format}' for domain '#{domain_config['name']}'. Must be one of: #{valid_formats.join(', ')}"
+      end
+      if processed_entry['forwarded_client_cert'] == 'always_forward'
+        raise "xfcc_format has no effect for domain '#{domain_config['name']}' when forwarded_client_cert is 'always_forward'. Remove xfcc_format or change forwarded_client_cert to 'sanitize_set'."
+      end
+      processed_entry['xfcc_format'] = format
+    end
+
+    processed_domains << processed_entry
+  end
+
+  params['domains'] = processed_domains
+end
+
 if_p('router.http_rewrite') do |r|
   params['http_rewrite'] = r
 end

packages/gorouter/spec

@@ -33,6 +33,7 @@ files:
   - code.cloudfoundry.org/gorouter/errorwriter/*.go # gosub
   - code.cloudfoundry.org/gorouter/fakes/*.go # gosub
   - code.cloudfoundry.org/gorouter/handlers/*.go # gosub
+  - code.cloudfoundry.org/gorouter/handlers/postselection/*.go # gosub
   - code.cloudfoundry.org/gorouter/integration/*.go # gosub
   - code.cloudfoundry.org/gorouter/logadapter/*.go # gosub
   - code.cloudfoundry.org/gorouter/logger/*.go # gosub

packages/routing-api/spec

@@ -22,10 +22,10 @@ files:
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/lager/v3/internal/truncate/*.go # gosub
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/lager/v3/lagerflags/*.go # gosub
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/*.go # gosub
+  - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/lock/*.go # gosub
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/cmd/locket/certauthority/*.go # gosub
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/cmd/locket/config/*.go # gosub
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/cmd/locket/testrunner/*.go # gosub
-  - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/lock/*.go # gosub
   - code.cloudfoundry.org/vendor/code.cloudfoundry.org/locket/models/*.go # gosub
   - code.cloudfoundry.org/routing-api/*.go # gosub
   - code.cloudfoundry.org/routing-api/admin/*.go # gosub