| Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
OC4J supports Secure Sockets Layer (SSL) communication, as follows:
In an Oracle Application Server environment (OPMN-managed), OC4J supports SSL communication between Oracle HTTP Server and OC4J using AJPS. This is the secure version of Apache JServ Protocol, the protocol that Oracle HTTP Server uses to communicate with OC4J. (Note, however, that the AJPS protocol used between Oracle HTTP Server and OC4J is not visible to the end user.)
In a standalone OC4J environment, or in an OPMN-managed environment without Oracle HTTP Server, OC4J supports SSL communication directly between a client and OC4J, using HTTPS.
OC4J supports ORMI over SSL, or ORMIS. With this feature, OC4J supports RMI communication over SSL between objects across OC4J server instances.
OC4J supports TCP over SSL, or TCPS. With this feature, communication between an OC4J data source and the database is secured.
Note that this chapter discusses the standalone OC4J scenario as well as two scenarios in an Oracle Application Server environment—OPMN-managed OC4J with OC4J as the Web listener, and OPMN-managed OC4J with Oracle HTTP Server as the Web listener. In all, the following topics are covered:
Integrating the Security Provider with SSL-Enabled Applications
Using Keys and Certificates with OC4J and Oracle HTTP Server
Notes:
Secure communication between a client and Oracle HTTP Server is independent of secure communication between Oracle HTTP Server and OC4J.
This chapter assumes some prior knowledge of security and SSL concepts.
See Also:
"Transport-Level Security" (overview)
Oracle HTTP Server Administrator's Guide for related information about using SSL with Oracle HTTP Server
Oracle Application Server Administrator's Guide for information about configuring additional Oracle Application Server components to take advantage of SSL
This section describes the responsibilities of Oracle components when an HTTP client request is initiated in an SSL-enabled J2EE environment. Figure 15-1 shows an application running in such an environment.
Figure 15-1 Oracle Component Integration in SSL-Enabled J2EE Environments
Here are the steps of the process:
An HTTP client attempts to access a Web application (named WebApp A1) hosted by OC4J. Oracle HTTP Server handles the request.
The mod_ossl/Oracle HTTP Server receives the request and determines that the WebApp A1 application requires SSL server authentication for HTTP clients.
If a server or client wallet certificate is configured, the HTTP client is prompted to accept the server certificate of Oracle HTTP Server and provide the client certificate.
OC4J security provider retrieves the SSL client certificate.
The security provider retrieves the SSL user from the certificate.
The final step or steps depend on the jaas-mode setting in the <jazn> element. Refer to "Introduction to JAAS Mode" and "Configuring and Using JAAS Mode" for information about how JAAS mode works.
The steps below describe using keys and certificates for SSL communication in OC4J. These are server-level steps, typically executed prior to deployment of an application that will require secure communication, perhaps when you first set up an Oracle Application Server instance.
Note that a keystore stores certificates, including the certificates of all trusted parties, for use by an application. Through its keystore, an entity such as OC4J (for example) can authenticate other parties, as well as authenticate itself to other parties. Oracle HTTP Server uses what is called a wallet for the same purpose.
In Java, a keystore is a java.security.KeyStore instance that you can create and manipulate using the keytool utility that is provided with the Sun Microsystems JDK. The underlying physical manifestation of this object is a file.
The Oracle Wallet Manager has functionality for Oracle wallets that is equivalent to the functionality of keytool for keystores.
Notes:
A keystore or wallet must include a private key, a public key, and a trusted certificate (such as a CA certificate) in order to be used in establishing trust relationships.
OC4J comes with a default wallet that does not include a trusted certificate. You should create and provision your own wallet instead of using the default wallet.
See Also:
For information about keytool:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
For information on Oracle Wallet Manager, the Oracle Application Server Administrator's Guide
Here are the steps at the OC4J end for using certificates between OC4J and Oracle HTTP Server:
Use keytool to generate a private key, public key, and unsigned certificate.You can place this information into either a new keystore or an existing keystore.
Obtain a signature for the certificate, using either of the following two approaches.
Generate your own signature:
Use keytool to "self-sign" the certificate. This is appropriate if your clients trust you as, in effect, your own certificate authority.
Alternatively, obtain a signature from a recognized certificate authority:
Using the certificate from Step 1, use keytool to generate a certificate request, which is a request to have the certificate signed by a certificate authority.
Submit the certificate request to a certificate authority (such as Verisign or Thawte; links following shortly).
Receive the signature from the certificate authority and import it into the keystore, again using keytool. In the keystore, the signature is matched with the associated certificate.
Note:
Oracle Application Server includes Oracle Application Server Certificate Authority (OCA). OCA enables customers to create and issue certificates for themselves and their users, although these certificates would probably be unrecognized outside a customer's organization without prior arrangements.See Also:
Oracle Application Server Certificate Authority Administrator's Guide for information about OCA
The process for requesting and receiving signatures is up to the particular certificate authority you use. Because that is outside the scope and control of Oracle Application Server, this document does not cover it. You can go to the Web site of any certificate authority for information. (Any browser should have a list of trusted certificate authorities.) Here are the Web addresses for VeriSign, Inc. and Thawte, Inc., for example:
http://www.verisign.com/ http://www.thawte.com/
For SSL communication between OC4J and Oracle HTTP Server, at the Oracle HTTP Server end you must execute the following steps as necessary.
Execute steps equivalent to the preceding steps for OC4J, but using a wallet and Oracle Wallet Manager instead of a keystore and the keytool utility.
As appropriate: If the OC4J certificate is signed by an entity that Oracle HTTP Server does not yet trust, obtain the certificate of the entity and import it into Oracle HTTP Server. The specifics depend on whether the OC4J certificate in question is self-signed, as follows.
If OC4J has a self-signed certificate (essentially, Oracle HTTP Server does not yet trust OC4J):
From OC4J, use keytool to export the OC4J certificate. This step places the certificate into a file that is accessible to Oracle HTTP Server.
From Oracle HTTP Server, use Oracle Wallet Manager to import the OC4J certificate.
Alternatively, if OC4J has a certificate that is signed by another entity (that Oracle HTTP Server does not yet trust):
Obtain the certificate of the entity in any appropriate way, such as by exporting it from the entity. The exact steps vary, depending on the entity.
From Oracle HTTP Server, use Oracle Wallet Manager to import the certificate of the entity.
As appropriate: If the Oracle HTTP Server certificate is signed by an entity that OC4J does not yet trust, and OC4J is in a mode of operation that requires client authentication:
(This is discussed in "Requesting Client Authentication".)
Obtain the certificate of the entity in any appropriate way, such as by exporting it from the entity. The exact steps vary, depending on the entity.
From OC4J, use keytool to import the certificate of the entity.
Note:
During communications over SSL between Oracle HTTP Server and OC4J, all data on the communications channel between the two is encrypted. The following steps are executed:The OC4J certificate chain is authenticated to Oracle HTTP Server during establishment of the encrypted channel.
Optionally, if OC4J is in client-authentication mode, Oracle HTTP Server is authenticated to OC4J. This process also occurs during establishment of the encrypted channel.
Any further communication after this initial exchange will be encrypted.
Standalone OC4J supports SSL communication directly between a client and OC4J, using HTTPS. This section describes how to accomplish this.
Use the following steps:
Create a keystore with an RSA private/public key pair using the keytool utility. In this example, we generate a keystore to reside in a file named mykeystore.jks, which has a password of 123456, using the RSA key pair generation algorithm:
% keytool -genkey -keyalg RSA -keystore mykeystore.jks -storepass 123456
In this tool:
The keystore option sets the filename where the keys are stored.
The storepass option sets the password for protecting the keystore. You can optionally omit this from the command line and be prompted for a password instead.
The keytool prompts you for additional information, as follows:
What is your first and last name?
[Unknown]: Test User
What is the name of your organizational unit?
[Unknown]: Support
What is the name of your organization?
[Unknown]: Oracle
What is the name of your City or Locality?
[Unknown]: Redwood Shores
What is the name of your State or Province?
[Unknown]: CA
What is the two-letter country code for this unit?
[Unknown]: US
Is <CN=Test User, OU=Support, O=Oracle, L=Redwood Shores, ST=CA, C=US> correct?
[no]: yes
Enter key password for <mykey>
(RETURN if same as keystore password):
Always press RETURN for the key password. In OC4J 10.1.3.x implementations, the keystore password must be the same as the key entry password.
The mykeystore file is created in the current directory. The default alias of the key is mykey.
Note:
Thekeytool utility supports PKCS12 format wallets as well as JKS format keystores.See Also:
For detailed information about the keytool utility:
http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html
For the ISO two-letter country code list:
http://www.iso.org/iso/english_country_names_and_code_elements
If you do not have a secure-web-site.xml file, create one in the following location: ORACLE_HOME/j2ee/home/config/secure-web-site.xml (by convention). You can start by copying whatever content you need from default-web-site.xml. This typically includes the following subelements under the <web-site> element:
<web-app> (for each Web application you want to secure)
<access-log> (for logging; confirm this specifies an appropriate log file)
<default-web-app>
You will also need an <ssl-config> element for your SSL configuration; that is discussed later in this procedure.
Update secure-web-site.xml with the following elements:
Update the <web-site> element to add secure="true" and to set the port value to some available port. (For example, port="4443". To use the default of 443, you have to be a super user.) For standalone OC4J, use HTTP protocol, which is the default setting. (The setting protocol="http" in combination with secure="true" results in HTTPS being used.)
<web-site port="4443" secure="true" protocol="http"
display-name="Default OracleAS Containers for J2EE Web Site" >
...
</web-site>
(Also remember to change the display-name setting as appropriate.)
Add the following under the <web-site> element to define the keystore and password.
<ssl-config keystore="your_keystore" keystore-password="your_password" />
Where your_keystore is the path to the keystore—either absolute, or relative to ORACLE_HOME/j2ee/home/config (where the Web site XML file is located)—and your_password is the keystore password.
Note:
You can hide the password through password indirection, as described in "Using Password Indirection".Also see "Optional Steps in secure-web-site.xml" below.
Save the changes to secure-web-site.xml.
Here is an example:
<?xml version="1.0"?> <web-site display-name="OC4J 10g Secure Web Site" protocol="http" port="4443" secure="true"> <ssl-config keystore="./roadrunner.jks" keystore-password="welcome1" /> <default-web-app application="default" name="defaultWebApp" root="/" /> <web-app application="SSLDemos-Project1-WS" name="WebServices" load-on-startup="true" root="/SSLDemos-Project1-context-root" /> <access-log path="../log/default-web-access2.log" split="day" /> </web-site>
Ensure that server.xml points to the secure-web-site.xml file.
As necessary, uncomment or add the following line in server.xml:
<web-site path="./secure-web-site.xml" />
Save the changes to server.xml.
Stop and restart OC4J to initialize the secure-web-site.xml file additions. Test the SSL port by accessing the site in a browser on the SSL port. If successful, you will be asked to accept the certificate, because it is not signed by an accepted authority.
When completed, OC4J listens for SSL requests on one port and non-SSL requests on another. You can disable either SSL requests or non-SSL requests, by commenting out the appropriate *-web-site.xml pointer in the server.xml configuration file:
<web-site path="./secure-web-site.xml" /> - comment this to remove SSL <default-site path="./default-web-site.xml" /> - comment this to remove non-SSL
These Web sites must use different ports.
Optional Steps in secure-web-site.xml
In addition to the steps outlined above for configuring secure-web-site.xml, the following optional steps may be appropriate as well:
Turn on the needs-client-auth flag, an attribute of the <ssl-config> element, to specify that client authentication is required, as follows:
<web-site ... secure="true" ... > ... <ssl-config keystore="path_and_file" keystore-password="pwd" needs-client-auth="true" /> </web-site>
This step sets up a mode where OC4J accepts or rejects a client entity for secure communication according to its identity. The needs-client-auth attribute instructs OC4J to request the client certificate chain upon connection. If the root certificate of the client is recognized, then the client is accepted.
The keystore specified in the <ssl-config> element must contain the certificates of any clients that are authorized to connect to OC4J through HTTPS.
Important:
In standalone OC4J (no Oracle HTTP Server), settingneeds-client-auth="true" is required in order to use client-cert authentication mode. See "Requesting Client Authentication" for related information.Specify each application in the Web site as shared. The shared attribute of the <web-app> element indicates whether multiple bindings (different Web sites, or ports, and context roots) can be shared. Supported values are "true" and "false" (default).
Sharing implies the sharing of everything that makes up a Web application, including sessions, servlet instances, and context values. A typical use for this mode is to share a Web application between an HTTP site and an HTTPS site at the same context path, when SSL is required for some but not all of the communications. Performance is improved by encrypting only sensitive information, rather than all information.
If an HTTPS Web application is marked as shared, then instead of using the SSL certificate to track the session, the cookie is used to track the session. This is beneficial in that the SSL certificate uses 50K to store each certificate when tracking it, which sometimes results in an "out of memory" problem for the session before the session times out. This could possibly make the Web application less secure, but might be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers.
See Also:
Oracle Containers for J2EE Configuration and Administration Guide for more information about sharing Web applications between Web sites
Set the cookie domain if shared="true" and the default ports are not used. When the client interacts with a Web server over separate ports, the cookie believes that each separate port denotes a separate Web site. If you use the default ports of 80 for HTTP and 443 for HTTPS, the client recognizes these as two different ports of the same Web site and creates only a single cookie. However, if you use nondefault ports, the client does not recognize these ports as part of the same Web site and will create separate cookies for each port, unless you specify the cookie domain.
Cookie domains track the client's communication across multiple servers within a DNS domain. If you use nondefault ports for a shared environment with HTTP and HTTPS, set cookie-domain in the <session-tracking> element in the orion-web.xml file for the application. The cookie-domain attribute contains the DNS domain with at least two components of the domain name provided:
<session-tracking cookie-domain=".oracle.com" />
Specify the cipher suites to use—combinations of cryptographic specifications that define security algorithms and key sizes. (This is a server-side cipher suite setting, as opposed to HTTPClient settings discussed in Chapter 16, "Oracle Security for Client Connections".) Use the cipher-suites attribute of the <ssl-config> element in secure-web-site.xml, as in this example:
<ssl-config keystore="your_keystore" keystore-password="your_password" cipher-suites="SSL_RSA_WITH_RC4_128_SHA, SSL_RSA_WITH_RC4_128_MD5,..." />
This is a comma-delimited list of cipher suites. If you omit this attribute, the set of cipher suites used is according to those specified as "enabled by default" in the reference documentation at:
http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html
Example 15-1 HTTPS Communication with Client Authentication
The following example configures a Web site for HTTPS secure communication with client authentication:
<web-site display-name="OC4J Web Site" protocol="http" port="4443" secure="true" > <default-web-app application="default" name="defaultWebApp" /> <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="welcome" needs-client-auth="true" /> </web-site>
Only the portions in bold are specific to security. The protocol value is always "http" for HTTP communication in standalone OC4J, whether or not you use secure communication. A protocol value of http with secure="false" indicates HTTP protocol; http with secure="true" indicates HTTPS protocol.
The needs-client-auth flag instructs OC4J to request the client certificate chain upon connection. If OC4J recognizes the root certificate of the client, then the client is accepted.
The keystore that is specified in the <ssl-config> element must contain the certificates of any clients that are authorized to connect to OC4J through HTTP and SSL.
OC4J, when managed by OPMN and used as its own Web listener (in other words, without Oracle HTTP Server), supports SSL communication between a client and OC4J using HTTPS (similarly to the standalone OC4J scenario discussed previously). You must also configure OPMN to support HTTPS.
This section describes how to use SSL in this OPMN-managed scenario, involving the following steps:
Configure OC4J with SSL (Scenario without Oracle HTTP Server)
Configure OPMN to Support HTTPS (Scenario without Oracle HTTP Server)
Configuring OC4J with SSL in an OPMN-managed environment without Oracle HTTP Server is largely the same as for standalone OC4J, as covered above in "Using SSL with Standalone OC4J". Refer there for additional details.
Create a keystore.
Create secure-web-site.xml (by convention). (Copy content from default-web-site.xml as appropriate.)
Update secure-web-site.xml with the following elements:
Update the <web-site> element to add secure="true". Typically, in an OPMN-managed environment, the choice of port defers to OPMN, as indicated by setting port="0". Use protocol="http". (The setting protocol="http" in combination with secure="true" results in HTTPS being used.)
<web-site port="0" secure="true" protocol="http"
display-name="Default OracleAS Containers for J2EE Web Site" >
...
</web-site>
(Also remember to change the display-name setting as appropriate.)
Add an <ssl-config> element under <web-site> to define the keystore location and password, using the keystore and keystore-password attributes.
Save the changes to secure-web-site.xml.
Here is an example:
<web-site display-name="OC4J Web Site" protocol="http" port="0" secure="true" > <default-web-app application="default" name="defaultWebApp" root="/j2ee" /> <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="welcome" /> </web-site>
Ensure that server.xml points to secure-web-site.xml.
Stop and restart OC4J to initialize secure-web-site.xml.
Notes:
It is possible to enter a real port here, rather than port 0, if you configure OPMN to not override the setting in this Web site XML file.
In an OC4J environment without Oracle HTTP Server, setting needs-client-auth="true" is required in order to use client-cert authentication mode. See "Requesting Client Authentication" for related information.
To use SSL with OC4J in an OPMN-managed environment without Oracle HTTP Server, you must configure OPMN to support HTTPS. Update the file ORACLE_HOME/opmn/conf/opmn.xml as follows:
Under component ID "OC4J", configure the security parameters (wallet information):
<ias-component id="OC4J">
...
<category id="security-parameters">
<data id="wallet-file" value="file:walletfile"/>
<data id="wallet-password" value="pwd"/>
</category>
...
</ias-component>
Also under component ID "OC4J", specify HTTPS protocol for the Web site:
<ias-component id="OC4J">
...
<port id="secure-web-site" range="12501-12600" protocol="https"/>
...
</ias-component>
See Also:
Oracle Process Manager and Notification Server Administrator's Guide for details about OPMN and opmn.xml
In an Oracle Application Server environment, where OC4J is managed by OPMN and Oracle HTTP Server is the Web listener, OC4J supports SSL communication between Oracle HTTP Server and OC4J using AJPS (the secure version of Apache JServ Protocol). This section describes how to use SSL in this scenario, involving the following:
This discussion concludes with sample configuration files.
Note:
In Oracle Application Server 10.1.3.x implementations, SSL is enabled by default for communication between Oracle HTTP Server and the client. No special steps are required. Note that this is unrelated to the discussion in this section for using SSL between OC4J and Oracle HTTP Server.See Also:
Oracle HTTP Server Administrator's Guide for related information about using SSL with Oracle HTTP Server, including how to customize your configuration to enable client authentication
Oracle Application Server Administrator's Guide for information about configuring additional Oracle Application Server components to take advantage of SSL
Configuring OC4J with SSL in an Oracle Application Server environment is largely the same as for standalone OC4J, as covered above in "Using SSL with Standalone OC4J". Refer there for additional details.
Create a keystore.
Create secure-web-site.xml (by convention). Copy content from default-web-site.xml as appropriate.
Update secure-web-site.xml with the following elements:
Update the <web-site> element to add secure="true". Typically, in an Oracle Application Server environment, the choice of port defers to OPMN (as indicated by the port="0" setting, which is added automatically). Also, use protocol="ajp13", which is the default setting in an Oracle Application Server environment. (The setting protocol="ajp13" in combination with secure="true" results in AJPS being used.)
<web-site port="0" secure="true" protocol="ajp13"
display-name="Default OracleAS Containers for J2EE Web Site" >
...
</web-site>
(Also remember to change the display-name setting as appropriate.)
Add an <ssl-config> element under <web-site> to define the keystore location and password, using the keystore and keystore-password attributes.
Save the changes to secure-web-site.xml.
Here is an example; individual <web-app> entries have been excluded from the example for better readability:
<web-site display-name="OC4J Web Site" protocol="ajp13" port="0" secure="true" > <default-web-app application="default" name="defaultWebApp" root="/j2ee" /> ... <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="welcome" /> </web-site>
The protocol value is always "ajp13" for communication through Oracle HTTP Server, whether or not you use secure communication. A protocol value of ajp13 with secure="false" indicates AJP protocol; ajp13 with secure="true" indicates AJPS protocol.
Ensure that server.xml points to secure-web-site.xml.
Stop and restart OC4J to initialize secure-web-site.xml.
Important:
The OC4J 10.1.3 implementation can support only a single AJP/AJPS Web site. For example, you cannot have adefault-web-site.xml file that configures an AJP Web site at the same time that you have a secure-web-site.xml file that configures an AJPS Web site.Notes:
It is possible to enter a real port here, rather than port 0, if you configure OPMN to not override the setting in this Web site XML file.
In an Oracle Application Server environment, where Oracle HTTP Server is the Web listener, the OC4J needs-client-auth attribute in the <ssl-config> element is not relevant to SSL authentication from the browser—that would be by arrangement between the client and Oracle HTTP Server. This attribute is relevant, however, if you want OC4J to require SSL authentication from Oracle HTTP Server. See "Requesting Client Authentication" for related information.
This section covers the following aspects of using AJP over SSL:
Configuring AJPS between OC4J and Oracle HTTP Server involves the following steps:
Use Oracle Wallet Manager to create an auto-login wallet, otherwise known as an SSO wallet, to use with Oracle HTTP Server.
Use the keytool utility to export a certificate from your keystore. (It is assumed you already have a keystore in OC4J from the step of configuring OC4J with SSL, described earlier.)
% keytool -export -file cert_file_name -keystore keystore_file_name \ -storepass password
Where cert_file_name is the desired file name for the certificate that is produced, and keystore_file_name is the name of the keystore you already created. You can optionally omit storepass from the command line and be prompted for a password instead. You will receive a message confirming the certificate file name if the command is successful.
Use Oracle Wallet Manager to import the generated certificate into your wallet. Under "Operations", use "Import Trusted Certificate".
In Oracle HTTP Server, verify proper SSL settings in the mod_oc4j.conf file for secure communication. SSL must be enabled, and you must specify a path to the wallet you created in step 1. (It is not necessary to specify a wallet password here.)
Oc4jEnableSSL on
Oc4jSSLWalletFile wallet_path
The wallet_path value is a directory path to the wallet file, without a file name. (The wallet file name is already known.)
See Also:
Oracle HTTP Server Administrator's Guide for information about mod_oc4j.conf
Regarding steps 1 and 3, Oracle Application Server Administrator's Guide for details about managing wallets and certificates
In an Oracle Application Server environment, configuration steps are also required for OPMN. Update the file ORACLE_HOME/opmn/conf/opmn.xml as follows:
Under component ID "OC4J", configure the security parameters (wallet information):
<ias-component id="OC4J">
...
<category id="security-parameters">
<data id="wallet-file" value="file:walletfile"/>
<data id="wallet-password" value="pwd"/>
</category>
...
</ias-component>
Also under component ID "OC4J", specify AJPS protocol for the Web site:
<ias-component id="OC4J">
...
<port id="secure-web-site" range="12501-12600" protocol="ajps"/>
...
</ias-component>
Under component ID "HTTP_Server", confirm SSL is enabled with the default "ssl-enabled" setting. (A setting of "ssl-disabled" would disable it.)
<ias-component id="HTTP_Server"> ... <data id="start-mode" value="ssl-enabled"/> ... </ias-component>
See Also:
Oracle Process Manager and Notification Server Administrator's Guide for details about OPMN and opmn.xml
This section presents samples relating to the configuration discussed in the preceding sections.
Sample <web-site> Element
This shows a sample <web-site> element from the secure-web-site.xml file:
<web-site port="0" protocol="ajp13" secure="true">
<default-web-app application="default" name="defaultWebApp" root="/j2ee" />
<web-app application="default" name="dms" root="/dmsoc4j" />
...
<ssl-config
keystore="C:\demotest\j2eetest\tsrc\shiphome\sslfiles\KEYSTORE\keystore"
keystore-password="welcome1"/>
</web-site>
Sample mod_oc4j.conf File
This shows a sample mod_oc4j.conf file:
<IfModule mod_oc4j.c>
Oc4jEnableSSL on
Oc4jSSLWalletFile C:\demotest\j2eetest\tsrc\shiphome\sslfiles\ssl.wlt\default
Oc4jSSLWalletPassword welcome1
<Location /oc4j-service>
SetHandler oc4j-service-handler
Order deny,allow
Deny from all
Allow from localhost ani-pc.us.oracle.com ani-pc
</Location>
</IfModule>
Sample opmn.xml File
This shows sample opmn.xml configuration for component IDs "OC4J" and "HTTP_Server".
<ias-component id="OC4J">
<process-type id="home" module-id="OC4J" status="enabled">
<module-data>
<category id="start-parameters">
<data id="java-options" value="-Xrs -server
-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true"/>
</category>
<category id="security-parameters">
<data id="wallet-file" value=
"file:C:/demotest/j2eetest/tsrc/shiphome/sslfiles/ssl.wlt/default"/>
<data id="wallet-password" value="welcome"/>
</category>
<category id="stop-parameters">
<data id="java-options" value=
"-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true"/>
</category>
</module-data>
<start timeout="600" retry="2"/>
<stop timeout="120"/>
<restart timeout="720" retry="2"/>
<port id="secure-web-site" range="12501-12600" protocol="ajps"/>
<port id="rmi" range="3201-3300"/>
<port id="jms" range="3701-3800"/>
<process-set id="default_island" numprocs="1"/>
</process-type>
</ias-component>
<ias-component id="HTTP_Server">
<process-type id="HTTP_Server" module-id="OHS">
<module-data>
<category id="start-parameters">
<data id="start-mode" value="ssl-enabled"/>
</category>
</module-data>
<process-set id="HTTP_Server" numprocs="1"/>
</process-type>
</ias-component>
This section discusses SSL authentication of a client to a server, focusing in particular on the OC4J client authentication mode that uses the OC4J needs-client-auth attribute.
The discussion considers the following scenarios:
An end user as a direct client to OC4J (either standalone or OPMN-managed)
Oracle HTTP Server, for purposes of this discussion, as a client to OC4J in an Oracle Application Server environment
An end user as a client to Oracle HTTP Server in an Oracle Application Server environment (for which OC4J configuration, including the needs-client-auth attribute, is irrelevant)
OC4J supports a client authentication mode in which the OC4J server explicitly requests SSL authentication from the client (or, in an Oracle Application Server environment, from Oracle HTTP Server). A client must identify itself with a digital certificate, which OC4J requests upon connection.
During secure communication with authentication between the client and OC4J, the following functionality is executed:
All communications between the two are encrypted.
OC4J is authenticated to the client. A "secret key" is securely exchanged and used for the encryption of the link.
The client is authenticated to OC4J.
Request client authentication through the needs-client-auth attribute of the <ssl-config> element in secure-web-site.xml, as shown in the following example, and then perform the steps that follow:
<web-site ... secure="true" ... > ... <ssl-config keystore="path_and_file" keystore-password="pwd" needs-client-auth="true" /> </web-site>
A certificate that OC4J trusts is called a trust point. Decide which of the certificates in the chain from the client is to be your trust point. Ensure that you either have control over the issuance of certificates using this trust point or that you trust the certificate authority as an issuer.
Import the intermediate or root certificate in the server keystore as a trust point for authentication of the client certificate.
Note:
If you do not want OC4J to accept certain trust points, make sure these trust points are not in the keystore.Execute the steps to create the client certificate, documented in "Using SSL with Standalone OC4J". The client certificate includes the intermediate or root certificate that is installed in the server. If you wish to trust another certificate authority, obtain a certificate from that authority.
Save the certificate in a file on the client.
Provide the certificate for the client initiation of the secure connection.
OC4J accepts or rejects a client entity for secure communication according to the client identity. If the root certificate of the client is recognized, then the client is accepted. The keystore specified in the <ssl-config> element in secure-web-site.xml must contain the certificates of any clients that are authorized to connect to OC4J.
In the certificate chain from the client, the trust point is the first certificate OC4J encounters that matches one in its own keystore. There are three ways to establish trust:
The client certificate is in the keystore.
One of the intermediate CA certificates in the certificate chain from the client is in the keystore.
The root CA certificate in the certificate chain from the client is in the keystore.
OC4J verifies that the entire certificate chain up to and including the trust point is valid to prevent any forged certificates.
When the OC4J HTTP listener is used—in standalone OC4J, or in OPMN-managed OC4J without Oracle HTTP Server—you can set needs-client-auth="true" in the <ssl-config> element in secure-web-site.xml to request SSL authentication from the client (end user). In fact, this setting is required in order to use client-cert authentication with the OC4J listener.
To provide a certificate, you would set the certificate in the client browser security area if the client is a browser, or programmatically present the client certificate and the certificate chain when initiating the HTTPS connection from a Java client.
Refer to the preceding section, "Overview of OC4J Client Authentication Mode", for additional information.
In an Oracle Application Server environment, Oracle HTTP Server, in a manner of speaking, acts as the client to OC4J. For client authentication in this mode, Oracle HTTP Server must have its own certificate, and authenticates itself by sending a certificate and a certificate chain that ends with a root certificate. OC4J can be configured to accept only root certificates from a specified list in establishing a chain of trust back to a client.
For this scenario, consider Oracle HTTP Server to be the client for purposes of the discussion in "Overview of OC4J Client Authentication Mode".
AJPS (secure Apache JServ Protocol) is used instead of HTTPS for secure communication between Oracle HTTP Server and OC4J.
For requesting SSL authentication from the client (end user) to Oracle HTTP Server in an Oracle Application Server environment, OC4J is not involved and its configuration (including the needs-client-auth attribute) is not relevant. This calls for an arrangement between the client and Oracle HTTP Server. Refer to the Oracle HTTP Server Administrator's Guide for information about using SSL with Oracle HTTP Server, including how to customize your configuration to enable client authentication.
Set the certificate in the client browser security area if the client is a browser, or programmatically present the client certificate and the certificate chain when initiating the HTTPS connection for a Java client.
This section discusses some common SSL errors and their causes and remedies, followed by a brief discussion of general SSL debugging.
The following errors may occur when using SSL certificates:
keytool utility cannot locate the root CA certificates in your keystore, and therefore cannot build the certificate chain from your server key to the trusted root certificate authority.% keytool -keystore mykeystore -import -alias cacert -file cacert.cer (keytool -keystore mykeystore -import -alias intercert -file inter.cer)
If you use an intermediate CA keytool utility, then execute these commands:
% keytool -keystore mykeystore -genkey -keyalg RSA -alias serverkey % keytool -keystore mykeystore -certreq -file my.host.com.csr
Get the certificate from the Certificate Signing Request (CSR), then execute the following command:
% keytool -keystore mykeystore -import -file my.host.com.cer -alias serverkey
You can display verbose debug information from the Java Secure Socket Extension (JSSE) implementation for SSL connections, using the javax.net.debug property. To get a list of options, start OC4J as follows:
-Djavax.net.debug=help (for a list of options)
-Djavax.net.debug=all (for debug messages with full verbosity)
This includes display of the browser request header, server HTTP header, server HTTP body, content length (before and after encryption), and SSL version.
ORMI over SSL (ORMIS) is disabled by default in OC4J, because it is recommended that client and server keystores or Oracle wallets be created before ORMIS is used.
This section describes the configuration to enable ORMIS with OC4J in a standalone environment, or in a clustered environment in Oracle Application Server. Once these steps are complete, the "ormis:" protocol can be used wherever the "ormi:" protocol was used previously.
In all, the following topics are discussed:
See Also:
Oracle Containers for J2EE Services Guide for general information about using ORMI in OC4J
ORMIS configuration and related RMI configuration require updates to the server.xml file and rmi.xml file on each OC4J instance. This section covers the following topics:
To enable ORMIS in an OC4J instance, the first step is to ensure that server.xml, the OC4J server configuration file, has an <rmi-config> element that specifies the path to rmi.xml, the OC4J RMI configuration file.
Specify the path to rmi.xml as follows:
<rmi-config path="rmi_path" />
Because both the server.xml file and the rmi.xml file are typically in the ORACLE_HOME/j2ee/home/config directory, the typical value for rmi_path is "./rmi.xml".
See Also:
Oracle Containers for J2EE Configuration and Administration Guide for details about server.xml
To use ORMIS, take the following steps to define the SSL configuration in rmi.xml on each OC4J instance:
Use the ssl-port attribute in the <rmi-server> element to specify the SSL listener port. For example:
<rmi-server ... port="23791" ssl-port="23943"> ... </rmi-server>
(This also sets the ORMI listener port to 23791.)
Note:
The default RMI port is 23791; the default ORMIS port is 23943.Add an <ssl-config> subelement under the <rmi-server> element. This is for keystore configuration, as desired, and results in startup of an ORMIS listener (in addition to the non-secure ORMI listener) when OC4J is restarted. There are two techniques, described below. One is to specify a keystore and password; the other is to use an anonymous cipher suite.
See Also:
Oracle Containers for J2EE Services Guide for additional information about rmi.xml
The following example sets the SSL port to 23943 and configures OC4J to use Oracle wallet-based certificates (as well as specifying an RMI log file):
<rmi-server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=
"http://xmlns.oracle.com/oracleas/schema/rmi-server-10_0.xsd"
port="23791" ssl-port="23943">
<ssl-config keystore="/wallets/wallet-server-a/ewallet.p12"
keystore-password="serverkey-a" />
...
<log>
<file path="../log/rmi.log" />
</log>
</rmi-server>
The value of the keystore attribute specifies the keystore location (absolute path, or path relative to ORACLE_HOME/j2ee/home/config, where the Web site XML file is located) and file name.
To use a Java keystore instead of an Oracle wallet, configure the <ssl-config> element as in the following example:
<ssl-config keystore="/keystores/keystore_a.jks" keystore-password="serverkey-a"/>
When using keystores and passwords, the server keystore must contain the signed certificate of any client that is authorized to connect to OC4J through ORMIS, or contain the root CA-issued certificate of the client.
Alternatively, you can enable ORMIS using anonymous cipher suites. To accomplish this, omit the keystore and keystore-password attributes from the <ssl-config> element:
<ssl-config />
In this mode, any ORMIS client can connect to the server without certification checks being performed.
Important:
Use this mode judiciously, given that it allows SSL communication without regard for a client's transport-level authenticity.In standalone OC4J, ORMI can be disabled while ORMIS is enabled. To do this, set the ORMI port to -1:
<rmi-server ... port="-1" ssl-port="23943"> <ssl-config keystore="keystore" keystore-password="password" /> ... </rmi-server>
With this configuration, the non-secure ORMI listener will be disabled when OC4J is restarted.
Note:
This is not supported for an OPMN-managed OC4J instance.To enable ORMIS in a clustered Oracle Application Server environment managed by OPMN, do the following:
Generally complete the steps documented for standalone OC4J above, in "Configure server.xml for the RMI Configuration File Location" and "Configure rmi.xml for ORMIS". The exception is to not set ssl-port in the <rmi-server> element in rmi.xml. This is not required in an OPMN-managed environment; in fact, the OPMN-managed RMIS port will override the ssl-port attribute in rmi.xml.
For each Oracle Application Server instance that belongs to the cluster, update the opmn.xml file to add a <port> element with the rmis port range shown below:
<ias-component id="OC4J">
<process-type id="home" module-id="OC4J" status="enabled">
<module-data>
<category id="start-parameters">
<data id="java-options" value="-server
-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true
-Dhttp.webdir.enable=false"/>
</category>
<category id="stop-parameters">
<data id="java-options" value=
"-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true -Dhttp.webdir.enable=false"/>
</category>
</module-data>
<start timeout="600" retry="2"/>
<stop timeout="120"/>
<restart timeout="720" retry="2"/>
<port id="default-web-site" range="12501-12600" protocol="ajp"/>
<port id="rmi" range="12401-12500"/>
<port id="rmis" range="12701-12800"/>
<port id="jms" range="12601-12700"/>
<process-set id="default_group" numprocs="1"/>
</process-type>
...
</ias-component>
See Also:
Oracle Application Server Administrator's Guide for general information about OPMN and the opmn.xml file
ORMIS (like ORMI) supports the ability to restrict incoming IP access by defining access control list (ACL) masks, through settings in the <access-mask> element and its <host-access> and <ip-access> subelements in rmi.xml.
Access controls can be either exclusive or inclusive:
In the exclusive mode, access is denied to all IP addresses or hosts except those specifically included. Use mode="deny" in <access-mask>, then specify which particular hosts or IP addresses to allow by using mode="allow" in <host-access> or <ip-access> subelements (or both).
In the inclusive mode, access is available to all IP addresses or hosts except those specifically excluded. Use mode="allow" in <access-mask>, then specify which particular hosts or IP addresses to deny by using mode="deny" in <host-access> or <ip-access> subelements (or both).
The following example configures an exclusive mode, allowing access to only localhost and 192.168.1.0. (255.255.255.0 is the applicable subnet mask.)
<rmi-server xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation=
"http://xmlns.oracle.com/oracleas/schema/rmi-server-10_0.xsd"
port="23791" ssl-port="23943">
<ssl-config keystore="../wallets/wallet-server-a/ewallet.p12"
keystore-password="serverkey-a" />
<access-mask default="deny">
<host-access domain="localhost" mode="allow"/>
<ip-access ip="192.168.1.0" netmask="255.255.255.0" mode="allow"/>
</access-mask>
...
</rmi-server>
See Also:
Oracle Containers for J2EE Servlet Developer's Guide for additional information about the <access-mask> element, which is supported with the same functionality in orion-web.xml
This section discusses the following client-side configurations for ORMIS:
For an application in a standalone OC4J environment, specify the ormis protocol in the setting of the java.naming.provider.url environment property, which defines the URI of the system and application:
java.naming.provider.url=ormis://hostname/appname
For an application in an Oracle Application Server (OPMN-managed) environment, specify the opmn:ormis protocol:
java.naming.provider.url=opmn:ormis://hostname/appname
Note:
It is not necessary to include a port number in the URL. The protocol determines what port is used.To call an EJB over ORMIS, you must also specify the following on the client side, as applicable:
Path to client keystore (absolute path is recommended)
This is the location of the client-side keystore, where server certificates have been imported.
Keystore password
There are three choices for where to specify these settings, in order of precedence:
As JSSE properties:
-Djavax.net.ssl.keyStore=keystore_path -Djavax.net.ssl.keyStorePassword=keystore_password
As properties in jndi.properties (ignored if JSSE property settings are used):
oc4j.[rmi.]keyStoreLoc=keystore_path oc4j.[rmi.]keyStorePass=keystore_password
As properties in ejb_sec.properties (ignored if JSSE or jndi.properties property settings are used):
oc4j.[rmi.]keyStoreLoc=keystore_path oc4j.[rmi.]keyStorePass=keystore_password
Notes:
Either oc4j.keyStoreLoc or oc4j.rmi.keyStoreLoc is acceptable. Similarly for keyStorePass.
To use ejb_sec.properties, place it in the current directory, from which the client Java VM was launched.
The RMI chapter of the Oracle Containers for J2EE Services Guide discusses how to configure ORMI tunneling through HTTP.
It is also possible to configure ORMI tunneling through HTTPS for SSL functionality. The basic steps are as follows:
Complete your SSL configuration as discussed in "Using SSL with Standalone OC4J" or "Using SSL in OPMN-Managed OC4J with Oracle HTTP Server" (as applicable).
For standalone OC4J, this consists of creating your keystore and configuring the secure-web-site.xml file.
For an Oracle Application Server environment, this consists of creating your keystore, configuring the secure-web-site.xml file (with some differences compared to standalone OC4J, as noted), configuring AJP over SSL (as desired), and configuring OPMN to enable HTTP and use SSL. Note that SSL is enabled by default in Oracle HTTP Server.
Configure your client appropriately (parallel to the steps in "Configuring Clients to Use ORMIS"):
For either standalone OC4J or an Oracle Application Server environment, specify the ormi:https protocol in setting the java.naming.provider.url environment property, which defines the URI of the system and application:
java.naming.provider.url=ormi:https://hostname:https_port/appname
For standalone OC4J, the https_port is as specified in secure-web-site.xml, as discussed in "Using SSL with Standalone OC4J". In an Oracle Application Server environment, the https_port is the Oracle HTTP Server SSL port.
Configure the keystore and password, as discussed in "Specify the Keystore and Password".
The following client code snippet uses a URL with the ormi:https protocol:
private static Context getInitialContext() throws NamingException {
Hashtable env = new Hashtable();
env.put( Context.INITIAL_CONTEXT_FACTORY,
"oracle.j2ee.naming.ApplicationClientInitialContextFactory" );
env.put( Context.SECURITY_PRINCIPAL, "oc4jadmin" );
env.put( Context.SECURITY_CREDENTIALS, "welcome1" );
env.put(Context.PROVIDER_URL, "ormi:https://localhost:443/apache-ejb");
env.put("oc4j.keyStoreLoc",
"C:/product/iasSOA0622/Apache/Apache/conf/ssl.wlt/default/ewallet.p12");
env.put("oc4j.keyStorePass", "welcome");
return new InitialContext( env );
}
An OC4J managed data source can be configured to use TCP over SSL (TCPS) to secure communication with an Oracle database. Using TCPS has the following requirements:
A database that has been configured with a trustore (in this case a PKCS12 wallet). Contact a DBA if you require assistance setting up security on the database server.
A 10.2.0.3 (or higher) JDBC driver (the application server uses the 10.1.0.5 JDBC driver as the default driver). The driver can be configured as a shared library for the container or for a specific application. See the"Utilizing the OC4J Class-Loading Framework" in the Oracle Containers for J2EE Developer's Guide.
An Oracle PKI security provider entry in the application server's JRE security file (JAVA_HOME/jre/lib/security/java.security). For example:
security.provider.3=oracle.security.pki.OraclePKIProvider
Note:
For more information on JDBC / SSL using TCPS, refer to the following document:http://www.oracle.com/technology/tech/java/sqlj_jdbc/pdf/wp-oracle-jdbc_thin_ssl.pdfThe managed data source definition must include the following:
The oracle.jdbc.driver.OracleDriver factory class.
A connection URL that defines the TCPS protocol as shown below:
jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps) \
(HOST=host)(PORT=2484)) \
(CONNECT_DATA=(SERVICE_NAME=orcl)))
A database username/password along with the trustore credentials
The path to the client wallet on the server. The location can be anywhere on the file system. For example:
/home/wallets/client/ewallet.p12
The following example demonstrates a managed data source definition that uses TCPS to connect to an Oracle database. The example uses SSL for encryption only and passes in a set of cipher suites.
<managed-data-source
connection-pool-name="ConnPoolTCPS"
jndi-name="jdbc/sslDS"
name="jdbc/sslDS"/>
<connection-pool name="ConnPoolTCPS">
<connection-factory
factory-class="oracle.jdbc.driver.OracleDriver"
user="user"
password="password"
URL="jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps) \
(HOST=host)(PORT=2484)) \
(CONNECT_DATA=(SERVICE_NAME=orcl)))"
commit-record-table-name="">
<property name="truststore"
value="/path/ewallet.p12"/>
<property name="truststore-password" value="password"/>
<property name="truststore-type" value="PKCS12"/>
<property name="oracle.net.ssl_cipher_suites"
value="SSL_DH_anon_WITH_3DES_EDE_CBC_SHA, SSL_DH_anon_WITH_RC4_128_MD5, \
SSL_DH_anon_WITH_DES_CBC_SHA"/>
</connection-factory>
</connection-pool>
|
 Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|