INTEGRATION GUIDE SAFENET LUNA HSM SAFENET DATA … · hashicorp vault integration guide safenet...

HashiCorp Vault INTEGRATION GUIDE

SAFENET LUNA HSM

SAFENET DATA PROTECTION ON DEMAND

HashiCorp Vault Integration Guide 007-000264-001, Rev. B, November 2019, Copyright © 2019 Gemalto

2

Document Information

Document Part Number 007-000264-001

Release Date November 2019

Revision History

Revision Date Reason

B November 2019 Update

Trademarks, Copyrights, and Third-Party Software

© 2019 Gemalto. All rights reserved. Gemalto and the Gemalto logo are trademarks and service marks of

Gemalto N.V. and/or its subsidiaries and are registered in certain countries. All other trademarks and

service marks, whether registered or not in specific countries, are the property of their respective owners.

Disclaimer

All information herein is either public information or is the property of and owned solely by Gemalto NV.

and/or its subsidiaries who shall have and keep the sole right to file patent applications or any other kind of

intellectual property protection in connection with such information.

Nothing herein shall be construed as implying or granting to you any rights, by license, grant or otherwise,

under any intellectual and/or industrial property rights of or concerning any of Gemalto’s information.

This document can be used for informational, non-commercial, internal and personal use only provided

that:

The copyright notice below, the confidentiality and proprietary legend and this full warning notice

appear in all copies.

This document shall not be posted on any network computer or broadcast in any media and no

modification of any part of this document shall be made.

Use for any other purpose is expressly prohibited and may result in severe civil and criminal liabilities.

The information contained in this document is provided “AS IS” without any warranty of any kind. Unless

otherwise expressly agreed in writing, Gemalto makes no warranty as to the value or accuracy of

information contained herein.

The document could include technical inaccuracies or typographical errors. Changes are periodically

added to the information herein. Furthermore, Gemalto reserves the right to make any change or

improvement in the specifications data, information, and the like described herein, at any time.

Gemalto hereby disclaims all warranties and conditions with regard to the information contained herein,

including all implied warranties of merchantability, fitness for a particular purpose, title and non-

infringement. In no event shall Gemalto be liable, whether in contract, tort or otherwise, for any indirect,

special or consequential damages or any damages whatsoever including but not limited to damages

resulting from loss of use, data, profits, revenues, or customers, arising out of or in connection with the use

or performance of information contained in this document.


3

Gemalto does not and shall not warrant that this product will be resistant to all possible attacks and shall

not incur, and disclaims, any liability in this respect. Even if each product is compliant with current security

standards in force on the date of their design, security mechanisms' resistance necessarily evolves

according to the state of the art in security and notably under the emergence of new attacks. Under no

circumstances, shall Gemalto be held liable for any third party actions and in particular in case of any

successful attack against systems or equipment incorporating Gemalto products. Gemalto disclaims any

liability with respect to security for direct, indirect, incidental or consequential damages that result from any

use of its products. It is further stressed that independent testing and verification by the person using the

product is particularly encouraged, especially in any application in which defective, incorrect or insecure

functioning could result in damage to persons or property, denial of service or loss of privacy.

Contents


4

CONTENTS

PREFACE.............................................................................................................................. 5

Scope ................................................................................................................................................................. 5 Document Conventions ...................................................................................................................................... 5

Command Syntax and Typeface Conventions ............................................................................................... 6 Support Contacts ............................................................................................................................................... 7

Customer Support Portal ................................................................................................................................ 7 Telephone Support ......................................................................................................................................... 7 Email Support ................................................................................................................................................. 7

CHAPTER 1: Introduction.................................................................................................. 8

Overview ............................................................................................................................................................ 8 Third Party Application Details ........................................................................................................................ 8 Supported Platforms ....................................................................................................................................... 8

Prerequisites ...................................................................................................................................................... 9 Configure the SafeNet Luna HSM .................................................................................................................. 9 Provisioning your HSM on Demand Service ................................................................................................ 10 Constraints on HSMoD Services .................................................................................................................. 10 Setting up HashiCorp Vault .......................................................................................................................... 11

CHAPTER 2: Integrating HashiCorp Vault with SafeNet HSM ........................................ 12

Configuring HashiCorp Vault ........................................................................................................................... 12 Enabling the PKCS11 seal ........................................................................................................................... 12 Initializing the Vault ....................................................................................................................................... 14 Logging into the Vault ................................................................................................................................... 15 Using the Secrets Engine ............................................................................................................................. 16

