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.
    • The root partition can't be deleted.
    • Its key material can't be deleted or modified by commands designated to manage key material.
      It can be modified by the CORE system processes such as certificate renewal and similar.
    • The Root SOClosedSecurity officer - UKC partition administrator role. password is specified in the bootstrapping command.
  • Access to the root partition requires Root SOClosedSecurity 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:

ucl list -p root
Private ECC key : UID=acfb7771dff11d9a Name="root-ca-key" Certificate : UID=5304888e200ee265 Name="root-ca-certificate" Private ECC key : UID=aebb9e6854edba34 Name="saml-key" Certificate : UID=51446197ab1245cb Name="saml-certificate" Password key : UID=319e272ec6bc88c9 Name="pwd-key" Private ECC key : UID=4b14361c57ae3652 Name="secret-data-key Private ECC key : UID=4031c2c05ebb66d0 Name="integrity-key"
  • root-ca-key and root-ca-certificate - CORE CA certificate and private key.
  • root-ca-key
    Signs all CORE server and client certificates.
    root-ca-certificate
    The certificate is exported to CORE Trust Keystore where it is used to verify CORE client and server certificates.

    Each Root CA Renewal adds a new pair and rotates the names. For example, following the first rotation, the current pair will be tagged with G1 (the first generation).
    The new pair will bear the reserved names (root-ca-key and root-ca-certificate). Now this section of the root partition material will show:

    • root-ca-key and root-ca-certificate
    • root-ca-key-G1 and root-ca-certificate-G1

  • pwd-key - encrypts user passwords. It is used by the Unbound password protection solution (key material type is "Password key").

Certificates

Certificates Folder

CORE Client Certificates Folder

This folder contains:

CORE Server Certificates Folder

The folder's content:

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:

KMIP Trust Keystore

By default, the CORE server, acting as a KMIPClosedKey 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 KMIPClosedKey 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 KMIPClosedKey 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 JKSClosedA 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 PKIClosedPublic 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 PKIClosedPublic 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:

KMIP Client Certificate

Externally signed KMIPClosedKey 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:

TLS Elements

Server.xml File

CORE server and its trust certificates are referred to in the server.xml file. See Tomcat Configuration File.

  • The server.xml_original file, located in the same folder, contains the default server.xml values for the installed release.

CORE Server Cipher Suites

EP Server supports the following TLS1.2 cipher suites:

On ports 443 and 8443
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAClosedElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_128_GCM_SHA256
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAClosedElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_256_GCM_SHA384
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_DHE_RSA_WITH_AES_128_GCM_SHA256
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_DHE_RSA_WITH_AES_256_GCM_SHA384
 
On port 5696 (KMIPClosedKey Management Interoperability Protocol - an extensible communication protocol that defines message formats for the manipulation of cryptographic keys on a key management server)
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAClosedElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography._WITH_AES_256_GCM_SHA384
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network_ECDHE_ECDSAClosedElliptic 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 TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.0 and TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.1 and additional TLSClosedTransport Layer Security - a cryptographic protocol that provides communications security over a computer network 1.2 ciphers on KMIPClosedKey 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:

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:

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

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 the support@unboundsecurity.com.

Client Libraries

PKCS#11 Library

The PKCSClosedPublic-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 as highlighted in the following capture.

Java 8 and 11 Security File System

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 MPCClosedMultiparty 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 distinctive keys and keystores to protect its share of the database.

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:

sudo cat /var/lib/ekm/data/key_backup.info #Thu May 02 12:57:28 UTC 2019 store_file=/home/ubuntu/BR/./EpBackup.jks store_type=JCEKS provider_name=SunJCE store_password=D4505CFCEA...truncated... key_name=EpBackup1 algorithm=RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING

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 EKMClosedEnterprise Key Management - previous name of the product. service configuration folder:

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:

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. It is controlled by the AUDIT level setting.
    • ekm-trace.log - the trace log of the CORE server. It is 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

Similar to ekm-trace.log control and output, CORE requests to external keystores have their log-control and data files.

  • External Keystore Log Control.
  • Capturing the external keystore requests and responses is controlled by the level setting in the extks-log.xml file in Log-control Folder. Applicable levels are: off, info, debug, and trace. The default level is info.

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

    EKM Service Owner Specification

    By default, the EKMClosedEnterprise Key Management - previous name of the product. Service is running on behalf of the following user:

    • Windows:
      The service account UnboundTech. It has a minimal set of privileges required to run the EKMClosedEnterprise 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.
    • Unboundtech user in WIndows