33 Enabling AJPS

This chapter describes how to enable (and disable) secure Apache JServ Protocol (AJPS), so that it could be used instead of HTTP for communication between Oracle HTTP Server and OC4J.

By default, AJPS is not enabled when you install Oracle Beehive.

This chapter covers the following topics:

Enabling AJPS
Disabling AJPS

Enabling AJPS

These steps involve creating wallets and certificates. Because both of these are specific to an Oracle Beehive instances, you must perform the following steps on every Oracle Beehive instance:

Create a keystore with an RSA private/public key pair using the keytool utility.

Note:
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 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 JDK. The underlying physical manifestation of this object is a file.

For more information about the keytool utility, refer to http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html.

For additional information, refer to "Using Keys and Certificates with OC4J and Oracle HTTP Server" and "Using SSL with Standalone OC4J" in Chapter 15, "SSL Communication with OC4J" in Oracle Containers for J2EE Security Guide.

The following example generates a keystore in a file named mykeystore.jks, which has a password of 123456, using the RSA key pair generation algorithm:
```
<Oracle home>\jdk\bin\keytool -genkey -keyalg RSA
  -keystore mykeystore.jks -validity <number of days> -storepass 123456
```
In this utility:
- The keystore option sets the filename where the keys are stored.
- The -validity <number of days> option sets the expiry date.
- 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 utility 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):
```
Note:
Always press RETURN for the key password. The keystore password must be the same as the key entry password.

The mykeystore.jks file is created in the current directory. The default alias of the key is mykey.
Export the certificate from the keystore you just created to a file with the keytool utility. The following example exports the certificate into a file named C:\cert.txt:
```
<Oracle home>\jdk\bin\keytool -export -file C:\cert.txt
  -keystore mykeystore.jks -storepass 123456
```
Ensure you specify the same password you used to create the keystore.
Import the certificate file into Oracle Wallet.
1. If you have not already done so, create a wallet and configure it for Oracle Beehive by following the steps described in "Configuring TLS with Oracle Wallet".
2. Use Oracle Wallet Manager to import the certificate. Select Menu, Operations, Import Trusted Certificate. Save the wallet.

Modify the KeystoreFile property of your Oracle Beehive instance:

beectl modify_property
  --component <Oracle Beehive instance identifier>
  --name KeystoreFile
  --value <full path name of the keystore file>

For example, if the identifier of your Oracle Beehive instance is beehive_instance_instance1.example.com and the full path name of your keystore file is C:\mykeystore.jks, then run the following command:

beectl modify_property
  --component beehive_instance_instance1.example.com
  --name KeystoreFile
  --value C:\mykeystore.jks

To retrieve the identifier of your Oracle Beehive instance, call the following command, where example.com is the host name of your Oracle Beehive instance:

beectl list_properties --component example.com

-------------------+-----------------------------------------------------------
Property name      | Property value                                    
-------------------+-----------------------------------------------------------
PrimaryHostName    | example.com                           
-------------------+-----------------------------------------------------------
Site               | _CURRENT_SITE                                     
-------------------+-----------------------------------------------------------
AlternateHostNames |                                                   
-------------------+-----------------------------------------------------------
BeehiveInstances   | beehive_instance_instance1.example.com
-------------------+-----------------------------------------------------------
Alias              | example.com                           
-------------------+-----------------------------------------------------------

Modify the KeystoreFilePassword property (the command will prompt you for the password):

beectl modify_secure_property
  --component <Oracle Beehive instance identifier>
  --name KeystoreFilePassword
  --value

Modify the AjpsEnabled property of the ManagedOc4jCluster object if it is false:

beectl modify_property
  --component _CURRENT_SITE:ManagedOc4jCluster
  --name AjpsEnabled
  --value true

Modify the AjpsEnabled property of the HttpServerCluster object if it is false:

beectl modify_property
  --component _CURRENT_SITE:HttpServerCluster
  --name HttpServerSslEnabled
  --value true

Commit configuration changes by calling the following beectl command:
```
beectl activate_configuration
```
Note:
If the beectl activate_configuration command asks you to run the beectl modify_local_configuration_files command, run this command. The command may restart your application tier.

Disabling AJPS

Set the AjpsEnabled property of the ManagedOc4jCluster object to false (this example also commits configuration changes):

beectl modify_property
  --component _CURRENT_SITE:ManagedOc4jCluster
  --name AjpsEnabled
  --value false
  --activate_configuration true

Modify local files (the following command may restart the application tier):
```
beectl modify_local_configuration_files
```