Skip Headers
Oracle® Secure Enterprise Search Administrator's Guide
11g Release 2 (11.2.2.2)

E35070-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

SSL and HTTPS Support in Oracle Secure Enterprise Search

For SSL support, Oracle SES uses JSSE, a highly-customizable SSL package included in Sun Microsystem's J2SE. Oracle SES uses SSL for many operations, some acting as the SSL client, and others acting as the SSL server.

Oracle SES can crawl HTTPS-based URLs, and the Oracle SES middle tier can be configured to support HTTPS-based access. HTTPS refers to HTTP running over a secure socket layer (SSL).

Understanding SSL

SSL is an encryption protocol for securely transmitting private content on the internet. Using SSL, two parties can establish a secure data channel. SSL uses a cryptographic system that uses two keys to encrypt data: a public key and a private key. Data encrypted with the public key can only be decrypted using the private key, and vice versa.

In SSL terms, the party that initiates the communication is considered the client. During the SSL handshake, authentication between the two parties occurs. The authentication can be one sided (server authentication only) or two sided (server and client authentication).

Server authentication is more common. It happens every time a Web browser accesses a URL that starts with HTTPS. Because of server authentication, the client can be certain of the server's identity and can trust that it is safe to submit secure data such as login username and password to the server.

The following list defines some common terms related to SSL:

  • Keystore: A repository that includes the following:

    • Certificates identifying trusted entities. If a keystore contains certificates of only trusted entities, then it is referred to as a truststore.

    • Private-key and the matching certificate. This certificate is sent as a response to SSL authentication challenges.

  • Certificate: A digital identification of an entity that contains the following:

    • SSL public key of the server

    • Information about the server

    • Expiration date

    • Digital signature by the issuer of the certificate used to verify the authenticity of the certificate

  • Certificate authority (CA): A well known and trusted entity (for example, VeriSign or Thawte). CAs are usually the issuers of other certificates.

  • Root certificate: A self-signed certificate where the issuer is the entity that the certificate represents. CA certificates are typically root certificates.

  • Certificate chain: This chain consists of the certificate, its issuer, the issuer of the issuer, and so on, all the way to the root certificate. If one certificate in the chain is trusted (that is, it is in the keystore), then the rest of the certificate can be verified for authenticity. This makes it possible for a keystore to contain only a few well-known and trusted root certificates from which most other certificates originate.

Every SSL connection starts with the SSL handshake. These are the basic steps:

  1. The client contacts the server to establish a SSL connection.

  2. The server looks in its keystore for its own SSL certificate and sends it back to the client.

  3. The client checks its keystore to see if it trusts the server or any of the entities in the server's certificate chain. If not, then the handshake is aborted. Otherwise, the client positively identifies the server and deems it trusted. The expiration date of the certificate is also checked, and the name on the certificate is matched against the domain name of the server.

  4. If the server is configured to require client authentication, then the server asks the client to identify itself, so the mirror image of steps 2 and 3 takes place.

  5. Session keys are generated and used for encrypting the transmitted data.

Oracle strongly recommends that you use an SSL-protected channel to transmit password and other secure data over networks.

Typically, the following components transmit password and other secure data over a network:

  • Federation

  • Connectors

  • Authorization Plugin

  • Identity plugin

  • Suggested content

  • Web Service APIs

Managing the Keystore

The keystore is populated with the root certificates representing well known certificate authorities. Most SSL-enabled Web sites use certificates that originate or chain from these main root certificates. See "Oracle SES Acting as an SSL Server" for more information about managing the keystore.

See Also:

The Java Secure Socket Extension (JSSE) Reference Guide at

http://docs.oracle.com/javase/1.4.2/docs/guide/security/jsse/JSSERefGuide.html

Importing SSL Certificates into the Java Virtual Machine

For connectors that interact with external SSL-enabled repositories at crawl time and query time, you must import the SSL certificate into the keystore location of the Oracle SES middle tier, that is, into the WebLogic Server directory wls_home/server/lib.

