11 Managing Security

This chapter describes how you can secure access to the Oracle Traffic Director administration server and enable SSL/TLS for Oracle Traffic Director virtual servers. It also describes how to configure client authentication and how you can use Oracle Traffic Director to secure access to origin servers.

This chapter contains the following sections:

• Securing Access to the Administration Server

• Configuring SSL/TLS Between Oracle Traffic Director and Clients

• Configuring SSL/TLS Between Oracle Traffic Director and Origin Servers

• Managing Certificates

• Managing PKCS#11 Tokens

• Managing Certificate Revocation Lists

• Managing Web Application Firewalls

• Configuring Client Authentication

• Preventing Denial-of-Service Attacks

Note:

For information about some steps that you can take to secure Oracle Traffic Director in your environment, see Securing Oracle Traffic Director Deployment.

Securing Access to the Administration Server

The administration server instance of Oracle Traffic Director hosts the administration console and command-line interface. So it is important to secure access to the administration server.

User access to the administration server interfaces is controlled through password-based authentication.

• By default, the administration server enables only one administrator user account, which you specify while creating the administration server. For information about changing the administrator user name and password, see Changing the Administrator User Name and Password.

• To allow multiple users to log in to the administration server, you can enable LDAP authentication. For more information, see Configuring LDAP Authentication for the Administration Server.

SSL authentication of the Oracle Traffic Director administration server with clients as well as with administration nodes is enabled, by default, through the use of two self-signed certificates—Admin-Client-Cert and Admin-Server-Cert.

• The self-signed administration-server certificates are created automatically when you create the administration server and are valid for 12 months. For information about renewing the administration-server certificates, see Renewing Administration Server Certificates.

• You can secure access to the software database containing the self-signed administration-server certificates by defining a password for the token named internal, which provides the interface to the certificates database. For more information, see Enabling the Pin for the Administration Server's PKCS#11 Token.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Changing the Administrator User Name and Password

You can change the administrator user name and password by using either the administration console or the CLI.

Changing the Administrator User Name and Password Using the Administration Console

To change the administrator user name and password by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Nodes button that is situated near the upper left corner of the page.

   A list of available nodes is displayed.

3. From the list of nodes, select Administration Server.

4. In the navigation pane, select Authentication.

   The Authentication page is displayed.

5. Specify the user name and password, and then click Save.

   Note:

   The user name can contain a maximum of 100 characters and must not contain spaces.

   A message is displayed in the Console Messages pane indicating that the updated settings are saved.

6. Restart the administration server by clicking Restart in the Common Tasks pane.

Changing the Administrator User Name and Password Using the CLI

• To change the administrator user name, run the set-admin-prop command.

  tadm> set-admin-prop admin-user=user_name
  OTD-70213 The administration server must be restarted for the changes to take effect.
  

  The user name can contain a maximum of 100 characters and must not contain spaces.

• To change the password, do the following:

  1. Run one of the following commands:

     tadm> set-admin-prop --set-password
     

     or

     tadm> reset-admin-password
     

     The following prompt is displayed:

     Enter admin-password>
     

  2. Enter the new password.

     A prompt to re-enter the new password is displayed:

     Enter admin-password again>
     

  3. Re-enter the new password.

     The following message is displayed.

     OTD-70201 Command 'reset-admin-password' ran successfully.
     

For the new user name and password to take effect, you should restart the administration server as described in Stopping and Restarting the Administration Server.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Configuring LDAP Authentication for the Administration Server

If you need more than one user to be able to log in to the administration server, you can store the user IDs and passwords in a directory server, and you can configure Oracle Traffic Director to access the directory server by using the Lightweight Directory Access Protocol (LDAP).

You can enable and configure LDAP authentication for the administration server by using either the administration console or the CLI.

Before You Begin

Before you start configuring Oracle Traffic Director to use LDAP authentication, keep the following information ready. This information is required for constructing the ldap(s)://host:port/baseDN URL that Oracle Traffic Director should use to access the LDAP directory server and for the directory server to search for the required user record.

• The name of the host on which the directory server runs.

• The port number at which the directory server listens for requests from LDAP clients.

• The base Distinguished Name (DN), which is the location within the directory information tree at which the directory server should start searching for the required user record.

• The bind DN, which is the user ID and password that Oracle Traffic Director provides to authenticate itself to the LDAP directory server.

  Note:

  If your directory server allows searches by anonymous clients, you need not specify the bind DN.

• The user groups whose members can access the administration server.

  By default, the administration server allows only users belonging to the group wsadmin to log in. While enabling LDAP authentication, you can specify a list of groups other than wsadmin whose members can log in.

Configuring LDAP Authentication for the Administration Server Using the Administration Console

To configure LDAP authentication for the administration server by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Nodes button that is situated near the upper left corner of the page.

   A list of available nodes is displayed.

3. From the list of nodes, select Administration Server.
4. In the navigation pane, select Authentication.

   The Authentication page is displayed.

5. Select LDAP Authentication.
6. Specify the mandatory parameters—host name, port, base DN, and allowed groups—and the optional parameters, as required.

   On-screen help and prompts are provided for all of the parameters.

   When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

   At any time, you can discard the changes by clicking the Reset button.

7. After making the required changes, click Save.

   A message is displayed in the Console Messages pane indicating that the updated settings are saved.

8. Restart the administration server by clicking Restart in the Common Tasks pane.

Configuring LDAP Authentication for the Administration Server Using the CLI

• To enable LDAP authentication, run enable-admin-ldap-auth, as shown in the following example:

  > tadm enable-admin-ldap-auth
   --ldap-url=ldap://ldap.example.com:3950/dc=example,dc=com
   --bind-dn=cn="Directory Manager" --allow-groups=sys,adm,mgr
  OTD-70213 The administration server must be restarted for the changes to take effect.
  

  This command configures Oracle Traffic Director as an LDAP client for the directory server ldap.example.com:3950. Oracle Traffic Director authenticates itself to the directory server by using the bind DN cn="Directory Manager", and the directory server starts the search for the required user record at the base DN dc=example,dc=com.

• To disable LDAP authentication, run disable-admin-ldap-auth, as shown in the following example:

  > tadm disable-admin-ldap-auth
  OTD-70213 The administration server must be restarted for the changes to take effect.
  

• To view the currently configured LDAP authentication properties, run get-admin-ldap-auth-prop, as shown in the following example:

  > tadm get-admin-ldap-auth-prop
  enabled=true
  ldap-url="ldap://ldap.example.com:3950/dc=example,dc=com"
  search-filter=uid
  group-search-filter=uniquemember
  group-search-attr=CN
  timeout=10
  allow-group=sys,adm,mgr
  

For more information about the enable-admin-ldap-auth, disable-admin-ldap-auth, and get-admin-ldap-auth-prop CLI commands, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Enabling the Pin for the Administration Server's PKCS#11 Token

The administration server's self-signed certificates are stored in a Public-Key Cryptography Standards (PKCS) 11-compliant security database. Access to the certificates database is provided through a token named internal. To secure access to the administration server's certificates database, you can enable the pin for the internal token.

If you enable the pin for the internal PKCS#11 token in the administration server configuration, a prompt to enter the token pin is displayed when you perform the following tasks:

• Start the administration server.

• Renew the administration server certificates.

You can set, change, or disable the pin for the internal token by using either the administration console or the CLI.

Setting the PKCS#11 Token Pin for the Administration Server Using the Administration Console

To set the PKCS#11 token pin for the administration server by using the administration console, do the following

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Nodes button that is situated near the upper left corner of the page.

   A list of the available nodes is displayed.

3. Select the Administration Server node.

   The General Settings page is displayed.

4. In the Token Pin Management section, select the Edit Token Pin check box.

   • To set the pin, enter the pin and confirm it in the New Pin and New Pin Again fields respectively.

   • To change the pin, enter the current pin in the Current Pin field. Then, enter the new pin and confirm it in the New Pin and New Pin Again fields respectively.

   • To disable pin protection for the token, select Unset Pin.

   When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

   At any time, you can discard the changes by clicking the Reset button.

5. After making the required changes, click Save.

   A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.

6. Stop the administration server by clicking Stop in the Common Tasks pane.

7. Start the administration server, by running the following command:

   > $INSTANCE_HOME/admin-server/bin/startserv
   

8. At the prompt to enter the token pin, enter the pin that you specified in step 4.

Setting the PKCS#11 Token Pin for the Administration Server Using the CLI

1. Run the set-token-pin command, as shown in the following example:

   tadm> set-token-pin --config=admin-server --token=internal
   

   If the token is already protected with a pin, a prompt to enter the current pin is displayed. Enter the current pin, and when prompted, enter the new pin and confirm it.

2. Restart the administration server as described in Stopping and Restarting the Administration Server.

For more information about set-token-pin, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Renewing Administration Server Certificates

To extend the validity of the self-signed administration server certificates, run the renew-admin-certs CLI command.

For example, the following command sets the expiry date of the self-signed administration server certificates to 24 months after the current date.

tadm> renew-admin-certs --validity=24
OTD-70216 The administration server and the administration nodes need to be restarted for the changes to take effect.

If you do not specify the --validity option, the expiry date is set to 12 months after the current date.

The renew-admin-certs command also attempts to update the certificates on the running nodes that are currently accessible. If a node is offline—not running or not accessible due to network problems—during the certificates renewal process, you can subsequently pull the renewed certificates from the administration server by running the renew-node-certs command on that node.

For the renewed certificates take effect, you should restart the administration server and nodes

Note:

After renewing the administration server certificates, the first time you access the CLI or administration console, a message is displayed indicating that the server's identity cannot be verified because the certificate is from an untrusted source. To continue, you should choose to trust the self-signed certificate.

If the PKCS#11 token that provides the interface to the certificates database is protected with a pin (see Enabling the Pin for the Administration Server's PKCS#11 Token), a prompt to enter the token pin is displayed.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Configuring SSL/TLS Between Oracle Traffic Director and Clients

This section describes how you can use SSL/TLS to secure communication between clients and Oracle Traffic Director instances. The information in this section is aimed at readers who are familiar with the concepts of SSL/TLS, certificates, ciphers, and keys. For basic information about those concepts, see SSL/TLS Concepts.

For information about how to configure SSL between the client browser and the load balancer in an Oracle Java Cloud Service Instance, see Configuring SSL for Your Custom Domain in an Oracle Java Cloud Service Instance Application Environment in Using Oracle Java Cloud Service.

This section contains the following subsections:

• Overview of the SSL/TLS Configuration Process

• Configuring SSL/TLS for a Listener

• Associating Certificates with Virtual Servers

• Configuring SSL/TLS Ciphers for a Listener

• Certificate-Selection Logic

• About Strict SNI Host Matching

• SSL/TLS Concepts

Overview of the SSL/TLS Configuration Process

To enable SSL/TLS for an Oracle Traffic Director instance, you must associate an RSA or ECC certificate, or both, with one more listeners of the instance. Additionally, you can associate an RSA or ECC certificate, or both, directly with virtual servers. The process of configuring SSL/TLS for Oracle Traffic Director instances involves the following steps:

1. Obtain the required certificates, which could be self-signed, issued by a third-party Certificate Authority (CA) like VeriSign or a certificate that you generated.

   For more information, see the following sections:

   • Creating a Self-Signed Certificate

   • Obtaining a CA-Signed Certificate

2. Install the certificates as described in Installing a Certificate.

3. Associate the certificates with the required HTTP or TCP listeners as described in Configuring SSL/TLS for a Listener.

   You can also associate certificates directly with virtual servers as described in Associating Certificates with Virtual Servers. For information about the logic that Oracle Traffic Director uses to select the certificate to be sent to a client during the SSL/TLS handshake, see Certificate-Selection Logic.

4. Configure ciphers supported for the HTTP or TCP listeners as described in Configuring SSL/TLS Ciphers for a Listener.

Configuring SSL/TLS for a Listener

You can configure a listener to receive HTTPS or TCP requests by using either the administration console or the CLI. Before you start, obtain the required certificates and install them as described in sections Creating a Self-Signed Certificate, Obtaining a CA-Signed Certificate, and Installing a Certificate.

Note:

• When you modify listeners, you are, in effect, modifying a configuration. So for the updated configuration to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.

• If you associate new certificates with a listener or remove previously associated certificates, for the changes to take effect, you must restart the instances. It is not sufficient to merely deploy the updated configuration.

• The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Configuring SSL/TLS for a Listener Using the Administration Console

