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
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.
Note
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 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
Config_path=
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).
Note
If NAE_IP is configured to Hostname or FQDN, then refer to Resolving FQDN/Hostname for more details.
NAE_Port
The NAE_Port
parameter specifies the port number of the CipherTrust Manager. The default port number is 9000.
Tip
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.
Possible Settings | Description |
---|---|
tcp | |
ssl | In CAKM library, TLSv1.2 and TLSv1.3 is used. By default, TLSv1.3 is enabled on all the CipherTrust Manager appliances. It is recommended to use ssl. |
Note
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.
Tip
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.
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.
Possible Settings | Description |
---|---|
yes | This feature is enabled. For example, to enable the verification, set Verify_SSL_Certificate=yes . |
no | The feature is disabled. This is the default value. |
Use_Persistent_Connections
The Use_Persistent_Connections
parameter enables to use persistent connections.
Possible Settings | Description |
---|---|
yes | Enables the functionality. The client establishes persistent connections with NAE servers. This is the default value. |
no | Disables the functionality. 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 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.
Possible Settings | Description |
---|---|
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 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.
Possible Settings | Description |
---|---|
0 | Disables this setting. The client uses the operating system’s connect timeout. |
Any positive integer | The default value is 60000ms. |
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.
Note
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).
Possible Settings | Description |
---|---|
0 | Disables this setting. The client waits indefinitely until the CipherTrust Manager can be reached. Requests remain outstanding until the client’s request is successfully satisfied. |
Any positive integer | The default value is 7000ms. |
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.
Possible Settings | Description |
---|---|
Any positive integer | The default value is 600000ms (10 minutes) |
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.
Possible Settings | Description |
---|---|
0 | This is the infinite retry interval. Once a server gets disabled, it will be brought back into use only after all the servers become disabled. |
Any positive integer | The default value is 600000ms (10 minutes) |
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.
Possible Settings | Description |
---|---|
0 | Disables the function |
Any positive integer | The default value is 100s. A higher value is recommended for large clusters. |
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 valueTLS_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.
Note
The default entry is commented out in the properties file as this parameter is compiled into the client library. You should modify this parameter only if you prefer to use some other combination of algorithms and protocols.
Modifying this parameter overrides the value in the library.
It is recommended to use TLS ciphers offered by the CipherTrust Manager appliance. If you specify some value other than the default, you must use ECDHE for key exchange.
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.
Possible Settings | Description |
---|---|
The path and filename | The path can be absolute or relative to your application. Do not use quotes, even if the path contains spaces. |
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.
Possible Settings | Description |
---|---|
The path and filename | The path can be absolute or relative to your application. Do not 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 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.
Possible Settings | Description |
---|---|
The path and filename | The path 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#8 format. |
Since this key is encrypted, you must use the Passphrase
parameter so that the CipherTrust Manager can decrypt it.
Note
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
.
Caution
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.
Note
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.
Possible Settings | Description |
---|---|
yes | set this value, if you want to obfuscate the passphrase. |
no | set this value, if you do not want to obfuscate the passphrase. |
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.
Possible Settings | Description |
---|---|
yes | This feature is enabled. For example, to enable the obfuscation of username and password, set Credentials_Encrypted=yes . This is the recommended value. |
no | The feature is disabled. This is the default value. |
Note
It is recommended to use only obfuscated passwords.
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.
Possible Settings | Description |
---|---|
no | Key caching is disabled. Remote encryption (encryption performed on CipherTrust Manager) is available as normal. This is the default and recommended setting. To disable the feature, set Symmetric_Key_Cache_Enabled=no |
yes | Key caching is enabled and the NAE-XML protocol is used for exporting keys. The Protocol parameter must be set to ssl. To enable key caching and use NAE-XML protocol for exporting keys, set Symmetric_Key_ Cache_Enabled=yes |
tcp_ok | Key caching is enabled over both tcp and ssl connections. The NAE-XML protocol is used for exporting the keys. To enable key caching over both tcp and ssl connections, set Symmetric_Key_Cache_ Enabled=tcp_ok |
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.
Possible Settings | Description |
---|---|
no | Key caching is disabled. Remote encryption (encryption performed on CipherTrust Manager) is available as normal. This is the default and recommended setting. To disable the feature, set Asymmetric_Key_Cache_Enabled=no |
yes | Key caching is enabled and the NAE-XML protocol is used for exporting keys. The Protocol parameter must be set to ssl. To enable key caching and use NAE-XML protocol for exporting keys, set Asymmetric_Key_ Cache_Enabled=yes |
tcp_ok | Key caching is enabled over both tcp and ssl connections. The NAE-XML protocol is used for exporting the keys. To enable key caching over both tcp and ssl connections, set Asymmetric_Key_Cache_ Enabled=tcp_ok |
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.
Possible Settings | Description |
---|---|
0 | This is the infinite timeout setting. Keys are never purged from the client cache. |
Any positive integer | At the end of this interval, the key is purged from the cache the next time the library is called. The default value is 43200 seconds (12 hours). For example, if you want a key to remain in the client key cache for 72000 seconds (20 hours), set Symmetric_Key_Cache_Expiry=72000 |
Note
This will be applicable to both Symmetric & Asymmetric cache.
It is recommended to keep short expiry time for keys kept in the cache.
Log_Level
The Log_Level
parameter determines the level of logging performed by the client.
Possible Settings | Description |
---|---|
None | Disables client logging. It is recommended not to disable logging. |
ERROR | One or more functionalities are not working and preventing some functionalities from working correctly. The application may continue to run. |
WARN | Unexpected behavior happened inside the application, but it is continuing its work and the key business features are operating as expected. |
INFO | Informational messages that highlights the progress of the application. |
DEBUG | Information needed to diagnose, troubleshoot, or test an application. |
Note
To run your client application, you 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.
Possible Settings | Description |
---|---|
filename | The log will be created in the same directory as the client. The default value is Logfile.txt . |
path and filename | The path can be absolute or relative to your application. Do not use quotes, even if the path contains spaces. The default is Logfile (created in the current directory). |
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.
Possible Settings | Description |
---|---|
Daily | Rotate logs daily. This is the default value. The rotated log file will contain logs from the previous day. For example, if the rotated log file is cakm_logfile.log_2024-07-02 , then rotated log file will have logs of 2024-07-01. |
Size | Rotate logs when they reach the size specified in Log_Size_Limit . For example, if you want logs to be rotated once they reach the size specified in Log_Size_Limit, set Log_Rotation=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.
Possible Settings | Description |
---|---|
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. For example, if you want the logs to be rotated once they reach 1 MB, set Log_Size_Limit=1M (or 1024k or, 1048576) . |
Note
Log_Rotation and Log_Size_Limit settings are applicable on both Log_File and MS_Sql_Ekm_Log.
VKM_mode
This parameter will be used for VKM to EKM migration of databases passively.
Possible Settings | Description |
---|---|
yes | This feature is enabled for passive migration and restores the backup of VKM databases. To enable the parameter, set VKM_mode=yes . |
no | The feature is disabled. This is the default value. |
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.
Possible Settings | Description |
---|---|
yes | This feature is enabled. |
no | The feature is disabled. This is the default value. |