Appliance Management Administration

This section is applicable to the KeySafe 5 Appliance Management component of the system. Use a web browser to navigate to https://<node-ip-address>/appliance, where <node-ip-address> is the management IP address to access.

System Configuration

Network Interface Configuration Options

When you install KeySafe 5, you have to specify a valid network connection to make sure the KeySafe 5 node can communicate with other KeySafe 5 nodes. If your network changes or if you want to use multiple NICs (Network Interface Cards), you can update your settings using Manage Network Settings from the Entrust KeySafe 5 System Console on the node whose network settings you want to change.

The Manage Network Settings menu includes the following options:

Option Description

Show Current Network Configuration

Lets you view the current network configuration for the node. If the node has multiple NICs, this option allows you to select which NIC configuration you want to view.

Manage IP Address Settings

Lets you change the current network configuration. If the node has multiple NICs, this option allows you to select which NIC configuration you want to change. For details, see Multi-NIC Node Configuration.

Disable a Network Interface

If the node is configured with multiple NICs, this option lets you remove one or more NICs from the configuration. For details, see Removing a NIC from the Configuration.

Note: You cannot remove the management interface.

Manage DNS Settings

Lets you view and update your current DNS Settings. For details, see Configuring DNS Settings.

Manage NTP Settings

Lets you view and update your current NTP Settings. For details, see Configuring NTP Settings.

Manage Static Routes

Lets you add static routes for the KeySafe 5 node for environments where dynamic routing is not the optimal solution. For details, see Configuring Static Routes.

Network Diagnostic Tools

Lets you troubleshoot network issues. For details, see Troubleshooting Network Issues.

Multi-NIC Node Configuration

If you want to segregate the communication traffic across multiple channels, you can configure a KeySafe 5 node to use multiple virtual NICs (Network Interface Cards). For example, you may want one NIC to handle the communication between the KeySafe 5 Appliance Management UI and the KeySafe 5 nodes on TCP/443 while a second NIC handles the cluster traffic and the internal node management traffic on TCP/8443.

With multiple NICs, one NIC must be designated as the "management interface", and this interface must be able to communicate on port TCP/8443. KeySafe 5 uses the internal node management interface to:

  • Determine the administrative MAC address for the node.

  • Initializes the communication traffic between the nodes in the cluster.

  • Handle any authentication requests that come into the cluster.

All management interface communication must take place on the management interface. You cannot split management communication across multiple interfaces.

Considerations

When you are configuring multiple NICs on a node, keep the following things in mind:

  • KeySafe 5 supports a maximum of four virtual NICs. One NIC must be the management interface, as described above. In addition to the management interface, you can specify up to three additional NICs that can be used for inbound and outbound traffic. This includes inbound client and KeySafe 5 Appliance Management UI traffic as well as outbound syslog, NFS, and email traffic.

  • All NICs must be of the same interface adapter type. For example, if the first NIC specified uses the adapter type VMXNET, all other NICs must be of type VMXNET.

  • All NICs use global values for their DNS settings, NTP settings, default gateway, and DNS server list. Any change made to those settings on one NIC affects all NICs.

  • When you deploy a new KeySafe 5 node through an OVA template, you must specify basic network information such as an IP address, domain, gateway, and DNS server list. When you do so, KeySafe 5 automatically designates that IP address as the management interface on port TCP/8443. We strongly recommend that you do not change this interface if the node is already part of a cluster.

  • Adding additional NICs to the VM after deployment requires you to shut down the KeySafe 5 node while you add the NICs. You cannot add NICs to a running system.

  • If the node is part of a cluster, the cluster will become degraded if the node is unreachable for too long.

  • KeySafe 5 automatically restarts the network services on the node every time you change the configuration for a NIC. The node will be unavailable for a brief period until this process has finished.

Configuring Multiple NICs on an Existing KeySafe 5 Node

When you deploy a new KeySafe 5 node, you configure the management interface during that process. We strongly recommend that you do not change this interface after you have deployed the node if the node is part of a cluster.

The following procedure describes how to add and configure additional NICs on an already-deployed node. For details about deploying a new KeySafe 5 node, see OVA Installation Guide.

During the following procedure, the node will be unavailable at certain points. If the node is part of a cluster, the cluster will become degraded if the node is unreachable for too long.

In addition, if the node is part of a cluster and you want to change the management interface, you must remove the node from the cluster first.

  1. If the additional NICs you want to use have not yet been configured on the VM in which the KeySafe 5 node is running, do the following:

    1. If the KeySafe 5 node is powered on, shut it down using your hypervisor or the node’s Entrust KeySafe 5 System Console. For details, see Using the Entrust KeySafe 5 System Console.

    2. In your hypervisor, add the new NICs to the KeySafe 5 VM and configure them using your corporate standards.

      Make sure that the new NICs use the same adapter type as the existing NICs. For example, if the management interface NIC is of type VMXNET, the new NICs must be of type VMXNET as well.

    3. Make a note of the MAC address you are using for each NIC. When the NICs are displayed in KeySafe 5, they are identified by their MAC address. Therefore, when you go to configure the NIC in KeySafe 5 later in this procedure, you will need to know its MAC address.

    4. Power on the KeySafe 5 VM.

  2. Log in as htadmin on the KeySafe 5 node whose NICs you want to configure.

    KeySafe 5 displays the Entrust KeySafe 5 System Console TUI (Text-based User Interface).

  3. Select Manage Network Settings.

  4. Select Manage IP Address Settings.

  5. On the Interfaces screen, select the NIC you want to configure and press Enter.

    The NIC that is the current management interface has 'Current management interface' listed after the name. We strongly recommend that you do not change this interface after deployment if this node is part of a KeySafe 5 cluster. If you select the management interface, acknowledge the configuration request at the prompt.

  6. On the Secondary Network Configuration screen, specify the static IP address and netmask for the KeySafe 5 node.

    • Changing the hostname on one NIC changes it for all NICs, including the management interface NIC. If this node is part of a cluster, you should not change the hostname for the node.

    • All NICs must use the same default gateway and DNS server list.

    • Make sure you specify a static IP address and netmask for the KeySafe 5 node.

  7. When you have finished specifying the network information, select OK and press Enter.

    KeySafe 5 restarts the network services using the new configuration. Contact with the node via the KeySafe 5 Appliance Management UI will be unavailable until the restart is finished.

    When the network finishes restarting, KeySafe 5 displays the Entrust KeySafe 5 System Console.

  8. Repeat the proceeding steps for any other NICs you want to configure. KeySafe 5 will restart the network services and the node will be unreachable for a short time after each configuration change.

  9. If you want to verify the configuration information, select Manage Network Settings. From there, select Show Current Network Configuration to view a list of the configured NICs with their IP addresses and netmasks. The management interface IP address is shown as the main interface. Any additional interfaces that are configured are shown below.

Removing a NIC from the Configuration

If you want to remove a NIC that you have previously configured, you should use the Entrust KeySafe 5 System Console to disable that NIC in KeySafe 5 before you remove it from the VM.

In addition, if this node is part of a cluster we recommend that you remove it from the cluster before you remove the NIC. You can then re-join it with the cluster after the network configuration is complete.

This option is not reversible and it requires the node to reboot.

  1. Log in as htadmin on the VM whose NIC you want to remove.

    KeySafe 5 displays the Entrust KeySafe 5 System Console TUI (Text-based User Interface).

  2. Select Manage Network Settings.

  3. Select Disable Network Configuration.

  4. Select the interface you want to disable.

    You cannot disable the management interface, so KeySafe 5 does not show that interface in the list.

  5. Confirm at the prompt.

  6. Press Enter to reboot the node.

  7. If desired, select Shutdown System and then use your hypervisor to remove the NIC from the VM.

Configuring DNS Settings

  1. Use your hypervisor to access one of the VMs in which KeySafe 5 is running, then log into the KeySafe 5 VM console as htadmin.

    KeySafe 5 displays the Entrust KeySafe 5 System Console TUI (Text-based User Interface).

  2. From the Entrust KeySafe 5 System Console, select Manage Network Settings > Manage DNS Settings.

  3. On the Modify DNS Settings page, you can view your existing DNS settings. Select one of the following:

    • No — Exits the screen and returns to the Manage Network Settings page.

    • Yes — Opens the Network Configuration screen. Enter a comma-separated list of DNS addresses. Select Ok to save and then Yes on the confirmation screen. If you decide not to make changes, select Cancel to return to the Manage Network Settings page.