To configure SSL/TLS for an HTTP or TCP listener by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to configure SSL/TLS-enabled listeners.
4. In the navigation pane, expand Listeners and select the listener for which you want to enable and configure SSL/TLS.

   The Listener Settings page is displayed.

5. In the SSL Settings section, select the SSL Enabled check box.
6. In the RSA Certificate and ECC Certificate fields, select the certificates that you want to use to authenticate the server.

   If you associate a listener with an RSA certificate and with an ECC certificate, the certificate that the server eventually presents to the client is determined during the SSL/TLS handshake, based on the cipher suite that the client and the server negotiate to use.

   You can also specify the following advanced SSL/TLS settings in the Advanced Settings section of the Listener Settings page:

   • Enable and disable settings for client authentication. For more information, see Configuring Client Authentication.

   • Enable and disable strict SNI host matching. For more information, see the About Strict SNI Host Matching. section.

   • Enable and disable the following TLS-specific features:

     • Version Rollbacks

       Select this check box if you want Oracle Traffic Director to detect and block attempts at rolling back the TLS version. For example, if the client requested TLS 1.0, but an attacker changed it to a lower version (say, SSL 3.0), Oracle Traffic Director can detect and block the rollback even if it supports the lower version.

     • Session Ticket Extension

       If enabled, TLS sessions can be resumed without storing the session state of each client on the server. Oracle Traffic Director encapsulates the session state of each client in a ticket and forwards the ticket to the client. The client can subsequently resume the TLS session by using the previously obtained session ticket.

   • Enable and disable SSL and TLS ciphers. For more information, see Configuring SSL/TLS Ciphers for a Listener.

   On-screen help and prompts are provided for all of the parameters.

   When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

   At any time, you can discard the changes by clicking the Reset button.

7. After making the required changes, click Save.

   A message, confirming that the updated listener was saved, is displayed in the Console Messages pane.

8. Click the Deployment Pending button that is displayed at the top of the main pane, and on the resulting dialog box, confirm the deployment by clicking Deploy.
9. Restart the instances of the configuration by clicking Start/Restart Instances in the Common Tasks pane.

Configuring SSL/TLS for a Listener Using the CLI

• To view the SSL/TLS properties of an HTTP or TCP listener, run the get-ssl-prop command, as shown in the following example:

  tadm> get-ssl-prop --config=soa --http-listener=ls1
  enabled=false
  strict-sni-vs-host-match=false
  client-auth=false
  tls=true
  max-client-auth-data=1048576
  tls-session-tickets-enabled=false
  ssl3=true
  tls-rollback-detection=true
  client-auth-timeout=60
  

• To configure SSL/TLS for an HTTP or TCP listener, run the set-ssl-prop command, as shown in the following example:

  tadm> set-ssl-prop --config=soa --http-listener=ls1 enabled=true server-cert-nickname=rsa-cert1
  OTD-70201 Command 'set-ssl-prop' ran successfully.
  

  For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by running the deploy-config command, and restart the instances by running the restart-instance command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Note:

When you enable SSL/TLS for an HTTP or TCP listener, initialization of PKCS#11 cryptographic tokens for the certificates database in the configuration is enabled automatically. For more information about configuring PKCS#11 tokens, see Managing PKCS#11 Tokens.

Associating Certificates with Virtual Servers

You can associate one RSA and one ECC certificate with each virtual server, by using either the administration console or the CLI. For information about the logic that Oracle Traffic Director uses to select the certificate to be sent to a client during the SSL/TLS handshake, see Certificate-Selection Logic.

Before you start, obtain the required certificates and install them as described in sections Creating a Self-Signed Certificate, Obtaining a CA-Signed Certificate, and Installing a Certificate.

Note:

• When you modify virtual servers, you are, in effect, modifying a configuration. So for the updated configuration to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.

• If you associate new certificates with a virtual server or remove previously associated certificates, for the changes to take effect, you must restart the instances. It is not sufficient to merely deploy the updated configuration.

• The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Associating Certificates with Virtual Servers Using the Administration Console

To associate certificates with virtual servers by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to associate certificates with virtual servers.
4. In the navigation pane, expand Virtual Servers and select the virtual server for which you want to associate certificates.

   The Virtual Server Settings page is displayed.

5. Go to the Certificates section of the Virtual Server Settings page.
6. In the RSA Certificate and ECC Certificate fields, select the certificates that you want to use to authenticate the server.

   When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

   At any time, you can discard the changes by clicking the Reset button.

7. After making the required changes, click Save.

   A message, confirming that the updated listener was saved, is displayed in the Console Messages pane.

8. Click the Deployment Pending button that is displayed at the top of the main pane, and on the resulting dialog box, confirm the deployment by clicking Deploy.
9. Restart the instances of the configuration by clicking Start/Restart Instances in the Common Tasks pane.

Associating Certificates with Virtual Servers Using the CLI

• To view the certificates that are currently associated with a virtual server, run the get-virtual-server-prop command, as shown in the following example:

  tadm> get-virtual-server-prop --config=soa --vs=soa.example.com server-cert-nickname
  cert-rsa-soa
  

• To associate a certificate with a virtual server, run the set-virtual-server-prop command, as shown in the following example:

  tadm> set-virtual-server-prop --config=soa --vs=soa.example.com  server-cert-nickname=cert-ecc-soa
  OTD-70201 Command 'set-virtual-server-prop' ran successfully.
  

  For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by running the deploy-config command, and restart the instances by running the restart-instance command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Note:

• If you associate a virtual server with an RSA certificate and with an ECC certificate, the certificate that the server eventually sends to the client is determined during the SSL/TLS handshake, based on the cipher suite that the client and the server negotiate to use.

• Make sure that a certificate of the same type—ECC or RSA—that you want to associate with the virtual server, is also associated with the listeners to which the virtual server is bound.

Configuring SSL/TLS Ciphers for a Listener

During the SSL/TLS handshake, the client and server inform each other about the SSL and TLS ciphers that they support and then negotiate the cipher—typically, the strongest—that they will use for the SSL/TLS session. For basic conceptual information about ciphers, see "About Ciphers".

You can configure the ciphers that Oracle Traffic Director supports for a listener by using either the administration console or the CLI.

Configuring Ciphers for a Listener Using the Administration Console

To configure the ciphers supported for an HTTP or TCP listener by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to configure ciphers.
4. In the navigation pane, expand Listeners and select the listener for which you want to configure ciphers.

   The Listener Settings page is displayed.

5. Go to the Advanced Settings section of the page and scroll down to the SSL subsection.
6. In the SSL3/TLS Ciphers field, select the check boxes for the ciphers that you want to enable for the listener, and deselect the check boxes for the ciphers that you want to disable.
7. After making the required changes, click Save.

   A message, confirming that the updated listener was saved, is displayed in the Console Messages pane.

8. Click the Deployment Pending button that is displayed at the top of the main pane, and on the resulting dialog box, confirm the deployment by clicking Deploy.
9. For the cipher changes to take effect, restart the instances of the configuration by clicking Start/Restart Instances in the Common Tasks pane.

Configuring Ciphers for a Listener Using the CLI

• To view the ciphers that are currently enabled for an HTTP or TCP listener, run the list-ciphers command, as shown in the following example:

  tadm> list-ciphers --config=soa --http-listener=http-listener-1|--tcp-listener=tcp-listener-1
  

  This command returns a list of all the ciphers that Oracle Traffic Director supports and indicates whether they are enabled for the listener.

• To enable specific ciphers for a listener, run the enable-ciphers command.

  For example, the following command enables two additional ciphers—TLS_RSA_WITH_AES_128_CBC_SHA and TLS_RSA_WITH_AES_256_CBC_SHA—for the listener http-listener-1 in the configuration soa.

  tadm> enable-ciphers --config=soa --http-listener=http-listener-1 TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA
  

• To disable ciphers for a listener, run the disable-ciphers command, as shown in the following example:

  tadm> disable-ciphers --config=soa --http-listener=http-listener-1  TLS_RSA_WITH_AES_256_CBC_SHA
  OTD-70201 Command 'disable-ciphers' ran successfully.
  

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Cipher Suites Supported by Oracle Traffic Director

During the SSL/TLS handshake, Oracle Traffic Director and clients negotiate the cipher suites to be used. Table 11-1 lists the cipher suites supported in Oracle Traffic Director. You can view this list by running the list-ciphers CLI command, as described earlier in this section. The name of each cipher suite indicates the key-exchange algorithm, the hashing algorithm, and the encryption algorithm, as depicted in.

• Protocols supported

  • TLS: TLS 1.0

  • SSL: SSL 3 and TLS 1.0

• Key exchange algorithms supported

  • RSA

  • RSA_EXPORT

  • RSA_EXPORT1024

  • RSA_FIPS

  • ECDHE_RSA

  • ECDH_RSA

  • ECDH_ECDSA

  • ECDHE_ECDSA

• Encryption algorithms supported

  • AES_256_CBC: 256-bit key

  • CAMELLIA_256_CBC: 256-bit key

  • 3DES_EDE_CBC: 168-bit key

  • AES_128_CBC: 128-bit key

  • CAMELLIA_128_CBC: 128-bit key

  • RC4_128: 128-bit key

  • SEED_CBC: 128-bit key

  • DES_CBC: 56-bit key

  • RC4_56: 56-bit key

  • RC4_40 and RC2_CBC_40: 128-bit key but only 40 bits have cryptographic significance

  • NULL: No encryption

• Message Authentication Code (MAC) algorithms supported

  • SHA: 160-bit hash

  • MD5: 128-bit hash

  • NULL: No hashing

Table 11-1 Cipher Suites Supported in Oracle Traffic Director

Cipher Suite	FIPS 140 Compliant?	Exportable?
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5		Yes
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5		Yes
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA	Yes
SSL_RSA_FIPS_WITH_DES_CBC_SHA	Yes
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	Yes
TLS_ECDHE_RSA_WITH_NULL_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA	Yes
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA	Yes
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA	Yes
TLS_ECDH_RSA_WITH_RC4_128_SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA	Yes
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA	Yes
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA	Yes
TLS_ECDH_ECDSA_WITH_RC4_128_SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA	Yes
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA	Yes
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA	Yes
TLS_ECDHE_ECDSA_WITH_NULL_SHA
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA	Yes
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA	Yes
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA		Yes
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA		Yes
TLS_RSA_WITH_AES_128_CBC_SHA	Yes
TLS_RSA_WITH_AES_256_CBC_SHA	Yes
TLS_RSA_WITH_SEED_CBC_SHA
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA
TLS_RSA_WITH_CAMELLIA_256_CBC_SHA

Source for FIPS 40-compliance information: http://www.mozilla.org/projects/security/pki/nss/ssl/fips-ssl-ciphersuites.html

Certificate-Selection Logic

When an HTTPS request is received, the certificate that Oracle Traffic Director sends to the client during the SSL/TLS handshake could be one of the following:

• A certificate associated with a virtual server bound to a configured HTTP/TCP listener

• A certificate associated with the default virtual server of the listener

• A certificate associated with the listener

Oracle Traffic Director uses the following logic to determine the certificate that should be sent to the client during the SSL/TLS handshake.

Table 11-2 Certificate-Selection Logic

Condition	Case A	Case B	Case C	Case D
Client sent SNI host extension	Yes	Yes	Yes	No
A matchingFoot 1 virtual server is found.	Yes	No	No	--
The matching virtual server has a certificate of a type—RSA or ECC— that matches the ciphers sent by the client.	Yes	--	--	--
The default virtual server of the listener has a certificate of a type—RSA or ECC— that matches the ciphers sent by the client.	--	Yes	--	--
The listener has a certificate of a type—RSA or ECC— that matches the ciphers sent by the client.	--	--	Yes	Yes
Certificate selected:	Certificate of the matching virtual server	Certificate of the default virtual server	Certificate of the listener	Certificate of the listener

^Footnote 1

A matching virtual server is a virtual server that is bound to the listener and has a host pattern that matches the Host: header sent by the client.

About Strict SNI Host Matching

When a client sends an HTTPS request to an SSL/TLS-enabled Oracle Traffic Director instance, the server needs to send a certificate to the client to initiate the SSL/TLS handshake. If the host name in the request does not match the server name (common name, CN) in the certificate provided by the server, a warning message is displayed by the client to the user. To continue with the SSL/TLS handshake process, the user must then explicitly choose to trust the certificate.

