2.3. Creating a Layer 3 Transparent Forward Proxy Topology

2.3.1. What it is

A topology is an entry point for network traffic into SSL Orchestrator. A transparent forward proxy topology is the mode where SSL Orchestrator is inserted into the network as a layer 3 routed path for outbound (typically Internet-bound) traffic flows. This topology mode inserts itself as a route hop in the network. It could either be that internal clients target the F5 BIG-IP as their gateway, or that the F5 BIG-IP is inserted somewhere between the client’s gateway and the network boundary by way of static, dynamic, or policy-based routes.


2.3.2. How to build it

The following steps illustrate how to build a simple transparent forward proxy topology.

Topology Properties

User Input

Name

Enter a unique name here.

Description

Optionally enter a description here.

Protocol

Select between TCP, UDP, Other (non-TCP/non-UDP), and Any (combination of TCP, UDP and non-TCP/non-UDP).

IP Family

Select between IPv4 and IPv6.

SSL Orchestrator Topologies

Select the L3 Outbound topology here.


Note

Note that SSL and TLS are used primarily with TCP-based protocols topologies. The TCP protocol selection creates the necessary architecture to perform decryption and re-encryption. UDP traffic is not decrypted but can be service chained. Other (non-TCP/non-UDP) is not decrypted and not service chained. This topology selection creates a routed outbound path for non-TCP/non-UDP traffic.

Click Save & Next to proceed.


SSL Configurations

User Input

The SSL Configurations page manages all decryption and re-encryption controls for this topology.

Client-side SSL

Cipher Type

Unless a more complex configuration is required, a Cipher String is typically most appropriate here.

Cipher

With the above Cipher String selection, enter a cipher string value here. DEFAULT is the baseline recommended practices cipher string as provided and maintained by F5 BIG-IP.

Certificate Key Chain

Leave this as default.crt and default.key.

CA Certificate Key Chain

Click the pencil icon to edit the existing certificate and key selection. In the dropdowns for Certificate and Key, select the local CA certificate and private key. Click Done to proceed.

Note

SSL Settings minimally require an RSA certificate and key but can also support Elliptic Curve certificates.

Server-side SSL

Cipher Type

Unless a more complex configuration is required, a Cipher String is typically most appropriate here.

Cipher

With the above Cipher String selection, enter a cipher string value here. DEFAULT is the baseline recommended practice cipher string as provided and maintained by F5 BIG-IP.

Trusted Certificate Authorities

Select a CA bundle certificate file that will be used to validate remote server certificates. In most situations, the built-in ca-bundle.crt is appropriate.

Click Save & Next to proceed.


Services List

User Input

For simplicity of this initial topology configuration, security services are defined in the Services chapter of this deployment guide. Please navigate to this chapter for complete information on configuration of services within SSL Orchestrator.

Click Save & Next to proceed.


Service Chain List

User Input

If services have been created per the previous step, create service chains to contain the services for use by security service policies. Click the Add button.

Name

Provide a name for the service chain.

Description

Optionally provide a description.

Services

Move any available services over to the “Selected Service Chain Order” box, and re-order as required.

Click the Save button to proceed. Repeat this process for any additional service chains.

Click Save & Next to proceed.


Security Policy

User Input

The Security Policy defines the set of traffic matching rules and corresponding actions to take on matches. The built-in security policy contains two rules:

  • Pinners_Rule - used to match URLs on a Pinners custom URL category, for TLS bypass. The Pinners custom URL category is a built-in category and contains a non-exhaustive list of sites known to use certificate pinning. You may need to add sites to this list based on specific business requirements.

  • All Traffic - the default catch-all rule for any traffic that does not match other rules. By default, this rule allows and intercepts (decrypts) traffic but does not preselect any service chain.

To create additional rules, click the Add button.

Name

Provide a name for this rule.

Conditions

Select a condition that matches your traffic requirement. For example, to match any traffic destined to financial site URLs, select the “Category Lookup (All)” Condition. In the box to the right, select the “Financial Data and Services” URL category. Enter as many categories as needed for this rule condition.

