Applies To:

Show Versions Show Versions

Archived Manual Chapter: BIG-IP Reference Guide v4.5:SSL Accelerator Proxies
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

This article has been archived, and is no longer maintained.



7

SSL Accelerator Proxies


What is an SSL Accelerator proxy?

An SSL Accelerator proxy enables the BIG-IP system to accept and terminate any connections that are sent by way of a fully SSL-encapsulated protocol. As an option, you can configure an SSL proxy to also initiate secure connections to a target web server.

Examples of fully-encapsulated SSL protocols that the BIG-IP system supports are: HTTPS, SMTPS, NNTPS, TELNETS, IMAPS, IRCS, POP3S, and FTPS.

In accepting and terminating SSL connections, the SSL proxy performs many functions. Not only can the proxy off load certificate verification tasks and encryption/decryption tasks from a target web server, it can also intelligently control the destination of client requests, for the purposes of authorization and load balancing.

Some of the features of the SSL proxy are:

  • An SSL-to-server feature, which enables the proxy to establish secure connections between the proxy and a target web server
  • A FIPS-140 Level-3 compliant, tamper-proof mechanism for storing private keys
  • Support for certificate revocation lists (CRLs)
  • Certificate-based client authorization using a Light-weight Directory Access Protocol (LDAP) server.

When you create a proxy, many of the configuration options include default values. These default values allow you to use the proxy as is, or customize it to further suit your particular needs.

Figure 7.1 shows how an SSL proxy fits into a standard client-server environment. The figure shows that a proxy can accept a request from a client, forward the request on to a content server, receive the response, and then forward the response back to the client.

Figure 7.1 An SSL Accelerator proxy on the BIG-IP system


Summary of features

An SSL proxy includes several important features. Table 7.1 summarizes these features.

 

Features

Description

Graphical or command line interface

Through the Configuration utility or the bigpipe proxy command, you can create an SSL proxy that includes default values for its configuration options. You can either use the default values or change them to suit the needs of your networking environment.

Authentication

Validation--An SSL proxy can perform the same certificate validation tasks that are normally performed by clients and servers when processing SSL connections. By validating client and server certificates, the proxy allows you to off load this task from your target web servers to the BIG-IP system, thereby enhancing the availability of your web servers.

Verification--In terminating SSL connections, an SSL proxy can perform a full range of certificate verification tasks, including the verification of both client and server certificates. For example, you can also define the extent to which the proxy verifies client certificates--you can configure the proxy to request client certificates, require them, or ignore them altogether. Also, the SSL proxy provides additional security through its ability to encrypt and decrypt proxy-to-server connections and through its provision of tamper-proof mechanisms for private key storage.

Revocation--When a client or server presents a certificate to the proxy, the proxy can check a list of revoked certificates (known as a CRL) as part of the certificate verification process.

Encryption and decryption

As a way to off load work from target web servers, the SSL proxy decrypts incoming client requests. As an added security option, you can configure the proxy to re-encrypt a request before forwarding it on to a server. Encryption and decryption of requests and responses are based on particular ciphers that you specify as part of proxy configuration.

Authorization

An SSL proxy can control access to system resources by allowing you to configure the proxy in certain ways. For example, you can configure the proxy to insert client certificate information into client requests and then grant access based on that information. Also, for environments that include an LDAP database server, the proxy can grant access to resources by querying the LDAP server using client certificate credentials.

Network traffic control

A powerful feature of the SSL proxy is its ability to insert different types of headers into client requests. This feature, when used with rule building, allows the proxy to intelligently control how SSL traffic is handled. For example, you can implement persistence for SSL connections by inserting session IDs or client certificate hashes as headers into client requests. Another traffic control feature is the proxy's ability to rewrite HTTP redirections to other servers.

Other SSL features

In addition to the features listed above, the SSL proxy allows you to configure other options such as invalid protocol versions, the size and timeout values of the SSL session cache, and SSL shutdown behavior.

 

Basic configurations

An SSL proxy can be deployed in either of two basic configurations.

  • Client-side SSL proxy
    A client-side SSL proxy terminates SSL connections, decrypts a request, and sends the request in clear text to a web server. The proxy then retrieves a clear-text response (such as a web page) and encrypts the request, before sending the web page back to the client. During the process of terminating an SSL connection, the proxy performs all of the certificate verification functions normally handled by the target web server, as well as encryption and decryption functions. For information on creating a basic client-side SSL proxy, see Creating a client-side-only SSL proxy .
  • Client-side SSL proxy with SSL-to-Server enabled
    Known as SSL-to-Server, the server-side proxy option ensures security by allowing the proxy to re-encrypt requests before sending them on to a web server. In addition to this re-encryption, the proxy performs the same validation and verification functions for server certificates that it does for client certificates. For information on enabling the SSL-to-Server feature, see Creating a client-side proxy with SSL-to-Server enabled .

The following sections describe how to create these two different proxy configurations.

Creating an SSL Accelerator proxy

When creating an SSL Accelerator proxy, you can enable the proxy to handle either client-side SSL connections only, or both client-side and server-side SSL connections. The following sections describe these two basic configurations and the procedures for implementing them.


Creating a client-side-only SSL proxy

A client-side proxy performs some basic functions that are automatically configured when you create the proxy. These functions are required, and the BIG-IP system creates default values for those functions. As a proxy administrator, you are free to modify those default values, as a way to customize the way that the proxy performs these basic functions.

Other client-side proxy functions, however, are strictly optional, providing you with a way to even further customize the way that the proxy manages SSL traffic.

The following sections describe these basic and optional functions. Following these sections are the procedures for creating a basic client-side proxy.


Basic client-side functions

The basic functions of a client-side proxy are to off load certificate validation and verification tasks, as well as encryption and decryption, from your target web servers. The proxy does this in the following way:

  • First, a client-side proxy attempts to validate and verify any client certificate presented with the request.
  • If validation and verification succeeds, the proxy decrypts the request, sends it to a target server as plain text, and waits for a response.
  • On receiving the unencrypted response, the proxy encrypts the response and sends it back to the client that originated the request.

In performing these functions, the proxy can use either a set of default values, or a set of new values that you specify.

For more information on certificate verification and encryption and decryption of requests and responses, see Certificate verification and Encryption and decryption .


Other functions

Additional client-side configuration options are available to further offload tasks from your web servers to the proxy. Examples are the ability for the proxy to rewrite HTTPS redirections from one web server to another, and the ability to maintain persistence for SSL connections.

In addition to off loading work from web servers, a client-side proxy can be configured to intelligently control SSL traffic, either for access control (authorization) purposes, or for load balancing purposes.

For more information on these functions, see Authorization , Network traffic control , and Other SSL protocol options .


Configuration procedures

Prior to creating a client-side SSL proxy, you must first generate a valid x509 certificate from a Trusted Certificate Authority, or generate a temporary certificate, and install it on the BIG-IP system. The BIG-IP system then uses this certificate when acting as a server to receive requests from clients. For more information on proxy certificates, see Signed certificates . For instructions on how to generate and install a certificate on the BIG-IP system, see Using the Key Management System .

Once you have installed a certificate on the BIG-IP system and created a basic client-side SSL proxy, you can configure additional options. For information on configuring additional options, see the remaining sections of this chapter.

Note


Use the following procedure only when creating a client-side proxy with no server-side proxy option enabled. To create a client-side proxy that includes the server-side proxy option, use the procedure described in the section titled Creating a client-side proxy with SSL-to-Server enabled .

You can create a client-side proxy using either the Configuration utility or the command line.


To create a client-side SSL proxy using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. Click the ADD button.
    The Add Proxy screen opens.
  3. In the Proxy Type box, check the box labeled SSL.
  4. In the Proxy Address box, type the IP address of the proxy.
  5. In the Proxy Service box, type https or select the https service from the list box.
  6. In the Destination Address box, type the IP address of either a local virtual server or a target web server.
  7. In the Destination Target box, use the Local Virtual Server option in the list box, or select External Node.
    When you use the default Local Virtual Server option, the destination of a packet is a virtual server on the proxy. When you select External Node, packets pass through the proxy to a target web server.
  8. In the SSL Certificate box, select a certificate file name from the list, or type a certificate file name.
  9. In the SSL Key box, select a key file name from the list, or type a key file name.
  10. Click Done.

To create a client-side SSL proxy from the command line

Use the following command-line syntax to create a client-side SSL proxy:

b proxy <ip>:<service> [unit <unit_id>] \
target <server|virtual> <ip>:<service> \
clientssl enable \
clientssl key <clientssl_key> \
clientssl cert <clientssl_cert>

The following example creates an SSL proxy:

b proxy 10.1.1.1:443 unit 1 \
target virtual 20.1.1.1:80 \
clientssl enable \
clientssl key my.server.net.key \
clientssl cert my.server.net.crt

When the SSL proxy is written in the /config/bigip.conf file, it looks like the sample in Figure 7.2 .

Figure 7.2 Sample SSL proxy entries in /config/bigip.conf with client-side certificate and key files configured


proxy 10.1.1.1:443 unit 1 {
target virtual 20.1.1.1:http
clientssl enable
clientssl key my.server.net.key
clientssl cert my.server.net.crt
}
 

Creating a client-side proxy with SSL-to-Server enabled

Once the SSL Accelerator proxy has decrypted a client request, you might want the BIG-IP system to re-encrypt that request before it sends the request to the server, to maintain server-side security. This feature is known as SSL-to-Server. You implement this feature when you create the client-side SSL proxy.

The following sections describe the basic functions of the server-side proxy, and describe how to create a proxy with the SSL-to-Server feature enabled.


Basic server-side functions

The proxy performs these additional tasks when the SSL-to-Server option is enabled:

  • Re-encrypting a decrypted client request and sending it to the server.
  • Verifying the server certificate (if required).
  • Sending a public key to the server for the purpose of encrypting the server response.
  • Decrypting the server response.
  • Re-encrypting the response and sending it to the client.

Configuration procedures

Prior to implementing a client-side proxy with the SSL-to-Server feature enabled, you must first generate a valid x509 certificate from a Trusted Certificate Authority, or generate a temporary certificate, and install it on the BIG-IP system. The proxy then uses this certificate when acting as a server to receive requests from clients. As an option, you can generate and install a second certificate on the BIG-IP system, when SSL-to-Server is enabled and the target server requires the proxy to present client credentials.

Note


If you do not install the second certificate on the proxy for implementing server-side SSL processing (SSL-to-Server), and the target server subsequently requires that the BIG-IP system present client credentials, any server-side connection will fail, causing the corresponding client-side connection to close.

For more information on proxy certificates, see Signed certificates . For instructions on how to generate and install a certificate on the BIG-IP system, see Using the Key Management System .

Once you have installed certificates on the BIG-IP system and created a basic client-side SSL proxy with SSL-to-Server enabled, you can configure additional options. For information on configuring additional options, see the remaining sections of this chapter.

Note


Use following procedure only when creating a client-side proxy with the server-side proxy option enabled. To create a client-side proxy without the server-side proxy option, use the procedure described in the section titled Creating a client-side-only SSL proxy .

You can create a client-side proxy with SSL-to-Server enabled using either the Configuration utility or the command line interface.


To create a client-side proxy with SSL-to-Server using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. Click the ADD button.
    The Add Proxy screen opens.
  3. In the Proxy Type box, check the boxes labeled SSL and ServerSSL.
  4. In the Proxy Address box, type the IP address of the proxy.
  5. In the Proxy Service box, type https or select the https service from the list box.
  6. In the Destination Address box, type the IP address of either a local virtual server or a target web server.
  7. In the Destination Target box, use the Local Virtual Server option in the list box, or select External Node.
    When you use the default Local Virtual Server option, the destination of a packet is a virtual server on the proxy. When you select External Node, packets pass through the proxy to a target web server.
  8. In the boxes labeled SSL Key and SSL Certificate, either type the names of the key and certificate files or select the names from a list of available key and certificate files.
    These certificate and key files are used to authenticate a proxy acting as a server to clients during client-side SSL processing.
  9. Optionally, in the boxes labeled Server SSL Key and Server SSL Certificate, either type the names of the key and certificate files or select the names from a list of available key and certificate files.
    When the target server requires the proxy to present client credentials, these certificate and key files are used to authenticate the proxy.
  10. Click Done.

