|
Oracle® HTTP Server Administrator's Guide
10g Release 2 (10.1.2) B14007-04 |
|
 Previous |
 Next |
|
Oracle® HTTP Server Administrator's Guide
10g Release 2 (10.1.2) B14007-04 |
|
|
Previous |
Next |
This chapter contains information about enabling and configuring SSL for Oracle HTTP Server.
Topics discussed are:
Secure Sockets Layer (SSL) is an encrypted communication protocol that is designed to securely send messages across the Internet. It resides between Oracle HTTP Server on the application layer and the TCP/IP layer, transparently handling encryption and decryption when a secure connection is made by a client.
One common use of SSL is to secure Web HTTP communication between a browser and a Web server. This case does not preclude the use of non-secured HTTP. The secure version is simply HTTP over SSL (named HTTPS). The differences are that HTTPS uses the URL scheme https:// rather than http://, and its default communication port is 4443 on UNIX or 443 on Windows.
mod_ossl is a plug-in to Oracle HTTP Server that enables the server to use SSL.
By default, SSL is disabled when you install Oracle Application Server. Perform the following tasks to enable and configure SSL:
To configure Oracle HTTP Server for SSL, you need a wallet that contains the certificate for the server. Wallets store your credentials, such as certificate requests, certificates, and private keys.
The default wallet that is automatically installed with Oracle HTTP Server is for testing purposes only. A real wallet has to be created for your production server. The default wallet is located in ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default. You can either place the new wallet in that location, or change the SSLWallet directive in ORACLE_HOME/Apache/Apache/conf/ssl.conf to point to the location of your real wallet.
|
See Also: Oracle Application Server Administrator's Guide for instructions on creating a wallet. It is important that you do the following:
|
Perform the following steps to enable SSL:
Open opmn.xml in a text editor.
In the <ias-component id="HTTP_Server"> entry, change the start mode from "ssl-disabled" to "ssl-enabled". After modification is made, the entry should look like the following:
<data id="start-mode" value="ssl-enabled"/>
Save and close opmn.xml.
Update the distributed cluster management database with the change:
ORACLE_HOME/dcm/bin/dcmctl updateconfig -ct opmn
Reload OPMN using the following command:
opmnctl reload
Stop Oracle HTTP Server using Application Server Control Console, or with the following command:
UNIX: ORACLE_HOME/opmn/bin> opmnctl [verbose] stopproc ias-component=HTTP_Server
Windows: ORACLE_HOME\opmn\bin> opmnctl [verbose] stopproc ias-component=HTTP_Server
Start Oracle HTTP Server using Application Server Control Console, or with the following command:
UNIX: ORACLE_HOME/opmn/bin> opmnctl [verbose] startproc ias-component=HTTP_Server
Windows: ORACLE_HOME\opmn\bin> opmnctl [verbose] startproc ias-component=HTTP_Server
|
Note: Be sure that you stop and start Oracle HTTP Server as per the instructions. Restarting Oracle HTTP Server does not yield the same result as stopping and starting it. |
You can verify if SSL was enabled successfully by navigating to the SSL port, for example:
HTTPS://hostname:4443
Optionally, you can further customize your configuration using mod_ossl directives.
|
Note: The templates files installed during installation contain all the necessary SSL configuration directives and a default setup for SSL. |
To enable client authentication, do the following:
Specify SSLVerifyClient on the server side.
Use proper client certificate on your client side for the HTTPS connection. Refer to your client documentation for information on getting and using a client certificate. Be sure that your client certificate is trusted by the server wallet.
|
See Also: Oracle Application Server Administrator's Guide for instructions on how to import a trusted certificate into your wallet. |
This section contains SSL features that are supported for this release.
This feature adds support SSL protocol features called variously "step-up", "server gated crypto" or "global server ID". "Step-up" is a feature that allows old, weak encryption browsers, to "step-up" so that public keys greater than 512 bits and bulk encryption keys greater than 64 bits can be used in the SSL protocol. This means that server X.509 certificates that contain public keys in excess of 512 bits and which contain "step-up" digital rights can now be used by Oracle Application Server. Such certificates are often called "128 bit" certificates, even though the certificate itself typically contains a 1024 bit certificate. The Verisign Secure Site Pro is an example of such a certificate which can now be used by Oracle Application Server.
Global Server ID functionality is provided by default, there is no configuration necessary.
Public-Key Cryptography Standards #11, or PKCS #11 for short, is a public key cryptography specification that outlines how systems use hardware security modules, which are basically "boxes" where cryptographic functions (encryption/decryption) are performed and where encryption keys are stored.
Oracle HTTP Server supports the option of having dedicated SSL hardware through nCipher. nCipher is a certified third party accelerator that improves the performance of the PKI cryptography that SSL uses.
mod_ossl provides standard support for HTTPS protocol connections to Oracle Application Server. It enables secure connections between Oracle HTTP Server and a browser client by using an Oracle-provided encryption mechanism over SSL. It may also be used for authentication over the Internet through the use of digital certificate technology. It supports SSL v. 3.0, and provides:
Encrypted communication between client and server, using RSA or DES encryption standards.
Integrity checking of client-server communication using MD5 or SHA checksum algorithms.
Certificate management with Oracle wallets.
The following mod_ssl directives are not supported by mod_ossl.
|
Note: The server will not start if these directives are used. |
To configure SSL for your Oracle HTTP Server, enter the mod_ossl directives you want to use in the httpd.conf file.
The following directives are described in subsequent sections:
Specifies if SSL accelerator is used. Currently only nFast card is supported.
| Category | Value |
|---|---|
| Valid Values | yes/no
|
| Syntax | SSLAccelerator yes|no
|
| Default | SSLAccelerator no
|
| Context | server configuration |
|
Note: TheSSLAccelerator directive has been deprecated. For information on enabling SSL acceleration support using a wallet, refer to the Oracle Advanced Security Administrator's Guide on http://www.oracle.com/technology/documentation.
|
Specifies the file where you can assemble the Certificate Revocation Lists (CRLs) from CAs (Certificate Authorities) that you accept certificates from. These are used for client authentication. Such a file is the concatenation of various PEM-encoded CRL files in order of preference. This directive can be used alternatively or additionally to SSLCARevocationPath.
| Category | Value |
|---|---|
| Syntax | SSLCARevocationFile file_name
|
| Example | SSLCARevocationFile /ORACLE_HOME/Apache/Apache/conf/ssl.crl/ca_bundle.crl
|
| Default | None |
| Context | server configuration, virtual host |
Specifies the directory where PEM-encoded Certificate Revocation Lists (CRLs) are stored. These CRLs come from the CAs (Certificate Authorities) that you accept certificates from. If a client attempts to authenticate itself with a certificate that is on one of these CRLs, then the certificate is revoked and the client cannot authenticate itself with your server.
| Category | Value |
|---|---|
| Syntax | SSLCARevocationPath path/to/CRL_directory/
|
| Example | SSLCARevocationPath /ORACLE_HOME/Apache/Apache/conf/ssl.crl/
|
| Default | None |
| Context | server configuration, virtual host |
Specifies the SSL cipher suite that the client can use during the SSL handshake. This directive uses a colon-separated cipher specification string to identify the cipher suite. Table 11-2 shows the tags you can use in the string to describe the cipher suite you want.
Tags are joined together with prefixes to form a cipher specification string.
| Category | Value |
|---|---|
| Valid Values | none: Adds the cipher to the list
|
| Example | SSLCipherSuite ALL:!LOW:!DH
In this example, all ciphers are specified except low strength ciphers and those using the Diffie-Hellman key negotiation algorithm. |
| Syntax | SSLCipherSuite cipher-spec
|
| Default | ALL:!ADH:!EXPORT56:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
|
| Context | server configuration, virtual host, directory |
Table 11-1 SSLCipher Suite Tags
| Function | Tag | Meaning |
|---|---|---|
|
Key exchange |
|
|
|
Key exchange |
|
Diffie-Hellman key exchange with RSA key |
|
Authentication |
|
No authentication |
|
Authentication |
|
|
|
Authentication |
|
Diffie-Hellman authentication |
|
Encryption |
|
No encryption |
|
Encryption |
|
|
|
Encryption |
|
Triple |
|
Encryption |
|
|
|
Data Integrity |
|
|
|
Data Integrity |
|
|
|
Aliases |
|
All SSL version 3.0 ciphers |
|
Aliases |
|
All export ciphers |
|
Aliases |
|
All 40-bit export ciphers only |
|
Aliases |
|
All 56-bit export ciphers only |
|
Aliases |
|
All low strength ciphers (export and single |
|
Aliases |
|
All ciphers with 128-bit encryption |
|
Aliases |
|
All ciphers using triple |
|
Aliases |
|
All ciphers using |
|
Aliases |
|
All ciphers using Diffie-Hellman key exchange |
|
Note: There are restrictions if export versions of browsers are used. Oracle module,mod_ossl, supports RC4-40 encryption only when the server uses 512 bit key size wallets.
|
Table 11-2 Cipher Suites Supported in Oracle Advanced Security 10i
| Cipher Suite | Authentication | Encryption | Data Integrity |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Toggles the usage of the SSL Protocol Engine. This is usually used inside a <VirtualHost> section to enable SSL for a particular virtual host. By default, the SSL Protocol Engine is disabled for both the main server and all configured virtual hosts. Example 11-1 is an example for using SSLEngine directive. The default SSL is 4443 on UNIX and 443 on Windows.
| Category | Value |
|---|---|
| Syntax | SSLEngine on|off
|
| Default | SSLEngine off
|
| Context | server configuration, virtual host |
Specifies where the SSL engine log file will be written. (Error messages will also be duplicated to the standard Oracle HTTP Server log file specified by the ErrorLog directive.)
Place this file at a location where only root can write, so that it cannot be used for symlink attacks. If the filename does not begin with a slash (/), it is assumed to be relative to the ServerRoot. If the filename begins with a bar (|), then the string following the bar is expected to be a path to an executable program to which a reliable pipe can be established.
This directive should occur only once per virtual server configuration.
| Category | Value |
|---|---|
| Syntax | SSLVerifyClient path/to/filename
|
| Default | None |
| Context | server configuration, virtual host |
Specifies the verbosity degree of the SSL engine log file.
| Category | Value |
|---|---|
| Valid Values | The levels are (in ascending order, where each level is included in the levels preceding it):
|
| Syntax | SSLLogLevel level
|
| Default | None |
| Context | server configuration, virtual host |
Type of semaphore (lock) for SSL engine's mutual exclusion of operations that have to be synchronized between Oracle HTTP Server processes.
| Category | Value |
|---|---|
| Valid Values |
|
| Example | SSLMutex file:/usr/local/apache/logs/ssl_mutex
|
| Syntax | SSLMutex type
|
| Default | SSLMutex none
|
| Context | server configuration |
Controls various runtime options on a per-directory basis. In general, if multiple options apply to a directory, the most comprehensive option is applied (options are not merged). However, if all of the options in an SSLOptions directive are preceded by a plus ('+') or minus ('-') symbol, then the options are merged. Options preceded by a plus are added to the options currently in force, and options preceded by a minus are removed from the options currently in force.
| Category | Value |
|---|---|
| Valid Values |
|
Valid Values (for SSLOptions continued)
|
|
| Syntax | SSLOptions [+-] option
|
| Default | None |
| Context | server configuration, virtual host, directory |
Type of pass phrase dialog for wallet access. mod_ossl asks the administrator for a pass phrase in order to access the wallet.
| Category | Value |
|---|---|
| Valid Values |
|
| Syntax | SSLPassPhraseDialog type
|
| Example | SSLPassPhraseDialog exec:/usr/local/apache/sbin/pfilter
|
| Default | SSLPassPhraseDialog builtin
|
| Context | server configuration |
Specifies SSL protocol(s) for mod_ossl to use when establishing the server environment. Clients can only connect with one of the specified protocols.
| Category | Value |
|---|---|
| Valid Values | SSLv2, SSLv3, TLSv1, ALL |
| Example | To specify only SSL version 3.0, set this directive to the following:
|
| Syntax | SSLProtocol [+-] protocol
|
| Default | SSLProtocol ALL
|
| Context | server configuration, virtual host |
Denies access unless an arbitrarily complex boolean expression is true.
| Category | Value |
|---|---|
| Syntax | SSLRequire expression
|
| Default | None |
| Context | directory |
The expression must match the following syntax (given as a BNF grammar notation):
expr ::= "true" | "false"
"!" expr
expr "&&" expr
expr "||" expr
"(" expr ")"
comp ::=word "==" word | word "eq" word
word "!=" word |word "ne" word
word "<" word |word "lt" word
word "<=" word |word "le" word
word ">" word |word "gt" word
word ">=" word |word "ge" word
word "=~" regex
word "!~" regex
wordlist ::= word
wordlist "," word
word ::= digit
cstring
variable
function
digit ::= [0-9]+
cstring ::= "..."
variable ::= "%{varname}"
Table 11-3 and Table 11-4 list standard and SSL variables. These are valid values for varname.
function ::= funcname "(" funcargs ")"
For funcname, the following function is available:
file(filename)
The file function takes one string argument, the filename, and expands to the contents of the file. This is useful for evaluating the file's contents against a regular expression.
Table 11-3 lists the standard variables for SSLRequire varname.
Table 11-3 Standard Variables for SSLRequire Varname
| Standard Variables | Standard Variables | Standard Variables |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 11-4 lists the SSL variables for SSLRequire varname.
Table 11-4 SSL Variables for SSLRequire Varname
| SSL Variables | SSL Variables | SSL Variables |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Denies access to clients not using SSL. This is a useful directive for absolute protection of a SSL-enabled virtual host or directories in which configuration errors could create security vulnerabilities.
| Category | Value |
|---|---|
| Syntax | SSLRequireSSL
|
| Default | None |
| Context | directory |
Specifies the global/interprocess session cache storage type. The cache provides an optional way to speed up parallel request processing.
| Category | Value |
|---|---|
| Valid Values |
|
| Syntax | SSLSessionCache type
|
| Examples | SSLSessionCache shmht: /ORACLE_HOME/Apache/Apache/logs/ssl_scache(512000)
|
| Default | SSLSessionCache none
|
Specifies the number of seconds before a SSL session in the session cache expires.
| Category | Value |
|---|---|
| Syntax | SSLSessionCacheTimeout seconds
|
| Default | 300 |
| Context | server configuration |
Specifies whether or not a client must present a certificate when connecting.
| Category | Value |
|---|---|
| Valid Values |
|
| Syntax | SSLVerifyClient level
|
| Default | None |
| Context | server configuration, virtual host |
|
Note: The leveloptional_no_ca included with mod_ssl (in which the client can present a valid certificate, but it need not be verifiable) is not supported in mod_ossl.
|
Specifies the location of the wallet with its WRL.
| Category | Value |
|---|---|
| Syntax | SSLWallet wrl
The format of |
| Example | SSLWallet file:/etc/ORACLE/WALLETS/server
Other values of wrl may be used as permitted by the Oracle SSL product. |
| Default | None |
| Context | server configuration, virtual host |
Specifies the Wallet password needed to access the wallet specified within the same context. You can choose either a cleartext wallet password or an obfuscated password. The obfuscated password is created with the command line tool iasobf. If you must use a regular wallet, Oracle recommends that you use the obfuscated password instead of a cleartext password.
| Category | Value |
|---|---|
| Syntax | SSLWalletPassword password
If no password is required do not set this directive. Note: If a wallet created with the Auto Login feature of Oracle Wallet Manager is used, then do not set this directive because these wallets do not require passwords. |
| Default | None |
| Context | server configuration, virtual host |
|
Note: SSLWalletPassword has been deprecated. A warning message is generated in the Oracle HTTP Server log if this directive is used. For secure wallets, Oracle recommends that you get a SSO wallet, with auto-login enabled, instead. Refer to the"Task 1: Creating a Real Wallet".
|
The iasobf utility enables you to generate an obfuscated wallet password from a cleartext password.
If you are using an Oracle Wallet that has been created with Auto Login enabled (an SSO wallet), then you do not need to use this utility. However, if you must use a regular wallet with a password, then Oracle recommends that you use the password obfuscation tool iasobf, which is located in ORACLE_HOME/Apache/Apache/bin, to generate an obfuscated wallet password from a cleartext password.
To generate an obfuscated wallet password, the command syntax is:
iasobf -p password
The obfuscated password is printed to the terminal. iasobf requires operating system user of httpd process. Accordingly, use the root argument for UNIX or system argument for Windows. For example, on UNIX, the command will be iasobf -password root.
|
Note: The corresponding tool for Windows environments is calledosslpassword, which can be used in the same way as iasobf.
|
The following directives are for mod_proxy support only:
Specifies whether the proxy cache will be used. The proxy will use the same session as the SSL server uses.
| Category | Value |
|---|---|
| Syntax | SSLProxyCache on/off
|
| Default | SSLProxyCache off
|
| Context | server configuration, virtual host |
Specifies the proxy server's cipher suite.
| Category | Value |
|---|---|
| Syntax | SSLCipherSuite cipher-spec
|
| Default | None
|
| Context | server configuration, virtual host |
Controls the proxy server's SSL protocol flavors.
| Category | Value |
|---|---|
| Syntax | SSLProxyProtocol [+-] protocol
|
| Default | None
|
| Context | server configuration, virtual host |
Specifies the location of the wallet containing the certificates to use when opening proxy connections.
| Category | Value |
|---|---|
| Syntax | SSLProxyWallet wrl
|
| Default | None
|
| Context | server configuration, virtual host |
Specifies the proxy wallet password.
| Category | Value |
|---|---|
| Syntax | SSLProxyWalletPassword password
|
| Default | None
|
| Context | server configuration, virtual host |
|
Note: SSLProxyWalletPassword has been deprecated. A warning message is generated in the Oracle HTTP Server log if this directive is used. For secure wallets, Oracle recommends that you get a SSO wallet instead.
|
