Configuration Parameters

When you install CDP for Oracle, a properties file named ProtectDB.properties is loaded at installed location . The properties contains the parameters that helps you configure the CDP client.

Important Notes

1. The values in the properties file are case-sensitive. yes is not YES, or Yes. tcp is not TCP or Tcp. Follow the example of the default properties file.

2. You can comment-out values using #. You may want to use comments to save settings when troubleshooting.

3. When editing parameters that use time values, you can use the following abbreviations:

   a. ms - Milliseconds. For example, 4500ms for 4.5 seconds.

   b. s - Seconds. For example, 30s for 30 seconds.

   c. m- Minutes. For example, 5m for 5 minutes.

   d. h - Hours. For example, 10h for 10 hours.

   e. d - Days. For example, 2d for 2 days.

If you do not include an abbreviation, the default time unit is used.

1. For any changes in the properties file to be effective, the loadProperties.sh (UNIX/Linux) or loadProperties.bat (Windows) file must be run. Depending on the platform, these files are placed at the following location:

   • On Unix/Linux: /lib/safenet/

   • On Windows: \bin\

2. CDP tries to perform cryptographic operations again in case it fails due to unavailability of Key Manager or heavy network load. CDP retries the cryptographic operations two more times after failure on first attempt.

3. Some other parameters are listed in the ProtectDB.properties file, which are not supported. These parameter are not mentioned in this list.

4. Remember that the properties file is NOT encrypted. Make sure that this file resides in a secure directory and has appropriate permissions so that it is readable only by the appropriate application or user.

Parameters

Version

The Version parameter indicates the version of the properties file and should not be modified.

NAE_IP.1

The NAE_IP.1 parameter specifies the IP address or hostname of the Key Manager. Specify multiple IP addresses/hostnames separated by colons (:) when load balancing is used. For example, 192.168.1.10:192.168.1.11:192.168.1.12. These servers must have the same value for the NAE_Port parameter. For IPv6, the IP address is to be specified in curly braces, such as {2002:0dc8:85k3:0000:0000:9a2e:0370:5221}. Also, combination of IPv4 and IPv6 addresses can be specified separated by colons(:) provided each IPv6 address is within {}. IPv6 is supported only for CipherTrust Manager.

NAE_Port

The NAE_Port parameter specifies the port of the Key Manager. The default port is 9000. Clients and servers must use the same port.

Protocol

The Protocol specifies the protocol used to communicate between the client and the Key Manager. Possible settings:

• tcp: This is the default setting.

• ssl: The ssl option supports TLSv1.0, TLSv1.1, and TLSv1.2. TLSv1.1, and TLSv1.2 are supported for JVM versions 1.6.0_121 and above.

  Use the following query to determine the JVM version being used in the Oracle database:

  SELECT dbms_java.get_ojvm_property(PROPSTRING=>'java.version') FROM dual;
  

  Key Exchange	Cipher	Keysize	Hash
  RSA	AES	256	SHA-1
  RSA	AES	128	SHA-1
  RSA	3DES	168	SHA-1

Use_Persistent_Connections

The Use_Persistent_Connections parameter enables the persistent connections functionality. Possible settings:

• yes: Enables the feature. The client establishes persistent connections with the NAE servers. This is the default value.

• no: Disables the feature. A new connection is made for each connection request. The connection is closed as soon as the client receives the server response.

Size_of_Connection_Pool

The Size_of_Connection_Pool parameter specifies the total number of client-server connections that the configuration could possibly allow. (Not what actually exists at a given moment.) Possible setting:

Any positive integer. The default is 300.

Connections in the pool can be active or waiting, TCP or SSL. A connection is created as needed, and the pool scales as needed. The pool starts at size 0, and can grow to the value set here. Once the pool is full, new connection requests must wait for an existing connection to close.

Connection pooling is configured on a per-client basis. The size of the pool applies to each client, it is not a total value for a Key Manager or for a load balancing group. If there are multiple clients running on the same machine, separate connection pools are maintained for each client.

Connection_Idle_Timeout

The Connection_Idle_Timeout parameter specifies the amount of time connections in the connection pool can remain idle before the client closes them. Possible setting:

Any positive integer. The default is 600000ms (10 min).

There are two different connection timeout values: one on the Key Manager, and one in the properties file. The value of the timeout in the properties file must be less than what is set on the server. This lets the client control when idle connections are closed. Otherwise, the client can maintain a connection that is closed on the server side, which can lead to error.

Unreachable_Server_Retry_Period

The Unreachable_Server_Retry_Period parameter specifies the amount of time the client will spend attempting to establish a connection to a load balancing group. An error is returned after the specified period if no server in the group is reachable. If logging is enabled, error messages are written to the log file. Possible settings:

• -1: This is the infinite retry interval. The client keeps trying to connect to a server until a connection is established. This setting is not compatible with multi-tier load balancing because the load balancer will never switch tiers.