Configuring NTP Settings

  1. Use your hypervisor to access one of the VMs in which KeySafe 5 is running, then log into the KeySafe 5 VM console as htadmin.

    KeySafe 5 displays the Entrust KeySafe 5 System Console TUI (Text-based User Interface).

  2. From the Entrust KeySafe 5 System Console, select Manage Network Settings > Manage NTP Settings.

  3. On the Modify NTP Network Settings page, you can view your existing NTP settings. Select one of the following:

    • No — Exits the screen and returns to the Manage Network Settings page.

    • Yes — Opens the Network Configuration screen. Enter a comma-separated list of NTP addresses. Select Ok to save and then Yes on the confirmation screen. If you decide not to make changes, select Cancel to return to the Manage Network Settings page.

Configuring Static Routes

In some network environments, it may be necessary to add static routes to KeySafe 5 rather than relying on dynamic routing.

  1. Use your hypervisor to access one of the VMs in which KeySafe 5 is running, then log into the KeySafe 5 VM console as htadmin.

    KeySafe 5 displays the Entrust KeySafe 5 System Console TUI (Text-based User Interface).

  2. From the Entrust KeySafe 5 System Console, select Manage Network Settings > Manage Static Routes.

  3. From the Static Routes page, you can:

    • View a list of the defined routes by selecting List Current Static Routes.

    • Add a new route by selecting Add Static Route and entering the route network address and gateway in the Add Static Route page. KeySafe 5 displays a message that the route has been successfully added.

    • Delete a previously-defined static route by selecting Delete Static Route and specifying the network address and gateway of the route you want to delete. KeySafe 5 displays a message that the route has been deleted.

Configuring SSL Settings

Because each node hosts a standalone webserver, if you want to configure the SSL settings for a node you must log into the KeySafe 5 Appliance Management UI for that specific node.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the General Settings section, click SSL Configuration.

  4. On the Protocol tab, select the TLS authentication modes that you want to use (TLSv1.3 is not supported in the KeySafe 5 OVA):

    • TLSv1.0, TLSv1.1, TLSv1.2

    • TLSv1.0, TLSv1.2

    • TLSv1.2 only

  5. Optionally, on the Cipher Suite tab, review the detailed list of available ciphers. If you want to remove ciphers from this list, click the X following the cipher name that you do not want to use. If you want to add a cipher, click in the bottom of the list box and enter a valid cipher name, then click Reload.

  6. When you are finished, click Apply.

Setting Email Server Preferences

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the General Settings section, click Mail Server.

  4. On the Mail tab, specify the options you want to use.

    Option Description

    Disable E-mail Notifications check box

    If checked, no alert emails are sent to the user accounts in the system. If the Admin Key is regenerated, all security admins must manually download their key parts from the Settings tab.

    If this option is not selected, KeySafe 5 only sends alerts and new Admin Key parts through email. Security Admins can still download their Admin Key parts from the KeySafe 5 Appliance Management UI.

    For details about the Admin Key, see Admin Keys.

    Server

    The IP address or fully qualified domain name (FQDN) of the SMTP server.

    If your domain has an MX record configured, you can use KeySafe 5 to relay mail by setting the IP address to 127.0.0.1. This is the default behavior.

    Port

    The mail server port.

    Login

    If required, the user account with which KeySafe 5 should log into the email server.

    Password

    The password for the login account.

    Sender

    The sender that KeySafe 5 should use when sending email.

    SMTPS

    If this option is set to On, KeySafe 5 uses SMTP Secure (SMTPS).

    Important information such as alerts and admin keys are shared by email. Entrust highly recommend you set this option to use encryption with SMTP.

  5. To test the email settings, click Send Test Email.

Setting KeySafe 5 Console Settings

If you do not remember the credentials of any user with the Security Administrator (secroot) privilege, or if you are locked out of the KeySafe 5 Appliance Management UI, KeySafe 5 provides a self-service option using the KeySafe 5 System Console to reset the (secroot) user credentials with a temporary password. You can disable this option if you do not want this feature.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the System Settings section, click KeySafe 5 Console Settings.

  4. On the KeySafe 5 Console Settings page, select one of the following:

    • Select YES to allow the htadmin user to reset the secroot password.

    • Select NO if you do not want to allow the htadmin user to reset the secroot password.

  5. Click Apply.

KeySafe 5 Certificates

KeySafe 5 requires that an SSL certificate be installed on each KeySafe 5 node in a cluster. Each KeySafe 5 instance is installed with two web servers:

  • An internal web server that manages the KeySafe 5 node to node cluster communication on port 8443.

  • An external web server that manages the KeySafe 5 Web UI, the REST API interface, and the Policy agent communication on port 443.

By default, KeySafe 5 includes a component for creating a Root Certificate Authority (CA) that can generate digital certificates. When the first KeySafe 5 node is installed, it creates a Private and Public CA that it also stores in the KeySafe 5 object store.

The first KeySafe 5 node then uses the Private CA to create an SSL certificate that contains the hostname (FQDN) as well as the IP address of the KeySafe 5 node for the internal web server and Public CA to create an SSL certificate that contains the hostname, both short and FQDN, as well as the IP address of the KeySafe 5 node for the external web server. When the node reboots, KeySafe 5 checks the IP address and recreates the SSL certificate if the IP address has changed.

KeySafe 5 node to node communication is on a TLS channel and it uses SSL certificates issued by Private CA to secure communication. When additional KeySafe 5 nodes are added to the cluster, the first KeySafe 5 node shares the Private and Public CA through the KeySafe 5 object store over an HTTPS connection.

In this scenario, the Public CA installed on all the KeySafe 5 nodes is the same, ensuring that every KeySafe 5 node is able to verify SSL certificates generated by every other KeySafe 5 node in the cluster. However, this default OVA Internal CA signed SSL certificate is considered self-signed, which can lead to trust issues.

Viewing the Expiration Date for the Current KeySafe 5 SSL Certificate

It is critical to keep the KeySafe 5 certificate current.

Use the following procedure to view the expiration date for the current KeySafe 5 certificate on the selected KeySafe 5 node.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Click the Servers tab and select a KeySafe 5 node.

  4. To view the SSL certificate configured for the internal web server, click the link next to Internal Web server in the Certificate detail.

    The link name is Default if the internal web server is using the default OVA Internal CA signed certificate and Custom if it is using a custom SSL certificate.

  5. To view the SSL certificate configured for the external web server, click the link next to External Web server in the Certificate detail.

    The link name is Default if the external web server is using the default OVA Internal CA signed certificate and Custom if it is using a custom SSL certificate.

  6. When you are done, click Close.

  7. If you want to check the expiration date for the certificate on another KeySafe 5 node, select that node and repeat this procedure.

Creating a Certificate Signing Request

A certificate signing request (CSR) tells an external Certificate Authority (CA) that you want an SSL certificate generated and signed by that CA. The SSL certificate can then be uploaded to KeySafe 5 and used in place of the default self-signed certificate.

When you use KeySafe 5 to create the CSR, KeySafe 5 creates a key pair and uses that key pair in conjunction with the information you specify to create the CSR. KeySafe 5 then encrypts the key pair and stores it for later use.

You can use the resulting CSR to generate an SSL certificate from the external CA you want to use. After you receive the SSL certificate from that external CA, you can upload it to KeySafe 5. Because the key pair already exists on the system, you do not need to upload anything else.

If you create the CSR to generate an SSL certificate to be installed for internal web server, you must include the IP address of the KeySafe 5 node in Subject Alternative Name.

