Configuring Properties File

This section explains how to configure the CADP_PKCS11.properties file. This properties file defines, among other things, the IP address, port number, and protocol of the CipherTrust Manager to which the clients connect.

This chapter covers the following topics:

• Editing the Properties File

• Modifying Parameters

Editing the Properties File

The values in the properties file are case-sensitive. Follow the example of the default properties file.

You can configure the value of NAE_IP parameter by following the instructions:

• For single IP,

  NAE_IP = 10.0.0.2

• For load balancing,

  NAE_IP=10.0.0.2:10.0.0.3:10.0.0.4

• For Multi-tier,

  NAE_IP.1=10.0.0.2:10.0.0.3:10.0.0.4

  NAE_IP.2=10.0.0.5:10.0.0.6:10.0.0.7

  NAE_IP.3=10.0.0.8:10.0.0.9:10.0.0.10

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

• ms: milliseconds (for example, 4500ms for 4.5 seconds)

• s: seconds (for example, 30s for 30 seconds)

• m: minutes (for example, 5m for 5 minutes)

• h: hours (for example, 10h for 10 hours)

• d: days (for example, 2d for 2 days)

For most time-related values, the default time unit is set to milliseconds.

For Symmetric_Key_Cache_Expiry and Persistent_Cache_Expiry_Keys, the default time unit is set to seconds.

Modifying Parameters

Once you install the client software, you can customize it to meet the needs of your environment by modifying the CADP_PKCS11.properties file.

The content of the file, including the settings but excluding comments, is shown below:

Version=3.1
NAE_IP=
NAE_Port=9000
Protocol=tcp
verify_ssl_certificate=no
Use_Persistent_Connections=yes
Size_of_Connection_Pool=300
Connection_Timeout=30000
Connection_Read_Timeout=30000
Connection_Idle_Timeout=600000
Connection_Retry_Interval=600000
Cluster_Synchronization_Delay=100
CA_File=
Cert_File=
Key_File=
Passphrase=
Passphrase_Encrypted=no
Credentials_Encrypted=no
Symmetric_Key_Cache_Enabled=no
Symmetric_Key_Cache_Expiry=43200
Persistent_Cache_Enabled=no
Persistent_Cache_Directory= 
Persistent_Cache_Expiry_Keys=43200
Persistent_Cache_Max_Size=100
Log_Level=WARN
Log_File=
Log_Rotation=Daily
Log_Size_Limit=100k

Version

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

NAE_IP

The NAE_IP parameter sets the IP address/Hostname of the CipherTrust Manager. You can configure both the IPv4 as well as IPv6 addresses. Specify the IPv6 address within curly braces ({.....}). For example, {fe80:0:0:0:200:f8ff:fe21:67cf}. Specify the IPv4 address directly.

Use multiple IP addresses/hostnames separated by colons (:) when load balancing is used. For example, use IPv4 like 192.168.1.100:192.168.1.101:192.168.1.102 and IPv6 like {fe80:0:0:0:200:f8ff:fe21:67cf}: {fe80:234f:0:0:200:f8ff:fe21:832d}. Combination of IPv4 and IPv6 addresses can also be used like 192.168.1.10: {fe80:0:0:0:200:f8ff:fe21:67cf}.

NAE servers can be configured up to three tiers. Tiers are numbered 1-3. If all servers in the primary tier 1 become unreachable, the client will switch to tier 2. If all servers in tier 2 become unreachable, the client will switch to tier 3. When using an alternative tier, the client will periodically try to switch back to tier 1 (after Connection_Retry_Interval has expired).

NAE_Port

The NAE_Port parameter specifies the port number of the CipherTrust Manager. The default port number is 9000.

Clients and Servers must use the same port number.

Protocol

The Protocol parameter specifies the protocol used to communicate between client and the CipherTrust Manager.

Clients and servers must use the same protocol. If your CipherTrust Manager appliances are listening for SSL requests but your clients aren't sending SSL requests, there will be no communication between the client and the server.

It is recommended that you gradually increase the security only after confirming a connectivity between the client and the server. Once a TCP connection is established between the client and the server, it is safe to move on to SSL. Initially, configuring the client and the server under the most stringent security constraint can complicate the troubleshooting.

