BDT Properties File
The unified BDT package includes the bdt.properties file that is saved at BDT_HOME/conf/bdt.properties after installation.
To perform encryption using the default crypto library, it is mandatory to configure the bdt.properties file. Use -f option to configure the minimum required parameters from the command line using the following command:
./bdt.sh -f
The BDT configuration parameters are classified as follows:
Network Configuration Parameters
| Parameter | Default Value | Description |
|---|---|---|
| NAE_IP.1 | No default | The NAE_IP.1 parameter specifies the IP address of the Key Manager and multiple IP addresses separated by colons (:) when load balancing is used.For example, 192.168.1.10:192.168.1.11:192.168.1.12 servers must have the same value for the NAE_Port.For IPv6, the IP address must be specified in curly braces, such as {2002:0dc8:85k3:0000:0000:9a2e:0370:5221}.Combination of IPv4 and IPv6 addresses can be separated by colons (:) provided each IPv6 address must be within curly braces. Refer to Limitations for details. |
| NAE_Port | 9000 | The NAE_Port parameter specifies the port of the Key Manager.Note: Both clients and servers must use the same port. |
| Protocol | tcp | The Protocol parameter is used to communicate between BDT and the Key Manager.Possible settings are: • tcp • ssl The ssl option uses TLSv1.0, TLSv1.1, and TLSv1.2. To establish SSL connections between BDT and Key Manager, at least one of TLSv1.0, TLSv1.1, and TLSv1.2 must be enabled on the servers. Both BDT and the Key Manager must use the same protocol. If the Key Managers are executing SSL requests, and BDT is not sending SSL requests, problems will occur. Note: It is recommended to gradually increase security after confirming connectivity between BDT and the Key Manager. Once a TCP connection is established between BDT and the Key Manager, it is safe to move on to SSL. Initially configuring BDT under the most stringent security constraints can complicate troubleshooting. |
Connection Configuration Parameters
| Parameter | Default Value | Description |
|---|---|---|
| Verify_SSL_Certificate | no | The Verify_SSL_Certificate parameter directs BDT to verify the IP address or hostname against the Subject Common Name (CN) or the Subject Alternative Name (SAN) in the server certificate presented by the Key Manager during authentication. SSL must be configured to use this feature.Possible settings are: • yes: Enables the feature. • no: Disables the feature. The feature is disabled by default. |
| SSL_Handshake_Timeout | No default | The SSL_Handshake_Timeout parameter allocates time for the SSL handshake. SSL must be configured to use this feature. Set to any positive integer. |
| Use_Persistent_Connections | yes | The Use_Persistent_Connections parameter enables the persistent connections functionality.Possible settings are: • yes: Enables the feature. BDT establishes persistent connections with the Key Manager. • no: Disables the feature. A new connection is made for each connection request. The connection is closed as soon as BDT receives the server response. |
| Size_of_Connection_Pool | 300 | The Size_of_Connection_Pool parameter specifies the total number of client-server connections that the configuration could possibly allow. It does not specify the connections that actually exist at a given moment.Possible setting is: • Any positive integer: Connections in the pool can be active or waiting, TCP or SSL. A connection is created 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. |
| Load_Balancing_Algorithm | round-robin | The Load_Balancing_Algorithm parameter is used to determine how BDT selects a Key Manager (server) from a load balancing group.Possible settings are: • round-robin: Directs the connection to the next server in the load balancing group. This is the default. • random: Directs the connection to a randomly selected member of the load balancing group. |
| Connection_Idle_Timeout | 600000ms (10 min) | 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 is: • Any positive integer: Note: 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 | 60000ms | 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 are: • -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 as the load balancer will never switch tiers. • Any positive integer: If multi-tier load balancing is enabled, set this value between 1 and twice the value of the Connection_Retry_Interval. |
| Maximum_Server_Retry_Period | 0 | The Maximum_Server_Retry_Period parameter specifies the total amount of time that BDT (client) will spend trying to make connections to any Key Manager (server ) on any tier. This value is used when multi-tiered load balancing is enabled.Possible settings are: • -1: BDT will try every server on every tier until any response is received. • 0: The default value is set to 0; there is no overall limit. Setting value to 0 disables this feature. • Any positive integer: BDT 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. |
| Connection_Timeout | 1 minute | The Connection_Timeout parameter specifies how long BDT (client) waits for the TCP connection function before timeout.Possible settings are: • 0: Disables this setting. The client uses the operating system’s connection timeout. • Any positive integer: Setting this parameter a few hundred ms less than the operating system’s connection timeout makes connection attempts to a downed Key Manager (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. Note: 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 | 7000ms | The Connection_Read_Timeout parameter controls how long BDT(client) waits when reading data from the Key Manager before determining that it is down. Requests should only timeout if the Key Manager is physically down (e.g. powered off, or not responding because of misconfiguration).Possible settings are: • 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 purpose of this parameter is to control how the client should react when the Key Manager is down. If it should timeout eventually and return an error back to the application, set this parameter to an appropriate number of milliseconds to allow requests to complete in high load and high latency situations. |
| Connection_Retry_Interval | 60000ms (1 minute) | The Connection_Retry_Interval parameter determines how long BDT (client) waits before trying to reconnect to a disabled Key Manager (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 again.Possible settings are: • 0: This is the infinite retry interval. The disabled server will never be brought back into use. • Any positive integer: If the server or network is under a high load, a connection timeout could occur for a running sever. If your Connection_Retry_Interval is not long enough, another connection attempt will be made to the busy server - adding to its already high load. |
SSL/TLS Configuration Parameters
Refer to Configure SSL on CipherTrust Manager for NAE Interface for instructions on how to configure SSL.
| Parameter | Default Value | Description |
|---|---|---|
| Client_Cert_Alias | the first certificate in the keystore | The client certificate sent to the Key Manager when client certificate authentication is enabled. If you have multiple client certificates in a keystore, you might want to specify which client certificate is sent to the Key Manager during the SSL handshake. If you do not specify a client certificate in the properties file, the first certificate in the keystore is sent to the Key Manager. |
| Client_Cert_Passphrase | the keystore password | The passphrase needed to access the client certificate listed in the Client_Cert_Alias.If you specify a value for the Client_Cert_Alias, you should also specify a value for the Client_Cert_Passphrase, otherwise the keystore password is used. |
| Key_Store_Location | No default | The Key_Store_Location parameter specifies the location of the Java keystore that contains the client certificate. The path can be absolute or relative to your application. Don’t use quotes, even if the path contains spaces. |
| Key_Store_Password | No default | The Key_Store_Password parameter specifies the password to unlock the keystore. |
Note
Remember that the properties file is NOT encrypted. Make sure this file has appropriate permissions so that it is readable only by the appropriate user.
Client Key Caching Parameters
| Parameter | Default Value | Description |
|---|---|---|
| Symmetric_Key_Cache_Enabled | no | The Symmetric_Key_Cache_Enabled parameter determines if the symmetric key caching feature is enabled. Symmetric keys can be cached.Possible settings are: • no: Key caching for symmetric keys is disabled. Crypto operations for symmetric key are performed on the Key Manager. • yes: Key caching for symmetric keys is enabled. Protocol must be set to ssl (and ssl must be configured).• tcp_ok: Key caching for symmetric keys is enabled over both tcp and ssl connections. |
| Symmetric_Key_Cache_Expiry | 43200s (12 hours) | The Symmetric_Key_Cache_Expiry parameter specifies the minimum amount of time that a key will remain in BDT (client) key cache.Possible settings are: • 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). |
| Symmetric_Key_Cache_AutoRefresh_Interval | 0 | The Symmetric_Key_Cache_AutoRefresh_Interval parameter specifies the time after which the cached key becomes eligible for refresh. The actual refresh operation occurs only when a cached key is queried from the cache before the key expires. It can be specified in any time unit; the default is seconds.If the eligible key is not queried from the symmetric cache, it is removed from the cache after its expiry. This parameter is applicable only if the symmetric key cache is enabled. Possible settings are: • 0: Auto refresh feature is disabled. • Any positive integer: The time after which the cached key is eligible for refresh. |
| Local_Cipher_Cache_Expiry | 0 | 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 are: • -1: This is the infinite timeout setting. Cipher is never purged from the client cache. • 0: The cipher will expire after every operation. • Any positive integer: At the end of this interval, the cipher will be purged from the cache the next time the library is called. Note: 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 | SunJCE or IBMJCE (depends on JVM) | The Local_Crypto_Provider parameter specifies the name of the JCE provider that will perform local cryptography if symmetric key caching is enabled. For example, SunJCE provider is the default on Sun JVM. |
| Key_non_exportable_policy | no | The Key_non_exportable_policy parameter is used to perform the crypto operations remotely when symmetric cache is enabled, and the key is non exportable. By default, this parameter is disabled.Possible settings are: • yes: Enables the feature. • no: Disables the feature. |