If you create the CSR outside of KeySafe 5, you need to upload both the SSL certificate and the matching private key file when you install the certificate on KeySafe 5.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Click the Servers tab and select a KeySafe 5 node.

  4. Select Actions > Create CSR.

  5. In the Generate Certificate Signing Request dialog box, specify the options you want to use.

    Field Description

    Common Name

    The name to associate with this request. By default, KeySafe 5 enters the selected server name in this field. You can edit the default name as needed.

    Locality

    The locale to associate with this request.

    State

    The state to associate with this request.

    Subject Alternative Names

    The host names that will be protected by this certificate. If you want to use the same certificate on multiple KeySafe 5 nodes in the system for the external web server, add all of the KeySafe 5 URLs to this list.

    By default, KeySafe 5 adds the URL of the selected KeySafe 5 node. You can change or delete the default URL as long as you end up specifying at least one KeySafe 5 node in this field.

    Key Size

    Select the key size that you want to use. The default is 4096 bytes.

    Country

    The country to associate with this request. The default is US.

    Organization

    The organization to associate with this request.

    Organization Unit

    The organizational unit associate with this request.

  6. Click Generate.

  7. When you receive the message that KeySafe 5 has created the CSR, click Download to save a copy of the CSR to your browser’s default download directory or click Preview to view the CSR in a pop-up window. You can copy the CSR from the Preview window to the clipboard if desired.

  8. Use the CSR to request an SSL certificate from the external Certificate Authority you want to use. How you do this depends on the CA you are using.

After you receive the SSL certificate from the external CA, install it on KeySafe 5 as described in Installing a New External Certificate.

Installing a New External Certificate

Use this procedure to replace the current KeySafe 5 SSL certificate with a new externally-signed SSL certificate. If you want to use a new, OVA Internal CA signed ("self-signed") SSL certificate generated by the Public CA or Private CA included with KeySafe 5, see Installing a New OVA Internal CA signed Certificate.

Before You Begin

  • If you generated the Certificate Signing Request (CSR) through KeySafe 5, you need to make sure you have the resulting SSL certificate and the CA certificate in Base64-encoded pem format files accessible to the KeySafe 5 node that you are logged into. If you generated the CSR through some other means, make sure you have both of the Base64-encoded pem format certificates and the Base64-encoded pem format private key file that goes with the certificates. KeySafe 5 supports only RSA private keys. For more information, see Creating a Certificate Signing Request.

  • If you generated the SSL certificate from OpenSSL or other third-party tool, make sure the certificate is formatted as a web server certificate.

  • The SSL certificate generated for the internal web server should be able to function as the Client and Server certificate.

  • SSL certificates that contain an intermediate CA certificate chain are not supported for the internal web server. If there is a certificate chain, it must be specified in the CA certificate for the internal web server.

Procedure

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Click the Servers tab and select a KeySafe 5 node.

    You can use SSL certificates signed by different certificate authorities on individual KeySafe 5 nodes. However, Entrust recommends that all of the SSL certificates be signed by the same Certificate Authority so that only one CA certificate is required to be trusted.

  4. Select Actions > Install Certificate.

  5. In the Certificate tab of the Certificate Installation dialog box, specify the options you want to use.

    Field Description

    SSL Certificate

    The SSL certificate file in Base64-encoded pem format. This certificate must be valid for the installation to succeed.

    CA Certificate

    The certificate of the CA that issued the SSL certificate in Base64-encoded pem format.

    Web Server

    Choose which web server to install the custom certificate. You can select both if you wish to install the same SSL certificate for the internal and the external web server. If the SSL certificate is used for both web servers, it should be able to function as a Client and Server certificate and it should have the KeySafe 5 IP address specified in SAN.
    Before KeySafe 5 installs the certificate, it checks with the certificate authority to make sure that the SSL certificate can be validated. If the CA certificate file you are uploading for the external web server contains just the certificate of the root certificate authority, make sure that the SSL certificate file contains the entire chain of intermediate CA certificates as well as the SSL certificate for the selected KeySafe 5 node.

  6. If you did not create the certificate signing request with KeySafe 5:

    1. Click the Private Key tab and click Load File, then navigate to the private key file you want to use. KeySafe 5 never stores the private key in clear text.

    2. If the private key file is encrypted, enter the user-specified password for the key file in the Password field. This password is not stored in the KeySafe 5 object store or on the local file system.

  7. Click Install Certificate.

  8. If you install the SSL certificate for the internal web server, the web server automatically restarts.

    If you install the SSL certificate for the external web server, when the installation is complete, click Restart Web Service or select Actions > Restart Web Service and confirm the request at the prompt.

    After the web service restarts, KeySafe 5 will use the new certificate.

    KeySafe 5 restarts the web server which may interrupt the browser connection to the KeySafe 5 Appliance Management UI. When the restart is finished you are returned to the KeySafe 5 Appliance Management UI login page.

    If you are using Chrome, the connection status in your browser may still show as insecure. To fix this, open the KeySafe 5 Appliance Management UI login page in a new tab.

  9. If you want to verify that the new certificate was properly installed, select the node and click the link next to Internal/External web server.

    If you already have custom certificate installed for external web server and the KeySafe 5 internal web server uses a default self signed SSL certificate, KeySafe 5 automatically detects and provides an option to use the same custom SSL certificate for internal web server if it meets the certificate requirements of internal web server. Select Use external Web server SSL certificate for internal Web server and click Save to install the same custom SSL certificate for the internal web server.

    If you already have custom certificate installed for internal web server and the KeySafe 5 external web server uses a default self signed SSL certificate, KeySafe 5 automatically detects it and provides an option to use the same custom SSL certificate for the external web server if it meets the certificate requirements of an external web server. Select Use internal Web server SSL certificate for external Web server and click Save to install the same custom SSL certificate for internal web server. When the installation is complete, click Restart Web Service or select Actions > Restart Web Service, then confirm the request at the prompt. After the web service restarts, KeySafe 5 will use the custom SSL certificate for external web server.

Installing a New OVA Internal CA signed Certificate

Use this procedure to replace the current KeySafe 5 certificate configured on internal or external web server with a new certificate signed by the certificate authority that is included with KeySafe 5.

If you want to install an externally-signed SSL certificate from a Base64-encoded pem format file, see Installing a New External Certificate.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Click the Servers tab and select a KeySafe 5 node.

    You can use a different certificate on each KeySafe 5 node. In this case, however, Entrust recommends that all of the certificates be signed by the same Certificate Authority.

  4. Select Actions > Use Self-Signed Certificate.

  5. Select the web server on which the certificate is to be installed.

  6. Click Proceed at the prompt.

    If you select the external web server, KeySafe 5 restarts the web server. This may interrupt the browser connection to the KeySafe 5 Appliance Management UI. When the restart is finished, you are returned to the KeySafe 5 Appliance Management UI login page.

  7. If you want to verify that the new certificate was properly installed, select the node and click the link next to Internal/External web server.

Admin Keys

All KeySafe 5 data (policy information, user account information, and so on) are held in an encrypted object store that is shared across all KeySafe 5 nodes in the cluster.

The object store is ultimately protected (through multiple layers of key wrappings) by an Admin Key that KeySafe 5 generates and maintains. This key is required if you ever need to restore KeySafe 5 from a backup or you need to change the hardware configuration of a KeySafe 5 node.

When you install the first KeySafe 5 node in your system, KeySafe 5 generates an Admin Key as soon as you log into the KeySafe 5 Appliance Management UI for the first time. The initial key has a single part and is assigned to the default secroot user account. As you add additional Security Administrator accounts to the system, KeySafe 5 shifts to an "n of m" Admin Key backup model, where "m" is the number of user accounts with Security Admin privileges and "n" is a user-defined value that states how many key parts must be uploaded before KeySafe 5 considers the Admin Key to be valid.

For example, if you have five Security Admins and you set n to 3, then at least three of the Security Admins will need to upload their Admin Key parts in order to restore KeySafe 5 from a backup. If you set n to 1, then any one of the five Security Admins can restore KeySafe 5 without consulting with any of the other Security Admins.

While you can regenerate Admin Key parts at any time, in order to restore KeySafe 5 from a backup image you must have the required number of Admin Key parts that were valid when the backup was created. You cannot regenerate the Admin Key parts and then immediately use those new key parts to restore KeySafe 5 from a previously-created back up.

The Admin Key is assigned a generation count that is incremented each time a new Admin Key is generated. This generation count allows you to identify which Admin Key parts go together. The email that each Security Admin receives when a new Admin Key is generated contains the generation count. For example:

This current Key Part supersedes any you may have previously received from this cluster. The Key Part is associated by a "generation count" with its relevant backups. The generation count for this key is: 8