Rotating HashiCorp Vault Keys ....................................................................................................................... 17

Preface


5

PREFACE

This document is intended to guide administrators through the steps for using a SafeNet Luna HSM or an HSM on Demand service with HashiCorp Vault.

Scope This document outlines the steps to integrate HashiCorp Vault with SafeNet Luna HSM or HSM on Demand service.

Document Conventions This section provides information on the conventions used in this template.

Notes

Notes are used to alert you to important or helpful information. These elements use the following format:

NOTE: Take note. Notes contain important or helpful information.

Cautions

Cautions are used to alert you to important information that may help prevent unexpected results or data

loss. These elements use the following format:

CAUTION! Exercise caution. Caution alerts contain important information that may

help prevent unexpected results or data loss.

Warnings

Warnings are used to alert you to the potential for catastrophic data loss or personal injury. These

elements use the following format:

**WARNING** Be extremely careful and obey all safety and security measures. In

this situation you might do something that could result in catastrophic data loss

or personal injury

Preface


6

Command Syntax and Typeface Conventions

Convention Description

bold The bold attribute is used to indicate the following:

Command-line commands and options (Type dir /p.)

Button names (Click Save As.)

Check box and radio button names (Select the Print Duplex check box.)

Window titles (On the Protect Document window, click Yes.)

Field names (User Name: Enter the name of the user.)

Menu names (On the File menu, click Save.) (Click Menu > Go To >

Folders.)

User input (In the Date box, type April 1.)

italic The italic attribute is used for emphasis or to indicate a related document. (See the Installation Guide for more information.)

Double quote marks Double quote marks enclose references to other sections within the document.

<variable> In command descriptions, angle brackets represent variables. You must substitute a value for command line arguments that are enclosed in angle brackets.

[ optional ]

[ <optional> ]

[ a | b | c ]

[<a> | <b> | <c>]

Square brackets enclose optional keywords or <variables> in a command line description. Optionally enter the keyword or <variable> that is enclosed in square brackets, if it is necessary or desirable to complete the task.

Square brackets enclose optional alternate keywords or variables in a command line description. Choose one command line argument enclosed within the braces, if desired. Choices are separated by vertical (OR) bars.

{ a | b | c }

{ <a> | <b> | <c> }

Braces enclose required alternate keywords or <variables> in a command line description. You must choose one command line argument enclosed within the braces. Choices are separated by vertical (OR) bars.

Preface


7

Support Contacts If you encounter a problem while installing, registering, or operating this product, refer to the

documentation. If you cannot resolve the issue, contact your supplier or Gemalto Customer Support.

Gemalto Customer Support operates 24 hours a day, 7 days a week. Your level of access to this service is

governed by the support plan arrangements made between Gemalto and your organization. Please consult

this support plan for further information about your entitlements, including the hours when telephone

support is available to you.

Customer Support Portal

The Customer Support Portal, at https://supportportal.thalesgroup.com, is a where you can find solutions

for most common problems. The Customer Support Portal is a comprehensive, fully searchable database

of support resources, including software and firmware downloads, release notes listing known problems

and workarounds, a knowledge base, FAQs, product documentation, technical notes, and more. You can

also use the portal to create and manage support cases.

NOTE: You require an account to access the Customer Support Portal. To create a new account, go to the portal and click on the REGISTER link.

Telephone Support

If you have an urgent problem, or cannot access the Customer Support Portal, you can contact Gemalto

Customer Support by telephone at +1 410-931-7520. Additional local telephone support numbers are listed

on the support portal.

Email Support

You can also contact technical support by email at [email protected].

https://supportportal.thalesgroup.com/

https://supportportal.thalesgroup.com/

mailto:[email protected]

CHAPTER 1: Introduction


8


Overview This document guides security administrators through the steps for integrating HashiCorp Vault with SafeNet HSMs. SafeNet HSMs come as on-premise hardware HSMs widely known as SafeNet Luna HSM and a cloud offering HSM on Demand (HSMoD) service.

HashiCorp Vault Enterprise allows HSM support as a feature. It uses the HSM for:

Master Key Wrapping: HashiCorp Vault protects its master key by transiting it through the HSM for encryption rather than splitting into key shares.

