Connection Configuration Parameters
CAPI
The following table lists the connection configuration parameters for CAPI.
| Parameter | Default | Description |
|---|---|---|
| Load_Balancing_Algorithm | round-robin | Determines how the client selects a CipherTrust Manager from a load balancing group. Possible settings: • round-robin - Directs the connection to the next server in the load balancing group. • random - Directs the connection to a randomly selected member of the load balancing group. • none - Directs the connection to the first server, ignoring trailing NAE_IPs. |
| Size_of_Connection_Pool | 300 | Total number of client-server connections that your configuration could possibly allow, not what actually exists at a given moment. Valid value: Any positive integer. This value is used only when persistent connections are enabled. 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, the 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 a server or a load balancing group. If there are multiple clients running on the same machine, separate connection pools are maintained for each client. |
| Connection_Idle_Timeout | 600000ms (10 mins) | The time a connection is allowed to be idle in the connection pool before it gets closed automatically by the client. Valid value: Any positive integer. The value is specified in milliseconds. Setting this value to 0 leads to infinite timeout. Note: There are two different connection timeout values: one on CipherTrust Manager, and one in the properties file. The value of the timeout in the properties file must be less than what is set on the server. This lets the client control when idle connections are closed. Otherwise, the client can maintain a connection that is closed on the server side, which can lead to error. |
| Connection_Timeout | 30000ms | Determines how long the client will wait for the connection to be established before time out. Valid values: • 0: Disables the setting. The client uses the operating system’s connection timeout. • Any positive integer. Setting this parameter a few hundred ms less than the operating system’s connection timeout makes connection attempts to a downed server fail faster, and 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 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 | 30000ms | This parameter allows you to control how long the client waits when reading data from a CipherTrust Manager before determining that it is down. Valid values: • 0 - This is infinite timeout setting. The client will keep on trying to read data from the server infinitely. • Any positive integer - The value is specified in milliseconds. For example, if you want the client to wait for 60000 milliseconds (1 minute) while trying to read data from the NAE server, before timing out, set Connection_Read_Timeout=60000.The purpose of this parameter is to control how you want the client to react when the CADP for C (CAPI or PKCS#11) library 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 request to complete in high load and high latency situations. Requests should only time out if the CipherTrust Manager is physically down (for example, powered off or not responding because of misconfiguration)timeout. |
| Connection_Retry_Interval | 600000ms (10 mins) | Determines how long the client will wait before trying to reconnect to a disabled server. If one of the CipherTrust Manager servers 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 reconnecting to it. If set to 0, it is an infinite retry interval. Once a server gets disabled, it is brought back into use only after all servers become disabled.Valid values: • 0 - Sets an infinite retry interval. After a server is disabled, it is brought back into use only after all servers become disabled. • Any positive integer - Specify value in milliseconds. |
| Cluster_Synchronization_Delay | 170sec | Specifies how long the client waits before assuming that key changes have been synchronized throughout a cluster. After creating, cloning, importing, or modifying a key, the client continues to use the same CipherTrust Manager appliance until the end of this delay period. Valid values: • 0 - Disables the functionality. • Any positive integer - A higher value is recommended for large clusters. This value is configurable at the CipherTrust Manager. For CADP for C, the Cluster_Synchronization_Delay value should be greater than or equal to the value defined on the CipherTrust Manager.For example, the client sets Cluster_Synchronization_Delay to 170 seconds and sends a key creation request to Appliance A, which is part of a cluster. Appliance A creates the key and automatically synchronizes with the rest of the cluster. The client uses only Appliance A for 170 seconds - enough time for the cluster synchronization to complete. After this time period, the client uses other cluster members as before. |
| Use_Persistent_Connections | yes | Enables the persistent connections functionality. Valid values: • yes - Enables the feature. The client establishes persistent connections with the NAE Servers. • no - Disables the feature. A new connection is made for each connection request. The connection is closed as soon as the client receives the server response. |
PKCS#11
The following table lists the connection configuration parameters for PKCS#11.
| Parameter | Default | Description |
|---|---|---|
| Size_of_Connection_Pool | 300 | Total number of client-server connections that your configuration could possibly allow, not what actually exists at a given moment. Valid value: Any positive integer. This value is used only when persistent connections are enabled. 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, the 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 a server or a load balancing group. If there are multiple clients running on the same machine, separate connection pools are maintained for each client. |
| Connection_Idle_Timeout | 600000ms (10 mins) | The time a connection is allowed to be idle in the connection pool before it gets closed automatically by the client. Valid value: Any positive integer. The value is specified in milliseconds. Setting this value to 0 leads to infinite timeout. Note: There are two different connection timeout values: one on CipherTrust Manager, and one in the properties file. The value of the timeout in the properties file must be less than what is set on the server. This lets the client control when idle connections are closed. Otherwise, the client can maintain a connection that is closed on the server side, which can lead to error. |
| Connection_Timeout | 30000ms | Determines how long the client will wait for the connection to be established before time out. Valid values: • 0: Disables the setting. The client uses the operating system’s connection timeout. • Any positive integer. Setting this parameter a few hundred ms less than the operating system’s connection timeout makes connection attempts to a downed server fail faster, and 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 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 | 30000ms | This parameter allows you to control how long the client waits when reading data from a CipherTrust Manager before determining that it is down. Valid values: • 0 - This is infinite timeout setting. The client will keep on trying to read data from the server infinitely. • Any positive integer - The value is specified in milliseconds. For example, if you want the client to wait for 60000 milliseconds (1 minute) while trying to read data from the NAE server, before timing out, set Connection_Read_Timeout=60000.The purpose of this parameter is to control how you want the client to react when the CADP for C (CAPI or PKCS#11) library 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 request to complete in high load and high latency situations. Requests should only time out if the CipherTrust Manager is physically down (for example, powered off or not responding because of misconfiguration)timeout. |
| Connection_Retry_Interval | 600000ms (10 mins) | Determines how long the client will wait before trying to reconnect to a disabled server. If one of the CipherTrust Manager servers 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 reconnecting to it. If set to 0, it is an infinite retry interval. Once a server gets disabled, it is brought back into use only after all servers become disabled.Valid values: • 0 - Sets an infinite retry interval. After a server is disabled, it is brought back into use only after all servers become disabled. • Any positive integer - Specify value in milliseconds. |
| Cluster_Synchronization_Delay | 170sec | Specifies how long the client waits before assuming that key changes have been synchronized throughout a cluster. After creating, cloning, importing, or modifying a key, the client continues to use the same CipherTrust Manager appliance until the end of this delay period. Valid values: • 0 - Disables the functionality. • Any positive integer - A higher value is recommended for large clusters. This value is configurable at the CipherTrust Manager. For CADP for C, the Cluster_Synchronization_Delay value should be greater than or equal to the value defined on the CipherTrust Manager.For example, the client sets Cluster_Synchronization_Delay to 170 seconds and sends a key creation request to Appliance A, which is part of a cluster. Appliance A creates the key and automatically synchronizes with the rest of the cluster. The client uses only Appliance A for 170 seconds - enough time for the cluster synchronization to complete. After this time period, the client uses other cluster members as before. |
| Use_Persistent_Connections | yes | Enables the persistent connections functionality. Valid values: • yes - Enables the feature. The client establishes persistent connections with the NAE Servers. • no - Disables the feature. A new connection is made for each connection request. The connection is closed as soon as the client receives the server response. |
