4 Configuring Security

This chapter explains how to configure security for Business Transaction Management. You should read this chapter thoroughly, and, if you decide to configure security, you should perform the security configuration for the relevant execution environment before installing any Business Transaction Management components into it.

You can configure security for Business Transaction Management using the following mechanisms:

Network-level security, in which you configure your application servers to communicate over HTTPS.

For management components that communicate using HTTPS, this security mechanism provides one-way or mutual authentication, message integrity, and encryption of on-the-wire messaging data. Refer to Setting up Network-Level Security for details.
Business Transaction Management's built-in security for HTTP(S) communications between Business Transaction Management components.

This security mechanism provides trust between management components that communicate using HTTP(S) and encryption of sensitive elements of their messaging data prior to serialization (that is, before being sent over the wire or stored to disk). Refer to Configuring the Assertion Secret and Encryption Key for details.
Business Transaction Management's built-in security for the transmission of observation messages from observers to monitors using Observation Protocol Secure (OPS). OPS is the Oracle proprietary Observation Protocol (OP) over a secure socket (SSL).

This security mechanism provides authentication between an observer and monitor, message integrity, and encryption of observation messages sent over the wire. Server authentication (authentication of the monitor to the observer) is provided by SSL. Client authentication (authentication of the observer to the monitor) is provided by OPS. Refer to Setting up a Secure Socket (SSL) for Observation Messages for details.

Communication Protocols and Deployment Scenarios

Business Transaction Management is designed for use in a distributed environment. As such, some components might be deployed in remote data centers, in a DMZ, or in a network without access to a centralized database. The following table describes the type of access required between the various Business Transaction Management components and between those components and your business services.

Table 4-1 Business Transaction Management Communication Protocols

From this Component	Required Protocol	To this Component	Description	Index to Diagrams
Each central server (the Main, the Transaction, and the Performance server)	HTTP or HTTPS	Any other central server	The central servers must be able to communicate with each other. The usual deployment topology will place each of these in the same network zone.	A
Each central server	HTTP or HTTPS	All monitors	Each of the central servers must be able to communicate with all monitors. This includes monitors that are deployed outside of the central network zone.	B
Main server	TCP, HTTP or HTTPS	All monitored business services	The Main server should be able to communicate with the monitored business services to determine whether they are “alive” (up or down). Note that the precise protocol used to determine aliveness can be configured on a per-service basis. (For information on configuring this protocol, enter a service request at My Oracle Support.)	C
Each monitor	HTTP or HTTPS	All central servers	Monitors must be able to communicate with each of the central servers.	D
Each monitor	JDBC	A Message Log Database (messageLogDB)	Each monitor must be able to write to, and read from, its Message Log Database using JDBC. The Message Log Database can be a single database inside a trusted network that is used by all monitors. Alternatively, if you have monitors in a DMZ or in a network without access to a centralized database, you can deploy one or more databases for the remote monitors.	E
Each observer	TCP and HTTP or HTTPS	Associated monitor	Each observer requires two connections to its associated monitor. The observer uses an HTTP(S) connection to download its configuration from the monitor. To transmit observation messages to the monitor, the observer connects using Observation Protocol (OP) over TCP or Observation Protocol Secure (OPS) over a secure socket. For monitor groups, these connections are made to the load balancer that fronts the monitor group. The socket port number is configured by way of the Observer Communication policy.	F
Transaction server	JDBC	All Message Log Databases	Optional. The Transaction server does not require direct access to the Message Log Databases. However, by providing such access, you can improve the performance of message log queries. You should enable this communication channel whenever possible.	G
Main server	JDBC	Sphere database (sphereDB)	The Main server must be able to write to the Sphere database using JDBC.	H
Performance	JDBC	Measurement database (measurementDB)	The Performance server must be able to write to the Measurement database using JDBC.	I
Transaction	JDBC	Transaction database (transactionDB)	The Transaction server must be able to write to the Transaction database using JDBC.	J
Monitor (in a monitor group)	JDBC	Monitor group database	Each monitor in a particular monitor group must be able to write to the same monitor group database using JDBC.	K