Automatic Unsealing: HashiCorp Vault stores its HSM-wrapped master key in storage, allowing for automatic unsealing.

Seal Wrapping: Provides FIPS key storage conforming functionality for Critical Security Parameters.

This document describes how to store the HashiCorp Vault encryption key on a SafeNet Luna HSM or an HSMoD service.

The benefits of securing the keys with SafeNet HSM include:

Secure generation, storage and protection of the encryption keys on FIPS 140-2 level 3 validated hardware.

Full life cycle management of the keys.

Access to the HSM audit trail*.

Take advantage of cloud services with confidence.

*HSMoD services do not have access to the secure audit trail

Third Party Application Details

This integration uses the following third party applications:

HashiCorp Enterprise HSM Vault Binary

Supported Platforms

List of the platforms which are tested with the following HSMs:

SafeNet Luna HSM: SafeNet Luna HSM appliances are purposefully designed to provide a balance of

security, high performance, and usability that makes them an ideal choice for enterprise, financial, and

government organizations. SafeNet Luna HSMs physically and logically secure cryptographic keys and

accelerate cryptographic processing.

The SafeNet Luna HSM on premise offerings include the SafeNet Luna Network HSM, SafeNet PCIe

HSM, and SafeNet Luna USB HSMs. SafeNet Luna HSMs are also available for access as an offering

from cloud service providers such as IBM cloud HSM and AWS cloud HSM classic.

Platforms tested:

RHEL



9

SafeNet Data Protection on Demand (DPoD): SafeNet DPoD is a cloud-based platform that provides on-

demand HSM and Key Management services through a simple graphical user interface. With DPoD,

security is simple, cost effective and easy to manage because there is no hardware to buy, deploy and

maintain. As an Application Owner, you click and deploy services, generate usage reports and maintain

only the services that you need.

Platforms tested:

RHEL

Prerequisites Before beginning the integration, ensure you complete the following steps. Configure the SafeNet Luna

HSM or Provisioning your HSM on Demand Service.

Configure the SafeNet Luna HSM

If you are using a SafeNet Luna HSM, complete the following:

1. Verify the HSM is set up, initialized, provisioned and ready for deployment. Refer to the SafeNet Luna HSM Product Documentation for more information.

2. Create a partition on the HSM that will be later used by HashiCorp Vault.

3. If using a SafeNet Luna Network HSM, register a client for the system and assign the client to the partition to create an NTLS connection. Initialize the Crypto Officer and Crypto User roles for the registered partition.

4. Ensure that each partition is successfully registered and configured. The command to see the registered partitions is:

# /usr/safenet/lunaclient/bin/lunacm

LunaCM (64-bit) v7.3.0-165. Copyright (c) 2018 SafeNet. All rights

reserved.

Available HSMs:

Slot Id -> 0

Label -> HashiCorp Vault

Serial Number -> 1280780175943

Model -> LunaSA 7.3.0

Firmware Version -> 7.3.0

Configuration -> Luna User Partition With SO (PW) Key Export With

Cloning Mode

Slot Description -> Net Token Slot

NOTE: Follow the SafeNet Luna Network HSM Product Documentation for detailed steps for creating the NTLS connection, initializing the partitions, and initializing the Security Officer, Crypto Officer, and Crypto User roles.

SafeNet Luna HSM HA (High-Availability) Setup

Refer to the SafeNet Luna Network HSM Product Documentation for HA steps and details regarding

configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly setting



10

in HA for failover to work so that if the primary goes down due to any reason all calls automatically route to

the secondary until the primary recovers and starts up.

Using SafeNet Luna HSM in FIPS Mode

Under FIPS 186-3/4, the RSA methods permitted for generating keys are 186-3 with primes and 186-3 with

aux primes. This means that RSA PKCS and X9.31 key generation is no longer approved for operation in a

FIPS-compliant HSM. If you are using the SafeNet Luna HSM in FIPS mode, you have to make the

following change in configuration file:

For Linux:

Misc = {

RSAKeyGenMechRemap = 1;

}

For Windows:

[Misc]

RSAKeyGenMechRemap=1

The above setting redirects the older calling mechanism to a new approved mechanism when SafeNet

Luna HSM is in FIPS mode.

Provisioning your HSM on Demand Service

Create an HSM on Demand Service for HashiCorp Vault to use. Refer to the SafeNet Data Protection on

