CORE Entities
CORE Root Partition
This topic summarizes the CORE Root partition's entities.
- The root partition is created and populated with the key material during the bootstrap of the CORE foundation servers.
- The root partition can't be deleted.
- The Root SO
Security officer - UKC partition administrator role. password is specified in the bootstrapping command.
- Its keys and certificates can't be deleted or edited. Certain objects may be modified by special crypto management applications such as certificate renewal.
- The root partition can't be deleted.
- Access to the root partition requires Root SO
Security officer - UKC partition administrator role. credentials and, by default, the partition's certificate on the appliance that tries to access it.
The system bootstrapping generates the following key material in the root partition:
- root-ca-key - signs all CORE server and client certificates.
- root-ca-certificate - verifies CORE client and server certificates.
Each Root CA Renewal
adds a new pair that bears the reserved names (root-ca-key
and root-ca-certificate
).
The names of the previous pear are versioned. For example, following two renewal cycles, the Root partition shall have the following pairs:
root-ca-key
and root-ca-certificate
root-ca-key-G1
and root-ca-certificate-G1
root-ca-key-G2
and root-ca-certificate-G2
- pwd-key - encrypts user passwords. It is used by the Unbound password protection solution (the key material type is "Password key").
- two-factor-master-key - OTP
One-Time Password (or Pin) - a password that is valid for only one login session or transaction. master key. Serves to derive the OTP
One-Time Password (or Pin) - a password that is valid for only one login session or transaction. seeds for CORE UI users. See TOTP-based 2FA.
- secret-data-key - used for encrypting secrets stored in CORE
See Secret Importing Options.
- integrity-key - CORE uses this key to sign its reports and respond to inquiries.
For examples of its usage, see Crypto Log Integrity Assertion.
CORE PKI
Certificates Folder
CORE Client Certificates Folder
This folder contains:
- certificates (.PFX
An archive file format for storing cryptography objects using Base64 encoding) of the registered partitions.
server-ca.p7b
CORE trust store. It contains CORE Root CA certificates.
CORE Server Certificates Folder
The folder's content:
cert.jks, cert.crt, key.pfx
- the server's certificate and encrypted key file.root_ca.ks
- the Root CA certificate.external-kmip-cert.ks
- keystore of the external KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server certificate.
Note
CORE server also includes the embedded CORE client. Because of that, it also contains CORE Client Certificates Folder.
Trust Certificates
CORE Trust Keystore
CORE client and server certificate validation is done using the CORE Root CA certificate(s) that are contained in the following files:
- CORE server - in the
root_ca.ks
JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. keystore in the CORE Server Certificates Folder.
- CORE client - in the
server-ca.p7b
file in the CORE Client Certificates Folder.
KMIP Trust Keystore
By default, the CORE server, acting as a KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server server on TCP/IP port 5696, uses its Root CA certificate to validate the identity of a KMIP
Key Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server client. To allow KMIP
Key Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server clients to sign their identity using external CA certificates, the CORE server maintains the JKS
A Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. keystore -
external-kmip-cert.ks
in the CORE Server Certificates Folder.
CORE Identity Certificates
CORE Server Certificate
CORE PKIPublic Key Infrastructure server certificate is located in the
key.pfx
file signed by the CORE Root CA certificate. See CORE Server Certificates Folder.
CORE Client Certificate
CORE PKIPublic Key Infrastructure client keeps its certificates in the CORE Client Certificates Folder.
By convention, the certificate's filename is <partition-name>.pfx
.
Other notable fields in the client's certificate are:
- Subject
- O = CLIENT
- OU = <partition name>
- CN = <client name>
- Issuer.CN = dyadic
- Friendly Name = <partition name>
- Subject Alternative Name(SAN
Subject Alternative Names - Certificate field with a list of IP addresses.)
- List of the client DNS names and IP addresses
KMIP Client Certificate
Externally signed KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server client certificate must contain the following fields:
- Subject
- O = CLIENT
- OU = <partition name>
- CN = <client name>
- Subject Alternative Name(SAN
Subject Alternative Names - Certificate field with a list of IP addresses.)
- List of the client DNS names and IP addresses
TLS and PKI Elements
Server.xml File
CORE server and its trust certificates are specified in the server.xml
file. See Apache Tomcat 8 Configuration Reference.
-
Linux:
/opt/ekm/conf/server.xml
-
Windows:
C:\Program Files\Dyadic\ekm\tomcat\conf\server.xml
The server.xml_original
file, located in the same folder, contains the default server.xml
values for the installed release.
HTTPS Server Cipher Suites
On ports 443 and 8443, the CORE Tomcat web service is configured to support the following: TLS1.2 ciphers.
- TLS1.2 ciphers
sslProtocol="TLS" sslEnabledProtocols="TLSv1.2" ciphers="HIGH+AESGCM"
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSA
Elliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_128_GCM_SHA256
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSA
Elliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_256_GCM_SHA384
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_DHE_RSA_WITH_AES_128_GCM_SHA256
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS1.3 ciphersuites
sslProtocol="TLS" sslEnabledProtocols="TLSv1.3"
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_AES_256_GCM_SHA384
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_AES_128_GCM_SHA256
To restrict the ciphersuites to any of the TLS1.2 and TLS1.3 ciphers listed above, modify the server.xml
file as follows:
SSLEnabled="true" scheme="https" secure="true"
clientAuth="want" sslProtocol="TLS" sslEnabledProtocols="TLSv1.3,TLSv1.2" ciphers="HIGH+AESGCM"
KMIP Cipher Suites
On the KMIPKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server port 5696, EP supports the following ciphers:
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSA
Elliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_256_GCM_SHA384
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSA
Elliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_128_GCM_SHA256
Note
To enable additional TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.0 and TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.1 or TLS
Transport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.2 ciphers on the KMIP
Key Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server port, contact support@unboundsecurity.com.
Client Files and Registry
Client Configuration
Note
Starting from the CORE 2.0.2010 release, CORE client settings can be specified in two locations hereon identified as:
- "V1" location - is the location used before this release. Provides backward compatibility.
- "V2" location - recommended option for new clients.
CORE client checks both locations starting from "V2". If the setting is not found, it searches for the setting in the "V1" location.
CORE client configuration is stored in the following location:
-
Linux:
V1 file: /etc/ekm/client.conf V2 file: /etc/unbound/client.conf -
Windows:
V1 registry: HKEY_LOCAL_MACHINE\SOFTWARE\Dyadic V2 registry: HKEY_LOCAL_MACHINE\SOFTWARE\Unbound -
MacOS:
V1 file: /private/etc/ekm/client.conf V2 file: /private/etc/unbound/client.conf
The setting that lists EP servers is the only mandatory client configuration setting. See Servers Setting . The setting's name of the setting depends on the client configuration version:
Name in V1: | servers |
Name in V2: | ukc.servers |
Names of the servers in the list must be DNS-resolvable.
Debug Log
The DyLog
files collect software execution traces on client and server appliances. See DY Logs.
Dy Log Folder
A DyLog
is a binary file (<random name>.dylog
) in the following folder:
-
Linux and MacOS:
/tmp/dy.log/<some date>/<random name>.dylog
-
Windows:
C:\Windows\Temp\dy.log\<some date>\<random name>.dylog
A single CORE service request may generate several dylog files. We recommend clearing all files from this folder before starting a new session.
Dy Log Control
To enable CORE debug log, set the following setting to 1.
Name in V1 : | enabled |
Name in V2 : | ukc.enabled |
-
Linux:
Old files: /etc/dylog.conf New file: /etc/unbound/client.conf -
Windows:
Old prefix: HKEY_LOCAL_MACHINE\SOFTWARE\Dyadic\log New prefix: HKEY_LOCAL_MACHINE\SOFTWARE\Unbound\log -
MacOS:
/etc/dylog.conf
Note
When your application software is Using Java Provider in Clientless Environment, set the environment variable DYLOG_ENABLED=
. 1
Other control settings:
Setting | Default | Description |
---|---|---|
network-info | 0 |
0 - network info (IP addresses, URLs) is present in the log. 1 - enables network info filtering. |
level | 3 | Keep the default unless directed otherwise by support@unboundsecurity.com. |
Client Libraries
PKCS#11 Library
The PKCSPublic-Key Cryptography Standards - Industry-standard cryptography specifications.#11 library is located in the following folder:
OS |
File |
Directory |
---|---|---|
RHEL | libekmpkcs11.so | /usr/lib64/ |
Ubuntu | /usr/lib/ | |
Windows | ekmpkcs11.dll |
C:\Program Files\Dyadic\ekm-client\bin\ |
Windows 32-bit | C:\Program Files\Dyadic\ekm-client\bin\x86\ |
OpenSSL Config and Library
The Unbound OpenSSL engine is located in the following folder of the CORE Client appliances.
Linux OpenSSL
The CORE OpenSSL Engine and configuration file are located in the following folder. Its integration with OpenSSL requires executing the dy_openssl
script that updates the standard openssl.cnf
file or creates a new one.
OS |
libekmsslengine.so (libdyadicsec.so) |
openssl.cnf |
---|---|---|
RHEL |
/usr/lib64/ |
/etc/pki/tls/ |
Ubuntu |
/usr/lib/ |
/etc/ssl/ |
SuSE | /usr/lib64/ | /etc/ssl/ |
1. RH8 and Ubuntu 18 and up are using OpenSSL Release 1.1.x. It requires CORE release 2.0.2001 or later.
2. If your system has multiple openssl.cnf
files, we recommend setting the environment variable OPENSSL_CONF
.
3. The selected openssl.cnf
file has to be modified by running the dy_openssl
script.
4. The name libdyadicsec.so
is maintained for backward compatibility. On the upgraded systems, it points at libekmsslengine.so
.
Windows OpenSSL
OS |
dyadicsec.dll |
openssl.cnf |
---|---|---|
Windows |
C:\Program Files\Dyadic\ekm-client\bin\ |
Use the environment variable |
CORE Client installation for Windows contains the following standard libraries that implement one of the latest Windows OpenSSL v.1.0.2<x>:
- C:\Program Files\Dyadic\ekm-client\bin\libeay32.dll
.
- C:\Program Files\Dyadic\ekm-client\bin\ssleay32.dll
.
Java
The location of the relevant Java folders depends on the Java release:
Java Security File
The java.security
file is located in the security folder as follows:
OS |
Java 8 |
Java 9-11 |
---|---|---|
RHEL/Centos/SuSE |
<JAVA_HOME>/jre/lib/security/ |
<JAVA_HOME>/conf/security/ |
Ubuntu |
<JAVA_HOME>/jre/lib/security/ |
<JAVA_HOME>/conf/security/ |
Windows | <JAVA_HOME>\jre\lib\security\ | <JAVA_HOME>\conf\security\ |
Java Security Provider Jar
CORE Java Security Provider JAR files are named and located as follows:
OS |
File |
Directory |
---|---|---|
RHEL/Centos/SuSE | ekm-java-provider-2.0.jar, ekm-java-9-provider-2.0.jar,
|
/usr/lib64/ |
Ubuntu |
/usr/lib/ |
|
Windows |
C:\Program Files\Dyadic\ekm-client\lib |
- In Java 7 and 8, use ekm-java-provider-2.0.jar
.
- In Java 9 and 11, use ekm-java-9-provider-2.0.jar
.
Database
The CORE database is split between EP and Partner servers in the MPCMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private. way - each key material object is split into two parts ("shares"), objects used by the partition management are duplicated.
The following File System structure is maintained by EP and Partner servers. Each server has unique keys and keystores to protect its database share.
Database Root Folder
- Linux:
/var/lib/ekm/data
- Windows:
C:\ProgramData\Dyadic\ekm\data
It contains the Backup Info File and the Database Folder.
Database Folder
The CORE server database is stored in the following folders:
- Linux:
/var/lib/ekm/data/database
- Windows:
C:\ProgramData\Dyadic\ekm\data\database
Backup Info File
API-based and UI-performed CORE server-pair backups use the following info (text) files:
- Linux:
/var/lib/ekm/data/key_backup.info
- Windows:
C:\ProgramData\Dyadic\ekm\data\key_backup.info
The key_backup.info
file specifies:
- Specification of the keystore that contains backup encryption public key.
- Name of the key and (if applied) the passphrase required to obtain the key.
- The backup encryption algorithm.
Example:
To create this file, make the necessary preparations and run ekm_set_backup_params.
Database Backup Folder
The CORE server database backups are stored in the following folders:
- Linux:
/var/lib/ekm/data/backup
- Windows:
C:\ProgramData\dyadic\ekm\data\backup
For each backup, it creates the following files:
- The
database_<DATE-TIME>.tar.gz
archive. It contains encrypted backup and its metadata. - The
database_<DATE-TIME>_digest.bin
file. It contains cryptographic data that is used by ekm_verify_backup.
CORE Logs
Log Folders
Log-control Folder
By default, CORE logging is controlled by settings in XML files located in the EKMEnterprise Key Management - previous name of the product. service configuration folder:
-
Linux conf folder
/opt/ekm/conf/
-
Windows conf folder
C:\Program Files\Dyadic\ekm\tomcat\conf\
Upgrade Note
CORE server upgrade preserves the current XML files. For the possible release-related changes in this file, see the <file-name>.xml_original
file, and propagate the necessary changes to the <file-name>.xml
file.
Log-data Folder
By default, the CORE log files are located in the following folders:
-
Linux logs folder
/opt/ekm/logs/
-
Windows logs folder
C:\Program Files\Dyadic\ekm\tomcat\logs\
Server Audit and Trace Logs
CORE server Audit and Trace logs are controlled and located as follows:
- Server Log Control
- Server Log Files
ekm.log
- the Audit log of the CORE system controlled by the AUDIT level setting.ekm-trace.log
- the trace log of the CORE server controlled by the TRACE level setting.- The console - presents the bootstrapping logs according to the CONFIG level setting.
CORE server logs are controlled by settings in the log4j.xml
file in Log-control Folder. It controls three categories of logs files by specifying the required level:
CORE logs are stored in the following files in the Log-data Folder:
The previous-day files are:
- Compressed.
- Renamed to include the date
<log-name>.YYYY-MM-DD.log.gz
. - Stored in
YYYY-MM
subfolder of Log-data Folder.
External Keystore Logs
Like the ekm-trace.log
control and output, CORE requests to external keystores have their log-control and data files.
- External Keystore Log Control.
- External Keystore Log File.
The details are controlled by the level setting in the extks-log.xml
file - see Log-control Folder. The levels are: off, info (default), debug, and trace.
The external keystore logs are stored in the extks.log
file in the Log-data Folder
Crypto Logs
Crypto logs are generated by the CORE engine on EP and Partner servers. They are in the Log Folders and use the following naming convention: ub-ekm-crypto-<DD>-<MM>-<YYYY>.log
. See CryptoLogs.
Tomcat Logs
Tomcat log files are located in the Log Folders
- The current day Tomcat logs are stored in
catalina.out
file. - The historic Tomcat logs are located in
catalina.<YYYY-MM-DD>.log
files.
Debug Logs
The DyLog
files collect software execution traces on client and server appliances. See Debug Log.
Admin
JAVA_HOME
Java is mandatory on CORE servers and optional on the CORE clients.
On Linux, the CORE software automatically locates the Java home directory if the Java was
installed using standard installation procedures (apt-get, yum, rpm
).
Check it by running using echo
or java
itself:
- Linux and MacOS:
- Windows:
echo $JAVA_HOME
or java -XshowSettings:properties -version 2>&1 > /dev/null | grep 'java.home'
echo %JAVA_HOME%
or java -XshowSettings:properties -version 2>&1 | findstr "java.home"
To set JAVA_HOME
- To set the default setting for all users:
-
Open
/etc/profile
in any editor. -
Add export
JAVA_HOME=/path/to/java_installation
. -
Run
source /etc/profile
.
-
Open
- To set the CORE-specific setting without affecting the default setting:
- Open the
/etc/default/ekm
file, and
- Set
JAVA_HOME
to the specific Java:
# Set JAVA_HOME if you wish to use a specific version of JAVA.
# Leave this unset to use the default version
#JAVA_HOME= - Open the
- Navigate to the Windows Environment Variables:
- Windows 7: On the Desktop, right-click My Computer and select Properties.
- Windows 10: Open Search and type advanced system settings.
- Open the Advanced tab and click the Environmental Variables button.
- Find the
JAVA_HOME
in the System variables. Set it to the specific JVM if you want to enforce its use.
CORE Server Admin Scripts
CORE admin scripts are in the following folders:
- Linux:
/opt/ekm/bin
- Windows:
C:\Program Files\Dyadic\ekm\tomcat\bin
System Processes
Services
This topic summarizes CORE services running on the CORE servers and clients.
- CORE server
- ekm - see Control CORE Service.
- CORE client on Linux and MacOS:
- ubpgpdaemon - see ucl pgp-key command.
EKM Service Owner Specification
By default, the EKMEnterprise Key Management - previous name of the product. Service is running on behalf of the following user:
- Linux:
Theroot
. To change the process owner, modify theEKM
in theEnterprise Key Management - previous name of the product._USER
/etc/default/ekm
file.
Note
To identify the EKMEnterprise Key Management - previous name of the product. service owner, run the
sudo service ekm status
command, and examine the value of the EKM
.Enterprise Key Management - previous name of the product._USER
Note
In the relocatable installation of CORE server software, the EKMEnterprise Key Management - previous name of the product. service runs on behalf of the user that installed it.
- Windows:
UnboundTech
service account. It has a minimal set of privileges required to run theEKM
service. If the CORE software installation fails to create this user, the service is executed by Windows default service account -Enterprise Key Management - previous name of the product.
Local System
.