keynexus · vmware vsphere® is a virtualization platform that allows the deployment and...

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

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

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.



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.


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.



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.


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


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

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.



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

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.



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

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


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.


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



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.


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.



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.


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.



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

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


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

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.

https://www.vmware.com/support/pubs/

KeyNexus Encrypt VMware vSAN


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

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


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

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.

keynexus · vmware vsphere® is a virtualization platform that allows the deployment and...

Documents