Demand Platform HELP for detailed configuration and setup procedures. Please familiarize yourself with

the section Constraints on HSMoD Services before proceeding.

Before beginning the integration with an HSMoD service, ensure the following:

1. HSMoD service for HashiCorp Vault integration exists.

2. HSMoD service client is downloaded and available on the client system.

NOTE: The HSMoD service client is a zip file that contains system information required to connect the client machine to the HSMoD service.

3. HSMoD service is initialized with the following user roles:

a. Security Officer (SO)

b. Crypto Officer (CO)

c. Crypto User (CU)

Constraints on HSMoD Services

Please take the following limitations into consideration when integrating your application software with an

HSM on Demand Service.



11

HSM on Demand Service in FIPS mode

HSMoD services operate in a FIPS and non-FIPS mode. If your organization requires non-FIPS algorithms

for your operations, ensure you enable the Allow non-FIPS approved algorithms check box when

configuring your HSM on Demand service. The FIPS mode is enabled by default.

Refer to the Mechanism List in the SDK Reference Guide for more information about available FIPS and

non-FIPS algorithms.

Verifying HSM on Demand <slot> value

LunaCM commands work on the current slot. If there is only one slot, then it is always the current slot. If

you are completing an integration using HSMoD services, you need to verify which slot on the HSMoD

service you have sent the commands. If there is more than one slot, then use the slot set command to

direct a command to a specified slot. You can use slot list to determine which slot numbers are in use by

which HSMoD service.

Setting up HashiCorp Vault

Download and install the HashiCorp Vault and set up the system environment to support the integration. HashiCorp Vault is distributed as a binary package for all supported platforms. The HashiCorp Vault is packaged as a zip archive. For more detailed information, refer to the HashiCorp Documentation.

1. Download the HashiCorp Vault package from HashiCorp.

2. Unzip the package in the working directory on the host machine. HashiCorp Vault runs as a single

binary named vault.

3. Add the current working directory to the PATH, so that vault is executable from any directory.

4. After installing vault, verify the installation worked by opening a new terminal session and checking

that the vault binary is available. By executing vault, you should see help output similar to the

following:

CHAPTER 2: Integrating HashiCorp Vault with SafeNet HSM


12


Configuring HashiCorp Vault To set up HashiCorp Vault using a SafeNet Luna HSM or HSM on Demand (HSMoD) service, complete the following:

Enabling PKCS11 seal

Initializing the Vault

Logging into the Vault

Using the Secret Engine

Enabling the PKCS11 seal

The PKCS11 seal configures HashiCorp Vault to use an HSM with PKCS11 as the seal wrapping mechanism.

To enable the PKCS11 seal

1. Create the HashiCorp Vault's configuration file named config.json and specify the following:

Where :

lib: The path to the PKCS#11 library shared object file.

slot : HSM partition slot number.

# PKCS11 seal seal "pkcs11" { lib = "<path to cryptoki library>" slot = "<slot number>" pin = "<partition password>" key_label = "HashiCorp" hmac_key_label = "HashiCorp_hmac" generate_key = "true" } storage "file" { path = "/tmp/vault" } # Addresses and ports on which Vault will respond to requests listener "tcp" { address = "127.0.0.1:8200" tls_disable = "true" } ui = true



13

pin : HSM partition password

generate_key : It instructs Vault to generate a key if no existing key with the label specified

by key_label can be found at Vault initialization time.

hmac_key_label : The label of the key to use for HMACing

NOTE: Alternatively, the HSM seal can be activated by providing the following environment variables:

VAULT_HSM_LIB, VAULT_HSM_SLOT, VAULT_HSM_PIN, VAULT_HSM_KEY_LABEL, VAULT_HSM_HMAC_KEY_LABEL and VAULT_HSM_GENERATE_KEY

Although the configuration file allows you to pass in VAULT_HSM_PIN as part of the seal's parameters, it is strongly recommended to set this value via environment variables.

2. Start the Vault server using the configuration file.

# ./vault server -config config.json



14

Initializing the Vault

You must initialize the Vault before you may access it to begin configuring and managing secrets.

To initialize the HashiCorp Vault

1. Launch a new terminal session and execute the following command:

# export VAULT_ADDR='http://127.0.0.1:8200'

2. Check the status of Vault by executing :

# ./vault status

3. Initialize the Vault by executing :