The following diagrams illustrate the type of access required by Business Transaction Management components in a variety of deployment scenarios. Note that the circled letters in the diagrams cross reference Table 4-1, "Business Transaction Management Communication Protocols".

Figure 4-1, "Deployed Business Transaction Management Components and Business Services"
Figure 4-2, "Communication Connections Among the Central Servers and Between the Central Servers and Monitors"
Figure 4-3, "Connections Between Business Transaction Management Components and Databases"
Figure 4-4, "Communication Connections Between the Monitors and Observers"
Figure 4-5, "Communication Connections Between the Main Server and Business Services"

Figure 4-1 Deployed Business Transaction Management Components and Business Services

Description of "Figure 4-1 Deployed Business Transaction Management Components and Business Services"

Figure 4-2 Communication Connections Among the Central Servers and Between the Central Servers and Monitors

Description of "Figure 4-2 Communication Connections Among the Central Servers and Between the Central Servers and Monitors"

Figure 4-3 Connections Between Business Transaction Management Components and Databases

Description of "Figure 4-3 Connections Between Business Transaction Management Components and Databases"

Figure 4-4 Communication Connections Between the Monitors and Observers

Description of "Figure 4-4 Communication Connections Between the Monitors and Observers"

Figure 4-5 Communication Connections Between the Main Server and Business Services

Description of "Figure 4-5 Communication Connections Between the Main Server and Business Services"

Setting up Network-Level Security

If you want to enable network-level security for Business Transaction Management components, you can do so using SSL/TLS provided by the application servers in which the components are deployed. SSL provides message integrity and confidentiality for communication among distributed management components, encrypting management traffic as it flows from one server to another. When configured with client certificates, SSL also provides mutual authentication between management components. Business Transaction Management provides no specialized support for SSL and does not interfere with standard SSL configurations. Therefore, any configuration supported by your application server can be used to secure Business Transaction Management traffic. It is strongly recommended that you first ensure that your application servers are properly configured for SSL before you install any Business Transaction Management components.

Once you have configured and tested SSL on the application servers where Business Transaction Management will be deployed, you will install Business Transaction Management and then configure it using the browser-based Initial Configuration wizard. During initial configuration, you will provide the SSL address and port number for your installation. The Business Transaction Management components will automatically communicate over the secured transports.

Note:

Observers and monitors communicate with each other by way of two separate channels—a socket connection for transmitting observation messages, and an HTTP/HTTPS connection for administration-related messages. Setting up SSL for the socket connection is covered in Setting up a Secure Socket (SSL) for Observation Messages. Setting up an HTTPS connection is a separate and unrelated task that you perform using the security features of your application servers.

Configuring HTTPS

This section pertains to all Business Transaction Management components, including the command line interface (CLI).

If you are installing the central servers into an HTTPS-only environment (that is, an environment in which there is no HTTP traffic between components), you must do one of the following:

Ensure that the application servers hosting the central servers are listening only on HTTPS ports.

Or

Modify each web.xml file packaged in each of the central server WAR files so as to specify that only HTTPS access is allowed. You can do this by simply uncommenting the following <security-constraint> element that is provided in those files:

<security-constraint>
  <display-name>Require SSL communication</display-name>
  <web-resource-collection>
    <web-resource-name>All AmberPoint system services</web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>

Setting JSEE Properties on WebLogic Servers

As a part of configuring WebLogic servers to communicate over HTTPS, you must set a number of Java system properties in your servers. These properties specify the information needed by your WebLogic servers to access their security stores. The information you provide in the properties is as follows:

Note:

In the following list, two-way SSL refers to an SSL connection that requires mutual authentication. One-way SSL refers to an SSL connection that requires only server authentication.

location of the client's trust store (required for one- or two-way SSL)
type of the trust store (required for one- or two-way SSL)
password for accessing the trust store (required for one- or two-way SSL)
location of the server's key store (required for two-way SSL)
type of the key store (required for two-way SSL)
password for accessing the key store (required for two-way SSL)

