Launch the First Server Pair

CORE cluster deployment starts with the deployment of a foundation pair of servers: Entry Point ("EP") and Partner. Yet if you plan for intensive symmetric key processing, you should include an Auxiliary server to accelerate the symmetric crypto calculation. In such a case, you should Launch the First Server Triplet.

Quickstart on Linux

In the following example, we create a CORE system with one partition and one RSA key.

Step Run on Command
1 EP and Partner

Install the CORE Server software.

sudo rpm -ivh <CORE Server Software>.rpm

2 EP and Partner

Bootstrap the software.

On EP:

Note: This script creates the Root SOClosedSecurity officer - UKC partition administrator role. with credentials (so, Password1!).

sudo /opt/ekm/bin/ekm_boot_ep.sh --self ep1 -p partner1 -f -w Password1!

On Partner:

sudo /opt/ekm/bin/ekm_boot_partner.sh --self partner1 -p ep1 -f

Note
By default, the time gap between the bootstraps should not exceed 30 minutes. To allow longer gap between the bootstraps, use -a (attempts) and/or -t (time between attempts) options in the bootstrap commands. See Bootstrap Parameters.

.3 EP and Partner

Start the EKMClosedEnterprise Key Management - previous name of the product. service. Run once on the EP and once on the Partner.

sudo service ekm start

4 EP

Make sure that the system is up and running.

ucl server test

Continue using UCLClosedUnbound Command Language or jump to Step #7 to switch to UI.

5 EP

Create a CORE partition "test".

Note: The ucl partition create creates the partition's SOClosedSecurity officer - UKC partition administrator role. with credentials (so, Password2!).

sudo ucl partition create -p test --so_password Password2! -w Password1!

6 EP

Create and display an RSA key.

ucl generate -t rsa --name rsa1 -p test
ucl show --name rsa1 -p test

7 EP

Disable client certificate requirement for using UI.

Note: This change of the default system settings releases UI user from owning certificates of the targeted partitions.

ucl system-settings set -k no-cert -v 1 -w Password1!

8 Workstation https://ep1

Bootstrap in Details

The deployment of the CORE cluster foundation server pair requires CORE Server Installation in the selected pair of servers followed by:

  1. Step 1 - Bootstrap the Pair.
  2. Step 2 - Activate the Pair.
  3. Step 3 - Prepare the EP.
  4. Step 4 - Commissioning Test.

Before You Continue

Check the following notes if this is the first time you are running CORE pair bootstrapping.

  • Concurrent Execution
  • EP and Partner must be bootstrapped in parallel to complete their mutual authentication. The order is non-essential.

  • Mutual Server Identity Approval
  • During the parallel bootstrapping of the servers, the administrator of each server is asked to approve the self-signed certificates presented by the other server.

  • Permanent Certificate
  • Once the identities of the participating servers are confirmed, each server receives its permanent (default: 2 yearsClosedFor any time interval setting in years, 1 year is converted to 365 days) certificate signed by the Unbound Root CA.

  • Server Identification in Boot Scripts
  • The bootstrap procedure is done on each server of the pair by running the ekm_boot_<EP-or-Partner> script. The (--self) parameter specifies the running server. The -p parameter specifies its peer server. For example:

    Script --self -p
    ekm_boot_ep EP Partner
    ekm_boot_partner Partner EP
  • Server Endpoint Identification
  • In the script arguments, all servers are identified by their inter-server connection endpoints: <IP address or hostname>[:<port>]. The default port is port 443.

    Note
    The selected identification of each server (IP address or hostname[:<port>] ) must be repeated in all scripts.

  • Optional: EP Server's Alternative Names
  • To create the EP server certificate with additional names and IP addresses in its certificate's subject alternative names list (SANClosedSubject Alternative Names - Certificate field with a list of IP addresses.), use the -n option in the ekm_boot_ep script.

    Note
    You can always update the EP certificate's SANClosedSubject Alternative Names - Certificate field with a list of IP addresses. by using ekm_renew_server_certificate.

Step 1 - Bootstrap the Pair

Note
This topic specifies the bootstrapping of the first pair. To add a pair to a cluster, see Add Server Pair.

In the following example we assume the following:

  • The hostnames of EP and Partner are ep1, partner1.
  • We are bootstrapping all servers using the default port 443.
  • If the [-f] option is omitted you are prompted to approve the certificates presented by the other two servers. See Validation of the Bootstrapping Server.

For the detailed specification of the parameters in the ekm_boot_<server role> scripts, see Bootstrapping Scripts.

Note
By default, the time gap between the bootstraps should not exceed 30 minutes. To allow longer gap between the bootstraps, use -a (attempts) and/or -t (time between attempts) options in the bootstrap commands. See Bootstrap Parameters.

 

