10g (9.0.4)
Part Number Part No. B10325-02
 Home |
 Solution Area |
 Contents |
 Index |
| OracleŽ Application Server Containers for J2EE Security Guide 10g (9.0.4) Part Number Part No. B10325-02 |
|
This chapter describes the Oracle Application Server Containers for J2EE (Oracle Application Server Containers for J2EE) implementation of HTTPS that provides SSL functionality to client HTTP connections. The following topics are included:
This chapter discusses how to use the Secure Sockets Layer protocol to communicate securely between networked applications. It begins by discussing fundamental SSL concepts, then continues with information about using Oracle HTTPS and JSSE.
|
Notes:
|
In SSL communication between two entities, such as companies or individuals, the server has a public key and an associated private key. Each key is a number, with the private key of an entity being kept secret by that entity, and the public key of an entity being publicized to any other parties with which secure communication might be necessary. The security of the data exchanged is guaranteed by keeping the private key secret, and by the complex encryption algorithm. This system is known as asymmetric encryption, because the key used to encrypt data is not the same as the key used to decrypt data.
Asymmetric encryption has a performance cost due to its complexity. A much faster system is symmetric encryption, where the same key is used to encrypt and decrypt data. But the weakness of symmetric encryption is that the same key has to be known by both parties, and if anyone intercepts the exchange of the key, then the communication becomes insecure.
SSL uses both asymmetric and symmetric encryption to communicate. An asymmetric key (PKI public key) is used to encode a symmetric encryption key (the bulk encryption key); the bulk encryption key is then used to encrypt subsequent communication. After both sides agree on the bulk encryption key, faster communication is possible without losing security and reliability.
When an SSL session is negotiated, the following steps take place:
This set of operations is called key exchange. After key exchange has taken place, the client and the server use the bulk encryption key to encrypt all exchanged data.
In SSL the public key of the server is sent to the client in a data structure known as an X.509 certificate. This certificate, created by a certificate authority (CA), contains a public key, information concerning the owner of the certificate, and optionally some digital rights of the owner. Certificates are digitally signed by the CA which created them using that CA's digital certificate public key.
In SSL, the CA's signature is checked by the receiving process to ensure that it is on the approved list of CA signatures. This check is sometimes performed by analysis of certificate chains. This occurs if the receiving process does not have the signing CA's public key on the approved list. In that case the receiving process checks to see if the signer of the CA's certificate is on the approved list or the signer of the signer, and so on. This chain of certificate, signer of certificate, signer of signer of certificate, and so on is a certificate chain. The highest certificate in the chain (the original signer) is called the root certificate of the certificate chain.
The root certificate is often on the approved list of the receiving process. Certificates in the approve list are called trust points or trusted certificates. A root certificate can be signed by a CA or can be self-signed, meaning that the digital signature that verifies the root certificate is encrypted through the private key that corresponds with the public key that the certificate contains, rather than through the private key of a higher CA.
Functionally, a certificate acts as a container for public keys and associated signatures. A single certificate file can contain one or multiple chained certificates, up to an entire chain. Private keys are normally kept separately to prevent them from being inadvertently revealed, although they can be included in a separate section of the certificate file for convenient portability between applications.
A keystore is used to store certificates, including the certificates of all trusted parties, for use by a program. 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 has what is called a wallet for the same purpose. Sun's SSL implementation introduces the notion of a truststore, which is a keystore file that includes the trusted certificate authorities that a client will implicitly accept during an SSL handshake.
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. Go to the following site for information about keytool:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
The steps for using keys and certificates for SSL communication in OC4J are as follows. 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 OracleAS instance.
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.
You can generate your own signature:
keytool to "self-sign" the certificate. This is appropriate if your clients will trust you as, in effect, your own certificate authority.
Alternatively, you can obtain a signature from a recognized certificate authority:
keytool to generate a certificate request, which is a request to have the certificate signed by a certificate authority.
keytool. In the keystore, the signature will be matched with the associated certificate.
|
Note: Oracle Application Server includes OracleAS Certificate Authority (OCA). This allows customers to create and issue certificates for themselves and their users, although these certificates would likely be unrecognized outside a customer's organization without prior arrangements. See the Oracle Application Server 10g Security 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 OracleAS, the OracleAS documentation 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, for example:
http://www.verisign.com/ http://www.thawte.com/
For SSL communication between OC4J and Oracle HTTP Server, you would also execute the preceding steps for Oracle HTTP Server, but using a wallet and Oracle Wallet Manager instead of a keystore and the keytool utility. See the Oracle Application Server 10g Security Guide for information about wallets and the Oracle Wallet Manager.
In addition, you would execute the following steps as appropriate.
If the OC4J certificate is signed by an entity that Oracle HTTP Server does not yet trust:
keytool to export the OC4J certificate. This places the certificate into a file that is accessible to Oracle HTTP Server.
If the Oracle HTTP Server certificate is signed by an entity that OC4J does not yet trust, and if OC4J is in a mode of operation that requires client authentication (as discussed in "Requesting Client Authentication"):
keytool to import the Oracle HTTP Server certificate.
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:
This example corresponds to Step 2 above, in the mode where you generate your own signature by using keytool to self-sign the certificate.
First, create a keystore with an RSA private/public keypair, using the keytool command. This example (in which % is the system prompt) uses the RSA keypair algorithm to generate a keystore to reside in a file named mykeystore, which has a password of 123456 and is valid for 21 days:
% keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 -validity 21
Note the following:
keystore option specifies the name of the file in which the keys are stored.
storepass option sets the password for protecting the keystore.
validity option sets the number of days for which the certificate is valid.
The keytool prompts you for more 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=Reading, ST=Berkshire, C=GB> correct? [no]: yes Enter key password for <mykey> (RETURN if same as keystore password):
|
Note: To determine your two-letter country code, use the ISO country code list at the following URL:
|
The mykeystore file is created in the current directory. The default alias of the key is mykey.
OC4J supports a client authentication mode in which the server explicitly requests authentication from the client before the server will communicate with the client. In an OracleAS environment, Oracle HTTP Server acts as the client to OC4J.
For client authentication, Oracle HTTP Server must have its own certificate and authenticate 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.
A certificate that OC4J trusts is called a trust point. In the certificate chain from Oracle HTTP Server, the trust point is the first certificate that OC4J encounters that matches one in its own keystore. There are three ways to establish trust:
OC4J verifies that the entire certificate chain up to and including the trust point is valid to prevent any forged certificates.
If you request client authentication with the needs-client-auth attribute, perform the following steps. See "OC4J Configuration Steps for SSL" for how to configure this attribute.
During secure communication between the client and OC4J, the following functionality is executed:
See Also:
java.net packages at http://www.java.sun.com
HTTPS is vital to securing client-server interactions. For many server applications, HTTPS is handled by the Web server. However, any application that acts as a client, such as servlets that initiate connections to other Web servers, needs its own HTTPS implementation to make requests and to receive information securely from the server. Java application developers who are familiar with either the HTTP package, HTTPClient, or who are familiar with the Sun Microsystems, Inc., java.net package can easily use Oracle HTTPS to secure client interactions with a server.
Oracle HTTPS extends the HTTPConnection class of the HTTPClient package, which provides a complete HTTP client library. To support client HTTPS connections, several methods have been added to the HTTPConnection class that use the OracleSSL class, OracleSSLCredential.
The HTTPConnection class is used to create new connections that use HTTP, with or without SSL. To provide support for PKI (Public Key Infrastructure) digital certificates and wallets, the methods described in "Oracle HTTPS Example" have been added to this class.
|
See Also:
The |
Security credentials are used to authenticate the server and the client to each other. Oracle HTTPS uses the Oracle Java SSL package, OracleSSLCredential, to load user certificates and trustpoints from base64 or DER-encoded certificates. (DER, part of the X.690 ASN.1 standard, stands for Distinguished Encoding Rules.)
The API for Oracle Java SSL requires that security credentials be passed to the HTTP connection before the connection is established. The OracleSSLCredential class is used to store these security credentials. Typically, a wallet generated by Oracle Wallet Manager is used to populate the OracleSSLCredential object. Alternatively, individual certificates can be added by using an OracleSSLCredential class API. After the credentials are complete, they are passed to the connection with the setCredentials method.
Oracle HTTPS supports HTTP 1.0 and HTTP 1.1 connections between a client and a server. To provide SSL functionality, new methods have been added to the HTTPConnection class of this package. These methods are used in conjunction with Oracle Java SSL to support cipher suite selection, security credential management with Oracle Wallet Manager, security-aware applications, and other features that are described in the following sections. Oracle HTTPS uses the Oracle Java SSL class, OracleSSLCredential, and it extends the HTTPConnection class of the HTTPClient package. HTTPClient supports two SSL implementations, OracleSSL and JSSE.
In addition to the functionality included in the HTTPClient package, Oracle HTTPS supports the following:
java.net.URL framework
In addition, Oracle HTTPS uses the HTTPClient package to support
The following sections describe Oracle HTTPS features in detail:
Before data can flow through an SSL connection, both sides of the connection must negotiate common algorithms to be used for data transmission. A set of such algorithms combined to provide a mix of security features is called a cipher suite. Selecting a particular cipher suite lets the participants in an SSL connection establish the appropriate level for their communications.
HTTPClient supports two different SSL implementations, each of which supports different cipher suites. These are discussed below.
In general, you should prefer:
OracleSSL supports the cipher suites listed in Table 11-1. Note that with NULL encryption, SSL is only used for authentication and data integrity purposes.
JSSE supports the cipher suites listed in Table 11-1. Note that with NULL encryption, SSL is only used for authentication and data integrity purposes.
Users can access information about established SSL connections using the getSSLSession method of Oracle HTTPS. After a connection is established, users can retrieve the cipher suite used for the connection, the peer certificate chain, and other information about the current connection.
Oracle HTTPS uses Oracle Java SSL to provide security-aware applications support. When security-aware applications do not set trust points, Oracle Java SSL allows them to perform their own validation letting the handshake complete successfully only if a complete certificate chain is sent by the peer. When applications authenticate to the trustpoint level, they are responsible for authenticating individual certificates below the trustpoint.
After the handshake is complete, the application must obtain the SSL session information and perform any additional validation for the connection.
Security-unaware applications that need the trust point check must ensure that trust points are set in the HTTPS infrastructure.
The HTTPClient package provides basic support for the java.net.URL framework with the HTTPClient.HttpUrlConnection class. However, many of the Oracle HTTPS features are supported through system properties only.
Features that are only supported through system properties are
See Also:
java.net.URL framework at
http://java.sun.com
For many users of HTTPS it is desirable to specify some default properties in a non-programmatic way. The best way to accomplish this is through Java system properties which are accessible through the java.lang.System class. These properties are the only way for users of the java.net.URL framework to set security credential information. Oracle HTTPS recognizes the following properties:
The following sections describe how to set these properties.
This property can be set to point to the text wallet file exported from Oracle Wallet Manager that contains the credentials that are to be used for a specific connection. For example:
javax.net.ssl.KeyStore=/etc/ORACLE/WALLETS/Default/default.txt
where default.txt is the name of the text wallet file that contains the credentials.
If no other credentials have been set for the HTTPS connection, then the file indicated by this property is opened when a handshake first occurs. If any errors occur while reading this file, then the connection fails and an IOException is thrown.
If you do not set this property, the application is responsible for verifying that the certificate chain contains a certificate that can be trusted. However, HTTPClient using Oracle SSL does verify that all of the certificates in the certificate chain, from the user certificate to the root CA, have been sent by the server and that all of these certificates contain valid signatures.
This property can be set to the password that is necessary to open the wallet file. For example:
javax.net.ssl.KeyStorePassword=welcome1
where welcome1 is the password that is necessary to open the wallet file.
Storing the wallet file password as a Java system property can result in a security risk in some environments. To avoid this risk, use one of the following alternatives:
HTTPConnection is started by using System.setProperty(). Unset the property after the handshake is completed.
This property can be set to a comma-delimited list of cipher suites. For example:
Oracle.ssl.defaultCipherSuites= SSL_RSA_WITH_DES_CBC_SHA,\ SSL_RSA_EXPORT_WITH_RC4_40_MD5,\ SSL_RSA_WITH_RC4_128_MD5
The cipher suites that you set this property to are used as the default cipher suites for new HTTPS connections.
|
See Also:
Table 11-1 for a complete list of the cipher suites that are supported by OracleSSL. |
The following is a simple program that uses Oracle HTTPS, HTTPClient, and OracleSSL to connect to a Web server, send a GET request, and fetch a Web page. The complete code for this program is presented here followed by sections that explain how Oracle HTTPS is used to set up secure connections.
import HTTPClient.HTTPConnection; import HTTPClient.HTTPResponse; import oracle.security.ssl.OracleSSLCredential; import java.io.IOException; public class HTTPSConnectionExample { public static void main(String[] args) { if(args.length < 4) { System.out.println( "Usage: java HTTPSConnectionTest [host] [port] " + "[wallet] [password]"); System.exit(-1); } String hostname = args[0].toLowerCase(); int port = Integer.decode(args[1]).intValue(); String walletPath = args[2]; String password = args[3]; HTTPConnection httpsConnection = null; OracleSSLCredential credential = null; try { httpsConnection = new HTTPConnection("https",hostname,port); } catch(IOException e) { System.out.println("HTTPS Protocol not supported"); System.exit(-1); } try { credential = new OracleSSLCredential(); credential.setWallet(walletPath,password); } catch(IOException e) { System.out.println("Could not open wallet"); System.exit(-1); } httpsConnection.setSSLCredential(credential); try { httpsConnection.connect(); } catch (IOException e) { System.out.println("Could not establish connection"); e.printStackTrace(); System.exit(-1); } javax.security.cert.X509Certificate[] peerCerts = null; try { peerCerts =
(httpsConnection.getSSLSession()).getPeerCertificateChain(); } catch(javax.net.ssl.SSLPeerUnverifiedException e) { System.err.println("Unable to obtain peer credentials"); System.exit(-1); } String peerCertDN =
peerCerts[peerCerts.length -1].getSubjectDN().getName(); peerCertDN = peerCertDN.toLowerCase(); if(peerCertDN.lastIndexOf("cn="+hostname) == -1) { System.out.println("Certificate for " +hostname+ " is issued to "
+ peerCertDN); System.out.println("Aborting connection"); System.exit(-1); } try { HTTPResponse rsp = httpsConnection.Get("/"); System.out.println("Server Response: "); System.out.println(rsp); } catch(Exception e) { System.out.println("Exception occured during Get"); e.printStackTrace(); System.exit(-1); } } }
This program example uses a wallet created by Oracle Wallet Manager to set up credential information. First the credentials are created and the wallet is loaded using
credential = new OracleSSLCredential(); credential.setWallet(walletPath,password);
After the credentials are created, they are passed to HTTPSConnection using
httpsConnection.setSSLCredential(credential);
The private key, user certificate, and trust points located in the wallet can now be used for the connection.
Although SSL verifies that the certificate chain presented by the server is valid and contains at least one certificate trusted by the client, that does not prevent impersonation by malicious third parties. An HTTPS standard that addresses this problem requires that HTTPS servers have certificates issued to their host name. Then it is the responsibility of the client to perform this validation after the SSL connection is established.
To perform this validation in this sample program, HTTPSConnectionExample establishes a connection to the server without transferring any data using the following:
httpsConnection.connect();
After the connection is established, the connection information, in this case the server certificate chain, is obtained with the following:
peerCerts = (httpsConnection.getSSLSession()).getPeerCertificateChain();
Finally the server certificate's common name is obtained with the following:
String peerCertDN = peerCerts[peerCerts.length -1].getSubjectDN().getName(); peerCertDN = peerCertDN.toLowerCase();
If the certificate name is not the same as the host name used to connect to the server, then the connection is aborted with the following:
if(peerCertDN.lastIndexOf("cn="+hostname) == -1) { System.out.println("Certificate for " +hostname+ " is issued to " + peerCertDN); System.out.println("Aborting connection"); System.exit(-1); }
It is important to verify the connection information before data is transferred from the client or from the server. The data transfer is performed in the same way for HTTPS as it is for HTTP. In this sample program a GET request is made to the server using the following:
HTTPResponse rsp = httpsConnection.Get("/");
OracleAS supports HTTPS client connections using the Java Secure Socket Extension (JSSE). A client can configure HTTPClient to use JSSE as the underlying SSL provider.
|
Notes:
|
HTTPClient still uses OracleSSL as the default provider, but the developer can easily change this by setting the SSLSocketFactory on the HTTPConnection class. This following code snippet demonstrates how a client could configure HTTPClient to use JSSE for SSL communication.
public void obtainHTTPSConnectionUsingJSSE() throws Exception { // set the trust store to the location of the client's trust store file // this value specifies the certificate authorities the client accepts System.setProperty("javax.net.ssl.trustStore", KEYSTORE_FILE); // creates the HTTPS URL URL testURL = new URL("https://" + HOSTNAME + ":" + HTTPS_PORTNUM); // call SSLSocketFactory.getDefault() to obtain the default JSSE implementation // of an SSLSocketFactory SSLSocketFactory socketFactory = (SSLSocketFactory)SSLSocketFactory.getDefault(); HTTPConnection connection = new HTTPConnection(testURL); // configure HTTPClient to use JSSE as the underlying // SSL provider connection.setSSLSocketFactory(socketFactory); // call connect to setup SSL handshake try { connection.connect(); } catch (IOException e) { e.printStackTrace(); } HTTPResponse response = connection.Get("/index.html"); }
The steps required to use JSSE with HTTPClient are as follows:
Notes:
javax.net.ssl.trustStore. Unlike OracleSSL, the client does not need to set the javax.net.ssl.keyStore property.
SSLSocketFactory by calling SSLSocketFactory.getDefault().
HTTPClient connection.
HTTPClient connection to use the JSSE implementation of SSL. HTTPClient can be configured to use JSSE in one of two ways:
HTTPConnection.connect() before sending any HTTPS data. This allows the connection to verify the SSL handshaking that must occur between client and server before any data can be encrypted and sent.
HTTPConnection instance normally. At this point, the client is set up to use HTTPClient with JSSE. There is no additional configuration necessary and basic usage is the same.
For secure communication between Oracle HTTP Server and OC4J, configuration steps are required at each end, as detailed in the following sections:
In Oracle HTTP Server, verify proper SSL settings in mod_oc4j.conf for secure communication. SSL must be enabled, with a wallet file and password specified, as follows:
Oc4jEnableSSL on Oc4jSSLWalletFile wallet_path Oc4jSSLWalletPassword pwd
The wallet_path value is a directory path to the wallet file, without a file name. (The wallet file name is already known.) The pwd value is the wallet password.
For more information about the mod_oc4j.conf file, see Oracle HTTP Server Administrator's Guide.
In the default-web-site.xml file (or other Web site XML file, as appropriate), you must specify appropriate SSL settings under the <web-site> element.
secure flag to specify secure communication, as follows:
<web-site ... secure="true" ... > ... </web-site>
Setting secure="true" specifies that the AJP protocol should use an SSL socket.
<ssl-config> sub-element and its keystore and keystore-password attributes to specify the path and password for the keystore, as follows:
<web-site ... secure="true" ... > ... <ssl-config keystore="path_and_file" keystore-password="pwd" /> </web-site>
The <ssl-config> element is required whenever the secure flag is set to "true".
The path_and_file value can indicate either an absolute or relative directory path and includes the file name. A relative path is relative to the location of the Web site XML file.
needs-client-auth flag. This is an attribute of the <ssl-config> element.
<web-site ... secure="true" ... > ... <ssl-config keystore="path_and_file" keystore-password="pwd" needs-client-auth="true" /> </web-site>
This sets up a mode where OC4J will accept or reject a client entity, such as Oracle HTTP Server, for secure communication depending on its identity. 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 secure AJP and SSL.
Here is an example that sets up secure communication with client authentication:
<web-site display-name="OC4J Web Site" protocol="ajp13" 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" needs-client-auth="true" /> </web-site>
Only the portions in bold are specific to security. 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, while ajp13 with secure="true" indicates secure AJP protocol.
For more information about elements and attributes of the <web-site> and <ssl-config> elements, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
For secure communication between a client and OC4J, configuration is required on OC4J standalone. You are required to provide a certificate on the client-side only if you configure client-authentication.
In the default-web-site.xml file of OC4J (or other Web site XML file, as appropriate), you must specify appropriate SSL settings under the <web-site> element.
secure flag to specify secure communication, as follows:
<web-site ... protocol="http" secure="true" ... > ... </web-site>
Setting secure="true" specifies that the HTTP protocol is to use an SSL socket.
<ssl-config> sub-element and its keystore and keystore-password attributes to specify the directory path and password for the keystore, as follows:
<web-site ... secure="true" ... > ... <ssl-config keystore="path_and_file" keystore-password="pwd" /> </web-site>
The <ssl-config> element is required whenever the secure flag is set to "true".
The path_and_file value can indicate either an absolute or relative directory path and includes the file name.
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, depending on 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.
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.
shared is 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 non-default 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 non-default ports for a shared environment with HTTP and HTTPS, set the cookie-domain attribute 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" />
The following configures a Web site for HTTPS secure communication with client authentication:
<web-site display-name="OC4J Web Site" protocol="http" 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, 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.
Then, configures the news application to accept both HTTP and HTTPS connections:
<web-app application="news" name="news-web" root="/news" shared="true" />
This Web site uses the default port numbers for HTTP and HTTPS communication. If it did not, you would also add the cookie-domain attribute.
<session-tracking cookie-domain=".oracle.com" />
For more information about elements and attributes of the <web-site>, <web-app>, and <session-tracking> elements, see the XML Appendix in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
The following example uses keytool to create a test certificate and shows all of the XML configuration necessary for HTTPS to work. To create a valid certificate for use in production environments, see the keytool documentation.
Ensure that JDK 1.3.x is installed. This is required for SSL with OC4J. Set the JAVA_HOME to the JDK 1.3 directory. Ensure that the JDK 1.3.x JAVA_HOME/bin is at the beginning of your path. This may be achieved by doing the following:
UNIX
$ PATH=/usr/opt/java130/bin:$PATH $ export $PATH $ java -version java version "1.3.0"
Windows
set PATH=d:\jdk131\bin;%PATH%
Ensure that this JDK version is set as the current version in your Windows registry. In the Windows Registry Editor under HKEY_LOCAL_MACHINE/SOFTWARE/JavaSoft/Java Development Kit, set 'CurrentVersion' to 1.3 (or later).
ORACLE_HOME/j2ee
keytool command. In our example, we generate a keystore to reside in a file named 'mykeystore', which has a password of '123456' and is valid for 21 days, using the 'RSA' key pair generation algorithm with the following syntax:
keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 -validity 21
Where:
keystore option sets the filename where the keys are stored
storepass option sets the password for protecting the keystore
validity option sets number of days the certificate is valid
The keytool prompts you for more information, as follows:
keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 -validity 21 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=Reading, ST=Berkshire, C=GB> correct? [no]: yes Enter key password for <mykey> (RETURN if same as keystore password):
|
Note:
To determine your 'two-letter country code', use the ISO country code list at the following URL: |
The mykeystore file is created in the current directory. The default alias of the key is mykey.
secure-web-site.xml file, then copy the default-web-site.xml to $ORACLE_HOME/j2ee/home/config/secure-web-site.xml.
secure-web-site.xml with the following elements:
secure="true" to the <web-site> element, as follows:
<web-site port="8888" display-name="Default OracleAS Containers for J2EE Web Site" secure="true">
<web-site> element to define the keystore and the password.
<ssl-config keystore="<Your-Keystore>" keystore-password="<Your-Password>" />
Where <Your-Keystore> is the full path to the keystore and <Your-Password> is the keystore password. In our example, this is as follows:
<!-- Enable SSL --> <ssl-config keystore="../../keystore" keystore-password="123456"/>
secure-web-site.xml.
secure-web-site.xml file, then edit server.xml to point to the secure-web-site.xml file.
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 in the server.xml configuration file.
<web-site path="./secure-web-site.xml" /> - comment out this to remove SSL <default-site path="./default-web-site.xml" /> - comment out this to remove non-SSL
OC4J supports a "client-authentication" mode in which the server explicitly requests authentication from the client before the server will communicate with the client. In this case, the client must have its own certificate. The client 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 the client.
A certificate that OC4J trusts is called a trust point. This is the first certificate that OC4J encounters in the chain from the client that matches one in its own keystore. There are three ways to configure trust:
OC4J verifies that the entire certificate chain up to and including the trust point is valid to prevent any forged certificates.
If you request client authentication with the needs-client-auth attribute, perform the following:
The following errors may occur when using SSL certificates:
Keytool Error: java.security.cert.CertificateException: Unsupported encoding
Cause: You cannot allow trailing whitespace in the keytool.
Action: Delete all trailing whitespace. If the error still occurs, add a new line in your certificate reply file.
Keytool Error: KeyPairGenerator not available
Cause: You are probably using a keytool from an older JDK.
Action: Use the keytool from the latest JDK on your system. To ensure that you are using the latest JDK, specify the full path for this JDK.
Keytool Error: Failed to establish chain from reply
Cause: The keytool cannot locate the root CA certificates in your keystore; thus, the keytool cannot build the certificate chain from your server key to the trusted root certificate authority.
Action: Execute the following:
keytool -keystore keystore -import -alias cacert -file cacert.cer (keytool -keystore keystore -import -alias intercert -file inter.cer)
If you use an intermediate CA keytool, then execute the following:
keystore keystore -genkey -keyalg RSA -alias serverkey keytool -keystore keystore -certreq -file my.host.com.csr
Get the certificate from the Certificate Signing Request, then execute the following:
keytool -keystore keystore -import -file my.host.com.cer -alias serverkey
No available certificate corresponds to the SSL cipher suites which are enabled
Cause: Something is wrong with your certificate.
IllegalArgumentException: Mixing secure and non-secure sites on the same ip + port
Cause: You cannot configure SSL and non-SSL web-sites to listen on the same port and IP address.
Action: Check to see that different ports are assigned within secure-web-site.xml and default-web-site.xml files.
Keytool does not work on HP-UX
Cause: On HP-UX, it has been reported that the 'keytool' does not work with the RSA option.
Action: Generate the key on another platform and FTP it to the HP-UX server.
|
 Copyright © 1996, 2003 Oracle Corporation. All Rights Reserved. |
|