• A positive integer: If multi-tier load balancing is enabled then set this value between 1 and twice the value of the Connection_Retry_Interval. The default is 60000ms.

Maximum_Server_Retry_Period

The Maximum_Server_Retry_Period parameter specifies the total amount of time that the client will spend trying to make connections to any server on any tier. This value is only used when multi-tiered load balancing is enabled. Possible settings:

• -1: The connection manager will try every server on every tier until one answers.

• 0: The feature is disabled; there is no overall limit.

• A positive value: The connection manager will try to make connections for at least the duration set in Maximum_Server_Retry_Period and will return an error if no connection can be made on the tier in use when the try period expires. The default value is 600000 (10 minutes).

Connection_Timeout

The Connection_Timeout parameter specifies how long the client waits for the TCP connect function before timing out. Possible settings:

• 0: Disables this setting. The client uses the operating system’s connect timeout.

• Any positive integer: The default is 1m (1 minute).

Setting this parameter a few hundred ms less than the operating system’s connection timeout makes connection attempts to a downed server fail faster, and failover happens sooner. If a connection cannot be made before the timeout expires, the server is marked as down and taken out of the rotation.

If the client is working with many versions of a key, do not set the Connection_Timeout parameter too low. Otherwise the client connection may close before the operation is complete.

Connection_Read_Timeout

The Connection_Read_Timeout parameter controls how long the client waits when reading data from a Key Manager before determining that it is down. Requests should only time out if the Key Manager is physically down (e.g. powered off, or not responding because of misconfiguration). Possible settings:

• 0: Disables this setting. The client waits indefinitely until the Key Manager can be reached. Requests remain outstanding until the client’s request is successfully satisfied.

• Any positive integer: The default is 7000ms.

The purpose of this parameter is to control how the client should react when the Key Manager is down. If it should time out eventually and return an error back to the application, then set this parameter to an appropriate number of milliseconds to allow requests to complete in high load and high latency situations.

Connection_Retry_Interval

The Connection_Retry_Interval parameter determines how long the client waits before trying to reconnect to a disabled server. If one of the Key Managers in a load balanced configuration is not reachable, the client assumes that the server is down, and then waits for the specified time period before trying to connect to it again. Possible settings:

• 0: This is the infinite retry interval. The disabled server will never be brought back into use.

• Any positive integer: The default value is 60000 ms (1 minute).

Client_Cert_Alias

The Client_Cert_Alias parameter specifies which client certificate to send to the Key Manager when client certificate authentication is enabled. If there are multiple client certificates in a keystore, then the client certificate to be sent to the NAE Server during the SSL handshake can be specified. If no client certificate is specified, the first certificate in the keystore is sent to the NAE Server. Possible setting:

The file name: Client certificates must be PEM encoded.

If Client_Cert_Alias is specified, then Client_Cert_Passphrase must also be specified; otherwise, Key_Store_Password is used.

Client_Cert_Passphrase

The Client_Cert_Passphrase parameter specifies the passphrase needed to access the client certificate listed in Client_Cert_Alias. If a value is specified for Client_Cert_Alias, then a value should also be specified for Client_Cert_Passphrase; otherwise, Key_Store_Password is used. Possible setting:

The passphrase associated with the private key.

Key_Store_Location

The Key_Store_Location parameter specifies the location of the Java keystore that contains the client certificate. Possible setting:

The path and file name: The path can be absolute or relative to the application. Don’t use quotes even if the path contains spaces. On Windows, the keystore path must include double slash. For example, C:\\app\\user\\product\\11.1.0\\db_1\\javavm\\lib\\security\\store.

Key_Store_Password

The Key_Store_Password parameter specifies the keystore password. Possible setting:

The passphrase associated with the keystore.

Cluster_Synchronization_Delay

The Cluster_Synchronization_Delay parameter specifies how long the client will wait before assuming that key changes have been synchronized throughout a cluster. After creating, cloning, importing, or modifying a key, the client will continue to use the same Key Manager appliance until the end of this delay period. Possible settings:

• 0: Disables the function.

• Any positive integer: The default is 100s. A higher setting may be needed for large clusters.

For example, the client sets Cluster_Synchronization_Delay to 100s and sends a key creation request to appliance A, which is part of a cluster. Appliance A creates the key and automatically synchronizes with rest of the cluster. The client will use only appliance A for 100 seconds - enough time for the cluster synchronization to complete. After this time period, the client will use other cluster members as before.

Symmetric_Key_Cache_Enabled

The Symmetric_Key_Cache_Enabled parameter determines if the symmetric key caching feature is enabled. Only symmetric keys can be cached Possible settings:

• no: Key caching is disabled. Remote encryption (encryption performed on the Key Manager) is available as normal.

• yes: Key caching is enabled. Protocol must be set to ssl. (And ssl must be configured.)

• tcp_ok: Key caching is enabled over both tcp and ssl connections.

Symmetric_Key_Cache_Expiry