The generation count is also included in the Admin Key Part filename, which is attached to the email. The attachment name is username_kc-ip-addr.key.gen#, where username is the Security Admin’s KeySafe 5 account name, kc-ip-addr is the KeySafe 5 IP address from which the Admin Key was generated, and # is the generation count. For example, secroot_10.238.66.235.key.gen8. This same naming convention is used if a Security Admin downloads their Admin Key Part from the KeySafe 5 Appliance Management UI.

If you want to restore KeySafe 5 from a backup created when the Admin Key shown above was valid, you must make sure that all the Admin Key Parts you upload have generation count = 8.

Generating the Admin Key

When KeySafe 5 generates an Admin Key, it cryptographically divides the key into parts and sends one part to each KeySafe 5 user account with Security Admin privileges.

KeySafe 5 automatically generates new Admin Key:

  • During installation of the first KeySafe 5 node. In this case, the secroot user account gets an Admin Key with a single part.

  • When a Security Admin user account is added or deleted. In this case, a new Admin Key is divided into a new number of parts, "m", and sent to all current Security Admins.

    The value of "n" is not changed. If you add three Security Admins immediately after the initial installation, the Admin Key will be divided into four parts, but only one part will be required when restoring the system. The way you set the required number of parts is described below.

  • When you explicitly generate a new Admin Key, as described below. In this case, the number of Admin Key parts is not changed.

Whenever the admin key is regenerated, KeySafe 5 forces you to download the admin key.
Procedure

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the General Settings section, click Admin Key Parts.

  4. Verify the following options:

    Option Description

    Minimum Key Parts

    The minimum number of parts needed when you want to restore KeySafe 5 from a back up ("n").

    Email Private Key on Generate

    If Enabled, when you generate a new Admin Key, KeySafe 5 automatically sends each Security Admin their key part as an email attachment. The attachment name is username_kc-ip-addr.key.gen#, where username is the Security Admin’s KeySafe 5 account name, kc-ip-addr is the KeySafe 5 IP address into which you are currently logged in, and # is the generation count.

    For example, secroot_10.238.66.235.key.gen8.

    If Disabled, when you generate a new Admin Key, KeySafe 5 sends each Security Admin an alert stating that the admin key has been changed and prompting them to download their key part.

  5. Click Generate New Key. KeySafe 5 increases the generation count by one and creates a new key part for each Security Admin in the system. If you have configured an EKS, KeySafe 5 also saves the Admin key to the EKS.

    Based on the setting of the Email Private Key on Generate option, KeySafe 5 also sends each Security Admin in the system an email with their key part or an alert stating that there is a new key part ready for download.

    If you intend to back up KeySafe 5 in the immediate future, we recommend that you notify your Security Admins that the new Admin Key part they just received is going to be tied to a backup image and they should download it to a secure location immediately. You cannot restore KeySafe 5 from a backup image unless you have the Admin Key parts that were valid when the back up was created, and you cannot download previous Admin Key parts from KeySafe 5.

  6. Click Close.

Downloading Your Admin Key Part

Every user account with Security Admin privileges receives an encrypted Admin Key part. Certain KeySafe 5 functions, such as restoring the system from a backup, require that a certain number of parts be uploaded to KeySafe 5 within a certain amount of time. Once KeySafe 5 receives the correct number of parts, it can validate the Admin Key and perform the requested procedure. Once you download your key part, make sure you store it securely and that you can find it when needed.

You also need to keep previous Admin Key parts and know when each part was created. If you need to restore a system from a previous backup, you must have the key parts that were valid when that backup was created. If the Admin keys have been regenerated, you cannot download the current Admin Key parts and use those to restore a previous version of KeySafe 5.

  1. Log into the KeySafe 5 Appliance Management UI with your standard account credentials.

  2. In the top menu bar, click Settings.

  3. In the Account Settings section, click Download Key. KeySafe 5 downloads a file to your browser’s default download location called username_kc-ip-addr.key.gen#, where username is the currently logged in KeySafe 5 account name, kc-ip-addr is the KeySafe 5 IP address into which you are currently logged in, and # is the generation count. For example, secroot_10.238.66.235.key.gen8.

  4. If you want to remove the Admin Key part from the KeySafe 5 encrypted object store, click Clear Key. If you later attempt do download the key part after clearing it, you will get an error stating that the key part does not exist. You will need to regenerate the key as described in Generating the Admin Key.

Using the Entrust KeySafe 5 System Console

When you log into the KeySafe 5 VM console as htadmin, KeySafe 5 displays the Entrust KeySafe 5 System Console. This menu lets you configure the local KeySafe 5 server. In general, the changes you make here do not apply to any other KeySafe 5 node in the cluster.

The menu is a TUI (Text-based User Interface). You navigate through the TUI using the Tab key to move between fields and pressing Enter when the correct choice is highlighted. If the TUI screen has numbers at the start of the line, you can also press the corresponding number key and then press Enter to navigate through the menus.

To return to the main Entrust KeySafe 5 System Console screen, press Esc (Escape). Based on where you are in the menus, you may need to press Esc several times.

The Entrust KeySafe 5 System Console contains the following options:

Option Name Description

1

Manage Network Settings

View or change the current network configuration.

2

Manage htadmin and SSH Access

Manage the htadmin account for this KeySafe 5 node and enable or disable access to the Entrust KeySafe 5 System Console via SSH.

3

Manage Accounts

Enable or disable the full support login account (htsupport), the restricted login account (htrestricted), or the KeySafe 5 webGUI default account (secroot).

4

Manage HSM Client Account

Not applicable for this version of KeySafe 5

5

Download Internal Certificate

Download the Entrust-generated CA certificate being used on this KeySafe 5 node so that you can add that certificate to your web browser as a trusted site.

6

Gather Diagnostic Logs

Creates a support bundle with diagnostic information and log files that Entrust Support can use to diagnose issues with your KeySafe 5 cluster.

7

Manage KeySafe 5 Node

Allows you to delete internal snapshots created automatically during upgrade.

8

Reboot or Shut Down KeySafe 5 Node

Reboots or shuts down the current KeySafe 5 node. If you plan to remove the node from the cluster or decommission it, see Removing a KeySafe 5 Node from a Cluster or Decommissioning a KeySafe 5 Node.

9

Manage Timeouts and Appearance

View or change the current timeout for the Entrust KeySafe 5 System Console. After this period of time elapses with no user input, KeySafe 5 closes the Entrust KeySafe 5 System Console and returns to the system login prompt. This option also lets you toggle the 3D appearance for the Entrust KeySafe 5 System Console.

10

Quit TUI Session

Close the Entrust KeySafe 5 System Console and return to the system login prompt.

Authentication

KeySafe 5 access can be authenticated in the following ways:

  • OpenID Connect, KeySafe 5 supports user authentication through integration with an OpenID Connect provider. If a provider is configured, the KeySafe 5 login dialog contains not only the Sign In button but also a configurable button to start the authentication process using the provider.

  • Locally, with a password stored in KeySafe 5. KeySafe 5 Security Admins can configure the password requirements and expiration options, as well as the maximum number of login attempts that are allowed before the KeySafe 5 account is disabled and an expiration date after which the account will be automatically disabled.

    Entrust does not recommend this option. This option means that the KeySafe 5 UI and its API will be unauthenticated.

Configuring Local Authentication Settings

This procedure describes how to configure the password and account security options for all locally-authenticated KeySafe 5 managed user accounts.

