KEYNEXUS
Google Cloud Integration Guide v1.2
07/2018 Introduction KeyNexus
Copyright Notice
Copyright 2018 KeyNexus. 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.
Page 2 of 44 KeyNexus KeyNexus Introduction
Table of Contents
Introduction ...... 5 Prerequisites ...... 6 Google Cloud SDK ...... 39 KeyNexus Patches ...... 41 Google Storage Utililty ...... 41 Deploying KeyNexus on Google Cloud ...... 6 Create a new Google Cloud Platform project ...... 6 Create a new Google Cloud Platform bucket ...... 7 Upload the KeyNexus image file to the Google Storage bucket ...... 8 Create an Image from the Google Cloud Platform ...... 8 Create an Instance from Google Cloud Platform ...... 9 KeyNexus Configuration ...... 10 KeyNexus Setup ...... 10 Cluster Nodes ...... 12 Configuring KeyNexus ...... 15 Groups ...... 16 Add a group ...... 17 Delete a group ...... 17 View Users in a Group ...... 18 Search for a Group ...... 18 Keys ...... 18 Add a new key ...... 19 Import Custom Keys ...... 22 Key Details ...... 24 Key Rotation ...... 25 Add Batch Keys through the API ...... 31 Users ...... 34 Create a New User ...... 34 Authentication Certificate ...... 36 Delete a User ...... 38
KeyNexus page 3 of 44 Introduction KeyNexus
Encrypting and Decrypting objects on Google Cloud Platform ...... 39 Google Cloud Disk Encryption and Decryption ...... 42 Encrypting and decrypting objects ...... 42
Page 4 of 44 KeyNexus KeyNexus Introduction
Introduction
Google Cloud Platform is a cloud storage platform for storing and retrieving data. It provides a simple programming interface which enables developers to take advantage of Google's own systems to perform data operations in a secure and cost-effective manner.
Google Cloud Platform stores objects that are organized into basic storage containers called buckets. All requests are authorized using an access control list (ACL) associated with each bucket and object, or with gsutil, a Python application that allows access to Google Storage through the command line.
Google Cloud Platform provides a range of programming languages to choose from when creating applications. These languages are supported by client libraries that allow applications to communicate with Google Cloud Storage. The libraries take care of the HTTP protocol details when using the Google Cloud Storage APIs.
This guide provides the instructions for the following tasks:
• Installing the Google Cloud SDK • Creating a bucket, uploading the KeyNexus VMDK file, and starting an instance on Google Cloud Platform. • Installing and configuring the KeyNexus patches. • Instructions for creating KeyNexus groups, users and keys in the KeyNexus portal. • Instructions for the scripts used to encrypt and decrypt objects stored on the Google Cloud Platform.
Important: This document provides the instructions required to create a bucket, upload the KeyNexus tar.gz file and set up an KeyNexus instance on Google Cloud Platform. This does not mean, however, that KeyNexus must be running on Google Cloud Platform in order to operate as a Key Management System for your files. One of the most powerful features of KeyNexus is its ability to operate independently of any cloud platform. This document was created using KeyNexus Web Portal version 1.10. Using a version of this product other than the one used in this guide may require a different workflow from the one provided here in order to achieve a successful result. The complete set of Google Cloud Platform documentation can be found at https://cloud.google.com/docs/.
KeyNexus page 5 of 44 Prerequisites KeyNexus
Prerequisites
Before proceeding with the configuration and deployment tasks, make sure the following tasks have been performed:
• Download and Install the Google Cloud SDK • Download the KeyNexus gcloud integration package. It includes this document, patch files and sample JSON files. Talk to your KeyNexus Representative for access to these files. • Download the keynexus.tar.gz file. Talk to your KeyNexus Representative for access to this file. Deploying KeyNexus on Google Cloud
This section provides instructions for the initial activation of Google Cloud Platform, creating a new project, creating a new bucket and uploading the KeyNexus file to that bucket. Once the file is successfully uploaded, it can be used to create an image. Note: These instructions are restricted to the steps necessary to set up an instance of the KeyNexus Web Portal. For complete instructions relating to Google Cloud platform, refer to the https://cloud.google.com/docs/. Create a new Google Cloud Platform project
If you already have a project created in Google Cloud Platform, continue on to Create a new Google Cloud Platform bucket. 1. Open Google Cloud Platform Console.
2. Click the Select a project dropdown on the Google Cloud Platform header. This opens the Select dialog.
Page 6 of 44 KeyNexus KeyNexus Deploying KeyNexus on Google Cloud
3. Click New Project. The New Project page appears.
4. Enter the project name, organization and select a location using the Browse button and selecting a folder from the list.
5. Click Create.
Create a new Google Cloud Platform bucket
Once the project is created, you can create a new bucket. A bucket in Cloud Storage is the container for all data stored in the Cloud Storage project.
If you already have a bucket created, continue on to Upload the KeyNexus image file to the Google Storage bucket.
1. Click the Navigation Menu button to bring up the Products and Services menu. Select Storage > Browser from the menu. This brings you to the Browser page.
2. Click Create Bucket. The Create a Bucket dialog appears.
1. Enter a name for the bucket. This name has to be unique from any other bucket on Google Cloud storage.
2. Select a storage class for the bucket from one of the Storage Class options.
3. Select a location from the Location dropdown. 4. Click Show advanced settings. Click Specify labels and Add label to provide additional values to assist in organizing your buckets. (Optional)
KeyNexus page 7 of 44 Deploying KeyNexus on Google Cloud KeyNexus
Upload the KeyNexus image file to the Google Storage bucket
Once the bucket has been created, you can upload the KeyNexus file.
1. Open the project that contains the bucket want to add an object to.
2. Select Storage > Browser from the options menu on the left side of the page. The Browser page appears, containing a list of buckets in the project.
3. Select a bucket from the list.
4. Click Upload Files to open the Upload Files dialog.
5. From the dialog, navigate to the file location and select the keynexus.tar.gz file.
6. Click Open. Depending on your connection speed, the download process can take some time to complete.
Create an Image from the Google Cloud Platform
Once the keynexus.tar.gz file is uploaded to a bucket, you can use the KeyNexus file to create an image which can then be used to create instances of the KeyNexus platform.
1. From Google Cloud Platform, navigate to the Compute Engine dashboard.
2. Click Images from the side navigation.
3. Click Create Image.
4. Enter a name for the image in the Name field.
5. Enter Family and Description information (optional).
6. Select Cloud Storage file from the Source menu.
7. Click Browse and navigate to the bucket that contains the KeyNexus image file. This must be a .tar.tz file.
Page 8 of 44 KeyNexus KeyNexus Deploying KeyNexus on Google Cloud
8. Click Create to create the image. Depending on your connection speed, this step can take some time to complete.
Once the KeyNexus file is successfully imported, it appears in the Images page.
Create an Instance from Google Cloud Platform
1. From the Images list, click the image you just created.
2. Click Create Instance. Give the instance a unique name.
3. Expand the Management, disk, networking, SSH keys submenu and add keynexus as a new network tag.
4. Under Firewall, select the Allow HTTPS traffic option.
5. This action can take a few minutes to complete. When finished, the new instance appears in the instance list. Note the instance’s external IP address.
Stop the instance and click Edit to make changes to the instance.
Create network firewall rule
6. Under Network Interfaces, click a network name to access the Network Details page. Click Firewall Rules, then Create Firewall Rule.
KeyNexus page 9 of 44 KeyNexus Configuration KeyNexus
7. Under Allowed Protocols and Ports, provide the following port numbers, each one separated with a semicolon: Database synchronization: tcp:444; tcp:4567; tcp:4568 Admin access: tcp:443; tcp:8443 API access: tcp:443
Click Create. KeyNexus Configuration
KeyNexus Setup
Once the KeyNexus portal has been deployed and powered on, you can access it through your browser. Connect to the VM by entering https://your.ip:8443 on your browser address bar, where your.ip is the address of your VM. Note: When applicable, you must accept the self-signed certificate when navigating to the Initialize Network Node, Cluster Configuration, or Account Login screens. The Subscription Activation and Cluster Configuration utilize the same setup pages and follow very similar processes. For instructions regarding setting up a cluster, refer to the KeyNexus Clustering and Backup Guide. In this document, a single node is initialized. If you are initializing a network node for the first time, the KeyNexus Subscription Activator page appears.
Page 10 of 44 KeyNexus KeyNexus KeyNexus Configuration
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 page 11 of 44 KeyNexus Configuration KeyNexus
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 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.
Page 12 of 44 KeyNexus KeyNexus KeyNexus Configuration
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. 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 page 13 of 44 KeyNexus Configuration KeyNexus
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 Configuration 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.
Page 14 of 44 KeyNexus KeyNexus KeyNexus Configuration
Click the Portal URL link or the Log In button to go to the KeyNexus login page, where the Business ID and Username fields are prepopulated. The Business ID is a unique alphanumeric code assigned to your organization, and is required when logging in using your account credentials. Record this number and store in a secure location as it is required for access to your account. If you lose your Business ID, contact your KeyNexus representative.
Configuring KeyNexus
Once you have received your Business ID, provide the URL containing the IP address (for example https://
KeyNexus page 15 of 44 KeyNexus Configuration KeyNexus
1. Enter the Business Number provided on the Subscription Activation page in the Business field.
2. Click the Login via SSO button if you have Single Sign On (SSO) configured for this account, otherwise enter a Username and Password in the applicable fields. Refer to the Administration section for information regarding configuring the KeyNexus portal for Single Sign-On.
3. Click Login.
4. Alternatively, click Sign in with client certificate. If you have previously generated a client certificate, you can use it to sign in to the KeyNexus portal as the user associated with the client certificate. Drag and drop the certificate file into the dialog, or click in the dialog, locate the certificate and click Open. If you have not generated a client certificate, refer to the Users section for instructions regarding the creation of a user with an associated client certificate.
A successful login advances you to the Dashboard Page. Groups
Use the Groups feature to create key groups that can assist you with the organization of your keys. Click the Groups tab to navigate to the Groups page. Note: The Groups tab is only available to users with Admin access.
Page 16 of 44 KeyNexus KeyNexus KeyNexus Configuration
Add a group
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.
The new group now appears in the Group Name list.
Delete a group
1. Locate the group to delete in the list and click Delete under the Actions heading next to the group name. The Delete Group Confirmation dialog appears.
2. Click Delete Group to remove the group or click Cancel to return to the Groups page.
Note: This operation cannot be undone.
KeyNexus page 17 of 44 KeyNexus Configuration KeyNexus
The group is removed from the Group Name list.
View Users in a Group
1. Hover the mouse pointer over the number of users beside the applicable group. The users in that group appear as a tooltip.
Search for a Group
1. Use the Search field to locate existing groups. The groups table is filtered to display only groups matching the entry provided in the field. Groups are searched by group names as a substring. For example, entering ‘key' in the search field displays only the groups that contain ‘key’ in their name.
Keys
The Keys feature is used to create keys, add keys to the system and to view and edit details relating to existing keys. Click the Keys tab to navigate to the Keys page.
Page 18 of 44 KeyNexus KeyNexus KeyNexus Configuration
The Keys Page contains a list of key names. Beside each key name is a version number, indicating how many times the key has been rotated. Each key row contains the type of key, owner information, and View and Delete Action buttons. Note: Each key must be associated with either a group or a key user. If no groups or key users have been created, you are prompted to create one before you can continue creating a key. See the Users and Groups sections for instructions regarding the creation of new users and groups.
Add a new key
1. Click +Add Key to advance to the Add or import new key dialog.
KeyNexus page 19 of 44 KeyNexus Configuration KeyNexus
2. Select one of the following to add a new key:
a. Symmetric (AES) b. Asymmetric (RSA) c. Custom key
3. Select a key type from the Key Type dropdown.
• Symmetric (AES) key types include AES128, AES192 and AES256. Select Import Existing Key to import an existing key and enter that key in the Base 64 encoded key field.
• Asymmetric (RSA) key types include RSA 2048, RSA3072, RSA4096, and ECDSA. Check Import Existing Key to import an existing private/public key pair.
• Custom Key is any key created outside KeyNexus that you want to store and manage with KeyNexus.
4. Provide a key name in the Key Name field. The key name cannot contain uppercase letters.
Page 20 of 44 KeyNexus KeyNexus KeyNexus Configuration
5. Provide a description of the key in the Key Description field. (optional)
6. Keys can be associated with a group or with an individual user. Select the group the key is associated with from the Key Group dropdown. Alternatively, you can associate the key with an individual user by selecting key is owned by user from the dropdown. The key is owned by user selection opens the Key Owner item in the Add Key dialog. If you have not created a group, you can still create a key, but the key is owned by user option is the only one available.
7. Select a key location (Production, Dev or Test) from the Key Location dropdown.
8. Click Automatic Rotation (optional). The Rotation Interval field appears.
The automatic rotation feature allows you to set a recurring key rotation period. After the set time has elapsed and just prior to the provisioning of the key, the key automatically rotates.
9. Click inside the Rotation Interval field to open the Interval dialog. Enter the interval between key rotations in the fields provided.
10. Click Apply to set the schedule. The schedule is now displayed in the Rotation Interval field.
11. Click Disable Key Until Date. (optional)
This function hides the private part of the key when you use the /service/key/get API endpoint. The private part of the key displays in the API response once the selected time and date have passed. Click the date on the calendar, select a time and click on the applicable time zone.
Note: The only way to see key data is through the API.
KeyNexus page 21 of 44 KeyNexus Configuration KeyNexus
12. Click Save. A message appears indicating the key was successfully created.
Import Custom Keys
In addition to generating its own keys, KeyNexus can also import and store keys generated outside KeyNexus. This operation can be performed in several different ways; it can be imported as a Base64 encoded AES key, as an RSA public and private key pair, or as a custom key. This section describes the method for importing and storing each key type. Import a Base64 Encoded AES key
1. Under the Symmetric tab, select Import Existing Key from the Key Type dropdown. The Base64 Encoded Key field appears under the Key Type dropdown.
2. Enter the Base64 encoded key in the Base64 Encoded Key field.
3. Follow the remaining steps as shown in the To add a new key section to complete the import process. Encode and Decode AES keys in Base64
To encode an existing AES key in Base64 on a Linux or Mac system, enter the following command through the command line interface: base64 [infile.txt] > [outfile.b64]
To decode the Base64 file stored in KeyNexus and save it to a text file on a Linux or Mac system, retrieve the key through a cURL request and enter the following command through the command line interface: base64 -D [infile.b64] > [outfile.txt]
To encode an existing AES key in Base64 on a Windows system, enter the following command in the command line interface:
Page 22 of 44 KeyNexus KeyNexus KeyNexus Configuration certutil -encode [infile.txt] [outfile.b64]
To decode the Base64 file stored in KeyNexus and save it to a text file on a Windows system, retrieve the key through a cURL request and enter the following command through the command line interface: certutil -decode [infile.b64] [outfile.txt]
Note: The length of the encoded AES key is determined from the input, but it must be one of the supported lengths (128, 192 or 256 bits). If your key is not one of the supported lengths, it is recommended that you import it as a custom key. See Importing Custom Keys for more information.
Import RSA keys
1. Under the Asymmetric tab, select the key type from the Key Type dropdown and check the Import Existing Key box below.
2. Add the Public Key and Private Key information in the applicable fields.
3. Follow the remaining steps as shown in the To add a new key section to complete the import process.
KeyNexus page 23 of 44 KeyNexus Configuration KeyNexus
Import Custom Keys
1. Under the Custom tab, Enter the key data into the Custom Key field. You can do this by copying the key content and pasting it into the field, dropping the key file into the field, or by clicking the Upload file button, navigating to the file location and clicking the Open button.
2. Follow the remaining steps as shown in the To add a new key section to complete the import process. Key Details
Once a key has been created or imported, it appears in the table located on the Keys page.
Click View beside each key name to display additional key details, edit attributes or rotate the key.
Page 24 of 44 KeyNexus KeyNexus KeyNexus Configuration
Key users also have the option of downloading the key from this page.
Key Rotation
Key Rotation retains the attributes of the original encryption key while generating new key data. Rotating keys on a regular basis reduces the risk of future compromise to your encrypted data. To rotate your key manually, click Rotate, then click Confirm Rotate. When the key has successfully rotated, the key version increments. Information relating to the rotation appears in Key History. To set or change the rotation schedule after a key has been created, make sure the Automatic Rotation option has been selected and click in the Rotation Interval field to set the rotation schedule.
KeyNexus page 25 of 44 KeyNexus Configuration KeyNexus
Note: Only AES and RSA keys can be rotated. Custom keys cannot be rotated. Note: Rotating your key periodically should be part of your key management strategy.
Page 26 of 44 KeyNexus KeyNexus KeyNexus Configuration
Edit Key Attributes
Select Edit Key Attributes to make changes to the key description, set the automatic key rotation, or edit key access restrictions.
Enter any information concerning the key in the Key Description field.
Set the Key Rotation schedule
Select Automatic Rotation to set a recurring key rotation period. After the set time has elapsed, the key automatically rotates.
1. Select the Automatic Rotation check box.
2. Click inside the Rotation Interval field to open the Interval dialog. Enter the interval between key rotations in the fields provided.
3. Click Apply to set the schedule.
Note: When automatic rotation is set, the rotation is not performed until necessary, such as just prior to provisioning. For example, if the key is not provisioned for 5 days, then the key is not rotated in this time period, even if the rotation interval is less than 5 days.
KeyNexus page 27 of 44 KeyNexus Configuration KeyNexus
Edit Key Access Restrictions
Use the Edit Key Access Restrictions feature to disable the key until a specific date, or to make changes to an existing key access restriction that was set during the key creation process.
1. Under Edit Key Access Restrictions, select the Set New Time option.
2. Select the Month, Day and Time that the access restriction ends.
3. Set the Time Zone.
When all changes have been made in the Modify Key dialog, click Apply changes to return to the key’s View page. Key Operations History
You can also view your key history from this page. Operations History allows you to view the key operations since it was created. Select a filter from the dropdown list to limit the history to Add, Add Batch, Change State, Delete, Get, Get Batch, and Rotate. Select All Operations to view the complete history of the key.
Page 28 of 44 KeyNexus KeyNexus KeyNexus Configuration
Note: Operations History information is only available to users with Admin access.
Download a Key
When a AES, RSA or custom key has been successfully generated or imported, you also have the option of downloading the key. This can be useful when removing any formatting changes. Log in under the key owner’s account. Click the Keys tab and click View beside the name of the key.
Click the Download Key button. The key file downloads to your system. Note: When downloading RSA keys, there are two download options; one for the private key, the second for the public key.
KeyNexus page 29 of 44 KeyNexus Configuration KeyNexus
Delete a Key
1. Click Delete to permanently remove this key. Click Confirm Delete to complete this action or Cancel to return to the Manage Keys page. Important: This operation cannot be undone. Ensure this operation is necessary before you proceed.
Search for a Key
Use the Search field to locate existing keys. The keys table is filtered to display only keys matching the entry provided in the field. For example, entering ‘key' displays only the groups that contain ‘key’ in their name.
Add keys through the API
All the configuration request examples shown in this section are through cURL.
The service/key/add endpoint allows you to create a key. Adding a key with business ID and credentials curl -k -H "content-type: application/json" -XPOST "https://your.ip:1443/service/key/add" -d '{ "business": "BUSINESS_ID", "creds": [ { "username": "USER", "password": "PASSWORD" } ], "group": "KEY_GROUP", "keyLocation": "LOCATION", "keyType": "TYPE", "keyName": "KEY_NAME" }'
Page 30 of 44 KeyNexus KeyNexus KeyNexus Configuration
Once you have authenticated with a Business ID and credentials with the authentication endpoint, the API returns a token. Use this token for the remainder of the endpoints that require or use a token for authenticating. Adding a key with a token curl -k -H "content-type: application/json" -XPOST "https://your.ip:1443/service/key/add" -d '{ "token": "TOKEN", "group": "KEY_GROUP", "keyLocation": "LOCATION", "keyType": "TYPE", "keyName": "KEY_NAME" }'
Add Batch Keys through the API
All the configuration request examples shown in this section are through cURL. add_batch allows you to create multiple keys at one time, rather than using add, which creates keys one at a time. Add_batch using a Business ID and credentials curl -k -H "content-type: application/json" -XPOST "https://your.ip:1443/service/key/add_batch" -d '{ "business": "BUSINESS_ID", "creds": [ { "username" : "USER", "password" : "PASSWORD" } ], "group": "KEY_GROUP", "keys": [ { "keyName": "KEY_NAME_A", "keyType": "KEY_TYPE_A", "keyLocation": "LOCATION_A" }, { "keyName": "KEY_NAME_B", "keyType": "KEY_TYPE_B", "keyLocation": "LOCATION_B" } ] }'
KeyNexus page 31 of 44 KeyNexus Configuration KeyNexus
Once you have authenticated with a Business ID and credentials with the authentication endpoint, the API returns a token. Use this token for the rest of the endpoints that require or use a token for authenticating. Add_batch using a token curl -k -H "content-type: application/json" -XPOST "https://your.ip:1443/service/key/add_batch" -d '{ "token": "TOKEN", "group": "KEY_GROUP", "keys": [ { "keyName": "KEY_NAME_A", "keyType": "KEY_TYPE_A", "keyLocation": "LOCATION_A" }, { "keyName": "KEY_NAME_B", "keyType": "KEY_TYPE_B", "keyLocation": "LOCATION_B" } ], }'
For each of the examples shown: “https://your.ip:1443/service/key/add” is the address of your VM, the port number and the add key endpoint.
“business” is the Business ID for your KeyNexus instance.
“username” is the name of the user signing in to create a key.
“password” is the password of the user signing in to create a key.
“token” is the returned value when you have provided the API a valid Business ID, username and password.
“keyLocation” defines where the key is assigned (Production, Dev or Test)
“group” is the group the key is associated with.
“keyName” is an optional parameter for providing the name of the key. keyName cannot be the same name used for an existing key. keyName cannot contain uppercase letters.
“keyType” defines the type of key used. The different allowable key types are: AES128, AES192, AES256, RSA2048, RSA3072, RSA4096, ECDSA or CUSTOM. If Custom key type is used, the keyData parameter that contains data related to the custom key must be included in the request.
Page 32 of 44 KeyNexus KeyNexus KeyNexus Configuration
If ECDSA (Elliptic Curve Digital Signature Algorithm) is used for the keyType, you can include the keyParams parameter and set it to one of the many available security curves. If ECDSA is selected and keyParams is not included in the request, the default parameter prime256v1 is used.
KeyNexus page 33 of 44 KeyNexus Configuration KeyNexus
Available ECDSA curves
FRP256v1, brainpoolp160r1, brainpoolp160t1, brainpoolp192r1, brainpoolp192t1, brainpoolp224r1, brainpoolp224t1, brainpoolp256r1, brainpoolp256t1, brainpoolp320r1, brainpoolp320t1, brainpoolp384r1, brainpoolp384t1, brainpoolp512r1, brainpoolp512t1, B-163, B-233, B-283, B-409, B-571, K-163, K-233, K-283, K-409, K-571, P-192, P-224, P-256, P-384, P-521, secp112r1, secp112r2, secp128r1, secp128r2, secp160k1, secp160r1, secp160r2, secp192k1, secp192r1, secp224k1, secp224r1, secp256k1, secp256r1, secp384r1, secp521r1, sect113r1, sect113r2, sect131r1, sect131r2, sect163k1, sect163r1, sect163r2 , sect193r1, sect193r2, sect233k1, sect233r1, sect239k1, sect283k1, sect409k1, sect409r1, sect571k1, sect571r1, c2pnb163v1, c2pnb163v2, c2pnb163v3, c2pnb176w1, c2tnb191v1, c2tnb191v2, c2tnb191v3, c2pnb208w1, c2tnb239v1, c2tnb239v2, c2tnb239v3, c2pnb272w1, c2pnb304w1, c2tnb359v1, c2pnb368w1, c2tnb431r1, prime192v1, prime192v2, prime192v3, prime239v1, prime239v2, prime239v3 prime256v1
Note: When using the add_batch endpoint, the keyType and keyLocation information must be provided for each individual key (KEY_TYPE_A, KEY_TYPE_B, etc.). This also applies if you are including the optional keyNames parameter in the request.
Users
The Users feature is used to create additional administrator and key user accounts, and to view and edit existing key request accounts and key groups. Note: The Users tab is only available to users with Admin access. Note: Each key must be associated with a group and each Key Access user must be in a group. 1. Click the Users tab. The Users page appears.
2. Click Administrators to view all users with admin access, or click Key Users to view all users with key user access.
Create a New User
1. Click Add User. The Add New User dialog appears.
Page 34 of 44 KeyNexus KeyNexus KeyNexus Configuration
1. Enter the information required in the Add New User dialog:
Field name Value/Description Username Enter username. User Role Check the Administrator or Key Access User option. Administrators can create additional keys, users and groups, while Key Access Users can create and manage keys, but cannot create additional users or groups. Groups Select a group or groups from the available group names. This option is only available with the Key Access user. Default Group From the list of groups, the user is a part of, you can select one to act as a default group. This is primarily used when integrating KeyNexus as a Key Management Server (KMS). (optional) Email Enter email associated with this account. (optional) Authenticate via Client Cert Select this option to generate or upload a certificate used to authenticate this user. You can download the certificate after the
KeyNexus page 35 of 44 KeyNexus Configuration KeyNexus
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. Confirm Password Re-enter your password
The Strength Meter under the Password field displays the strength of the entered password. Password strength levels are displayed as a colored bar below the Password field, and identified as Weak, Medium, Strong or Very Strong.
2. (Optional) 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 field 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.).
3. Click Add User.
Authentication Certificate
Instead of using a username and password to authenticate a KeyNexus user, you can generate, download or upload 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.
Page 36 of 44 KeyNexus KeyNexus KeyNexus Configuration
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. Important: Enabling a new authentication method automatically disables any existing method. When you generate a new certificate, your login credentials change. Any current authentication token becomes invalid and your login session terminates. Make sure you click Download to download the new certificate. If you do not download the certificate, you will be unable to log back in, as the current login credentials have been disabled. Note: If there is no existing authentication certificate associated with the user, the dialog displays a message indicating you must generate a new certificate. Note: Generating a new certificate automatically invalidates any existing certificate for that user. To apply an existing authentication certificate to the user account, click Upload. Copy and paste the authentication certificate information into the Certificate field.
KeyNexus page 37 of 44 KeyNexus Configuration KeyNexus
Note: when uploading an auth cert, make sure it contains matching user and Business ID information. If the certificate does not contain these items, a message appears, indicating that the certificate is not valid. This certificate can be provided when integrating KeyNexus to different applications. For an example of how the authentication certificate is used, refer to the KeyNexus VSphere Integration Guide.
Delete a User
1. Click Delete beside the user name in the Users list to permanently remove this user. Click Confirm Delete to complete this action or Cancel to return to the Users page. Note: This operation cannot be undone.
Note: Before deleting a user, ensure that any keys owned by that user have also been deleted.
To search for a user
1. Use the Search field to locate existing users. The Users table is filtered to display only the user names that match the entry provided in the field. For example, entering ‘b' displays only the user names that contain the letter ‘b’.
Page 38 of 44 KeyNexus KeyNexus Google Cloud SDK
Google Cloud SDK
The Google Cloud SDK is a set of tools used by Cloud Platform that allows you to access Cloud Platform services from the command line. The Google Cloud SDK contains:
• gcloud: provides primary command line interface to Google Cloud Platform. • gsutil: python-based application for accessing Google Cloud Platform from the command line. • bq: python-based tool for accessing BigQuery from the command line. For the purposes of this guide, gcloud and gsutil will be discussed. To install and configure Google Cloud SDK: 1. Navigate to Google Cloud SDK page (https://cloud.google.com/sdk/).
2. Select the OS you want to install for from the Install from… dropdown.
3. Click the Google Cloud SDK Installer link to download the SDK installer.
4. Launch the Google Cloud SDK Installer. The Google Cloud SDK Setup Wizard opens. Click Next.
KeyNexus page 39 of 44 Google Cloud SDK KeyNexus
5. Review the license agreement and click I Agree to continue.
6. Select the install type and click Next.
7. Enter the install location in the Destination Folder field or click Browse and navigate to the folder you want to install the Google Cloud SDK to. Click Next.
8. Select the components to install and click Install. Wait for the components to install. Click Next when the install is complete.
9. Select from the different checkboxes, making sure to leave the Start Google Cloud SDK Shell and the Run gcloud init to configure the Cloud SDK boxes checked. The SDK shell opens and the gcloud init command executes.
Page 40 of 44 KeyNexus KeyNexus Google Storage Utililty
10. Follow the gcloud sdk configuration instructions. KeyNexus Patches
There are three patches required to add KeyNexus functionality to the Google Cloud SDK.
• create.py: patch to fix image create support for CSEK.
• csek_utils.py: patch to add gcloud KeyNexus key support.
• gsutil.patch: patch to add gsutil KeyNexus keysupport.
In the gcloud integration package, an installation script is provided to automate the patching process. Run the install.sh to install the script. Google Storage Utililty
Google Storage Utility (gsutil) is a Python-based tool for managing buckets and objects in Google Cloud Storage from the command line. The patch provided in the gcloud integration package adds support for keys that are stored and managed by an instance of KeyNexus to be used with Google Cloud Storage. gsutil uses a BOTO configuration file, which can be created in a location defined by setting the boto_config environment variable. The default location for the .boto configuration file is in your home directory. Running gsutil config creates the file automatically. KeyNexus requires the [GSUtil] section of the file to be configured. Open the BOTO file with a source code editor to add the following configuration: encryption_key=keynexus_key keynexus_host="
KeyNexus page 41 of 44 Google Storage Utililty KeyNexus keynexus_name="
Where:
Encryption_key is a required option that must be added to the BOTO configuration file when using customer-supplied encryption keys. keynexus_host is a comma delimited list consisting of the address and port of one or more KeyNexus VMs that were setup. Specifying multiple address allows automatic failover. keynexus_name is the name of the key to use. keynexus_user is the username of a Key Request Account. keynexus_password is the password for the Key Request account.
Encrypting and Decrypting objects on Google Cloud Platform
Google Cloud Disk Encryption and Decryption
Google Cloud Platform has its own encryption through Google Compute Engine, but allows customers to supply their own encryption keys. For more information about encrypting disks with customer supplied encryption on the Google Cloud Platform, refer to https://cloud.google.com/compute/docs/disks/customer-supplied-encryption. The KeyNexus patch provided in the gcloud integration package enhances the for Customer- Supplied Encryption Key csek-key-file JSON configuration by adding in support for KeyNexus stored keys.
A sample JSON configuration csek-key-file is available in the sample directory included in the gcloud integration package.
Change the project name and zone as necessary to match your settings. Encrypting and decrypting objects
When gsutil is configured to use KeyNexus, uploaded objects are automatically encrypted with the latest version of a key. Similarly, downloaded objects are automatically decrypted with the version of the key that they were originally encrypted with. Use mv (move/remove objects or subdirectories) or cp (copy files and objects) to upload or download files:
# Upload a local file and encrypt it with key
Page 42 of 44 KeyNexus KeyNexus Google Storage Utililty
# Decrypt and download a remote_file gsutil cp gs://
KeyNexus page 43 of 44
KeyNexus gcloud Integration Guide v1.2
Copyright 2018 KeyNexus Inc. All rights reserved. KeyNexus is a trademark of KeyNexus Inc. All other product names, logos, and brands are KeyNexus Inc. property of their respective owners. All other company, 205 2657 product and service names used in this document are Wilfert Road for identification purposes only. Use of these names, Victoria, B.C. V9B 5Z3 logos, and brands does not imply endorsement.