WebLogic servers allow you to specify this information either by way of javax.net.ssl.* (JSEE) properties or by way of weblogic.security.* properties. WebLogic servers can read this information from either type of property. However, Business Transaction Management also requires access to this same information but can only read the information from JSEE properties. For this reason you can provide the required information by setting JSEE properties only, or by setting both weblogic.security.* and JSEE properties. If you do not set the JSEE properties, your Business Transaction Management components will fail to start up.

Note:

You must set the JSEE properties even if you have disabled the Use JSSE SSL checkbox on the Environment > Servers > servername > Configuration > SSL > Advanced tab in the WebLogic Administration Console.

You set the JSEE properties as Java options either by way of the WebLogic Administration Console or in the WebLogic server startup script. These are the options to set for two-way SSL:

-Djavax.net.ssl.trustStore=path_to_my_trustStore

-Djavax.net.ssl.trustStoreType=type_of_my_trustStore

-Djavax.net.ssl.trustStorePassword=my_trustStore_password

-Djavax.net.ssl.keyStore=path_to_my_keyStore

-Djavax.net.ssl.keyStoreType=type_of_my_keyStore 

-Djavax.net.ssl.keyStorePassword=my_keyStore_password

The following example shows how to set the JSEE properties on Windows for two-way SSL in the WebLogic server startup script using the WebLogic Demo security stores:

set JAVA_OPTIONS=-Djavax.net.ssl.trustStore=C:\Oracle\Middleware\wlserver_10.3\server\lib\DemoTrust.jks -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword=MyTrustStorePassword -Djavax.net.ssl.keyStore=C:\Oracle\Middleware\wlserver_10.3\server\lib\DemoIdentity.jks -Djavax.net.ssl.keyStoreType=JKS -Djavax.net.ssl.keyStorePassword=MyKeyStorePassword %JAVA_OPTIONS%

If you set these properties in your WebLogic server startup script, be sure to insert the line before the following line or the JAVA_OPTIONS value might be overwritten (the first example is for Windows and the second is for UNIX-like operating systems):

set SAVE_JAVA_OPTIONS=%JAVA_OPTIONS%

SAVE_JAVA_OPTIONS="${JAVA_OPTIONS}"

Note:

Use of the WebLogic Scripting Tool (WLST) in an HTTPS environment requires the weblogic.security.* properties.

Setting JSEE Properties for the Command Line Interface

If you are using the Business Transaction Management Command Line Interface (CLI) in an HTTPS environment, then you must set the same JSSE properties that you set on your WebLogic servers in Setting JSEE Properties on WebLogic Servers. The following example shows how to set the JSSE properties by way of the CLI's built-in variable, AP_OPTS. This example uses the the WebLogic Demo security stores:

set AP_OPTS=-Djavax.net.ssl.trustStore=C:\Oracle\Middleware\wlserver_10.3\server\lib\DemoTrust.jks -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword=MyTrustStorePassword -Djavax.net.ssl.keyStore=C:\Oracle\Middleware\wlserver_10.3\server\lib\DemoIdentity.jks -Djavax.net.ssl.keyStoreType=JKS -Djavax.net.ssl.keyStorePassword=MyKeyStorePassword

Configuring Firewalls

This section pertains to the central servers, monitors, and observers.

If you are using a firewall, you must configure it to allow access to each port on which a Business Transaction Management component receives communications. These are:

the ports on which the hosting application servers listen.
the sockets on which the monitors receive observation messages from the observers.
the ports used for JDBC connections to Business Transaction Management databases. These databases are discussed in Setting up Business Transaction Management Databases.

Configuring the Assertion Secret and Encryption Key

Note:

If you choose to perform the configuration described in this section, then you must do so on each application server that hosts a Business Transaction Management central server, monitor, or observer. You must also perform this configuration for the execution environment in which you use the Business Transaction Management command line interface (CLI).

Communications between Business Transaction Management components are secured by way of trusted assertions. This means that for your Business Transaction Management components to communicate with each other, and for your Business Transaction Management installation to function properly, every Business Transaction Management component must be configured with an assertion secret of the same value.