Maintaining a Keystore

Depending on the requirement, the keystore might need maintenance. For example:

  • If a main root certificate has expired, then it must be replaced by a new issue.

  • If Oracle SES must trust another SSL-enabled peer whose certificate does not originate from a root certificate, then the peer's certificate, or one from its chain, must be added to the keystore.

  • To enable SSL in the Oracle SES middle tier, Oracle SES must act as an SSL server, and that calls for the keystore to contain a private key and the corresponding certificate with the public key. (The same holds true for the SSL client role where the server requires client side SSL authentication.)

Maintenance of the keystore can be done using Sun Microsystem's keytool program, which ships with J2SE. You can find this utility under java_home/bin. Third-party keytool GUI wrapper programs are available.

See Also:

For detailed instructions on how to add, remove, or update certificates, generate keys, and create new keystores with a keytool:

http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/keytool.html

Oracle SES Acting as an SSL Client

Oracle SES acts as the SSL client in the following situations:

  • The crawler accesses a data repository that uses SSL (for example, HTTPS Web sites).

  • The form registration wizard in the Oracle SES Administration GUI accesses HTTPS URLs.

  • Oracle SES federates queries to other SSL-enabled search services (for example, an SSL-enabled Oracle SES instance).

    Note that for Oracle SES 11.1.2 instances, the broker and the endpoint do not have to exchange any certificates when the broker tries to create a federated source using the HTTPS Web service URL. This is because the Oracle SES instances share the same default certificates in the trusted store.

If you crawl an SSL-enabled Web site whose SSL key is not in the SSL keystore, the following error occurs:

@ javax.net.ssl.SSLHandshakeException: 
sun.security.validator.ValidatorException: No trusted certificate found 

To fix this error, you can add the key to the Oracle SES keystore.

To add an SSL certificate to the Oracle SES keystore: 

  1. Access the page in a browser, and accept the SSL certificate when prompted.

  2. View the certificate through your browser options.

  3. Import the certificate into the Oracle SES keystore.

  4. Try the crawl again.

The following sections explain how to import certificates.

Oracle SES Acting as an SSL Server

Oracle SES acts as the SSL server when the Oracle SES middle tier, configured to use SSL, responds to HTTPS requests. The Oracle SES crawler connects to SSL-enabled sites using the JSSE package, which contains a keystore with a few default certificates from well known CAs.

This section contains the following topics:

Configuring Oracle Secure Enterprise Search to Use SSL

When Oracle SES is used along with the Oracle HTTP Server, Oracle recommends that Oracle SES be configured to use SSL with client-side authentication for communication with the Oracle HTTP Server. Furthermore, use a keystore other than the default one. Oracle recommends that you create separate identity and trust keystores.

The communication channel between the client and Oracle SES is by default not SSL-enabled and not encrypted.

