Skip Headers
Oracle® Database Lite Administration and Deployment Guide
10g (10.0.0)
Part No. B12262-01
  Go To Table Of Contents
Go To Index


17 Configuring SSL For Mobile Server

Oracle Database Lite 10g supports Secure Socket Layer (SSL) communication between the Mobile Server and Mobile Clients. Oracle Database Lite uses the SSL that is embedded within OC4J, which is shipped as part of Mobile Server.


If you choose to install standalone Mobile Server, the standalone OC4J is installed; however, the other option installs OracleAS as the middle-tier. OracleAS also includes OC4J, but the configuration for SSL is more involved. This chapter covers the basic SSL configuration for the standalone Mobile Server. See the Oracle Application Server Containers for J2EE Security Guide for more information on all aspects of configuring SSL.

This chapter assumes that you understand the concepts behind SSL and provides only the steps for using keys and certificates for SSL communication for the standalone Mobile Server.


These are server-level steps which are typically executed prior to deployment of an application that requires SSL communication.

17.1 Creating an SSL Certificate

Oracle Database Lite ships a sample keystore file with a self-signed sample certificate. Use this keystore only for development or testing purposes. Obtain a signature from a recognized certificate authority for all production systems. The test keystore is located in the following directory: �


To create a keystore file, perform the following steps:�

  1. Use the Sun Microsystems Java keytool utility to generate a private key, public key, and an unsigned certificate. Place this information into either a new or existing keystore.


    A keystore is a instance that you create and manipulate using the keytool utility, which is provided with the Sun Microsystems JDK. See for more information on the keytool utility.

  2. Obtain a signature for the certificate, using either of the following � approaches:

    • Generate your own signature by using keytool to self-sign the� certificate. This is appropriate only if your clients trust you as your own certificate authority.

    • Obtain a signature from a recognized certificate authority through� the following steps:�

    1. Using the certificate from Step 1, use keytool to generate a certificate� request, which requests a certificate authority to sign the certificate.�

    2. Submit the certificate request to a certificate authority.��

    3. Receive the signature from the certificate authority and import it into� the keystore using keytool. In the keystore, the signature is matched with the associated certificate.

Each certificate authority has its own process for requesting and receiving signatures. Since this is outside the scope and control of Oracle Database Lite, it is not covered in Oracle Database Lite documentation.� However, the SSL section in the Oracle Application Server Containers for J2EE Security Guide has an example of how to generate your own keystore. For other information, go to the Web site of any certificate authority. Each browser� lists trusted certificate authorities. Here are the Web addresses for VeriSign, Inc. and Thawte, for example:

17.2 Configuring Mobile Server for SSL

Once you have a certificate, you must configure SSL in the application server that is installed with the Mobile Server. When you installed, you chose to install the Mobile Server either in standalone mode or to use the application server. Both of these environments are discussed below:

17.2.1 Configuring SSL for Mobile Server With Oracle9iAS or OracleAS

For production systems, you have either Oracle9iAS or OracleAS installed with the Mobile Server. You must configure SSL on both the application server and the Mobile Server, as follows:

  1. Configure SSL in the application server using the administration GUI. The directions on how to configure SSL when using Oracle9iAS or OracleAS as your middle-tier is in the SSL or HTTPS chapter in the Oracle Application Server Containers for J2EE Security Guide.

  2. Configure SSL in the Mobile Server by adding SSL=YES in the [WEBTOGO] section of the ORACLE_HOME\Mobile\Server\bin\webtogo.ora file.

  3. After all configuration is complete, restart the application server to initialize the changes.

17.2.2 Configuring SSL for Standalone Mobile Server

With the standalone Mobile Server, the standalone version of the OC4J application server is installed with the Mobile Server. To configure SSL for this environment, you modify the Mobile Server webtogo.ora file and certain XML elements within the OC4J XML configuration files, as follows:

  1. Configure SSL in the Mobile Server by adding SSL=YES in the [WEBTOGO] section of the ORACLE_HOME\Mobile\Server\bin\webtogo.ora file.

  2. If you do not have a secure-web-site.xml file, then copy and rename the default-web-site.xml to J2EE_HOME\config\secure-web-site.xml.

  3. Edit the secure-web-site.xml file with the following elements:

    1. Add secure="true" to the <web-site> element, as follows:�

      <web-site port="443" display-name="Oracle Application Server� Containers for J2EE Web Site" secure="true">
    2. Add the following new line inside the <web-site> element to define the� keystore and the password:

      <ssl-config keystore="YourKeystore" keystore-password="YourPassword" />

      where YourKeystore is the path and name of the keystore and YourPassword is the keystore password. The path for the keystore can either be a full path or a path that is relative to J2EE_HOME\config. In addition, you can hide the password through password indirection. This is discussed fully in the Oracle Application Server Containers for J2EE Security Guide. For example, with a keystore of "../../keystore" and password of "oracle", the configuration is as follows:�

      <!-- Enable SSL -->�<ssl-config keystore="../../keystore" keystore-password="oracle"/>
    3. Change the <web-site> element port number to use an available port. The reason you must change the port is because you copied this file from default-web-site.xml, which uses the port that is currently configured. Thus, choose a port that can be used for SSL communication; for example, the� default for SSL ports is 443.�

    4. Save the changes to secure-web-site.xml.

  4. Edit the server.xml file to point to the secure-web-site.xml file.�

    1. Uncomment or add the following line in the file server.xml so that the� secure-web-site.xml file is added to the OC4J initialization.

      <web-site path="./secure-web-site.xml" />
    2. Save the changes to the server.xml file.

  5. Stop and re-start OC4J to include the secure-web-site.xml file modifications.

  6. Test the SSL port by accessing the Mobile Server in a browser on the SSL port. �For example, https://<yourserver>:443/webtogo.

    If you are using the test keystore file or your own self-signed certificate, you will be asked to accept the certificate, since the SSL certificate used is not signed by an accepted certificate authority.� When completed, Mobile Server listens for SSL requests on the port configured in the secure-web-site.xml file and listens for non-SSL requests on the port configured in the default-web-site.xml file. 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

17.3 Troubleshooting Error Messages for an SSL-Enabled Mobile Server

The following errors may occur when using SSL certificates on your Mobile Server:

No available certificate corresponds to the SSL cipher suites which are enabled
Cause: Something is wrong with your certificate.
Action: Examine your certificates and check that at least one of them supports the SSL cipher suite you are using.
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.