Entrust does not recommend this option. This option means that the KeySafe 5 UI and its API will be unauthenticated.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the General Settings section, click Authentication.

  4. In the Type drop-down, select Local (Password).

  5. On the Basic tab, change the options as desired, then click Apply when finished.

    Field Description

    Password Expiration

    The maximum number of days that a password can be used before it expires. KeySafe 5 also uses this value to calculate the default password expiration date when a new local KeySafe 5 user is created. (Default: 60)

    Once a password expires, the user is prompted to change their account password the next them they log into the KeySafe 5 Appliance Management UI.

    Max Failed Logins

    The number of failed login attempts allowed before the user account is locked. (Default: 5)

    If the maximum number of logins is exceeded, the next time the user attempts to log in they receive a message informing them that the account is disabled and telling them to talk to a Security Administrator.

    The Security Administrator must then re-enable the account as described in Re-enabling a KeySafe 5 managed User Account.

    Minimum Previous Passwords

    The number of unique new passwords that must be associated with a user account before an old password can be used. (Default: 5)

  6. On the Strength tab, click the desired value to change the setting, then click Save when finished. If you change one of these settings, KeySafe 5 applies the new requirements to any new passwords created for a KeySafe 5 account. It does not apply the requirements to any existing KeySafe 5 account passwords.

    Field Description

    Minimum Password Length

    The minimum number of characters that must be in a password. (Default: 8)

    Minimum Uppercase Characters

    The minimum number of characters that must be upper case. (Default: 1)

    Minimum Special Characters

    The minimum number of characters that must be something other than a-z, A-Z, or 0-9. (Default: 1)

    Minimum Lowercase Characters

    The minimum number of characters that must be lowercase. (Default: 1)

    Minimum Required Digits

    The minimum number of characters that must be numeric. (Default: 1)

  7. When you are finished, click Close

Re-enabling a KeySafe 5 managed User Account

A KeySafe 5 managed user account can become disabled for the following reasons:

  • The number of consecutive unsuccessful login attempts has exceeded the value set for Max Failed Logins. For more information, see Configuring Local Authentication Settings.

  • A KeySafe 5 Security Admin has manually disabled the account.

  • The expiration date associated with the account has passed.

  • The Account Enabled check box was not selected when the user account was created.

If you cannot log into any KeySafe 5 accounts with Security Admin privileges, contact Entrust Support.
Procedure

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Security.

  3. Select the account you want to re-enable in the list. The KeySafe 5 Appliance Management UI displays the details for the selected account below the table.

  4. In the Account Status field, click Disabled.

  5. Check the Enabled? check box and click Save.

  6. Verify the expiration date in the Account Expiration field.

  7. To change the account password, click the Authentication tab then click Change Password.

Your changes take effect immediately.

Configuring an OpenID Connect Provider

KeySafe 5 supports user authentication through an OpenID Connect provider. If a provider is configured, the KeySafe 5 login dialog contains not only the KeySafe 5 Sign In button but also a configurable button to start the authentication process using the provider.

Before You Begin

The OpenID Connect provider must be configured to accept the KeySafe 5 URLs. Each login dialog requires both a login and a logout URL, so for KeySafe 5, you have to configure numerous URLs for each node in the cluster. You have to configure the login and logout URL for KeySafe 5 itself.

In the following example of URL list for OpenID Connect provider, <node-ip-address> is the hostname or IP address of the KeySafe 5:

Login:

  • https://<node-ip-address>/callback

  • https://<node-ip-address>/keysafe5

  • https://<node-ip-address>/v5/oidc/callback

Logout:

  • https://<node-ip-address>/callback

  • https://<node-ip-address>/keysafe5

  • https://<node-ip-address>/v5/kc/oidc/logout

Procedure

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the Type drop-down, select OpenID Connect.

Specify the options you want to use. When you are done, click Apply.

Field Description

Client ID

The organizational identity assigned by the OpenID Connect provider when you sign up for the service.

Client Secret

A cryptographic component used to secure the organization’s access to the OpenID Connect provider. Client Secret is mandatory for Authenticated Flow and optional for PKCE Flow.

This field is write-only. It will never be displayed again after it has been initially created. It can be reentered if necessary.

Base URL

The URL that KeySafe 5 will use to contact the OpenID Connect provider to present the login page.

Name

A user-defined name for the OpenID Connect provider. KeySafe 5 displays this name on the button on the login dialogs.

Only one global OIDC provider can be configured per KeySafe 5 cluster.

KeySafe 5 Cluster Maintenance

KeySafe 5 Nodes and Clusters

When you install KeySafe 5, the process creates a KeySafe 5 node that can operate singly or be joined with other KeySafe 5 nodes to form an active-active cluster. These nodes can be installed in different geographic locations, but they must be able to communicate with each other.

All KeySafe 5 nodes in a cluster share configuration settings, and data. Changes made on one node are automatically synced to all nodes in the cluster through an encrypted object store. This provides a failover mechanism in case a KeySafe 5 node becomes unreachable.

The KeySafe 5 nodes constantly exchange heartbeats to verify that every node in the cluster is reachable. If all nodes respond to the heartbeats, the cluster is considered "healthy". If one or more nodes stop responding for a given length of time, the cluster is considered "degraded". If a cluster is degraded, the active KeySafe 5 nodes can still serve requests but you cannot make changes to the nodes in the cluster.

The heartbeat interval and status thresholds are user-configurable for the cluster. For details, see Setting Cluster Options.

Viewing the Cluster Status

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, look at the Cluster icon. If there is a green heart, the cluster is healthy. If there is a red X, the cluster is degraded. You can also look at the Status field on the Cluster tab.

  3. To view the status of the individual servers in the cluster, click the Servers tab. The Status column shows the status for each server in the cluster:

    Field Description

    Maintenance

    Same as cluster status, going through rolling upgrade.

    Offline

    Unreachable and unavailable

    Online

    Reachable and available.

    Unavailable

    Server to server connection works but the KMIP Database is unavailable (port 5432).

    Unreachable

    Unable to connect to the server (port 8443).

  4. A yellow star appears before the server name of the node that has been designated as the database master node. The other nodes in the cluster are replica nodes.

Setting Cluster Options

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster and specify the options you want to use.

    Option Description

    Description

    A user-defined description for the cluster.

    Status

    The status of the cluster. If this is Healthy, all KeySafe 5 nodes are functioning normally. If this is Degraded, KeySafe 5 can still serve requests but you cannot make changes to the nodes in the cluster.

    Group Administrator

    The KeySafe 5 administration group to which this cluster belongs. You cannot change this field.

    Backup Hosts

    The hostnames or IP addresses of systems that are allowed to access the KeySafe 5 backup directory through NFS. (0.0.0.0 means any server can have access)

    Any time you back up KeySafe 5, it automatically stores the backup file in a folder called /hcs/backup. If you issue an NFS mount command to that directory from another server, you can access any of the backup files. Make sure these backup images are securely stored in case you ever need to restore KeySafe 5.

    Backup Over NFS

    Whether backup over NFS is enabled. (Default: disabled)

    Cluster Operation Timeout

    The amount of time that a KeySafe 5 node waits to receive a response from another KeySafe 5 node. If a response is not received by the specified timeout, the KeySafe 5 cluster goes into degraded mode, which indicates a network connectivity problem.

    Enter a value between 1 and 30 seconds. (Default: 5 seconds)

    If a KeySafe 5 cluster frequently switches between degraded state and healthy state, you can increase this timeout. We recommend, however, that you keep the timeout as short as possible.

    Heartbeat Timeout

    The number of seconds to wait for a KeySafe 5 heartbeat response between KeySafe 5 nodes in the cluster. If this time is exceeded, the heartbeat fails.

    Enter a value between 2 and 15 seconds. (Default: 3 seconds)

    Healthy Interval

    The number of seconds between successful KeySafe 5 heartbeats for the cluster to be considered healthy.

    Enter a value between 1 and 10 seconds. (Default: 1 second)

    Degraded Interval

    The number of seconds between failed KeySafe 5 heartbeats for the cluster to be considered degraded.

    Enter a value between 1 and 10 seconds. (Default: 1 second)

    Healthy Threshold

    The number of successful consecutive heartbeats that must occur before KeySafe 5 determines that a degraded cluster is now healthy.

    Enter an integer between 2 and 10. (Default: 2)

    Degraded Threshold

    The number of failed consecutive heartbeats that must occur before KeySafe 5 determines that a healthy cluster is now degraded.

    Enter a value between 2 and 10. (Default: 2)

    Any changes you make are communicated to all nodes in the cluster and take effect immediately.

Startup Authentication

You can choose to enable passphrase-based startup authentication to provide further protection for the master key for all nodes in the same cluster. With passphrase-based startup authentication, the KeySafe 5 node will enter Recovery Mode every time it is rebooted. You will need to enter the passphrase in the KeySafe 5 Appliance Management UI. See the Recovery using Passphrase section in Recovering Access to KeySafe 5.