To create a client-side proxy with SSL-to-Server from the command line

Use the following command line syntax to create a client-side SSL proxy with SSL-to-Server enabled:

b proxy <ip>:<service> [unit <unit_id>] \
target <server|virtual> <ip>:<service> \
clientssl enable \
clientssl key <clientssl_key> \
clientssl cert <clientssl_cert> \
serverssl enable \
serverssl key <serverssl_key> \
serverssl cert <serverssl_cert> \

For example:

b proxy 10.1.1.1:443 unit 1\
target virtual 20.1.1.10:443 \
clientssl enable \
clientssl key my.server.net.key \
clientssl cert my.server.net.crt \
serverssl enable
serverssl key my.client.net.key \
serverssl cert my.client.net.crt

Figure 7.3 shows the state of the /config/bigip.conf file, after creating a client-side proxy with SSL-to-Server enabled, and configuring the certificates and keys for both client-side and server-side SSL connections.

Figure 7.3 Sample SSL proxy entries in /config/bigip.conf with both client-side and server-side certificate and key files configured


proxy 10.1.1.1:443 unit 1 {
target virtual 20.1.1.1:https
clientssl enable
clientssl key my.server.net.key
clientssl cert my.server.net.crt
serverssl enable
serverssl key my.client.net.key
serverssl cert my.client.net.crt
}
 

Displaying SSL Accelerator proxy information

You can use the display information about an SSL proxy by using either the Configuration utility or the bigpipe proxy command.


To display configuration information for a proxy using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. Click an existing proxy name.
    The properties page for that proxy is displayed.

To display configuration information for a proxy from the command line

Use the following syntax to view configuration information for the specified proxy:

b proxy <ip>:<service> show

For example, if you want to view configuration information for the SSL proxy 209.100.19.22:443, type the following command:

b proxy 209.100.19.22:443 show


Disabling or deleting an SSL Accelerator proxy

The following procedures show how to disable or delete an SSL proxy.


To disable an SSL proxy using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. In the Proxy Server column, locate the proxy to be disabled.
  3. In the Enabled column, click the button.
    All proxies are enabled by default.

To delete an SSL proxy using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. In the Proxy Server column, locate the proxy to be deleted.
  3. In the Delete column, click the Delete button.

To disable or delete an SSL proxy from the command line

You can disable or delete a proxy with the following syntax:

b proxy <ip>:<service> disable
b proxy <ip>:<service> delete

For example, if you want to disable the SSL proxy 209.100.19.22:443, type the following command:

b proxy 209.100.19.22:443 disable

If you want to delete the SSL proxy 209.100.19.22:443, type the following command:

b proxy 209.100.19.22:443 delete

Authentication

Authentication is the process of verifying the identity of a client or server and determining whether or not that client or server can be trusted. When attempting to authenticate a client or server, the proxy first checks the validity of the certificate being presented. If the certificate is valid, the proxy then seeks to verify the certificate, to ensure that the sender can be trusted. The proxy can also check a Certificate Revocation List (CRL), to see if a certificate being presented by a client or server has been revoked.

To help you configure the proxy to handle these various authentication tasks, this section addresses the following topics:

  • Certificate verification
  • Certificate revocation
  • The Key Management System (KMS)

Certificate verification

Certificate verification is the process of determining whether a client or server can trust a certificate that is presented by a peer (that is, a client or a server). When receiving a request from a client or a response from a server, an SSL proxy attempts to verify that the certificate presented by the client or server can be trusted.


Signed certificates

A basic security requirement for clients and servers handling SSL connections is that they each present a certificate signed by a trusted Certificate Authority (CA), whenever they communicate with a peer. Thus, in a client-server scenario where the server requires the presentation of a client certificate, the client presents a certificate to the server servicing the request, and a server presents a certificate to the client receiving the response.

When an SSL proxy is added to the scenario, the BIG-IP system, too, must hold certificates that it can present to clients and servers when processing requests and responses. Specifically, a client-side proxy that requires the presentation of a certificate from a client needs to hold a certificate, to be used when acting as a server to communicate with that client. Optionally, if the SSL-to-Server feature is enabled and a target server requires the presentation of a certificate from the proxy, the proxy can hold a second certificate, to be used when acting as a client to communicate with that target server.

You must generate and install certificates onto the BIG-IP system prior to creating the proxy. You can do this either through the Configuration utility or the genkey and genconf command-line utilities. As an alternative, you can import existing key/certificate pairs. For more information on importing existing key/certificate pairs, see Importing keys and certificates .

Figure 7.4 shows the distribution of certificates in a client-server configuration in which a client-side proxy with SSL-to-Server enabled has been added.

Figure 7.4 Certificates in a BIG-IP system configuration with an SSL proxy

The following section provides an introduction to certificate verification as handled by the SSL proxy, and then provides detailed procedures for configuring both client-side and server-side verification.


Summary of certificate verification methods and options

The primary way that a proxy verifies a client or server certificate is through the use of trusted certificate authority (CA) files and Trusted CAs paths. The proxy uses these files and paths to determine whether it should trust a certificate that a client or server presents to it. Moreover, for client-side SSL connections, the SSL proxy can advertise to a client a list of those CAs that the proxy wants the client to recognize as trusted CAs. Finally, the proxy can send a chain file to a client or server, to ensure that the client or server can authenticate the proxy. These various files and paths are described as follows.

  • Trusted CAs files
    A Trusted CAs file is the primary means by which an SSL proxy verifies a certificate, either from a client or a server. The Client Trusted CAs file and the Server Trusted CAs file each contain a list of Certificate Authorities (CA) that the proxy trusts. When a client or server presents a certificate to the proxy, the proxy checks the certificate against the appropriate list of trusted CAs. If a match exists, then the SSL proxy trusts that client or server.
  • Trusted CAs paths
    A Trusted CAs path is a secondary means by which a proxy verifies a certificate, either from a client or server. The Client Trusted CAs path and the Server Trusted CAs path contain individual files that each contain a certificate signed by a CA that the proxy trusts. When the proxy cannot find a Certificate Authority listed in one of the Trusted CAs fileTrusted CAs files, it checks either the Client Trusted CAs path or the Server Trusted CAs path, depending on whether the certificate verification is part of client-side or server-side SSL processing.
  • The Client Certificate CA file
    Unlike a Trusted CAs file, which is known to and used strictly by the SSL proxy, the Client Certificate CA file is directly advertised to clients, to inform them of the CAs that the proxy wants its clients to recognize as trusted CAs.
  • Certificate chain files.
    When you create a client-side proxy, you can specify a Client Chain file. The Client Chain file is used by a client to authenticate the proxy during the client certificate verification process. If you enable the SSL-to-Server option for server-side processing, you can specify a second chain file, called the Server Chain file. The Server Chain file is used by a server to authenticate the proxy during the server verification process.

In addition to specifying a list of trusted CAs as a way to verify certificates, you can also configure some other verification options on the SSL proxy. These options include specifying whether the SSL proxy should request, require, or ignore certificates presented to it; configuring the SSL proxy to authenticate a client either once per SSL session or upon each subsequent reuse of the session; and specifying the number of certificates in a chain that the SSL proxy can traverse before verification fails.


Client-side certificate verification

When a client makes an HTTPS request, the SSL proxy performs the client certificate verification task normally performed by the target web server.

Figure 7.5 shows the interaction between a client and an SSL proxy during the certificate verification process.

Figure 7.5 Client-side certificate verification process

As Figure 7.5 shows, when a client presents a certificate to the proxy, the proxy uses the Client Trusted CAs file or the Client Trusted CAs path to determine the Certificate Authorities that it can trust. Using this file and path is the primary way that a proxy attempts to verify a client certificate. A default Client Trusted CAs file and Client Trusted CAs path are automatically created when you create a client-side proxy. You can either use the default file and path or specify a different file and path. For more information, see Specifying trusted client CAs .

A second factor in client certificate verification is the Client Certificate CA file, which the proxy uses to advertise to clients a list of the CAs that the proxy trusts. Note that this list could be different from the list of CAs that the proxy actually trusts. Like the Trusted CAs file and path, a default version of the file is automatically created when you create a client-side proxy. You can either use the default file, or create a different file. For more information, see Advertising a list of trusted client CAs .

Finally, there is a client chain file, which the proxy sends to a client as part of the client certificate verification process. Instead of being used to verify a client certificate, the proxy's client chain file is used by a client to verify the proxy's certificate. The default client chain file is the Client Trusted CAs file. For more information, see Configuring a client certificate chain .

Table 7.2 lists and describes the various options that are available for configuring certificate verification on a client-side SSL proxy

 

Configuration Option

Description

Specifying trusted client CAs

Allows you to configure certificate chaining and verification.

Advertising a list of trusted client CAs

Allows you to specify the CAs that you would like to advertise to clients as being trusted by the proxy.

Configuring a client certificate chain

Allows you to specify or build a certificate chain file that a client can use to authenticate the proxy.

Configuring the presentation of client certificates

Allows you to configure the SSL proxy to either request, require, or ignore certificates presented by a client.

Configuring per-session authentication

Allows you to specify whether the proxy should authenticate a client once per session or once per session and upon each subsequent reuse of an SSL session.

Authentication depth

Allows you to specify the maximum number of certificates that can be traversed in a client certificate chain.

 

The following sections provide detailed descriptions of the options listed above and the procedures for configuring them.


Specifying trusted client CAs

For client-side SSL processing, you can configure the SSL proxy to verify certificates presented by a client. Using either the Configuration utility or the bigpipe proxy command, you can specify both a Client Trusted CAs file name and a Client Trusted CAs path name, which the proxy then uses to verify client certificates. If you do not configure a Client Trusted CAs file or Client Trusted CAs path, the proxy uses a default file and path.

To configure client-side certificate verification, you might need to configure these elements:

  • The Client Trusted CAs file
    The Client Trusted CAs file that you specify for certificate verification contains one or more certificates, in Privacy Enhanced Mail (PEM) format. Built manually, this file contains a list of the client certificates that the SSL proxy will trust. If you do not specify a Client Trusted CAs file, or the specified Client Trusted CAs file is not accessible to the proxy, the proxy uses the default file name /config/bigconfig/ssl.default.crt.
  • The Client Trusted CAs path
    The Client Trusted CAs path is a path name to a directory containing the certificates used when searching for trusted CAs. When searching a Client Trusted CAs path, the proxy only examines those certificates that include a properly-formatted symbolic link to a certificate file. If you do not specify a Client Trusted CAs path, or the Client Trusted CAs path is not accessible to the proxy, the proxy uses the default path name /config/bigconfig/ssl.crt/. Note that each certificate file should contain only one certificate. This is because only the first certificate in the file is used, unlike the Client Trusted CAs file, which can contain more than one certificate.
  • Symbolic links to client certificates
    Generating symbolic links for certificates ensures that each file in the path is linked to a certificate.

    The procedures for specifying a Client Trusted CAs file and a Client Trusted CAs path, and for generating symbolic links to client certificates, follow.


To specify the Client Trusted CAs file, Client Trusted CAs path, and symbolic-link generation using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the boxes Client Trusted CAs file and Client Trusted CAs path, either select the name of a Trusted CAs file and path from the box, or type the name of a Trusted CAs file or path.
  4. If you want to ensure that each certificate has a link to its corresponding file, check the Generate Symbolic Links for Client Trusted CAs Path check box. You should do this whenever you specify any of the path attributes.
  5. Click Done.

