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 SOSecurity 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.
• Access to the root partition requires Root SOSecurity 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 - OTPOne-Time Password (or Pin) - a password that is valid for only one login session or transaction. master key. Serves to derive the OTPOne-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

• Linux:

  /etc/ekm

• Windows:

  C:\ProgramData\Dyadic\ekm

• MacOS:

  /private/etc/ekm

This folder contains:

• certificates (.PFXAn 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

• Linux:

  /etc/ekm/ssl

• Windows:

  C:\ProgramData\Dyadic\ekm\ssl

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 KMIPKey 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 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 sign their identity using external CA certificates, the CORE server maintains the 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 - 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(SANSubject 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(SANSubject 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"

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_128_GCM_SHA256

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_256_GCM_SHA384

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_DHE_RSA_WITH_AES_128_GCM_SHA256

TLSTransport 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"

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_AES_256_GCM_SHA384

TLSTransport 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:

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_256_GCM_SHA384

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAElliptic 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 TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.1 or TLSTransport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.2 ciphers 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, 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 OPENSSL_CONF.

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, ekm-java-utils.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

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:

<Loggers> Logger name="AUDIT" level="info" Logger name="TRACE" level="off" Logger name="CONFIG" level="info" </Loggers>
• Server Log Files

CORE logs are stored in the following files in the Log-data Folder:

• 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.

The previous-day files are:

1. Compressed.
2. Renamed to include the date <log-name>.YYYY-MM-DD.log.gz.
3. 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.

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.

• External Keystore Log File.

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:
echo $JAVA_HOME or
java -XshowSettings:properties -version 2>&1 > /dev/null | grep 'java.home'


• Windows:
echo %JAVA_HOME% or
java -XshowSettings:properties -version 2>&1 | findstr "java.home"

To set JAVA_HOME

Linux and MacOS:

• 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.
• 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=

Windows:

1. 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.
2. Open the Advanced tab and click the Environmental Variables button.
3. 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: 
  The root. To change the process owner, modify the EKMEnterprise Key Management - previous name of the product._USER in the /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 EKMEnterprise 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 the EKMEnterprise Key Management - previous name of the product. service. If the CORE software installation fails to create this user, the service is executed by Windows default service account - Local System.