Configuring the Properties File
This section explains how to configure the IngrianNAE.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
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.
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 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
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=
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=MEDIUM
Log_File=
Log_Rotation=Daily
Log_Size_Limit=100k
Credentials_Encrypted=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.
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.
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 SafeNet ProtectApp PKCS#11 library, TLSv1.2 is used. By default, TLSv1.2 is enabled on all the CipherTrust Manager appliances. • If you have disabled the use of TLSv1.2 on your servers then you cannot establish SSL connections between your NAE clients and servers. |
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.
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.
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#12 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.
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 |
kmip_yes | Key caching is enabled and the KMIP protocol is used for exporting keys. The Protocol parameter must be set to ssl. To enable key caching and use KMIP protocol for exporting keys, set Symmetric_Key_ Cache_Enabled=kmip_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 |
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
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.
Possible Settings | Description |
---|---|
yes | The feature is enabled. For example, to enable the feature, set Persistent_Cache_ Enabled=yes kmip_yes |
To enable this feature, you must also enable symmetric key caching.
The
Symmetric_Key_Cache_Enabled
parameter must be set toyes
,tcp_ok
, or
Possible Settings | Description |
---|---|
no | The feature is disabled. |
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 SafeNet ProtectApp PKCS#11 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.
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 . |
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.
Possible Settings | Description |
---|---|
0 | Disables the feature. |
Any positive integer | The default value is 100 keys. For example, if you want to store a maximum of 500 keys in the persistent cache, set Persistent_Cache_Max_Size=500 . |
Log_Level
The Log_Level
parameter determines the level of logging performed by the client.
Possible Settings | Description |
---|---|
None | Disables client logging. We recommend that you do not disable logging. |
Low | Only error messages are logged. |
Medium | The client logs error messages and warnings. |
High | The client logs error messages, warnings, and informational messages. This level generates a very large number of entries and is usually reserved for debugging. |
Note
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.
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. |
Log_Rotation
The Log_Rotation
parameter specifies whether logs are rotated daily or once they reach a certain size.
Possible Settings | Description |
---|---|
Daily | Rotates logs daily. This is the default value. |
Size | Rotates logs when they reach the size specified in Log_Size_Limit . |
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. |
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.