Use_Persistent_Connections

The Use_Persistent_Connections parameter enables to use persistent connections.

Size_of_Connection_Pool

The Size_of_Connection_Pool parameter is the total number of client-server connections that your configuration could possibly allow, not what actually exists at a given moment.

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 the CipherTrust 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_Timeout

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

Setting this parameter a few hundred ms less than the operating system's connection timeout makes connection attempts to fail faster to a server that is down, thus 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 your 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 allows you to control how long the client waits when reading data from the CipherTrust Manager before determining that it is down. Requests should only time out if the CipherTrust Manager is physically down (for example, powered off or not responding because of misconfiguration).

The purpose of this parameter is to control how you want the client to react when the CipherTrust 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_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.

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 CipherTrust Manager appliances 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.

Cluster_Synchronization_Delay

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

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

CA_File

The CA_File parameter refers to the CA certificate that was used to sign the server certificate presented by the NAE Server to the client.

All CipherTrust Manager appliances in a clustered environment must have an identical configuration. Therefore, same server certificate is used by all the servers present in a cluster. As such, you only need to point to 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 CipherTrust Manager appliances, your client applications cannot establish SSL connections with any of the servers in the cluster.

If a local CA on CipherTrust Manager was used to sign the NAE Server certificate, you can download the certificate for the local CA, and put that certificate on the client.

Cert_File

The Cert_File parameter stores the path and filename of the client certificate. This is only used when your SSL configuration requires clients to provide a client certificate to authenticate to the CipherTrust Manager appliances.

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

Key_File

The Key_File parameter refers to the private key associated with the client certificate specified in the Cert_ File parameter.

Since this key is encrypted, you must use the Passphrase parameter so that the CipherTrust Manager can decrypt it.

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

Passphrase

The Passphrase parameter refers to the passphrase associated with the private key. The passphrase must be associated with the private key named in Key_File.

If the passphrase is not associated with the private key, the client attempts to read the passphrase from standard input; this causes the application to hang.

Remember that the property file is NOT encrypted. Make sure that this file resides in a secure directory and has an appropriate permissions so that it is readable only by the appropriate applications or users.

Passphrase_Encrypted

The Passphrase_Encrypted parameter allows you to enable/disable passphrase obfuscation.

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.

Symmetric_Key_Cache_Expiry

The Symmetric_Key_Cache_Expiry parameter determines the minimum amount of time for which a key remains in the client key cache.

It is recommended to keep short expiry time for keys kept in the cache.

Persistent_Cache_Enabled

The Persistent_Cache_Enabled parameter determines if the persistent key caching feature is enabled.

• To enable this feature, you must also enable symmetric key caching.

• The Symmetric_Key_Cache_Enabled parameter must be set to yes, tcp_ok, or

• This is the default and recommended setting.

• To disable the feature, set Persistent_Cache_Enabled=no

Persistent_Cache_Directory

The Persistent_Cache_Directory parameter determines the directory where the provider library creates the persistent cache file. You can provide the path to the directory that contains the keys. 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_Expiry_Keys

The Persistent_Cache_Expiry_Keys parameter determines the number of seconds after which key is fetched from the CipherTrust Manager.

• If the CipherTrust Manager is not reachable, key will not be deleted and insertion time of key will be updated.

• If any other error comes from the CipherTrust Manager, key will be deleted.

To enable the persistent cache, the value of Persistent_Cache_Expiry_Keys property must be greater than zero.

If the client is not able to access the CipherTrust Manager, the expired keys are not deleted from the persistent cache. Even if the key is updated on the CipherTrust Manager, client will continue to use the stored persistent key. Hence, it is recommended to keep the CipherTrust Manager accessible to work with the updated keys.

Persistent_Cache_Max_Size

The Persistent_Cache_Max_Size parameter determines the maximum number of keys that can be stored in the persistent cache.

Log_Level

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

The user running your 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 a path for the log file.

Log_Rotation

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

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.

Credentials_Encrypted

This flag indicates that NAE Username and Password are encrypted using PassPhraseSecure Utility. Default value is set to no. If value is set to yes and an invalid obfuscated string is set, then the system throws an error.

It is recommended to use only obfuscated passwords.