KEYNEXUS vSphere Integration Guide
v2.4
08/2018
Copyright Notice
Copyright 2018 KeyNexus Inc. All rights reserved.
Information in this document is subject to change without notice. The software described in
this document is furnished under a license agreement or nondisclosure agreement. No part
of this publication may be reproduced, stored in a retrieval system, or transmitted in any form
or any means electronic or mechanical, including photocopying and recording for any
purpose other than the purchaser's personal use without written permission
Table of Contents
Introduction ................................................................................................................................ 4
System Requirements ................................................................................................................ 4
Hardware Requirements ..................................................................................................... 4
Software Requirements ....................................................................................................... 4
Before you Begin ....................................................................................................................... 4
Deploy KeyNexus in vSphere ..................................................................................................... 5
KeyNexus Instance Setup .........................................................................................................11
To initialize a node .............................................................................................................12
Cluster Nodes ....................................................................................................................13
Activate your KeyNexus Subscription .................................................................................15
Add a Key Management Server ................................................................................................16
Authentication Certificate ...................................................................................................19
Encrypt a VM in vSphere ..........................................................................................................24
Encrypt VMware vSAN ..............................................................................................................26
Troubleshooting ........................................................................................................................28
Introduction KeyNexus
Page 4 of 31 KeyNexus
Introduction
VMware vSphere® is a virtualization platform that allows the deployment and configuration of
virtual machines (VMs) on a large scale. vSphere is made up of 2 main components, ESXi, a
bare-metal hypervisor that can partition your server into individual VMs, and vCenter Server,
which allows you to manage multiple hosts and pool host resources.
KeyNexus is a Unified Key Management Service that provides a centralized platform for the
management of encryption keys throughout their lifecycle. With KeyNexus, you can create or
import keys, control key access by assigning them to a specific group or user.
This document provides details relating to the deployment and configuration of the KeyNexus
VM in a vCenter Server System, how to add KeyNexus as a Key Management Server (KMS) to
a vCenter Server, as well as information to assist you in vSphere VM and vSAN encryption. The
Troubleshooting section describes common issues, possible causes and resolutions.
This document was created using vSphere version 6.5 and KeyNexus version 1.10.
Note:
System Requirements
Hardware Requirements
Hardware Requirement Processor Recommended: Intel quad core or higher
Memory Minimum 6 GB RAM Recommended: 16 GB of RAM
Storage Minimum 20 GB HDD Recommended: 40 GB HDD
Software Requirements KeyNexus is normally provided as an OVA file. Refer to the vSphere documentation to ensure your system meets the platform requirements. As long as your system software meets the necessary requirements to run your virtual machine platform and meets the KeyNexus hardware requirements, KeyNexus will perform as described.
Before you Begin Before proceeding with the configuration and deployment tasks, make sure the following tasks
have been performed:
• Make sure you have the latest copy of the KeyNexus OVA.
KeyNexus Deploy KeyNexus in vSphere
KeyNexus page 5 of 31
• Download and install the latest version of vSphere. Refer to the vSphere installation
documentation for information regarding the download, installation and configuration
instructions for the latest vSphere version.
• Review the current licensing agreement with any and all third-party software. Pay
particular attention to conditions relating to the use of any trial versions of the software.
Deploy KeyNexus in vSphere This section discusses deploying the KeyNexus OVA in the vSphere vCenter client.
Important: This section provides the instructions required to deploy the KeyNexus OVA in
vSphere. This does not mean, however, that KeyNexus must be running in vSphere in order to
operate as a Key Management Server for your files. One of the most powerful features of
KeyNexus is its ability to operate on multiple platforms. If you already have KeyNexus deployed
in another environment, you can begin with the instructions in the Add a Key Management
Server section.
1. Launch the VMware vSphere client.
Important: This document’s workflow uses the vSphere Web Client and not the HTML5
client. Make sure Flash is enabled on your system.
2. Login to VMware vCenter as an Administrator.
Deploy KeyNexus in vSphere KeyNexus
Page 6 of 31 KeyNexus
3. Select the vSphere host from the navigator pane. This is where KeyNexus will be
deployed.
4. Right click the host and select Deploy OVF Template. The Deploy OVF Template
dialog appears.
5. Select Local file > Browse on the Select template page. Navigate to the saved OVA
location and select the KeyNexus OVA file.
KeyNexus Deploy KeyNexus in vSphere
KeyNexus page 7 of 31
6. Click Next.
7. Enter a name for the OVA and select and deployment location. Click Next.
8. Select a host or cluster from the Select a resource page. The VM shares the resources
of the resource pool you select. The image below shows the second level of the
Datacenter hierarchy being selected. It can take a few moments for vSphere to complete
its validation.
9. Click Next.
10. Verify your template details on the Review details page.
Deploy KeyNexus in vSphere KeyNexus
Page 8 of 31 KeyNexus
11. When everything looks correct, click Next.
12. Select a provision from the Select virtual disk format dropdown. Thin provision
conserves disk space by using the minimum amount of space initially required and
grows based on demand. Thick provision uses the entire allocated space from the start.
The workflow described here uses the Thin provision.
13. Select None from the VMStorage policy dropdown.
14. Click Next.
15. Select the destination network from the dropdown.
KeyNexus Deploy KeyNexus in vSphere
KeyNexus page 9 of 31
If you are using DHCP for your IP allocation, click Next. If you are manually providing a
static IP address, select Static – Manual from the IP allocation dropdown at the bottom
of the page and click Next.
Use the Customize Template page to provide your static IP information. Enter your DNS,
Gateway, IP address and Netmask information in the fields provided. If you are using
DHCP for your IP allocation, leave these fields blank. Click Next.
Deploy KeyNexus in vSphere KeyNexus
Page 10 of 31 KeyNexus
16. Take a moment to review all the settings before continuing. If any changes are required,
click the Back button until you get to the appropriate page, and make the changes.
When everything is configured properly, click Finish. This starts the OVA deployment
process.
17. Wait for the OVA deployment to complete. This can take several minutes.
18. Confirm the VM is powered off by right-clicking the VM in the Navigator window and
selecting Power > Power Off.
19. Right-click on the KeyNexus OVA and select Edit Settings.
KeyNexus KeyNexus Instance Setup
KeyNexus page 11 of 31
20. Confirm the Memory value is set to a minimum of 8GB. Review the other settings to
make sure they conform with your environment. Click OK.
Note: If the memory is set to a value below 8GB, your KeyNexus instance may not work
as expected.
21. Power on the VM by right-clicking it in the Navigator window and selecting Power >
Power On.
KeyNexus Instance Setup
To successfully configure your KeyNexus cluster, the nodes that make up that cluster must be
initialized. Perform this operation on each node before adding it to your cluster.
To access the KeyNexus Subscription Activator, open your browser and provide the URL
containing the IP address (for example https://<KeyNexus_IP>:8443 where <KeyNexus_IP>
is the IP address of the KeyNexus node), or the fully qualified domain name. Make sure to add
port 8443 to the end of the URL. The Subscription Activator page appears.
Note: When applicable, accept the self-signed certificate when navigating to the Initialize
Network Node, Cluster Configuration, or Account Login pages.
If you are initializing a network node for the first time, the Subscription Activator page appears.
KeyNexus Instance Setup KeyNexus
Page 12 of 31 KeyNexus
To initialize a node
1. Select Reboot if your system requires a reboot in order for the network config to take
effect.
2. Select DHCP or Static from the Network Config options.
Select DHCP to configure the network automatically using DHCP.
Select Static to manually configure the host and enter your valid network information (IP
Address, Network Mask, Network Gateway and DNS) in their respective fields.
KeyNexus KeyNexus Instance Setup
KeyNexus page 13 of 31
There are several considerations when deciding between using DHCP or Static IP:
• When using DHCP, if the same IP address cannot always be provided to the
same node, DHCP should only be used for short term test clusters.
• If you need to use DHCP in a production environment, ensure that the same IP is
provided to the same node using external tools such as pinned entries in the
DHCP server. This helps to ensure that the same IP is provided to the same
node.
• Static IP can be used in a production environment to help ensure the same IP is
provided to the same node.
Note: If you select Static, change the IP address of the machine and choose the
Reboot option, the Cluster Configuration on the Initialize Network Node success page
does not advance you to the Cluster Nodes page. The IP in the address tab of the
browser is no longer associated with that node. You must connect to the activator again
with one of the new IPs entered into the browser address bar to finish the configuration
once the reboot is complete.
3. Click Show Terms to review the Terms of Service and click Accept to accept them.
Terms of service must be accepted to continue.
4. Enter a Cluster Admin Password. Passwords must be 8-256 characters long. You
must provide this password when clustering nodes. All nodes in a cluster must share the
same password.
5. Click Initialize Node. If any configuration step has been missed or entered incorrectly,
that area is highlighted in red when you attempt to initialize the node. The information in
highlighted area must be entered correctly to continue.
When the node has been initialized, a message indicating the node has been successfully
initialized is displayed.
6. Click Cluster Configuration to continue.
Cluster Nodes Use the Cluster Nodes page to enter the name and IP address of each node in your cluster.
KeyNexus Instance Setup KeyNexus
Page 14 of 31 KeyNexus
1. Enter the name and IP address of your first node in the NODE #1 box.
2. Click Add Node to open an additional node box. Enter the name and IP address of the
second node. Repeat for each node you are adding to your cluster. When a valid node
name and IP address are entered, the border around the Node box turns green.
3. To remove a node, click the x in the top right corner of the node box. You cannot remove
NODE #1.
Once you have configured all the nodes in your cluster, click Continue to Specify License.
This button appears when at least one node contains a valid name and IP address is entered.
Use the License page to enter your subscription key, create a first admin username and
password, re-enter your cluster configuration password, and set the external IP address for the
node currently being configured.
KeyNexus KeyNexus Instance Setup
KeyNexus page 15 of 31
Activate your KeyNexus Subscription
1. Provide your subscription key in the Subscription Key field. There are several ways you
can enter your key. You can enter your key manually, you can cut and paste the key
from a text file, or you can import the subscription key by dragging and dropping a text
file containing the subscription key into the Subscription Key field.
2. Once a valid subscription key is entered in the Subscription Key field, information
regarding the Business ID, the company associated with this subscription key, and the
subscription key expiry date are displayed.
3. Create an admin user by entering a name in the Pick your admin username field.
4. Enter a password in the Pick your admin password field and verify it in the Pick your
admin Password (Verify) field. The password must contain a minimum of 10
characters. KeyNexus uses a password strength meter to indicate the strength of the
password and provides tips for creating stronger passwords.
Note: The tips provided by the password strength meter are informational. As long as
your password meets the minimum length requirement, KeyNexus accepts the
password.
5. Enter the Cluster Administrator Password you created during the node initialization.
6. Select the External IP address from the dropdown list. This list is made up of the nodes
entered on the Cluster Nodes page.
7. Click Activate Cluster when all fields have been completed. It can take some time for
this action to complete.
Successful activation of the KeyNexus cluster brings you to a summary page that contains
information regarding your Business ID, the nodes in your cluster, the administrator account and
company account details.
Add a Key Management Server KeyNexus
Page 16 of 31 KeyNexus
Add a Key Management Server Once the KeyNexus portal is activated, it can be configured as a Key Management Server
(KMS).
vSphere requests encryption keys from KeyNexus. KeyNexus generates and stores these keys
which are passed to the vCenter server and used whenever a VM stored on vSphere needs to
be encrypted.
This process requires two configuration steps: Creating the user in the KeyNexus Web Portal,
and adding KeyNexus as a KMS to your vCenter Server.
1. Go to https://<your.ip>/login and log in with your Business ID,
Username and Password. Click Login. This advances you to the Dashboard
page.
Use the Groups feature to create a new group. The user account that vSphere will access must
be associated with a default group. Click the Groups tab to navigate to the Groups page.
KeyNexus Add a Key Management Server
KeyNexus page 17 of 31
1. Click +Add Group. The Add New Group dialog appears.
2. Enter the name of the key group in the Group Name field. This name should
follow a naming convention to assist with the logical grouping of your keys.
Note: Group names cannot use uppercase letters.
3. Click Save. A message indicating that the new group was created appears in the
top right corner.
When you have completed the group creation task, use the Users feature to create the user
account that vSphere will access for KeyNexus authentication and key creation.
1. Click the Users tab. This advances you to the Users page.
2. Click Add User. The Add New User dialog appears.
vSphere uses this account to authenticate to KeyNexus and create keys.
Add a Key Management Server KeyNexus
Page 18 of 31 KeyNexus
3. Enter the information required in the Add New User dialog:
Field name Value/Description
Username
Enter the username. This username is used by vSphere when authenticating to KeyNexus.
User Role Select Key Access User
Group Select a group or groups from the list of available groups.
Default Group From the list of groups the user is a part of, select one to act as a default group.
Email Enter email associated with this account (optional).
Authenticate via Client Cert Select this option to generate a certificate used to authenticate this user. You can download the certificate after the new user is created. See Authentication Certificate for more information.
Password Enter password for this user. Password must have a minimum length of 10 characters. KeyNexus provides feedback relating to the strength of your password. When Client Cert is selected, it is not necessary to enter a password.
Confirm Password Re-enter your password
KeyNexus Add a Key Management Server
KeyNexus page 19 of 31
4. Click the Enforce IP Whitelist checkbox to restrict API requests for this account
to IP address contained in this range. Enter the IP addresses in the fields
provided. To enter multiple IP addresses, enter the IP addresses in a comma
separated value format (a.b.c.d, a.b.c.d, etc).
5. Click Add User.
Authentication Certificate Instead of using a username and password to authenticate a KeyNexus user, you can generate
and download an authentication certificate associated with a specific KeyNexus account and
use it in lieu of login credentials. This certificate can be generated in several different ways:
a. During the initial user creation process, select the Authenticate via Client Cert option.
b. After the user has been created, locate the user in the Users list and click
AuthCertificate beside the user name.
c. After the user has been created, locate the user in the Users list, click Edit beside the
user name, select the Authenticate via Client Cert option and click Apply Changes.
In each case the Authentication Certificate Download dialog opens.
Click Download to download the existing authentication certificate or select the Generate New
Certificate option and click Generate and Download to generate and download a new
authentication certificate.
Note: If there is no existing authentication certificate associated with the user, the dialog
displays a message indicating you must generate a new certificate.
Add a Key Management Server KeyNexus
Page 20 of 31 KeyNexus
Note: Generating a new certificate automatically invalidates any existing certificate for that user.
Once KeyNexus has been activated, the account used to connect to vSphere has been created
and the Authentication Certificate has been successfully generated and downloaded, the next
step is to add KeyNexus as a KMS to vCenter.
1. Login to VMware vCenter as an Administrator.
2. From the Home page select Hosts & Clusters.
3. Under the Configuration Tab, click More > Key Management Servers.
KeyNexus Add a Key Management Server
KeyNexus page 21 of 31
4. Click Add KMS. The Add KMS dialog appears.
5. Configure the values described in the following table:
Field name Value/Description
KMS cluster Select Create new cluster from the dropdown list
Cluster name Enter the cluster name
Server alias Enter the KMS server alias
Server address Enter the server address in IPv4 format or as a fully
qualified domain name
Server port Enter 5696. This port is normally used to send and receive
KMIP messages.
Proxy address Enter proxy address (optional)
Proxy port Enter proxy port (optional)
User name When establishing trust with KMS with user certificates
and private keys, leave this field blank.
Password When establishing trust with KMS with user certificates
and private keys, leave this field blank.
Add a Key Management Server KeyNexus
Page 22 of 31 KeyNexus
6. Click OK when finished.
7. Click Yes on the Set default KMS cluster dialog to allow vSphere to use the
cluster you created as the default.
Once the KMS has been configured and set, it appears in the Key Management
Servers list. Complete the process by establishing trust between KeyNexus and
vSphere.
8. Click Trust to trust the KeyNexus certificate.
9. Click Establish Trust with KMS tab. The Establish Trust dialog appears.
KeyNexus Add a Key Management Server
KeyNexus page 23 of 31
10. Select Upload certificate and private key. Click OK. This forwards you to the
Upload Certificate and Private Key dialog.
11. Navigate to the Cert Auth file location. Paste or upload the Cert Auth file to both
the certificate and the private key fields. The Cert Auth file contains both and
does not require editing prior to uploading to each field.
12. Click OK.
The Connection Status should now read Normal beside your KeyNexus server
in the VSphere KMIPs configuration screen.
Encrypt a VM in vSphere KeyNexus
Page 24 of 31 KeyNexus
Encrypt a VM in vSphere You can encrypt a VM in vSphere by editing the VMs storage policies and then assigning the
VM encryption policy to each VM that requires encryption. Make sure you have setup KeyNexus
as the Key Management Server before attempting to encrypt a VM. Follow the procedure below
to encrypt a VM.
1. Connect to the vCenter Server through the vSphere Web Client.
2. Select the VM and make sure it is powered off. The VM cannot be encrypted unless it is
powered off.
3. Right-click on the VM to encrypt and select VM Policies > Edit Storage Policies.
KeyNexus Encrypt a VM in vSphere
KeyNexus page 25 of 31
4. Select VM Encryption Policy for both VM Home and Hard Disk and click OK. Wait for
Reconfiguring Virtual Machine to finish. This can take several minutes.
The vCenter Server instance request a key from KeyNexus, which creates a Key Encryption
Key (KEK) used to encrypt the Data Encryption Key (DEK) generated in vSphere. The
vCenter server instance keeps a list of key IDs, but does not store the keys themselves. The
KEKs are stored in KeyNexus, separate from the encrypted data.
Encrypt VMware vSAN KeyNexus
Page 26 of 31 KeyNexus
To confirm that the key was successfully created, log in to KeyNexus, look at the user
associated with vSphere and confirm the key was created. You can view additional
information relating to the key through the key history feature.
5. Power on the encrypted VM by right-clicking it in the Object Navigator and selecting
Power > Power On.
To confirm that the VM has been successfully encrypted in vSphere, click the VM name in the
Navigator window, select the Configure tab and click VM Hardware from the list. Beside the
Encryption heading you should see a message indicating that the VM configuration files and
Hard Disk are encrypted.
Note: For more about setting encrypted VMs, refer to the VMware documentation found at
https://www.vmware.com/support/pubs/.
Encrypt VMware vSAN VMware vSAN creates a single storage pool that can be shared across all hosts in a cluster.
When encryption is enabled, vSAN encrypts all VMs and associated files in the vSAN datastore,
protecting all files stored there.
KeyNexus Encrypt VMware vSAN
KeyNexus page 27 of 31
vSAN encryption employs the same initial workflows regarding deployment and KeyNexus
initialization and configuration used to encrypt a VM in vSphere. Confirm KeyNexus has been
configured as the vSphere KMS before setting up your vSAN encryption.
1. Connect to the vCenter Server through the vSphere Web Client.
2. Select the cluster you want to encrypt from the Object Navigator.
3. Under the Configuration Tab, click vSAN > General.
4. Click the Edit button. The Edit Settings dialog appears.
5. Click the Encryption option, then select the KeyNexus KMS from the KMS Cluster
dropdown.
6. Click OK.
Note: If you want to erase any existing data from the disks as they are encrypted, click the
Erase disks before use option.
Troubleshooting KeyNexus
Page 28 of 31 KeyNexus
Troubleshooting Use this section to find solutions to some of the most common errors when configuring and
deploying the KeyNexus OVA, setting up KeyNexus as a Key Management Server, or
encrypting a VM.
Issue:
When providing the Subscription key, Username and Password on the Subscription Activator
page, a create_admin error message is displayed when you click Submit.
Cause
This message is received when the memory value for the KeyNexus VM is set too low.
Resolution
1. Power off the VM.
2. Select Action > Edit Settings.
3. Make sure that the Memory value is set to a minimum of 8GB.
4. power the VM back up.
5. Reconnect to the Subscription Activator page.
6. Re-enter the Subscription Key, Username and Password and click Submit. You should
now receive your Business ID.
Issue:
When configuring the KMS through vSphere, you receive a Cannot establish trust connection
message in the Connection Status field.
KeyNexus Troubleshooting
KeyNexus page 29 of 31
Cause
There can be several reasons this error message appears:
a) This message appears when the IP address provided in the Add KMS dialog is
incorrect.
b) This message appears when the Port Number provided in the Add KMS dialog is
incorrect.
c) This message appears if the user certificate or private key are absent or incorrect.
Resolution
In the first two cases, the issue can be resolved by updating the applicable field in the KMS
settings dialog.
1. Click Edit KMS settings.
2. Confirm the server address and update the Server address field.
3. Confirm that the Server Port value is set to 5696. This port is normally assigned to send
and receive KMIP messages.
4. Click OK.
In the last case, click Establish trust with KMS, select Upload certificate and private key
and click OK. In the Upload Certificate and Private Key dialog, re-enter the certificate and
private key in the fields provided and click OK. If you still see the Cannot establish trust
connection message in the Connection Status field, retrieve a new Authentication Certificate
from the associated user in KeyNexus and enter the new certificate in the Establish trust with
KMS dialog.
Troubleshooting KeyNexus
Page 30 of 31 KeyNexus
Issue:
When encrypting a VM, a RuntimeFault.summary message appears in the Status column of
the Recent Tasks log.
Cause
This is an indicator that the KMS is not connecting to the user account in KeyNexus. The most
common cause of this is the auth cert not entered correctly in vSphere.
Resolution
1. Under the Configuration Tab, click More > Key Management Servers.
2. Click Establish Trust with KMS.
3. Select Upload certificate and private key from the dialog and click OK.
4. Enter the correct certificate in both fields and click OK.
KeyNexus Inc. 205 2657 Wilfert Road Victoria, B.C. V9B 5Z3
KeyNexus vSphere Integration Guide v2.4
Copyright 2018 KeyNexus Inc. All rights reserved. KeyNexus is a trademark of KeyNexus Inc. All other product names, logos, and brands are
property of their respective owners. All other company,
product and service names used in this document are
for identification purposes only. Use of these names,
logos, and brands does not imply endorsement.