If an Oracle Traffic Director instance contains multiple, name-based virtual servers configured with a single IP address and port combination, to determine the appropriate certificate that should be sent to the client, the server needs to know the value of the Host header in the HTTP request, which it cannot read until after the SSL/TLS connection is established.

An extension to the SSL and TLS protocols, called Server Name Indication (SNI), addresses this issue, by allowing clients to provide the requested host name during the SSL/TLS handshake in the SNI host extension. Oracle Traffic Director uses the host name in the SNI host extension to determine the virtual server certificate that it should send to the client. For information about associating certificates with virtual servers, see Associating Certificates with Virtual Servers.

Support for SNI is enabled by default for SSL/TLS-enabled HTTP listeners in Oracle Traffic Director. For stricter control, like if you want to prevent non-SNI clients from accessing name-based virtual servers, you should enable the Strict SNI Host Matching parameter.

When Strict SNI Host Matching is enabled for an HTTP listener, and if for that listener at least one of the virtual servers has certificates, then Oracle Traffic Director returns a 403-Forbidden error to the client, if any of the following conditions is true:

• The client did not send the SNI host extension during the SSL/TLS handshake.

• The request does not have the Host: header.

• The host name sent by the client in the SNI host extension during the SSL/TLS handshake does not match the Host: header in the request.

SSL/TLS Concepts

This section provides basic information about security-related concepts. It contains the following topics:

• About SSL

• About Ciphers

• About Keys

• About Certificates

About SSL

Secure Socket Layer (SSL) is a protocol for securing Internet communications and transactions. It enables secure, confidential communication between a server and clients through the use of digital certificates. Oracle Traffic Director supports SSL v3 and Transport Layer Security (TLS) v1.

In a 2-way HTTP over SSL (HTTPS) connection, each party—say a browser or a web server—first verifies the identity of the other. This phase is called the SSL/TLS handshake. After the identities are verified, the connection is established and data is exchanged in an encrypted format. The following are the steps in the SSL/TLS handshake between an SSL-enabled browser and an SSL-enabled server:

1. The browser attempts to connect to the server by sending a URL that begins with https:// instead of http://.

2. The server sends its digital certificate (see "About Certificates") and public key to the client.

3. The client checks whether the server's certificate is current (that is, it has not expired) and is issued by a certificate authority (CA) that the client trusts.

4. If the certificate is valid, the client generates a one-time, unique session key and encrypts it with the server's public key, and then sends the encrypted session key to the server.

5. The server decrypts the message from the client by using its private key and retrieves the session key.

At this point, the client has verified the identity of the server; and only the client and the server have a copy of the client-generated, unique session key. Till the session is terminated, the client and the server use the session key to encrypt all communication between them.

About Ciphers

A cipher is an algorithm, a mathematical function, used for encrypting and decrypting data. Some ciphers are stronger and more secure than others. Usually, the more bits a cipher uses, the harder it is to decrypt the data encrypted using that cipher.

SSL v3 and TLS v1 support a variety of ciphers. Clients and servers may support different cipher suites (sets of ciphers), depending on factors such as the protocol they support, the organizational policies on encryption strength, and government restrictions on export of encrypted software.

In any 2-way encryption process, the client and the server must use the same cipher suite. During the SSL/TLS handshake process, the server and client negotiate the cipher suite—typically, the strongest one—that they will use to communicate.

About Keys

Encryption using ciphers, by itself, does not ensure data security. A key must be used with the encrypting cipher to produce the actual encrypted result, or to decrypt previously encrypted information. The encryption process uses two keys—a public key and a private key. The keys are mathematically related; so information that is encrypted using a public key can be decrypted only using the associated private key, and vice versa. The public key is published by the owner as part of a certificate (see "About Certificates"); only the associated private key is safeguarded.

About Certificates

A certificate is a collection of data that uniquely identifies a person, company, or other entity on the Internet. It enables secure, confidential communication between two entities. Personal certificates are used by individuals; server certificates are used to establish secure sessions between the server and clients over SSL.

Certificates can be self-signed (by the server), signed by a trusted third party called Certification Authority (CA) or one that you created. The holder of a certificate can present the certificate as proof of identity to establish encrypted, confidential communication. The CA could be a third-party vendor or an internal department responsible for issuing certificates for an organization's servers.

Certificates are based on public-key cryptography, which uses a pair of keys (very long numbers) to encrypt information so that it can be read only by its intended recipient. The recipient then decrypts the information using one of the keys.

A certificate binds the owner's public key to the owner's identity. In addition to the public key, a certificate typically includes information such as the following:

• The name of the holder and other identification, such as the URL of the server using the certificate

• The name of the CA that issued the certificate

• The digital signature of the issuing CA

• The validity period of the certificate

Configuring SSL/TLS Between Oracle Traffic Director and Origin Servers

This section describes how to use SSL/TLS to secure connections between Oracle Traffic Director instances and origin servers that are Oracle WebLogic Server and Oracle HTTP Server instances. It contains the following topics:

• About One-Way and Two-Way SSL/TLS

• Configuring One-Way SSL/TLS Between Oracle Traffic Director and Origin Servers

• Configuring Two-Way SSL/TLS Between Oracle Traffic Director and Origin Servers

About One-Way and Two-Way SSL/TLS

The connections between Oracle Traffic Director and origin servers in the back end can be secured using one-way or two-way SSL/TLS.

• One-way SSL/TLS: The SSL/TLS-enabled origin server presents its certificate to the Oracle Traffic Director instance. The Oracle Traffic Director instance is not configured to present any certificate to the origin server during the SSL/TLS handshake.

• Two-way SSL/TLS: The SSL/TLS-enabled origin server presents its certificate to the Oracle Traffic Director instance. The Oracle Traffic Director instance too presents its own certificate to the origin server. The origin server verifies the identity of the Oracle Traffic Director instance before establishing the SSL/TLS connection. Additionally, either end of the SSL/TLS connection—Oracle Traffic Director and/or origin servers—can be configured to verify the host name while exchanging certificates.

Configuring One-Way SSL/TLS Between Oracle Traffic Director and Origin Servers

To configure one-way SSL/TLS between Oracle Traffic Director and origin servers, you must export the origin servers' certificates in PKCS#12 format, install them in the certificate database of Oracle Traffic Director, and, optionally, configure Oracle Traffic Director to trust the certificates.

Note:

• The procedure described in this section is for a scenario where all of the servers in the origin-server pool use certificates issued by the same CA. In such a scenario, you can configure one-way SSL/TLS by importing just the root certificate of the CA that signed the certificates for the origin servers into the certificates database of Oracle Traffic Director.

• If the origin servers use self-signed certificates or certificates issued by different CAs, you should individually export and import each of the server certificates or the individual root certificates of the CAs that signed the server certificates.

• If the WebLogic Server Plug-In Enabled attribute, which can be accessed using the Weblogic Server administration console, is set to true and when Oracle Traffic Director terminates an SSL connection, Oracle Traffic Director communicates the certificate information to the applications deployed on the WebLogic Server. An application can then validate for specific information in the certificate, such as key size or cipher, before allowing the clients to access the application.

1. Export the root certificate of the CA that issued certificates to the origin servers into the PKCS#12 format.

   • For Oracle WebLogic Server origin servers:

     Use the keytool command available in Java SE 6.

     Syntax:

     > $JAVA_HOME/bin/keytool -exportcert -alias alias -file file -keystore keystore -storepass storepass -rfc
     

     alias is the nickname of the certificate to be exported, file is the name for the exported certificate, keystore is the name of the custom Oracle WebLogic Server identity store file, and storepass is the password for the specified keystore.

     Example:

     > $JAVA_HOME/bin/keytool -exportcert -alias wlsos1 -file wls_os_cert
      -keystore $DOMAIN_HOME/soa_domain/soa_keystore.jks -storepass stpass -rfc
     

     For more information about keytool, see the documentation at:

     http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

   • For Oracle HTTP Server origin servers:

     Use the exportWalletObject WebLogic Scripting Tool (WLST) command.

     Syntax:

     exportWalletObject(instName, compName, compType, walletName, password, type, path, DN)
     

     Example:

     > exportWalletObject('inst1', 'ohs1', 'ohs','wallet1', 'password', 'Certificate', '/tmp','cn=soa.example.com')
     

     This command exports the certificate with the DN cn=soa.example.com from the wallet wallet1, for Oracle HTTP Server instance ohs1. The trusted certificate is exported to the directory /tmp.

     For more information about the exportWalletObject command, see the documentation at http://docs.oracle.com/cd/E21764_01/web.1111/e13813/custom_infra_security.htm#CDDFDHDH.

2. Install the root certificate, which you just exported, in the certificates database of Oracle Traffic Director by using the install-cert CLI command.

   Note:

   For information about installing a certificate using the Administration Console, see Installing a Self-signed or CA-signed Certificate Using the Administration Console.

   Syntax:

   tadm> install-cert --config=config_name --token=name --cert-type=ca --nickname=nickname cert_file
   

   Example:

   tadm> install-cert --config=soa --token=internal --cert-type=ca --nickname=Server-Cert os_cert
   

   Note:

   If the origin servers use self-signed certificates or certificates issued by different CAs, do the following instead of steps 1 and 2:

   1. Export each server certificate, or each root certificate of the CAs that signed the server certificates, individually, by using the same commands used in step 1.

   2. Install each certificate, which you exported in the previous step, in the certificates database of Oracle Traffic Director, by using the install-cert CLI command, as described in step 2 but with --cert-type=server.

   3. Configure Oracle Traffic Director to trust each of the origin servers' certificates, as described in Configuring Oracle Traffic Director to Trust Certificates.

3. If required, configure Oracle Traffic Director to verify the host name in the origin server's certificate by using the set-route-prop CLI command.

   Syntax:

   tadm> set-route-prop --config=config_name  --vs=vs_name --route=route_name validate-server-cert=true
   

   Example:

   tadm> set-route-prop --config=soa  --vs=vs1 --route=route1 validate-server-cert=true
   

   To view a list of the virtual servers in a configuration and the routes defined for a virtual server, use the list-virtual-servers and list-routes CLI commands, respectively.

   Caution:

   If you choose to configure Oracle Traffic Director to validate the host name in the origin server's certificate during the SSL/TLS handshake, then you must do the following:

   • Ensure that the server name (CN) in the origin server's certificate matches the origin server's host name as specified in the origin-server pool of the Oracle Traffic Director configuration. For more information about configuring origin-server pools, see Managing Origin-Server Pools.

   • Ensure that dynamic discovery is disabled (default setting). For more information about dynamic discovery, see Configuring an Oracle WebLogic Server Cluster as an Origin-Server Pool.

   Otherwise, when the origin server presents its certificate, Oracle Traffic Director cannot validate the host name in the certificate, and so the SSL/TLS handshake will fail.

4. Deploy the updated configuration to the Oracle Traffic Director instances by using the deploy-config CLI command.

   tadm> deploy-config config_name
   

Note:

For more information, about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Configuring Two-Way SSL/TLS Between Oracle Traffic Director and Origin Servers

To configure two-way SSL/TLS between Oracle Traffic Director and origin servers, do the following:

Note:

For more information, about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

1. Perform the procedure for configuring one-way SSL/TLS, as described in Configuring One-Way SSL/TLS Between Oracle Traffic Director and Origin Servers.
2. Obtain a CA-issued server certificate for Oracle Traffic Director, as described in Obtaining a CA-Signed Certificate.
3. Install the CA-issued server certificate in the Oracle Traffic Director configuration, as described in Installing a Certificate..
4. Configure the required Oracle Traffic Director route with the certificate that Oracle Traffic Director should present to the origin server, by using the enable-route-auth CLI command.

   Syntax:

   tadm> enable-route-auth --config=config_name --vs=vs_name --route=route_name --client-cert-nickname=cert_nickname
   

   Example:

   tadm> enable-route-auth --config=soa --vs=vs1 --route=route1 --client-cert-nickname=soa_cert
   

   To view a list of the virtual servers in a configuration and the routes defined for a virtual server, use the list-virtual-servers and list-routes CLI commands, respectively.

5. Deploy the updated configuration to the Oracle Traffic Director instances by using the deploy-config CLI command.

   tadm> deploy-config config_name
   

