Win $20,000. Help build the future of education. Answer the call. Learn more

Integrate Enterprise HashiCorp Vault with IBM Cloud Hyper Protect Crypto Services

Introduction

Stringent industry compliance requirements make selecting the best hardware security module (HSM) for integration with privileged access management security products such as HashiCorp Vault Enterprise a primary concern for businesses.

IBM Cloud Hyper Protect Crypto Service provides access to a cloud-based HSM that is FIPS 140-2 Level 4 certified and allows an interface using Enterprise PKCS#11 (ep11) that Vault Enterprise uses for both auto-unseal and seal wrapping capabilities to conform to the key storage and key transport requirements under the FIPS 140-2 compliance.

Vault provides a centralized approach to secrets-management across every element of the application delivery lifecycle. It also provides a highly available and secure way of storing and exposing secrets to applications and users such as encryption keys, API tokens, and database credentials. Vault allows teams to consume the data they need without coordinating with security teams. Security teams can change passwords, rotate credentials, and update policies without coordinating across the organization. Vault protects its database in storage with a Vault-Master Key, which is also held in storage on the Vault Enterprise Server. When a Vault server is started, it starts in a sealed state. In this state, Vault is configured to know where and how to access the physical storage, but doesn’t know how to decrypt any of it. Unsealing is the process of obtaining the plaintext master key necessary to read the decryption key to decrypt the data, allowing access to the Vault.

drawing Image source: https://www.vaultproject.io/img/vault-autounseal-storage.png

Vault pulls its encrypted master key from storage and moves it through the Cloud Hyper Protect Crypto Service for decryption via PKCS #11 / Cryptoki API. When the master key is decrypted, Vault uses it to decrypt the encryption key and then resume Vault operations. You can learn more about the scope of the cryptographic operations by Vault that is delegated to Cloud Hyper Protect Crypto Service via their Vault Compliance Letter.

Learning objectives

This tutorial gives you a starting point on how to integrate IBM Cloud Hyper Protect Crypto Service with HashiCorp Vault Enterprise’s auto-unseal and seal-wrap features.

drawing

Prerequisites

  1. Vault Binary – 1.6.1 Ent HSM Linux or later
  2. SSH Access to the virtual server instance where Enterprise Vault is or will be installed
  3. Ensure that you have access to an instance of IBM Cloud Hyper Protect Crypto Services
  4. Set up the Cloud Hyper Protect Crypto Services as PKCS#11 HSMs
  5. Install IBM Cloud CLI – supported platforms include Windows / Mac / Linux (x86 & s390x)
    • Install the Trusted Key Entry (TKE) plugin:
      ibmcloud plugin install tke
      
    • Log in to the IBM Cloud
      ibmcloud login -g <target resource group> -r <target region>
      

Estimated time

Completing this tutorial should take about 45 minutes.

Steps

1. Initialize Cloud Hyper Protect Crypto Service

First, you need to initialize the Cloud Hyper Protect Crypto Service instance and load a master key. The following diagram below shows an overview of the process:

Initialize Service Instances

You have two options when it comes to initializing the crypto units that are assigned for your Cloud Hyper Protect Crypto Service instance:

  1. Manual procedure – where you create the parts for the master key – “Initializing Service Instances using key part files”
  2. Auto-Init – where master key parts are auto-generated – “Initializing HPCS using Auto Init with Recovery Crypto Units”

After the Cloud Hyper Protect Crypto Service instance is initialized, navigate to the Overview tab of your Cloud Hyper Protect Crypto Service instance to make a note of the following:

  • YOUR-HPCS-INSTANCE-ID
  • YOUR-HPCS-EP11-ENDPOINT-URL
  • YOUR-HPCS-EP11-ENDPOINT-PORT

HPCS Overview Tab

2. Create the HSM access credentials

  1. Create the service IDs and API keys for the following users and make a note of the API keys:

    • SO user
    • Normal user
    • Anonymous user (for Slot 0)

    For more information on PKCS11 user types, check Setting up Cloud Hyper Protect Crypto Service PKCS#11 User Types

  2. Create the API key for access to Cloud Hyper Protect Crypto Service

     ibmcloud iam api-key-create apikeyhpcs -d "API key for Hyper Protect Crypto Services PKCS11"
    

