System Settings and Static Properties
This section addresses generic settings. For UI specific system settings, see:
- Managing SSO Providers - Settings of OpenID Connect providers.
- LDAP Provider Settings.
System Settings
The following sections present and describe groups of the related settings as follows:
- Tag
- Internal name. The
ucl settings get
command uses tags to show the settings. - Alias
- Name used by CLI
Command Line Interface
- Default
- The default value
- Restart
- "Yes" indicates that Activation of Change. is required.
Activation of Change.
The "YES" entry in the "Restart" column indicates that activation of the change requires:
- In a non-FIPS
Federal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors system -
restart ALL EP servers. See EKM Service Management. - In a FIPS
Federal Information Processing Standards - standards developed by the United States federal government for use in computer systems by non-military government agencies and government contractors system -
restart ALL triplets of servers. See EKM Service Restart in FIPS Triplet.
In addition, the system will turn on the RESTART_REQUIRED reminder. See Summary of Alerts.
No-cert
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_ALLOW_NO_CERTIFICATE | no-cert |
0 ("NO") - Client-side certificate is required to connect to connect to the CORE Web UI. |
0 |
no |
This setting controls whether the authentication of a RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API user includes the validation of its certificate. This setting may be overruled by partitions. See Exemption from Certificate Possession.
Check_jwt_originator
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_CHECK_JWT![]() |
check_jwt_originator |
0 ("NO") - The IP of the JWT |
1 |
no |
Once an application using CORE API is authenticated and authorized to perform crypto operations - it receives an access token used in the subsequent requests. The targeted CORE server validates the signature and the validity period of the token. The check_jwt_originator
setting further hardens the validation of the token by verifying that its current holder is the same one that the token was assigned to. See Troubleshooting check_jwt_originator.
Log_operation_purpose
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_LOG_OPERATION_PURPOSE | log_operation_purpose |
0 ("NO") - Logs the short form of operation description. For example, "Sign". |
0 |
no |
Use this setting to distinguish between the explicit sign operation and the implicit one (such as when generating CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate) in the
ekm.log
.
For example,
- if the setting is disabled (0)
- if the setting is enabled (1)
the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate-generate request produces the following "sign" log:
user@part2 my-pc@part2 part2 Sign 0x0045e655ad5edfe998 0 0 250 OK
the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate-generate request produces the following "sign" log
:
user@part2 my-pc@part2 part2 Sign_CSR
Certificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate 0x0045e655ad5edfe998 0 0 250 OK
To enable, use --value 1:
Is-fips
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_IS_FIPS![]() |
is-fips |
0 ("NO") - FIPS mode
|
0 |
YES |
Refresh and Sync Timers
This group of settings controls the rate at which the key material is refreshed.
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_REFRESH_INTERVAL | refresh-interval | Duration of a pause between key material refresh cycles (in minutes). See Key Material Refresh. | 60 minutes | YES |
x-DY_SEED_INTERVAL | seed-interval | Randomness seed refresh interval (in hours). |
12 hours | YES |
x-DY_SYNC_INTERVAL | sync-interval | DB sync interval (in minutes). |
5 minutes. | YES |
These settings allow tuning the key material refresh and DB synchronization cycles.
- Refresh - modifies the key shares on the EP and its Partner servers without impacting the consistency of the result produced by the key.
- DB Sync - changes in the database of an EP server are mirrored to all EPs, and changes in the Partner server database are mirrored to all Partners.
Automatic Key-rotation Time
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_KEY_ROTATION_EXEC_TIME | key-rotation-time | Time of Day when the key rotation task starts its work. See Periodic Rotation. | 00:00 |
YES |
Connection Timeouts
This group of settings controls the time allocated to receive responses to CORE-to-CORE server requests. All settings are in milliseconds.
Tag | Alias | Description | Range | Default | Restart |
---|---|---|---|---|---|
x-DY_CONNECT_TIMEOUT | connect-timeout | Inter-Server connection setup timeout. |
50 .. 60,000 in increments of 50. Units: ms |
0 - use OS timeout | YES |
x-DY_WRITE_TIMEOUT | write-timeout |
Inter-server POST timeout. |
YES | ||
x-DY_READ_TIMEOUT | read-timeout | Inter-server GET timeout. |
YES |
- Connect - the max time allocated for setting TCP connection between two CORE servers
- Write - the max time allocated to receive confirmation that the POST method succeeded.
- Read - the max time allocated to receive a response to the GET procedure
The default value (0
) indicates that the timeout setting is delegated to the underlying OS.
If the OS setting specifies unlimited wait, the performed operation may hang forever. If this happens, restart the EKMEnterprise Key Management - previous name of the product. service.
These settings allow tweaking CORE-to-CORE server communication timeouts:
Note
1. Change these timeouts only as directed by support@unboundsecurity.com.
2. The following processes use the default OS timeout regardless of the above settings: CORE database backup, Collection of CORE crypto-operation logs, and adding new servers to the cluster.
Keep-Alive Timers
This group of settings enables the detection of connection issues on idle CORE-to-CORE server links. A link enters this state after the keep-alive-idle
seconds had passed without traffic on the link.
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_KEEP_ALIVE_IDLE | keep-alive-idle |
1 to 32767; The interval during which the inter-server connection needs to remain idle before starting the keepalive probing (seconds). |
180 secs | YES |
x-DY_KEEP_ALIVE_INTERVAL | keep-alive-interval | 1 to 32767; The time interval between individual keepalive probes
(seconds). |
60 secs | YES |
x-DY_KEEP_ALIVE_COUNT | keep-alive-count | 1 to 32767; The maximum number of consecutively failed keepalive probes before dropping the connection. |
20 failures | YES |
CORE keep-alive mechanism is used for the early detection of inter-CORE connection issues on idle links. A link is classified as an idle link if the Keepalive idle period
has expired since the last message crossed the link. In such a case, the server starts sending the keep-alive
message once in the Keepalive probe period
.
If the number of consecutive probe failures reaches the Keepalive failures max
, the link is declared as not operational, and the alert is raised.
Certificate Validity Settings
Public Key Infrastructure settings used by CORE:
Tag | Alias | Description | Default | Restart |
---|---|---|---|---|
x-DY_ROOT_CA_CERTIFICATE_EXPIRATION | root-ca-exp | Validity period (in days). | 2922 days (~8 years![]() |
no |
x-DY_ROOT_CA_CERTIFICATE_PRE_EXPIRY | root-ca-pre-expiry | The expiry alert is raised N days before its last validity day (in days). |
180 days |
no |
x-DY_SERVER_CERTIFICATE_EXPIRATION | server-exp | Validity period (in days) | 1096 days (~3 years![]() |
no |
x-DY_SERVER_CERTIFICATE_PRE_EXPIRY | server-pre-expiry | The expiry alert is raised N days before its last validity day (in days). | 180 days |
no |
x-DY_CLIENT_CERTIFICATE_EXPIRATION | client-exp | Validity period (in minutes) | 1578240min (~3.5 years![]() |
no |
x-DY_CLIENT_CERTIFICATE_PRE_EXPIRY | client-pre-expiry | The expiry alert is raised N minutes before its last validity minute (in minutes) |
129600min (~3month) |
no |
Note
Custom settings of the certificate validity
period must comply with the following rule:Validity(rootCA) >= 2 * MAX[Validity(serverCertificate), Validity(clientCertificate)] + 730
Expiry Alerts:
- CORE client certificate:
Once the CORE client's certificate lifecycle enters the alert period, SOSecurity officer - UKC partition administrator role. of all partitions that serve the client are alerted to renew its certificate.
- CORE server certificate and the Root CA certificates
Once the CORE server's certificate or the Root CA certificate reaches the alert period, the root SOSecurity officer - UKC partition administrator role. is alerted to renew the certificate.
Troubleshooting System Settings
- Troubleshooting
check_jwt_originator
- The integrity of the token.
- The validity of its usage interval.
- Optionally, the validity of the token user's IP address (comparing the sender's network IP with the IP stored in the "
orig
" field of the token).
When the EP server acting as JWTJSON Web Token - means of representing claims transferred between two parties issuer creates an authentication token, it stores the request originator's IP in the "orig" field and delivers the token to the originator.
Each time a CORE app provides a JWTJSON Web Token - means of representing claims transferred between two parties token with its request, EP checks the following:
The last assertion depends on the check_jwt_originator
setting. By default, this setting is enabled.
Default Capacity Constraints
The following maximum values are the CORE default capacity constraints per system, partition, and operation. Before increasing any of these, contact support@unboundsecurity.com.
Maximum Number of | Per System | Per Partition |
---|---|---|
Server pairs in a cluster | 12 | |
Auxiliary servers | 12 | |
Partitions | 3,000 | |
OIDC![]() |
8 | |
External Key Stores | 12,000 | 10 |
Crypto objects | 500,000 | 100,000 |
Clients | 10,000 | 1,000 |
Users | 10,000 | 1,000 |
User groups | 10,000 | 1,000 |
User roles | 10,000 | 1,000 |
Statements in Partition Policy | 1,000 | 30 |
Quorum requests in DB(*) | 1,000 | 30 |
Backup records | 3,000 |
Note: "Quorum request in DB" refers to both pending and approved requests that are kept in the database. As needed, consider deleting the approved requests.
Maximum Size in Bytes | Per Crypto Operation |
---|---|
Crypto payload size | < 4000 |
Note: For example, max size of a secret that can be accepted by the system.
System Static Properties
The CORE system properties are optional EKMEnterprise Key Management - previous name of the product. service settings that may be customized by configuring JAVA_OPTS and restarting the EKM
Enterprise Key Management - previous name of the product. service.
To change the default static system properties,
- Edit or, as needed, create the following file
- Linux:
/opt/ekm/bin/
file.setenv.sh
- Windows:
C:\Program Files\Dyadic\ekm\tomcat\bin\
setenv.bat
Add or modify
export JAVA_OPTS="$JAVA_OPTS -D<name=value>"
Add or modify
set JAVA_OPTS="%JAVA_OPTS% -D<name=value>"
For example, to modify the default
ekm.max.list.key
setting, use:JAVA_OPTS="${JAVA_OPTS} -Dekm.max.list.keys=5000"
- Linux:
- Restart the service. See EKM
Enterprise Key Management - previous name of the product. Service Restart (see EKM Service Management).
enable.kmip.tls1
By default, the EP server expects its KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server clients to use TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.2 cipher suites.
To extend the list of the options to TLS1.1 and TLS1.o cipher suites, set the system property enable.kmip.tls1 setting to true.
Static Property | Default | Example | Applicable |
---|---|---|---|
enable.kmip.tls1 | false | -Denable.kmip.tls1=true | EP |
check.integrity
The integrity validation assures the authenticity of the CORE object's metadata by cryptographic comparison of the specified data on EP and Partner servers.
The validation is always applied when the metadata is provided to an application. When the object's metadata is used internally by the CORE , the validation is bypassed (by default). To activate the validation also in this case, add the -Dcheck.integrity=true
option to the CORE JAVA_OPTS
.
See Integrity Validation on Servers
Static Property | Default | Example | Applicable |
---|---|---|---|
check.integrity | disabled | -Dcheck.integrity=false | EP and Partner |
To enable the integrity check, set -Dcheck.integrity=true
.
ekm.max.list.keys
Restrict the max number of crypto objects that a single GET request may request.
Static Property | Default | Example | Applicable |
---|---|---|---|
ekm.max.list.keys | unrestricted | -Dekm.max.list.keys=8192 | EP |
proxyHost
There are several properties that can be used to configure a proxy, including the proxy name, port, and any non-Proxy host names. These are only relevant when working with an external KMSKey Management System.
Static Property | Default | Example | Applicable |
---|---|---|---|
http.proxyHost | N/A | -Dhttp.proxyHost="proxy.example.com" | EP |
http.proxyPort | N/A | -Dhttp.proxyPort=1010 | EP |
http.nonProxyHosts | N/A | -Dhttp.nonProxyHosts=”localhost|host.example.com” | EP |