6. Export the root certificate of the CA that signed the certificate for the Oracle Traffic Director instance, from the Oracle Traffic Director certificates database to the .pem format.

   Syntax:

   > $ORACLE_HOME/bin/certutil -L -d certdir -n nickname -a -o output_cert_file
   

   certdir is the full path to the config directory of the Oracle Traffic Director instance from which you want to export the root CA certificate, nickname is the nickname of the certificate that you want to export, and output_cert_file is the name of the .pem file to which the certificate should be exported.

   Example:

   > $ORACLE_HOME/bin/certutil -L -d ../net-test/config/ -n rootca -a -o /tmp/rootca1.pem
   

   For more information about the certutil command, run the following command:

   > $ORACLE_HOME/bin/certutil -H
   

7. Import the root certificate that you exported in the previous step into the trust keystore for the Oracle WebLogic Server origin servers (and the Oracle wallet for Oracle HTTP Server origin servers).

   • For Oracle WebLogic Server origin servers:

     Use the keytool command available in Java SE 6.

     Syntax:

     > $JAVA_HOME/bin/keytool -importcert -v -trustcacerts -alias alias
      -file cert_file -keystore keystore_file -storepass keystore_password
      -noprompt
     

     alias is the nickname of the CA-issued root CA exported in the previous step, file is the name of the exported .pem certificate file, keystore is the name of the custom Oracle WebLogic Server identity store file, and storepass is the password for the specified keystore.

     Example:

     > $JAVA_HOME/bin/keytool -importcert -v -trustcacerts -alias rootca1
      -file /tmp/rootca1.pem -keystore $DOMAIN_HOME/soa_domain/soa_keystore.jks
      -storepass stpass -noprompt
     

     For more information about keytool, see the documentation at:

     http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

   • For Oracle HTTP Server origin servers:

     Use the importWalletObject WLST command.

     Syntax:

     importWalletObject(instName, compName, compType, walletName, password, type, filePath)
     

     Example:

     > importWalletObject('inst1', 'ohs1', 'ohs','wallet1', 'password', 'TrustedCertificate','/tmp/rootca1.pem')
     

     For more information about the importWalletObject command, see the documentation at http://docs.oracle.com/cd/E21764_01/web.1111/e13813/custom_infra_security.htm#CDDGIBEJ.

8. Configure the origin servers to require Oracle Traffic Director to present its client certificate during the SSL/TLS handshake.

   • For Oracle WebLogic Server origin servers:

     Perform the procedure described in "Configure two-way SSL" in the Oracle WebLogic Server Administration Console Online Help at http://docs.oracle.com/cd/E21764_01/apirefs.1111/e13952/taskhelp/security/ConfigureTwowaySSL.html.

     Note:

     By default, host name verification is enabled in Oracle WebLogic Server. For information about disabling host name verification, see "Disable host name verification" in the Oracle WebLogic Server Administration Console Online Help at http://docs.oracle.com/cd/E21764_01/apirefs.1111/e13952/taskhelp/security/DisableHostNameVerification.html.

   • For Oracle HTTP Server origin servers:

     Add the following directive in the httpd.conf file.

     SSLVerifyClient require
     

Managing Certificates

This section contains the following topics:

• Creating a Self-Signed Certificate

• Obtaining a CA-Signed Certificate

• Installing a Certificate

• Viewing a List of Certificates

• Renewing a Server Certificate

• Deleting a Certificate

• Configuring Oracle Traffic Director to Trust Certificates

Note:

• The information in this section is aimed at readers who are familiar with the concepts of SSL, certificates, ciphers, and keys. For basic information about those concepts, see SSL/TLS Concepts.

• The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Creating a Self-Signed Certificate

You can create a self-signed certificate if you do not need your certificate to be signed by a CA, or if you want to test the SSL/TLS implementation while the CA is in the process of signing your certificate.

Note that if you use a self-signed certificate to enable SSL/TLS for an Oracle Traffic Director virtual server, when a client accesses the https:// URL of the virtual server, an error message is displayed indicating that the signing CA is unknown and not trusted. To proceed with the connection, the client can choose to trust the self-signed certificate.

You can create a self-signed certificate by using either the administration console or the CLI.

Before You Begin

Before you begin creating a self-signed certificate or a certificate-signing request, decide the following:

• The fully qualified host name used in DNS lookups (for example, www.example.com).

  If the host name in the client request does not match the name on the certificate, the client is notified that the certificate server name does not match the host name.

  Note:

  In a high availability scenario, ensure that the server name (CN) in the server's certificate matches the host name of the VIP that the OTD instance is configured to listen on.

• The nickname of the certificate (required only for creating a self-signed certificate).

• The certificate's validity period, in months (required only for creating a self-signed certificate).

• The key type—RSA or ECC.

  Oracle Traffic Director supports generation of the traditional RSA-type keys and the more advanced Elliptic Curve Cryptography (ECC) keys. ECC offers equivalent security with smaller key sizes, which results in faster computations, lower power consumption, and memory and bandwidth savings.

• The key size (for RSA) or curve (for ECC).

  For RSA keys, you can specify 1024, 2048, 3072, or 4096 bits. Long keys provide better encryption, but Oracle Traffic Director would need more time to generate them.

  For ECC keys, you should specify the curve for generating the key pair. Oracle Traffic Director supports the following curves: prime256v1, secp256r1, nistp256, secp256k1, secp384r1, nistp384, secp521r1, nistp521, sect163k1, nistk163, sect163r1, sect163r2, nistb163, sect193r1, sect193r2, sect233k1, nistk233, sect233r1, nistb233, sect239k1, sect283k1, nistk283, sect283r1, nistb283, sect409k1, nistb409, sect571k1, nistk571, sect571r1, nistb571, secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, nistp192, secp224k1, secp224r1, nistp224, prime192v1.

Creating a Self-Signed Certificate Using the Administration Console

To create a self-signed certificate by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to create an self-signed certificate.

4. In the navigation pane, expand SSL and select Server Certificates.

   The Server Certificates page is displayed.

5. Click the New Self-Signed Certificate button.

   The New Self-Signed Certificate wizard starts.

   Figure 11-1 New Self-Signed Certificate Wizard

   
   Description of "Figure 11-1 New Self-Signed Certificate Wizard"

   Note:

   If the PKCS#11 token, in which the certificates and keys for the configuration are stored, is protected by a pin, the first screen of the wizard displays a prompt to select the token and enter the pin.

   1. Select the appropriate token.

      If the keys are stored in the local key database maintained by Oracle Traffic Director, select the internal token.

      If the keys are stored in a Smart Card, or in an external device or engine, select the name of that external token.

   2. Enter the pin for the selected token.

   To avoid having to enter token pins repeatedly during an administration-console session, you can cache the pins as described in "Caching the Token Pins for an Administration Console Session".

6. Follow the on-screen prompts to complete creation of the certificate by using the details—server name, certificate nickname, validity, key type, and so on—that you decided earlier.

   After the certificate is created, the Results screen of the New Self-Signed Certificate wizard displays a message confirming successful creation of the certificate.

7. Click Close.

   • A message is displayed in the Console Message pane confirming that the certificate was created.

   • The certificate that you created is displayed on the Server Certificates page.

   • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes, as described in Deploying a Configuration.

Creating a Self-Signed Certificate Using the CLI

To create a self-signed certificate, run the create-selfsigned-cert command, as shown in the following example:

tadm> create-selfsigned-cert --config=soa --server-name=soa.example.com
 --nickname=cert-soa
OTD-70201 Command 'create-selfsigned-cert' ran successfully.

This command creates a self-signed certificate that is valid for a default period of 12 months with the nickname cert-soa for the server soa.example.com in the configuration soa. The key type and other parameters were not specified; so the command creates the certificate with RSA-type (default) keys that are 2048 bits (default) long.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information, about create-selfsigned-cert, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Obtaining a CA-Signed Certificate

To obtain a certificate signed by a Certificate Authority (CA), you should submit a Certificate Signing Request (CSR) to the CA, pay the prescribed fee if required, and wait for the CA to approve the request and grant the certificate.

The CSR is a digital file—a block of encrypted text in Base-64 encoded PEM format—containing information such as your server name, organization name, and country. It also contains the public key that will be included in the certificate.

You can create a CSR by using either the administration console or the CLI of Oracle Traffic Director.

Before You Begin

Before you begin creating a CSR, decide the server name; key type; and key size (for RSA) or curve (for ECC), as described in Creating a Self-Signed Certificate..

Note:

In a high availability scenario, ensure that the server name (CN) in the server's certificate matches the host name of the VIP that the OTD instance is configured to listen on.

Creating a CSR Using the Administration Console

To create a CSR by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to create a CSR.

4. In the navigation pane, expand SSL and select Server Certificates.

   The Server Certificates page is displayed.

5. Click the Create Certificate Request button.

   The Create Certificate Signing Request wizard starts.

   Figure 11-2 Create Certificate Signing Request Wizard

   
   Description of "Figure 11-2 Create Certificate Signing Request Wizard"

   Note:

   If the PKCS#11 token in which the certificates and keys for the configuration are stored is protected by a pin, the first screen of the wizard displays a prompt to select the token and enter the pin.

   1. Select the appropriate token.

      If the keys are stored in the local key database maintained by Oracle Traffic Director, select the internal token.

      If the keys are stored in a Smart Card, or in an external device or engine, select the name of that external token.

   2. Enter the pin for the selected token.

   To avoid having to enter token pins repeatedly during an administration console session, you can cache the pins as described in "Caching the Token Pins for an Administration Console Session".

6. Follow the on-screen prompts to complete creation of the CSR by using the details—server name, key type, and so on—that you decided earlier.

   After the CSR is created, the Results screen of the Create Certificate Signing Request wizard displays the encrypted text of the CSR as shown in the following example:

   -----BEGIN NEW CERTIFICATE REQUEST-----
    MIICmDCCAYACAQAwDDEKMAgGA1UEAxMBeTCCASIwDQYJKoZIhvcNAQEBBQADggEP
    ADCCAQoCggEBAMBzgU1mQJrQYQOiedKVpQVedJplQT1gh943RfNfCsl6VbD1Kid8
    ...
    lines deleted
    ...
    v6PWA9azqAfnJ8IriK6xTMQ54oQNzSALEKvIGb+jBUUzo2S+UiEr+VXvfPAdHnPX
    2ZBCA4qvPr477lETgPphfxDjjvvH+EKrZMClM4JkJ4g3p+X0X+5vz53w964=
    -----END NEW CERTIFICATE REQUEST-----
   

7. Copy and store the CSR text, including the header line BEGIN NEW CERTIFICATE REQUEST and the footer line END NEW CERTIFICATE REQUEST, and click Close.

The CSR includes the public key and other information that the CA needs to verify the identity of the Oracle Traffic Director server for which you want to enable SSL. The private key is stored in encrypted form in the INSTANCE_HOME/net-config_name/config/key4.db file.

You can now send the CSR with the required certificate-signing fee to a CA of your choice.

Creating a CSR Using the CLI

To create a CSR, run the create-cert-request command, as shown in the following example:

tadm> create-cert-request--config=soa --server-name=soa.example.com
 --token=internal
OTD-70201 Command 'create-selfsigned-cert' ran successfully.

This command creates a CSR and displays the encrypted text of the CSR as shown in "Creating a Self-Signed Certificate Using the Administration Console".

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information, about create-cert-request, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

After obtaining the CA-signed certificate in response to your CSR, you should install the certificate in the appropriate configuration, as described in Installing a Certificate.

Installing a Certificate

You can install a self-signed or CA-signed certificate by using the administration console or the CLI. In addition, you can install an existing certificate by using the pk12util utility.

This section contains the following topics:

• Installing a Self-signed or CA-signed Certificate Using the Administration Console

• Installing a Self-signed or CA-signed Certificate Using the CLI

• Installing an Existing Certificate Using pk12util

Installing a Self-signed or CA-signed Certificate Using the Administration Console

To install a self-signed or CA-signed certificate by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to install a certificate.

4. In the navigation pane, expand SSL, and select Server Certificates or Certificate Authorities.

   • To install self-signed or CA-signed certificates, select Server Certificates.

   • To install root certificates or certificate chains, select Certificate Authorities.

5. Click the Install Certificate button.

   The Install Certificate wizard or the Install Server Certificate wizard (Figure 11-3) starts, depending on whether you were on Server Certificates page or the Certificate Authorities page when you clicked the Install Certificate button.

   Figure 11-3 Install Server Certificate Wizard

   
   Description of "Figure 11-3 Install Server Certificate Wizard"

   Note:

   If the PKCS#11 token in which the certificates and keys for the configuration are stored is protected by a pin, the first screen of the wizard displays a prompt to select the token and enter the pin.

   1. Select the appropriate token.

      If the keys are stored in the local key database maintained by Oracle Traffic Director, select the internal token.

      If the keys are stored in a Smart Card, or in an external device or engine, select the name of that external token.

   2. Enter the pin for the selected token.

   To avoid having to enter token pins repeatedly during an administration console session, you can cache the pins as described in "Caching the Token Pins for an Administration Console Session".