Startup Authentication allows KeySafe 5 to be used in tactical kits in hostile environments. Onsite staff can simply power off the KeySafe 5 nodes, which make them unusable until a passphrase or admin key is provided.

Note: If Startup Authentication is enabled, you cannot add a new KeySafe 5 node. You must disable Startup Authentication first, add the new node, and then re-enable Startup Authentication.

Enabling Startup Authentication

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Go to the Cluster tab.

  4. Select Actions > Startup Authentication.

  5. In the Startup Authentication window, click Edit.

  6. In the Passphrase Based Startup Authentication field, select Enabled.

  7. Enter and confirm your passphrase.

    The passphrase must be at least 12 characters long and include 1 digit, 1 uppercase character, 1 lowercase character, and 1 symbol.

  8. Click Apply.

Disabling Startup Authentication

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Go to the Cluster tab.

  4. Select Actions > Startup Authentication.

  5. In the Startup Authentication window, click Edit.

  6. In the Passphrase Based Startup Authentication field, select Disabled.

  7. Click Apply.

KeySafe 5 Backup and Restore

KeySafe 5 stores the configuration information and objects for all KeySafe 5 nodes in an encrypted object store that is shared among all nodes. Any changes you make on any KeySafe 5 node in the cluster is automatically disseminated to the other nodes in the cluster in a secure manner. This also allows you to backup all required information from any node in the cluster.

You can back up KeySafe 5 using:

Automatic Backup Feature

KeySafe 5 automatically creates a backup file once every 12 hours as long as the cluster is healthy. If this is the first time the automatic backup has completed successfully since the node was first initialized or restarted, KeySafe 5 records this information in the audit log. It does not send an alert or email to any KeySafe 5 users. It also does not record any subsequent successful backups.

The automatic backup schedule may change based on the following rules:

  • If the cluster is in a degraded state, no automatic backup is attempted. The cluster must be healthy in order for KeySafe 5 to create a backup file.

  • If the cluster is healthy but the automatic backup fails for some reason, KeySafe 5 retries the backup operation every hour. The first time the automatic backup fails KeySafe 5 records this information in the audit log and alerts all KeySafe 5 accounts with Domain Admin privileges. It does not record subsequent failed backup attempts.

  • Changes to the KeySafe 5 configuration may trigger an automatic backup, but it is better to backup KeySafe 5 manually whenever you make changes to be certain that you have an up-to-date backup file available.

Backing Up KeySafe 5 Through the KeySafe 5 Appliance Management UI

This procedure creates an encrypted backup file that can be downloaded through NFS on authorized servers or downloaded via the KeySafe 5 Appliance Management UI to the administrator’s default download directory.

The backup file can later be used to restore KeySafe 5 to the state it was in when the backup was taken.

Procedure

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Go to the Cluster tab.

  4. If you want to make the backup file available through NFS:

    1. Make sure the Backup Over NFS option is set to Enabled.

    2. Verify the IP addresses in the Backup Hosts field. If you want any server to have access to the backup directory, enter 0.0.0.0.

  5. Select Actions > KeySafe 5 Backup. KeySafe 5 displays the latest backup information if one exists.

  6. Click Perform Backup. KeySafe 5 creates a new backup file in the backup directory on the server and updates the information in this dialog box.

    If you want to download the backup file locally, click Download. KeySafe 5 saves the encrypted backup file to your browser’s default download location. The filename is in the format <server-name>-<product_version>←datetimestamp>-<admin_key_version>.bu.

    If you want to access the backup file through NFS, log into one of the servers listed in the Backup Hosts field and mount the directory using the mount command. For example, if your KeySafe 5 node IP address is 192.168.140.135, you would enter:

    # mount -t nfs 192.168.140.135:/hcs/backup /backup
# ls -l /backup
total 506
lrwxrwxrwx  1 root root     30 Dec 16 14:57 htkc.bu -> testkc01-5.1-20191216092703-4.bu
-rw-r--r--  1 root root 191776 Dec 16 14:57 testkc01-5.1-20191216092703-4.bu

  7. When you are done, click Close.

Accessing KeySafe 5 Backup Files

If you want to access an existing KeySafe 5 backup file, you can use the KeySafe 5 Appliance Management UI or, if you have configured an NFS server, you can use NFS.

Appliance Management UI Access

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Go to the Cluster tab.

  4. Select Actions > KeySafe 5 Backup. KeySafe 5 displays the latest backup information if one exists.

  5. Click Download. KeySafe 5 saves the encrypted backup file to your browser’s default download location. The filename is in the format <server-name>-<product_version>←datetimestamp>-<admin_key_version>.bu.

  6. Click Close.

NFS Access

To access the backup file through NFS, log into one of the Backup Host servers configured for the cluster and mount the directory using the mount command. For example, if your KeySafe 5 node IP address is 192.168.140.135, you would enter:

# mount -t nfs 192.168.140.135:/hcs/backup /backup
# ls -l /backup
total 506
lrwxrwxrwx  1 root root     30 Dec 16 14:57 htkc.bu -> testkc01-5.1-20191216092703-4.bu
-rw-r--r--  1 root root 191776 Dec 16 14:57 testkc01-5.1-20191216092703-4.bu

Restoring KeySafe 5 Through the KeySafe 5 Appliance Management UI

Restoring from a KeySafe 5 backup should only be needed if there is a catastrophic failure in the KeySafe 5 cluster. If one KeySafe 5 node becomes unusable, for example due to hardware failures, simply remove the node from the cluster and add a new node.

Restore is a destructive process. Any changes made to objects created since the backup image was taken will be lost. This includes policies, and KeySafe 5 user accounts. If the KeySafe 5 SSL certificate was changed since the backup was taken, the older SSL certificate will be restored along with the rest of the system and the current SSL certificate will be discarded.

Custom SSL certificates for internal and external webservers will be restored only if the IP address specified in the certificate matches the KeySafe 5 IP address.
Procedure

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. If there are any other nodes in this cluster, you must remove them before you restore the node. To do so:

    1. Click on the Servers tab.

    2. Click on each of the other nodes in the cluster and select Actions > Remove.

    3. Click Proceed at the prompt to confirm the request.

  4. Go to the Cluster tab.

  5. Select Actions > KeySafe 5 Restore.

  6. Click Browse and select the backup file from which you want to restore KeySafe 5. The name of the selected file appears next to the Browse button.

  7. Click Verify Image. KeySafe 5 uploads the file and verifies that it is a valid backup file. It also displays a hint stating which Admin Key generation count goes with this backup file in case you need to upload the matching Admin Key parts. For example:

    Hint: Keypart generation version for this backup image is 16.

    For details, see Admin Keys.

  8. Click Restore Image.

  9. Click Proceed at the prompt to confirm the request. KeySafe 5 restores the system information from the backup file and reboots the server.

  10. Verify the restoration by logging back into the KeySafe 5 Appliance Management UI.

    Remember that all user account information has been reverted back to whatever it was when the backup was taken. That means your account may not exist or that the password may have changed.

  11. If the hardware has changed since the backup was taken, KeySafe 5 presents you with additional options.

    Option Description

    Recovery using Keypart upload

    Allows you to recover the Admin key by uploading the parts from local files. You must upload the required number of parts of the Admin key within 10 minutes to use this method.

    Important: All Admin key parts must have the key generation count that was valid when the back up was taken. For details, see Admin Keys.

    Recovery from External key server

    Allows you to recover the Admin key by connecting to an external KMIP (Key Management Interoperability Protocol) server or HSM (Hardware Security Module).

    Decommission

    Tells KeySafe 5 to decommission the server. For more information, see Decommissioning a KeySafe 5 Node.

  12. If you removed any nodes from the cluster, re-join them as described in Joining or Re-joining a KeySafe 5 Cluster.