3. Set up the Cloud Hyper Protect Crypto Service PKCS#11 client library

  1. Install the PKCS#11 client library from https://github.com/IBM-Cloud/hpcs-pkcs11/releases as shown below:

     mkdir -p /etc/ep11client
     mkdir -p ~/vault/lib
     mkdir -p ~/vault/conf
    
     cd ~/vault/lib
     wget -O pkcs11-grep11.so https://github.com/IBM-Cloud/hpcs-pkcs11/releases/download/v2.3.90/<latest-library>
     export PATH=$PATH:~/vault/lib
    
  2. Copy sample-grep11client.yaml to ~/vault/lib/grep11client.yaml and update the following entries:

    • YOUR-HPCS-INSTANCE-ID
    • YOUR-HPCS-EP11-ENDPOINT-URL
    • YOUR-HPCS-EP11-ENDPOINT-PORT
    • YOUR-HPCS-API-KEY

    If you want to change tokenspaceID in the file, use V4 UUID generator at https://www.uuidgenerator.net/version4

  3. Copy the grep11-configuration file to the server-config directory

     cp ~/vault/lib/grep11client.yaml /etc/ep11client/grep11client.yaml
    
  4. Install opensc and associate the Cloud Hyper Protect Crypto Service PKCS11 library with it:

     apt-get install opensc
     cd ~/vault/lib
     pkcs11-tool --module=./pkcs11-grep11.so -I
    

    Your response should look like this:

     Cryptoki version 2.40
     Manufacturer     IBM (v2.3.90)
     Library          GREP11 PKCS11 client (v2.3.90) (ver 0.1)
     Using slot 0 with a present token (0x0)
    

    Initialize the token with this command:

     pkcs11-tool --module=./pkcs11-grep11.so --init-token --label demo-hpcs-vault-key --so-pin=<SO Pin with permissions>
    

    Your response should look like this:

     Using slot 0 with a present token (0x0)
     Token successfully initialized
    

4. Set up Vault

  1. Install Enterprise Vault on your virtual server instance. Download and licensing options vary by platform. You can explore Enterprise Vault for pricing details or you can sign up for a free 30-day trial.

  2. Create the Vault configuration file server.hcl on ~/vault/conf/server.hcl

    • update
    • update
  3. Apply the license

    • Vault’s HSM auto-unseal and seal wrap features require a Vault Enterprise Plus license.
  4. Start Vault

    Run vault using the following commands below:

     vault server -config /home/ubuntu/vault/conf
    

    For production deployments, use systemd to launch the vault process. Refer to Systemd Service File for Vault to apply the Vault best practices in defining your systemd parameters.

  5. Initialize and unseal Vault

     vault operator init
     Recovery Key 1: x0vAjSXFWUvWZtpQoOjyw/pbfzGb3p9J6vgHKJ66WzL2
     Recovery Key 2: cfTyPk+9BbGmq/cjwMUcMATyCw3Jzk8vdg32DF/x2jzi
     Recovery Key 3: 4k9Ml4KExtxKS01/KBHYwNQLJFkr8ul47LwB4oSEo7VT
     ...
    
     Initial Root Token: s.1hda9JfGTeoBKsxfJuzfXIRC
    
     Success! Vault is initialized
    
     Recovery key initialized with 5 key shares and a key threshold of 3. Please
     securely distribute the key shares printed above.
    
     vault operator unseal
     Unseal Key (will be hidden):
     Key                      Value
     ---                      -----
     Recovery Seal Type       shamir
     Initialized              true
     Sealed                   false
    
  6. Restart and auto-unseal Vault

     vault status
     Key                      Value
     ---                      -----
     Recovery Seal Type       shamir
     Initialized              true
     Sealed                   false
    
  7. Cloud Hyper Protect Crypto Service clean-up (optional)

     ibmcloud login
     ibmcloud target -g Default
     export CLOUDTKEFILES=/Users/<user>/.bluemix/plugins/tke
    
     ibmcloud tke cryptounit-zeroize
     ibmcloud plugin uninstall tke
     ibmcloud resource service-instance-delete Hashi-HPCS-Demo-Seal
    

Summary

This tutorial has given you a starting point on how to integrate IBM Cloud Hyper Protect Crypto Service with HashiCorp Enterprise Vault’s auto-unseal and seal-wrap features. To learn more about building open-source vault for s390x, read the tutorial Build and configure HashiCorp Vault on IBM Cloud Hyper Protect Virtual Server.