Action

Select to either Allow or Reject traffic for this traffic condition.

SSL Forward Proxy Action

Select to either Intercept (decrypt) or Bypass (not decrypt) TLS traffic for this condition.

Service Chain

Select a service chain to process traffic for this condition.

Click the OK button. Repeat this process for any additional rules.

Optionally enable the Server Certificate Status Check option if a blocking page response is required for untrusted or expired server certificates.


Note

Note that to use URL category condition for public URLs, a URL Database subscription license must be provisioned. If no URL Database license exists, you can still use custom URL categories. For IP Reputation conditions, an IP Intelligence subscription license must be provisioned.

Click Save & Next to proceed.


Interception Rule

User Input

The Interception Rule defines the more specific ingress properties of the topology.

Description

Optionally enter a description.

Source Address

This defines a matching source address pattern for ingress traffic flows. The default 0.0.0.0%0/0 pattern matches all inbound traffic (on route domain 0).

Destination Address/Mask

This defines a matching destination address pattern for ingress traffic flows. The default 0.0.0.0%0/0 pattern matches all outbound traffic (on route domain 0). For Internet-bound traffic, this is the appropriate pattern.

Port

This defines a matching destination port for ingress traffic flows. It may be desirable to only process HTTP port 80 or HTTPS port 443 for example. The default 0 port pattern processes outbound traffic on any port.

VLANs

This defines the client facing VLANs that this topology will listen on.

Access Profile

This defines the security policy that will process traffic based on traffic matching rules. This will default to the previously created security policy.

Access Profile Scope

This setting prevents a malicious user from establishing a session using one virtual server, and then using that same session to access, potentially without further authentication, another virtual server and the resources behind it. Default is Named.

This setting is specifically used with transparent proxy captive portal authentication to relay the authenticated session information to the topology. In this case, use the Named profile scope.

  • Profile: Gives a user access only to resources that are behind the same access profile.

  • Named: Gives a SSL Orchestrator user access to resources behind any access profile that has global scope.

L7 Interception Rules

This provides an option to add listeners for FTP, IMAP, POP3 and SMTP traffic.

Click Save & Next to proceed.


Egress Settings

User Input

Egress settings define how traffic exits the topology.

Manage SNAT Settings

If a source NAT is required for this topology, select from either:

  • Automap - uses the egress VLAN self-IP as the source address.

  • Use Existing SNAT - provides selection of an existing SNAT pool.

  • Create New - allows for creation of a new SNAT pool.

Gateways

The gateway setting allows for selection of a system or dedicated egress route path. Select from either:

  • Default Route - uses the system-defined routing table.

  • Use Existing Gateway Pool - provides selection of an existing pool.

  • Create New - allows for creation of a new gateway pool.

Click Save & Next to proceed.


Log Settings

User Input

Log Settings are defined per-topology and provide options to enable different levels of logging for the multiple SSL Orchestrator objects. No logging is expressly required, so the default “Error” setting appropriately generates logs only on error conditions. Keep in mind that SSL Orchestrator will produce extensive logs per flow when raised above Error, so it is recommended only to set higher when troubleshooting issues.

Click Save & Next to proceed.


Summary

User Input

The summary page displays all of the previously defined settings and provides re-entry to each setting to make modifications before deploying.

If all is correct, click Deploy to build this transparent forward proxy SSL Orchestrator topology.


2.3.3. How it works