# ./vault operator init -recovery-shares=1 -recovery-threshold=1

This will generate a recovery key and initial root token. Copy these keys and keep it in safe place.

Note the following logs in the first terminal where Vault Server is running :

2018-11-16T06:15:48.859-0500 [INFO] core: loaded wrapping token key

2018-11-16T06:15:48.860-0500 [INFO] core: successfully mounted backend:

type=kv path=secret/

…

2018-11-16T06:15:48.952-0500 [INFO] core: root token generated

…

2018-11-16T06:15:49.031-0500 [INFO] core: vault is unsealed

2018-11-16T06:15:49.032-0500 [INFO] core: post-unseal setup starting

2018-11-16T06:15:49.153-0500 [INFO] core: loaded wrapping token key

…

2018-11-16T06:15:49.157-0500 [INFO] core: successfully unsealed with stored

key(s): stored_keys_used=1



15

2018-11-16T06:15:49.157-0500 [INFO] expiration: lease restore complete

4. Verify the keys generated on the partition by executing partition contents in lunacm.

Logging into the Vault

You must log in to the Vault to begin configuring and managing the secrets engine.

To log in to the HashiCorp Vault

1. Log into the Vault.

# ./vault login <VAULT-TOKEN>

where <VAULT-TOKEN> is the initial root token generated during Vault initialization.



16

2. If UI is enabled in configuration file (config.json), the Vault UI can be accessed:

http://127.0.0.1:8200/ui

Provide the VAULT TOKEN in the field of Token to login.

Using the Secrets Engine

Secrets engines are components which store, generate, or encrypt data. The kv secrets engine is used to store

arbitrary secrets within the configured physical storage for Vault. Versioning can be enabled and a configurable number of versions for each key will be stored.

To use the Secrets Engine

1. To view the secrets, execute :

# ./vault secrets list

2. Enable the kv engine

# ./vault secrets enable -version=1 kv

Success! Enabled the kv secrets engine at: kv/

http://127.0.0.1:8200/ui

http://127.0.0.1:8200/ui



17

3. Write arbitrary secret data

# ./vault kv put kv/my-secret my-value=s3cr3t

Success! Data written to: kv/my-secret

4. Display the secret value by executing command:

# ./vault kv get kv/my-secret

====== Data ======

Key Value

--- -----

my-value s3cr3t

This completes the integration of HashiCorp Vault with SafeNet Luna HSM or HSM on Demand (HSMoD) service.

Rotating HashiCorp Vault Keys The PKCS11 seal supports rotating keys by using different key labels to track key versions.

To rotate the key value, you generate a new key in a different key label in the HSM and update Vault's configuration with the new key label value. Restart your Vault instance to pick up the new key label and all new encryption operations will use the updated key label. Old keys must not be disabled or deleted as they are used to decrypt older data.

If rotation is desired for data that was seal wrapped prior to this version, set default_key_label and

hmac_default_key_label to allow for decryption of older values.

To rotate HashiCorp Vault Keys

1. Stop the Vault server from the terminal, if running.

2. Change the configuration file config.json as follows:

# PKCS11 seal seal "pkcs11" { lib = "<path to cryptoki library>" slot = "<slot number>" pin = "<partition password>" default_key_label="HashiCorp"

key_label = "HashiCorp_rot"

default_hmac_key_label = "HashiCorp_hmac"

hmac_key_label = "HashiCorp_hmac_rot"

generate_key = "true" } storage "file" { path = "/tmp/vault" } # Addresses and ports on which Vault will respond to requests listener "tcp" { address = "127.0.0.1:8200" tls_disable = "true" } ui = true



18

3. Start the Vault using the updated configuration file.

# ./vault server -config config.json

4. Launch a new terminal session and execute the following command :

# export VAULT_ADDR='http://127.0.0.1:8200'

5. Verify the Vault status and list the secrets by executing:

# ./vault secrets list

6. Verify the keys generated in the partition by executing partition contents in lunacm utility on host.

This completes the rotation of the HashiCorp Vault keys using SafeNet Luna HSM or HSM on Demand (HSMoD) service.

INTEGRATION GUIDE SAFENET LUNA HSM SAFENET DATA … · hashicorp vault integration guide safenet...

Documents

Transcript of INTEGRATION GUIDE SAFENET LUNA HSM SAFENET DATA … · hashicorp vault integration guide safenet...