Skip to content

Hyper Protect Virtual Servers (HPVS) Lab Process Overview

Prerequisites

See the Prerequisites page to complete the prerequisites for this lab. This includes creating accounts and credentials to access the Source Code Management (SCM) GitHub and the Docker Image Management (Docker Registry) Docker Hub for the lab.

The Big Picture

Here is a big picture of what is going on in the lab (i.e. lab architecture).

Secure Build Big Picture

Note

Student 1 and Student 2 in the illustration are 2 example students. In the actual lab, more students will be present.

The 5 different pieces of this puzzle:

  1. SETUP
  2. BUILD
  3. REGISTER
  4. DEPLOY
  5. ACCESS

(and how to CLEAN UP) are explained in more detail in their respective sections below.

SETUP

Configure your environment with the necessary credentials to connect to GitHub and Docker Hub respectively (see Configuring your Environment).

BUILD

Securely build a Docker Image for the Secure Electrum Bitcoin Wallet Application. (see Create your HPVS Secure Build Server and Securely Build your Application). This uses the Secure Build Process detailed below1:

Secure Build Overview

Securely Seeding Docker Content Trust

This Secure Build Process leverages a Hyper Protect Virtual Server, called the Secure Build Server, to establish trust and security in the Docker Content Trust process. This ensures images verified using the Notary service architecture were safely built and signed. This is done by generating the repository and root keys used to establish trust with the Notary Service inside of the Secure Build Server to guarantee that the initial keys used for a repository are trusted on first use (solving the TOFU problem).

However, those aren't the only keys used throughout the lab. The table below illustrates all of the different keys used throughout the secure build process, what they do, how they are created, and who is ultimately responsible for them.

List of the keys employed during the Secure Build Lab in order of creation. 2
Key Name Key Type Key Function Private Key Location How Created Owner
HPVS Registry CLI Encryption Key AES 256 bit key Encrypts the Docker token you provide as part of the hpvs registry add command in this section of the lab
Client Linux VM (i.e. Skytap for the lab)		 This symmetric key is hardcoded in the HPVS CLI binary file downloaded on the Skytap instance prior to the lab IBM HPVS Developers
GitHub SSH Key RSA 4096 bit key pair Provides SSH access to GitHub account to clone repositories via SSH
Client Linux VM (i.e. Skytap for the lab) as well as the secure build server		 In this section of the SETUP process ISV or application developer
Secure Build Server Client Certificate and Key RSA key pair securely communicate with the secure build server over the Secure Build REST API
Client Linux VM (i.e. Skytap for the lab)		 Generated in this section of the lab and the public key is passed to the server when creating the secure build server ISV or application developer or Cloud Admin
Repository Registration Signing Key RSA 4096 bit key pair (encrypted using GPG utility) (signatures use SHA256 hashing) The private key signs the repository definition file and the public key verifies this signature. Needed to create and update repositories defined on a Hyper Protect Virtual Servers appliance
Client Linux VM (i.e. Skytap for the lab)		 By the GnuPG utility using the gpg --generate-key command in this section of the lab ISV or application developer
Root Key ECDSA (NIST P-256 curve) 256 bit key pair (signatures use SHA256 hashing) Signs the root.json metadata file which specifies which keys are valid for image signing, snapshots, and timestamps for a given secure build server hpvs logo
Encrypted in Secure Build Server Quotagroup		 In response to the hpvs sb build command, Docker Content Trust CLI generates this key on the secure build server on first push to remote Docker repository in this section of lab ISV or application developer
Image Signing "Targets" Key ECDSA (NIST P-256 curve) 256 bit key pair (signatures use SHA256 hashing) Signs the targets.json metadata file which specifies the hashes of securely built Docker images hpvs logo
Encrypted in Secure Build Server Quotagroup		 In response to the hpvs sb build command, Docker Content Trust CLI generates this key on the secure build server on first push to a remote Docker repository in this section of lab ISV or application developer
Snapshot Key ECDSA (NIST P-256 curve) 256 bit key pair (signatures use SHA256 hashing) Signs the snapshot.json metadata file which specifies the filenames, sizes, and hashes of the targets.json and root.json metadata files to prevent mix and match attacks
Stored encrypted using Javascript Object Signing and Encryption in the image registry's signer database see Notary Service Architecture for more detail		 By the Notary server on the first push to a given Docker repository (triggered by hpvs sb build in this section of the lab.) Image registry administrator
Timestamp Key ECDSA (NIST P-256 curve) 256 bit key pair (signatures use SHA256 hashing) Frequently signs the timestamp.json metadata file which specifies the hash and size of the snapshot.json file at the current time to provide freshness guarantees without needing to re-download content on the client side
Stored encrypted using Javascript Object Signing and Encryption in the image registry's signer database see Notary Service Architecture for more detail		 Initially by the Notary server on the first push to a given Docker repository (triggered by hpvs sb build in this section of the lab.) This key has the shortest expiry time and is frequently rotated by the image registry's Notary server Image registry administrator
Manifest Signing Key RSA 2048 bit key pair (signatures use SHA256 hashing) The secure build server uses the private key to sign the manifest bundle which contains the source code used to build the docker image, any ssh keys (the public part) that could have access to the server (if enabled), and the logs and status of the secure build at the time of image signing. hpvs logo
Encrypted in Secure Build Server Quotagroup		 Created at the end of the secure build after each hpvs sb build in this section of the lab. The corresponding public key and the manifest itself are retrieved securely (using the Secure Build Server Client Certificate and Key) by the client VM to verify the build in this section of the lab ISV or application developer

REGISTER

Register your securely built Docker Image with your Secure Service Container to verify its validity3 (see the end of Securely Build your Application and the beginning of Deploy your Securely Built Application as a Hyper Protect Virtual Server). Image Registration Overview

DEPLOY

Deploy your Secure Bitcoin Wallet application (from the verified repository created in step 3) as a Hyper Protect Virtual Server within its own secure enclave4 (see Deploy your Securely Built Application as a Hyper Protect Virtual Server). Hyper Protect Virtual Servers Overview

ACCESS

Access your Secure Electrum Bitcoin Wallet Application application to use it with security built-in (see Welcome to the Secure Bitcoin Wallet on IBM LinuxONE).

CLEANUP

Clean up your environment for future users (see Clean up your environment).

  1. The Secure Build Experience graphic is adapted from charts provided by the Hyper Protect Virtual Servers On-Premises development team. ↩

  2. The above table explains all of the keys used for this lab, expounding on the more general table provided in the IBM Knowledge Center with specific details for the lab and omitting keys not used during the course of the lab. ↩

  3. The Image Registration Experience graphic is adapted from charts provided by the Hyper Protect Virtual Servers On-Premises development team. ↩

  4. The Hyper Protect Virtual Server Experience graphic is adapted from charts provided by the Hyper Protect Virtual Servers On-Premises development team. ↩

Last update: June 29, 2021
Created: June 20, 2020