Configuring the Properties File

This section explains how to configure the /etc/ks_config 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 comment out values using #. You may want to use comments to save settings while troubleshooting. For example, you can store commonly used NAE_IP addresses like this:

NAE_IP=10.0.0.2
#NAE_IP=10.0.0.3
#NAE_IP=10.0.0.4

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.

Modifying Parameters

Once you install the client software, you can customize it to meet the needs of your environment by modifying the configuration file, IngrianNAE.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
Load_Balancing_Algorithm=round-robin
Connection_Timeout=30000
Connection_Read_Timeout=30000
Connection_Idle_Timeout=600000
Connection_Retry_Interval=600000
Cluster_Synchronization_Delay=170
Cipherspec=
CA_File=
Cert_File_Location=
Cert_File= 
Key_File= 
Passphrase=
Passphrase_Encrypted=no
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_Port

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

Protocol

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

Verify_SSL_Certificate

This parameter is considered only when the Protocol is set to 'ssl'. This parameter can enable or disable verification of Key Manager IP address(IPV4 or IPV6)/host name against Subject Common Name (CN) or Subject Alternative Name (DNS or IP) in the certificate.

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.

Load_Balancing_Algorithm

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

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.

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.

Cipherspec

This parameter specifies which SSL/TLS protocol and encryption algorithms to use. Multiple cipher strings can be separated by colons. For example, the value
TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCMSHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128- SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA
specifies TLS 1.2 and TLS 1.3 high strength ciphers.
Here,
TLS 1.2 ciphers are - ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA
AND
TLS 1.3 ciphers are - TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256.
If TLS 1.3 cipher is not provided then the ciphers - TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256 gets enabled by default. So to use TLS 1.2, you can disable TLS 1.3 protocol at CM. Refer to Modify TLS version of an interface.

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_Location

This parameter is used to specify the location through which the client certificate authentication will be done, that is, through File Path or using Microsoft Certificate Store.

The valid values of the parameter can be Cert_File_Path, Microsoft_Cert_Store, Microsoft_Cert_Store::Local_Machine, and Microsoft_Cert_Store::Current_User. The default value is Cert_File_Path and default Microsoft_Cert_Store type is .

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.

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.

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.

Passphrase_Encrypted

The Passphrase_Encrypted parameter enables or disables the obfuscation of the passphrase for client private key specified in Key_File. This value is required to enable/disable the obfuscation of the passphrase for client private key specified in Key_File obfuscated PassPhrase can be generated by using utility "PassPhraseSecure". The default value is 'no'.

Log_Level

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

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.