Business Transaction Management also encrypts sensitive data contained in the communications between its components. It encrypts this data for both on-the-wire communications and storage in the Business Transaction Management databases.

These security mechanisms are enabled by default, and all Business Transaction Management components are preconfigured with a default value for both the assertion secret and the encryption key. This default security configuration fully enables the security mechanisms and, at the same time, simplifies the installation of Business Transaction Management.

However, because every Business Transaction Management installation has the same default values, using the default values is a potential security threat. For demonstration purposes, and perhaps for development environments, using the default values might be adequate. But, in production environments, you should tighten security by providing your own unique values. You should also use your own values in your test environment before deploying Business Transaction Management into your production environment. If you intend to provide your own values for the assertion secret and encryption key, you should perform that configuration on each application server that hosts a Business Transaction Management component before you deploy the component.

For components deployed to WebLogic servers, you have a choice as to the method you use for configuring and storing these security settings—you can use either Oracle Wallet (see Configuring Security Using Oracle Wallet) or Business Transaction Management extension properties (see Configuring Security Using Extension Properties). (Oracle Wallet is an implementation of Oracle Credential Store Framework, or OCSF, and is a component of Java Platform Security, or JPS.) For all other Java application servers, and for Oracle Enterprise Gateway, you use Business Transaction Management extension properties. If necessary, you can mix these security configuration methods. For example, you could use Oracle Wallet on some application servers but use Business Transaction Management extension properties on other application servers.

Configuring Security Using Oracle Wallet

This section pertains to central servers, monitors, and observers that will be deployed to WebLogic application servers. It explains how to configure the assertion secret and encryption key for your Business Transaction Management components using Oracle Wallet. You must repeat this procedure for each central server, monitor, and observer for which you want to configure the assertion secret and encryption key using Oracle Wallet.

Ensure that the WebLogic domain in which the Business Transaction Management component will be installed includes the Java Required Files (JRF) template.

If the domain does not yet exist, be sure to add the JRF template when you create the domain. If the domain already exists but doesn't include the JRF template, extend the domain and add the template.

The JRF template includes the JPS JAR files that are referred to in later steps. (JPS is a component of Oracle Platform Security Services.)
Decide on names for the credentials that will hold your assertion secret and encryption key.

You are free to choose any name you want, but each of the two credentials must have a different name, and you must use the same two credential names for all of your Business Transaction Management components.
Decide on values for your issuer name and issuer assertion secret.

You are free to choose any values you want for these strings, but you must use the same values for all of your Business Transaction Management components.
Locate the distribution archive for the Business Transaction Management central servers and expand it into a directory on the machine that hosts the central server, monitor, or observer for which you want to configure security (this directory is henceforth referred to as BTM_Central_Expanded).

The distribution archive is named BTM_Servers*.zip, where * represents the version number.
Configure the setBtmOverriderEnv_via_CredStore script file by completing the following substeps.

Configuring the setBtmOverriderEnv_via_CredStore script file accomplishes these tasks: adds the JPS JAR files to your application server's classpath; overrides the default credential store; and specifies the names of the credentials that hold the shared secret and encryption key (note that you will create the credentials in a later step).
1. Locate the setBtmOverriderEnv_via_CredStore script file in BTM_Central_Expanded/security_add_ons.
  
  For Windows systems, use setBtmOverriderEnv_via_CredStore.cmd; for UNIX-like systems, use setBtmOverriderEnv_via_CredStore.sh.
2. Copy the script file to your WebLogic server:
  
  If you want to configure security for all domains, copy the script file to your WebLogic server's home directory. The home directory is the weblogic92 or wlserver_10.3 directory located in your WebLogic installation directory, for example, C:\bea\wlserver_10.3.
  
  If you want to configure security for a particular domain, copy the script file to the top level of that domain's directory.