Perform the following steps:

  1. Create a new keystore. This step is optional but Oracle recommends it. To create the keystore:

    1. Log in to the WebLogic Server Administration Console.

    2. Expand the Environment button and click Servers. This takes you to the configuration page for the servers.

    3. Click the name of the server for which you want to configure SSL.

    4. Click the keystores tab.

    5. From the keystores list, select Custom Identity and Custom Trust.

    6. In the custom identity keystore field, add the complete path and name of the new keystore. To create a new keystore SESIdentity.jks, add the path and name wls_home/server/lib/SESIdentity.jks to the keystore field.

    7. Set the custom identity keystore type to be jks. Set a pass phrase for the store.

    8. In the custom trust field, add the complete path and name of the new keystore. To create a new keystore SESTrust.jks, add the path and name wls_home/server/lib/SESTrust.jks to the keystore field.

    9. Set the custom identity keystore type to be jks. Set a pass phrase for the store.

    10. Click Save to create the new keystores.

  2. Create new certificates for the identity and trust keystores. Use Sun Microsystem's keytool utility to perform the following steps:

    1. Generate the key for the identity keystore by executing the following keytool command from the java_home/bin directory:

      >keytool -genkey -alias [MyCertificateAlias] -keyalg RSA -keysize 1024 -dname ["My DN"] -keypass [MyKeyPass ] -keystore [MyKeyStore ]  -storepass  [PasswordOfTheKeystoreCreatedAbove] -storetype [StoreTypeCreatedAbove]
      

      For example,

      > keytool -genkey -alias sescert -keyalg RSA -keysize 1024 -dname "CN=example0123.us.mycompany.com,OU=ses,O=oracle,C=us" -keypass welcome1 -keystore wls_home/server/lib/SESIdentity.jks -storepass welcome1 -storetype jks
      

      The above command creates a certificate with the alias sescert and the given dn and keypass welcome1. It uses SESIdentity.jks as the keystore, which is the same as the one created in step 1. The storepass and the storetype are the same as supplied in step 1.

    2. Generate the key for the trust keystore by executing the following keytool command from the java_home/bin directory:

      > keytool -genkey -keyalg RSA -alias sescert -keysize 1024 -dname "CN=example0123.us.mycompany.com,OU=ses,O=oracle,C=us" -keypass welcome1 -keystore wls_home/server/lib/SESTrust.jks -storepass welcome1 -storetype jks
      
    3. Certify the generated keys by running the following command:

      > keytool -selfcert -alias sescert -keyalg RSA -validity 2000 -keypass welcome1 -keystore wls_home/server/lib/SESIdentity.jks -storepass welcome1
      

      The command uses the alias, keypass, and the keystore location supplied in step 2.a. The store pass is the password of the store.

      To self certify the keystore, run the following command:

      > keytool -selfcert -alias sescert -keyalg RSA -validity 2000 -keypass welcome1 -keystore wls_home/server/lib/SESTrust.jks -storepass welcome1
      

      Note:

      In addition to using Sun Microsystem's Keytool utility to self-sign the generated key, you can use any of the options mentioned here: http://docs.oracle.com/cd/E12840_01/wls/docs103/secmanage/identity_trust.html
  3. Configure Oracle SES to use the generated key:

    1. Log in to the WebLogic Server Administration Console.

    2. Select the server for which you want to configure SSL by expanding the Environment button and clicking on Servers. The configuration page for servers is displayed.

    3. Click the ssl tab.

    4. The private key location is set to from Custom Identity Keystore.

    5. In the Private Key Alias field, provide the private key alias. This is the alias specified in step 2a.

    6. Provide the private key pass phrase that you specified in step 2a.

    7. Save the changes.

  4. (Optional) Enable two-way-SSL for Oracle SES:

    1. Log in to the WebLogic Server Administration Console.

    2. Select the server for which you want to configure SSL by expanding the Environment button and clicking on Servers. The configuration page for servers is displayed.

    3. Click the SSL tab.

    4. Click Advanced link present at the bottom of the page.

    5. Set the parameter Two Way Client Cert Behavior value to Client Certs Requested and Enforced.

    6. Save the changes and restart the SSL channel.

  5. (Optional) Enable WebLogic plugin when the WebLogic Server is used along with the Oracle HTTP Server that uses WebLogic proxy plugin:

    1. Log in to the WebLogic Server Administration Console.

    2. Select the server for which you want to configure SSL by expanding the Environment button and clicking on Servers. The configuration page for servers is displayed.

    3. Click the General tab.

    4. Click Advanced link present at the bottom of the page.

    5. Select Weblogic plugin enabled.

    6. Save the changes and restart the Oracle SES server.

  6. Enable SSL for Oracle SES:

    1. Log in to the WebLogic Server Administration Console.

    2. Select the server for which you want to configure SSL by expanding the Environment button and clicking on Servers. The configuration page for servers is displayed.

    3. Click the General tab.

    4. Select SSL Listen Port Enabled and provide a port number. The default port is 7002.

    5. Save the changes.

    6. Click the Control tab. You can access the control tab by expanding the Environment button and clicking on Servers.

    7. From the Control tab, restart SSL.