6. Paste the certificate text from a .pem file or specify the path name of the certificate file.

   If you opt to paste the certificate text, be sure to include the headers BEGIN CERTIFICATE and END CERTIFICATE, including the beginning and ending hyphens, as shown in the following example:

   -----BEGIN CERTIFICATE-----
   MIIEuTCCA6GgAwIBAgIQQBrEZCGzEyEDDrvkEhrFHTANBgkqhkiG9w0BAQsFADCB
   vTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL
   ...
   lines deleted
   ...
   lRQOfc2VNNnSj3BzgXucfr2YYdhFh5iQxeuGMMY1v/D/w1WIg0vvBZIGcfK4mJO3
   7M2CYfE45k+XmCpajQ==
   -----END CERTIFICATE-----
   

7. Follow the on-screen prompts to complete installation of the certificate.

Installing a Self-signed or CA-signed Certificate Using the CLI

To install a self-signed or CA-signed certificate, run the install-cert command, as shown in the following example:

tadm> install-cert --config=soa --token=internal --cert-type=server --nickname=soa-cert /home/admin/certs/verisign-cert.cer

The --cert-type option specifies the certificate type—server or CA. This command install the server certificate with the nickname soa-cert in the configuration soa. To install a CA certificate, specify ca for the --cert-type option. Note that the --nickname option is not mandatory for installing ca and chain certificate types.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about install-cert, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Installing an Existing Certificate Using pk12util

The command-line utility pk12util can be used to import an existing certificate and private key into an internal or external PKCS#11 module. By default, pk12util uses certificate and private key databases named cert7.db and key3.db.

Perform the following steps to install an existing certificate:

1. Add ORACLE_HOME/lib to your path.

2. Run the pk12util command as shown below:

   pk12util -i importfile [-d certdir] [-P dbprefix] [-h tokenname] [-k slotpwfile | -K slotpw] [-w p12filepwfile | -W p12filepw] [-v] 
   

   Note:

   • Option -P must follow the -h option, and it must be the last argument.

   • Enter the exact token name including capital letters and spaces between quote marks.

   For example, the following command imports a PKCS12-formatted certificate into an NSS certificate database:

   pk12util -i certandkey.p12 [-d certdir][-h "nCipher"][-P https-jones.redplanet.com-jones-
   ]
   

3. Enter the database and/or token password. For more information about PKCS#11 tokens, see Managing PKCS#11 Tokens.

4. Associate the certificate that you installed with one more listeners. For more information, see Configuring SSL/TLS for a Listener.

Viewing a List of Certificates

You can view a list of the certificates installed in a configuration by using either the administration console or the CLI.

Viewing a List of Certificates Using the Administration Console

To view a list of the certificates installed in a configuration by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to view certificates.

4. In the navigation pane, expand SSL, and select Server Certificates or Certificate Authorities.

   • To view self-signed or CA-signed certificates installed in the configuration, select Server Certificates.

   • To view root certificates or certificate chains, select Certificate Authorities.

   The resulting page displays the installed certificates.

   Note:

   If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.

   1. Click Cache Token Pin.

   2. In the resulting dialog box, enter the pins for the tokens, and click OK.

Viewing a List of Certificates Using the CLI

• To view a list of the certificates installed in a configuration, run the list-certs command, as shown in the following examples.

  • The following command displays a list of the server certificates in the configuration soa.

    tadm> list-certs --config=soa --verbose --all
    nickname        issuer-name     expiry-date
    -------------------------------------------
    cert-adf        adf             "Aug 17, 2012 5:32:40 AM"
    cert-soa        soa             "Aug 17, 2012 5:32:26 AM"
    

  • The following command displays a partial list of the CA certificates that are installed in the configuration soa.

    tadm> list-certs --config=soa --server-type=ca --verbose --all
    nickname        issuer-name     expiry-date
    -------------------------------------------
    "Builtin Object Token:GlobalSignRootCA" "GlobalSign" "Jan 28, 2028 4:00:00 AM"
    "Builtin Object Token:GlobalSignRootCA-R2" "GlobalSign" "Dec 15, 2021 12:00:00 AM"
    

• To view the properties of a certificate, run the get-cert-prop command, as shown in the following example.

  tadm> get-cert-prop --config=soa --nickname=cert-soa
  nickname=cert-soa
  subject="CN=soa.example.com"
  server-name=soa.example.com
  issuer="CN=soa.example.com"
  serial-number=00:95:9C:34:04
  fingerprint=34:E7:52:5E:3F:0A:EE:30:ED:BF:96:81:DD:1E:A3:02
  key-type=rsa
  key-size=2048
  issue-date=Sep 14, 2011 12:22:41 AM
  expiry-date=Sep 14, 2012 12:22:41 AM
  is-expired=false
  is-read-only=false
  is-self-signed=true
  is-user-cert=true
  is-ca-cert=false
  has-crl=false
  

Note:

If the pin is enabled for a token in the specified configuration, a prompt to enter the token pin is displayed when you run the list-certs and get-cert-prop commands.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Renewing a Server Certificate

To renew a certificate, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to renew certificates.

4. In the navigation pane, expand SSL and select Server Certificates.

   The resulting page displays the installed server certificates.

   Note:

   If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.

   1. Click Cache Token Pin.

   2. In the resulting dialog box, enter the pins for the tokens, and click OK.

5. Click the Renew button for the certificate that you want to renew.

   The Renew Server Certificate dialog box is displayed.

6. Specify the new validity period and click Next.

7. Click Renew Certificate.

8. Click Close.

   • A message is displayed in the Console Messages pane, confirming that the certificate has been renewed for the specified period.

   • The new expiry date for the certificate is displayed on the Server Certificates page.

   • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Deleting a Certificate

You can delete certificates in a configuration by using either the administration console or the CLI.

Deleting a Certificate Using the Administration Console

To delete a certificate in a configuration by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to delete certificates.

4. In the navigation pane, expand SSL and select Server Certificates or Certificate Authorities.

   • To delete self-signed or CA-signed certificates, select Server Certificates.

   • To delete root certificates or certificate chains, select Certificate Authorities.

   The resulting page displays the installed certificates.

   Note:

   If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.

   1. Click Cache Token Pin.

   2. In the resulting dialog box, enter the pins for the tokens, and click OK.

5. Click the Delete button for the certificate that you want to delete.

   • If one or more listeners are associated with the certificate that you are deleting, a message is displayed indicating that the certificate cannot be deleted.

   • If the certificate that you are deleting is not associated with any listener, a prompt to confirm deletion of the certificate is displayed.

     Click OK to proceed.

   A message is displayed in the Console Messages pane, confirming that the certificate has been deleted.

   In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Deleting a Certificate Using the CLI

To delete a certificate, run the delete-cert command.

For example, the following command deletes the certificate with the nickname rsa-cert-1 from the configuration soa.

tadm> delete-cert --token=internal --config=soa rsa-1

If the certificate that you are deleting is associated with one or more listeners, the following message is displayed.

OTD-64309 Certificate 'rsa-1' is being referred by listeners: listener1,listenerN

You can delete the certificate forcibly by including the --force option.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about delete-cert, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Configuring Oracle Traffic Director to Trust Certificates

The built-in certificates database in Oracle Traffic Director includes several pre-installed root certificates, including those from popular commercial CAs like VeriSign. You can also use the administration console and the CLI to configure Oracle Traffic Director to trust certificates signed by specific CAs.

Configuring Certificate Trust Flags Using the Administration Console

To specify whether Oracle Traffic Director should trust certificates signed by a specific CA by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to change certificate trust flags.

4. In the navigation pane, expand SSL and select Certificate Authorities.

   The resulting page displays the installed certificates.

   Note:

   If the pin is enabled for a token in the selected configuration, the installed certificates are not displayed. Instead, a message to enter the token pins is displayed on the page.

   1. Click Cache Token Pin.

   2. In the resulting dialog box, enter the pins for the tokens, and click OK.

5. Click the nickname of the certificate for which you want to change the trust flags.

   The Edit Certificate Authority dialog box is displayed.

6. Select the Trusted to Sign Client Certificates or Trusted to Sign Server Certificates check box, as required.

7. Click Save.

   A message is displayed in the Console Messages pane, confirming that the trust flags for the selected certificate have been updated.

   In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Configuring Certificate Trust Flags Using the CLI

To specify whether Oracle Traffic Director should trust certificates signed by a specific CA, run the set-cert-trust-prop command.

For example, the following command configures the certificate with the nickname Visa eCommerce Root in the configuration soa to be trusted to sign client and server certificates.

tadm> set-cert-trust-prop --config=soa --nickname="Visa eCommerce Root"
 is-client-ca=true is-server-ca=true
OTD-70201 Command 'set-cert-trust-prop' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about set-cert-trust-prop, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Managing PKCS#11 Tokens

A PKCS#11 token is a software or hardware interface to a Public-Key Cryptography Standards (PKCS) 11-compliant security database in which digital certificates and keys can be stored. Oracle Traffic Director includes a token named internal that provides the interface to the built-in Network Security Services (NSS) certificate database. If any other PKCS#11-compliant databases are available on the administration server host, Oracle Traffic Director recognizes them automatically and exposes the corresponding tokens, including those implemented through physical devices like hardware accelerators and smart cards.

Note:

The information in this section is aimed at readers who are familiar with the concepts of SSL, certificates, ciphers, and keys. For basic information about those concepts, see SSL/TLS Concepts.

You can enable and disable initialization of PKCS#11 tokens for a Oracle Traffic Director configuration and enable the pins for the tokens.

• If initialization of PKCS#11 tokens is enabled for a configuration and if the pin is enabled for any of the tokens, when you attempt to start instances of the configuration, a prompt to enter the pins for pin-enabled tokens is displayed.

  To avoid having to enter the token pin every time you start instances, while specifying the pin, you can opt to save it in the configuration file, as described later in this section.

• If the pin is enabled for a token in a configuration, when you access the certificates database represented by that token for any purpose (for example, to view installed certificates or to install a certificate), a prompt to select the token and enter the token pin is displayed. To avoid having to enter the token pin repeatedly, you can cache it as described in "Caching the Token Pins for an Administration Console Session".

You can configure PKCS#11 tokens by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Configuring PKCS#11 Settings Using the Administration Console

To configure a PKCS#11 token by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to configure tokens.

4. In the navigation pane, select SSL.

   The SSL Settings page is displayed. The Cryptographic Tokens section contains the parameters pertaining to PKCS#11 tokens.

   • To enable initialization of PKCS#11 tokens, select the PKCS#11 Tokens check box.

   • If you want Oracle Traffic Director to bypass processing of the PKCS#11 layer during SSL/TLS processing, select the Allow PKCS#11 Bypass check box. Bypassing the PKCS#11 layer improves performance.

   • To enable or disable a token, and to set or change a token's pin, click on the token name.

     The Edit Token dialog box is displayed.

     • To enable the token, select the Token State check box.

     • To enable the token pin, select the Set Token Pin check box.

       Enter the new pin and confirm it.

     • To change the token pin, select the Edit Token Pin check box.

       Enter the current pin, and then enter the new pin and confirm it.

     • To disable the token pin, select the Edit Token Pin check box.

       Enter the current pin, and then select the Unset Pin check box.

   Note:

   • If you select Save Pin, the token pin is saved in the configuration file. Users are not prompted to enter the token pin when they attempt to start instances of the configuration.

   • If you set or change the token pin, and choose not to save it in the configuration file, then to restart the server, you should stop it and then start it again. You cannot restart the server by using the restart-admin CLI command or through the administration console.

   When you change the value in a field or tab out of a text field that you changed, the Save button is enabled.

5. After making the required changes, click Save.

   • A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.

   • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Configuring PKCS#11 Settings Using the CLI

• To enable or disable initialization of PKCS#11 tokens, run the set-pkcs11-prop command, as shown in the following example:

  tadm> set-pkcs11-prop --config=soa enabled=true
  OTD-70201 Command 'set-pkcs11-prop' ran successfully.
  

