This chapter contains the following sections:
Configuring SSL/TLS Between Oracle Traffic Director and Clients
Configuring SSL/TLS Between Oracle Traffic Director and Origin Servers
Note:
For information about some steps that you can take to secure Oracle Traffic Director in your environment, see Securing Oracle Traffic Director Deployment.
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Nodes button that is situated near the upper left corner of the page.
A list of available nodes is displayed.
From the list of nodes, select Administration Server.
In the navigation pane, select Authentication.
The Authentication page is displayed.
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.
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:
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>
Enter the new password.
A prompt to re-enter the new password is displayed:
Enter admin-password again>
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.
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:
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.
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
Log in to the administration console, as described in Accessing the Administration Console.
Click the Nodes button that is situated near the upper left corner of the page.
A list of the available nodes is displayed.
Select the Administration Server node.
The General Settings page is displayed.
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.
After making the required changes, click Save.
A message, confirming that the updated configuration was saved, is displayed in the Console Messages pane.
Stop the administration server by clicking Stop in the Common Tasks pane.
Start the administration server, by running the following command:
> $INSTANCE_HOME/admin-server/bin/startserv
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
For more information about set-token-pin
, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help
option.
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.
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:
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:
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:
Install the certificates as described in Installing a Certificate.
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.
Configure ciphers supported for the HTTP or TCP listeners as described in Configuring SSL/TLS Ciphers 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:
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.
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:
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.
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:
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.
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
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.
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.
This section provides basic information about security-related concepts. It contains the following topics:
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:
The browser attempts to connect to the server by sending a URL that begins with http
s
://
instead of http://
.
The server sends its digital certificate (see "About Certificates") and public key to the client.
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.
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.
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
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:
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.
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.
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
.
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:
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.
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
.
Configure Oracle Traffic Director to trust each of the origin servers' certificates, as described in Configuring Oracle Traffic Director to Trust Certificates.
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.
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.
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.
This section contains the following topics:
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to create an self-signed certificate.
In the navigation pane, expand SSL and select Server Certificates.
The Server Certificates page is displayed.
Click the New Self-Signed Certificate button.
The New Self-Signed Certificate wizard starts.
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.
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.
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".
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.
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to create a CSR.
In the navigation pane, expand SSL and select Server Certificates.
The Server Certificates page is displayed.
Click the Create Certificate Request button.
The Create Certificate Signing Request wizard starts.
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.
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.
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".
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-----
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.
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
To install a self-signed or CA-signed certificate by using the administration console, do the following:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to install a certificate.
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.
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
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.
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.
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".
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-----
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:
Add ORACLE_HOME/lib
to your path.
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- ]
Enter the database and/or token password. For more information about PKCS#11 tokens, see Managing PKCS#11 Tokens.
Associate the certificate that you installed with one more listeners. For more information, see Configuring SSL/TLS for a Listener.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to view certificates.
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.
Click Cache Token Pin.
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.
To renew a certificate, do the following:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to renew certificates.
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.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
Click the Renew button for the certificate that you want to renew.
The Renew Server Certificate dialog box is displayed.
Specify the new validity period and click Next.
Click Renew Certificate.
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to delete certificates.
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.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to change certificate trust flags.
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.
Click Cache Token Pin.
In the resulting dialog box, enter the pins for the tokens, and click OK.
Click the nickname of the certificate for which you want to change the trust flags.
The Edit Certificate Authority dialog box is displayed.
Select the Trusted to Sign Client Certificates or Trusted to Sign Server Certificates check box, as required.
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to configure tokens.
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.
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:
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:
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.
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:
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Click the name of the configuration that you want to set up to install CRLs automatically.
In the navigation pane, select SSL.
The SSL Settings page is displayed.
Go to the Advanced Settings section of the page.
In the Update CRL Path field, enter the absolute path to the directory that contains the updated CRL files.
Click New Event.
The New CRL Update Event dialog box is displayed.
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:
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.
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:
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.
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to configure web application firewall.
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.
On the Web Application Firewall page, click Enabled to enable web application firewall for a particular virtual server.
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.
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.
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:
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.
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:
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.
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>)
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:
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.
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:
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.
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:
Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.
A list of the available configurations is displayed.
Select the configuration for which you want to configure request limits.
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
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.
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.
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:
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.
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.
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.