To specify the Client Trusted CAs file and Client Trusted CAs path from the command line

To specify the Client Trusted CAs file and Client Trusted CAs path from the command line, type the bigpipe proxy command, using the appropriate arguments, as follows:

b proxy <ip>:<service> [clientssl] ca file <clientside CA file name>

b proxy <ip>:<service> [clientssl] ca path <clientside CA path name>


To generate symbolic links for a Client Trusted CAs path from the command line

To generate symbolic links from the command line, you must use the UNIX make command.

  1. Use the UNIX cd command to change to the directory containing the certificates.
  2. Run the following command as shown:

    make -f /config/bigconfig/ssl.crt/Makefile

  3. Restart the SSL proxy by either running the proxyd command from the command line or by reconfiguring the proxy in the Configuration utility.

Note


Whenever you subsequently add, remove, or modify certificates, you must restart the SSL proxy again, as described in Step 3 above. This causes the changes to take effect.
Advertising a list of trusted client CAs

If you intend to configure the SSL proxy to require or request client certificates for authentication, you will want the proxy to send to clients a list of CAs that the server is likely to trust.

This list, known as the Client Certificate CA file, is different from the Client Trusted CAs file. This is because, in some cases, you might have a client that does not possess a valid client certificate, in which case you might not want to reveal the actual list of CAs that the proxy trusts. The Client Certificate CA file solves this problem by allowing the proxy to advertise a list of CAs that is different from the actual Client Trusted CAs file configured as part of certificate verification.

Tip


Although the contents of the Client Certificate CA file can differ from that of the Client Trusted CAs file, it is best, for compatibility reasons, to set the Client Certificate CA option to match the actual Client Trusted CAs file. This is because modern borwsers might not permit SSL session negotiation to proceed if the peer that requests the client certificate does not provide a list of trusted CAs.

To configure the proxy to send this list, you can specify a PEM-formatted certificate file that contains one or more CAs that a server trusts for client authentication. If no Client Certificate CA file is specified, no list of trusted CAs is sent to a client.


To advertise a list of trusted CAs using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client Certificate CA File box, select a file name from the box, or type the certificate CA file name.
  4. Click Done.

To advertise a list of trusted CAs from the command line

To use the command line to configure the proxy to send a list of trusted CAs to a client, type the bigpipe proxy command, using the following arguments:

b proxy <ip>:<service> [clientssl] client cert ca <clientside client cert CA file name>


Configuring a client certificate chain

In any client verification process, not only does the proxy need to authenticate the client, but the client might need to authenticate the proxy. However, a certificate that the SSL proxy uses to authenticate itself to a client is sometimes signed by an intermediate CA that is not trusted by that client. In this case, the proxy might need to use a certificate chain. The proxy enables you to specify the name of a specific certificate chain file, either through the Configuration utility or from the command line. Note that the certificate files that make up the chain file must be in PEM format.

When attempting to access the specified chain file, the SSL proxy searches for the file in the following manner:

  1. The proxy looks to see that the file you specified has a .chain extension.
  2. If the file specification does not include a .chain extension, the proxy appends that extension to the specified file and then searches for that file.
  3. If the file is not found, the proxy instead appends a .crt extension to the specified file and searches again.
  4. If the file is still not found, the proxy uses the same file name as that of the configured certificate. For example, the proxy might take the certificate name www.mysite.com.crt, replace the .crt file name extension with the .chain extension, and search on the file name www.mysite.com.chain.
  5. If unable to find the certificate chain using the preceding procedure, the proxy attempts to build the chain.

To specify a certificate chain using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the box Client Chain File, either select the name of a Client Trusted CAs file from the box, or type the name of a Client Trusted CAs file.
  4. Click Done.

To specify a certificate chain from the command line

To specify a certificate chain from the command line, type the bigpipe proxy command with the appropriate arguments, as follows:

b proxy <ip>:<service> [clientssl] chain <clientside chain file name>


Configuring the presentation of client certificates

You can configure an SSL proxy to handle authentication of clients in three ways:

  • You can configure the proxy to request and verify a client certificate. In this case, the SSL proxy always grants access regardless of the status or absence of the certificate.
  • You can configure the proxy to require a client to present a valid and trusted certificate before granting access. In this case, if certificate verification fails, all corresponding connections are closed, and log messages are generated by the proxyd daemon.
  • You can configure the proxy to ignore a certificate (or lack of one) and therefore never authenticate the client. The ignore setting is the default setting, and when used, causes any per-session authentication setting to be ignored. For information on configuring per-session authentication, see Configuring per-session authentication .

Warning


If are using the LDAP-based client authorization feature, use of the request or ignore options can sometimes cause a connection to terminate. For more information, see Creating an authorization model .

Tip


The request option works well with the header insertion feature. Configuring the SSL proxy to insert client certificate information into an HTTP client request and to authenticate clients based on the request option enables the BIG-IP system or a server to then perform actions such as redirecting the request to another server, sending different content back to the client, or performing client certificate or session ID persistence.
To configure client-side certificate presentation using the Configuration utility
  1. From the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client Certificate box, choose either the Request, Require, or Ignore option.
  4. Click Done.

To configure client-side certificate presentation from the command-line

To configure client-side certificate presentation from the command line, use the bigpipe proxy command and specify the desired option, as follows:

b proxy <ip>:<service> [clientssl] client cert <request | require | ignore>


Configuring per-session authentication

You can configure an SSL proxy to require authentication either once per SSL session (once), or once upon each subsequent reuse of an SSL session (always). The default setting for this option is once.

Whether you set this value to once or always depends on your application. A well-designed web application should only need to verify a certificate once per session. We recommend for performance reasons that you use the default setting (once) whenever possible.


To modify per-session authentication using the Configuration utility

You can modify the SSL proxy to require authentication not only once per session, but also upon each subsequent reuse of an SSL session.

  1. In the navigation pane, click Proxies.
  2. Click the Add button.
    The Client Authenticate Once box is checked.
  3. Click on the Client Authenticate Once box
    This clears the box, thereby changing the setting from once to always.
  4. Click Done.

To modify per-session authentication from the command line

To modify the SSL proxy to require authentication not only once per session, but also upon each subsequent reuse of an SSL session, specify always argument with the bigpipe proxy command. This changes the setting from once to always. The command line syntax for this operation s as follows:

bigpipe proxy <ip>:<service> [clientssl] authenticate <once | always>


Configuring authentication depth

Using this option, you can configure the maximum number of certificates that can be traversed in the client certificate chain. The default value is 9. If a longer chain is provided, and the client has not been authenticated within this number of traversals, client certificate verification fails. If the authentication depth value is set to zero, then only the client certificate, and one of the chain file, is examined.


To configure authentication depth using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client Authenticate Depth box, type a whole number.
  4. Click Done.

To configure authentication depth from the command line

To configure authentication depth from the command line, use the authenticate depth argument with the bigpipe proxy command, as follows:

b proxy <ip>:<service> [clientssl] authenticate depth <num>


Server-side certificate verification

Server-side verification occurs when the SSL-to-Server feature is enabled and the presentation of a server certificate to the proxy is set to require. Figure 7.6 shows the interaction between an SSL proxy and a server during the certificate verification process.

Figure 7.6 Server-side certificate verification process

As Figure 7.6 shows, when a server presents a certificate to the proxy, the proxy uses the Server Trusted CAs file or the Server Trusted CAs path to determine which Certificate Authorities it can trust. Using this file and path is the primary way that a proxy attempts to verify a server certificate. A default Server Trusted CAs file and Server Trusted CAs path are automatically created when you enable the SSL-to-Server option. You can either use the default file and path, or specify a different file and path. For more information, see Specifying trusted server CAs .

In addition to the Trusted CAs file and Trusted CAs path, there is a server chain file, which the proxy sends to a server as part of the entire server certificate verification process. Instead of being used to verify a server certificate, however, the proxy's server chain file is used by a server to verify the proxy's certificate. The default server chain file is the Server Trusted CAs file. For more information, see Configuring a server certificate chain .

Table 7.3 lists and describes the various options available for configuring certificate verification on a server-side SSL proxy

 

Configuration Option

Description

Specifying trusted server CAs

Allows you to configure certificate chaining and verification.

Configuring a server certificate chain

Allows you to specify or build a certificate chain file that a server can use to authenticate the proxy.

Configure presentation of server certificates

Allows you to configure the SSL proxy to either require or ignore certificates presented by a server.

Authentication depth

Allows you to specify the maximum number of certificates that can be traversed in a server certificate chain.

 

The following sections provide detailed descriptions of the options listed above and the procedures for configuring them.


Specifying trusted server CAs

For server-side SSL processing, you can configure the SSL proxy to verify certificates presented by a server. Using either the Configuration utility or the bigpipe proxy command, you can specify both a Server Trusted CAs file name and a Server Trusted CAs path name, which the proxy then uses to verify server certificates. You can also generate symbolic links to ensure that every file in the path is linked to a certificate.

To configure server-side certificate verification, you might need to configure the following elements:

  • The Server Trusted CAs file
    The Server Trusted CAs file that you specify for certificate verification contains one or more certificates, in PEM format. Built manually, this file contains a list of the server certificates that the SSL proxy will trust. If you do not specify a Server Trusted CAs file, or the specified Server Trusted CAs file is not accessible to the proxy, the proxy uses the default file name /config/bigconfig/ssl.crt/default.crt.
  • The Server Trusted CAs path
    The Server Trusted CAs path is a path name to a directory containing the certificates used when searching for trusted CAs. When searching a Server Trusted CAs path, the proxy only examines those certificates that include a properly-formatted symbolic link to a certificate file. If you do not specify a Server Trusted CAs path, or the Server Trusted CAs path is not accessible to the proxy, the proxy uses the default path name /config/bigconfig/ssl.crt/. Note that each certificate file should contain only one certificate. This is because only the first certificate in the file is used.
  • Symbolic links to server certificates
    Generating symbolic links for certificates ensures that each file in the path is linked to a certificate.

The procedures for specifying a Trusted CAs file and a Trusted CAs path, and for generating symbolic links to server certificates follow.


To specify the Server Trusted CAs file, Server Trusted CAs path, and symbolic-link generation using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the boxes Server Trusted CAs file and Server Trusted CAs path, either select the name of a Trusted CAs file or path from the box, or type the name of a Trusted CAs file or path.
  4. If you want to ensure that each certificate has a link to its corresponding file, check the Generate Symbolic Links for Server Trusted CAs Path check box. You should do this whenever you specify any of the path attributes.
  5. Click Done.

To specify the Server Trusted CAs file and Server Trusted CAs path from the command line

To specify the Server Trusted CAs file and Server Trusted CAs path from the command line, type the bigpipe proxy command, using the appropriate arguments, as follows:

b proxy <ip>:<service> serverssl ca file <serverside CA file name>

b proxy <ip>:<service> serverssl ca path <serverside CA path name>


To generate symbolic links for a server CRL path

For the procedure on generating symbolic links for a Server Trusted CAs path, use the procedure described in To generate symbolic links for a Client Trusted CAs path from the command line .


Configuring a server certificate chain

In any server verification process, not only does the proxy need to authenticate the server, but the server might need to authenticate the proxy. However, a certificate that the SSL proxy uses to authenticate itself to a server is sometimes signed by an intermediate CA that is not trusted by that server. In this case, the proxy might need to build a certificate chain.

You can build a certificate chain by specifying the name of a specific certificate chain file, either through the Configuration utility or from the command line. Note that the certificate files that make up the chain file must be in PEM format.

When attempting to access the specified chain file, the SSL proxy searches for the file in the following manner:

  1. The proxy looks to see that the specified file has a .chain extension.
  2. If the file specification does not include a .chain extension, the proxy appends that extension to the file and then searches for the file.
  3. If the file is not found, the proxy instead appends a .crt extension to the file and searches again.
  4. If the file is still not found, the proxy uses the same file name as that of the optionally-configured certificate. For example, the proxy might take the file name www.dot.com.crt, replace the .crt file name extension with the .chain extension, and search on the file name www.dot.com.chain.
  5. If unable to build the certificate chain using the preceding procedure, the proxy attempts to build the chain through certificate verification.

