The Parameters

Once you have installed CipherTrust Vaulted Tokenization, you can modify the properties file. The parameters listed in the file are detailed below.

Note

The properties file has many parameters, such as Client_Cert_Passphrase and Key_Store_Password that stores password. For such parameters, it is recommended to use the Passphrase utility or the IngrianProvider.obfuscate() API to obfuscate passwords for added security. Also, these passwords should not be used as cryptographic key names for the crypto operations.

Version

version of the properties file and should not be modified.

NAE_IP.1

the IP address or the Hostname of the Key Manager. When using load balancing , specify multiple IP addresses/Hostnames separated by colons (:). 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 used separated by colons (:) provided each IPv6 address is within {}.

Note

IPv6 is supported for CipherTrust Manager.

It is recommended to use the hostname in NAE_IP.1 parameter. To use the hostname, map the Key Manager's IP with Hostname in the system's host file. Also, a hostname can have multiple IP addresses.

When hostnames are specified in the NAE_IP.1 parameter and each hostname have multiple IPs:

• The IPs at a hostname are randomly selected when new connection to Key Manager is requested. And if a particular IP is not available, it is marked as down for the duration = (the number of IPs returned by DNS resolution when the application first starts * value of Connection_Timeout).

  The Size_of_Connection_Pool is maintained at the hostname level and not on the number of IPs for the hostname.

NAE_Port

The port on which the client will communicate with the server. Your client must use the same port as the server. The default is 9000.

KMIP_Port

The port on which the client will communicate with the server. Your client must use the same port as the server. The default is 5696.

Key_non_exportable_policy

The parameter used to perform the crypto operations remotely when symmetric/asymmetric cache is enabled and the key is non exportable. By default, this parameter is disabled. Set to either yes or no.

• yes - Enables the feature.

• no - Disables the feature.

Log_MaxBackupIndex

Maximum number of log backup files to be stored on the disk if log rotation is enabled.

• -1 - Allows infinite backup files storage on disk. This feature is the default value.

• 0 - Allows maximum 7 backup files storage on disk.

• Any positive integer - Allows as much number of backup files storage on disk as mentioned in the value.

Protocol

The protocol used to communicate between the client and the Key Manager. Clients and servers must use the same protocol. Can be either tcp or ssl. The ssl option uses TLSv1.2.

Note

To use TLSv1.2 with Java 8, enable one of the following SSL Ciphers on KeySecure Classic Management Console (Security >> Advanced Security >> SSL):

Key Exchange- RSA, Cipher-AES, Keysize-128, and Hash-SHA-1
Key Exchange- RSA, Cipher-AES, Keysize-256, and Hash-SHA-1

It is recommended to use the SSL Cipher with strong key exchange.

Note

If you are using the Key Manager NAE, you should gradually increase security after confirming connectivity between the client and the Key Manager. Once you have established a TCP connection between the client and server, it is safe to move on to SSL. Initially configuring a client under the most stringent security constraints can complicate troubleshooting. You can’t gradually secure the KMIP port, so this approach is not an option on Key Manager.

Verify_SSL_Certificate

Directs CipherTrust Vaulted Tokenization 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. Set to either yes or no.

• yes - Enables the feature. The server certificate must include either the hostname or the IP address in the CN or SAN field. If the hostname is used, the hostname must be reachable by the client.

• no - Disables the feature. The feature is disabled by default.

  

  Note

  The Verify_SSL_Certificate parameter does not work with Java 17.

SSL_Handshake_Timeout

Allocates time for the SSL handshake. SSL must be configured to use this feature. Set to any positive integer.

Use_Persistent_Connections

Enables the persistent connections functionality. Set to either yes or no.

• yes - Enables the feature. The client persists the connections established with the Key Manager. 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 total number of client-server connections that your configuration could possibly allow. (Not what actually exists at a given moment.) Set to any positive integer. The default value 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 for a client session on per server basis. The size of the pool applies to each client-session for a server, it is not a total value for a Key Manager or for a load balancing group.

Regardless of your setting, the pool will always have at least 2 connections per NAE Server. The larger your connection pool, the less likely your client will get a failed connection request.

Load_Balancing_Algorithm

The algorithm used to determine how the client selects a Key Manager from a load balancing group.

Possible Settings:

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

The amount of time connections in the connection pool can remain idle before the client closes them. Set to any positive integer. The default is 600000ms (10 min).

Note

There are two different connection idle timeout values: one on the KeySecure Classic, and one set by this property. The value of this property 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 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. Set to -1 or to any positive integer.

• -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.

• 0 - If multi-tier load balancing is enabled and Unreachable_Server_Retry_Period is set to 0, the client will not try to connect to a server on the particular load balancer in case all the servers are down in that particular load balancer. The client will move on to the next load balancer, if available, to establish connection.

• 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 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. Set to -1, 0, or any positive integer.

• -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.

Connection_Timeout