3. Open the script file in a text editor.
4. Set the BTM_TIS_CRED_NAME variable to the name of the credential that holds the assertion secret by replacing the string >>> YOUR_ISSUER_SECRET_CREDENTIAL_NAME_HERE <<< with the credential name you chose for your assertion secret.
5. Set the BTM_ENCKEY_CRED_NAME variable to the name of the credential that holds the encryption key by replacing the string >>> YOUR_ENCRYPT_KEY_CREDENTIAL_NAME_HERE <<< with the credential name you chose for your encryption key.
6. Save and close the script file.
Configure your WebLogic domain startup scripts to call the setBtmOverriderEnv_via_CredStore script file:

Note:
This step assumes that you haven't modified your startWebLogic scripts. If you have modified your scripts, you might also have to modify the installation procedure accordingly.
1. Navigate to the bin directory of one of the WebLogic domains for which you want to configure security and open the startup script in a text editor (open bin\startWebLogic.cmd for Windows systems or bin/startWebLogic.sh for UNIX-like systems; do not edit the startup script located directly within the domain directory).
2. Locate the following line (the first line is for Windows and the second for UNIX-like systems):
```
call "%DOMAIN_HOME%\bin\setDomainEnv.cmd"

. ${DOMAIN_HOME}/bin/setDomainEnv.sh
```
3. Directly after that line, add a line that calls the setBtmOverriderEnv_via_CredStore script file:
  
  If you are configuring security for all domains on a Windows system, add this line:
```
call "%WL_HOME%\setBtmOverriderEnv_via_CredStore.cmd"
```
  If you are configuring security for all domains on a UNIX-like system, add this line (note the initial period and space):
```
. ${WL_HOME}/setBtmOverriderEnv_via_CredStore.sh   
```
  If you are configuring security for a particular domain on a Windows system, add this line:
```
call "%DOMAIN_HOME%\setBtmOverriderEnv_via_CredStore.cmd"
```
  If you are configuring security for a particular domain on a UNIX-like system, add this line (note the initial period and space):
```
. ${DOMAIN_HOME}/setBtmOverriderEnv_via_CredStore.sh
```
4. Repeat this step for each domain for which you want to configure security.
Add permission grants for Business Transaction Management components to the policy store:
1. Navigate to the config\fmwconfig directory of one of the WebLogic domains for which you are configuring security.
  
  This directory was created when you extended the domain to include the JRF template and is the default location where the oracle.security.jps.config property looks.
2. Open the file system-jazn-data.xml in a text editor.
3. For each deployment in the domain for which you want to configure security, add a <grant> element as a child of the <jazn-data>/<jazn-policy> element, replacing the string Your Deployment Name Here with the name of the deployment, as shown in the following example:
```
<jazn-data>
 <jazn-policy>
 (... other <grant> elements, etc. ...)
 
  
  <grant>
   <grantee>
    <codesource>
     <url>file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/Your Deployment Name Here/-</url>
    </codesource>
   </grantee>
   <permissions>
    <permission>
     <class>
      oracle.security.jps.service.credstore.CredentialAccessPermission
     </class>
     <name>context=SYSTEM,mapName=BTM,keyName=*</name>
     <actions>read,write</actions>
    </permission>
   </permissions>
  </grant>
  
 
 (... other <grant> elements, etc. ...)
 </jazn-policy>
</jazn-data>
```
  Table 1-1 lists the deployment names for the central servers and monitors. For observers, use the name of the deployment that contains the business application you want to monitor.
4. Save and close the file.
5. Repeat this step for each domain for which you want to configure security.
Use the Business Transaction Management command line interface (CLI) to create a “Trusted Issuer and Secret” credential that contains your assertion secret and add it to the Oracle Wallet credential store associated with the policy store that you just configured:

In the following substeps, you will first set up the environment for the CLI, then point the CLI to the Oracle Wallet credential store, and finally use the CLI to create the credential for your assertion secret and add it to the store.
1. Open a command shell or window and ensure that its JAVA_HOME and JPS_11_HOME environment variables are set properly.
  
  These variables can be set at the system or the shell/window level. The JAVA_HOME variable must point to a JDK that is version 6 or higher. The JPS_11_HOME variable must point to your oracle.jps file, for example, to:
```
oracle\Middleware\oracle_common\modules\oracle.jps_11.1.1
```
2. Open the file BTM_Central_Expanded/security_add_ons/jps_config_dir/jps-config.xml in a text editor and locate the following line:
```
<serviceInstance name="credstore" provider="credstoressp" location="./">
```
3. Change the value of the location attribute from ./ to the /config/fmwconfig/ directory under the WebLogic domain directory, for example:
```
<serviceInstance name="credstore" provider="credstoressp" location="C:/Oracle/Middleware/user_projects/domains/my_domain/config/fmwconfig/">
```
  The value of the location attribute must match the location of the %DOMAIN_HOME%\config\fmwconfig directory where you configured the policy store for your domain, in step 7.
4. In your command shell/window, navigate to the BTM_Central_Expanded/tools directory and issue the following command (replacing my_credential_name with the name you chose for this credential in step 5 d):
```
btmcli credStoreTool -createCred my_credential_name -credType is
```
  The CLI then prompts you for the Trusted Assertion Issuer and the Trusted Assertion Secret. The latter is masked with asterisks as you type.
5. Input the values for the Trusted Assertion Issuer and the Trusted Assertion Secret (and keep the command shell/window open for the next step).
  
  Use the values you chose in step 3.
  
  Note:
  If you prefer not to use the interactive mode, you can provide the issuer name and assertion secret by appending -credValue my_issuer:my_secret to the command line. However, using interactive mode is more secure because of the masking.
The credential for your assertion secret has now been created and added to the Oracle Wallet credential store.
In the same command shell/window, use the CLI to create a credential for your encryption key by issuing the following command (replacing my_credential_name with the name you chose for this credential in step 5 e):
```
btmcli credStoreTool -createCred my_credential_name -credType bin -genKey AES:128
```
This command creates a credential with the given name, generates an AES, 128-bit, random encryption key, and adds it to the Oracle Wallet credential store.
Retrieve the encryption key for use in configuring the other machines in your system by issuing the following command (replacing my_credential_name with the name of your credential):
```
btmcli credStoreTool -getCred my_credential_name -credType bin -showSecret
```
This command returns the string value of your encryption key. You will need to copy this string to the other machines in your system as you configure them.
Repeat the pertinent steps of this procedure for each central server, monitor, and observer for which you want to configure the assertion secret and encryption key using Oracle Wallet, but on repetition make the following changes:
- Skip steps 2 and 3 (you will use the same credential names and issuer name and issuer assertion secret values that you used on the first machine).
- Issue the following CLI command instead of the commands shown in steps 9 and 10 (replacing my_credential_name with the name of your credential, and my_encryption_key_string with the string you retrieved in step 10):
```
btmcli credStoreTool -createCred my_credential_name -credType bin -credValue my_encryption_key_string
```
  This command creates a credential with the given name and encryption key, and adds it to the Oracle Wallet credential store.

Configuring Security Using Extension Properties

This section pertains to central servers, monitors, and observers. It explains how to configure the assertion secret and encryption key using Business Transaction Management extension properties. You must repeat this procedure for each central server, monitor, and observer for which you want to configure the assertion secret and encryption key using extension properties.

There are two basic pieces to this security mechanism:

The first piece of the mechanism is a set of files in which you declare your extension properties and set their values.

The assertion secret and encryption key each require their own extension property file. If you are setting both, then you will require two extension property files. You place both extension property files in the same directory and protect the files by way of your operating system's file security mechanism. The application server in which the Business Transaction Management component is running must have permission to read the extension property files. For details, see Setting up the Extension Property Files.
The second piece of the mechanism is a Java system property (or for observers in .NET environments, a Windows environment variable) that points to the directory containing the extension property files. For details, see Setting up the Pointer.

Setting up the Extension Property Files

Create a directory to hold the extension property files.

You can use any name for the directory. (The remainder of this procedure assumes the directory name is ext_props.)
If you want to configure the assertion secret, complete the following substeps:
1. Inside the ext_props directory, create a file named com.amberpoint.SimpleIdentityAssertion.properties.
2. Add this line to the file:
```
TrustedIssuerOverriderClassName=com.amberpoint.wsclient.TrustedIssuerOverriderByExtProp
```
3. Then add this line to the file:
```
TrustedIssuerSecretOverride=MySecret
```
  where MySecret is your own secret string.