Parameter Description
-a Attempts – the number of handshake attempts between the paired servers (default = 2000).
-t Timeout – the duration of a pause between each attempt (default = one second).

Step 2 - Activate the Pair

The bootstrap procedure created the system service (named ekm on Linux and ekmsvc on Windows) on each server. To activate the pair, start this service on both servers:

Step 3 - Prepare the EP

Continue with the following case-specific steps on EP:

  1. If EP is running on Windows:

    Configure the mandatory servers setting in the Client Configuration using the <EP>[:<Port>] value that was used in the ekm_boot_ep.bat command.

    Client Registry

  2. Check UCLClosedUnbound Command Language by running

    ucl diagnose

    The expected response is the name of the server as specified by the --self parameter of the bootstrap. For example, ep1. The absence of the expected name indicates an issue. To fix it, open the Client Configuration and change (or add) the servers= setting.

  3. As needed:

Step 4 - Commissioning Test

To check that the bootstrapped pair is ready to handle CORE service requests, run:

ucl server test

For troubleshooting, see Troubleshooting UCL Server Test.

Troubleshooting

Rerun the Bootstrap

To rerun a bootstrap procedure (for any reason):

  1. Terminate the EKMClosedEnterprise Key Management - previous name of the product. service on both servers.
  2. Clean the Database Folder on both servers.
  3. Rerun steps in the Bootstrap in Details.

Validation of the Bootstrapping Server

The initial certificate of the bootstrapping server is self-signed, and therefore can be forged by man-in-middle. To facilitate manual approval of the integrity and authenticity of the received certificate,

  • The bootstrapping server presents its certificate's thumbprint like this:
  • INFO CREATE_DATA_BASE OK
    INFO GENERATE_KEY_AND_SELF_SIGNED_CERTIFICATE OK
    Self signed certificate generated, thumbprint is D0:0B:1D:E2:4E:94:90:F9:98:CD:C4:69:29:CE:93:01:04:ED:82:6A:8A:64:D3:83:F5:89:A8:13:CB:DA:4B:BC

    This info is visible to the admin of the bootstrapping server.

  • The receiving server recalculates the thumbprint of the received certificate and presents it for the manual approval like this:
  • thumbprint: D0:0B:1D:E2:4E:94:90:F9:98:CD:C4:69:29:CE:93:01:04:ED:82:6A:8A:64:D3:83:F5:89:A8:13:CB:DA:4B:BC
    do you trust this server (Yes/No)? :

    This info is visible to the admin of a server that received this certificate.

  • To compare both values, the approver should contact the sender.

Troubleshooting UCL Server Test

If you completed all steps (including the EKMClosedEnterprise Key Management - previous name of the product. Service start on both servers) using the default ports but failed in the ucl server test, then do the following:

  1. On both servers, restart the EKMClosedEnterprise Key Management - previous name of the product. Service as specified in EKM Service Management.
  2. Make sure the service is running on both servers.
  3. Inspect Tomcat and CORE logs for additional potential errors.
  4. Rerun the ucl server test with the --verbose option to obtain additional clues.
  5. If the cause is a problem in inter-server connectivity, perform the following:
    1. Make sure each server can reach its partner over the default port (443).

      Run telnet <destination> 443 from each server. The expected response is:

      Trying <server>... Connected to <server>.Escape character is '^]'.
    2. If failed getting Connected to <server> message:
      1. Collect the tcpdump on port 443 while running the ucl server test command and examine it.
      2. Examine Firewall interference.
      3. Fix and Launch the First Server Pair.

Customize the Service Port

By default, the CORE server installation enabled ports 443 and 8443 to handle CORE crypto and management requests.

 

To add additional client-facing port(s), perform the following steps on EP server:

  1. Locate and open for editing the Server.xml File.
  2. Locate the <Connector port="443" XML element.
  3. Copy and paste it (everything from "<" to ">").
  4. In the cloned XML element, replace port 443 with the required additional port.
  5. Restart the EKMClosedEnterprise Key Management - previous name of the product. Service (see EKM Service Management).

 

To test the new port, perform the following:

  • Edit Servers Setting in the EP server.
  • Change the port value of the servers=<EP>[:<port>] property to the new port value (e.g., servers=<EP>:6443).
  • Run the ucl server test command.

 

If you completed all steps (including the EKMClosedEnterprise Key Management - previous name of the product. Service restart on both servers) but failed in the ucl server test, then do the following:

  1. Rerun the test with the --verbose option to obtain additional clues.
  2. Restart the EKMClosedEnterprise Key Management - previous name of the product. Service as specified in EKM Service Management and rerun the test.
  3. Run tcpdump on the specified ports to eliminate network-related issues.