Configuring Properties File

This section explains how to configure the cakm_mssql_ekm.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

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

You can configure multiple NAE_IPs through the multi-tier functionality.

• For Fully Qualified Domain Name,

  NAE_IP= <FQDN_domain_name>

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 cakm_mssql_ekm.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
Cipherspec=
CA_File=
Cert_File=
Key_File=
Passphrase=
Passphrase_Encrypted=no
Credentials_Encrypted=no
Symmetric_Key_Cache_Enabled=no
Asymmetric_Key_Cache_Enabled=no
Symmetric_Key_Cache_Expiry=43200
Log_Level=WARN
Log_File=C:\Program Files\CipherTrust\CAKM For SQLServerEKM\logs\cakm_logfile.log
Log_Rotation=Daily
Log_Size_Limit=100k
MS_Sql_Ekm_Log=
VKM_mode=no
Thumbprint=yes
Cert_Auth=no

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. Hostname or FQDN can also be specified instead of IP address.

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.

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 Protocol is set to ssl. Enable or disable verification of DataSecure IP address(IPV4 or IPV6)/host name against Subject Common Name (CN) or Subject Alternative Name (DNS or IP) in the server 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.

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

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 allows you to enable/disable passphrase obfuscation.

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.

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.

Asymmetric_Key_Cache_Enabled

The Asymmetric_Key_Cache_Enabled parameter determines if the asymmetric key caching feature is enabled. Only asymmetric 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.

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.

MS_Sql_Ekm_Log

EKM logs are generated at the file location mentioned in the MS_Sql_Ekm_Log property.

The default path of log file is where the CAKM For SQL EKM is installed.

For example, if CAKM for SQL EKM is installed at the following path:

C:\Program Files\CAKM For SQL EKM

EKM logs will be created at C:\Program Files\CAKM For SQL EKM\logs\cakm_sql_ekm_wrapper.log

MS_Sql_Ekm_Log = <log_file_path>

You can configure separate log files for different database instances.

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.

VKM_mode

This parameter will be used for VKM to EKM migration of databases passively.

Thumbprint

Thumbprint is the unique id maintained for each key. Specifying the value of Thumbprint as "no", enables the special handling of thumbprint. In this case, only hex format is compatible.

• To create a new key, the key name must be provided in the hex format.

• Key size should be in an even number.

• Key length is limited to 64 characters.

Recommended value of Thumbprint is "yes".

Cert_Auth

Specifying the value of Cert_auth as "yes", enables the authentication of a client with the CipherTrust Manager with a certificate present with the client. This eliminates the need for username and password.