SSL Orchestrator creates discrete configurations based on the selected topology. Multiple topologies are allowed to exist together as long as they do not conflict with the client facing VLAN and IP addresses of other topologies. The Topology Properties page provides the following options,

  • Topology Properties

    The Protocol option presents four protocol types:


    • TCP - this option creates a single TCP wildcard (all TCP traffic) interception rule for the L3 Inbound, L3 Outbound, and L3 Explicit Proxy topologies. SSL and TLS are primarily used with TCP protocols. A TCP topology will create the necessary architecture to decrypt and re-encrypt traffic flows.


    • UDP - this option creates a single UDP wildcard (all UDP traffic) interception rule for the L3 Inbound and L3 Outbound topologies. A UDP topology does not perform decryption but can service chain UDP traffic.


    • Other - this option creates a single any-protocol wildcard (all non-TCP/non-UDP traffic) interception rule for L3 Inbound and L3 Outbound topologies. A non-TCP/non-UDP topology does not perform decryption or service chaining. It creates a routed path for non-TCP/non-UDP traffic flows.


    • Any - this option creates all of the above TCP, UDP and non-TCP/non-UDP interception rules for outbound traffic flows.

      The SSL Orchestrator Topologies option page presents six topologies. For a transparent forward proxy topology, select the L3 Outbound option. An L3 outbound topology is effectively a “routed hop” configuration, where the SSL Orchestrator topology listener becomes a routed path on the way to external (typically Internet-bound) resources.


Note

Note that at points throughout subsequent topology configurations, it becomes possible to re-use existing objects. For example, if forward proxy SSL settings have already been defined by another forward proxy topology workflow, those SSL settings can be re-used. Look for the “Use Existing” option as you progress through a topology workflow to re-use existing functionality.