How long the client will wait for the connection call to return a value. If a connection cannot be established before the timeout expires, then the server is marked as down and is taken out of rotation until the Connection_Retry_Interval has passed.

Possible Settings:

1m (default) - The client will wait 1 minute.

0 - The client will not force a timeout. The waiting period set by the client’s OS still applies; the client will wait as long as the TCP stack normally waits for a connection.

Any positive integer.

You can use abbreviations (ms, s, m, h, d) to specify the time units (milliseconds, seconds, minutes, hours, days). If you do not include an abbreviation, the default time unit (milliseconds) is used.

If your application is time-sensitive, set this parameter a few hundred millisecondsless than your OS’s connection timeout. This will make connections to a down server fail more quickly, in which case failover will occur sooner.

Connection_Read_Timeout

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). Set to 0 or any positive integer.

• 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 you want the client to react when the Key Manager is down. If you want it to time out eventually and return an error back to your application, then you should set this value to an appropriate number of milliseconds to allow for requests to complete in high load and high latency situations.

Connection_Retry_Interval

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. Set to 0 or any positive integer.

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

• Any positive integer - The default value is 600000ms (10 minutes).

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.

Client_Cert_Alias

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, either in the properties file or programmatically, the first certificate in the keystore is sent to the Key Manager.

Client_Cert_Passphrase

The passphrase needed to access the client certificate listed in 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.

Note

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.

Key_Store_Location

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

The keystore password.

Note

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.

Cluster_Synchronization_Delay

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. Set to either 0 or any positive integer.

• 0 - disables the function.

• Any positive integer. - The default is 170s. You may want a higher setting for large clusters.

For example, the client sets Cluster_Synchronization_Delay to 170s 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 170 seconds - enough time for the cluster synchronization to complete. After this time period, the client will use other cluster members as before.

Note

The parameters to set the cluster synchronization in KeySecure Classic are cluster retry interval and cluster retry attempts with default values 40 seconds and 4 respectively. These parameters are configurable in KeySecure Classic, so the value to be set for the Cluster_Synchronization_Delay parameter depends on the values set for the KeySecure Classic.

The value to be set for Cluster_Synchronization_Delay parameter should be greater than value of (cluster retry attempts) times (cluster retry interval).

Symmetric_Key_Cache_Enabled

Determines if the symmetric key caching feature is enabled. Symmetric keys can be cached. Set to either no, yes, or tcp_ok.

• 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.

Note

Keys are stored in the key cache. Cache are created per client, per session.

Asymmetric_Key_Cache_Enabled

Determines if the asymmetric key caching feature is enabled. Asymmetric keys can be cached. Set to either no, yes, or tcp_ok.

• no - Key caching for asymmetric keys is disabled. Crypto operations for asymmetric key are performed on the Key Manager).

• yes - Key caching for asymmetric keys is enabled. Protocol must be set to ssl. (And ssl must be configured.)

• tcp_ok - Key caching for asymmetric keys is enabled over both tcp and ssl connections.

Note

Keys are stored in the key cache. Cache are created per client, per session.

Symmetric_Key_Cache_Expiry

The minimum amount of time that a key will remain in the client key cache. The cache holds both symmetric and asymmetric keys. The name of this property retains the word symmetric for backwards compatibility. Set to either 0 or any positive integer.

• 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

It is 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. By default, this parameter is set to 0 (disabled). Possible values 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

The time after which the local cipher initialized with cached keys expires and then reinitialized with cached keys. This parameter is applicable only if the symmetric key cache is enabled. By default this parameter is set to 0. The default unit is milliseconds. Possible values are:

• -1

• 0

• A positive integer

The following table shows the possible configurations of Symmetric_Key_Cache_AutoRefresh_Interval, Symmetric_Key_Cache_Expiry, and Local_Cipher_Cache_Expiry and their impact on the local cipher expiry time.

Local_Crypto_Provider

The name of the provider that will perform local cryptography if symmetric key caching is enabled.

Persistent_Cache_Enabled

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

• yes - The feature is enabled.

• no - The feature is disabled.

Note

Persistent key caching feature is not supported for tokenization operations.

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.

Ignore_DNS_Resolution_Failure

To ignore DNS Resolution failure at the time of Initialization, set Ignore_DNS_Resolution_Failure to true. This means if DNS resolution fails then initialization does not fail and CipherTrust Vaulted Tokenization fetches the key from the persistent cache, if enabled.

Possible settings:

true - The feature is enabled. So, even on DNS resolution failure or invalid IP, the initialization does not fail.

false - The feature is disabled. On DNS resolution failure the initialization fails. This is the recommended setting.

CA_File

The CA certificate that was used to sign the server certificate presented by the NAE Server to the client. The path specified for this parameter can be absolute or relative to your application. Do not use quotes, even if the path contains spaces.