4. By default, the name of the issuer of the security assertion is AmberPoint. If you want to override this default issuer's name, add this third line to the file:
```
TrustedIssuerNameOverride=MyIssuerName
```
  where MyIssuerName is the name of the issuer of the security assertion.
5. Close the file.
If you want to configure the encryption key, complete the following substeps:
1. Inside the ext_props directory, create a file named com.amberpoint.security.encryption.properties.
2. Add these two lines to the file:
```
SystemDefaultAESKeyOverriderClassName=com.amberpoint.security.util.SystemDefaultAESKeyOverriderByExtProp

aes.defaultKeySize=128
```
3. Then add this line to the file:
```
aes.defaultKey=MyEncryptionKey
```
  where MyEncryptionKey is a base 64-encoded, AES, 128-bit key.
  
  After generating your base 64-encoded encryption key, you can copy and paste it in order to set the value of this property. If your key includes special characters, you should enclose it in double quotes, for example:
```
aes.defaultKey="oylJKoTGXTHasOYwtjwA7g=="
```
4. Close the file.
Using your operating system's file security mechanism, secure your extension property files (com.amberpoint.SimpleIdentityAssertion.properties and com.amberpoint.security.encryption.properties).

Ensure that the application server in which the Business Transaction Management component is running has permission to read the extension property files.

Setting up the Pointer

The procedure you use to set up the pointer to the extension property files depends on the type of server in which your Business Transaction Management component is deployed. This section describes how to set up the pointer for a:

Java application server (see Setting up the Pointer for a Java Application Server)
Oracle Enterprise Gateway server (see Setting up the Pointer for an Oracle Enterprise Gateway Server)
.NET Environment (see Setting up the Pointer for a .NET Environment)

Setting up the Pointer for a Java Application Server

Open your server's startup script in a text editor.
Create a Java system property named com.amberpoint.util.Extension.dir and set its value to the location of the extension property directory, for example:

For Windows systems:
```
set JAVA_OPTIONS=-Dcom.amberpoint.util.Extension.dir=C:\btm\ext_props %JAVA_OPTIONS%
```
For UNIX-like systems:
```
JAVA_OPTIONS=-Dcom.amberpoint.util.Extension.dir="/home/btm/ext_props" "${JAVA_OPTIONS}"
```
Note:
For WebLogic servers, add the line to the startWebLogic script after the call to setDomainEnv.

Setting up the Pointer for an Oracle Enterprise Gateway Server

Open OEG_HOME/system/conf/jvm.xml file in a text editor (OEG_HOME is the top-level directory in your Enterprise Gateway server installation).
Create a Java system property named com.amberpoint.util.Extension.dir and set its value to the location of the extension property directory.

Set this property by adding a <SystemProperty> element as a child of the <JVMSettings> element, for example:

For Windows systems:
```
<SystemProperty name="com.amberpoint.util.Extension.dir" value="C:\btm\ext_props"/>
```
For UNIX-like systems:
```
<SystemProperty name="com.amberpoint.util.Extension.dir" value="/home/btm/ext_props"/>
```

Setting up the Pointer for a .NET Environment

Create a Windows environment variable named com.amberpoint.util.Extension.dir and set its value to the location of the extension property directory, for example:
```
set = C:\btm\ext_props
```

Setting up a Secure Socket (SSL) for Observation Messages

Observers send observation messages to their associated monitor using the Oracle proprietary Observation Protocol (OP) over a socket connection. You can secure your observation messages by setting up a secure socket (SSL) for this communication channel. OP over SSL is known as Observation Protocol Secure (OPS).

This security mechanism provides your choice of server-only or mutual authentication, message integrity, and encryption of observation messages during transmission. Server authentication (authentication of the monitor to the observer) is provided by SSL. Client authentication (authentication of the observer to the monitor) is provided by OPS.