Whenever repurposing a topology object, a warning will appear, “There are other configuration items that are referencing this item. Editing this item will affect the referencing ones mentioned below.” Click OK to acknowledge.


  • SSL Configurations

    This page defines the specific SSL settings for the selected topology, in this case a forward proxy, and controls both client-side and server-side SSL options. If an existing SSL configuration is available (from a previous workflow), it can be selected and re-used across multiple topologies. Otherwise the SSL Configurations page creates new SSL settings for this workflow. The [Advanced] options below are available when “Show Advanced Settings” is enabled (top right).


    Client-side SSL

    • [Advanced] Processing Options - SSL Orchestrator 7.1 and above provides TLS 1.3 support for outbound topologies. TLS 1.3 configuration is described in a later chapter of this deployment guide.


    • Cipher Type - cipher type can be a Cipher Group or Cipher String. If the former, select a previously-defined cipher group (from Local Traffic - Ciphers - Groups). If the latter, enter a cipher string that appropriately represents the client-side TLS requirement. For most environments, DEFAULT is optimal.


    • Certificate Key Chain - the certificate key chain represents the certificate and private key used as the “template” for forged server certificates. While re-issuing server certificates on-the-fly is computationally easy, private key creation is extremely CPU-intensive. For that reason, the underlying SSL Forward Proxy engine forges server certificates from a single defined private key. This setting gives you the opportunity to apply your own template private key, and optionally store that key in a FIPS-certified HSM for additional protection. The built-in “default” certificate and private key uses 2K RSA and is generated from scratch when the F5 BIG-IP system is installed, resulting in a globally unique private key.


    • CA Certificate Key Chain - an SSL forward proxy must re-sign (forge) remote server certificate to local clients using a local certificate authority (CA) certificate, and local clients must trust this local CA. This setting defines the local CA certificate and private key used to perform the re-signing (forging) operation. Click the pencil icon to Edit, then select an installed CA certificate and Key, and click Done to proceed. The Chain option allows you to also import a CA bundle file. In organizations where a certificate authority system is defined, there may be multiple layers of CA certificates, a “root” CA, subordinates of the root, and potentially subordinates of the subordinates. Clients must explicitly trust the root CA but might not possess subordinate CAs to perform proper validation. The modern TLS handshake offers the ability to pass CA certificates, up to but not including the root CA to clients to allow them to build the complete CA chain. Therefore, the Chain option here allows you to specify a bundle of subordinate CAs that clients may not have.

      Note

      SSL Settings minimally require RSA-based template and CA certificates but can also support Elliptic Curve (ECDSA) certificates. In this case, SSL Orchestrator would forge an EC certificate to the client if the TLS handshake negotiated an ECDHE_ECDSA cipher. To enable EC forging support, add both an EC template certificate and key, and EC CA certificate and key.


    • [Advanced] Bypass on Handshake Alert - this setting allows the underlying SSL Forward Proxy process to bypass SSL decryption if an SSL handshake error is detected on the server side. It is recommended to leave this disabled.


    • [Advanced] Bypass on Client Certificate Failure - this setting allows the underlying SSL Forward Proxy process to bypass SSL decryption if it detects a Client Certificate Request message from the server, as in when a server requires mutual certificate authentication. It is recommended to leave this disabled.

      Note

      Enabling either of the above two Bypass options can create a security vulnerability. If a colluding client and server can force an SSL handshake error, or force client certificate authentication, they can effectively bypass SSL inspection. It is recommended that these settings be left disabled.


    Server-side SSL

    • [Advanced] Processing Options - SSL Orchestrator 7.1 and above provides TLS 1.3 support for outbound topologies. TLS 1.3 configuration is described in a later chapter.


    • Cipher Type - cipher type can be a Cipher Group or Cipher String. If the former, select a previously-defined cipher group (from Local Traffic - Ciphers - Groups). If the latter, enter a cipher string that appropriately represents the server-side TLS requirement. For most environments, DEFAULT is optimal.


    • Trusted Certificate Authority - browser vendors routinely update the CA certificate stores in their products to keep up with industry security trends, and to account for new and revoked CAs. In the SSL forward proxy use case, however, SSL Orchestrator now performs all server-side certificate validation on behalf of the client browser and should therefore do its best to maintain the same industry security trends. F5 BIG-IP ships with a CA certificate bundle that maintains a list of CA certificates common to the browser vendors. However, a more comprehensive bundle can be obtained from the official F5 Downloads site.


    • [Advanced] Expire Certificate Response - SSL Orchestrator performs validation on remote server certificates and can control what happens if it receives an expired server certificate. The options are drop, which simply drops the traffic, and ignore, which mirrors an expired forged certificate to the client. The default and recommended behavior for forward proxy is to drop traffic on an expired certificate.


    • [Advanced] Untrusted Certificate Response - SSL Orchestrator performs validation on remote server certificates and can control what happens if it receives an untrusted server certificate, based on the Trusted Certificate Authority bundle. The options are drop, which simply drops the traffic, and ignore, which mirrors an untrusted forged certificate to the client. The default and recommended behavior for forward proxy is to drop traffic on an untrusted certificate.


    • [Advanced] OCSP - this setting selects an existing or can create a new OCSP profile for server-side Online Certificate Status Protocol (OCSP) and OCSP stapling. With this enabled, if a client issues a Status_Request message in its ClientHello message (an indication that it supports OCSP stapling), SSL Orchestrator will issue a corresponding Status_Request message in its server-side TLS handshake. SSL Orchestrator will then forge the returned OCSP stapling response back to the client. If the server does not respond with a staple but contains an Authority Info Access (AIA) field that points to an OCSP responder URL, SSL Orchestrator will perform a separate OCSP request. The returned status is then mirrored in the stapled client-side TLS handshake.


    • [Advanced] CRL - this setting selects an existing or can create a new CRL profile for server-side Certificate Revocation List (CRL) validation. With this enabled, SSL Orchestrator attempts to match server certificates to locally cached CRLs.


  • Services

    The Services List page is used to define security services that attach to SSL Orchestrator. The Guided Configuration includes a services catalog that contains common product integrations. Each icon represents a security product integration deployed as one of the five basic service types. The service catalog also provides “generic” security services if your security service is not included in the catalog. Depending on screen resolution, it may be necessary to scroll down to see additional services.


    ../../_images/image910.png

    Figure 9: SSL Orchestrator service catalog


    For simplicity of this initial topology configuration, security services are defined in the Services chapter of this deployment guide. Please navigate to this chapter for complete information on configuration of the different service types.


  • Service Chain List

    Service Chains are ordered lists of security devices. Based on security requirements or business logic, different service chains may contain different or overlapping sets of services, and different types of traffic can be assigned to different service chains. For example, HTTP traffic may need to go through all of the security services, while non-HTTP traffic goes through a subset, and traffic destined to a financial service URL can bypass decryption and still flow through a smaller set of security services.


    ../../_images/image101.png

    Figure 10: SSL Orchestrator logical security policy and service chaining


  • Security Policy

    Security Policies are the set of rules that govern how traffic is processed in SSL Orchestrator, and the actions a rule can take include,

    • Whether or not to allow the traffic (Allow or Reject)

    • Whether or not to decrypt the traffic (Intercept or Bypass)

    • Which service chain (if any) to pass the traffic through


    The Guided Configuration presents an intuitive rule-based, drag-and-drop user interface for the definition of security policies. Note that the default “All Traffic” rule allows and intercepts (decrypts) traffic but does not assign a service chain. To be effective, it is advisable to assign a service chain here.


    ../../_images/image111.png

    Figure 11: SSL Orchestrator basic security policy


    In the background, SSL Orchestrator maintains these security policies as visual per-request policies in the Access module, viewable in the Visual Policy Editor. If traffic processing is required that exceeds the capabilities of the rule-based user interface, the underlying per-request policy can be managed directly.

    Note

    Note that once the per-request policy is manipulated, the rules-based user interface can no longer be used.

    The Server Certificate Status Check option inserts additional security policy logic to validate the remote server certificate and return a blocking page to the user if the certificate is untrusted or expired. One or both of the Certificate Response options on the SSL Configuration page (Expire Certificate Response and Untrusted Certificate Response) must be set to ‘ignore’. SSL Orchestrator will “mask” the server certificate’s attributes in order to present a blocking page with a valid forged certificate.


  • Interception Rule

    Interception Rules are based on the selected topology and define the “listeners”, analogous to LTM virtual servers, that accept and process different types of traffic (ex. TCP, UDP, other). In the background, SSL Orchestrator maintains these interception rules as LTM virtual servers. The resulting LTM virtual servers will bind the SSL settings, VLANs, IPs, and security policies created in the topology workflow.


    • Source Address - the source address field provides a filter for incoming traffic based on source address and/or source subnet. It is usually appropriate to leave the default 0.0.0.0%0/0 setting applied to allow traffic from all addresses to be processed.


    • Destination Address/Mask - the destination address/mask field provides a filter for incoming traffic based on destination address and/or destination subnet. As this is a transparent forward proxy configuration, it is appropriate to leave the default 0.0.0.0%0/0 setting applied to allow all outbound traffic to be processed.


    • [Custom] Port - the setting defines a destination port filter for incoming traffic. It might be useful, for example, to define an L3 outbound topology to only listen on port 443 for HTTPS traffic, enabling other protocol traffic to be handled by other topologies.


    • [Custom | Advanced] Client TCP Profile - this setting allows for selection of a custom client-side TCP profile.


    • [Custom | Advanced] Server TCP Profile - this setting allows for selection of a custom server-side TCP profile.


    • [Custom | Advanced] SSL Configuration - this setting allows for selection of an alternative SSL configuration.


    • [Custom] L7 Profile Type - this setting allows for selection of a custom L7 profile type.


    • [Custom] L7 Profile - this setting allows for selection of a custom L7 profile, and options reflect the L7 Profile Type selection.


    • Ingress Network - VLANs - this defines the VLANs through which traffic will enter. For a transparent forward proxy topology, this would be a client-side VLAN.


    • Security Policy Settings - Access Profile - the Access Profile selection is exposed for both explicit and transparent forward proxy topology deployments. In transparent forward proxy mode, this allows selection of an access policy to support captive portal authentication (covered later in this guide).


    • Security Policy Settings - Access Profile Scope - the Access Profile scope selection is exposed for both explicit and transparent forward proxy topology deployments. In transparent forward proxy mode, this allows selection of scope for the access policy to support captive portal authentication (covered later in this guide).


    • [Custom | Advanced] Pool - a pool defined on a transparent forward proxy is of minimal usefulness, but allows for direct targeting of a resource, which also enables address and port translation on this listener.


    • L7 Interception Rules - Protocols - FTP and email protocol traffic are all “server-speaks-first” protocols, and therefore SSL Orchestrator must process these separately from typical client-speaks-first protocols like HTTP. This selection enables processing of each of these protocols, which create separate port-based listeners for each. As required, selectively enable the** **additional protocols that need to be decrypted and inspected through SSL Orchestrator. This option is not available when in a Custom configuration mode.


  • Egress Settings

    Egress Settings are defined per-topology and manage both the gateway route and outbound SNAT settings.

    • Manage SNAT Settings - enables per-topology instance SNAT settings.


    • Gateways - enables per-topology instance gateway routing. Options are to use the system default route, to use an existing gateway pool, or to create a new gateway.


  • Log Settings

    Log Settings are defined per-topology. In environments where multiple topologies are deployed, this can help to streamline troubleshooting by reducing debug logging to the affected topology. Multiple discrete logging options are available:

    • Per-Request Policy - provides log settings for security policy processing. In Debug mode, this log facility produces an enormous amount of traffic, so it is recommended to only set Debug mode for troubleshooting. Otherwise the most appropriate setting is Error to only log error conditions.


    • FTP - specifically logs error conditions for the built-in FTP listener when FTP is selected among the additional protocols in the Interception Rule configuration. The most appropriate setting is Error to only log error conditions.


    • IMAP - specifically logs error conditions for the built-in IMAP listener when IMAP is selected among the additional protocols in the Interception Rule configuration. The most appropriate setting is Error to only log error conditions.


    • POP3 - specifically logs error conditions for the built-in POP3 listener when POP3 is selected among the additional protocols in the Interception Rule configuration. The most appropriate setting is Error to only log error conditions.


    • SMTP - specifically logs error conditions for the built-in SMTP listener when SMTP is selected among the additional protocols in the Interception Rule configuration. The most appropriate setting is Error to only log error conditions.


    • SSL Orchestrator Generic - provides log settings for generic SSL Orchestrator processing. If Per-Request Policy logging is set to Error, and SSL Orchestrator Generic is set to Information, only the SSL Orchestrator packet summary will be logged. Otherwise the most appropriate setting is Error to only log error conditions.


  • Summary

    The Summary page presents an expandable list of all of the workflow-configured objects. To expand the details for any given setting, click the corresponding arrow icon on the far right. To edit any given setting, click the corresponding pencil icon. Clicking the pencil icon will send the workflow back to the selected settings page.

    Upon successfully deploying the configuration, SSL Orchestrator will now display a Configure view.


    ../../_images/image121.png

    Figure 12: Guided Configuration landing page


    The Interception Rules tab shows the listeners that were created per the selected topology.

    ../../_images/image131.png

    Figure 13: Interception Rules list


    In the above,

    • The -in-t-4 listener defines normal TCP IPv4 traffic.

    • The -in-u-4 listener defines normal UDP IPv4 traffic.

    • The -ot-4 listener defines normal non-TCP/non-UDP IPv4 traffic.

    • The -ftp, -ftps, -pop3, -smtp25 and -smtp587 listeners create paths for each respective protocol.


2.3.4. Additional Information

To test a transparent forward proxy topology, configure a client’s gateway route to point to the self-IP of the client facing VLAN, as specified in the Ingress Network section of the Interception Rules page. Ensure that the client trusts the local issuing CA certificate. Open a browser from the client and attempt to access an external HTTPS resource. Once the page is loaded, observe the server certificate presented to the client and take note of the certificate issuer, which should be the local issuing CA. If you have access to the client’s command line shell and the cURL or wget utilities, you can simulate browser access using one of the following commands:

curl -vk https://www.example.com
wget --no-check-certificate -dO - https://www.example.com

Both of these commands will display both the HTML server response and the issuer of the server’s certificate.


2.3.5. Video