• To view the available PKCS#11 tokens in a configuration, run the list-tokens commands as shown in the following example:

  tadm> list-tokens --config=soa --verbose --all
  name            enabled         has-saved-pin
  ---------------------------------------------
  internal        false           false    
  

• To enable or disable a token, run the set-token-prop command, as shown in the following example:

  tadm> set-token-prop --config=soa --token=internal enabled=true
  OTD-70201 Command 'set-token-prop' ran successfully.
  

• To set or change the pin for a token, run the set-token-pin command, as shown in the following example:

  tadm> set-token-pin --config=soa --token=internal
  

  If the token is already protected with a pin, a prompt to enter the current pin is displayed. Enter the current pin, and when prompted, enter the new pin and confirm it.

  Note:

  If you enable initialization of PKCS#11 tokens (set-pkcs11-prop ... enabled=true) and if the pin is enabled for any of the tokens, then when you attempt to start or restart the instances of the configuration, a prompt to enter the pins for the pin-enabled tokens is displayed. To suppress the pin prompt, you can save the pins in the configuration file by specifying the --save-pin=true option for the set-token-pin command.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Caching the Token Pins for an Administration Console Session

If the pin is enabled for a token in a configuration, when you access the certificates database represented by that token for any purpose (for example, to view installed certificates or to install a certificate), a prompt to select the token and enter the token pin is displayed. When using the administration console for managing certificates, you can avoid having to enter the token pins repeatedly, by specifying them once and caching them for the duration of the session; that is until you log out or until the session times out.

To cache the token pins for an administration-console session, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to cache token pins.
4. In the navigation pane, expand SSL and select Server Certificates or Certificate Authorities.
5. Click Cache Token Pin.

   The Cache Token Pin dialog box is displayed.

6. Enter the pins for the tokens.
7. Click OK.

   A message is displayed in the Console Messages pane confirming that the token pins are cached for the session.

Managing Certificate Revocation Lists

A Certificate Revocation List (CRL) is a list that a CA publishes to inform users about certificates that the CA has decided to revoke before they expire. CRLs are updated periodically; the updated CRLs can be downloaded from the CA's website.

To ensure that Oracle Traffic Director servers do not trust server certificates that have been revoked by CA, you should download the latest CRLs from the CAs' websites regularly and install them in your Oracle Traffic Director configurations.

You can install CRLs manually. You can also configure Oracle Traffic Director to take the downloaded CRLs from a specified directory and install them automatically at specified intervals.

This section contains the following topics:

• Installing and Deleting CRLs Manually

• Installing CRLs Automatically

Note:

• The information in this section is aimed at readers who are familiar with the concepts of SSL, certificates, ciphers, and keys. For basic information about those concepts, see SSL/TLS Concepts.

• The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Installing and Deleting CRLs Manually

You can install and delete CRLs manually by using either the administration console or the CLI.

Installing CRLs Manually Using the Administration Console

To install a downloaded CRL by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to install a certificate.
4. In the navigation pane, expand SSL, and select Certificate Authorities.
5. Click the Install CRL button.

   The Install Certificate Revocation List dialog box is displayed.

6. Specify the location of the downloaded CRL file, and click Install CRL.

   • A message, confirming successful installation of the CRL, is displayed in the Console Messages pane.

   • The CRL that you just installed is displayed on the Certificate Authorities page.

   • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Installing and Deleting CRLs Manually Using the CLI

• To install a downloaded CRL, run the install-crl command, as shown in the following example:

  tadm> install-crl --config=soa /home/admin/crls/ServerSign.crl
  OTD-70201 Command 'install-crl' ran successfully.
  

• To view a list of the installed CRLs in a configuration, run the list-crls command, as shown in the following example:

  tadm> list-crls --config=soa --verbose --all
  crl-name        next-update
  ---------------------------
  "Class 1 Public Primary Certification Authority" "Sat Apr 15 16:59:59 PDT 2000"
  "VeriSign Class 3 Code Signing 2010 CA" "Mon Aug 29 14:00:03 PDT 2011"
  "VeriSign Class 3 Organizational CA" "Sun May 18 13:48:16 PDT 2014"
  

• To delete a CRL, run the delete-crl command, as shown in the following example:

  tadm> delete-crl --config=config1 "VeriSign Class 3 Organizational CA"
  OTD-70201 Command 'delete-crl' ran successfully.
  

  When you delete a CRL, it is removed from the Oracle Traffic Director configuration and from the directory in which the downloaded CRL was stored.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Installing CRLs Automatically

You can configure Oracle Traffic Director to periodically take downloaded CRL files from a specified directory and install them automatically by using either the administration console or the CLI.

At the specified interval, Oracle Traffic Director looks for updated CRL files in the specified directory.

• If Oracle Traffic Director detects new CRL files, it installs them in the configuration and logs a message in the server log.

• If existing CRL files have been changed, Oracle Traffic Director installs the updated CRL files in the configuration and logs a message in the server log.

• If Oracle Traffic Director detects that previously installed CRL files have been removed from the directory, it deletes the CRLs from the configuration and logs a message in the server log.

• If no changes are detected in the CRL directory, Oracle Traffic Director does not perform any update.

Configuring Oracle Traffic Director to Install CRLs Automatically Using the Administration Console

To configure Oracle Traffic Director to install CRLs automatically by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Click the name of the configuration that you want to set up to install CRLs automatically.

4. In the navigation pane, select SSL.

   The SSL Settings page is displayed.

5. Go to the Advanced Settings section of the page.

6. In the Update CRL Path field, enter the absolute path to the directory that contains the updated CRL files.

7. Click New Event.

   The New CRL Update Event dialog box is displayed.

8. Specify the interval or time of the day at which the CRLs should be updated, and then click OK.

   • A message, confirming creation of the event, is displayed in the Console Messages pane.

   • The new event is displayed in the CRL Update Events list.

     • New events are enabled by default. To change the status, select the Enable/Disable check box.

     • To delete an event, click the Delete button.

   • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Configuring Oracle Traffic Director to Install CRLs Automatically Using the CLI

To configure Oracle Traffic Director to install CRLs automatically, do the following:

1. Specify the directory in which the downloaded CRLs are stored, by using the set-pkcs11-prop command.

   For example, the following command specifies /home/admin/crls as the directory in which downloaded CRLs are stored.

   tadm> set-pkcs11-prop --config=soa crl-path=/home/admin/crls
   OTD-70201 Command 'set-pkcs11-prop' ran successfully.
   

2. Schedule an event for Oracle Traffic Director to take the downloaded CRLs from the specified directory and install them automatically, by using the create-event command.

   For example, the following command specifies that the CRLs for the configuration soa should be updated after every 86400 seconds (1 day).

   tadm> create-event --config=soa --command=update-crl --interval=604800
   OTD-70201 Command 'create-event' ran successfully.
   

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Managing Web Application Firewalls

A web application firewall (WAF) is a filter or server plugin that applies a set of rules, called rule sets, to an HTTP request. Web application firewalls are useful for establishing an increased security layer in order to identify and prevent attacks. It acts as a firewall for applications hosted within the origin server. In addition, it enables administrators to inspect any part of an HTTP request, such as headers and body, and configure conditions to accept or reject the HTTP request based on the condition.

Several free and commercial versions of web application firewall modules are available for use. The web application firewall module for Oracle Traffic Director supports ModSecurity 2.6, which is an intrusion detection and prevention engine for web applications. The ModSecurity rule sets can be customized to shield applications from common attacks such as cross-site scripting (XSS) and SQL injection. Based on various criterion, such as HTTP headers, environment variables and CGI variables, ModSecurity filters and rejects incoming requests. For more information about ModSecurity, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Introduction.

Among the many providers who have published different versions of the rule sets for ModSecurity, Oracle Traffic Director has been tested with the Open Web Application Security Project (OWASP), which is an open-source application security project, and is one of the most commonly used rule set providers. For more information, see https://www.owasp.org/index.php/Category:OWASP_ModSecurity_Core_Rule_Set_Project.

This section contains the following topics:

• Overview of Web Application Firewalls

• Configuring Web Application Firewalls

• Listing the Rule Set Files

• Removing Rule Set Files

• Supported Web Application Firewall Directives_ Variables_ Operators_ Actions_ Functions_ Persistent Storages and Phases

Overview of Web Application Firewalls

With Oracle Traffic Director, web application firewalls can be enabled (or disabled) for each virtual server in your configuration. This in turn applies a set of rules, and acts as a firewall for the web applications deployed on the origin servers. For more information about origin servers and virtual servers, see Managing Origin Servers and Managing Virtual Servers respectively.

Oracle Traffic Director supports rule sets at both virtual server level and configuration level. Note that rules defined at the virtual server level will override rules defined at the configuration level. When deployed, these rules and the configuration changes are pushed to the instances, reconfiguring the instances. For more information about the web application firewall works, see Web Application Firewall Examples and Use Cases.

Configuring Web Application Firewalls

To configure web application firewalls, you can either download an open source web application firewall rule sets or create your own rule sets. For example, download the ModSecurity Core Rule Set (CRS) from the OWASP repository, and unzip the rule sets to any folder. Oracle Traffic Director supports rules in the following directories:

• base_rules

• optional_rules

• slr_rules

Note:

Web application firewall supports the ModSecurity 2.6 directives that are used by the configurations within the base_rules, optional_rules and slr_rules directories of OWASP ModSecurity Core Rule Set. However, it does not support Apache core config directives such as <IfDefine...> and <Location...>, and the ones supported by other Apache modules such as RequestHeader, Header and so on.

After unzipping the above directories, the files in these directories can be edited and uploaded to the administration server. These rule set files are then pushed to the Oracle Traffic Director instances when deployed. For more information, see Enabling and Installing Web Application Firewall Rule Sets.

Note:

• Though the server can be configured to pick up the rule set files from a directory outside the config directory, rule file management will not be supported. When Oracle Traffic Director is configured for high availability, it is recommended that the web application firewall rule sets are placed within the config directory.