Removing a KeySafe 5 Node from a Cluster

  1. Log into the KeySafe 5 Appliance Management UI on any node you are not removing using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Click the Servers tab.

  4. Select the node you want to remove.

  5. Select Actions > Remove.

  6. Click Proceed at the prompt to confirm the request.

  7. If this KeySafe 5 node is included in any KeySafe 5 Mappings, KeySafe 5 displays a message stating which mappings it is a part of and giving you the following options. Select an option and click Proceed to continue.

    Option Description

    Disable the KeySafe 5 node

    Select this option if you are planning to re-join the node to the cluster later (for example, after upgrading it to a new KeySafe 5 version).

    You will need to manually re-enable the node in the Mapping after you re-join it with the cluster.

    Remove the KeySafe 5 node

    Select this option if you are removing the node permanently from the cluster.

    Do not change the mapping

    Select this option if you are planning to re-join the node with the cluster within a short time.

    . KeySafe 5 removes the node and refreshes the Servers tab.

If you want to rejoin the node to an existing KeySafe 5 cluster, see Joining or Re-joining a KeySafe 5 Cluster.

If you want to remove the node permanently, see Decommissioning a KeySafe 5 Node.

Joining or Re-joining a KeySafe 5 Cluster

When you install KeySafe 5, you can specify whether you want to configure the node as the first node in the system (standalone) or add it to an existing cluster.

If you ever need to change the node’s cluster assignment, or you need to re-join a node with its previous cluster, you can do so using the KeySafe 5 Appliance Management UI installed on the node. You do not need to re-install the KeySafe 5 software.

When a node is added to a cluster, any existing configuration and data are permanently deleted and cannot be restored. If this node was previously part of a different cluster or was used in standalone mode, make sure you do not need the data stored on this node before you add it to the new cluster.

Joining a KeySafe 5 Cluster

The following procedure describes how to configure a newly deployed node to join an existing KeySafe 5 cluster.

Before You Begin

  • Make sure you know the IP address of any KeySafe 5 node that is already part of the cluster you want to join.

  • If the node is currently part of a different cluster, you should remove the node from the original cluster so that the original cluster does not become degraded. For details, see Removing a KeySafe 5 Node from a Cluster.

  • If you are re-joining a node to an existing cluster and you are using an externally signed SSL certificate for KeySafe 5, make sure that you use the same hostname for the KeySafe 5 node that it had originally. If you change the hostname, you will need to reinstall the externally signed SSL certificate on that node.

  • A KeySafe 5 node cannot be joined to an existing KeySafe 5 cluster if the internal web server of the joining node is configured with a custom SSL certificate.

  • Entrust recommends that you configure the KeySafe 5 node with a private IP address.

Procedure

  1. Log into the KeySafe 5 Appliance Management UI on the KeySafe 5 node you want to join with the cluster.

  2. On the Welcome to KeySafe 5 screen, click Join an Existing Cluster.

    The Join Existing Cluster window displays.

  3. On the Get Started page, review the overview information to determine that you are ready to begin. This includes:

    • Access to the cluster you are joining the node to. We recommend that you open the KeySafe 5 Appliance Management UI for the cluster in a different tab or browser window.

    • Permissions on both this node and the cluster node so you can download and import the required certificates and files.

    • A passphrase to use during the joining process. Passphrase requirements are configured by a KeySafe 5 administrator in the System Settings. This phrase is a temporary string used to encrypt the initial communication between this node and the existing KeySafe 5 cluster.

    • Verifying that both this node and the cluster node are running the same KeySafe 5 version and build. The version number for the cluster node is on the Settings > System Upgrade page.

  4. Click Continue.

  5. On the Download CSR page, click Generate and Download CSR.

  6. Click Continue.

  7. Switch to one of the existing nodes in the cluster and navigate to the Cluster page.

  8. Select Actions > Add a Node.

  9. On the Add a Node window, upload the CSR that you downloaded from the new node (in .pem format) and enter a passphrase to use during the joining process.

  10. Click Save and Download Bundle to download the certificate bundle from the cluster node.

    The certificate bundle is a .zip file you must unpack. It contains both an encrypted SSL certificate in .p12 format and a CA certificate in .pem format.

  11. Click OK to close the Add a Node window.

  12. Return to the new node and click Continue.

  13. On the Node page, upload the encrypted SSL certificate and CA certificate that you downloaded from the cluster node, enter the IP address or hostname of any node in the existing cluster, and enter the passphrase that you selected.

  14. Click Join.

    During the joining process, a status page is displayed on the new node. Do not refresh the browser while this is in process.

    The cluster will automatically be placed in maintenance mode.

    The node will restart after the join is complete.

  15. When the node has successfully restarted, click Login.

Re-Joining a KeySafe 5 Cluster

The following procedure describes how to configure a node that has been in use as either a standalone node or part of a cluster to join another existing KeySafe 5 cluster.

This process will destroy all data on the node.
Before You Begin

  • Make sure you know the IP address of any KeySafe 5 node that is already part of the cluster you want to join.

  • If the node is currently part of a different cluster, you should remove the node from the original cluster so that the original cluster does not become degraded. For details, see Removing a KeySafe 5 Node from a Cluster.

  • If you are re-joining a node to an existing cluster and you are using an externally signed SSL certificate for KeySafe 5, make sure that you use the same hostname for the KeySafe 5 node that it had originally. If you change the hostname, you will need to reinstall the externally signed SSL certificate on that node.

Procedure

  1. Log into the KeySafe 5 Appliance Management UI on the KeySafe 5 node you want to join with the cluster.

  2. In the top menu bar, click Cluster.

  3. Select Actions > Join a Cluster.

    The Join Existing Cluster window displays.

  4. On the Get Started page, review the overview information to determine that you are ready to begin. This includes:

    • Access to the cluster you are joining the node to. We recommend that you open the KeySafe 5 Appliance Management UI for the cluster in a different tab or browser window.

    • Permissions on both this node and the cluster node so you can download and import the required certificates and files.

    • A passphrase to use during the joining process. The passphrase must contain 12 alphanumeric characters. It cannot contain spaces or special characters. This phrase is a temporary string used to encrypt the initial communication between this node and the existing KeySafe 5 cluster.

    • Verifying that both this node and the cluster node are running the same KeySafe 5 version and build. The version number for the cluster node is on the Settings > System Upgrade page.

  5. Confirm that you understand that all existing data on this node will be deleted by typing "delete my data".

  6. Click Continue.

  7. On the Download CSR page, click Generate and Download CSR.

  8. Click Continue.

  9. Switch to one of the existing nodes in the cluster and navigate to the Cluster page.

  10. Select Actions > Add a Node.

  11. On the Add a Node window, upload the CSR that you downloaded from the new node (in .pem format) and enter a passphrase to use during the joining process.

  12. Click Save and Download Bundle to download the certificate bundle from the cluster node.

    The certificate bundle is a .zip file you must unpack. It contains both an encrypted SSL certificate in .p12 format and a CA certificate in .pem format.

  13. Click OK to close the Add a Node window.

  14. Return to the new node and click Continue.

  15. On the Node page, upload the encrypted SSL certificate and CA certificate that you downloaded from the cluster node, enter the IP address or hostname of any node in the existing cluster, and enter the passphrase that you selected.

  16. Click Join.

    During the joining process, a status page is displayed on the new node. Do not refresh the browser while this is in process.

    The cluster will automatically be placed in maintenance mode.

    The node will restart after the join is complete.

  17. When the node has successfully restarted, click Login.

Rebooting a KeySafe 5 Node

You can only reboot the node that you are currently using.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Go to the Servers tab.

  4. Select Actions > System Reboot.

  5. Click Proceed to acknowledge the warning message.

Decommissioning a KeySafe 5 Node

Before You Begin

  • Make sure the node is not part of a cluster before you decommission it. For details, see Removing a KeySafe 5 Node from a Cluster.

  • Make sure you have access to all of the key parts for the Admin key that was generated for this system. All of the parts need to be uploaded within 10 minutes of the first file upload in order for the decommission to work.

    If there are multiple system administrators, each administrator has one of the key parts. You can either collect the parts and have one administrator upload them all or you can have each administrator log in and upload their part simultaneously.

    For this procedure you must use the Admin Key parts that were sent to the Security Administrators. You cannot use the Admin Key stored on an external key server.

When you decommission a KeySafe 5 node, KeySafe 5 uses zeroization to completely erase the data on the disks where the KeySafe 5 software and the object store are located. This is a non-reversible procedure.