Because all Key Manager servers in a clustered environment must have an identical configuration, all servers in the cluster use the same server certificate. As such, you need to point to only one CA certificate in the CA_File system parameter. If you do not supply the CA certificate that was used to sign the server certificate used by the Key Manager servers, your client applications cannot establish SSL connections with any of the servers in the cluster.

Cert_File

The parameter stores the path and file name of the client certificate. This is used only when your SSL configuration requires clients to provide a client certificate to authenticate to the Key Manager servers. The path specified for this parameter can be absolute or relative to your application. Don’t use quotes, even if the path contains spaces. Client certificates must be PEM-encoded.

Note

If this value is set, the certificate and private key must be present, even if Key Manager is not configured to request a client certificate.

Key_File

The private key associated with the client certificate specified in the specified in the Cert_File parameter. The path specified for this parameter can be absolute or relative to your application. Do not use quotes, even if the path contains spaces. The client private key must be in PEM-encoded PKCS#12 format.

Note

If this value is set, the certificate and private key must be present, even if Key Manager is not configured to request a client certificate.

Passphrase

Passphrase to unlock the client private key specified in the Key_File parameter. This value is required when client certificate authentication is enabled.

Note

Since the value is in the clear text, this properties file must have its permission restricted so that it can be read only by the applications that are to have legitimate access to it.

Credentials_Encrypted

This parameter indicates that the Key Manager username and password are encrypted using PassphraseUtility. The default value is set to no but if the value is set to 'yes' and an invalid obfuscated string is set then the application throws an error.

Passphrase_Encrypted

This parameter indicates that specified parameters Client_Cert_Alias and Client_Cert_Passphrase are encrypted using PassphraseUtility. Possible values are yes and no. The default value is set to no.

KMIP_Private_Suffix

Use this parameter to re-set the text string added as suffix to the private key in the KMIP public/private key pair. This suffix string is managed to keep the names unique as required by the KMIP specification. By default, KMIP key pairs are assigned the suffixes “Public” or “Private” to maintain uniqueness.

KMIP_Public_Suffix

Use this parameter to re-set the text string added as suffix to the public key in the KMIP public/private key pair. This suffix string is managed to keep the names unique as required by the KMIP specification. By default, KMIP key pairs are assigned the suffixes “Public” or “Private” to maintain uniqueness.

Log_Level

To decide the level of log messages, set the Log_Level parameter to one of the values shown in the following table:

Log_File

To specify the log file name, set the Log_File parameter with the log file name and path. The path can be absolute or relative to your application. Do not use quotes, even if the path contains spaces.

Note

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_Rotation

To specify how frequently the log file is rotated based on time or log size, set the Log_Rotation parameter to one of the values shown in the following table:

Log_Size_Limit

To specify how large log files are before they are rotated, set the Log_Size_Limit parameter. This parameter is used only when Log_Rotation is set to Size. Set the value to any positive integer. The default unit is bytes. You can use the suffix k or K for kilobytes and m or M for megabytes. The default value is 100k.

Log_GMT

For logging on local machine, specify if timestamps include the Greenwich Mean Time (GMT) offset by setting the Log_GMT parameter. The following settings are available:

When enabled, timestamps include the deviation from GMT, as shown below.

[10/04/11 14:21:12:194 GMT- 700]

SysLog_IP

To enable logging on SysLog Server, set the SysLog_IP parameter to the IP address of the SysLog server on which logs are to be saved.

Note

Either SysLog_IP or Log_File parameter will be used for logging. If both the values are specified, SysLog_IP will have first priority for logging.

Note

IPv6 is not supported for Syslog Server.

SysLog_Port

To enable logging on SysLog Server, set the SysLog_Port parameter to the port used to connect the client to the SysLog server.

SysLog_Protocol

To enable logging on SysLog Server, set the SysLog_Protocol parameter used for communication between the client and the SysLog server. The possible options are:

• TCP

• UDP

• SSL

Note

To enable logging on SysLog Server, it is mandatory to provide correct values for all the three parameters. Additionally, to use the SSL protocol, SysLog_SSLKeystore and SysLog_SSLKeystorePassword parameters are required.

SysLog_SSLKeystore

To enable SSL protocol for logging on SysLog Server, set the SysLog_SSLKeystore parameter for the location of the keystore/truststore containing SysLog server certificates and CA certificates. By default, keystore cacert from JRE_HOME/lib/security will be referred in case user does not specify the SysLog_SSLKeystore parameter and uses SSL in the SysLog_Protocol parameter.

SysLog_SSLKeystorePassword

To enable SSL protocol for logging on SysLog Server, set the SysLog_SSLKeystorePassword parameter for the password of keystore/truststore containing SysLog server certificates and CA certificates. In case user does not specify the SysLog_SSLKeystore parameter, default password of keystore cacert is used.

Note

If client side authentication is used for establishing SSL connection to the SysLog Server, the passphrase of the private key associated with the client certificate must be same as the one specified in the SysLog_SSLKeystorePassword parameter.