To build a certificate chain using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the box Server Chain File, either select the name of a Server Trusted CAs file from the box, or type the name of a Server Trusted CAs file.
  4. Click Done.

To build a certificate chain from the command line

To build a certificate chain from the command line, type the bigpipe proxy command with the appropriate arguments, as follows:

b proxy <ip>:<service> serverssl chain <serverside chain file name>


Configuring the presentation of server certificates

To implement certificate verification on the server side (that is, between the SSL proxy and the server), you can configure the proxy either to require the server to present a certificate or to ignore the presentation of a certificate. Note, however, that you cannot require the server to present a certificate if anonymous cipher suites are negotiated. For information on configuring ciphers, see Specifying SSL ciphers .

If this option is set to require, the proxy attempts to verify any certificate presented by the server. If this verification fails, the SSL connection also fails, and the corresponding client connection is closed. If this option is set to ignore (the default setting), verification fails only when a certificate is presented by the server and the certificate is expired or malformed.


To verify server certificates using the Configuration utility
  1. From navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Server Certificate field, select require or ignore from the box.
  4. Click Done.

To verify server certificates from the command line

Specify this option as serverssl server cert on the bigpipe proxy command line. The following command shows an example:

b proxy <ip>:<service> serverssl server cert require


Authentication depth

In addition to the option to require or ignore a certificate presented by the server, SSL-to-Server has an option to specify the maximum number of certificates that can be traversed in a server certificate chain.


To configure certificate traversal using the Configuration utility
  1. From navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Authentication depth box, type a whole number. The default setting is 9.
  4. Click Done.

To configure certificate traversal from the command line

On the bigpipe proxy command line, this option is specified as serverssl authenticate depth, followed by a whole number representing the maximum number of certificates to be traversed. The following command shows an example.

b proxy <ip>:<service> serverssl authenticate depth 8


Certificate revocation

The SSL proxy feature includes support for certificate revocation lists (CRLs). This CRL support is in the form of a CRL file and a CRL path. Like the Trusted CAs files and paths, the proxy enables you to configure one CRL file and path for the client-side proxy, and one CRL file and path for the server-side proxy.

When specifying a CRL path (client-side or server-side), you can also generate symbolic links for each CRL.

CRL files can become outdated, and might need to be updated as often as every day, or as seldom as every 30 days. If your CRL file is out-of-date, the BIG-IP system rejects all certificates, both valid and invalid. For this reason, it is important to keep your CRL files up-to-date at all times. You can do this by issuing the following command from the /config/bigconfig/ssl.crl directory: openssl crl -in <crlname> -text -noout.


Client-side certificate revocation

To configure CRLs for a client-side proxy, you might need to configure the following elements:

  • The Client CRL file
    The Client CRL file contains a list of revoked client certificates. When specifying a list of revoked client certificates, the file that you specify must be a PEM-formatted file.
  • The Client CRL path
    The path name you specify is the path to a directory with CRLs and corresponding symbolic links. If the CRL path is not specified or accessible, the proxy uses the path /config/bigconfig/ssl.crl/ by default.
  • Symbolic links to revoked certificates
    Generating symbolic links for CRLs ensures that each file in the path is linked to a revoked certificate. Once these links are generated, authentication fails if a client presents a revoked certificate as part of the client authentication process.

    The procedures for specifying a client CRL file and a client CRL path, and for generating symbolic links to revoked client certificates follow.


To specify the Client CRL file, Client CRL path, and symbolic-link generation using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the boxes Client CRL File and Client CRL Path, either select the name of a CRL file or path from the box, or type the name of a CRL file or path.
  4. If you want to ensure that each certificate has a link to its corresponding file, check the Generate Symbolic Links for Client CRL Path check box. You should do this whenever you specify any of the path attributes.
  5. Click Done.

To specify the Client CRL file and Client CRL path from the command line

To specify the Client CRL file and Client CRL path from the command line, type the bigpipe proxy command, using the appropriate arguments, as follows. Note that this command does not generate the symbolic links necessary for the CRL path. For information on generating symbolic links from the command line, see the next procedure.

b proxy <ip>:<service> [clientssl] crl file <clientside crl file name>

b proxy <ip>:<service> [clientssl] crl path <clientside crl path name>


To generate symbolic links for a client CRL path from the command line

To generate symbolic links from the command line, you must use the UNIX make command. The procedure is as follows.

  1. Use the UNIX cd command to change to the directory containing the CRLs.
  2. Run the following command as shown:

    make -f /config/bigconfig/ssl.crl/Makefile

  3. Restart the SSL proxy by either running the proxyd command from the command line or by reconfiguring the proxy in the Configuration utility.

Note


Whenever you subsequently add, remove, or modify CRLs, you must run the make command again (only if a client CRL path is specified) and restart the SSL proxy again, as described in Steps 2 and 3 above. This causes the changes to take effect.

Server-side certificate revocation

To configure CRLs for a server-side proxy, you might need to configure the following elements:

  • The Server CRL file
    The Server CRL file contains a list of revoked server certificates. When specifying a list of revoked server certificates, the file that you specify must be a PEM-formatted file.
  • The Server CRL path
    The path name you specify is the path to a directory with CRLs and corresponding symbolic links. If the CRL path is not specified or accessible, the proxy uses the path /config/bigconfig/ssl.crl/ by default.
  • Symbolic links to revoked certificates
    Generating symbolic links for CRLs ensures that each file in the path is linked to a revoked certificate. Once these links are generated, authentication will fail if a server presents a revoked certificate as part of the server authentication process.

The procedures for specifying a server CRL file or a server CRL path, and for generating symbolic links to revoked server certificates follow.


To specify the Server CRL file and Server CRL path using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the boxes Server CRL File and Server CRL Path, either select the name of a CRL file or path from the box, or type the name of a CRL file or path.
  4. If you want to ensure that each certificate has a link to its corresponding file, check the Generate Symbolic Links for Server CRL Path check box. You should do this whenever you specify any of the path attributes.
  5. Click Done.

To specify the Server CRL file and Server CRL path from the command line

To specify the Server CRL file and Server CRL path from the command line, type the bigpipe proxy command, using the appropriate arguments, as follows:

b proxy <ip>:<service> serverssl crl file <serverside crl file name>

b proxy <ip>:<service> serverssl crl path <serverside crl path name>


To generate symbolic links for a server CRL path

For the procedure on generating symbolic links for a server CRL path, use the procedure described in To generate symbolic links for a Client Trusted CAs path from the command line .


Using the Key Management System

Managing certificates and public-private key pairs can be confusing, especially when you have more than one proxy defined. To help you manage certificates and keys, the BIG-IP system provides a set of key management screens within the Configuration utility.

Collectively, these screens are known as the Key Management System (KMS).

The Configuration utility includes a set of screens for managing key pairs and certificates. Available under the Cert Admin tab on the main Proxies screen, these screens allow you to:

  • List information about all existing key pairs and certificates
  • Generate new key pairs and certificate requests
  • Regenerating certificate requests
  • Install certificates for existing key pairs
  • Associate certificates with proxies
  • Displaying a key, certificate, and SSL proxy properties
  • Import and export PEM-formatted keys and certificates
  • Import and export non-PEM-formatted keys and certificates (packaged archives only)

The following sections describe these features and how to use them.


Administering keys and certificates

Summary information about existing key pairs and certificates is available on the SSL Certificate Administration screen, available from the main Proxies screen. Figure 7.7 shows an example of the SSL Certificate Administration screen.

Figure 7.7 The SSL Certificate Administration screen

The SSL Certificate Administration screen displays the following information:

Key List
The list of identification names associated with existing key pairs. Note that only the first 20 characters of a key name appear in this box. To see a key name that exceeds 20 characters, click on the key name and view its properties.

Security Type
The type of key. Possible values are NONE and FIPS. This column only appears if you have the FIPS-140 Accelerator option installed.

Certificate ID
The identification name of the certificate associated with the key pair. Note that only the first 20 characters of a certificate ID appear in this box. To see a certificate ID that exceeds 20 characters, click on the certificate ID and view its properties.

Expires
The date on which the certificate expires. Expired dates appear in red.

CA
The certificate authority that issued the certificate. Self-signed certificates, (where the issuer and the subject are the same), are indicated as Self.

Generate
A button that displays the Generate Certificate Request screen, used to generate a certificate for the key pair shown. This button only appears when no certificate request has been generated for the key shown.

Install
A button that displays the Install Certificate screen, used to install a certificate for the key pair shown. This button only appears when no certificate is installed for the key shown.

Generate New Key Pair/Certificate Request
A button that displays the Generate New Key Pair/Certificate Request screen, used to generate a new key pair and request a certificate for that key pair.

The following procedures describe how to use the SSL Certificate Administration screen.


To list key pair and certificate information
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. When finished, click Done.

Generating keys and certificate requests

Using the SSL Certificate Administration screen within the Configuration utility, you can either generate a certificate request for an existing key pair, or you can generate a new key pair and certificate request.


To generate a certificate request for an existing key pair
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Key List column, locate the key pair for which you want to generate a certificate request.
  4. In the Certificate ID column, click Generate.
    This displays the Create Certificate Request screen.
  5. Type in the data for all boxes on the screen.
  6. Click the Generate Certificate Request button.

To generate a new key pair and certificate request
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Generate New Key Pair/Certificate Request button.
    This displays the Create Certificate Request screen.
  4. Type in the data for all boxes on the screen.
  5. Click the Generate Key Pair/Certificate Request button.

Regenerating certificate requests

If you already have a certificate for an existing key pair, and want to regenerate that certificate, use the following procedure.


To regenerate a certificate for an existing key pair
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Certificate ID column, click on the certificate that you want to regenerate.
    The Certificate Properties screen displays.
  4. Click the Request Certificate button.

Installing certificates