Configuring Oracle HTTP Server to Use SSL

Configuring Oracle HTTP Server (OHS) to use SSL is a multistep process involving configuration of the server, modification of certain .conf files, and exchange of certificates.

To configure Oracle HTTP Server to require SSL: 

  1. Configure the Oracle HTTP server:

    1. From ORACLEOHS_HOME/bin, run owm, where, ORACLEOHS_HOME is the root directory of the Oracle HTTP Server (OHS). This opens Oracle Wallet Manager, which is used to create the certificate for OHS.

    2. Click Wallet and then click New.

      If you get a message indicating that the default directory is not set, click Continue.

    3. Provide a password for the wallet. Click No for the option to configure user certificate request.

    4. Click Wallet and then click Save As. Save the wallet to the directory ORACLEOHS_HOME/instances/instanceName/config/OHS/ componentName/keystores/myWallet. This creates a new wallet with the name myWallet for the Oracle HTTP server.

      instanceName and componentName are specified during the installation of Oracle HTTP Server.

    5. Create a key-cert pair (a user certificate) using the following command from ORACLEOHS_HOME/bin

      > orapki wallet add -wallet [walletPath] -dn ["myDN"] -keysize 1024 -self_signed -validity 720
      

      For example,

      > orapki wallet add -wallet $ORACLEOHS_HOME/instances/instance1/config/OHS/ohs1/keystores/myWallet -dn CN=example0123.us.mycompany.com,OU=ohs.ses,O=oracle,ST=ca,C=US -keysize 1024 -self_signed -validity 720
      

      The command adds a user certificate with the given dn and the wallet located at ORACLEOHS_HOME/instances/instance1/config/OHS/ohs1/keystores/myWallet. Note that instance1 is the name of the instance provided during installation and ohs1 is the name of the component provided during installation.

    6. Go back to the OWM utility and reopen the wallet. To reopen it, close and open the wallet by selecting the correct directory. You should now see Certificate:[Ready] under the wallet.

    7. Save the changes.

    8. Double-click Certificate:[Ready], click the Operations tab, and select export user certificate. Export the user certificate file (/tmp/OHSIdentityCertificate.crt) to a suitable location.

  2. Edit the file ssl.conf located at ORACLEOHS_HOME/instances/instanceName/config/OHS/componentName/.to include the following. Note that instanceName and componentName are specified during the installation of Oracle HTTP Server.

    <VirtualHost*:dddd>
    <IfModule mod_weblogic.c>
       WebLogicHost [SESHost]
       WebLogicPort [SESPort]
       Debug ALL
       WLLogFile [Location of the log file]
       SecureProxy On
       WlSSLWallet "MyWalletLocation"
    <Location /weblogic>
       SetHandler weblogic-handler
       PathTrim /weblogic
    </Location>
    <Location /console>
       SetHandler weblogic-handler
    </Location>
    </IfModule>
    </VirtualHost >
    

    For example, if the host is sesHost, the port is 7002, and the wallet is located at Oracle_Instance/config/Component_Type/Component_Name/keystores/myWallet, then the following configuration file is helpful:

    <IfModule mod_weblogic.c>
       WebLogicHost sesHost
       WebLogicPort 7002
       Debug ALL
       WLLogFile /scratch/exampleuser/Certificates/weblogic.log
       SecureProxy On
       WlSSLWallet "${ORACLE_INSTANCE}/config/${COMPONENT_TYPE}/${COMPONENT_NAME}/keystores/myWallet"
    <Location /weblogic>
       SetHandler weblogic-handler
       PathTrim /weblogic
    </Location>
    <Location /console>
       SetHandler weblogic-handler
    </Location>
    </IfModule>
    
  3. Edit the file mod_wl_ohs.conf located at ORACLEOHS_HOME/instances/instanceName/config/OHS/componentName/ to include the following:

    <IfModule weblogic_module>
            WebLogicHost [SES host name]
      WebLogicPort [SES HTTP port]
      Debug ON
      WLLogFile [Location of the log]
    </IfModule>
    <Location /search/query>
      SetHandler weblogic-handler
    </Location>
    <Location /search/admin>
      SetHandler weblogic-handler
    </Location>
    # For monitor SES URL
    <Location /monitor>
    SetHandler weblogic-handler
    </Location>
    # For Help links in Admin side
    <Location /search/ohw>
    SetHandler weblogic-handler
    </Location>
    

    For example if the Oracle SES host is sesHost and the port is 8001, then the file would contain:

    <IfModule weblogic_module>
              WebLogicHost sesHost
      WebLogicPort 8001
      Debug ON
      WLLogFile /scratch/exampleuser/weblogic.log
    </IfModule>
    <Location /search/query>
      SetHandler weblogic-handler
    </Location>
    <Location /search/admin>
      SetHandler weblogic-handler
    </Location>
    <Location /monitor>
    SetHandler weblogic-handler
    </Location>
    <Location /search/ohw>
    SetHandler weblogic-handler
    </Location>
    
  4. Exchange the certificates for OHS and Oracle SES WebLogic Server. To exchange them, use Oracle Wallet Manager to import and export certificates from and to the wallet, and use the Java keytool for the Oracle SES keystore. While importing a certificate, ensure that it is self-signed. If not, then you must import any of the certificates in the chain. See "Understanding SSL" for more information about certificate chains.

    Perform the following steps to exchange certificates:

    1. Export the SESIdentity key generated in step 2a of Configuring Oracle Secure Enterprise Search to Use SSL to a suitable location by running the following command from the Oracle SES directory java_home/bin:

      > keytool -export -alias sescert -keystore wls_home/server/lib/SESIdentity.jks -file /tmp/SESIdentityCertificate.crt
      

      The above command exports the certificate with the alias sescert and the keystore created in step 2a of Configuring Oracle Secure Enterprise Search to Use SSL to the file /tmp/SESIdentityCertificate.crt.

    2. Import the exported OHS certificate created in step 1h to Oracle SES. To import it, run the following command from the Oracle SES directory java_home/bin:

      > keytool -file [LocationOfOHSIdentityCertificate]  -alias [MyOHSCerAlas] -import -trustcacerts -keystore [LocationofSESTrustStore] -storepass [MyPasswordForTheTrustStore] -storetype jks
      

      For example, if the location of the exported OHS identity certificate is tmp/OHSIdentityCertificate.crt, the Oracle SES trust store is at wls_home/server/lib/SESTrust.jks, the store password is welcome1, and the alias is ohsCert, then run the following:

      > keytool -file tmp/OHSIdentityCertificate.crt  -alias ohsCert -import -trustcacerts -keystore wls_home/server/lib/SESTrust.jks -storepass welcome1 -storetype jks
      
    3. Import the Oracle SES certificate into OHS wallet. The Oracle SES certificate is the file SESIdentityCertificate.crt exported in step 4a. To import this certificate, from the Oracle Wallet Manager utility, click Operations and select Import Trusted Certificate. Navigate to the location of the exported Oracle SES certificate (/tmp/SESIdentityCertificate.crt), and import it as a trusted certificate.

    4. Restart Oracle HTTP Server. Before restarting the server, ensure that the Auto Login option is enabled in Oracle Wallet Manager. The restart fails if the option is not enabled.

      To restart the server, run the following command from ORACLEOHS_HOME/instances/instance1/bin/:

      opmnctl restartproc process-type=OHS
      
    5. Restart SSL for the WebLogic Server by using the control page of the server.

      To access the control page, click Environment, then Server, and then Control.

See Also:

Oracle Database Advanced Security Administrator's Guide for more information about Oracle Wallet Manager

Oracle Database Advanced Security Administrator's Guide for more information about the orapki utility

Oracle HTTP Server Administering a Standalone Deployment Based on Apache 2.0 for more information about enabling SSL for OHS