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:

The client contacts the server to establish a SSL connection.
The server looks in its keystore for its own SSL certificate and sends it back to the client.
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.
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.
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.

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 keyst ore, 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:

Access the page in a browser, and accept the SSL certificate when prompted.
View the certificate through your browser options.
Import the certificate into the Oracle SES keystore.
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 Require SSL
Configuring Oracle HTTP Server to Require SSL

Configuring Oracle Secure Enterprise Search to Require SSL

When Oracle SES is fronted by an Oracle HTTP Server, Oracle recommends that Oracle SES be configured to require 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:

Create a new keystore. This step is optional but Oracle recommends it. To create the keystore:
1. Log in to the admin console for WebLogic available at http://sesHost:sesPort/console. Use the following credentials:
  
  Login Name: weblogic
  
  Password: Oracle SES Administrator's password
2. Expand the Environment button and click Servers. This takes you to the configuration page for the servers.
3. Click on 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. The default keystore is located at ORACLE_BASE/wlserver/server/lib. To create a new keystore SESIdentity.jks, add the path and name ORACLE_BASE/wlserver/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. The default keystore is located at ORACLE_BASE/wlserver/server/lib. To create a new keystore SESTrust.jks, add the path and name ORACLE_BASE/wlserver/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.
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 this command from ORACLE_HOME:
```
>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 $ORACLE_BASE/wlserver/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 running the following command from ORACLE_HOME.
```
> keytool -genkey -keyalg RSA -alias sescert -keysize 1024 -dname "CN=example0123.us.mycompany.com,OU=ses,O=oracle,C=us" -keypass welcome1 -keystore $ORACLE_BASE/wlserver/server/lib/SESTrust.jks -storepass welcome1 -storetype jks
```
3. Certify the generated keys by running the following command from ORACLE_HOME.
```
> keytool -selfcert -alias sescert -keyalg RSA -validity 2000 -keypass welcome1 –keystore $ORACLE_BASE/wlserver/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 from ORACLE_HOME.
```
> keytool -selfcert -alias sescert -keyalg RSA -validity 2000 -keypass welcome1 -keystore $ORACLE_BASE/wlserver/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: https://download.oracle.com/docs/cd/E12840_01/wls/docs103/secmanage/identity_trust.html
Configure Oracle SES to use the generated key:
1. Log in to the admin console for WebLogic and select the server for which you want to configure SSL by expanding the Environment button and clicking on Servers. This takes you to the configuration page for the servers.
2. Click the ssl tab.
3. The private key location is set to from Custom Identity Keystore.
4. In the Private Key Alias field, provide the private key alias. This is the alias specified in step 2a.
5. Provide the private key pass phrase that you specified in step 2a.
6. Save the settings.
Enable SSL for Oracle SES:
1. Log in to the admin console for WebLogic and select the server for which you want to configure SSL by expanding the Environment button and clicking on Servers. This takes you to the configuration page for the servers.
2. Click the General tab.
3. Select SSL Listen Port Enabled and provide a port number. The default port is 7002.
4. Save the settings.
5. Click the Control tab. You can access the control tab by expanding the Environment button and clicking on Servers.
6. From the control tab, restart SSL.

Configuring Oracle HTTP Server to Require SSL

Configuring OHS to require 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:

Configure the Oracle HTTP server:
1. From ORACLEOHS_HOME/bin, run owm. 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 ORACLE_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 wallet.
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.

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>

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>

Exchange the certificates for OHS and Oracle SES WebLogic servers. 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 Require SSL to a suitable location by running the following command:
```
> keytool -export -alias sescert –keystore $ORACLESES_HOME/wls/wlserver/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 Require SSL to the file /tmp/SESIdentityCertificate.crt.
2. Import the exported OHS certificate created in step 1h to Oracle SES. To import it, run this command from ORACLE_HOME:
```
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 ORACLE_BASE/wlserver/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 $ORACLE_BASE/wlserver/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 Oracle WebLogic Server by using the control page of the server.
  
  To access the control page, click Environment, then Server, and then Control.