Using the SSL Certificate Administration screen within the Configuration utility, you can install a certificate for an existing key pair. Also, if you have regenerated a certificate for an existing key pair (see Regenerating certificate requests, you can install that certificate, using the Certificate Properties screen. To perform these tasks, use the following procedures.


To install a certificate for an existing key pair
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Key List column, locate the key pair for which you want to install a certificate.
  4. In the Certificate ID column, click Install.
    This displays the Install SSL Certificate screen.
  5. Select either Option 1 or Option 2 and follow the instructions on the screen.
  6. In the Certificate Identifier box, type a name for the certificate, or choose a name from the list. This name constitutes the certificate ID.
  7. Click the Install Certificate button.

To install a regenerated certificate
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Certificate ID column, click on the certificate that you regenerated.
    The Certificate Properties screen displays.
  4. Click the Install Certificate button.

Displaying properties

You can display the properties of a certificate or an SSL proxy, using the following procedures.


To display certificate properties
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Certificate ID column, click the certificate ID for which you want to view properties.
    This displays all properties of that certificate.
  4. Click Return to Certificate Administration.

To display SSL proxy properties
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Proxy Associations tab.
    This displays the SSL Certificate Proxy Associations screen.
  4. Select the proxy for which you want to view properties.
    This displays all properties of the selected proxy.
  5. Click Return to Certificate Administration.

Deleting keys and certificates

You can delete keys and certificates, using the following procedure.


To delete keys and certificates
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Key List column, identify the keys and certificates you want to delete.
  4. If a trashcan icon appears in the Delete column, click the trashcan.
    This deletes the keys and certificate. If no trashcan icon appears in the Delete column, you cannot delete the keys and certificates because they are associated with a proxy.

Note


A trashcan icon does not appear in the Delete column for a key pair and certificate if the associated SSL proxy is currently in use.

Binding a certificate to a key

Sometimes, a certificate ID does not match the key ID of the key used to create the certificate. This causes the certificate to lack an associated key. For example, certificate xyz might have been created using key abc. In this case, the certificate xyz is not bound to key abc. You can correct this problem by binding the certificate to the key.


To bind a certificate to a key
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Certificate ID column, click the name of the certificate that you want to bind to a key.
    This displays all properties of that certificate.
  4. In the Associated Key box, choose the key to which you want to bind the certificate.
  5. Click Apply.

Associating certificates with SSL proxies

Once you have generated a key pair and installed a certificate for that key pair, you can use the Proxy Associations screen to add a proxy for an existing certificate. You can also use this screen to view the properties of an existing proxy.


To add a proxy for an existing certificate
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Proxy Associations tab.
    This shows all existing key pairs and certificates and the proxies to which they are assigned, if any.
  4. Identify the keys and certificate that you want to associate with a new proxy.
  5. In the Add Server column, click the corresponding Add button.
    This opens the Add Proxy wizard, which is the same wizard that is available from the main Proxies screen. Note that if the proxy you are adding is a client-side proxy, the key and certificate fields are automatically filled in on the Add Proxy screen with the names of the corresponding keys and certificate.
  6. Enter all pertinent information into the appropriate fields. For detailed information on creating a proxy, see Creating an SSL Accelerator proxy .
  7. Click Done.

Importing keys and certificates

With the Import tab, you can import either an exported key pair, certificate, or a key/certificate archive into the Key Management System. This screen can only be used when the certificate you are importing is in Privacy Enhanced Mail (PEM) format.


To import a key pair
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Import tab.
    This displays the SSL Key/Certificate/Archive Import screen.
  4. In the Import Type box, choose the Key button.
  5. Click Continue.
    This displays the Install SSL Key screen.
  6. Follow the instructions on the screen to install the key that you want to import.
  7. Click Install Key.
    This installs the key and displays its properties.

To import a certificate
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Import tab.
    This displays the SSL Key/Certificate/Archive Import screen.
  4. In the Import Type box, click the Certificate button.
  5. Click Continue.
    This displays the Install SSL Certificate screen.
  6. Follow the instructions on the screen to install the certificate that you want to import.
  7. Click Install Certificate.
    This installs the certificate and displays its properties.

To import a key/certificate archive
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Import tab.
    This displays the SSL Key/Certificate/Archive Import screen.
  4. In the Import Type box, choose the Archive button.
  5. Click Continue.
    This displays the Choose SSL Key/Certificate Archive screen.
  6. Type in an archive file name or use the Browse button to select it.
  7. Click Continue
    This displays the Import Archive screen.
  8. Using the left and right arrows on the screen, select the keys and certificates from the archive that you would like to import.
  9. Click Install Included Items.

Exporting keys and certificates

The Export screen enables you to export a key/certificate archive from the key management system for the purpose of transferring them to another SSL proxy on the network. Once you have exported the selected keys, certificates, or key pair/certificate archives, you can use the KMS Import function to download them to the target SSL proxy.

The Export screen can only be used when the certificate you are exporting is in Privacy Enhanced Mail (PEM) format. Therefore, you cannot export FIPS keys, that is, keys generated on a FIPS-140 system.


To export a key pair
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Export tab.
    This displays the SSL Key/Certificate/Archive Import screen.
  4. In the Export Type box, click the Key button.
  5. From the list box, select a key pair name.
  6. Click Continue.
  7. Follow the instructions on the screen.

To export a certificate
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Export tab.
    This displays the SSL Key/Certificate/Archive Import screen.
  4. In the Export Type box, click the Certificate button.
  5. From the list box, select a certificate name.
  6. Click Continue.
  7. Follow the instructions on the screen.

To export a key/certificate archive
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. Click the Export tab.
  4. In the Export Type box, click the Archive button.
  5. From the list box, select an archive name.
  6. Click Continue.
  7. Using the left and right arrows on the screen, select the keys and certificates that you would like to include in the archive.
  8. Click Download Archive.

Converting keys on a FIPS-140 system

If you have a FIPS system, and that system has non-FIPS keys installed on it, you can perform a one-way conversion of those keys from non-FIPS to FIPS.


To convert non-FIPS keys to FIPS keys
  1. In the navigation pane, click Proxies.
  2. Click the Cert Admin tab.
  3. In the Key List column, click the key that you want to convert.
    This displays all properties of that key.
  4. In the Type box, select FIPS.
  5. Click Apply.
  6. When prompted, confirm the one-way conversion action.

Storing private keys securely

Private keys are traditionally stored as plain text on hard disks, where they are susceptible to tampering or theft. For SSL proxy keys, however, you can avoid this risk by using the keys of a FIPS-140 Hardware Security Module (HSM). Such keys conform to government-approved security standards. For more information, see Platform Guide: 520/540.

Note


Multiple-vendor HSMs are incompatible within the same BIG-IP system.

Encryption and decryption

One of the functions of the SSL proxy is to handle encryption and decryption tasks that are normally performed by a web server as part of processing a client request. When configured as a client-side-only proxy, the proxy decrypts incoming requests before sending them on in plain text to the target server. When the SSL-to-Server feature is enabled, the proxy provides an additional level of security by re-encrypting the request before sending it on to the target server.

Figure 7.8 shows how a client-side proxy encrypts and decrypts application data as it passes from client to server and back again.

Figure 7.8 Encryption and decryption with client-side proxy

Figure 7.9 shows how a client-side proxy with SSL-to-Server enabled encrypts and decrypts application data as it travels on the same route as the packet shown in Figure 7.8 .

Figure 7.9 Encryption and decryption with SSL-to-Server enabled

In addition to creating a client-side proxy and enabling the SSL-to-Server feature, you can configure other encryption options. Table 7.4 summarizes these options.

 

Configuration Option

Description

Specifying SSL ciphers

Allows you to specify to client and servers the specific ciphers the proxy can support.

Inserting cipher specifications into HTTP requests

Allows you to insert cipher specifications as headers into HTTP requests and then direct the connection based on the cipher specified.

 

The following sections describe these options and the procedures for configuring them.


Specifying SSL ciphers

For each SSL proxy, you can specify the ciphers available for SSL connections.

When configuring ciphers, you must ensure that the ciphers configured for the SSL proxy match those of the client sending a request, or a server sending a response.

For example, a client might connect to and successfully establish an SSL connection to an SSL proxy that is configured to use both client-side and server-side SSL. After the client sends additional data (such as an HTTP request), the SSL proxy attempts to establish an SSL connection to a server. However, the SSL proxy might be configured to enable only 3DES ciphers for server-side SSL, and the servers might be configured to accept only RC4 ciphers. In this case, the SSL handshake between the SSL proxy and the server fails because there are no common ciphers enabled. This results in the client connection being closed. If the client is using a browser, the user is likely to receive an error message indicating that the web page failed to load.

You can configure the list of SSL ciphers that are available for both client-side and server-side SSL connections. Whether using the Configuration utility or the bigpipe proxy command, you can specify a string to indicate the available list of SSL ciphers, or you can use the default cipher string, DEFAULT. The DEFAULT cipher string is normally defined as ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH.

Use of the SSLv2 cipher is not recommended unless necessary. Therefore, concerned users should set the cipher string to DEFAULT:-SSLv2.

Note


The SSL proxy supports any combination of ciphers supported by OpenSSL version 0.9.6, except for the IDEA cipher suite. To see the complete syntax for the cipher list, see this OpenSSL web site: http://www.openssl.org/docs/apps/ciphers.html.
To configure a cipher list using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In either or both of the Client Cipher List String or Server Cipher List String boxes, type a properly-formatted string.
  4. Click Done.

To configure a cipher list from the command line

To specify a list of ciphers from the command line, specify the client-side cipher list or the server-side cipher list, using the following syntax:

b proxy <ip>:<service> [clientssl] ciphers \"quoted string\"
b proxy <ip>:<service> serverssl ciphers \"quoted string\"

Note that you can use the openssl ciphers command to test the validity of a cipher string. The syntax for this command is as follows:

openssl ciphers -v [cipherlist]

For example, the following command lists all OpenSSL ciphers, including NULL ciphers:

openssl ciphers -v 'ALL:eNULL'


Inserting cipher specifications into HTTP requests

The SSL proxy includes a powerful feature for managing your SSL traffic. This feature gives you the ability to insert headers into incoming requests, and then to direct the traffic based on the information in those headers.

One of the header types that the proxy can insert into an HTTP request is a specification of the cipher that the client used to encrypt its request. After configuring the proxy to insert this information into a request, you can then build a rule that reads the header, through use of the http_header variable, and directs the request to a specific pool of servers.

For more information on using this feature to control the destination of client requests, see Inserting headers into HTTP requests .

Authorization

Unlike authentication, authorization is not about trusting identity, but about controlling access to system resources. Once the SSL proxy has verified that a client or server can be trusted, the proxy can then control the connection's level and type of access to the destination content.

The SSL proxy configuration options that support access control for SSL connections are:

  • Inserting client certificate fields into HTTP requests
  • Limiting the number of concurrent client TCP connections
  • Client authorization with an LDAP database server

The following sections describe these authorization options.


Inserting client certificate fields into HTTP requests

One of the most useful ways to control a client's access to system resources is to configure a proxy to insert fields of a client certificate as headers into client requests. For example, properly configured, a proxy can insert the status of a client certificate as a header into a request, and then build a rule that uses the http_header variable to select the target web server based on that status.

For more information on using this header insertion feature to control the destination of client requests, see Inserting headers into HTTP requests .


Limiting concurrent TCP connections

When configuring the SSL proxy, you can define the maximum number of client TCP connections allowed per proxy.

If you define a value of 0, the BIG-IP system performs no limit-checking. There is no upper limit on the maximum number of connections allowed.


To specify the maximum number of allowed client TCP connections
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client TCP Connection Limit box, type a number.
  4. Click Done.

Configuring LDAP-based client authorization

For environments that include a Lightweight Directory Access Protocol (LDAP) server, an SSL proxy can perform authorization of client requests. Like the proxy authentication functions, part of client authorization is based on certificates. The other part of proxy authorization is based on user groups and roles that you define.

The remainder of this section is organized into the following topics:

  • Authorization types
  • Authorization models
  • Configuring client authorization on an SSL proxy

Note


The LDAP-based client authorization feature depends on external client authentication being configured through the Setup utility.

Authorization types

An authorization type is the type of database that the SSL proxy uses to store authorization data for client requests. Currently, the proxy supports one authorization type, known as LDAP. The name LDAP refers to the Lightweight Directory Access Protocol, on which the client authorization database is based.


Authorization models

Client authorization by an SSL proxy is based on an authorization model that you define. An authorization model consists of a set of LDAP parameter values that you define for a proxy. The proxy then uses these values when searching the database during client authorization. You can define multiple authorization models, each with a different set of parameter values, but you can assign only one model per proxy.

Figure 7.10 shows sample values for an authorization model as specified on the bigpipe authz command line.

Figure 7.10 Sample parameter values for an LDAP-based authorization model


bigpipe authz authmodel
method ldap \
cachetimeout 200 \

ldap searchtype certmap \
ldap servers 192.168.10.1:389 192.168.10.2 \
ldap admindn "cn=admin,dc=f5,dc=com" \
ldap adminpw "secret" \
ldap certmap base = "ou=AuthzLDAPCertMap,dc=f5,dc=com" \
ldap certmap key: "authzLDAPmap" \
ldap certmap useserial false \
ldap user key uid \
ldap group base "dc=f5,dc=com" \
ldap group key group \
ldap group member key member \
ldap valid groups webusers webadmin
bigpipe proxy 192.168.198.67:443 authz models authmodel
authz set remoteuser hdr enable
 

With an LDAP-based authorization model, a proxy can authorize clients based on signed client certificates issued by trusted CAs. Then, to further enhance the ability of the proxy to authorize client requests, an authorization model can also include parameters that specify groups and roles. Basing authorization on not only certificates but also groups and roles provides the flexibility you need to control client access to system resources.

The following sections describe these two methods of authorization.


Certificate-based authorization

During the process of authorizing a client, the proxy must search the LDAP database. When using certificate-based authorization, the proxy can search the LDAP database in three ways. The following sections describe these three distinct search types.

  • CERT - Comparing incoming certificates to certificates in the LDAP database
    Many LDAP server environments already incorporate certificates into the user profiles stored in the LDAP database. Therefore, one way of configuring authorization in LDAP server environments is to configure the proxy to compare an incoming certificate to the certificate stored in the LDAP database for the user associated with the client request. If the certificate is found in the user's LDAP profile, access is granted to the user and the request is granted.
  • CERTMAP - Searching for certificates in certificate-to-user mappings
    If you create an object and class that maps certificates to users in the LDAP database, you can then configure the proxy to search for a certificate in the map, and retrieve a user from that map. The proxy then checks to ensure that the user in the LDAP database is a valid user.
  • USER - Extracting usernames from incoming certificates
    If certificates are not stored in the LDAP database, you can configure the proxy to extract a user name from the certificate presented as part of the incoming client request. The proxy then checks to see if an entry for the user exists in the LDAP database. This scenario is a good choice for a company that acts as its own Certificate Authority, where the company is assured that if the certificate is verified, then the user is authorized.

Regardless of the type of certificate-based authorization being performed, the process yields the results shown in Table 7.5 .

 

Result of search

Authorization status

No records match

Authorization fails

One record matches

Authorization succeeds and is subject to groups and roles

Two or more records match

Authorization fails, due to invalid database entries

 

Group-based and role-based authorization

In addition to enabling certificate-based authorization, you can also configure authorization based on groups and roles.

  • Groups
    Because LDAP servers already have the concept and structure of groups built into them, the proxy can include groups in its authorization feature. To enable the use of groups for authorization purposes, you must indicate the base and scope under which the proxy will search for groups in the LDAP database. Also, you must specify attribute values for "group" and "member". Once these tasks have been completed, the proxy can search through the list of valid groups until a group is found that has the current user as a member.
  • Roles
    Unlike a group, a role is an attribute directly associated with a user. Any role-based authorization performed by the proxy depends on the LDAP database having the concept of roles built into it. To determine if a user should be granted access to a resource, the proxy searches through the roles assigned to the user and attempts to match that role to a valid role defined by the administrator.

Creating an authorization model

To fully implement SSL client authorization on the BIG-IP system, you must create an authorization model, consisting of a set of parameter values. Associated with the ldap authorization type, these parameters are normally configured, with default values, either through the Configuration utility or through the bigpipe proxy command. Table 7.6 lists and describes the configurable authorization parameters for an LDAP-based authorization model.

 

Authorization model parameters

Description

LDAP Basic Parameters

Method

The type of database being used for authorization. Currently, LDAP is the only method that can be specified.

Cache timeout

The length of time in seconds that items are kept in the authorization cache. Note that Configuration utility and the command line interface do no valid range-checking.

LDAP General Parameters

Server list

The list of IP addresses and port numbers for all of the potential LDAP servers.

Secure

A parameter that instructs the BIG-IP system to use secure LDAP communication (that is secure communication to the LDAP server using SSL) between the proxy and the LDAP server.

Admin distinguished name (DN)

The distinguished name of an account to which to bind, in order to perform searches. This "search" account is a read-only account used to do searches. The admin account can be used as the "search" account. If no admin DN is specified, then no bind is attempted. This parameter is only required when a site does not allow anonymous searches.

Admin password

A password for the "search" account created on the LDAP server.

LDAP Search Parameters

Search type

The certificate-based authorization method that the proxy uses when searching the LDAP database (described in Certificate-based authorization ). Possible values are USER, CERTMAP, and CERT.

User base

The search base for the subtree used by the USER and CERT search types. A typical search base is: ou=people,dc=company,dc=com.

Certificate map base

The search base for the subtree used by the CERTMAP search type. A typical search base is similar to the following: ou=people,dc=company,dc=com.

User key

The name of the attribute in the LDAP database that specifies a user ID. Used by the USER search type. A typical example of a user key value is uid.

Certificate map key

The name of the certificate map found in the LDAP database. Used by the CERTMAP search type.

Certificate serial number

The serial number of a certificate. Used for CERTMAP searches only, this parameter is used in combination with the certificate's issuer name, and replaces the subject DN. (A subject DN = country + state + city + org + common name + email.)

LDAP Filtering Parameters

Group base

The search base for the subtree used by group searches. This parameter is only used when specifying valid groups. A typical search base would be similar to the following: ou=people,dc=company,dc=com.

Group key

The name of the attribute in the LDAP database that specifies the group name in the group subtree.

Group member key

The name of the attribute in the LDAP database that specifies members (DNs) of a group.

Valid groups

A list of groups to which a user must belong in order to be authorized.

Role key

The name of the attribute in the LDAP database that specifies a user's authorization roles. This key is used only when using valid roles (as described in the following entry).

Valid roles

A list of roles. A user must be assigned to one of these roles in order to be authorized. Valid roles in this list are delimited by a space.

 

Note


For an example of an authorization model, see Figure 7.10 .
To create an authorization model using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. Click the Authorization Model tab.
    This displays the SSL Proxy Authorization Model List screen. Any authorization models that you have defined are listed.
  3. Click Add.
    This invokes the Add Authorization Model Wizard and displays the Configure Basic Properties screen.
  4. Type a name for the authorization model and a value for the Cache Timeout parameter. Note that the Method parameter has only one allowable value, LDAP, and therefore cannot be changed.
  5. Click Next.
    This displays the Configure LDAP General Properties screen.
  6. Type values for the parameters listed and click Next.
    This displays the Configure LDAP Search Properties screen.
  7. Enter a value for the User Key parameter.
  8. Select either the User, Certificate, or Certificate Map button, and type in the corresponding value or values for that search type.
  9. If you chose the User search type, click Next. Otherwise, proceed to Step 11.
    Clicking Next displays the Configure LDAP Filtering Properties screen.
  10. Type in values for the Group and Role parameters listed and click Done.
  11. If you chose the Certificate or Certificate Map search type, click Done.

To create an authorization model from the command line

Use the bigpipe authz command, as shown in the following command syntax.

b authz <name> [method (ldap|...)]
[cachetimeout <number>]
[ldap searchtype (user|certmap|cert)]
[ldap servers <server list>]
[ldap secure (enable | disable)]
[ldap admindn <string>]
[ldap adminpw <string>]
[ldap user base <string>]
[ldap user key <string>]
[ldap certmap base <string>]
[ldap certmap key <string>]
[ldap certmap useserial <string>]
[ldap group base <string>]
[ldap group key <string>]
[ldap group member key <string>]
[ldap valid groups <string list>]
[ldap role key <string>]
[ldap valid roles <string list>]

Note


Once you have created an authorization model, you must associate that model with an SSL proxy. For detailed procedures, see Associating an authorization model with an SSL proxy .
Viewing authorization model properties

Through the Configuration utility, you can view at a glance all of the parameter values that make up an existing authorization model.


To view the properties of an authorization model using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. Click the Authorization Model tab.
    This displays the SSL Proxy Authorization Model List screen, which lists any authorization models that you have defined.
  3. Click an authorization model.
    This displays all of the parameter values defined for that model.

To view the properties of an authorization model from the command line

b proxy <ip_addr>:<service> authz models show


Configuring client authorization options on an SSL proxy

Table 7.7 lists and describes the authorization options that you can configure on an SSL proxy, after you have defined an authorization model.

 

SSL proxy authorization options

Description

Specifying an authorization header

Creates a standard HTTP header for authorization that is set to a server with the UID from the LDAP database.

Specifying a remote user header

Creates a standard HTTP header for remote users that is set to the UID used in the authorization.

Associating an authorization model with an SSL proxy

Specifies the name of an authorization model that you want to associate with an SSL proxy.

Setting the authorization failure mode

Determines, on authorization failure, whether the BIG-IP system terminates a client connection or allows the connection to pass through.

Specifying an authorization failure user name

Specifies a user name that is used when the user name in the LDAP database cannot be accessed due to authorization failure.

 

Specifying an authorization header

This option creates an authorization header. The value of this option can be either true or false. If true, the authorization header is created and set to the value of a server with the uid from the LDAP database. If false, no authorization header is created. The default value is false.


To insert an authorization header using the Configuration utility
  1. From navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Insert Authorization Header box, click the check box.
    This sets the value to true.
  4. Click Apply.

To insert an authorization header from the command line

b proxy <ip_addr>:<service> authz set auth hdr enable


Specifying a remote user header

This option creates a remote user header. The value of this option can be either true or false. If true, the HTTP remote user header is set to the UID used in the authorization. If false, the HTTP remote user header is not created or modified. The default value is false.


To insert a remote user header using the Configuration utility
  1. From navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Insert Remote-User Header box, click the check box.
    This sets the value to true.
  4. Click Done.

To specify a remote user header from the command line

b proxy <ip_addr>:<service> authz set remoteuser hdr \ enable


Associating an authorization model with an SSL proxy

This option specifies the name of an existing authorization model that you want to associate with an SSL proxy. You can make this association either at the time that you are creating the SSL proxy, or at any time after creating the proxy.

The following procedures show how to assoicate an authorization model with an existing SSL proxy.


To associate an authorization model with an existing SSL proxy using the Configuration utility
  1. In the navigation pane, click Proxies.
    The Proxies screen opens.
  2. Click a proxy name.
  3. Click the Advanced Properties tab.
  4. From the Authorization Model list, select the name of an authorization model that you previously created using the Add Authorization Model Wizard.
  5. Click Done.

To associate an authorization model with an existing SSL proxy from the command line

Use the bigpipe proxy command, as follows:

b proxy <ip_addr>:<service> authz models <models list>


Setting the authorization failure mode

This option determines, on authorization failure, whether the BIG-IP system terminates a client connection or allows the connection to pass through. Allowed values are accept and reject. The default value is reject.


To set the authorization failure mode using the Configuration utility
  1. From navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Authorization Failure Mode box, select either accept or reject.
  4. Click Done.

To set the authorization failure mode from the command line

b proxy <ip_addr>:<service> authz onfailure model accept | \ reject


Specifying an authorization failure user name

This option specifies a user name that is used when the user name in the LDAP database cannot be accessed due to authorization failure. This option only applies when the Authorization Failure Mode option is set to accept.


To specify an authorization failure user name using the Configuration utility
  1. From navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Authorization Failure User Name box, type a user name to be used in the header.
  4. Click Done.

To specify an authorization failure user name from the command line

b proxy <ip_addr>:<service> authz onfailure username <username>

Network traffic control

The SSL proxy provides several configuration options that you can use to control your SSL traffic in certain ways. Table 7.8 summarizes these options.

 

Configuration Option

Description

Inserting headers into HTTP requests

Controls traffic by inserting custom headers, cipher specifications, client certificate fields, and session IDs into HTTP requests.

Rewriting HTTP redirections

Rewrites any HTTP redirection, as a way of ensuring that a connection remains on a secure channel.

Adding a lasthop pool to an SSL proxy

Sets up a lasthop pool that takes precedence over the auto_lasthop global variable. Replies are sent back through a router defined in the lasthop pool instead of the same router through which the request was originally received.

Disabling ARP requests

Disables all ARP requests for a proxy IP address.

Configuring proxy failover

Configures a redundant system so that failover from one unit to another occurs automatically, in the event of a cryptographic accelerator failure.

 

Inserting headers into HTTP requests

You can configure the SSL proxy to insert several kinds of headers into an HTTP client request. They are:

  • A custom HTTP header
  • Cipher specification
  • Client certificate fields
  • Client session IDs

If any of these header types is inserted into a valid HTTP request, the SSL proxy places the headers so that they immediately follow the first line of the request. If more than one header is inserted, the headers are inserted in the order listed above.


Security Considerations

Before using the header insertion feature, you should be aware of the following security considerations:

  • If a client request uses a non-standard HTTP method, or the request is pipelined, the SSL proxy might not be able to insert headers, and in some cases, the entire connection might fail. Moreover, when the request does not fail, it is possible to mistake HTTP headers supplied by the client for those inserted by the SSL proxy. Therefore, if you are making security decisions based on the value of inserted headers, you should ensure that the client request uses a standard HTTP method or that the request is not pipelined. The standard HTTP methods that the BIG-IP system currently supports are: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT, as well as all currently-standardized WebDAV methods.
  • Using the HTTP header insertion feature is not recommended when the SSL proxy targets a virtual server that is directly accessible to client connections. This is because a header could be mistakenly construed by the system as an indication that the connection came through the SSL proxy. Instead, the header could have been generated by the client itself when connecting directly to the virtual server. If you have configured your system to deliver certain content only to connections terminated by the SSL proxy, you should avoid using the proxy header insertion feature, when that proxy targets an externally-accessible virtual server. It is recommended that virtual servers intended to be accessed by SSL proxy connectinos only be configured with IP addresses on the loopback interface, for example 127.0.0.10.

Warning


The header insertion feature applies to HTTP requests only and should be enabled only on proxies that are configured to listen on HTTPS ports, such as port 443.

The following sections describe the four header types that you can insert into HTTP requests.


A custom HTTP header

When adding an SSL proxy, you can configure the proxy to insert a string of your choice, consisting of up to 253 characters, into an HTTP request. This feature is useful for custom applications, as well as for securing content. For example, when the Outlook Web Access application detects the presence of a particular custom HTTP header, the application generates embedded URLs using the protocol HTTPS instead of HTTP.

A properly-formatted custom HTTP header is in the form of Field: Value. Note that an improperly-formatted custom HTTP header could cause the content server to fail in its handling of proxied requests.


To insert a custom header using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Insert HTTP Header String box, type a custom HTTP header in the form of Field: Value.
  4. Click Done.

To insert a custom header from the command line

To insert a custom header into an HTTP request using the command line, specify the header insert argument with the bigpipe proxy command, as follows:

b proxy <ip>:<service> header insert \"header:value\"


A cipher specification

When adding an SSL proxy, you can configure the proxy to insert information about the negotiated SSL cipher into an HTTP request. When you configure this option, the SSL proxy inserts the actual cipher name, the SSL version, and the number of significant bits into the HTTP request.

An inserted cipher specification header is in the form SSLClientCipher: [cipher] version=[version] bits=[bits], where [cipher], [version], and [bits] represent the actual cipher name, version, and number of significant cipher bits, respectively. For example, the following is a possible cipher specification inserted as a header into an HTTP request:

"SSLClientCipher: DES-CBC3-SHA, version=TLSv1/SSLv3, bits=168"

The ability to insert a cipher specification into a client request is useful because you can then build a rule that directs traffic based on the cipher specified in the request header. For example, you can build a rule, using the http_header rule variable,that directs requests with unacceptable cipher strengths to a cipher upgrade path, instead of discarding the sessions altogether.

Figure 7.11 shows an example of a rule that directs traffic based on the cipher specified in the request header.

Figure 7.11 A rule based on cipher strength specified in an HTTP header


if (exists http_header "SSLClientCipher") {
if (http_header "SSLClientCipher" contains "bits >= 128") {
use ( secure_pool )
}
else {
redirect to "<https://%h/upgradebrowser.html>"
}
}
else {
redirect to "<https://%h/servererror.html>"
}
 

To insert a cipher specification using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. Check the Insert Cipher check box.
  4. Click Done.

To insert a cipher specification from the command line

Specify the cipher insert argument with the bigpipe proxy command, as follows:

b proxy <ip>:<service> [clientssl] cipher insert <enable | disable>


Client certificate fields

When adding an SSL proxy, you can configure the proxy to insert, into an HTTP request, a header for almost every field of a client certificate. This feature is most useful when:

  • You have configured the SSL proxy to authenticate clients with the request option. Because client authentication always succeeds in this case, despite status of the certificate, you might want the proxy to insert information into the HTTP request about the client certificate and the results of the verification attempt. Based on this information, the BIG-IP system or a server could then perform actions such as redirecting the request to another server, or sending different content back to the client. For more information, see Configuring the presentation of client certificates .
  • You want to better control the load balancing of your network traffic. In this case, you can create a rule that performs load balancing according to the certificate information in the header. Figure 7.12 shows an example.

Figure 7.12 A rule based on certificate status specified in an HTTP header


if (exists http_header "SSLClientCertStatus") {
if (http_header "SSLClientCertStatus" contains "OK") {
use ( authenticated_pool )
}
else {
redirect to "<https://%h/authenticationfailed.html>"
}
}
else {
redirect to "<https://%h/servererror.html>"
}
 


Table 7.9 shows the client certificate headers that the SSL proxy can insert into a client request. For each header, the format, description, and keyword are shown.

 

Header Name

Format

Description

Certificate status

SSLClientCertStatus: [status]

The status of the client certificate. The value of [status] can be "NoClientCert", "OK", or "Error". If status is "NoClientCert", only this header is inserted into the request. If status is "Error", the error is followed by a numeric error code.

Certificate version

SSLClientCertVersion: [version]

The version of the certificate.

Certificate serial number

SSLClientCertSerialNumber: [serial]

The serial number of the certificate.

Signature algorithm of the certificate

SSLClientCertSignatureAlgorithm: [alg]

The signature algorithm of the certificate.

Issuer of the certificate

SSLClientCertIssuer: [issuer]

The issuer of the certificate.

Certificate validity dates

SSLClientCertNotValidBefore: [before]
SSLClientCertNotValidAfter: [after]

The validity dates for the certificate. The certificate is not valid before or after the dates represented by [before] and [after], respectively.

Certificate subject

SSLClientCertSubject: [subject]

The subject of the certificate.

Public key of the subject

SSLClientCertSubjectPublicKey: [key]

The type of public key type. The allowed types are "RSA ([size] bit)", "DSA", or "Unkown public key".

The certificate itself

SSLClientCert: [cert]

The actual client certificate.

MD5 hash of the certificate

SSLClientCertHash: [hash]

The MD5 hash of the client certificate.

 

Tip


When inserting a client certificate into a request, it is recommended for performance reasons that you insert the hash of a certificate, rather than the entire certificate itself. You can do this by using the SSLClientCertHash: [hash] header.
To insert fields of a client certificate using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Insert Certificate section, check the appropriate check boxes.
  4. Click Done.

To insert fields of a client certificate from the command line

To insert headers for the fields of a client certificate into an HTTP request using the command line, specify the client cert insert argument with the bigpipe proxy command, as follows:

b proxy <ip>:<service> [clientssl] client cert insert \ <([versionnum] [serial] [sigalg] [issuer] [validity] [subject] \ [subpubkey] [whole] [hash])+ | disable>

Note


The status header is always inserted automatically whenever one or more client certificate headers are configured to be inserted, and therefore is not specified in the Configuration utility or on the command line.

Client session IDs

Client session IDs inserted as headers into HTTP requests, combined with use of universal persistence, provides a way to implement persistence for terminated SSL connections.

For unterminated connections, that is, when you have not created an SSL proxy, you can implement SSL persistence simply by configuring the SSL persistence attribute (ssl) on the pool that is receiving the SSL connections.

For terminated connections, that is, when you have created an SSL proxy, you implement SSL persistence in a different way--by inserting client session IDs as headers into HTTP requests, and then configuring universal persistence on the target pool. The SSL proxy contains a configuration option that you can use to insert a client session ID as a header into an HTTP request.

Note


The ssl persistence type is not supported on any virtual server that is the target of an SSL proxy. However, other persistence types are supported on vitual servers to which proxy connections are targeted. For information on persistence types, see Chapter 4, Pools .

The header that is inserted can be one of two types:

  • A header in which the session ID is the session ID initially negotiated with the client for the corresponding TCP connection. The proper format of this header is SSLClientSessionID:X, where X represents the hexidecimal representation of the SSL session ID that was initially negotiated with the client for the corresponding TCP connection.
  • A header in which the session ID is the current session ID. The proper format of this header is SSLClientCurrentSessionID:X, where X represents the current SSL session ID.

If you enable the insertion of session ID headers, but specify neither of these two types of session IDs, the SSL proxy inserts the session ID initially negotiated with the client.

Note


For information on enabling universal persistence based on client session IDs , see Chapter 4, Pools .
To insert a session ID header using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Insert Client Session ID section, check either or both of the Initial and Current check boxes.
  4. Click Done.

To insert a session ID header from the command line

To insert a session ID header into an HTTP request using the command line, specify the sessionid insert argument with the bigpipe proxy command, as follows:

b proxy <ip>:<service> [clientssl] sessionid insert [initial] [current] [enable]


Rewriting HTTP redirection

One of the attributes you can set on a BIG-IP pool is HTTP redirection. Configured as a pool attribute, HTTP redirection redirects a client request to another protocol identifier, host name, port number, or URI path. For example, a pool might be configured to redirect a request from the HTTPS protocol to the HTTP protocol.

When a client request is redirected from the HTTPS to the HTTP protocol, an SSL proxy can rewrite that redirection back to HTTPS. (Specifically, this applies to HTTP responses 301, 302, 303, 305, and 307). This ability for the SSL proxy to rewrite HTTP redirections provides additional security by ensuring that client requests remain on a secure channel.

Another reason to configure a proxy to rewrite HTTP redirections pertains to IIS and Netscape web-server environments. Without a BIG-IP proxy, a web server running IIS and Netscape redirects a request incorrectly, if the original request included a malformed directory name (without a trailing slash [/]). An SSL proxy has the ability to rewrite this incorrect redirection.

Note that the rewriting of any redirection only takes place in the HTTP Location header of the redirection response, and not in any content of the redirection.

Note


An alternative to configuring an SSL proxy to rewrite this type of redirection is to install a special BIG-IP file, redirectfilter.dll, on your IIS server. Once this file is installed, the IIS server can handle any rewriting of HTTP redirections, without the help of the SSL proxy. For background information, see Redirecting HTTP requests .

To enable the proxy to rewrite HTTP redirections, you simply specify, through either the Configuration utility or the bigpipe proxy command, the way that you want the proxy to handle URIs during the rewrite. Once enabled, this feature rewrites the protocol name and the port number. The following sections describe proxy behavior when the rewrite feature is enabled.


Selecting URIs to rewrite

When configuring the SSL proxy to rewrite HTTP redirections, you specify whether the proxy should rewrite only those URIs matching the URI originally requested by the client (minus an optional trailing slash), or all URIs. In the latter case, the SSL proxy always rewrites redirected-to URIs, and rewrites those URIs as if they matched the originally-requested URIs.

Table 7.10 shows examples of how redirections of client requests are transformed when the SSL proxy is listening on port 443 and the rewrite feature is enabled.

 

Original redirection

Rewrite of Redirection with SSL Proxy Listening on Port 443

http://www.myweb.com/myapp/

https://www.myweb.com/myapp/

http://www.myweb.com:8080/myapp/

https://www.myweb.com/myapp/

 

Table 7.11 shows examples of how redirections of client requests are transformed when the SSL proxy is listening on port 4443 and the rewrite feature is enabled.

 

Original redirection

Rewrite of Redirection with SSL Proxy Listening on Port 4443

http://www.myweb.com/myapp/

https://www.myweb.com:4443/myapp/

http://www.myweb.com:8080/myapp/

https://www.myweb.com:4443/myapp/

 

Rewriting the protocol name

When configured to rewrite HTTP redirections, the SSL proxy rewrites the HTTP protocol name to HTTPS. For example, a client might send a request to https://www.sample.com/bar and be initially redirected to http://www.sample.com/bar/, which is a non-secure channel. If you want the client request to remain on a secure channel, you can configure the SSL proxy to rewrite the redirected URI to go to https://www.sample.com/bar/ instead. (Note the addition of the trailing slash.)


Rewriting the port number

In addition to rewriting the protocol name from HTTP to HTTPS, the SSL proxy rewrites the port number of the redirected request. This happens in the case when the web server and/or SSL proxy are listening on a non-standard port, for example, when the client request is initially redirected to http://www.sample.com:8080/bar/. In this case, the SSL proxy rewrites not only the protocol name but the port number also. If, however, the SSL proxy is listening on the standard HTTPS port 443, then the SSL proxy removes the 8080 port number, without replacing it with 443.


Configuration procedures for rewriting HTTP redirections

You can configure the rewrite feature using either the Configuration utility or the bigpipe proxy command.


To configure the rewrite feature using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Rewrite Redirects section, if you want to enable the feature, select either Matching or All. from the list. To disable the feature, do not select an option from the box. By default, the feature is disabled.
  4. Click Done.

To configure the rewrite feature from the command line

To configure this feature from the command line, type the bigpipe proxy command and specify the redirects rewrite argument, as follows:

b proxy <ip>:<service> redirects rewrite <<matching | all> [enable] | disable>


Adding a last hop pool to an SSL proxy

In cases where you have more than one router sending connections to a BIG-IP system, connections are automatically sent back through the same router from which they were received when the auto_lasthop global variable is enabled, as it is by default. If the global auto_lasthop is disabled for any reason (for example, you may not want it for a virtual server), or if you want to exclude one or more routers from auto_lasthop, you can direct your replies to the last hop router using a last hop pool. The lasthop pool takes precedence over auto_lasthop.

To configure a last hop pool, you must first create a pool containing the router inside addresses. After you create the pool, use the following syntax to configure a last hop pool for a proxy:

b proxy <ip>:<service> lasthop pool <pool_name>

For example, if you want to assign the last hop pool named ssllasthop_pool to the SSL proxy 11.12.1.200:443, type the following command:

b proxy 11.12.1.200:443 lasthop pool ssllasthop_pool


Disabling ARP resquests

By default, the BIG-IP system responds to ARP requests for proxy addresses and sends a gratuitous ARP request for router table update. If you want to disable the proxy address for ARP requests, you must specify arp disable.


Configuring SSL proxy failover

If you have a BIG-IP system redundant configuration, you might be able to configure the SSL proxy to initiate an automatic failover in the event of a fatal cryptographic hardware module failure. A fatal failure is the condition where the BIG-IP system, after having had an initial success communicating with the cryptographic accelerator module, subsequently receives a hardware error.

Not all cryptographic accelerator modules generate hardware errors upon failure. Thus, the ability to configure automatic SSL proxy failover depends on the type of accelerator module that you are using.

This option is configured globally, and by default is set to disable.

For redundant system configurations, you can also configure an option known as connection mirroring, on an individual virtual server . Connection mirroring mirrors connection information to the peer unit during failover. Be aware, however, that you cannot enable connection mirroring on a virtual server that is the target of an SSL proxy.


To configure SSL proxy failover using the Configuration utility
  1. In the navigation pane, click System.
  2. Click the Advanced Properties tab.
  3. In the Enabled box of the SSL Accelerator Failure area, check the box.
  4. Click Done.

To configure SSL proxy failover from the command line

To enable or disable the SSL proxy for failover from the command line, type the bigpipe global command with the appropriate arguments, as follows:

b global sslproxy failover <enable | disable>

Other SSL protocol options

In addition to the configuration options on an SSL proxy that allow you to control SSL-related functions such as certificate validation, verification, and revocation, the proxy offers other options related to the SSL protocol. Figure 7.12 lists and describes these options

 

Configuration Option

Description

Configuring invalid SSL protocol versions

Specifies the SSL protocol versions that the proxy will consider to be invalid.

Configuring the SSL session cache

Configures both the size and the timeout values for the SSL session cache.

Configuring SSL shutdowns

Configures the proxy to force clean SSL shutdowns, and to allow SSL sessions to resume after unclean shutdowns.

 

The remainder of this chapter describes these options and how to configure them.


Configuring invalid protocol versions

When configuring protocol versions, you must ensure that the protocol versions configured for the SSL proxy match those of the proxy's peer. That is, protocol versions for the client-side SSL proxy must match those of the client, and protocol versions for the server-side SSL proxy must match those of the server. Thus, for both client-side and server-side SSL connections, you can specify the protocol versions that are not allowed.

You can declare up to two of the following three protocol versions to be invalid: SSLv2, SSLv3, and TLSv1. If no protocol versions are specified, all SSL protocol versions are allowed.

Note


At a minimum, it is recommended that you specify SSLv2 as invalid.
To specify invalid protocol versions using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client-side Connections Do Not Use These SSL Versions section or the Server-side Connections Do Not Use These SSL Versions section, check the appropriate boxes.
  4. Click Done.

To specify invalid SSL protocol versions from the command line

To specify invalid SSL protocol versions, use the following syntax:

b proxy <ip>:<service> [clientssl] invalid [SSLv2] [SSLv3] [TLSv1]

b proxy <ip>:<service> serverssl invalid [SSLv2] [SSLv3] [TLSv1]


Configuring SSL session cache

For both client-side and server-side SSL connections, you can configure timeout and size values for the SSL session cache.

Because each proxy maintains a separate client-side SSL session cache, you can configure the client-side values on a per-proxy basis. For server-side SSL connections, however, the proxy maintains a single session cache. Thus, you must configure server-side session cache values globally.


Setting SSL session cache timeout

Using either the Configuration utility or the bigpipe command, you can specify the number of usable lifetime seconds of negotiated SSL session IDs. The default timeout value for the SSL session cache is 300 seconds. Acceptable values are integers greater than or equal to 5.

Clients attempting to resume an SSL session with an expired session ID are forced to negotiate a new session.

  • Client-side timeout values.
    The client-side timeout values are configured on a per-proxy basis.You can set client-side timeout values to zero, which represents no timeout.

Warning


If the timeout value for the client-side SSL session cache is set to zero, the SSL session IDs negotiated with that proxy's clients remain in the session cache until either the proxy is restarted, or the cache is filled and the purging of entries begins. Setting a value of zero can introduce a significant security risk if valuable resources are available to a client that is reusing those session IDs. It is therefore common practice to set the SSL session cache timeout to a length of time no greater than 24 hours, and for significantly shorter periods.
  • Server-side timeout values.
    A single, server-side timeout value is configured globally. This timeout value cannot be set to zero. For optimal performance, the timeout value should be set to the minimum SSL session cache timeout value used by the servers to which the proxy makes server-side SSL connections. Under certain conditions, the proxy attempts to efficiently negotiate a new server-side SSL session prior to its expiration.

To set the timeout value of the client-side SSL session cache using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client Session Cache Timeout box, type an integer greater than or equal to 5, or 0, or use the default value.
  4. Click Done.

To set the timeout value of the client-side SSL session cache from the command line

To set the timeout value of the client-side SSL session cache, type the bigpipe proxy command with the appropriate arguments, as follows:

b proxy <ip>:<service> [clientssl] cache timeout <num>


To set the timeout value of the server-side SSL session cache using the Configuration utility
  1. In the navigation pane, click System.
  2. Click the Advanced Properties tab.
  3. In the Server SSL Session Cache Timeout box, type zero or an integer greater than or equal to five, or use the default value.
  4. Click Done.
To set the timeout value of the server-side SSL session cache from the command line

To set the timeout value of the server-side SSL session cache, type the bigpipe global command with the appropriate arguments. as follows:

b global sslproxy serverssl cache timeout <num>


Setting SSL session cache size

Using either the Configuration utility or the bigpipe command, you can specify the maximum size of the SSL session cache. The default value for the size of the SSL session cache is 20,000 entries. A value of 0 disallows session caching.

You can configure the client-side values for the maximum size of the session cache on a per-proxy basis. You can configure a single, server-side value for the maximum size of the session cache globally.


To set the maximum size of the client-side SSL session cache using the Configuration utility
  1. In the navigation pane, click Proxies.
  2. Click the Add button.
  3. In the Client Session Cache Size box, type an integer or use the default value.
  4. Click Done.

To set the maximum size of the client-side SSL session cache size from the command line

To set the maximum size of the client-side SSL session cache from the command line, type the bigpipe proxy command with the appropriate arguments, as follows:

b proxy <ip>:<service> [clientssl] cache size <num>


To set the maximum size of the server-side SSL session cache using the Configuration utility
  1. In the navigation pane, click System.
  2. Click the Advanced Properties tab.
  3. In the Server SSL Session Cache Size box, type an integer or use the default value.
  4. Click Done.

To set the maximum size of the server-side SSL session cache from the command line

To set the maximum size of the server-side SSL session cache from the command line, type the bigpipe global command with the appropriate arguments. as follows:

b global sslproxy serverssl cache size <num>


Configuring SSL shutdowns

With respect to the shutdown of SSL connections, you can configure two global options on the BIG-IP system:

  • Forcing clean SSL shutdowns
  • Allowing SSL sessions to resume after unclean shutdown

The following sections describe these options.


Forcing clean SSL shutdowns

By default, the SSL proxy performs unclean shutdowns of all SSL connections, which means that underlying TCP connections are closed without exchanging the required SSL shutdown alerts. If you want to force the SSL proxy to perform a clean shutdown of all SSL connections, you can disable the default setting.

This feature is especially useful with respect to the Internet Explorer browser. Different versions of the browser, and even different builds within the same version of the browser, handle shutdown alerts differently. Some versions or builds require shutdown alerts from the server, while others do not, and the SSL proxy cannot always detect this requirement or lack of it. In the case where the browser expects a shutdown alert but the SSL proxy has not exchanged one (the default setting), the browser displays an error message.


To configure SSL shutdowns using the Configuration utility
  1. In the navigation pane, click System.
  2. Click the Advanced Properties tab.
  3. In the Force Unclean Shutdown Of All SSL Connections box, check or clear the check box.
  4. Click Done.

To configure SSL shutdowns from the command line

To configure SSL shutdowns from the command line, type the bigpipe global command with the appropriate arguments, as follows:

b global sslproxy unclean shutdown <enable | disable>


Resuming SSL sessions

In addition to forcing clean shutdowns, you can also configure the SSL proxy to prevent an SSL session from being resumed after an unclean shutdown. The default option is disable, which causes the SSL proxy to allow uncleanly shut down SSL sessions to be resumed. Conversely, when the enable option is set, the SSL proxy refuses to resume SSL sessions after an unclean shutdown.


To configure the SSL proxy to resume SSL sessions using the Configuration utility

You can allow the SSL proxy to resume, or prevent the SSL proxy from resuming, SSL sessions after an unclean shutdown.

  1. In the navigation pane, click System.
  2. Click the Advanced Properties tab.
  3. In the Strict SSL Shutdown Compliance (causes slower IE sessions) box, check or clear the check box.
    Clearing the box prevents the proxy from resuming SSL sessions after an unclean shutdown. Checking the box enables the proxy to resume SSL sessions after an unclean shutdown.
  4. Click Done.

To configure the SSL proxy to resume SSL sessions from the command line

To prevent the SSL proxy from resuming SSL sessions after an unclean shutdown, you can enable the strict resume global attribute on the SSL proxy, as follows:

b global sslproxy strict resume enable

To allow the SSL proxy to resume SSL sessions after an unclean shutdown, you can disable the strict resume global attribute on the SSL proxy, as follows:

b global sslproxy strict resume diable



Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)