• Using unsupported directives, variables, operators, actions, phases, functions and storages can cause server startup errors. For example, installing the rule set file modsecurity_crs_42_tight_security.conf without removing the unsupported action ver can cause Oracle Traffic Director to display the following error message when you start the server:

  [ERROR:16] [OTD-20016] Syntax error on line 20 of /scratch/rgoutham/instance1/net-config1/config/ruleset/config1/modsecurity_crs_42_tight_security.conf:
  [ERROR:16] [OTD-20016] Error parsing actions: Unknown action: ver
  [ERROR:32] [OTD-20008] Failed to parse VS webapp-firewall-ruleset (ruleset/config1/*.conf)
  [ERROR:32] [OTD-10422] Failed to set configuration
  [ERROR:32] server initialization failed
  

  To avoid getting this error, modify the rule set file, and remove or comment out unsupported directives, variables, operators, actions, phases, functions and storages, and then start the server.

Enabling and Installing Web Application Firewall Rule Sets

You can enable and install web application firewall rule sets by using either the administration console or the CLI.

Note:

• When you enable and install a web application firewall rule set, you are, in effect, modifying a configuration. So for the new rule set to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.

• The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Enabling and Installing Web Application Firewall Rule Sets Using the Administration Console

To configure web application firewall for a virtual server by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to configure web application firewall.

4. In the navigation pane, expand Virtual Servers, expand the name of the virtual server for which you want to configure web application firewall, and select Web Application Firewall.

   The Web Application Firewall page is displayed.

   1. On the Web Application Firewall page, click Enabled to enable web application firewall for a particular virtual server.

   2. Click Install Rule Set Files.

      In the Install Rule Set Files dialog box, either browse to the folder where you unzipped the rule set files and select the rule set file or enter the full path to the location of the rule set file. To install multiple rule set files, install them one at a time.

      After you install one or more rule set files, the following text is added to the Rule Set Pattern field:

      ruleset/<virtual-server-id>/*.conf
      

      Note:

      • When you install rule set files at the configuration level, the rule set pattern appears as follows:

        ruleset/*.conf
        

      • If required, you can add custom rule set patterns. However, rule sets outside the ruleset/<virtual-server-id> directory (if at the virtual server level) or the ruleset directory (if at the configuration level) cannot be viewed or deleted using the Oracle Traffic Director administration console or CLI. These rule sets will need to be managed manually.

   3. Click Install Rule Set.

      A message, confirming that the rule set files were installed, is displayed in the Console Messages pane.

      In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Enabling Web Application Firewall Using the CLI

To enable web application firewall using the CLI, run the enable-webapp-firewall command.

For example, the following command enables web application firewall for the virtual server vs1 in the configuration soa.

tadm> enable-webapp-firewall --config=soa --vs=vs1       
OTD-70201 Command 'enable-webapp-firewall' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about enable-webapp-firewall, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Installing Web Application Firewall Rule Sets Using the CLI

To install web application firewall rule sets using the CLI, run the install-webapp-firewall-ruleset command.

For example, the following command installs the web application firewall rule set modsecurity_crs_20_protocol_violations.conf for the virtual server vs1 in the configuration soa.

tadm> install-webapp-firewall-ruleset --config=soa --vs=vs1 /home/rulesets/modsecurity_crs_20_protocol_violations.conf
OTD-70201 Command 'install-webapp-firewall-ruleset' ran successfully.

To install web application firewall rule sets at the configuration level, run the above command without the --vs option. For example, the following command installs the web application firewall rule set modsecurity_crs_50_outbound.conf for the configuration soa.

tadm> install-webapp-firewall-ruleset --config=soa /home/rulesets/modsecurity_crs_50_outbound.conf
OTD-70201 Command 'install-webapp-firewall-ruleset' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about install-webapp-firewall-ruleset, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Note:

You can use the set-config-prop and set-virtual-server-prop commands to set the value of webapp-firewall-ruleset property at the configuration level and virtual server level respectively. For more information, see the Oracle Traffic Director Command-Line Reference.

Listing the Rule Set Files

You can view the list of rule set files by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Viewing the List of Rule Set Files Using the Administration Console

To view the list of rule set files by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to view rule set files.
4. On the Web Application Firewall page, the Rule Set Files table lists the installed rule set files. To view the contents of these files either click and select individual rule files, or click the Name check box to select all the rules files.
5. Click View.

   The contents of each rule file is displayed in the Rule set file contents window.

Viewing the List of Rule Set Files Using the CLI

While it is not possible to view the contents of individual rule set files using CLI, you can view the list of installed rule set files. To view the list of rule set files, run the list-webapp-firewall-rulesets command.

For example, the following command lists the installed web application firewall rule set files for the virtual server vs1 in the configuration soa:

tadm> list-webapp-firewall-rulesets --config=soa --vs=vs1 --verbose

ruleset-file-name
--------------------
modsecurity_crs_45_trojans.conf
modsecurity_crs_42_tight_security.conf
modsecurity_crs_46_slr_et_sqli_attacks.conf

To view the list of web application firewall rule sets that are installed at the configuration level, run the above command without the --vs option. For example, the following command lists the web application firewall rule sets that are installed at the configuration level for the configuration soa.

tadm> list-webapp-firewall-rulesets --config=soa --verbose

ruleset-file-name
--------------------
modsecurity_crs_40_generic_attacks.conf
modsecurity_crs_47_common_exceptions.conf

You can view the properties of a web application firewall by running the get-webapp-firewall-prop command.

For more information about the list-webapp-firewall-rulesets and get-webapp-firewall-prop commands, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Removing Rule Set Files

You can remove rule set files by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Removing Rule Set Files Using the Administration Console

To remove rule set files for a particular virtual server:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to delete rule set files.
4. On the Web Application Firewall page, either click and select individual rule files or click the Name check box to select all the rule files.
5. Click the Delete button. At the confirmation prompt, click OK.

   A message is displayed in the Console Message pane confirming that the rule set files were deleted.

   In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes, as described in Deploying a Configuration.

Removing Rule Set Files Using the CLI

To remove rule set files for a particular virtual server, run the delete-webapp-firewall-ruleset command, as shown in the following example:

tadm> delete-webapp-firewall-ruleset --config=soa --vs=vs1 modsecurity_crs_20_protocol_violations.conf
OTD-70201 Command 'delete-webapp-firewall-ruleset' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about delete-webapp-firewall-ruleset, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Note:

The disable-webapp-firewall command can be used to disable a web application firewall. For more information, see the Oracle Traffic Director Command-Line Reference.

Supported Web Application Firewall Directives, Variables, Operators, Actions, Functions, Persistent Storages and Phases

Oracle Traffic Director supports various ModSecurity 2.6 directives, variables, operators, actions, functions, persistent Storages and phases.

Supported Web Application Firewall Directives

Oracle Traffic Director supports the following ModSecurity 2.6 directives. For more information and to see the full list of ModSecurity directives, including unsupported directives, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Configuration_Directives.

SecAction
SecArgumentSeparator
SecAuditEngine
SecAuditLog
SecAuditLog2
SecAuditLogDirMode
SecAuditLogFileMode
SecAuditLogParts
SecAuditLogRelevantStatus
SecAuditLogStorageDir
SecAuditLogType
SecComponentSignature
SecContentInjection
SecCookieFormat
SecDataDir (see note below)
SecDebugLog
SecDefaultAction
SecDebugLogLevel
SecGeoLookupDb
SecInterceptOnError
SecMarker
SecPcreMatchLimit (see note below)
SecPcreMatchLimitRecursion (see note below)
SecRequestBodyAccess
SecRequestBodyInMemoryLimit (see note below)
SecRequestBodyNoFilesLimit (see note below)
SecRequestBodyLimitAction
SecResponseBodyAccess
SecResponseBodyLimit
SecResponseBodyLimitAction (see note below)
SecResponseBodyMimeType
SecResponseBodyMimeTypesClear
SecRule
SecRuleEngine (see note below)
SecRuleRemoveById
SecRuleRemoveByMsg
SecRuleRemoveByTag
SecRuleUpdateActionById
SecRuleUpdateTargetById
SecTmpDir
SecUnicodeMapFile (see note below)
SecUnicodeCodePage (see note below)
SecUploadDir
SecUploadFileLimit
SecUploadFileMode
SecUploadKeepFiles
SecWebAppId (see note below)
SecCollectionTimeout

Note:

• SecWebAppId can be specified within virtual server specific web application firewall configuration file to associate the application namespace to a particular virtual server.

• The directive SecRequestBodyLimitAction enables you to set action against requests that hit SecRequestBodyNoFilesLimit. However, the directive SecRequestBodyLimit is not supported by Oracle Traffic Director and hence, you cannot set action against this directive.

• Oracle Traffic Director does not support the directive SecRequestBodyLimit, which is used for configuring the maximum request body size that ModSecurity accepts for buffering. In place of this directive, the following options can be used:

  Option 1: Use the directives, SecRequestBodyNoFilesLimit and SecRequestBodyLimitAction. Example:

  SecRequestBodyNoFilesLimit 100
  SecRequestBodyLimitAction Reject
  

  Option 2: For Reject behavior, Oracle Traffic Director can be configured to check a request's Content-Length header in obj.conf. In addition, max-unchunk-size value can be set in server.xml.

  Similarly, for ProcessPartial behavior, body-buffer-size element in server.xml can be set to the desired limit. In this case, only the first part of the body that fits the limit is processed and the rest is passed through.

• If the directive SecRuleEngine is specified within the configuration file(s) specified by the webapp-firewall-ruleset element, then it will be ignored. However, this condition is not applicable if SecRuleEngine is set to DetectionOnly mode.

• The directive SecRequestBodyInMemoryLimit is ignored if the header Content-Type is set to x-www-form-urlencoded.

• The directives SecDataDir, SecPcreMatchLimit, SecPcreMatchLimitRecursion, SecUnicodeCodePage, and SecUnicodeMapFile can only be used at configuration level. The scope of these directives is considered to be Main. All the other directives can be used at both virtual server level and configuration level. The scope of these directives is considered to be Any. If a directive with Main scope is specified within the virtual server level configuration file, then an error will be logged and the server will fail to start.

Supported Web Application Firewall Variables

Oracle Traffic Director supports the following ModSecurity 2.6 variables. For more information and to see the full list of ModSecurity variables, including the unsupported variables, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Variables.

ARGS
ARGS_COMBINED_SIZE
ARGS_GET
ARGS_GET_NAMES
ARGS_NAMES
ARGS_POST
ARGS_POST_NAMES
AUTH_TYPE
DURATION
ENV
FILES
FILES_COMBINED_SIZE
FILES_NAMES
FILES_SIZES
GEO
HIGHEST_SEVERITY
MATCHED_VAR
MATCHED_VARS
MATCHED_VAR_NAME
MATCHED_VARS_NAMES
MODSEC_BUILD 
MULTIPART_BOUNDARY_QUOTED
MULTIPART_BOUNDARY_WHITESPACE
MULTIPART_DATA_AFTER
MULTIPART_DATA_BEFORE
MULTIPART_FILE_LIMIT_EXCEEDED
MULTIPART_HEADER_FOLDING
MULTIPART_INVALID_QUOTING
MULTIPART_INVALID_HEADER_FOLDING
MULTIPART_LF_LINE 
MULTIPART_MISSING_SEMICOLON
MULTIPART_CRLF_LF_LINES
MULTIPART_STRICT_ERROR
MULTIPART_UNMATCHED_BOUNDARY
PERF_COMBINED
PERF_GC
PERF_LOGGING
PERF_PHASE1
PERF_PHASE2
PERF_PHASE3
PERF_PHASE4
PERF_PHASE5
PERF_SREAD
PERF_SWRITE
QUERY_STRING
REMOTE_ADDR
REMOTE_PORT
REMOTE_USER
REQBODY_ERROR
REQBODY_ERROR_MSG
REQBODY_PROCESSOR
REQBODY_PROCESSOR_ERROR
REQUEST_BASENAME
REQUEST_BODY (see note below)
REQUEST_BODY_LENGTH
REQUEST_COOKIES
REQUEST_COOKIES_NAMES
REQUEST_FILENAME
REQUEST_HEADERS (see note below)
REQUEST_HEADERS_NAMES
REQUEST_LINE
REQUEST_METHOD
REQUEST_PROTOCOL
REQUEST_URI
REQUEST_URI_RAW
RESPONSE_BODY
RESPONSE_CONTENT_LENGTH
RESPONSE_CONTENT_TYPE
RESPONSE_HEADERS
RESPONSE_HEADERS_NAMES
RESPONSE_PROTOCOL
RESPONSE_STATUS
RULE
SERVER_ADDR
SERVER_NAME
SERVER_PORT
SESSIONID
TIME
TIME_DAY
TIME_EPOCH
TIME_HOUR
TIME_MIN
TIME_MON
TIME_SEC
TIME_WDAY
TIME_YEAR
TX
UNIQUE_ID
URL_ENCODED_ERROR
USERID
WEBAPPID
WEBSERVER_ERROR_LOG (see note below)
XML

Note:

• The REQUEST_BODY variable, which holds raw request body, will contain the body content that is available after it passes through other filters.

• In open source ModSecurity, apache error log for each request/response can be collected and stored in the WEBSERVER_ERROR_LOG variable, and printed in the auditlog action. However, Oracle Traffic Director does not support this feature.

• As request headers with the same name are concatenated into a single one, the header count is always 1. Hence, &REQUEST_HEADERS:<any header name> will always return 1 in spite of how many same request headers were sent.

Supported Web Application Firewall Operators

Oracle Traffic Director supports the following ModSecurity 2.6 operators. For more information and to see the full list of ModSecurity operators, including unsupported operators https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Operators.

beginsWith
contains
containsWord
endsWith
eq
ge
geoLookup
gt
inspectFile
ipMatch
le
lt
pm
pmf
pmFromFile
rbl (see note below)
rx
streq
strmatch
validateByteRange
validateDTD
validateSchema
validateUrlEncoding
validateUtf8Encoding
verifyCC
verifyCPF
verifySSN
within

Note:

ModSecurity 2.6 does not support the directive SecHttpBlKey. Hence use of Project Honey Pot (dnsbl.httpbl.cong) as RBL, which requires SecHttpBlKey, is not supported.

Supported Web Application Firewall Actions

Oracle Traffic Director supports the following ModSecurity 2.6 actions. For more information and to see the full list of ModSecurity actions, including the unsupported actions, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Actions.

allow
append
auditlog (see note below)
block
capture
chain
ctl
deny (see note below)
deprecatevar
drop (see note below)
exec
expirevar
id
initcol
log
logdata
msg
multiMatch
noauditlog
nolog
pass
pause
phase
prepend
redirect
rev
sanitiseArg
sanitiseMatched
sanitiseMatchedBytes
sanitiseRequestHeader
sanitiseResponseHeader
severity
setuid
setsid
setenv
setvar
skip
skipAfter
status
t
tag
xmlns

Note:

• In open source ModSecurity, apache error log for each request/response can be collected and stored in the WEBSERVER_ERROR_LOG variable, and printed in the auditlog action. However, Oracle Traffic Director does not support this feature.

• Actions that change HTTP response status, such as deny, will not successfully change the response status when it is invoked in phase 4. In such a scenario, the following error message is logged in the server log:

  " ModSecurity: Access denied with code 403 (phase 4)."
  

• When drop action is invoked in phase 4, Oracle Traffic Director will send out HTTP headers to the client and then drop the connection.

• When deny action is invoked in phase 4, Oracle Traffic Director strips the response body, instead of sending 403 response status. This might cause the following warning to appear in the server log:

  Response content length mismatch (0 bytes with a content length of <original content length>)
  

Supported Web Application Firewall Transformation Functions

Oracle Traffic Director supports the following ModSecurity 2.6 transformation functions. For more information and to see the full list of ModSecurity transformation functions, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Transformation_functions.

base64Decode
sqlHexDecode
base64DecodeExt
base64Encode
cmdLine
compressWhitespace
cssDecode
escapeSeqDecode
hexDecode
hexEncode
htmlEntityDecode
jsDecode
length
lowercase
md5
none
normalisePath
normalisePathWin
parityEven7bit
parityOdd7bit
parityZero7bit
removeNulls
removeWhitespace
replaceComments
removeCommentsChar
removeComments
replaceNulls
urlDecode
urlDecodeUni
urlEncode
sha1
trimLeft
trimRight
trim

Supported Web Application Firewall Persistent Storages

Oracle Traffic Director supports the following ModSecurity 2.6 persistent storages. For more information and to see the full list of ModSecurity persistent storages, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Persistant_Storage.

GLOBAL
IP
RESOURCE
SESSION
USER

Supported Web Application Firewall Phases

Oracle Traffic Director supports the following ModSecurity 2.6 phases. For more information and to see the full list of ModSecurity phases, see https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual#wiki-Processing_Phases.

Phase:1 - Request headers stage
Phase:2 - Request body stage
Phase:3 - Response headers stage
Phase:4 - Response body stage
Phase:5 - Logging

Note:

• Actions that change HTTP response status, such as deny, will not successfully change the response status when it is invoked in phase 4.

• When drop action is invoked in phase 4, Oracle Traffic Director will send out HTTP headers to the client and then drop the connection.

• When deny action is invoked in phase 4, Oracle Traffic Director strips the response body, instead of sending 403 response status. This might cause the following warning to appear in the server log:

  Response content length mismatch (0 bytes with a content length of <original content length>)
  

Configuring Client Authentication

Client authentication is the verification of a client by the Oracle Traffic Director virtual server or TCP proxy, based on the certificate that the client provides.

Client authentication is not enabled by default. You can configure the Oracle Traffic Director listeners to require clients to provide a certificate, by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Configuring Client Authentication Using the Administration Console

To enable client authentication for a listener by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.
2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to enable client authentication for listeners.
4. In the navigation pane, expand Listeners, and select the listener for which you want to configure client authentication.

   The Listener Settings page is displayed.

5. Go to the Advanced Settings section of the page and scroll down to the SSL/TLS subsection.
6. Select the required Client Authentication mode.

   • Required: The server requests the client for a certificate; if the client does not provide a certificate, the connection is closed.

   • Optional: The server requests the client for a certificate, but does not require it. The connection is established even if the client does not provide a certificate.

   • False (default): Client authentication is disabled.

7. Specify the Authentication Timeout and Maximum Authentication Data parameters.

   On-screen help and prompts are provided for all of the parameters.

   When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

   At any time, you can discard the changes by clicking the Reset button.

8. After making the required changes, click Save.

   • A message, confirming that the updated listener was saved, is displayed in the Console Messages pane.

   • In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Configuring Client Authentication Using the CLI

To enable client authentication for an HTTP or TCP listener, run the set-ssl-prop command.

For example, the following command makes client authentication mandatory for the listener http-listener-1, with 60 seconds as the authentication time-out duration and 262144 bytes as the maximum length of authentication data that can be buffered.

tadm> set-ssl-prop --config=soa --http-listener=http-listener-1
 client-auth=required max-client-auth-data=262144 client-auth-timeout=60
OTD-70201 Command 'set-ssl-prop' ran successfully.

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Preventing Denial-of-Service Attacks

A denial-of-device (DoS) attack is an attempt by a malicious user to prevent legitimate users from accessing a service, by sending continuous requests to the server.

To prevent DoS attacks, you can configure Oracle Traffic Director virtual servers to reject requests when the frequency of requests or the number of concurrent connections exceeds a specified limit. For more granular control over requests, you can define several request limits and configure each limit to be applied to requests that match specified URL patterns and query string patterns, request headers that match specified values, and so on.

This section contains the following subsections:

• Request Limiting Parameters

• Configuring Request Limits for a Virtual Server

Request Limiting Parameters

You can specify multiple request limits for a virtual server. For each request limit, you can configure several parameters:

• You can make each request limit applicable to requests fulfilling a specified condition that you specify using expressions such as the following:

  $path = "*.jsp"
  $url = "/images/*"
  $ip =~ "^130\.35\.46\..*"
  

  You can use any variable or a combinations of variables to specify the condition for a limit. For more information about building expressions for request limit conditions, see "Using Variables, Expressions, and String Interpolation" in the Oracle Traffic Director Configuration Files Reference.

• In each request limit, you can specify the number of concurrent requests (max-connections) and the average number of requests per second (max-rps).

  For example, if you specify a limit (say, max-rps=20), Oracle Traffic Director continuously tracks the request rate by recalculating it at a compute interval that you specify (default: 30 seconds), based on the number of requests received during that interval. When the specified request limit is reached, Oracle Traffic Director rejects all subsequent requests.

• You can also specify an optional attribute that Oracle Traffic Director should monitor when applying request limits. Oracle Traffic Director uses separate counters to track the request statistics for each monitored attribute.

  For example, to specify that Oracle Traffic Director should track the request rate separately for each client IP, you can specify the variable $ip as the monitor attribute. When the request rate exceeds the specified limit for any client, subsequent requests from that client are rejected, but requests from other clients continue to be served.

  You can also combine variables when specifying the attribute to be monitored. For example, to limit requests from clients that request the same URIs too frequently, you can specify $ip:$uri as the attribute to be monitored. When the request rate from any client for any single URI exceeds the limit, further requests to the same URI from that client are rejected, but requests from that client to other URIs, as well as requests from other clients to any URI continue to be served.

• For requests that Oracle Traffic Director rejects, it returns the HTTP response code that you specify. The default status code is 503 (service unavailable).

• After a specified limit—max-connections or max-rps—is reached, Oracle Traffic Director continues to reject all subsequent requests until a specified continue condition is satisfied. You can specify one of the following continue conditions:

  • Threshold (default): Service resumes when the request rate falls below the specified limit.

  • Silence: Service resumes when the incoming request falls to zero for an entire interval.

Configuring Request Limits for a Virtual Server

You can configure request limits for a virtual server by using either the administration console or the CLI.

Note:

• When you modify a virtual server, you are, in effect, modifying a configuration. So for the new virtual-server settings to take effect in the Oracle Traffic Director instances, you should redeploy the configuration as described in Deploying a Configuration.

• The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Configuring Request Limits Using the Administration Console

To configure request limits by using the administration console, do the following:

1. Log in to the administration console, as described in Accessing the Administration Console.

2. Click the Configurations button that is situated at the upper left corner of the page.

   A list of the available configurations is displayed.

3. Select the configuration for which you want to configure request limits.

4. In the navigation pane, expand Virtual Servers, expand the name of the virtual server for which you want to configure request limits, and select Request Limits.

   The Request Limits page is displayed. It lists the request limits that are currently defined for the virtual server.

   Creating a Request Limit

   1. Click New Request Limit.

      The New Request Limit dialog box is displayed.

      In the Name field, enter a name for the new request limit.

      In the Connections field, specify the maximum number of concurrent connections to the virtual server.

      In the Requests Per Second field, specify the maximum number of requests that the virtual server can accept per second.

      Note:

      You must specify at least one of the limits—maximum number of connections or maximum number of requests per second.

      In the Monitor Attribute field, specify the attribute in the request header, which the virtual server should monitor for applying the request limit. If you do not specify this parameter, the request limit is applied to all requests.

   2. Click Next.

      If this is the first request limit for the virtual server, the New Caching Rule dialog box gives you the option to choose whether the limit should be applied to all requests. Select All Requests.

      If you wish to apply the limit to only those requests that satisfy a condition, create a new condition by selecting Create a new condition. In the New Expression pane, select a Variable/Function and an Operator from the respective drop-down lists and provide a value in the Value field.

      Select the and/or operator from the drop-down list when configuring multiple expressions. Similarly, use the Not operator when you want the route to be applied only when the given expression is not true.

      To enter a condition manually, click Cancel and then click Edit Manually. In the Condition field, specify the condition under which the request limit should be applied. For information about building condition expressions, click the help button near the Condition field or see "Using Variables, Expressions, and String Interpolation" in the Oracle Traffic Director Configuration Files Reference.

   3. Click Next and then click Create Request Limit.

      The request limit that you just created is displayed on the Request Limits page.

      In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

   Editing a Request Limit

   To change the settings of a request limit, do the following:

   1. Click the Name of the request limit.

      The Editing Request Limit page is displayed.

      Note:

      To access the condition builder to edit conditions, select Requests satisfying the condition and click Edit. The condition builder enables you to delete old expressions and add new ones.

   2. Specify the parameters that you want to change.

      While editing a request limit, in addition to changing the parameters that you specified while creating the request limit, you can set and change the requests-per-second compute interval, and the HTTP status code that the virtual server should return for requests that it rejects when the specified limits are reached. In addition, you can edit the condition that you have set by clicking Edit, which allows you to edit the condition either manually or using the condition builder. You can also delete old expressions and add new ones.

      On-screen help and prompts are provided for all of the parameters.

      When you change the value in a field or tab out of a text field that you changed, the Save button near the upper right corner of the page is enabled.

      At any time, you can discard the changes by clicking the Reset button.

   3. After making the required changes, click Save.

      A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.

      In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

   Deleting a Request Limit

   To delete a request limit, click the Delete button. At the confirmation prompt, click OK.

Configuring Request Limits Using the CLI

• To create a request limit, run the create-request-limit command.

  Examples:

  • The following command creates a request limit named limit_ip in the virtual server soa.example.com of the configuration soa, to limit the number of concurrent requests from any single client to 5.

    tadm> create-request-limit --config=soa --vs=soa.example.com --max-connections=5 limit_ip
    OTD-70201 Command 'create-request-limit' ran successfully.
    

  • The following command creates a request limit named limit_subnet in the virtual server soa.example.com of the configuration soa, to limit the number of requests per second from the client IP addresses in the subnet 111.23.30.* to 20.

    tadm> create-request-limit --config=soa --vs=soa.example.com --condition="$ip='111.12.30.*'" --max-rps=20 limit_subnet
    OTD-70201 Command 'create-request-limit' ran successfully.
    

  Note that the value of the --condition option should be a regular expression. For information about building condition expressions, see "Using Variables, Expressions, and String Interpolation" in the Oracle Traffic Director Configuration Files Reference.

• To view a list of the request limits defined for a virtual server, run the list-request-limits command, as shown in the following example:

  tadm> list-request-limits --config=soa --vs=soa.example.com
  request-limit   condition
  -------------------------
  limit_ip       -
  limit_subnet   "$ = '111.23.30.*'"
  

• To view the properties of a request limit, run the get-request-limit-prop command, as shown in the following example:

  tadm> get-request-limit-prop --config=soa --vs=soa.example.com --request-limit=limit_ip
  continue-condition=silence
  condition="$ip = '111.23.30.*'"
  error-code=503
  max-connections=50
  rps-compute-interval=30
  max-rps=20
  request-limit=limit_ip
  

• To change the properties of a request limit, run the set-request-limit-prop command.

  For example, the following command changes the request-per-second compute interval of the request limit limit_ip in the virtual server soa.example.com of the configuration soa to 60 seconds.

  tadm> set-request-limit-prop --config=soa --vs=soa.example.com --rule=loan-rule rps-compute-interval=60
  

• To delete a request limit, run the delete-request-limit command, as shown in the following example:

  tadm> delete-request-limit --config=soa --vs=soa.example.com limit_ip
  OTD-70201 Command 'delete-request-limit' ran successfully.
  

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.