Server authentication requires a properly configured key store that is accessible to the monitor and a properly configured trust store that is accessible to the observers. Business Transaction Management provides built-in, preconfigured key and trust stores so as to minimize the setup required to enable SSL (a preconfigured server certificate is also provided for .NET-based observers). For demonstration purposes, and perhaps for development environments, using these built-in security stores might be adequate. But, in production environments, you should tighten security by providing your own security stores. Note that these security stores are separate from the network-level security stores used for HTTPS.

Note:

The client authentication mechanism is entirely built into OPS. You do not need, under any circumstances, to provide security stores for client authentication.

The default Observer Communication policy configures the observation message channel to use OPS/SSL and requires mutual authentication (with the built-in security stores being used for the server authentication). If you intend to use the built-in security stores rather than your own, and you intend to use only Java-based observers, then you can simply accept these default settings. In this case, you do not have to perform any further configuration.

If you want to use your own security stores for server authentication, use the following procedure as a guide. This procedure describes how to create and deploy your own key store and trust store containing a self-signed certificate.

Note:

If you intend to use the built-in security stores, but intend to use them with .NET-based observers, then skip to step 4 and deploy the preconfigured certificate to the machines that will host the .NET observers. You can find the preconfigured certificate at nanoagent\config\ssl\server.cer in the ZIP files containing the .NET-based observers.

Prepare a key store and trust store containing an appropriate certificate and private key:
1. Locate the keytool application in your JDK.
2. Generate a key store containing a certificate-private key pair.
  
  For example, the following keytool command generates a key store containing a certificate-private key pair in a file named “mykeystore.ks”. The alias for the certificate-private key pair is “myks”, the common name is “MyMonitor”, the algorithm is RSA, the password for accessing the certificate and private key is “mycertandprivkeypass”, and the password for accessing the key store is “mykeystorepass” (this command creates the file if it does not yet exist):
```
keytool -genkey -alias myks -dname "CN=MyMonitor" -keyalg RSA -keypass mycertandprivkeypass -storepass mykeystorepass -keystore mykeystore.ks
```
3. Export the certificate from your key store to an external file.
  
  For example, the following keytool command exports the certificate created in the previous example to a file named “mycertificate.cer”:
```
keytool -export -alias myks -storepass mykeystorepass -file mycertificate.cer -keystore mykeystore.ks
```
4. Import the certificate (without the associated private key) into the trust store.
  
  For example, the following keytool command imports the certificate created in the previous example into the trust store contained in the file “mytruststore.ks” (this command creates the trust store file if it does not yet exist).
```
keytool -import -v -trustcacerts -alias myks -file mycertificate.cer -keystore mytruststore.ks -keypass mycertandprivkeypass -storepass mykeystorepass
```
Deploy the key store to the machines that will host the monitors.

Copy the key store (for example, mykeystore.ks) either to the machines that will host the monitors or to a location accessible to the monitors by way of HTTP GET.
Deploy the trust store to the machines that will host your Java-based observers (ignore this step if you don't have Java-based observers).

Perform this task in one of these two ways:
- Copy the trust store (for example, mytruststore.ks) either to the machines that will host the observers or to a location accessible to the observers by way of HTTP GET.
- Copy the trust store (for example, mytruststore.ks) either to the machines that will host the monitors or to a location accessible to the monitors by way of HTTP GET. By using this second method, you can configure the monitor to automatically dispatch the trust store to the observers by enabling the Auto Dispatch Trust Store to Java Observers field when you configure the Observer Communication policy (see Applying an Observer Communication Policy).
Deploy the certificate to the machines that will host your .NET-based observers (ignore this step if you don't have .NET-based observers).

Using the Windows Certificate Import Wizard, import the certificate (for example, mycertificate.cer) to the Trusted Root Certification Authorities folder of the certificate store on the machines that will host the .NET-based observers.

Note:

The SSL connection for observation messages will not be operational until you have configured the Observer Communication policy with information about your security stores that corresponds with the choices you have made in this section. You will need this information handy when you configure the Observer Communication policy. See step 4 in Applying an Observer Communication Policy for details about the information you will need on hand at that point.