The Symmetric_Key_Cache_Expiry parameter determines the minimum amount of time that a key will remain in the client key cache. Possible settings:

• 0: This is the infinite timeout setting. Keys are never purged from the client cache.

• A positive integer: At the end of this interval, the key will be purged from the cache the next time the library is called. The default value is 43200 seconds (12 hours).

Local_Cipher_Cache_Expiry

The Local_Cipher_Cache_Expiry parameter determines the minimum amount of time after which the cipher initialized with the key expires and is reinitialized with the cached key. Possible settings:

• -1: This is the infinite timeout setting. Cipher is never purged from the client cache.

• 0: The cipher will expire after every operation.

• A positive integer: At the end of this interval, the cipher will be purged from the cache the next time the library is called. Default value is set at 43200000 ms (12 hours).

The Local_Cipher_Cache_Expiry time should be less than or equal to the Symmetric_Key_Cache_Expiry time and Symmetric_Key_Cache_Enabled parameter should be set as yes or tcp_ok.

Local_Crypto_Provider

The Local_Crypto_Provider parameter specifies the name of the JCE provider that will perform local cryptography if symmetric key caching is enabled. The default value is SunJCE or IBMJCE, depending on JVM. Possible setting:

A JCE Provider currently enabled on the client.

Persistent_Cache_Enabled

Enables and disables the persistent key caching feature. To enable this feature, you must also enable either symmetric key caching. By default, this parameter is disabled. Possible values are:

• yes: The feature is enabled.
• no: The feature is disabled.

Persistent_Cache_Expiry_Keys

The time after which a key will expire from the persistent cache. This value must be greater than zero. The default value is 43200 seconds (12 hours).

Persistent_Cache_Directory

The location of the persistent cache file. The directory must already exist. The path can be absolute or relative to your application. Don’t use quotes, even if the path contains spaces.

Persistent_Cache_Max_Size

The maximum number of keys that can be stored in the persistent cache. The default value is 100 keys. Possible values are:

• Any positive integer: the maximum number of keys to be stored in persistent cache.

• -1: allows infinite number of keys to be stored in persistent cache.

FIPS_Mode

The FIPS_Mode parameter is used to enable or disable FIPS mode. To use FIPS local encryption Symmetric_Key_Cache_Enabled must be set to "yes" or "tcp_ok", and FIPS_Mode must be set to "on". Possible settings:

• on: Disables the FIPS mode.

• off: Enables the FIPS mode. This is the default setting.

Log_Level

The Log_Level parameter determines the level of logging performed by the client. Possible settings:

• NONE: Disables client logging. It is recommended not to disable logging.

• LOW: Only error messages are logged.

• MEDIUM: The client logs error messages and warnings. This is the default setting.

• HIGH: The client logs error messages, warnings, and informational messages. This level generates a very large number of entries and is usually reserved for debugging.

The user running the client application must have permission to write to the log file, and to create new files in the directory where the log files are created.

Log_File

The Log_File parameter specifies a name (and possibly a path) for the log file. Possible settings:

• The file name: The log will be created in the same directory as the client. The default value is Logfile.txt.

• The path and file name: The path can be absolute or relative to the application. Don’t use quotes even if the path contains spaces. On Windows, the log file path must include double slash. For example, C:\\logs\\logfile.txt.

Log_Rotation

The Log_Rotation parameter specifies whether logs are rotated daily or once they reach a certain size. Possible settings:

• Daily: Rotates logs daily. This is the default setting.

• Size: Rotates logs when the reach the size specified in Log_Size_Limit.

Log_GMT

The Log_GMT parameter specifies whether timestamp should be formatted in GMT or not. Possible settings:

• yes: Timestamps will be formatted in GMT.

• no: Timestamps will not be formatted in GMT. This is the default setting.

Log_Size_Limit

The Log_Size_Limit parameter specifies how large log files can be before they are rotated. This parameter is used only when Log_Rotation is set to Size. Possible settings:

Any positive integer: The default unit is bytes. Use the suffix k (or K) for kilobytes and m (or M) for megabytes. The default value is 100k.

Key_non_exportable_policy

The protocol used to perform the crypto operation remotely when local cache is enabled and the key is non-exportable. Possibel settings:

• yes: Enables the feature. The non exportable key in local caching mode can perform the crypto operation remotely.

• no: Disables the feature. The feature is disabled by default. No crypto operation could be performed as the key is non exportable.

SysLog_IP

The SysLog_IP parameter specifies the IP address of the syslog server where the log messages are to be directed. CDP sends the messages to configured port of syslog server over UDP. Also the Ingrian user should have the following permission:

call dbms_java.grant_permission( 'INGRIAN', 'SYS:java.net.SocketPermission','localhost:1024-', 'listen');

Possible setting:

IP address: The IP address of the syslog server.

SysLog_Port

The SysLog_Port parameter specifies the port number used to connect CDP for Oracle to the Syslog server. Possible setting:

Port number: The port number of the syslog server. The default value is 514.