Procedure

  1. Log into the KeySafe 5 Appliance Management UI on the node you want to decommission using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the System Settings section, click System Decommission.

  4. Click Browse to upload the first part of the admin key. Navigate to the key part and click Choose. The filename of the key part replaces the text of the Browse button.

  5. Click Upload File.

  6. If there is only one admin key part, KeySafe 5 immediately logs you out of the system and zeroes out the disks associated with the KeySafe 5 node. If there are multiple key parts, KeySafe 5 starts a 10 minute timer. All admin key parts must be uploaded within the 10 minutes before KeySafe 5 will decommission the node.

  7. If you need to restart the process, click Reset. You will need to re-upload all key parts to complete the process.

System Maintenance and Troubleshooting

Increasing KeySafe 5 Storage in a VM

If you installed KeySafe 5 in a VM, you can increase the amount of storage available without reinstalling KeySafe 5. You just need to increase the size of the underlying disk and reboot the KeySafe 5 node.

  1. Increase the size of the virtual disk in which KeySafe 5 is installed using your hypervisor tools.

    Note: You may need to shut down the VM before you can resize the disk. For details, see your hypervisor documentation.

  2. Log into the KeySafe 5 Appliance Management UI using an account with Domain Admin privileges.

  3. In the top menu bar, click Cluster.

  4. Select the KeySafe 5 node whose disk you just resized in the list.

  5. Select Actions > System Reboot.

  6. If necessary, log back into the KeySafe 5 Appliance Management UI after the KeySafe 5 node has rebooted.

  7. Review the Audit Log messages. The node should report the new size upon success or provide information if the resize failed.

Troubleshooting Network Issues

The KeySafe 5 System Console provides diagnostics that let you test the link between a KeySafe 5 node and external servers such as DNS servers, NTP servers, other KeySafe 5 node servers, or servers running third-party applications such as OIDC servers.

  1. Use your hypervisor to access one of the VMs in which KeySafe 5 is running, then log into the KeySafe 5 VM console as htroot.

  2. KeySafe 5 displays the Entrust KeySafe 5 System Console TUI (Text-based User Interface).

  3. Select Manage Network Settings and press Enter.

  4. Select Network Diagnostic Tools and press Enter.

  5. On the Network Diagnostics page, select one of the following options:

    Option Description

    Verify DNS Server Response

    Enter a comma-separated list of IP address that you want KeySafe 5 to verify as a DNS server. KeySafe 5 responds with one verification line per specified server.

    This test can be used to verify that the KeySafe 5 node can communicate through the firewall on the correct port to the specified IP addresses.

    Verify NTP Server Response

    Enter a comma-separated list of IP address or hostnames that you want KeySafe 5 to verify. KeySafe 5 responds with one verification line per specified server.

    Test Remote Server is Reachable

    This option sends a simple ping (ICMP) to another server to see if that server is up and responding. This test does not prove that the current KeySafe 5 node can actually communicate with the target server. It just means that the target server exists and is online.

    Test Inbound Ports of Another Server

    This option tests whether the current KeySafe 5 node can communicate with the target server on the specified ports (the default port is 8443 for KeySafe 5 to KeySafe 5 communication). If you want to specify multiple ports, separate the port numbers with a space.

    The test returns one of the following responses for each specified port:

    OK — The current node can communicate with the target server on the specified port. This response does not mean, however, that the target server can communicate back to the current node. If the target is another KeySafe 5 node with which you want to form a cluster, you need to log into the target node and run this test again using the target node as the base. If the test passes on both servers, then the two KeySafe 5 nodes can be joined in a single cluster.

    Connection Refused — The current node cannot communicate with the target node through the specified port.

    Operation Timed Out — The target node did not respond to the communication request from the current node.

    Return to Main Menu

    Closes the Network Diagnostics page and returns to the main Entrust KeySafe 5 System Console page.

Support Access and Log Files

Entrust provides two methods of support access:

  • Restricted support — Customers can access support logs and run simple diagnostic tools through a limited SSH-accessible shell that can be invoked from the Entrust KeySafe 5 System Console. For details, see Using the Restricted Shell.

  • Full support — The Entrust support staff can access and troubleshoot the customer’s system. Full support access requires multi-factor authentication between the KeySafe 5 Administrator at the customer site and Entrust Support. If such access is required, Entrust Support will guide you through the process.

Using the Restricted Shell

The restricted support login provides a limited SFTP-accessible shell in which the KeySafe 5 administrator can gather diagnostic information. It is disabled by default.

Creating a Support Bundle with the KeySafe 5 Appliance Management UI

In certain circumstances it may be necessary to gather diagnostic information and logs from KeySafe 5 that can be sent to Entrust support for further analysis. The following procedure describes how to create a log bundle using the KeySafe 5 Appliance Management UI.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Settings.

  3. In the Support section, click Download Logs.

  4. If a log has not yet been created for this cluster or if you want to generate a new log, click Create Bundle.

  5. In the Logs dialog box, enter the following information:

    Option Description

    Include Audit Log

    If Yes, KeySafe 5 includes the full audit log in the bundle. The default is Yes.

    Include All Cluster Logs

    If Yes, KeySafe 5 includes the log bundle from every KeySafe 5 node in the cluster. If No, KeySafe 5 only includes the log bundle from the current node. The default is No.

    Include Core Files

    If Yes, KeySafe 5 includes core files in the bundle. The default is No.

    Passphrase

    If you specify a passphrase, KeySafe 5 encrypts the bundle with an AES 256-bit key using the provided passphrase.

  6. When you are done, click Create. KeySafe 5 creates the log file and then refreshes the information about the log bundle it created.

  7. To download the bundle, click Download.

Enabling or Disabling Support Logins

You must enable support accounts before support personnel from Entrust can access your system. When the account is enabled, support personnel have full access to the system to carry out diagnosis and repairs in exceptional situations.

You can disable the support account after, for example, a successful upgrade. The support login will be disabled automatically after 24 hours.

  1. Log into the KeySafe 5 Appliance Management UI using an account with Security Admin privileges.

  2. In the top menu bar, click Cluster.

  3. Click the Servers tab.

  4. Select the node you want to modify.

  5. Select Actions > Support Login Settings.

  6. On the Support Login Settings page, check the Enable Support Login checkbox.

  7. Enter and confirm the password for the support login.

    The password must be at least 8 characters long, including 1 digit, 1 uppercase character, 1 lowercase character, and 1 symbol.

  8. Click Save.

  9. If the support login is enabled, you can disable it by checking the Disable Support Login checkbox and clicking Save.

Recovering Access to KeySafe 5

There are times when you will need to recover your KeySafe 5 system, such as when you increase the number of CPUs allotted to a KeySafe 5 server, change the network hardware address, migrate KeySafe 5 to a different host, or restore from a backup to a newly-created VM. The system recovery process prevents rogue administrators from making unauthorized changes to, or copies of, KeySafe 5 disks.

  • When you make a change that affects the hardware signature, the KeySafe 5 Appliance Management UI displays the System Recovery dialog box.

  • For backup/restore, the KeySafe 5 Appliance Management UI displays the System Recovery Options dialog box.

Procedure

  1. Select the method you want to use to recover your system. The options are:

    Option Description

    Recovery using Keypart Upload

    Allows you to upload the minimum number of required Admin Key parts that were sent to the Security Admins in the system. If you select this option, the KeySafe 5 Appliance Management UI displays the Recover Admin Key page.

    To upload a part, click Browse and select the appropriate recovery_key file. The Browse button should change to show the name of the selected file. When the correct file is displayed, click Upload file.

    Make sure that all Admin Key parts you upload have the same generation count. This information can be found in the email accompanying the Admin Key part. For details, see Admin Keys.

    When the required number of parts have been uploaded, KeySafe 5 recovers the system and displays the Recovery Success message. Click Proceed to return to the KeySafe 5 Appliance Management login page.

    Recovery using Passphrase

    Allows you to recover your system when you are using passphrase-based authentication. If you select this option, the UI displays the Recovery Passphrase page. Enter your passphrase and click Recover. For more information, see Startup Authentication.

    Decommission

    If you want to decommission your KeySafe 5 system, see Decommissioning a KeySafe 5 Node.

  2. If there are multiple KeySafe 5 nodes in the cluster, re-join those nodes with the node you just recovered. For details, see Joining or Re-joining a KeySafe 5 Cluster.