Hyper Protect Virtual Servers Wildfire Workshop¶

Welcome to our Hyper Protect Virtual Servers workshop. IBM Hyper Protect Virtual Servers protect Linux® workloads on IBM Z® and LinuxONE throughout the application lifecycle – from build through to deploy and manage. Now you can be confident that applications and data are private and protected from a variety of internal and external threats. This workshop provides a primer on Hyper Protect Virtual Servers and practical use cases relevant to the enterprise. In addition, you will gain hands-on experience with IBM’s unique secure image build process to build a secure image and deploy it inside a FIPS 197-compliant protected memory enclave. Next, you will learn about Hyper Protect Virtual Servers' crypto service built on a FIPS 140-2 Level 4-compliant HSM. Lastly, you will gain hands-on experience exploiting the crypto service.

Agenda¶

Acknowledgements¶

Thanks to the following contributors: Jasmine Burgess

Workshop owners¶

Lab Assignments¶

You will need to enter the "Skytap Password" one time only (assuming you don't switch browsers or clear cache).

If your Ubuntu desktop asks for a login password for userid hyper-protect-lab, the password, for all teams, will be provided by an instructor in the WebEx meeting chat. Your desktop will lock and ask for this password if your session is idle for one hour.

Your two-digit team number will be used in the Secure Image Build lab in Step 1 here . You must use both digits, including the leading zero (for teams 01-09).

Name	Team Number	Skytap URL
TBD	01	http://ibm.biz/hpvsteam01
TBD	02	http://ibm.biz/hpvsteam02
TBD	03	http://ibm.biz/hpvsteam03
TBD	04	http://ibm.biz/hpvsteam04
TBD	05	http://ibm.biz/hpvsteam05
TBD	06	http://ibm.biz/hpvsteam06
TBD	07	http://ibm.biz/hpvsteam07
TBD	08	http://ibm.biz/hpvsteam08
TBD	09	http://ibm.biz/hpvsteam09
TBD	10	http://ibm.biz/hpvsteam10
TBD	11	http://ibm.biz/hpvsteam11
TBD	12	http://ibm.biz/hpvsteam12
TBD	13	http://ibm.biz/hpvsteam13
TBD	14	http://ibm.biz/hpvsteam14
TBD	15	http://ibm.biz/hpvsteam15
TBD	16	http://ibm.biz/hpvsteam16
TBD	17	http://ibm.biz/hpvsteam17
TBD	18	http://ibm.biz/hpvsteam18
TBD	19	http://ibm.biz/hpvsteam19
TBD	20	http://ibm.biz/hpvsteam20

GREP11 Lab ↵

GREP11 Lab Overview¶

GREP11 Overview¶

In this lab you will be working with the GREP11 feature of the Hyper Protect Virtual Servers on-premises offering.

GREP11 is a shorthand term for gRPC protocol-based Enterprise PKCS#11.

PKCS #11 refers to the Public Key Cryptography Standard #11 Cryptographic Token Interface, which is a standard for devices that hold cryptographic information and perform cryptographic functions.

gRPC stands for Google Remote Procedure Call, which is a protocol developed by Google, and contributed to open source. gRPC uses HTTP/2 for its transport protocol.

Enterprise PKCS#11, often referred to as EP11, refers to IBM's library, designed for enterprise usage, that is very similar to the PKCS #11 standard.

The PKCS #11 standard covers the following cryptographic categories, and the GREP11 library provides functions in each of these categories:

Encryption
Decryption
Message digests (also known as hashes)
Signing and MACing (Message Authentication Codes)
Verifying signatures and MACs
Key Management- creating symmetric keys, creating asymmetric keys, wrapping and unwrapping keys, and deriving keys from other keys
Random number generation - strictly speaking not a cryptographic operation unto itself, but random numbers are often used in cryptographic operations

Lab Environment¶

You will be working with the Hyper Protect Virtual Servers command line interface (CLI) running on an x86_64 virtual machine running the Ubuntu 18.04.5 Linux distribution. You will also be using this virtual machine to run programs, written in the Go programming language, that will communicate with the GREP11 server. This virtual machine is provisioned on SkyTap in the IBM Cloud, and you will access it through your web browser. Your instructor will provide you the information needed to access your virtual machine under separate cover.

The GREP11 server runs as a Docker container running in Hyper Protect Virtual Servers. Hyper Protect Virtual Servers runs in a Secure Service Container (SSC) LPAR on an IBM z15 server located in Herndon, Virginia, USA, and managed by the Advanced Technology Group - IBM Z team.

The Hyper Protect Virtual Servers LPAR is in an Advanced Technology Group private network and your Ubuntu virtual machine communicates with it through a VPN connection. Your instructor will provide you the information needed to establish a VPN connection under separate cover.

Note

The client program code used in this lab could also be run on the s390x architecture. IBM provides sample client code, which connects to a GREP11 Server, in two programming lanugages - Go and JavaScript, both of which are supported on s390x. This lab will utilize client code written in Go.

The following diagram summarizes the data flow from the client application you will be running in this lab, to the GREP11 server which runs in the Hyper Protect Virtual Servers LPAR on an IBM Z or LinuxONE server, through kernel calls that call the cryptographic device driver (represented by /dev/ap in the drawing) which then accesses the Crypto Express 7S card through the PCIe bus.

GREP11 flow

There is no inherent significance to the highlighted boxes in the drawing. We highlighted the client application box to point out that the client application does not have to reside on the same host as the GREP11 server. We highlighted the Go box since we will be working with the Go language GREP11 client in this lab and not the JavaScript GREP11 client. We highlighted GRPC just because, well, the G in GREP11 stands for gRPC.

What has been done for you already¶

Our starting point for the lab is having the GREP11 servers running on our Hyper Protect Virtual Servers LPAR. Each GREP11 server is connected to a single domain on an IBM Crypto Express 7S card that is configured to our LPAR. Our Hyper Protect Virtual Servers LPAR has two Crypto Expess 7S cards configured to it, with one domain on each card dedicated to our LPAR. So, with only two domains and many students, we had to provision the GREP11 servers ahead of time.

We will describe the process of setting this up so that you will have a reference.

Detailed Lab Process¶

Read about how we configured the GREP11 servers
Issue relevant Hyper Protect Virtual Servers CLI commands
Clone the GitHub repository which the lab uses
Run Hyper Protect Virtual Servers commands to inspect the GREP11 setup
Run the GREP11 samples that IBM documentation points to
Run custom lab exercises that go into greater depth

How to set up a GREP11 server¶

Hyper Protect Virtual Servers LPAR setup¶

NOTE: All commands on this page are for reference only and not to be entered by you in the lab¶

Hyper Protect Virtual Servers runs in an LPAR that is defined in Secure Service Container (SSC) mode. Defining an LPAR is a normal task for an IBM Z or LinuxONE systems administrator, typically performed from the Hardware Management Console (HMC).

The systems administrator must¹ dedicate one or more domains of one or more Crypto Express cards to the Hyper Protect Virtual Servers LPAR in order to use the GREP11 server. These Crypto Express cards must be defined in EP11 mode to your IBM Z or LinuxONE server in order to be used by a GREP11 server. These tasks are documented in the Hyper Protect Virtual Servers documentation, or in IBM publications referenced in the Hyper Protect Virtual Servers documentation.

The version of Hyper Protect Virtual Servers that we will be using in this lab is version 1.2.2.1, which was released on November 6, 2020.

A GREP11 server communicates with one and only one Crypto Express domain, and vice versa. You can run multiple GREP11 servers if you have multiple domains configured to your Hyper Protect Virtual Servers LPAR.

The GREP11 server is stateless, so desired levels of throughput and resilience can be achieved by loading the same master key in one or more domains of one or more Crypto Express 7S cards across one or more CECs across one or more geographies.

Overview of GREP11 server setup¶

This section provides an overview of what the remaining sections of this page will discuss in detail.

The following steps are required:

Create a Certification Authority (CA) certificate and key
Create a GREP11 server X.509 certificate for Transport Layer Security (TLS) authentication
Create an X.509 certificate for your client application for TLS authentication
List Crypto Domains on your Hyper Protect Virtual Servers LPAR
Create YAML and/or JSON configuration files for GREP11 server initialization
Start the GREP11 server

Important

The commands shown on this page are for reference only- they have already been performed by the lab instructors in order to set up the lab environment for you.

Create a Certification Authority (CA) certificate and key¶

The openssl utility is used to generate a private key and a certificate that will act as a certification authority (CA). This will be used in later steps to issue certificates for the GREP11 server and for the client application which will connect to the GREP11 server.

Whenever you browse the web to a site with https, the server presents its certificate to your browser. This is known as server-side or one-way TLS authentication. Most websites do not ask you to present a certificate. The website makes itself available to anybody who browses to it.

With mutual TLS authentication, the client does need to present a certificate. The server will only establish a session with a client who presents a certificate that is trusted by the server. This prevents our GREP11 server from being used by unauthorized clients.

The following command was used to create the RSA private key which will be used by our soon to be created CA

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl genrsa -out atgz-hpvs-ca.key 2048

This created a file named atgz-hpvs-ca.key which is an RSA private key.

In most cases (and mandatory from PKCS #11 version 2.4 onwards) the RSA private key contains enough information to reconstitute the public key. It is for this reason that the private key is used as input to the following command, which will create a Certification Authority X.509 certificate. X.509 certificates contain information identifying the certificate holder, the attributes of the certificate, including what the certificate can be used for, and, importantly, the public key.

We used this command to create this certificate.

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl req -new -x509 -key atgz-hpvs-ca.key -out atgz-hpvs-ca.pem

The atgz-hpvs-ca.key file was input to this command, and the atgz-hpvs-ca.pem file is the output of this command. This atgz-hpvs-ca.pem file is our "homegrown" certification authority root certificate.

I will use the Linux cat command to get a raw listing of the root certificate we just created:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

cat atgz-hpvs-ca.pem

Example output

The first and last lines are meant to assure you that this is a certificate, but the lines in between are less insightful, as it is base64-encoded binary data. Fortunately the openssl utility comes to our rescue and allows us to print the certificate in a form that a human can hope to understand:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl x509 -in atgz-hpvs-ca.pem -text

Example output

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            6a:59:55:83:a1:ab:58:f7:e8:8b:0c:14:70:20:5d:07:e7:fb:90:f4
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = US, ST = Virginia, L = Herndon, O = IBM, OU = Advanced Technology Group - IBM Z, CN = ATG-Z HPVS CA, emailAddress = silliman@us.ibm.com
        Validity
            Not Before: Dec 10 19:28:28 2020 GMT
            Not After : Jan  9 19:28:28 2022 GMT
        Subject: C = US, ST = Virginia, L = Herndon, O = IBM, OU = Advanced Technology Group - IBM Z, CN = ATG-Z HPVS CA, emailAddress = silliman@us.ibm.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus:
                    00:c0:14:7c:90:0a:05:d6:db:08:c9:f4:37:d0:c7:
                    bc:0e:02:87:3f:e2:84:10:54:c6:c0:9a:4c:05:26:
                    26:95:73:0e:3b:f8:f6:b6:13:5d:8f:58:73:14:29:
                    35:82:b2:7b:1b:0a:8c:39:42:7e:bf:bd:80:d9:6e:
                    b3:5b:4a:53:40:ab:64:3e:b7:64:b8:80:24:26:59:
                    a2:89:88:64:ea:19:40:da:ae:86:3e:5f:e3:af:fd:
                    c7:67:76:f7:d1:47:c4:a6:39:cf:bd:bd:85:b1:e1:
                    1d:b8:c3:f9:49:06:eb:48:a7:cb:14:ba:42:6e:36:
                    39:a2:0b:c7:c6:e3:ae:b7:07:c8:ec:e1:c0:a9:f8:
                    ce:6d:d1:b1:a1:0e:59:c8:2a:24:ff:32:42:f1:fc:
                    06:6e:d4:12:59:8a:2c:00:c8:e4:d8:29:ff:e5:96:
                    bc:d1:44:f9:07:97:7d:89:8a:51:2a:4b:68:9d:3f:
                    e0:10:f9:e0:16:e4:ef:cd:11:4b:23:a8:86:f8:ef:
                    d4:ef:c9:68:b7:47:45:7a:c9:51:83:12:34:d6:10:
                    de:82:bf:ee:a4:4c:0a:33:81:9e:e6:85:63:d1:52:
                    75:a1:8d:bd:8d:af:4b:9b:cc:e3:84:da:0b:2e:43:
                    c8:c6:75:18:b0:ab:09:bf:72:d7:74:ef:11:50:3d:
                    8c:53
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
                DE:C1:82:99:1F:AA:20:93:28:8A:7F:F4:98:25:C0:20:C3:80:62:79
            X509v3 Authority Key Identifier: 
                keyid:DE:C1:82:99:1F:AA:20:93:28:8A:7F:F4:98:25:C0:20:C3:80:62:79

            X509v3 Basic Constraints: critical
                CA:TRUE
    Signature Algorithm: sha256WithRSAEncryption
        b1:40:33:cf:cb:43:d9:64:04:08:a1:ec:ce:87:ac:a4:77:79:
        f2:a1:fc:08:f4:52:04:4f:ea:26:29:a6:ba:56:d8:7f:3c:3a:
        cc:34:94:49:c3:65:9d:82:4c:a7:9a:1c:c0:c5:1c:15:07:6a:
        9a:6b:2c:cd:c1:d1:49:c4:fe:17:21:33:16:f8:c5:02:a2:86:
        5b:3a:31:19:3d:c3:76:65:65:d5:2c:79:2b:4b:61:b4:b9:2c:
        79:19:5a:bd:95:9d:38:cc:83:99:fa:41:16:95:11:b2:7f:04:
        4f:fa:e6:ec:d7:00:9f:b7:4e:e9:12:46:37:aa:9c:95:10:96:
        63:b2:fa:3d:ed:eb:f8:67:b9:58:5d:e6:df:45:23:76:db:17:
        94:22:e1:9a:70:a4:19:da:00:7e:f8:30:cb:bf:7e:f8:7b:31:
        78:d4:73:0c:60:1c:e2:2f:9d:8d:b4:e0:5a:0d:07:99:28:19:
        ce:12:d0:e2:be:b0:9f:9d:9c:bf:0b:ec:9f:0b:ab:d9:af:8b:
        6f:92:9a:95:3a:96:65:9f:01:6d:3d:47:95:ac:3e:89:98:21:
        62:b2:4d:3a:65:a6:df:b8:a8:96:a1:f3:b0:38:39:2c:89:9a:
        0b:d6:35:c0:f8:22:b9:7e:c1:3b:52:d0:58:b1:31:d8:8b:03:
        96:76:fa:7d
-----BEGIN CERTIFICATE-----
MIIEMzCCAxugAwIBAgIUallVg6GrWPfoiwwUcCBdB+f7kPQwDQYJKoZIhvcNAQEL
BQAwgagxCzAJBgNVBAYTAlVTMREwDwYDVQQIDAhWaXJnaW5pYTEQMA4GA1UEBwwH
SGVybmRvbjEMMAoGA1UECgwDSUJNMSowKAYDVQQLDCFBZHZhbmNlZCBUZWNobm9s
b2d5IEdyb3VwIC0gSUJNIFoxFjAUBgNVBAMMDUFURy1aIEhQVlMgQ0ExIjAgBgkq
hkiG9w0BCQEWE3NpbGxpbWFuQHVzLmlibS5jb20wHhcNMjAxMjEwMTkyODI4WhcN
MjIwMTA5MTkyODI4WjCBqDELMAkGA1UEBhMCVVMxETAPBgNVBAgMCFZpcmdpbmlh
MRAwDgYDVQQHDAdIZXJuZG9uMQwwCgYDVQQKDANJQk0xKjAoBgNVBAsMIUFkdmFu
Y2VkIFRlY2hub2xvZ3kgR3JvdXAgLSBJQk0gWjEWMBQGA1UEAwwNQVRHLVogSFBW
UyBDQTEiMCAGCSqGSIb3DQEJARYTc2lsbGltYW5AdXMuaWJtLmNvbTCCASIwDQYJ
KoZIhvcNAQEBBQADggEPADCCAQoCggEBAMAUfJAKBdbbCMn0N9DHvA4Chz/ihBBU
xsCaTAUmJpVzDjv49rYTXY9YcxQpNYKyexsKjDlCfr+9gNlus1tKU0CrZD63ZLiA
JCZZoomIZOoZQNquhj5f46/9x2d299FHxKY5z729hbHhHbjD+UkG60inyxS6Qm42
OaILx8bjrrcHyOzhwKn4zm3RsaEOWcgqJP8yQvH8Bm7UElmKLADI5Ngp/+WWvNFE
+QeXfYmKUSpLaJ0/4BD54Bbk780RSyOohvjv1O/JaLdHRXrJUYMSNNYQ3oK/7qRM
CjOBnuaFY9FSdaGNvY2vS5vM44TaCy5DyMZ1GLCrCb9y13TvEVA9jFMCAwEAAaNT
MFEwHQYDVR0OBBYEFN7BgpkfqiCTKIp/9JglwCDDgGJ5MB8GA1UdIwQYMBaAFN7B
gpkfqiCTKIp/9JglwCDDgGJ5MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL
BQADggEBALFAM8/LQ9lkBAih7M6HrKR3efKh/Aj0UgRP6iYpprpW2H88Osw0lEnD
ZZ2CTKeaHMDFHBUHapprLM3B0UnE/hchMxb4xQKihls6MRk9w3ZlZdUseStLYbS5
LHkZWr2VnTjMg5n6QRaVEbJ/BE/65uzXAJ+3TukSRjeqnJUQlmOy+j3t6/hnuVhd
5t9FI3bbF5Qi4ZpwpBnaAH74MMu/fvh7MXjUcwxgHOIvnY204FoNB5koGc4S0OK+
sJ+dnL8L7J8Lq9mvi2+SmpU6lmWfAW09R5WsPomYIWKyTTplpt+4qJah87A4OSyJ
mgvWNcD4Irl+wTtS0FixMdiLA5Z2+n0=
-----END CERTIFICATE-----

A few lines of the output above have been highlighted. Notice the highlighted line that says CA: TRUE. This attribute indicates that this certificate is acting as a certification authority and can issue other certificates. Notice the lines above it which have values for Subject Key Identifier and Authority Key Identifier. Subject Key Identifier is the identity of the holder of the certificate. Authority Key Identifier is the identity of the issuer of the certificate. You can see that the values for these are the same. This is known as a self-signed certificate. Certification authorities (CA) exist in a hierarchy- one CA can issue a certificate to another CA with the CA: TRUE attribute, and so forth. In our lab we have this single, homegrown certification authority that we created, with its self-signed certificate that we created per the instructions in the Hyper Protect Virtual Servers documentation.

Create a GREP11 server X.509 certificate for TLS authentication¶

Once we created a "homegrown" certification authority, we next created an X.509 certificate for our GREP11 server. This certificate was issued by our certification authority.

The first step was to create another RSA private key that our GREP11 server will use:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl genrsa -out grep11-server79-9876-key.pem 2048

Note

The value of the -out argument, grep11-server79-9876-key.pem can be whatever you want it to be. I named it what I did for a reason. The 79 in server79 is for the last octet of my Hyper Protect Virtual Servers LPAR's IP adresss, 192.168.22.79, and I intend to use this certificate for a GREP11 server listening on port 9876 on one of the LPAR's Crypto Express 7S domains.

Then, this private key was used as input to openssl in order to create a certificate signing request:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl req -new -key grep11-server79-9876-key.pem -out grep11-server79-9876.csr

The certificate signing request will be passed to our certification authority which will use the information to create an X.509 certificate. We used openssl for this, too:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl x509 -sha256 -req -in grep11-server79-9876.csr -CA atgz-hpvs-ca.pem -CAkey atgz-hpvs-ca.key -set_serial 8086 -extfile openssl.cnf -extensions server -days 365 -outform PEM -out grep11-server79-9876.pem

The file name of the certificate that was created by the preceding command is the value of the -out argument, grep11-server79-9876.pem. openssl allows us to list this certificate in human-friendly form:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl x509 -in grep11-server79-9876.pem -noout -text

Example output

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 8086 (0x1f96)
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = US, ST = Virginia, L = Herndon, O = IBM, OU = Advanced Technology Group - IBM Z, CN = ATG-Z HPVS CA, emailAddress = silliman@us.ibm.com
        Validity
            Not Before: Dec 10 19:28:28 2020 GMT
            Not After : Jan  4 19:28:28 2022 GMT
        Subject: C = US, ST = Virginia, L = Herndon, O = IBM, OU = Advanced Technology Group - IBM Z, CN = 192.168.22.79
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus:
                    00:d9:c4:97:86:cc:d9:a8:d7:0e:e4:d5:7e:6a:97:
                    e6:03:f4:85:4c:4d:2f:c5:bc:1e:88:da:ab:31:68:
                    3b:1b:b7:eb:ae:81:a6:0f:34:1f:b0:90:bb:a7:1a:
                    7a:2c:c1:6b:be:b6:8b:9d:b4:b8:71:78:ff:fb:84:
                    61:c4:22:4e:8f:42:52:90:15:de:58:c8:1f:3d:5d:
                    3c:15:c7:9f:9d:bb:13:c4:0c:d8:a1:53:83:56:18:
                    ec:75:fd:69:5a:f4:ed:6e:61:5e:f0:1b:57:58:7c:
                    89:28:5b:b7:81:c9:6d:4e:fa:63:33:a1:98:ee:7a:
                    18:5b:ad:c5:53:8a:fe:3e:c7:99:07:7f:45:e2:15:
                    fa:2a:bc:e2:eb:2a:dc:7e:38:7a:8c:ec:1f:89:b1:
                    e3:91:6f:1a:36:d3:17:03:54:c3:56:57:65:7f:d4:
                    6b:56:dc:94:21:d9:5d:43:06:26:a6:fa:48:06:85:
                    95:e9:f3:10:b3:26:cb:69:c3:67:28:d3:ef:74:40:
                    50:7b:2a:f9:56:20:79:e4:92:64:2d:ea:6b:bc:07:
                    2a:95:3e:d2:80:5e:c5:61:b7:84:ca:63:83:e0:0a:
                    67:fe:e3:9c:af:12:54:f0:22:82:b3:84:30:87:08:
                    b5:8c:bf:05:af:dd:80:94:a3:0f:39:d4:d7:2e:d5:
                    d3:e7
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Basic Constraints: 
                CA:FALSE
            X509v3 Key Usage: 
                Digital Signature, Key Encipherment, Data Encipherment
            X509v3 Extended Key Usage: 
                TLS Web Server Authentication
            Netscape Cert Type: 
                SSL Server
            X509v3 CRL Distribution Points: 

                Full Name:
                URI:http://localhost/ca.crl

            X509v3 Subject Alternative Name: 
                DNS:192.168.22.79:9876, IP Address:192.168.22.79
    Signature Algorithm: sha256WithRSAEncryption
        1f:bb:b0:26:34:62:82:62:ca:7f:1c:a6:ef:54:15:d9:44:88:
        e4:97:19:5b:2c:fc:dd:1c:01:70:ee:27:1c:ec:49:58:25:a5:
        dc:9e:9a:55:71:9b:05:bb:c1:1b:6e:85:a3:ab:9c:ce:05:bf:
        29:3b:cb:ed:98:f5:01:e8:cb:e2:e6:14:c1:74:0d:96:38:14:
        58:ca:84:ad:af:35:fd:12:50:16:10:f3:6d:c1:fe:ba:04:12:
        ea:19:17:dd:95:a8:8b:65:83:da:bc:ef:6e:23:00:2c:52:6e:
        80:af:a9:93:7a:5f:40:8d:e7:55:ea:1d:90:d8:8c:04:59:91:
        91:b4:22:19:9f:9a:b6:20:ee:36:4d:c1:75:29:54:e1:a0:47:
        cd:82:14:86:75:37:60:4e:1a:54:f5:81:ec:5a:3a:de:64:93:
        51:fb:c6:44:b1:66:d7:41:59:b6:95:27:c9:81:fc:d9:76:a5:
        f2:16:74:47:8c:c8:a3:b1:1d:f3:98:34:b1:fa:52:d9:3e:d1:
        63:8b:70:d3:a3:aa:ac:47:1c:90:13:76:df:98:47:ae:19:e2:
        c4:d5:81:eb:44:66:45:09:6a:75:c6:5f:0c:aa:e0:44:52:16:
        35:be:49:f0:10:65:3f:df:a3:50:0d:3b:ae:94:59:9c:28:a5:
        41:24:a5:45

Create an X.509 certificate for your client application for TLS authentication¶

The client applications need a certificate that is issued by the same certification authority that the GREP11 server uses. The process is similar- create a private key, pass that as input for the creation of a certificte signing request, and then pass that to the certification authority in order to receive a certificate. We used these commands:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl genrsa -out client-key.pem 2048

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl req -new -key client-key.pem -out client.csr

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl x509 -req -days 1000 -in client.csr -CA ca.pem -CAcreateserial -CAkey ca.key -out client.pem

Here is a listing of the client certificate that you will be using in the lab. It will be configured properly for you so that your client program can present it to the GREP11 server:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

openssl x509 -in client.pem -noout -text

Example Output

Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number:
            7a:dc:83:ab:72:46:2f:30:b9:d2:71:b4:9b:00:43:4f:53:63:a7:ce
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = US, ST = Virginia, L = Herndon, O = IBM, OU = Advanced Technology Group - IBM Z, CN = ATG-Z HPVS CA, emailAddress = silliman@us.ibm.com
        Validity
            Not Before: Dec 10 19:28:28 2020 GMT
            Not After : Mar 20 19:28:28 2021 GMT
        Subject: C = US, ST = Virginia, L = Herndon, O = IBM, OU = Advanced Technology Group - IBM Z, CN = GREP11 Lab Student, emailAddress = silliman@us.ibm.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                RSA Public-Key: (2048 bit)
                Modulus:
                    00:d2:4f:86:c1:d6:9a:6b:f4:2c:7d:6f:91:59:b9:
                    98:12:6e:d1:5f:ea:ca:90:b4:74:0e:dd:99:ce:20:
                    ca:f6:75:df:fe:54:76:ef:fd:3a:a2:f9:cf:15:0d:
                    1e:19:5c:e5:0f:55:50:ff:64:7f:2b:a6:1f:35:8b:
                    38:f8:f4:2a:a6:c7:66:0c:ef:17:d9:40:46:fb:d1:
                    ca:28:dd:a0:6b:08:28:b9:55:95:9d:cc:67:9b:f4:
                    26:da:04:76:fb:d3:02:e3:8e:af:f7:c3:4c:01:30:
                    04:47:e3:e3:0a:58:33:47:8e:11:50:1d:1a:ca:30:
                    a8:09:76:fc:b9:a7:86:05:2b:46:44:f6:dd:48:e2:
                    5e:64:78:8b:06:42:32:5f:cf:7d:e6:80:e1:32:94:
                    6f:fe:8a:b9:f5:a1:3a:c0:d5:3a:c7:5f:4e:e3:7b:
                    2e:0f:58:a2:35:26:57:0c:0d:c7:7f:2d:8f:8c:09:
                    84:ee:eb:d4:0e:da:5a:3a:e3:09:2f:f2:be:b9:b0:
                    48:cd:c7:d0:4c:03:d6:25:68:5d:5f:7e:3a:b1:9b:
                    4b:a4:09:b3:40:30:be:6d:be:9c:de:77:e7:18:4c:
                    ff:6d:cf:70:9c:37:bd:8e:5b:6d:75:1f:a5:c2:55:
                    ec:38:25:c9:cd:38:4b:8e:63:47:63:4e:e7:90:21:
                    6b:a1
                Exponent: 65537 (0x10001)
    Signature Algorithm: sha256WithRSAEncryption
        ac:89:54:fc:40:06:1f:84:99:08:f8:70:ab:b0:24:1d:b3:6c:
        a2:86:bd:b8:82:e3:6d:aa:c1:c7:7a:b8:3c:1d:59:80:89:92:
        57:07:ca:28:cd:80:de:11:e7:ed:d9:40:29:0b:90:1a:b7:9b:
        ed:b5:15:6a:6c:1c:31:3f:82:0f:01:1f:64:05:bb:12:16:67:
        d2:b2:3d:84:ef:74:34:56:80:11:69:ab:85:5b:43:ac:ba:13:
        e2:ca:b3:12:4a:39:ff:f1:4f:47:60:e9:16:49:75:34:95:1d:
        e0:51:c4:05:96:5e:1b:50:31:cf:ba:1a:a5:e1:1f:ed:8b:62:
        84:6d:a4:f3:6c:d4:20:d1:f1:b1:6e:79:de:57:c9:93:f7:12:
        68:86:45:dd:f4:2d:a9:c9:41:b4:6c:5e:79:01:5a:91:64:a1:
        01:14:c5:81:04:fb:64:7e:d1:42:ef:2c:e8:9f:6c:ba:b9:01:
        53:4b:32:30:0f:2a:30:4d:84:d1:11:a6:b6:cc:56:58:b0:1c:
        4f:ea:dc:3e:6e:4f:60:5b:ed:a1:0d:c8:f1:6b:dc:1a:05:00:
        ad:a9:72:ce:ff:d1:d6:ae:0a:a9:56:36:5a:ab:d0:33:41:59:
        80:8f:17:90:8a:71:f6:df:bd:6c:8e:4b:10:5d:5b:8f:94:9a:
        2d:03:85:0b

Note

For the lab, each student will use a copy of the same client certificate. In most production use cases each client would use their own certificate which uniquely identifies them.

List Crypto Domains on your Hyper Protect Virtual Servers LPAR¶

You can list your available domains with the Hyper Protect Virtual Server CLI:

Reminder

The command shown below is for reference only- it has already been performed by the lab instructors in order to set up the lab environment for you.

hpvs crypto list

Example output

 hpvs crypto list
+---------------+--------+
| CRYPTO.DOMAIN | STATUS |
+---------------+--------+
| 08.0014       | online |
| 0a.0014       | online |
+---------------+--------+

The values shown in the CRYPTO.DOMAIN column are in hexadecimal. So, translating to decimal, our LPAR is using Crypto Express 7S cards 8 and 10, with domain 20 in both cards assigned to our LPAR. (A Crypto Express 7S card can have up to 85 domains- think of each domain as a "virtual" Crypto Express 7S card).

Create YAML or JSON configuration files for GREP11 server¶

There are two alternative ways to start your GREP11 server:

Using hpvs deploy with a YAML file as input
Using hpvs vs create with a JSON file as input

I will show both the YAML and JSON files first, then I will show both methods of starting the GREP11 server.

YAML file for GREP11 server configuration¶

This is the YAML file for a GREP11 server that will listen for client connections on port 9876, and will use domain 20 (hex 14) of Crypto Express 7S card 08:

GREP11 server YAML configuration file

version: v1 
#
# use this file with the 'hpvs deploy' command, e.g.,
#
#  hpvs deploy --config $HOME/hpvs/config/grep11/vs_grep11_79-9876.yml 
#
type: virtualserver
virtualservers:
- name: grep11-08-0014-9876
host: atgzlpar79
repoid: hpcsKpGrep11_runq
imagetag: 1.2.7.5
imagefile: hpcsKpGrep11_runq.tar.gz
crypto:
    crypto_matrix:
    - 08.0014
environment:
- key: EP11SERVER_EP11CRYPTO_DOMAIN
    value: "08.0014"
#
- key: EP11SERVER_EP11CRYPTO_CONNECTION_TLS_CERTFILEBYTES
    value: "@/home/hyper-protect-lab/hpvs/config/grep11/keys/grep11-server79-9876.pem"
- key: EP11SERVER_EP11CRYPTO_CONNECTION_TLS_KEYFILEBYTES
    value: "@/home/hyper-protect-lab/hpvs/config/grep11/keys/grep11-server79-9876-key.pem"
- key: EP11SERVER_EP11CRYPTO_CONNECTION_TLS_CACERTBYTES
    value: "@/home/hyper-protect-lab/hpvs/config/grep11/keys/atgz-hpvs-ca.pem"
- key: EP11SERVER_EP11CRYPTO_CONNECTION_TLS_ENABLED
    value: "true"
- key: EP11SERVER_EP11CRYPTO_CONNECTION_TLS_MUTUAL
    value: "true"
- key: EP11SERVER_EP11CRYPTO_ENABLED
    value: "true"
- key: TLS_GRPC_CERTS_DOMAIN_CRT
    value: "\\n"
- key: TLS_GRPC_CERTS_DOMAIN_KEY
    value: "\\n"
- key: TLS_GRPC_CERTS_ROOTCA_CRT
    value: "\\n"
ports:
- hostport: 9876
    protocol: tcp
    containerport: 9876

JSON file for GREP11 server configuration¶

This is a JSON file for a GREP11 server that will listen for client connections on port 9876, and will use domain 20 (hex 14) of Crypto Express 7S card 08:

GREP11 server JSON configuration file

{
"EP11SERVER_EP11CRYPTO_DOMAIN":"08.0014",
"EP11SERVER_EP11CRYPTO_CONNECTION_TLS_CERTFILEBYTES":"@/home/hyper-protect-lab/hpvs/config/grep11/keys/grep11-server79-9876.pem",
"EP11SERVER_EP11CRYPTO_CONNECTION_TLS_KEYFILEBYTES":"@/home/hyper-protect-lab/hpvs/config/grep11/keys/grep11-server79-9876-key.pem",
"EP11SERVER_EP11CRYPTO_CONNECTION_TLS_CACERTBYTES":"@/home/hyper-protect-lab/hpvs/config/grep11/keys/atgz-hpvs-ca.pem",
"EP11SERVER_EP11CRYPTO_CONNECTION_TLS_ENABLED":true,
"EP11SERVER_EP11CRYPTO_CONNECTION_TLS_MUTUAL":true,
"EP11SERVER_EP11CRYPTO_ENABLED":true,
"TLS_GRPC_CERTS_DOMAIN_CRT":"\\n",
"TLS_GRPC_CERTS_DOMAIN_KEY":"\\n",
"TLS_GRPC_CERTS_ROOTCA_CRT":"\\n"
}

Start the GREP11 server¶

If you looked carefully at the JSON file and the YAML file in the previous section, you may have noticed that the YAML file contains more information than the JSON file contains. As a result, the syntax is simpler for the command that uses the YAML file. The command that uses the JSON file uses command line arguments to provide some of the information that the YAML file contained. Compare the two methods:

Reminder

The commands shown below are for reference only- they have already been performed by the lab instructors in order to set up the lab environment for you.

Command to start the GREP11 server with the YAML file

hpvs deploy --config $HOME/hpvs/config/grep11/vs_grep11_79-9876.yml

Command to start the GREP11 server with the JSON file

hpvs vs create --name grep11-08-0014-9876 --repo hpcsKpGrep11_runq --tag 1.2.7.5 --crypto_matrix=08.0014 --cpu 2 --ram 2048 --envjsonpath ${HOME}/hpvs/config/grep11/grep11_env_08.0014.json --ports "{containerport = 9876, protocol = tcp, hostport = 9876}"

Important

Starting now, as you navigate to the next section of the lab, you should enter all the commands shown in the lab. Only the commands in this section were for reference.

The GREP11 server is a feature provided by Hyper Protect Virtual Servers. You are not required to use it. If you do not use this feature, you do not have to define Crypto Express domains to the LPAR. You may wish to for other purposes, and you can use the other modes offered by Crypto Express cards for those purposes, but you must use EP11 mode for usage by the GREP11 server. ↩

Displaying your GREP11 environment¶

List Crypto Domains on your Hyper Protect Virtual Servers LPAR¶

List your available domains with the Hyper Protect Virtual Server CLI:

hpvs crypto list

Example output

hpvs crypto list
+---------------+--------+
| CRYPTO.DOMAIN | STATUS |
+---------------+--------+
| 08.0014       | in use |
| 0a.0014       | in use |
+---------------+--------+

A value of in use in the STATUS column indicates that each crypto domain has a GREP11 server connected to it.

Display the GREP11 servers¶

Display the virtual servers running on the Hyper Protect Virtual Servers LPAR:

hpvs vs list

Example output

+----------------------+---------+-------------+----------------------------------------------------------------------------------------------------------------+
| NAMES                | STATE   | STATUS      | IMAGE                                                                                                          |
+----------------------+---------+-------------+----------------------------------------------------------------------------------------------------------------+
| grep11-08-0014-9876  | running | Up 19 hours | docker-eu-public.artifactory.swg-devops.com/sys-zaas-team-hpcs-dev-docker-local/hpcs/grep11-ep11server:1.2.7.5 |
| grep11-0a-0014-19876 | running | Up 19 hours | docker-eu-public.artifactory.swg-devops.com/sys-zaas-team-hpcs-dev-docker-local/hpcs/grep11-ep11server:1.2.7.5 |
+----------------------+---------+-------------+----------------------------------------------------------------------------------------------------------------+

Observe that there are two servers listed whose name starts with grep11. These are the two GREP11 servers that we have provided. One accessible from host port 9876 and one from host port 19876.

Note

The list you see may differ from what is shown in our example, but you should see the two GREP11 servers whose names are highlighted in our example.

Display details about one of the GREP11 servers with this command:

hpvs vs show --name grep11-08-0014-9876

Example output

+-------------+------------------------------+
| PROPERTIES  | VALUES                       |
+-------------+------------------------------+
| Name        | grep11-08-0014-9876          |
| CPU         | 2                            |
| Memory      | 2048                         |
| State       | running                      |
| Status      | Up 19 hours                  |
| Networks    | Gateway:172.31.0.1           |
|             | IPAddress:172.31.0.2         |
|             | MacAddress:02:42:ac:1f:00:02 |
|             | Network:bridge               |
|             | Subnet:16                    |
| Ports       | LocalPort:9876/tcp           |
|             | GuestPort:9876               |
| Quotagroups | []                           |
+-------------+------------------------------+

(Optional) Feel free to run the hpvs vs show command against the other GREP11 server.

Please proceed to the next section of the lab.

Run the GREP11 Sample code¶

Clone the GitHub repository which has the source code¶

Change to the /home/hyper-protect-lab/go/src/github.com/ibm-developer directory
```
cd ${HOME}/go/src/github.com/ibm-developer
```
Ensure you are in the directory mentioned in the prior step¹. You may be able to tell from the command prompt. You can also enter the pwd ("print working directory") to be sure, e.g.,:
```
pwd
```
Example Output
```
/home/hyper-protect-lab/go/src/github.com/ibm-developer
```

Clone the GitHub repository used in this lab:

git clone https://github.com/silliman/ibm-cloud-hyperprotectcrypto.git

Example Output

Cloning into 'ibm-cloud-hyperprotectcrypto'...
remote: Enumerating objects: 821, done.
remote: Counting objects: 100% (821/821), done.
remote: Compressing objects: 100% (551/551), done.
remote: Total 821 (delta 227), reused 821 (delta 227), pack-reused 0
Receiving objects: 100% (821/821), 9.30 MiB | 8.42 MiB/s, done.
Resolving deltas: 100% (227/227), done.

Change to the ibm-cloud-hyperprotectcrypto directory which the prior git clone command created:
```
cd ibm-cloud-hyperprotectcrypto
```
Tip

Use the pwd command if you cannot already tell by your command prompt that you are in the /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto directory.

Run the GREP11 sample code¶

Start Visual Studio Code within your current directory:
```
code .  # if typing by hand don't forget the period (for current directory)
```
In a moment you should see the Visual Studio Code window with your current directory structure shown in the Explorer pane in the upper left corner of the window:
Expand the golang folder, and then expand the examples folder underneath it. Your Explorer pane should then look similar to this:
From the Visual Studio Code menu, select View then Terminal, as shown below:
You will see a terminal appear within Visual Studio Code at the bottom:

Tip

If you hover your mouse over the line above the terminal, when it turns into the "double arrow" as highlighted in the above screen snippet, you can drag the line to resize your terminal window. This tip may come in handy for you during the course of the lab.
Change to the golang/examples directory within the Visual Studio Code terminal that you just opened:
```
cd golang/examples
```
Your terminal will look like this:

Tip

I have shown you how to use the Terminal window with Visual Studio Code, which you may find convenient. Your Ubuntu Desktop also provides a Terminal application that you can use to open one or more terminal windows. They behave the same, and which one you use is a personal choice, as long as you are in the correct directory that the instructions expect you to be in.

It is convenient to have a terminal window inside Visual Studio Code, but it comes at the expense of some screen real estate being taken away from the source code used in the exercises.

Use whichever method works best for you.

Test the GREP11 sample code:

go test -v

Example Output

=== RUN   Example_getMechanismInfo
--- PASS: Example_getMechanismInfo (0.29s)
=== RUN   Example_encryptAndDecrypt
--- PASS: Example_encryptAndDecrypt (0.84s)
=== RUN   Example_digest
--- PASS: Example_digest (0.55s)
=== RUN   Example_signAndVerifyUsingRSAKeyPair
--- PASS: Example_signAndVerifyUsingRSAKeyPair (0.50s)
=== RUN   Example_signAndVerifyUsingECDSAKeyPair
--- PASS: Example_signAndVerifyUsingECDSAKeyPair (0.52s)
=== RUN   Example_signAndVerifyToTestErrorHandling
--- PASS: Example_signAndVerifyToTestErrorHandling (0.51s)
=== RUN   Example_wrapAndUnwrapKey
--- PASS: Example_wrapAndUnwrapKey (0.41s)
=== RUN   Example_deriveKey
--- PASS: Example_deriveKey (0.61s)
=== RUN   Example_tls
--- PASS: Example_tls (0.40s)
PASS
ok      github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/examples   4.653s

Explanation of GREP11 sample code¶

The test used the go test subcommand, which does the following:

It looks for any file in the current directory named something*_test.go. There are two such files in our directory, *server_test.go and tls_test.go.
It looks for functions in these files named Example_something, and executes these functions.
At the bottom of each of these functions, a series of comment lines, starting with a header line, specifies what the expected output from the function should be. If the output from the function call matches the lines (except for the header line), then the test passes. Otherwise the test fails.

In the explorer pane, click on server_test.go or tls_test.go and examine the source code to see these lines. For example, lines 222-227 in server_test.go indicate what the expected output of the Example_encryptAndDecrypt function should be:

// Output:
// Generated AES Key
// Generated IV
// Encrypted message
// Decrypted message
// Hello, this is a very long and creative message without any imagination

Note

Go is a compiled language, and there are no executable files in this directory- the 'go test' command compiles the source code in the directory into an executable file in order to run the tests, and then cleans up afterwards by removing this executable.

Here is an itemization of the functions that our go test -v command tested, with a brief description of each. Our lab exercises in the subsequent sections will go into a little more depth on some of the more interesting of these functions.

Example_getMechanismInfo gets a list of PKCS #11 Mechanisms and then retrieves information about one of them. We will delve deeper into this in the first exercise.
Example_encryptAndDecrypt creates a secret (i.e., symmetric) key, encrypts data with it, then decrypts it, and ensures the data was unchanged after going through the encryption and decryption. We will look more into this in the second exercise.
Example_digest creates a digest², or hash, against some data. Digests are used in digital signatures, which the next two tests cover.
Example_signAndVerifyUsingRSAKeyPair creates an RSA public and private key pair and uses the private key to create a digital signature and the public key to verify the digital signature.
Example_signAndVerifyUsingECDSAKeyPair creates an elliptic curve public and private key pair and uses the private key to create a digital signature and uses the public key to verify the digital signature. We go into greater depth (and discuss the differences between RSA and Elliptic Curves) in the third exercise.
Example_signAndVerifyToTestErrorHandling intentionally causes an error- after a signature is created, the program modifies a byte in it, so that when the signature is verified later, an error occurs. The test passes because the expected error message is listed in the expected test output.
Example_wrapAndUnwrapKey creates a public and private key pair and uses the public key to encrypt, or wrap, a symmetric key, which can then only be decrypted, or unwrapped, by the private key. The fourth and final exercise covers this topic.
Example_deriveKey illustrates a common algorithm where two sides of a connection each have a public and private key pair, and they use each other's public key in an algorithm that allows each of them to derive an identical secret, i.e., symmetric, key, without ever having sent that secret key across the connection. This is a common use case because encryption and decryption with a symmetric key is much faster than encryption and decryption with public and private keys. The two parties use relatively slow public key cryptography to derive this shared symmetric key at the beginning of their session, and then switch to using this symmetric key for the remainder of the session. This function and all of the functions preceding it in this list are in the server_test.go source file.
Example_tls creates an X.509 certificate, starts up an http server that uses this certificate, and has a client connect to the server with TLS authentication, which uses this certificate to establish a session. This test is in the tls_test.go source file.

Please proceed to the next section.

The Go compiler has traditionally been very picky about where source code files must reside. This situation has eased recently with the introduction of Go modules in newer releases, but our lab is not using Go modules. Go expects to find source files in the ${GOPATH}/src directory hierarchy, and if you do not have the GOPATH environment variable set, it expects fo find source files in the ${HOME}/go/src directory hierarchy. ↩
A hash is a fixed-length fingerprint for a set of input data of any size. Since there are an infinite number of possible input combinations, and the hash is fixed-length, in theory two different sets of data could produce the same hash. This is called a collision. In practice, the hash is of sufficient size, and the algorithm to produce it sufficiently complex, that it is computationally infeasible to produce the same hash with two different sets of input. If it can be demonstrated that two different sets of input can produce the same fingerprint by a hashing algorithm, then that algorithm will be considered insecure and fall into disuse in favor of stronger hashing algorithms. ↩

Run the Lab exercises ↵

An overview of the exercises¶

Expand the lab folder in your Visual Studio Code explorer pane so that you can see the source code files in the folder, similar to what is shown in the screen snippet below:

Change to golang/lab

Running the go test -v command in the golang/examples directory was good for ensuring that our GREP11 server setup works and that our client application can access it. But there is not a lot of output produced by this test, so we took the functions used in the test and added statements in many places to produce output for educational purposes. We also added some flexibility to the functions by adding some function arguments that would let us modify function behavior, again, for educational purposes.

We left the golang/examples directory intact, and copied the source code into a new directory that we created, golang/lab, and made our program modifications in that directory.

Note

These exercises are meant to illustrate various concepts for learning about the functionality that the GREP11 server and the Crypto Express card in EP11 mode provide, and are not meant to illustrate Go programming lanuage best practices. In fact, we violated one best practice (DRY - Don't Repeat Yourself) when we copied the examples directory into the lab directory!

Feel free to copy our source code and use it as you see fit, but it is provided "as is", without support or warranty of any kind.

Other than adding a whole bunch of statements to print output, at a high level, the following changes in program structure were made after copying the source code from golang/examples into golang/labs

The routine to set the variables needed to connect to the GREP11 server was moved into a separate file, callopt.go. This routine specifies the IP address and port where the GREP11 server is listening, and it also contains variables specifying the certificates and keys necessary to establish a session between our program and the GREP11 server using mutual TLS authentication.

Note

The information in the callopt.go file is the type of information that would be provided by an administrator, such as the Hyper Protect Virtual Servers administrator for hostname or IP address and port for connection, and perhaps the same or a different security administrator for the certficates and keys necessary to successfully establish the connection with mutual TLS authentication.
A main() function, which is the entry point for the program, was created, in the file main.go. It uses arguments to determine which of the four exercises to invoke. (You can actually invoke any combination of them in one program invocation but in our lab instructions we only have you do one at a time). We added some extra arguments that work with exercises two, three, and four, in order to illustrate concepts of interest.
There are four separate source files, exercise1.go, exercise2.go, exercise3.go, and exercise4.go each of which was created by copying one of the Example_ test functions from golang/examples/server_test.go, modifying the name of the function to remove Example_ from its name to reinforce the point that it was no longer a function suitable for using with the go test command.
1. exercise1.go began life as Example_getMechanismInfo()
2. exercise2.go started out as Example_encryptAndDecrypt()
3. exercise3.go was Example_signAndVerifyUsingECDSAKeyPair()
4. exercise4.go had its origins as Example_wrapAndUnwrapKey()
We deleted some of the files that we copied over that were not needed to run our lab exercises.

It's time to start the first exercise. Enjoy!

Exercise 1 - List Mechanisms¶

Explanation of Mechanisms¶

Mechanisms is the PKCS #11 standard's fancy word for algorithms.

In the introduction of the PKCS#11 Cryptographic Token Interface Base Specification 2.40 document, there is this statement: Details of cryptographic mechanisms (algorithms) may be found in the associated PKCS#11 Mechanisms documents.

And then in the PKCS#11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40 it says A mechanism specifies precisely how a certain cryptographic process is to be performed.

This exercise will list the mechanisms supported by the Crypto Express card in EP11 mode.

The program that you will invoke in this exercise issues a GetMechanismList() function call to the GREP11 server, and then it will iterate through the list returned, calling GetMechanismInfo() against each mechanism to obtain more info about it.

Run the program and then a brief discussion of the results will follow:

You may wish to view the source code used by the lab exercises while running them. It is handy to expand the Outline view in the left pane of Visual Studio Code which will show the various function and type definitions of the source code you have highlighted in the main portion of the Visual Studio Code window. The Outline view may not be necessary for smaller source code files but it comes in handy for some of the larger source code files. The screen snippet below shows where the Outline view is:
Change to the lab directory in your terminal:
```
cd ../lab
```
In the prior section, the go test command built the executable file it needed transparently to us. For our lab exercises, we need to build the executable binary. We will use a single executable for all of the exercises, and invoke the various exercises through command line arguments. Build the executable now with this command:
```
go build
```
Note

The absence of any messages is your indication of success!
The go build command should have created an excutable file that shares the name of the directory in which you are working- lab. List that file and you should see it has a recent date and timestamp.
```
ls -l lab
```
Example output
```
-rwxr-xr-x 1 hyper-protect-lab hyper-protect-lab 17545825 Jul  8 06:26 lab
```
Tip

You may be doing this lab in a virtual machine whose clock is set for a time zone different from where you are. You can always issue the date command to see what time your virtual machine thinks it is at the moment.

Run the first exercise by passing the appropriate argument, shown below, to the lab program:

./lab --ex1

Example output

Got mechanism list of length 94:

Mechanism  0 : CKM_RSA_PKCS 
MinKeySize:512 MaxKeySize:4096 Flags:404224  

Mechanism  1 : CKM_RSA_PKCS_OAEP 
MinKeySize:512 MaxKeySize:4096 Flags:393984  

Mechanism  2 : CKM_RSA_PKCS_KEY_PAIR_GEN 
MinKeySize:512 MaxKeySize:4096 Flags:65536  

Mechanism  3 : CKM_RSA_X9_31_KEY_PAIR_GEN 
MinKeySize:512 MaxKeySize:4096 Flags:65536  

Mechanism  4 : CKM_RSA_PKCS_PSS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  5 : CKM_SHA1_RSA_X9_31 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  6 : CKM_SHA1_RSA_PKCS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  7 : CKM_SHA1_RSA_PKCS_PSS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  8 : CKM_SHA256_RSA_PKCS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  9 : CKM_SHA256_RSA_PKCS_PSS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  10 : CKM_SHA224_RSA_PKCS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  11 : CKM_SHA224_RSA_PKCS_PSS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  12 : CKM_SHA384_RSA_PKCS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  13 : CKM_SHA384_RSA_PKCS_PSS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  14 : CKM_SHA512_RSA_PKCS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  15 : CKM_SHA512_RSA_PKCS_PSS 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  16 : CKM_AES_KEY_GEN 
MinKeySize:16 MaxKeySize:32 Flags:32768  

Mechanism  17 : CKM_AES_ECB 
MinKeySize:16 MaxKeySize:32 Flags:768  

Mechanism  18 : CKM_AES_CBC 
MinKeySize:16 MaxKeySize:32 Flags:393984  

Mechanism  19 : CKM_AES_CBC_PAD 
MinKeySize:16 MaxKeySize:32 Flags:393984  

Mechanism  20 : CKM_DES2_KEY_GEN 
MinKeySize:16 MaxKeySize:16 Flags:32768  

Mechanism  21 : CKM_DES3_KEY_GEN 
MinKeySize:24 MaxKeySize:24 Flags:32768  

Mechanism  22 : CKM_DES3_ECB 
MinKeySize:16 MaxKeySize:24 Flags:768  

Mechanism  23 : CKM_DES3_CBC 
MinKeySize:16 MaxKeySize:24 Flags:393984  

Mechanism  24 : CKM_DES3_CBC_PAD 
MinKeySize:16 MaxKeySize:24 Flags:393984  

Mechanism  25 : CKM_GENERIC_SECRET_KEY_GEN 
MinKeySize:8 MaxKeySize:256 Flags:557056  

Mechanism  26 : CKM_SHA256 
Flags:1024  

Mechanism  27 : CKM_SHA256_KEY_DERIVATION 
Flags:524288  

Mechanism  28 : CKM_SHA256_HMAC 
MinKeySize:16 MaxKeySize:32 Flags:10240  

Mechanism  29 : CKM_SHA224 
Flags:1024  

Mechanism  30 : CKM_SHA224_KEY_DERIVATION 
Flags:524288  

Mechanism  31 : CKM_SHA224_HMAC 
MinKeySize:14 MaxKeySize:32 Flags:10240  

Mechanism  32 : CKM_SHA_1 
Flags:1024  

Mechanism  33 : CKM_SHA1_KEY_DERIVATION 
Flags:524288  

Mechanism  34 : CKM_SHA_1_HMAC 
MinKeySize:10 MaxKeySize:32 Flags:10240  

Mechanism  35 : CKM_SHA384 
Flags:1024  

Mechanism  36 : CKM_SHA384_KEY_DERIVATION 
Flags:524288  

Mechanism  37 : CKM_SHA384_HMAC 
MinKeySize:24 MaxKeySize:32 Flags:10240  

Mechanism  38 : CKM_SHA512 
Flags:1024  

Mechanism  39 : CKM_SHA512_KEY_DERIVATION 
Flags:524288  

Mechanism  40 : CKM_SHA512_HMAC 
MinKeySize:32 MaxKeySize:32 Flags:10240  

Mechanism  41 : CKM_SHA512_256 
Flags:1024  

Mechanism  42 : CKM_IBM_SHA512_256 
Flags:1024  

Mechanism  43 : CKM_SHA512_256_HMAC 
MinKeySize:16 MaxKeySize:32 Flags:10240  

Mechanism  44 : CKM_IBM_SHA512_256_HMAC 
MinKeySize:16 MaxKeySize:32 Flags:10240  

Mechanism  45 : CKM_SHA512_224 
Flags:1024  

Mechanism  46 : CKM_IBM_SHA512_224 
Flags:1024  

Mechanism  47 : CKM_SHA512_224_HMAC 
MinKeySize:14 MaxKeySize:32 Flags:10240  

Mechanism  48 : CKM_IBM_SHA512_224_HMAC 
MinKeySize:14 MaxKeySize:32 Flags:10240  

Mechanism  49 : CKM_EC_KEY_PAIR_GEN 
MinKeySize:192 MaxKeySize:521 Flags:26279936  

Mechanism  50 : CKM_ECDSA 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  51 : CKM_ECDSA_SHA1 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  52 : CKM_ECDH1_DERIVE 
MinKeySize:192 MaxKeySize:521 Flags:18350080  

Mechanism  53 : CKM_IBM_ECDH1_DERIVE_RAW 
MinKeySize:192 MaxKeySize:521 Flags:18350080  

Mechanism  54 : CKM_IBM_EC_MULTIPLY 
MinKeySize:192 MaxKeySize:521 Flags:256  

Mechanism  55 : CKM_DSA_PARAMETER_GEN 
MinKeySize:1024 MaxKeySize:3072 Flags:32768  

Mechanism  56 : CKM_DSA_KEY_PAIR_GEN 
MinKeySize:1024 MaxKeySize:3072 Flags:65536  

Mechanism  57 : CKM_DSA 
MinKeySize:1024 MaxKeySize:3072 Flags:10240  

Mechanism  58 : CKM_DSA_SHA1 
MinKeySize:1024 MaxKeySize:3072 Flags:10240  

Mechanism  59 : CKM_DH_PKCS_PARAMETER_GEN 
MinKeySize:1024 MaxKeySize:3072 Flags:32768  

Mechanism  60 : CKM_DH_PKCS_KEY_PAIR_GEN 
MinKeySize:1024 MaxKeySize:3072 Flags:65536  

Mechanism  61 : CKM_DH_PKCS_DERIVE 
MinKeySize:1024 MaxKeySize:3072 Flags:524288  

Mechanism  62 : CKM_IBM_DH_PKCS_DERIVE_RAW 
MinKeySize:1024 MaxKeySize:3072 Flags:524288  

Mechanism  63 : Mechanism(0x80010023) 
MinKeySize:256 MaxKeySize:256 Flags:75776  

Mechanism  64 : CKM_RSA_X9_31 
MinKeySize:512 MaxKeySize:4096 Flags:10240  

Mechanism  65 : CKM_PBE_SHA1_DES3_EDE_CBC 
MinKeySize:24 MaxKeySize:24 Flags:32768  

Mechanism  66 : CKM_IBM_SHA3_224 
Flags:1024  

Mechanism  67 : CKM_IBM_SHA3_256 
Flags:1024  

Mechanism  68 : CKM_IBM_SHA3_384 
Flags:1024  

Mechanism  69 : CKM_IBM_SHA3_512 
Flags:1024  

Mechanism  70 : Mechanism(0x80010025) 
MinKeySize:14 MaxKeySize:32 Flags:10240  

Mechanism  71 : Mechanism(0x80010026) 
MinKeySize:16 MaxKeySize:32 Flags:10240  

Mechanism  72 : Mechanism(0x80010027) 
MinKeySize:24 MaxKeySize:32 Flags:10240  

Mechanism  73 : Mechanism(0x80010028) 
MinKeySize:32 MaxKeySize:32 Flags:10240  

Mechanism  74 : CKM_IBM_ATTRIBUTEBOUND_WRAP 
MaxKeySize:4096 Flags:393216  

Mechanism  75 : Mechanism(0x1043) 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  76 : CKM_IBM_ECDSA_SHA224 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  77 : Mechanism(0x1044) 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  78 : CKM_IBM_ECDSA_SHA256 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  79 : Mechanism(0x1045) 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  80 : CKM_IBM_ECDSA_SHA384 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  81 : Mechanism(0x1046) 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  82 : CKM_IBM_ECDSA_SHA512 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  83 : Mechanism(0x80010031) 
MinKeySize:192 MaxKeySize:521 Flags:26224640  

Mechanism  84 : CKM_IBM_EC_C25519 
MinKeySize:256 MaxKeySize:256 Flags:18350080  

Mechanism  85 : CKM_IBM_EC_C448 
MinKeySize:448 MaxKeySize:448 Flags:18350080  

Mechanism  86 : CKM_IBM_EDDSA_SHA512 
MinKeySize:256 MaxKeySize:256 Flags:17836032  

Mechanism  87 : CKM_IBM_ED448_SHA3 
MinKeySize:448 MaxKeySize:448 Flags:17836032  

Mechanism  88 : CKM_IBM_EAC 
Flags:524288  

Mechanism  89 : CKM_IBM_RETAINKEY 
MaxKeySize:256 Flags:131072  

Mechanism  90 : CKM_IBM_CMAC 
MinKeySize:16 MaxKeySize:32 Flags:10240  

Mechanism  91 : CKM_AES_CMAC 
MinKeySize:16 MaxKeySize:32 Flags:10240  

Mechanism  92 : CKM_DES3_CMAC 
MinKeySize:16 MaxKeySize:24 Flags:10240  

Mechanism  93 : Mechanism(0x80070001) 
MinKeySize:16 MaxKeySize:64 Flags:524288

Explanation of exercise output¶

Near the top of the output, you see the line:

Got mechanism list of length 94:

This indicates there were 94 mechanisms returned by the call to GetMechanismList().

Then, for each mechanism, two lines of output are created, one with the mechanism name, which usually start with CKM_. The mechanism number has no significance, this is just an index number assigned by our lab program, starting at 0 and incremented by the program as it iterates over the list.

The information returned by GetMechanismInfo() includes the minimum key size and maximum key size for the mechanism, if applicable, and flags that are associated with the mechanism. The numbers shown are in decimal, and the key sizes shown are in bytes.

Tip

If you are doing this lab at your leisure on your own system, you could look in golang/ep11/header_consts.go and find the flags within lines 596 through 649 of that file. You'd have to convert the decimal value shown to hexadecimal. If you are taking this lab as part of a virtual event, do not take the time now to deconstruct these flags- you can always do that later since this lab is publicly available.

Observe that the large majority of mechanisms in the list have a name starting with CKM_, while a handful, such as item 77, 79, 81, and others, do not. It appears that if the mechanism is not listed in the golang/ep11/header_consts.go file, within lines 205 to 594, then it will not have a name starting with CKM_.

Note that the PKCS #11 specification does not mandate that an implementation support all defined mechanisms. Even within the subset of the 94 mechanisms that are supported by IBM's EP11 library, some are for algorithms that are considered rather outdated, and, in some cases, downright insecure. For example, the SHA-1 cryptographic hash algorithm is considered insecure these days, so any mechanims in the list that have SHA1 or SHA_1 in their name (and there are some) should be avoided.

Let's move on to Exercise 2.

Exercise 2 - Encrypt and Decrypt Data¶

Overview of Exercise 2¶

Exercise 2 creates an AES secret key and uses it to encrypt some plaintext data. Plaintext which has been encrypted is referred to as ciphertext. This ciphertext is then decrypted back into plaintext using the same AES secret key that was used for encryption. The original plaintext is compared to- and is expected to be identical to- the plaintext that resulted from the encryption and decryption.

Note

Plaintext data is often, but not necessarily, human-readable. It is any data that could be of value to an adversary, if the adversary could obtain the data in its original, or plaintext, form. Hence the need for encryption. If an adversary were to obtain ciphertext, it is unreadable and thus of little or no value to the adversary.

Note

The PKCS #11 standard uses the phrase secret key often. Secret key is synonoymous with the term symmetric key, which is also a term commonly used in cryptography. That is, a single key is used for both encryption and decryption.

Run the second exercise:

./lab --ex2

Example Output

Generated AES Key with mechanism  CKM_AES_KEY_GEN

length of key blob is 256 bytes
Key blob is (values in decimal):
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 141 38 0 0 0 0 0 0 0 1 18 52 217 158 52 159 29 220 10 126 250 240 129 168 243 15 158 220 32 30 158 254 73 111 45 102 230 162 209 246 93 216 200 108 223 116 32 109 1 82 87 166 108 227 20 9 54 59 24 126 154 14 159 250 161 203 128 27 237 27 218 243 169 235 28 112 101 109 177 94 191 251 198 126 102 93 236 51 190 157 4 188 128 1 114 120 135 191 22 7 42 191 209 135 168 241 228 137 121 180 140 113 211 159 26 192 70 74 130 25 180 75 86 230 207 240 101 164 65 179 122 59 202 213 142 244 54 151 158 46 72 52 249 87 219 11 202 69 150 45 195 200 84 134 30 148 21 70 144 235 236 141 234 135 4 120 1 180 69 84 35 73 16 71 208 212 143 135 222 115 85 26 25 172 2 202 15 2 249 109 71 41 255 177 105 20 134 33 10 54 254 210]

The above structure is what you would save in order to persist this key blob.

Below is how the above structure would typically be saved, in PEM Format:

-----BEGIN HSM ENCRYPTED AES SECRET KEY-----
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADsIIxQY2Y9lWElrfi1CQo
AAAAAAAAjSYAAAAAAAAAARI02Z40nx3cCn768IGo8w+e3CAenv5Jby1m5qLR9l3Y
yGzfdCBtAVJXpmzjFAk2Oxh+mg6f+qHLgBvtG9rzqesccGVtsV6/+8Z+Zl3sM76d
BLyAAXJ4h78WByq/0Yeo8eSJebSMcdOfGsBGSoIZtEtW5s/wZaRBs3o7ytWO9DaX
ni5INPlX2wvKRZYtw8hUhh6UFUaQ6+yN6ocEeAG0RVQjSRBH0NSPh95zVRoZrALK
DwL5bUcp/7FpFIYhCjb+0g==
-----END HSM ENCRYPTED AES SECRET KEY-----

WK virtualization mask is [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
See 6.2.2 of page 179 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

WK ID is [3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]
See 6.7.1 on page 182 of  http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Blob version is [18 52]
See 3.1.1 on page 141 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Initialization Vector is [217 158 52 159 29 220 10 126 250 240 129 168 243 15]

Encrypted part is [158 220 32 30 158 254 73 111 45 102 230 162 209 246 93 216 200 108 223 116 32 109 1 82 87 166 108 227 20 9 54 59 24 126 154 14 159 250 161 203 128 27 237 27 218 243 169 235 28 112 101 109 177 94 191 251 198 126 102 93 236 51 190 157 4 188 128 1 114 120 135 191 22 7 42 191 209 135 168 241 228 137 121 180 140 113 211 159 26 192 70 74 130 25 180 75 86 230 207 240 101 164 65 179 122 59 202 213 142 244 54 151 158 46 72 52 249 87 219 11 202 69 150 45 195 200 84 134 30 148 21 70 144 235 236 141 234 135 4 120 1 180 69 84]

MAC is [35 73 16 71 208 212 143 135 222 115 85 26 25 172 2 202 15 2 249 109 71 41 255 177 105 20 134 33 10 54 254 210]
MAC is 32 bytes, see field 15 in 3.1 on page 140 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Checksum is [144 147 65], length of checksum is 3


Original message, prior to any encryption or decryption operations:  Hello, this is a very long and creative message without any imagination

in progress ciphertext is:
��!E�S���}�p�!��

in progress ciphertext is:
��!E�S���}�p�!��7I�Hd�i�7p�/N˽.�g��K�;����_����NØtk���YH�^�

Final ciphertext is:
��!E�S���}�p�!��7I�Hd�i�7p�/N˽.�g��K�;����_����NØtk���YH�^���H�5f�!��>-c

In progress decryption is:


In progress decryption is:
Hello, this is a very long and creative message without any imag

Final decryption is:
Hello, this is a very long and creative message without any imagination

Original message equals decrypted message!

Original message:  Hello, this is a very long and creative message without any imagination
Length of original message: 71

Encrypted message
��!E�S���}�p�!��7I�Hd�i�7p�/N˽.�g��K�;����_����NØtk���YH�^���H�5f�!��>-c
Length of encrypted message: 80

Decrypted message: Hello, this is a very long and creative message without any imagination
Length of decrypted message: 71

The mechanism used to generate the key is CKM_AES_KEY_GEN which informs us that we wish to generate an AES secret key.

The length of the key blob is 256 bytes. Notice that this key blob contains metadata used by the EP11 library, so it contains much more than the actual key, which is 256 bits, not bytes. In fact we can't even see the key in cleartext form. It is encrypted within the key blob by the Crypto Express 7S card domain's root wrapping key. The only place the key we created is ever available in the clear is while it is being used inside the Crypto Express 7S card, because the root wrapping key never leaves the card.

The ID of the root wrapping key of the Crypto Express 7S card domain is listed in the output in the line that starts with WK ID is. This ID is the first sixteen bytes of the hash of the key. It is not the full hash, and even if it was, you cannot retrieve the original data from the hash, so the root wrapping key remains secret.

The ID of the root wrapping key for our Crypto Express 7S card domain is

[3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]

As you perform the exercises in this lab, you may notice that any time I print out the WK ID, it will always be this value.

The encryption in this exercise takes place in multiple calls. One may either encrypt all of the data in a single call to a function named Encrypt(), or may make multiple calls by performing one or more calls to EncryptUpdate() followed by a call to EncryptFinal(). This sample program uses the latter approach, so in the output you see two lines that say In progress ciphertext is that show the results so far after each EncryptUpdate() call and then a line that says Final ciphertext is after the call to EncryptFinal(). Decryption follows the same pattern- two calls to DecryptUpdate() followed by a call to DecryptFinal(), and the output in the program indicates this.

The program for this exercise defaults to a key length of 256 bits. Try running with a key length of 128 bits:

./lab --ex2 --keyLength 128

Example Output

Generated AES Key with mechanism  CKM_AES_KEY_GEN

length of key blob is 256 bytes
Key blob is (values in decimal):
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 141 38 0 0 0 0 0 0 0 1 18 52 3 221 177 141 112 242 216 176 144 18 6 175 10 206 202 162 226 99 67 216 88 101 201 3 114 172 228 151 134 15 141 183 46 209 125 119 136 246 196 223 189 56 243 204 100 151 226 149 160 128 229 255 216 226 133 171 65 244 16 197 245 172 136 232 118 184 206 173 34 79 215 214 202 250 8 237 80 168 235 252 137 221 202 76 92 21 176 127 119 178 212 220 235 169 231 144 203 67 92 32 243 99 83 171 234 198 118 71 201 176 223 202 214 117 107 152 139 105 99 39 22 243 21 20 173 175 57 84 114 199 115 225 125 30 230 123 50 120 157 37 32 151 24 77 118 170 12 222 17 3 53 7 177 238 226 18 192 102 80 131 223 195 188 205 133 31 172 138 123 48 4 244 81 224 205 165 108 128 163 226 55 208 117 70 166 128 111 166 213 158]

The above structure is what you would save in order to persist this key blob.

Below is how the above structure would typically be saved, in PEM Format:

-----BEGIN HSM ENCRYPTED AES SECRET KEY-----
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADsIIxQY2Y9lWElrfi1CQo
AAAAAAAAjSYAAAAAAAAAARI0A92xjXDy2LCQEgavCs7KouJjQ9hYZckDcqzkl4YP
jbcu0X13iPbE370488xkl+KVoIDl/9jihatB9BDF9ayI6Ha4zq0iT9fWyvoI7VCo
6/yJ3cpMXBWwf3ey1NzrqeeQy0NcIPNjU6vqxnZHybDfytZ1a5iLaWMnFvMVFK2v
OVRyx3PhfR7mezJ4nSUglxhNdqoM3hEDNQex7uISwGZQg9/DvM2FH6yKezAE9FHg
zaVsgKPiN9B1RqaAb6bVng==
-----END HSM ENCRYPTED AES SECRET KEY-----

WK virtualization mask is [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]
See 6.2.2 of page 179 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

WK ID is [3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]
See 6.7.1 on page 182 of  http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Blob version is [18 52]
See 3.1.1 on page 141 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Initialization Vector is [3 221 177 141 112 242 216 176 144 18 6 175 10 206]

Encrypted part is [202 162 226 99 67 216 88 101 201 3 114 172 228 151 134 15 141 183 46 209 125 119 136 246 196 223 189 56 243 204 100 151 226 149 160 128 229 255 216 226 133 171 65 244 16 197 245 172 136 232 118 184 206 173 34 79 215 214 202 250 8 237 80 168 235 252 137 221 202 76 92 21 176 127 119 178 212 220 235 169 231 144 203 67 92 32 243 99 83 171 234 198 118 71 201 176 223 202 214 117 107 152 139 105 99 39 22 243 21 20 173 175 57 84 114 199 115 225 125 30 230 123 50 120 157 37 32 151 24 77 118 170 12 222 17 3 53 7 177 238 226 18 192 102]

MAC is [80 131 223 195 188 205 133 31 172 138 123 48 4 244 81 224 205 165 108 128 163 226 55 208 117 70 166 128 111 166 213 158]
MAC is 32 bytes, see field 15 in 3.1 on page 140 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Checksum is [132 58 194], length of checksum is 3


Original message, prior to any encryption or decryption operations:  Hello, this is a very long and creative message without any imagination

in progress ciphertext is:
���[�F�Vl

in progress ciphertext is:
���[̶:���l
        �.�W�+�]n,�#�-��{������4��uj��!�
                                            v

Final ciphertext is:
���[̶:���l
        �.�W�+�]n,�#�-��{������4��uj��!�
                                            v��7Ѵ��,��5-��

In progress decryption is:


In progress decryption is:
Hello, this is a very long and creative message without any imag

Final decryption is:
Hello, this is a very long and creative message without any imagination

Original message equals decrypted message!

Original message:  Hello, this is a very long and creative message without any imagination
Length of original message: 71

Encrypted message
���[̶:���l
        �.�W�+�]n,�#�-��{������4��uj��!�
                                            v��7Ѵ��,��5-��
Length of encrypted message: 80

Decrypted message: Hello, this is a very long and creative message without any imagination
Length of decrypted message: 71

Our first run of this program used a key length of 256 bits, and this run used a key length of 128 bits. Notice that the key blob itself is still 256 bytes in length.

By the way, the gibberish printed out in the encrypted message portion of the output is because a byte of ciphertext is likely to contain any value from 0 to 255 and only a portion of those will turn out to be printable characters if you try to treat it as if it was a character string and try to print it out like this program does- you may see one or more lines, if one of the ciphertext bytes produced happens to be the value of a linefeed character, and if it is a carriage return without a line feed it may have "overwritten" some of the preceding gibberish. Real life use cases aren't typically going to require you to print ciphertext as this program did for education purposes.

Try with a key length of 192 bits:
```
./lab --ex2 --keyLength 192
```
Note

Output not shown here, it should be similar to the prior two commands.
Try with a key length of 384 bits:
```
./lab --ex2 --keyLength 384
```
Example Output
```
panic: GenerateKey Error: rpc error: code = Unknown desc = CKR_KEY_SIZE_RANGE

goroutine 1 [running]:
main.encryptAndDecrypt(0x180, 0xa28e3b, 0x47)
    /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/exercise2.go:55 +0x2c89
main.main()
    /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/main.go:73 +0x3a3
```
Don't panic! (Even if Go did). I meant for this to happen.

This exercise uses the CKM_AES_KEY_GEN mechanism. (This is in the first line of the program output). If we run exercise one again and pipe its output to grep, with a fancy argument to print one extra line, we can see that the minimum key size is 128 bits and the maximum key size is 256 bits. Try it:
```
./lab --ex1 | grep CKM_AES_KEY_GEN --after-context 1
```
Note

The minimum and maximum key sizes are shown in bytes, so you must multiply the values shown by eight to get the sizes in bits.
So our key size must be in a range from 128 to 256 bits. Let's try a key length of 224 bits:
```
./lab --ex2 --keyLength 224
```
Example Output
```
panic: GenerateKey Error: rpc error: code = Unknown desc = CKR_KEY_SIZE_RANGE

goroutine 1 [running]:
main.encryptAndDecrypt(0xe0, 0xa28e3b, 0x47)
    /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/exercise2.go:55 +0x2c89
main.main()
    /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/main.go:73 +0x3a3
```
Is this the new math where 224 is not between 128 and 256? No. What's going on here is that the AES standard supports keys of a certain length- 128, 192, and 256 bits. So while the mechanism information told us the minimum and maximum key size, the expectation is that the programmer knows a little bit about the AES standard when using it!
Would you like to encrypt and decrypt your own text? Try it like this- feel free to copy and paste what is provided here, or substitute your own witty banter for the value of the --plaintext argument.
```
./lab --ex2 --plaintext "The quick brown fox jumped over the lazy dog"
```
Note

Output not shown, but you should see the message being encrypted and decrypted. Unless...

Troubleshooting

If you received this message in your output, panic: Failed Encrypt [rpc error: code = Unknown desc = CKR_ARGUMENTS_BAD], then there is a pretty good chance that you supplied a plaintext value less than twenty-one characters in length.

This exercise was based on the sample code, which performs the encryption in two steps. The first step passed the first twenty bytes of input to the crypto card, and the second step passed the remainder of the input. The input was hard-coded and of length greater than twenty bytes, so the sample does not have logic to handle input of twenty bytes or less. The sample has not been modified to handle the case where that second pass isn't needed.

Don't worry, in the real world, you can probably solve this problem if you throw enough money at it. :-)

Exercise 3 - Sign and Verify Data¶

Overview of Exercise 3¶

Exercise three uses public key cryptography to demonstrate signing of data and then verifying the signature.

Other terms often used that are associated with public key cryptography are asymmetric keys or public and private key pairs.

The major characteristic is that an asymmetric key is actually a pair of keys that are related. One key is called the public key and can be shared with anyone. The other key is called the private key and is kept secret.

These key pairs can be used for encryption and decryption, as well as for creating and verifying digital signatures.

Public key cryptography in simple terms¶

Public key cryptography and encryption

When using public key cryptography, the assumption is that anybody in the world could have your public key, but you have kept your private key to yourself.

For encryption, anybody who has your public key could encrypt data with it and send you that encrypted data, or ciphertext. If an adversary possessed the ciphertext, they could not decrypt it. Only you, with your private key, can decrypt it.

Technically, you could encrypt data with your private key that holders of your public key could decrypt, but this use case doesn't make sense- since anybody could have your public key, you have not managed to achieve privacy with your encryption.

Public key cryptography and digital signatures

Your private key can be used to allow you to digitally "sign" data, which is an attestation that you have seen the data that you have signed, analagous to your signing by pen a letter or contract on a piece of paper.

There are different digital signature algorithms, but in general, they follow the following pattern. Assume you want to digitally sign some data you send to somebody:

You create a digest, or hash, over some data, using some algorithm. This hash uniquely identifies the data.
You encrypt this hash with your private key. This is your digital signature.
You send the data, and your digital signature, to the intended recipient.
The recipient calculates the digest, or hash, of the data, using the same algorithm that you used in step 1. If the data has remained intact in transit, they will calculate the same hash that you did in step 1.
They then decrypt your signature (from step 2) with your public key. This retrieves in plaintext the hash you signed in step 2.
If the hash they calculated in step 4 matches the hash that you encrypted with your private key in step 2 (and retrieved by them in step 5), then it is proof that you have seen the data they have received.

The fundamental assumption is that you have kept your private key in your sole possession. If an adversary stole your private key they could impersonate you.

Also, observe that the validity of this digital signature is independent of whether or not the data that you send is plaintext or ciphertext.

The two most commonly used forms of public key cryptography are RSA cryptography and elliptic curve cryptography.

RSA cryptography was developed first and is built upon the difficulty of factoring the product of two very large prime numbers. It is easy for a computer to find two very large prime numbers and multiply them together to obtain a product. On the other hand, given this product, it is extremely difficult, if not impossible, for even today's powerful computers to figure out what two prime numbers were used to produce that product! It seems like a preposterous statement, but it's true!

Elliptic curve cryptography is based on algebraic equations called elliptic curves. The idea is that a mathematical addition function can be defined on this curve, such that it is very easy for a computer to do a large number of additions on the curve which results in a point on the curve. But if you give someone the equation for the curve, and the point on the curve that you have calculated, but you don't tell them how many additions you did to calculate this point, even today's powerful computers cannot figure out how many additions were performed! It seems like a preposterous statement, but it's true!

In simple terms, an RSA public key contains the product of the two primes, and the RSA private key contains the hidden information- the two primes. An elliptic curve public key contains all of the information about the curve, including the point that was calculated, except for the number of additions used to calculate the point, while the elliptic curve private key includes the hidden information- the number of additions that were used to create the point.

If I multiplied two small prime numbers like 7 x 13 and gave you the product 91, it probably wouldn't take you too long to factor it back to 7 and 13. Computers need to use incredibliy large prime numbers in order to calculate a product that another computer can't quickly factor. That is why RSA keys are usually 2048 or 4096 bits in length. You can create smaller RSA keys but today's computers can factor the product contained in the public key quicker, the smaller the key.

On the other hand, the size of elliptic curve public keys can be much smaller than RSA public keys, and provide the equivalent strength. That is, a relatively small-sized elliptic curve key is just as difficult for a computer to crack by brute force than it is for a much larger-sized RSA key.

For this reason, elliptic curve cryptography is becoming increasingly popular- the smaller key size means less computational power is needed to work with these keys, so they are more efficient and use less power, which is more appealing for devices that are typically drawing on battery power, like smartphones and tablets.

EP11 supports both RSA and elliptic curve cryptography, as you saw in the GREP11 sample. This exercise will dig a little deeper into elliptic curves.

Run Exercise 3¶

Run the third exercise:

./lab --ex3

Example Output

selected curve P521 with ObjectID of 1.3.132.0.35
Curve ObjectID in ASN.1 BER encoding is [6 5 43 129 4 0 35]

Generated ECDSA PKCS key pair with mechanism  CKM_EC_KEY_PAIR_GEN

key pair public key blob length is 286 bytes

key pair public key blob is [48 129 155 48 16 6 7 42 134 72 206 61 2 1 6 5 43 129 4 0 35 3 129 134 0 4 1 251 93 197 238 11 2 165 14 39 212 27 175 77 65 78 70 252 221 242 195 236 163 3 63 184 70 158 146 51 22 230 181 30 78 101 47 150 133 100 197 101 31 144 59 192 199 237 14 94 86 237 73 52 79 1 45 220 65 57 113 117 113 173 220 70 0 48 137 50 146 141 22 219 122 151 69 232 10 132 29 121 198 108 226 233 9 117 185 16 125 236 113 235 136 54 127 109 229 150 26 117 63 231 242 158 101 248 86 80 17 69 31 217 156 122 140 30 75 132 155 187 35 148 239 49 81 172 10 210 181 169 4 16 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 4 32 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 8 255 72 74 131 146 172 234 187 4 8 0 0 0 0 0 0 0 1 4 20 16 1 0 0 0 1 128 128 0 1 128 128 128 1 0 10 0 0 0 1 4 32 217 93 11 148 136 24 62 138 168 213 244 131 187 81 107 102 114 120 167 70 193 179 233 4 32 228 144 160 232 167 125 167]

key pair private key blob length is 896 bytes

key pair private key blob is [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 1 38 0 0 0 0 0 0 0 1 18 52 145 242 100 209 252 135 97 118 108 26 68 196 204 214 35 186 208 121 174 78 194 146 179 179 92 26 100 178 30 39 144 58 232 153 47 120 177 131 143 109 255 143 188 55 83 243 168 100 93 113 176 50 33 176 209 178 137 124 13 64 217 65 230 242 127 41 206 53 149 52 238 111 241 174 206 137 141 251 17 145 233 76 219 82 103 108 35 168 57 114 44 179 164 157 12 81 167 193 171 27 42 69 50 108 161 45 227 151 199 15 59 120 177 122 62 66 95 9 115 57 85 29 132 224 146 162 177 224 143 36 125 126 210 113 18 73 145 60 48 109 176 162 41 145 33 242 93 154 122 118 216 252 111 7 253 207 195 227 151 15 112 99 44 177 14 14 193 35 199 207 79 29 219 88 146 132 3 80 128 196 150 37 18 7 192 185 68 38 158 232 84 145 198 24 210 154 34 157 76 53 244 18 31 194 99 80 36 31 225 41 141 69 135 116 43 239 186 193 84 112 103 110 56 148 66 115 76 202 125 45 15 86 124 24 19 247 208 131 51 37 186 172 94 58 155 214 238 131 253 48 86 125 62 240 123 236 237 88 76 218 21 215 202 210 90 29 119 239 2 237 11 242 202 214 116 98 88 90 15 0 12 170 20 96 132 49 224 57 22 113 123 27 19 173 121 50 99 116 175 20 153 192 223 84 121 17 154 88 74 118 245 131 21 179 162 154 44 182 15 66 240 9 154 118 1 122 101 101 103 14 207 47 167 133 152 187 147 221 241 84 223 72 136 243 239 77 65 121 219 208 223 95 175 139 39 100 52 227 185 126 22 143 41 183 28 57 63 238 117 196 172 63 131 116 248 74 165 132 160 77 148 174 44 102 91 29 49 74 230 85 215 83 154 130 46 164 163 212 85 82 103 5 205 233 181 126 160 118 154 65 120 155 89 224 218 132 99 158 134 210 225 219 252 254 167 208 170 164 148 97 226 25 236 152 47 113 74 5 73 177 157 60 120 4 62 87 17 116 190 73 132 124 17 61 46 63 12 184 8 74 177 100 119 151 58 163 126 181 199 95 202 99 112 64 55 97 66 138 83 168 62 160 62 8 160 148 126 215 124 65 228 200 122 192 129 121 18 135 244 95 4 94 0 231 246 49 195 181 35 72 161 110 97 180 135 111 33 28 173 49 235 8 58 56 217 31 159 195 61 195 34 10 160 111 224 53 22 175 9 79 39 142 46 43 91 210 69 183 229 68 114 86 142 221 196 206 234 143 244 49 236 231 253 226 95 36 14 131 74 48 31 144 4 254 235 158 189 98 28 1 100 181 19 139 69 29 166 136 227 85 21 131 130 138 197 249 29 222 65 128 252 16 217 121 157 232 150 126 54 245 116 145 127 175 167 125 46 94 214 38 224 85 172 87 97 163 231 181 218 248 103 211 224 79 122 157 160 76 54 242 13 46 182 10 105 119 6 51 91 11 116 120 2 188 148 108 191 158 100 28 40 158 212 35 94 53 6 59 84 216 207 101 112 40 178 164 252 110 116 39 59 78 78 7 204 241 147 2 234 244 153 214 32 151 187 250 112 162 173 136 214 67 114 195 102 170 240 228 160 123 41 178 7 2 147 66 5 236 100 170 198 233 8 218 163 244 224 211 8 127 36 60 220 185 158 17 171 78 156 168 141 73 86 146 47 252 55 247 12 105 21 170 199 27 69 149 217 78 89 37 125 246 220 29 177 15 18 78 153 170 123 109 248 47 4 130 121 174 88 44 96 61 71 208 112 34 236 111 189 240 195 15 45 176 84 140 35 171 110 124 164 98 0 122 173 69 82 27 118 51 226 30 193 106 51 21 83 194 189 110 18 92 156 198 221 189 211 84 220 207]

Some of the fields in the private key blob follow: 

WK ID is [3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]
See 6.7.1 of page 182 of  http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Blob version is [18 52]
See 3.1.1 on page 141 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

IV is [145 242 100 209 252 135 97 118 108 26 68 196 204 214]

Encrypted part is [35 186 208 121 174 78 194 146 179 179 92 26 100 178 30 39 144 58 232 153 47 120 177 131 143 109 255 143 188 55 83 243 168 100 93 113 176 50 33 176 209 178 137 124 13 64 217 65 230 242 127 41 206 53 149 52 238 111 241 174 206 137 141 251 17 145 233 76 219 82 103 108 35 168 57 114 44 179 164 157 12 81 167 193 171 27 42 69 50 108 161 45 227 151 199 15 59 120 177 122 62 66 95 9 115 57 85 29 132 224 146 162 177 224 143 36 125 126 210 113 18 73 145 60 48 109 176 162 41 145 33 242 93 154 122 118 216 252 111 7 253 207 195 227 151 15 112 99 44 177 14 14 193 35 199 207 79 29 219 88 146 132 3 80 128 196 150 37 18 7 192 185 68 38 158 232 84 145 198 24 210 154 34 157 76 53 244 18 31 194 99 80 36 31 225 41 141 69 135 116 43 239 186 193 84 112 103 110 56 148 66 115 76 202 125 45 15 86 124 24 19 247 208 131 51 37 186 172 94 58 155 214 238 131 253 48 86 125 62 240 123 236 237 88 76 218 21 215 202 210 90 29 119 239 2 237 11 242 202 214 116 98 88 90 15 0 12 170 20 96 132 49 224 57 22 113 123 27 19 173 121 50 99 116 175 20 153 192 223 84 121 17 154 88 74 118 245 131 21 179 162 154 44 182 15 66 240 9 154 118 1 122 101 101 103 14 207 47 167 133 152 187 147 221 241 84 223 72 136 243 239 77 65 121 219 208 223 95 175 139 39 100 52 227 185 126 22 143 41 183 28 57 63 238 117 196 172 63 131 116 248 74 165 132 160 77 148 174 44 102 91 29 49 74 230 85 215 83 154 130 46 164 163 212 85 82 103 5 205 233 181 126 160 118 154 65 120 155 89 224 218 132 99 158 134 210 225 219 252 254 167 208 170 164 148 97 226 25 236 152 47 113 74 5 73 177 157 60 120 4 62 87 17 116 190 73 132 124 17 61 46 63 12 184 8 74 177 100 119 151 58 163 126 181 199 95 202 99 112 64 55 97 66 138 83 168 62 160 62 8 160 148 126 215 124 65 228 200 122 192 129 121 18 135 244 95 4 94 0 231 246 49 195 181 35 72 161 110 97 180 135 111 33 28 173 49 235 8 58 56 217 31 159 195 61 195 34 10 160 111 224 53 22 175 9 79 39 142 46 43 91 210 69 183 229 68 114 86 142 221 196 206 234 143 244 49 236 231 253 226 95 36 14 131 74 48 31 144 4 254 235 158 189 98 28 1 100 181 19 139 69 29 166 136 227 85 21 131 130 138 197 249 29 222 65 128 252 16 217 121 157 232 150 126 54 245 116 145 127 175 167 125 46 94 214 38 224 85 172 87 97 163 231 181 218 248 103 211 224 79 122 157 160 76 54 242 13 46 182 10 105 119 6 51 91 11 116 120 2 188 148 108 191 158 100 28 40 158 212 35 94 53 6 59 84 216 207 101 112 40 178 164 252 110 116 39 59 78 78 7 204 241 147 2 234 244 153 214 32 151 187 250 112 162 173 136 214 67 114 195 102 170 240 228 160 123 41 178 7 2 147 66 5 236 100 170 198 233 8 218 163 244 224 211 8 127 36 60 220 185 158 17 171 78 156 168 141 73 86 146 47 252 55 247 12 105 21 170 199 27 69 149 217 78 89 37 125 246 220 29 177 15 18 78 153 170 123 109 248 47 4 130 121 174 88 44 96 61 71 208 112 34 236 111 189 240 195 15 45 176 84 140 35 171]

MAC is [110 124 164 98 0 122 173 69 82 27 118 51 226 30 193 106 51 21 83 194 189 110 18 92 156 198 221 189 211 84 220 207]
MAC is 32 bytes, see field 15 in 3.1 on page 140 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

-----BEGIN HSM ENCRYPTED PRIVATE KEY-----
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADsIIxQY2Y9lWElrfi1CQo
AAAAAAAAASYAAAAAAAAAARI0kfJk0fyHYXZsGkTEzNYjutB5rk7CkrOzXBpksh4n
kDromS94sYOPbf+PvDdT86hkXXGwMiGw0bKJfA1A2UHm8n8pzjWVNO5v8a7OiY37
EZHpTNtSZ2wjqDlyLLOknQxRp8GrGypFMmyhLeOXxw87eLF6PkJfCXM5VR2E4JKi
seCPJH1+0nESSZE8MG2woimRIfJdmnp22PxvB/3Pw+OXD3BjLLEODsEjx89PHdtY
koQDUIDEliUSB8C5RCae6FSRxhjSmiKdTDX0Eh/CY1AkH+EpjUWHdCvvusFUcGdu
OJRCc0zKfS0PVnwYE/fQgzMluqxeOpvW7oP9MFZ9PvB77O1YTNoV18rSWh137wLt
C/LK1nRiWFoPAAyqFGCEMeA5FnF7GxOteTJjdK8UmcDfVHkRmlhKdvWDFbOimiy2
D0LwCZp2AXplZWcOzy+nhZi7k93xVN9IiPPvTUF529DfX6+LJ2Q047l+Fo8ptxw5
P+51xKw/g3T4SqWEoE2UrixmWx0xSuZV11Oagi6ko9RVUmcFzem1fqB2mkF4m1ng
2oRjnobS4dv8/qfQqqSUYeIZ7JgvcUoFSbGdPHgEPlcRdL5JhHwRPS4/DLgISrFk
d5c6o361x1/KY3BAN2FCilOoPqA+CKCUftd8QeTIesCBeRKH9F8EXgDn9jHDtSNI
oW5htIdvIRytMesIOjjZH5/DPcMiCqBv4DUWrwlPJ44uK1vSRbflRHJWjt3EzuqP
9DHs5/3iXyQOg0owH5AE/uuevWIcAWS1E4tFHaaI41UVg4KKxfkd3kGA/BDZeZ3o
ln429XSRf6+nfS5e1ibgVaxXYaPntdr4Z9PgT3qdoEw28g0utgppdwYzWwt0eAK8
lGy/nmQcKJ7UI141BjtU2M9lcCiypPxudCc7Tk4HzPGTAur0mdYgl7v6cKKtiNZD
csNmqvDkoHspsgcCk0IF7GSqxukI2qP04NMIfyQ83LmeEatOnKiNSVaSL/w39wxp
FarHG0WV2U5ZJX323B2xDxJOmap7bfgvBIJ5rlgsYD1H0HAi7G+98MMPLbBUjCOr
bnykYgB6rUVSG3Yz4h7BajMVU8K9bhJcnMbdvdNU3M8=
-----END HSM ENCRYPTED PRIVATE KEY-----

-----BEGIN PUBLIC KEY-----
MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQB+13F7gsCpQ4n1BuvTUFORvzd8sPs
owM/uEaekjMW5rUeTmUvloVkxWUfkDvAx+0OXlbtSTRPAS3cQTlxdXGt3EYAMIky
ko0W23qXRegKhB15xmzi6Ql1uRB97HHriDZ/beWWGnU/5/KeZfhWUBFFH9mceowe
S4SbuyOU7zFRrArStakEEAOwgjFBjZj2VYSWt+LUJCgEIAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAABAj/SEqDkqzquwQIAAAAAAAAAAEEFBABAAAAAYCA
AAGAgIABAAoAAAABBCDZXQuUiBg+iqjV9IO7UWtmcninRsGz6QQg5JCg6Kd9pw==
-----END PUBLIC KEY-----

Data signed
Signature verified

The first line of the output shows the Object ID of the curve that was used. These Object IDs are assigned by standards bodies. The Object ID used here is 1.3.132.0.35. Stick 1.3.132.0.35 in your favorite Google machine and see what you find. Or take my word for it that this identifies the secp521r1 curve.

The second line of the output shows ASN.1 BER encoding of 1.3.132.0.35, which is 6 5 43 129 4 0 35. If you were to look up how ASN.1 BER encoding works, your first question would be, "Why?". Don't go there now. But I bring it up because you will notice that a few lines down in the output, in the key pair public key blob section, you'll see that encoded string, 6 5 43 129 4 0 35, about 14 bytes from the beginning. In fact, while the whole point of using the GREP11 server and the Crypto Express 7S cards is to keep secrets from an adversary, the information shown in the key pair public key blob section is "in the clear"- you could give this to your adversary without fear of having your secrets compromised.

The list of decimal bytes of these keys is mostly gibberish to us humans, I'm not sure why I even bothered to print them out, but take a look at the output at the end, where there are several lines between a header and footer for HSM ENCRYPTED PRIVATE KEY (BEGIN and END), and several lines between a header and footer for a PUBLIC KEY.

To use these keys in the future, you would need to persist both of these to separate files. You wouldn't have a reason to give your adversary the HSM ENCRYPTED PRIVATE KEY, but, if he did obtain it, it would be of no value to him unless he was able to access your Crypto Express 7S card that had the same root wrapping key. The contents of this file are encrypted and are usuable only within the Crypto Express card that created it, or in another Crypto Express card that had the same root wrapping key.

Since the PUBLIC KEY is, by definition, shareable with the world, we can use the common openssl utility to look at it.

Try it like this:

Copy the lines from near the bottom of your output that have your public key , including the BEGIN PUBLIC KEY and END PUBLIC KEY header and footer lines, and the dashes, into your clipboard
In a terminal window, type echo " (that is a single pair of double-quotes) and then paste your clipboard contents onto the command line
Type " | openssl ec -in - -pubin -noout -text and then press Enter

You should see output similar to this:

read EC key
Public-Key: (521 bit)
pub:
    04:00:59:fe:0c:b3:d0:6e:b2:d7:b0:c0:05:86:66:
    dd:62:bc:fe:96:5c:fa:08:6d:f3:be:5f:6d:a1:3d:
    8f:40:13:83:23:ec:34:e4:e5:20:6c:f9:75:34:bd:
    30:cd:be:1f:5b:aa:ee:44:99:d9:ae:69:50:24:c7:
    82:7c:f4:f2:18:d1:b0:00:be:5c:64:f5:dd:16:79:
    eb:d4:9c:28:ae:43:9b:f4:13:a4:f3:db:3c:a2:e5:
    52:bb:0f:9f:e1:c4:a4:c1:29:63:4e:bc:2f:73:4c:
    da:fd:4f:42:63:0d:3d:9d:bb:29:76:57:85:13:57:
    3a:ae:8f:20:64:0a:cf:c2:f1:41:d3:fc:8a
ASN1 OID: secp521r1
NIST CURVE: P-521

Tip

If you are a Linux guru you could create a file with vi and copy the key into the file, and then provide that as input to the openssl command, e.g., openssl ec -in baz -pubin -noout -text if baz was the file you created.

In the exercise output I first printed the public key as an array of decimal numbers (worthless!), then I printed it in PEM-encoded format (boring!) but now you see the key in hexadecimal format (that's incredible!!). You also get the added bonus of knowing it's a legit public key since the openssl utility made sense of it.

Try using a different curve:

./lab --ex3 --curve P224

Example Output

selected curve P224 with ObjectID of 1.3.132.0.33
Curve ObjectID in ASN.1 BER encoding is [6 5 43 129 4 0 33]

Generated ECDSA PKCS key pair with mechanism  CKM_EC_KEY_PAIR_GEN

key pair public key blob length is 208 bytes

key pair public key blob is [48 78 48 16 6 7 42 134 72 206 61 2 1 6 5 43 129 4 0 33 3 58 0 4 177 164 170 83 241 4 140 49 236 115 12 22 130 206 48 90 174 181 135 16 59 31 11 122 14 254 13 172 129 64 249 1 40 44 231 155 52 110 38 67 175 244 45 81 157 5 213 125 224 199 126 65 251 200 159 53 4 16 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 4 32 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 8 6 63 231 63 240 230 179 88 4 8 0 0 0 0 0 0 0 1 4 20 16 1 0 0 0 1 128 128 0 1 128 128 128 1 0 10 0 0 0 1 4 32 90 61 58 127 30 244 119 154 65 27 170 14 182 232 45 237 92 61 188 238 138 237 84 7 5 209 228 172 195 235 219 189]

key pair private key blob length is 544 bytes

key pair private key blob is [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 1 38 0 0 0 0 0 0 0 1 18 52 1 7 210 186 20 15 180 182 68 217 17 251 23 142 218 85 206 228 75 16 37 108 9 47 216 5 160 29 100 235 78 164 63 25 232 181 251 214 113 69 26 198 9 222 119 149 66 64 233 183 172 93 96 41 223 99 201 110 138 227 51 26 197 166 9 8 190 40 129 254 49 89 54 38 209 21 60 137 118 113 174 145 254 145 152 119 73 114 11 144 41 25 106 152 140 167 192 88 82 199 100 234 18 255 129 213 111 25 126 2 200 3 44 90 252 84 48 191 106 98 2 77 78 7 165 189 227 52 167 78 188 5 185 254 178 206 180 171 47 110 54 38 87 16 191 167 134 237 48 49 153 168 54 225 251 75 223 3 55 239 48 119 76 89 103 20 30 222 104 167 219 210 46 17 75 224 196 191 55 238 236 156 205 119 182 199 12 58 144 248 124 216 181 38 11 17 139 144 123 31 108 76 171 91 154 112 6 160 188 2 181 110 212 46 66 153 211 21 184 1 51 194 12 245 73 155 192 206 80 213 51 187 166 3 207 127 151 127 59 158 192 7 92 113 247 118 108 55 217 84 183 34 24 144 57 215 193 96 179 93 2 190 84 85 119 199 179 96 119 2 9 160 231 251 214 187 5 206 224 207 111 52 58 181 131 237 11 245 106 181 223 217 240 98 162 190 11 116 18 46 225 218 17 130 79 19 4 171 94 129 197 59 201 54 63 31 60 90 84 225 223 121 94 173 42 103 3 204 128 187 143 209 78 80 151 157 90 44 76 20 254 18 96 197 70 36 135 24 13 156 77 112 196 22 35 123 199 169 17 195 156 0 212 50 140 50 126 70 132 126 149 172 94 173 49 156 173 207 208 109 166 88 148 204 25 122 119 58 130 215 130 101 13 235 96 29 210 130 229 51 232 250 206 124 162 68 112 3 191 129 184 195 34 186 72 103 159 228 155 244 43 108 205 37 82 176 243 200 233 88 91 31 243 33 232 44 178 19 57 182 239 63 238 130 33 1 127 250 215 109 121 187 134 218 173 74 112 88 230 152 90 147 20 43 28 254 173 28 25 255 0 147 78 51 231 175 190 29]

Some of the fields in the private key blob follow: 

WK ID is [3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]
See 6.7.1 of page 182 of  http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Blob version is [18 52]
See 3.1.1 on page 141 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

IV is [1 7 210 186 20 15 180 182 68 217 17 251 23 142]

Encrypted part is [218 85 206 228 75 16 37 108 9 47 216 5 160 29 100 235 78 164 63 25 232 181 251 214 113 69 26 198 9 222 119 149 66 64 233 183 172 93 96 41 223 99 201 110 138 227 51 26 197 166 9 8 190 40 129 254 49 89 54 38 209 21 60 137 118 113 174 145 254 145 152 119 73 114 11 144 41 25 106 152 140 167 192 88 82 199 100 234 18 255 129 213 111 25 126 2 200 3 44 90 252 84 48 191 106 98 2 77 78 7 165 189 227 52 167 78 188 5 185 254 178 206 180 171 47 110 54 38 87 16 191 167 134 237 48 49 153 168 54 225 251 75 223 3 55 239 48 119 76 89 103 20 30 222 104 167 219 210 46 17 75 224 196 191 55 238 236 156 205 119 182 199 12 58 144 248 124 216 181 38 11 17 139 144 123 31 108 76 171 91 154 112 6 160 188 2 181 110 212 46 66 153 211 21 184 1 51 194 12 245 73 155 192 206 80 213 51 187 166 3 207 127 151 127 59 158 192 7 92 113 247 118 108 55 217 84 183 34 24 144 57 215 193 96 179 93 2 190 84 85 119 199 179 96 119 2 9 160 231 251 214 187 5 206 224 207 111 52 58 181 131 237 11 245 106 181 223 217 240 98 162 190 11 116 18 46 225 218 17 130 79 19 4 171 94 129 197 59 201 54 63 31 60 90 84 225 223 121 94 173 42 103 3 204 128 187 143 209 78 80 151 157 90 44 76 20 254 18 96 197 70 36 135 24 13 156 77 112 196 22 35 123 199 169 17 195 156 0 212 50 140 50 126 70 132 126 149 172 94 173 49 156 173 207 208 109 166 88 148 204 25 122 119 58 130 215 130 101 13 235 96 29 210 130 229 51 232 250 206 124 162 68 112 3 191 129 184 195 34 186 72 103 159 228 155 244 43 108 205 37 82 176 243 200 233 88 91 31 243 33 232 44 178 19 57 182 239 63 238 130 33 1]

MAC is [127 250 215 109 121 187 134 218 173 74 112 88 230 152 90 147 20 43 28 254 173 28 25 255 0 147 78 51 231 175 190 29]
MAC is 32 bytes, see field 15 in 3.1 on page 140 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

-----BEGIN HSM ENCRYPTED PRIVATE KEY-----
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADsIIxQY2Y9lWElrfi1CQo
AAAAAAAAASYAAAAAAAAAARI0AQfSuhQPtLZE2RH7F47aVc7kSxAlbAkv2AWgHWTr
TqQ/Gei1+9ZxRRrGCd53lUJA6besXWAp32PJborjMxrFpgkIviiB/jFZNibRFTyJ
dnGukf6RmHdJcguQKRlqmIynwFhSx2TqEv+B1W8ZfgLIAyxa/FQwv2piAk1OB6W9
4zSnTrwFuf6yzrSrL242JlcQv6eG7TAxmag24ftL3wM37zB3TFlnFB7eaKfb0i4R
S+DEvzfu7JzNd7bHDDqQ+HzYtSYLEYuQex9sTKtbmnAGoLwCtW7ULkKZ0xW4ATPC
DPVJm8DOUNUzu6YDz3+XfzuewAdccfd2bDfZVLciGJA518Fgs10CvlRVd8ezYHcC
CaDn+9a7Bc7gz280OrWD7Qv1arXf2fBior4LdBIu4doRgk8TBKtegcU7yTY/Hzxa
VOHfeV6tKmcDzIC7j9FOUJedWixMFP4SYMVGJIcYDZxNcMQWI3vHqRHDnADUMowy
fkaEfpWsXq0xnK3P0G2mWJTMGXp3OoLXgmUN62Ad0oLlM+j6znyiRHADv4G4wyK6
SGef5Jv0K2zNJVKw88jpWFsf8yHoLLITObbvP+6CIQF/+tdtebuG2q1KcFjmmFqT
FCsc/q0cGf8Ak04z56++HQ==
-----END HSM ENCRYPTED PRIVATE KEY-----

-----BEGIN PUBLIC KEY-----
ME4wEAYHKoZIzj0CAQYFK4EEACEDOgAEsaSqU/EEjDHscwwWgs4wWq61hxA7Hwt6
Dv4NrIFA+QEoLOebNG4mQ6/0LVGdBdV94Md+QfvInzUEEAOwgjFBjZj2VYSWt+LU
JCgEIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAgGP+c/8OazWAQI
AAAAAAAAAAEEFBABAAAAAYCAAAGAgIABAAoAAAABBCBaPTp/HvR3mkEbqg626C3t
XD287ortVAcF0eSsw+vbvQ==
-----END PUBLIC KEY-----

Data signed
Signature verified

Try the P256 curve:

./lab --ex3 --curve P256

Example output

selected curve P256 with ObjectID of 1.2.840.10045.3.1.7
Curve ObjectID in ASN.1 BER encoding is [6 8 42 134 72 206 61 3 1 7]

Generated ECDSA PKCS key pair with mechanism  CKM_EC_KEY_PAIR_GEN

key pair public key blob length is 219 bytes

key pair public key blob is [48 89 48 19 6 7 42 134 72 206 61 2 1 6 8 42 134 72 206 61 3 1 7 3 66 0 4 110 106 106 221 176 75 119 181 154 179 115 108 192 148 127 80 203 20 154 165 194 20 40 117 94 117 223 125 118 133 226 230 18 128 20 46 239 61 241 136 41 9 78 202 124 188 192 93 181 229 245 210 78 187 156 152 192 132 255 162 17 51 187 117 4 16 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 4 32 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 8 203 203 135 115 66 126 231 150 4 8 0 0 0 0 0 0 0 1 4 20 16 1 0 0 0 1 128 128 0 1 128 128 128 1 0 10 0 0 0 1 4 32 117 106 180 43 131 151 71 204 222 211 38 32 214 138 208 98 235 7 172 87 236 205 51 122 54 65 64 58 70 89 127 218]

key pair private key blob length is 576 bytes

key pair private key blob is [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 1 38 0 0 0 0 0 0 0 1 18 52 234 153 96 242 234 92 129 26 151 136 72 248 23 66 196 52 4 170 78 111 124 89 151 169 22 232 12 154 65 246 71 238 229 101 98 135 230 50 24 66 130 82 190 65 48 151 138 8 183 43 229 56 95 235 90 163 68 81 9 77 56 28 104 192 150 105 31 193 133 24 224 125 104 86 165 104 162 87 247 209 66 173 168 45 232 4 229 134 211 133 24 229 196 10 32 90 129 146 138 115 39 163 206 102 141 49 142 143 55 114 160 210 56 132 237 137 157 136 203 0 20 217 144 233 140 198 26 179 60 218 95 201 29 214 100 144 55 226 195 23 83 105 50 175 174 214 216 130 2 71 17 191 197 26 180 89 147 168 61 236 49 230 64 190 217 199 13 244 173 182 255 91 144 51 231 177 252 232 210 156 130 70 14 30 129 255 82 247 162 116 213 100 248 100 190 125 48 3 168 85 249 192 75 26 221 95 113 27 1 123 130 248 176 164 140 61 141 190 157 241 193 100 2 180 163 73 141 252 213 35 213 158 95 46 85 0 94 159 101 16 31 97 109 63 64 35 238 255 208 175 121 180 84 162 66 210 119 10 131 119 187 27 116 152 2 41 62 175 176 244 123 70 42 51 244 113 238 102 113 195 54 242 80 148 90 145 226 10 180 122 94 143 119 125 187 118 7 28 184 214 205 205 97 18 71 235 186 245 199 246 57 3 208 121 40 73 6 28 64 217 154 216 108 59 46 158 80 133 8 196 11 223 201 199 234 77 99 219 238 244 6 254 96 55 5 88 109 181 57 85 82 64 67 46 13 114 56 74 117 215 61 161 26 37 221 210 18 229 131 11 232 38 101 190 54 241 253 217 100 80 205 45 113 51 237 105 252 159 11 126 74 152 22 138 45 30 188 157 151 101 139 134 16 221 153 56 216 167 210 214 79 150 96 170 83 161 118 219 162 45 113 179 106 87 147 99 222 42 122 194 24 249 53 210 222 206 2 74 232 110 135 6 12 110 53 2 15 144 180 185 58 249 41 54 36 128 61 116 221 158 154 95 142 32 213 89 48 209 47 155 239 2 142 171 218 207 130 140 18 125 86 224 20 5 4 83 108 163 82 243 62 254 77 103 87 90 32 112 50 169 54 139 200 219 92 84 191 177 139 94]

Some of the fields in the private key blob follow: 

WK ID is [3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]
See 6.7.1 of page 182 of  http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Blob version is [18 52]
See 3.1.1 on page 141 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

IV is [234 153 96 242 234 92 129 26 151 136 72 248 23 66]

Encrypted part is [196 52 4 170 78 111 124 89 151 169 22 232 12 154 65 246 71 238 229 101 98 135 230 50 24 66 130 82 190 65 48 151 138 8 183 43 229 56 95 235 90 163 68 81 9 77 56 28 104 192 150 105 31 193 133 24 224 125 104 86 165 104 162 87 247 209 66 173 168 45 232 4 229 134 211 133 24 229 196 10 32 90 129 146 138 115 39 163 206 102 141 49 142 143 55 114 160 210 56 132 237 137 157 136 203 0 20 217 144 233 140 198 26 179 60 218 95 201 29 214 100 144 55 226 195 23 83 105 50 175 174 214 216 130 2 71 17 191 197 26 180 89 147 168 61 236 49 230 64 190 217 199 13 244 173 182 255 91 144 51 231 177 252 232 210 156 130 70 14 30 129 255 82 247 162 116 213 100 248 100 190 125 48 3 168 85 249 192 75 26 221 95 113 27 1 123 130 248 176 164 140 61 141 190 157 241 193 100 2 180 163 73 141 252 213 35 213 158 95 46 85 0 94 159 101 16 31 97 109 63 64 35 238 255 208 175 121 180 84 162 66 210 119 10 131 119 187 27 116 152 2 41 62 175 176 244 123 70 42 51 244 113 238 102 113 195 54 242 80 148 90 145 226 10 180 122 94 143 119 125 187 118 7 28 184 214 205 205 97 18 71 235 186 245 199 246 57 3 208 121 40 73 6 28 64 217 154 216 108 59 46 158 80 133 8 196 11 223 201 199 234 77 99 219 238 244 6 254 96 55 5 88 109 181 57 85 82 64 67 46 13 114 56 74 117 215 61 161 26 37 221 210 18 229 131 11 232 38 101 190 54 241 253 217 100 80 205 45 113 51 237 105 252 159 11 126 74 152 22 138 45 30 188 157 151 101 139 134 16 221 153 56 216 167 210 214 79 150 96 170 83 161 118 219 162 45 113 179 106 87 147 99 222 42 122 194 24 249 53 210 222 206 2 74 232 110 135 6 12 110 53 2 15 144 180 185 58 249 41 54 36 128 61 116 221 158 154 95 142 32 213 89 48 209 47 155 239 2 142 171 218 207 130 140]

MAC is [18 125 86 224 20 5 4 83 108 163 82 243 62 254 77 103 87 90 32 112 50 169 54 139 200 219 92 84 191 177 139 94]
MAC is 32 bytes, see field 15 in 3.1 on page 140 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

-----BEGIN HSM ENCRYPTED PRIVATE KEY-----
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADsIIxQY2Y9lWElrfi1CQo
AAAAAAAAASYAAAAAAAAAARI06plg8upcgRqXiEj4F0LENASqTm98WZepFugMmkH2
R+7lZWKH5jIYQoJSvkEwl4oItyvlOF/rWqNEUQlNOBxowJZpH8GFGOB9aFalaKJX
99FCragt6ATlhtOFGOXECiBagZKKcyejzmaNMY6PN3Kg0jiE7YmdiMsAFNmQ6YzG
GrM82l/JHdZkkDfiwxdTaTKvrtbYggJHEb/FGrRZk6g97DHmQL7Zxw30rbb/W5Az
57H86NKcgkYOHoH/UveidNVk+GS+fTADqFX5wEsa3V9xGwF7gviwpIw9jb6d8cFk
ArSjSY381SPVnl8uVQBen2UQH2FtP0Aj7v/Qr3m0VKJC0ncKg3e7G3SYAik+r7D0
e0YqM/Rx7mZxwzbyUJRakeIKtHpej3d9u3YHHLjWzc1hEkfruvXH9jkD0HkoSQYc
QNma2Gw7Lp5QhQjEC9/Jx+pNY9vu9Ab+YDcFWG21OVVSQEMuDXI4SnXXPaEaJd3S
EuWDC+gmZb428f3ZZFDNLXEz7Wn8nwt+SpgWii0evJ2XZYuGEN2ZONin0tZPlmCq
U6F226ItcbNqV5Nj3ip6whj5NdLezgJK6G6HBgxuNQIPkLS5OvkpNiSAPXTdnppf
jiDVWTDRL5vvAo6r2s+CjBJ9VuAUBQRTbKNS8z7+TWdXWiBwMqk2i8jbXFS/sYte
-----END HSM ENCRYPTED PRIVATE KEY-----

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEbmpq3bBLd7Was3NswJR/UMsUmqXC
FCh1XnXffXaF4uYSgBQu7z3xiCkJTsp8vMBdteX10k67nJjAhP+iETO7dQQQA7CC
MUGNmPZVhJa34tQkKAQgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE
CMvLh3NCfueWBAgAAAAAAAAAAQQUEAEAAAABgIAAAYCAgAEACgAAAAEEIHVqtCuD
l0fM3tMmINaK0GLrB6xX7M0zejZBQDpGWX/a
-----END PUBLIC KEY-----

Data signed
Signature verified

Finally, try the fourth suupported curve, P384:

./lab --ex3 --curve P384

Example output

selected curve P384 with ObjectID of 1.3.132.0.34
Curve ObjectID in ASN.1 BER encoding is [6 5 43 129 4 0 34]

Generated ECDSA PKCS key pair with mechanism  CKM_EC_KEY_PAIR_GEN

key pair public key blob length is 248 bytes

key pair public key blob is [48 118 48 16 6 7 42 134 72 206 61 2 1 6 5 43 129 4 0 34 3 98 0 4 20 236 106 175 76 209 142 54 136 119 12 96 68 207 237 15 207 93 133 101 224 190 191 207 252 8 13 111 41 146 195 110 245 102 246 21 126 198 152 204 142 142 123 85 205 73 71 95 199 156 111 125 60 137 24 103 37 211 215 222 89 119 181 242 0 63 164 49 14 7 40 199 86 111 168 136 8 249 164 117 253 72 33 144 66 15 126 131 230 42 32 37 210 78 27 99 4 16 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 4 32 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 8 31 146 195 59 47 0 221 196 4 8 0 0 0 0 0 0 0 1 4 20 16 1 0 0 0 1 128 128 0 1 128 128 128 1 0 10 0 0 0 1 4 32 166 134 66 17 102 8 140 118 31 64 4 242 234 134 34 72 132 116 245 10 224 174 74 101 243 172 223 184 156 51 28 103]

key pair private key blob length is 720 bytes

key pair private key blob is [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 1 38 0 0 0 0 0 0 0 1 18 52 153 221 86 12 9 88 111 233 79 50 0 98 38 116 119 42 179 162 115 61 69 173 2 50 40 5 241 34 125 95 215 44 94 60 200 193 50 47 70 234 63 92 12 149 107 163 199 247 244 21 145 94 176 100 72 240 241 146 134 62 70 238 188 1 31 91 136 108 73 110 218 192 207 194 239 183 109 245 140 135 33 148 169 75 112 120 9 173 218 117 181 74 141 98 52 108 110 115 135 113 187 153 210 17 27 101 149 108 233 171 190 217 178 69 154 188 13 79 167 107 197 222 34 246 90 23 80 87 71 32 39 100 100 38 41 239 210 168 65 58 118 220 16 7 32 148 54 163 80 1 199 139 165 132 161 234 172 7 87 11 31 106 203 50 250 123 9 145 5 40 155 103 123 16 113 60 61 210 215 238 164 150 191 97 200 231 170 17 180 184 90 104 114 10 114 61 129 222 6 139 56 248 177 110 10 53 234 143 90 10 149 134 174 170 32 237 224 29 124 102 218 206 171 105 10 18 16 233 191 119 26 12 167 215 135 23 95 83 89 171 154 14 249 247 35 202 88 83 220 5 191 52 71 15 64 20 21 62 55 241 158 98 38 95 137 193 201 253 122 71 25 10 128 22 53 60 199 175 192 194 104 68 187 83 136 228 246 102 194 153 119 139 178 33 170 80 237 242 75 179 107 184 194 221 45 216 161 217 150 100 224 22 7 94 142 242 114 3 52 237 105 123 39 61 185 226 37 38 159 64 208 219 25 170 246 223 126 122 120 135 86 193 101 6 105 148 156 12 77 162 221 200 34 202 29 228 198 5 193 112 96 95 16 225 1 6 41 252 234 218 227 64 95 16 221 124 2 4 42 209 138 212 11 35 149 12 240 152 187 36 87 60 156 4 138 76 214 193 233 17 174 49 119 133 96 215 49 137 139 45 36 162 230 79 83 100 87 83 13 159 146 143 170 144 34 248 76 97 244 226 63 124 122 121 35 177 81 219 119 21 42 42 40 92 37 220 93 118 245 215 76 129 128 251 187 202 225 112 82 171 55 8 158 70 93 209 70 31 31 251 22 170 11 215 35 190 122 0 48 146 182 84 180 106 192 119 0 227 114 134 98 247 100 13 30 56 20 232 87 56 120 132 197 194 244 138 6 31 224 220 50 114 202 129 226 170 8 168 37 184 206 16 11 55 229 59 26 38 6 74 4 191 232 77 70 242 232 80 3 144 192 248 102 68 155 22 34 97 12 221 63 106 55 248 185 169 207 239 178 95 71 220 127 87 74 14 241 233 45 248 208 51 92 103 59 39 218 52 53 177 164 7 135 195 99 49 135 89 18 132 8 185 51 41 0 0 210 46 166 22 59 21 223 44 65 60 83 41 211 102 10 123 89 57 98 87 183 212 197 96 149 236 104 175 109 207 180 77 52 123 170 159 77 29 255 146 246 94 95 71 63 156 183 227 45 82 160 148 152 87 53 42 161 58]

Some of the fields in the private key blob follow: 

WK ID is [3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40]
See 6.7.1 of page 182 of  http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

Blob version is [18 52]
See 3.1.1 on page 141 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

IV is [153 221 86 12 9 88 111 233 79 50 0 98 38 116]

Encrypted part is [119 42 179 162 115 61 69 173 2 50 40 5 241 34 125 95 215 44 94 60 200 193 50 47 70 234 63 92 12 149 107 163 199 247 244 21 145 94 176 100 72 240 241 146 134 62 70 238 188 1 31 91 136 108 73 110 218 192 207 194 239 183 109 245 140 135 33 148 169 75 112 120 9 173 218 117 181 74 141 98 52 108 110 115 135 113 187 153 210 17 27 101 149 108 233 171 190 217 178 69 154 188 13 79 167 107 197 222 34 246 90 23 80 87 71 32 39 100 100 38 41 239 210 168 65 58 118 220 16 7 32 148 54 163 80 1 199 139 165 132 161 234 172 7 87 11 31 106 203 50 250 123 9 145 5 40 155 103 123 16 113 60 61 210 215 238 164 150 191 97 200 231 170 17 180 184 90 104 114 10 114 61 129 222 6 139 56 248 177 110 10 53 234 143 90 10 149 134 174 170 32 237 224 29 124 102 218 206 171 105 10 18 16 233 191 119 26 12 167 215 135 23 95 83 89 171 154 14 249 247 35 202 88 83 220 5 191 52 71 15 64 20 21 62 55 241 158 98 38 95 137 193 201 253 122 71 25 10 128 22 53 60 199 175 192 194 104 68 187 83 136 228 246 102 194 153 119 139 178 33 170 80 237 242 75 179 107 184 194 221 45 216 161 217 150 100 224 22 7 94 142 242 114 3 52 237 105 123 39 61 185 226 37 38 159 64 208 219 25 170 246 223 126 122 120 135 86 193 101 6 105 148 156 12 77 162 221 200 34 202 29 228 198 5 193 112 96 95 16 225 1 6 41 252 234 218 227 64 95 16 221 124 2 4 42 209 138 212 11 35 149 12 240 152 187 36 87 60 156 4 138 76 214 193 233 17 174 49 119 133 96 215 49 137 139 45 36 162 230 79 83 100 87 83 13 159 146 143 170 144 34 248 76 97 244 226 63 124 122 121 35 177 81 219 119 21 42 42 40 92 37 220 93 118 245 215 76 129 128 251 187 202 225 112 82 171 55 8 158 70 93 209 70 31 31 251 22 170 11 215 35 190 122 0 48 146 182 84 180 106 192 119 0 227 114 134 98 247 100 13 30 56 20 232 87 56 120 132 197 194 244 138 6 31 224 220 50 114 202 129 226 170 8 168 37 184 206 16 11 55 229 59 26 38 6 74 4 191 232 77 70 242 232 80 3 144 192 248 102 68 155 22 34 97 12 221 63 106 55 248 185 169 207 239 178 95 71 220 127 87 74 14 241 233 45 248 208 51 92 103 59 39 218 52 53 177 164 7 135 195 99 49 135 89 18 132 8 185 51 41 0 0 210 46 166 22 59 21 223 44 65 60 83 41 211 102 10 123 89 57 98 87 183 212 197 96 149 236]

MAC is [104 175 109 207 180 77 52 123 170 159 77 29 255 146 246 94 95 71 63 156 183 227 45 82 160 148 152 87 53 42 161 58]
MAC is 32 bytes, see field 15 in 3.1 on page 140 of http://public.dhe.ibm.com/security/cryptocards/pciecc4/EP11/docs/ep11-structure.pdf

-----BEGIN HSM ENCRYPTED PRIVATE KEY-----
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADsIIxQY2Y9lWElrfi1CQo
AAAAAAAAASYAAAAAAAAAARI0md1WDAlYb+lPMgBiJnR3KrOicz1FrQIyKAXxIn1f
1yxePMjBMi9G6j9cDJVro8f39BWRXrBkSPDxkoY+Ru68AR9biGxJbtrAz8Lvt231
jIchlKlLcHgJrdp1tUqNYjRsbnOHcbuZ0hEbZZVs6au+2bJFmrwNT6drxd4i9loX
UFdHICdkZCYp79KoQTp23BAHIJQ2o1ABx4ulhKHqrAdXCx9qyzL6ewmRBSibZ3sQ
cTw90tfupJa/YcjnqhG0uFpocgpyPYHeBos4+LFuCjXqj1oKlYauqiDt4B18ZtrO
q2kKEhDpv3caDKfXhxdfU1mrmg759yPKWFPcBb80Rw9AFBU+N/GeYiZficHJ/XpH
GQqAFjU8x6/AwmhEu1OI5PZmwpl3i7IhqlDt8kuza7jC3S3YodmWZOAWB16O8nID
NO1peyc9ueIlJp9A0NsZqvbffnp4h1bBZQZplJwMTaLdyCLKHeTGBcFwYF8Q4QEG
Kfzq2uNAXxDdfAIEKtGK1AsjlQzwmLskVzycBIpM1sHpEa4xd4Vg1zGJiy0kouZP
U2RXUw2fko+qkCL4TGH04j98enkjsVHbdxUqKihcJdxddvXXTIGA+7vK4XBSqzcI
nkZd0UYfH/sWqgvXI756ADCStlS0asB3AONyhmL3ZA0eOBToVzh4hMXC9IoGH+Dc
MnLKgeKqCKgluM4QCzflOxomBkoEv+hNRvLoUAOQwPhmRJsWImEM3T9qN/i5qc/v
sl9H3H9XSg7x6S340DNcZzsn2jQ1saQHh8NjMYdZEoQIuTMpAADSLqYWOxXfLEE8
UynTZgp7WTliV7fUxWCV7Givbc+0TTR7qp9NHf+S9l5fRz+ct+MtUqCUmFc1KqE6
-----END HSM ENCRYPTED PRIVATE KEY-----

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEFOxqr0zRjjaIdwxgRM/tD89dhWXgvr/P
/AgNbymSw271ZvYVfsaYzI6Oe1XNSUdfx5xvfTyJGGcl09feWXe18gA/pDEOByjH
Vm+oiAj5pHX9SCGQQg9+g+YqICXSThtjBBADsIIxQY2Y9lWElrfi1CQoBCAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQIH5LDOy8A3cQECAAAAAAAAAAB
BBQQAQAAAAGAgAABgICAAQAKAAAAAQQgpoZCEWYIjHYfQATy6oYiSIR09Qrgrkpl
86zfuJwzHGc=
-----END PUBLIC KEY-----

Data signed
Signature verified

Each of the curves had a number in its name that indicates how large the key is, in bits. We worked with 224-, 256-, 384-, and 521-bit keys (yes that is 521 bits and not 512 bits but don't ask me why- I first have to get smart enough to understand it myself before I get smart enough to explain it to you coherently- besides, I'm sure Google has the answer). I am smart enough to know that there are 8 bits in a byte and while the key lengths in cryptographic algorithms are usually expressed in bits, the lengths in our exercise output for the various blobs are expressed in bytes. And there's nothing wrong with that, because our key blobs have lots of other metadata and attributes and fields besides just the key itself. That's why I purposely referred to them as key blobs and not keys.

Try this handy "one-line script" that runs this exercise four times, once for each curve, and then pipes the output to egrep so that we can pick out some lines of interest. You can see how the curve strength impacts the size of the public and private key blobs:
```
 for curve in P224 P256 P384 P521 ; do  ./lab --ex3 --curve ${curve} ; done | egrep -ie 'curve|key blob length'
```
Expected Output
```
selected curve P224 with ObjectID of 1.3.132.0.33
Curve ObjectID in ASN.1 BER encoding is [6 5 43 129 4 0 33]
key pair public key blob length is 208 bytes
key pair private key blob length is 544 bytes
selected curve P256 with ObjectID of 1.2.840.10045.3.1.7
Curve ObjectID in ASN.1 BER encoding is [6 8 42 134 72 206 61 3 1 7]
key pair public key blob length is 219 bytes
key pair private key blob length is 576 bytes
selected curve P384 with ObjectID of 1.3.132.0.34
Curve ObjectID in ASN.1 BER encoding is [6 5 43 129 4 0 34]
key pair public key blob length is 248 bytes
key pair private key blob length is 720 bytes
selected curve P521 with ObjectID of 1.3.132.0.35
Curve ObjectID in ASN.1 BER encoding is [6 5 43 129 4 0 35]
key pair public key blob length is 286 bytes
key pair private key blob length is 896 bytes
```
It makes sense that the larger key sizes produce bigger key blobs. If I ever figure out enough to give a full accounting of the difference in blob sizes, I'll update the lab. If you ever figure it out, please create a GitHub pull request with the answer.

Let's move on to our fourth and final exercise.

Exercise 4 - Wrap and Unwrap a Key¶

Overview of Exercise 4¶

Data that is not encrypted is referred to as plaintext. Data that is encrypted is referred to as ciphertext.

Whether this data is human readable text, like this sentence, or binary data (like a lot of the output in our exercises!), or whatever, is usually of little concern to encryption and decryption algorithms. The input is just a bunch of bits- either 1 or 0.

Keys themselves are just a bunch of bits- 1's and 0's. Can you encrypt and decrypt keys with other keys? You sure can. There's nothing magical about that. But, like all disciplines, cryptographers have special terms for encrypting and decrypting keys- they use the term wrapping a key to refer to encrypting a key, and unwrapping a key refers to decrypting a key. There are valid reasons to make the distinction- for example, the PKCS #11 standard allows you to assign attributes to keys, and you can create keys such that they can or cannot wrap or unwrap keys, and you may wish to create different keys for different purposes. In fact, it is considered best practice to not use the same key to encrypt both data and keys, so using different terminology- encrypting data versus wrapping keys allows for easier separation of duties and may make key management easier.

In this exercise, the following use case will be demonstrated- securely transmitting a secret key so that both parties have the same secret key and can use it for encryption during a session:

Sender wishes to send a secret (i.e., symmetric) key to a recipient.
Sender generates a secret key and wraps it with the recipient's public key
Sender sends the wrapped key to the recipient- this is safe since it is wrapped with the recipient's public key
Recipient receives the wrapped key, and unwraps it with her private key

Run Exercise 4¶

Run the fourth exercise:

./lab --ex4

Example Output

Generated AES key
Generated PKCS RSA key pair

the AES key prior to being wrapped is:
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 141 37 0 0 0 0 0 0 0 1 18 52 228 123 210 48 148 72 67 55 62 73 210 121 66 247 116 178 245 24 106 221 115 156 71 47 218 46 103 246 124 74 119 150 39 244 103 45 22 196 216 35 98 215 63 143 111 10 217 35 1 34 26 127 84 98 120 216 45 88 92 129 231 135 244 57 118 125 8 141 119 168 29 141 122 29 224 59 1 244 174 182 103 220 131 195 114 27 143 94 112 118 185 49 140 147 51 10 26 16 150 95 130 1 239 21 212 148 246 182 10 159 243 69 233 30 202 254 52 241 146 79 66 44 9 199 32 56 113 169 227 133 51 177 98 204 240 57 244 188 254 99 38 243 227 153 119 170 28 38 109 86 197 175 193 64 255 113 106 40 94 90 204 5 241 135 72 79 76 42 166 180 59 93 91 62 94 248 153 138 201 11 2 155 224 41 66 230 89 253 94 74]

the checksum of the AES key is: [147 241 235]

the AES key has been wrapped with a PKCS RSA Public Key
The AES key has been unwrapped with the PKCS Private Key corresponding to the PKCS Public Key we used to wrap it with.

the AES key after being wrapped and unwrapped is:
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 12 0 0 0 0 0 0 0 0 1 18 52 206 249 87 66 227 239 81 119 120 21 113 29 123 27 2 52 241 6 31 39 195 183 118 39 98 185 255 179 31 44 217 72 38 56 126 190 23 230 112 120 180 74 27 118 70 9 145 247 109 197 15 92 126 232 161 192 140 63 241 178 29 188 70 79 29 240 6 39 76 22 244 149 99 241 220 160 157 40 58 42 255 121 3 181 9 118 15 96 170 49 208 117 127 248 187 202 226 92 76 198 142 164 39 85 247 74 203 28 50 106 162 144 217 93 110 120 157 126 106 37 202 133 10 133 162 89 201 186 210 12 93 124 74 231 120 172 149 134 196 232 247 5 228 92 146 119 245 115 107 124 153 218 87 65 119 80 131 101 53 219 210 111 107 216 117 6 45 153 176 221 49 121 208 77 164 68 230 219 190 45 238 82 201 112 126 205 97 110 201 187 28 240 134 33 223 206 209 45 207 159 132 178 222 232 63 160]

the checksum of the unwrapped AES key is: [147 241 235 0 0 1 0]

I mentioned in the overview of this exercise that you can assign attributes to keys when you create them. The code for this exercise, by default, assigns an attribute that allows the public key it creates to wrap keys, and it assigns an attribute to the private key to allow it to unwrap keys.

Run this command which will cause the program to set the applicable attribute for the private key such that it is not allowed to unwrap a key. Observe in the output that, while the wrap operation proceeds, the unwrap fails:

./lab --ex4 --unwrap=false

Example output

Generated AES key
Generated PKCS RSA key pair

the AES key prior to being wrapped is:
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 141 37 0 0 0 0 0 0 0 1 18 52 120 27 243 16 225 139 153 149 120 188 137 72 50 120 131 243 65 98 62 77 65 60 178 184 93 56 192 2 202 179 211 210 240 252 246 171 56 100 172 203 61 233 216 102 186 60 207 208 1 173 188 223 4 45 199 93 159 251 80 32 171 131 10 228 235 131 98 191 70 58 116 218 179 225 62 235 136 76 246 39 55 21 247 126 181 47 3 130 64 70 198 91 136 21 133 177 138 190 118 139 183 195 32 110 107 230 101 253 127 40 171 124 1 146 32 138 11 148 175 180 54 21 123 51 144 234 167 228 218 128 47 74 26 203 250 95 110 208 47 245 229 198 164 121 76 226 138 122 31 168 169 251 74 149 174 62 88 86 122 204 149 195 200 41 139 250 0 242 226 34 193 78 32 151 250 220 249 249 106 106 231 217 34 139 118 29 206 140 217 75]

the checksum of the AES key is: [79 136 190]

the AES key has been wrapped with a PKCS RSA Public Key
panic: Unwrap AES key error: rpc error: code = Unknown desc = CKR_KEY_FUNCTION_NOT_PERMITTED

goroutine 1 [running]:
main.wrapAndUnwrapKey(0xc420030001)
        /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/exercise4.go:110 +0x1543
main.main()
        /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/main.go:79 +0x35e

This command will cause the public key to be created without the ability to wrap a key. The command will fail when trying to wrap the key:

./lab --ex4 --wrap=false

Example output

Generated AES key
Generated PKCS RSA key pair

the AES key prior to being wrapped is:
[0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 176 130 49 65 141 152 246 85 132 150 183 226 212 36 40 0 0 0 0 0 0 141 37 0 0 0 0 0 0 0 1 18 52 94 240 28 56 111 164 179 172 71 8 202 169 163 165 249 244 192 122 26 215 148 231 8 62 1 127 152 148 45 31 45 189 172 0 97 131 35 17 231 104 88 103 196 2 96 167 213 198 9 62 10 241 154 128 94 206 4 229 36 89 125 38 231 94 155 212 43 90 44 253 221 170 164 83 13 228 232 156 205 205 183 65 252 45 183 191 75 243 56 130 64 170 140 197 150 91 224 229 88 47 185 97 138 145 93 241 181 206 4 141 225 214 249 62 21 4 83 105 12 209 109 187 124 171 112 222 107 44 203 204 240 23 236 60 27 190 248 201 189 3 112 89 163 28 91 254 220 95 74 11 247 137 54 107 93 106 21 199 166 152 208 200 151 220 233 4 125 105 139 235 83 211 121 166 15 209 229 173 92 2 74 50 107 41 73 150 197 116 162 37]

the checksum of the AES key is: [229 2 226]

panic: Wrap AES key error: rpc error: code = Unknown desc = CKR_KEY_FUNCTION_NOT_PERMITTED

goroutine 1 [running]:
main.wrapAndUnwrapKey(0xc420030100)
        /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/exercise4.go:90 +0x1553
main.main()
        /home/hyper-protect-lab/go/src/github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/lab/main.go:79 +0x35e

Note

The public key has been prevented from wrapping a key, but it could still be used to encrypt data.

Congratulations for reaching the end of the lab!

We hope you have gotten a taste of the functionality offered by the Crypto Express cards and made accessible to you via the GREP11 server feature of Hyper Protect Virtual Servers. And if you know a bit more about security after doing this lab than you did before, we're pleased about that!

We welome your suggestions for improvements or enhancements to the lab.

Please do not forget to take your survey for the Webinar and your survey about your Workshop Manager/SkyTap experience. Here is the link for the Workshop Manager/SkyTap survey: Workshop Manager survey

Ended: Run the Lab exercises

Ended: GREP11 Lab

Secure Image Build Lab ↵

Prerequisites¶

Create a GitHub account¶

You will need to have a GitHub account in order to complete this lab. If you do not already have one, you can create a free account here.

Create a Docker account¶

Create a Docker account (if you don't already have one) following the instructions here.

Create a Docker access token¶

Create an access token for Docker Hub access during the lab (you will delete it after finishing the lab) following the instructions here. If you already have a Docker account and already have a Docker access token, we recommend that you create a new access token just for this lab instead of using any existing ones.

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:

SETUP
BUILD
REGISTER
DEPLOY
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 below¹:

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. ²

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	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	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.	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 validity³ (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 enclave⁴ (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).

The Secure Build Experience graphic is adapted from charts provided by the Hyper Protect Virtual Servers On-Premises development team. ↩
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. ↩
The Image Registration Experience graphic is adapted from charts provided by the Hyper Protect Virtual Servers On-Premises development team. ↩
The Hyper Protect Virtual Server Experience graphic is adapted from charts provided by the Hyper Protect Virtual Servers On-Premises development team. ↩

Configuring your Environment¶

Explore the Hyper Protect Virtual Servers command line interface (CLI)¶

Info

In this lab, we will use the Hyper Protect Virtual Servers CLI (hpvs command) to interact with our Hyper Protect Virtual Servers Hosting Appliance in order to perform the various actions necessary for the Secure Build. Below is a quick introduction to the commands available through this CLI.

See the different commands you could enter with:

hpvs --help

Example Output

IBM® Hyper Protect Virtual Servers, the evolution of the
IBM® Secure Service Container for IBM® Cloud Private offering,
protects Linux workloads on IBM Z and LinuxONE throughout their
lifecycle build management and deployment.
This solution delivers the security needed to protect
mission critical applications in hybrid multi-cloud deployments.

Usage:
hpvs [command]

Available Commands:
completion  generate the autocompletion script for the specified shell
crypto      Crypto command
deploy      Deploy command
help        Help about any command
host        Host command
image       Image Command
network     Network command
quotagroup  Quotagroup command
regfile     Generate encrypted repository registration file. If you have already image build on s390x arch
registry    Registry command
repository  Repository command
sb          SecureBuild command
snapshot    Snapshot command
undeploy    Undeploy command
version     Print hpvs version
vs          Virtual Server command

Flags:
    --debug                   If --debug is passed, it will enable debug logs
-h, --help                    Help for hpvs
    --log-output-dir string   Set log output directory

Use "hpvs [command] --help" for more information about a command.

See more information for the Available Commands listed above with:

completioncryptodeployhelphostimagenetworkquotagroupregfileregistryrepositorysbsnapshotundeployversionvs

hpvs completion --help

Example Output

Generate the autocompletion script for hpvs for the specified shell.
See each sub-command's help for details on how to use the generated script.

Usage:
hpvs completion [command]

Available Commands:
bash        generate the autocompletion script for bash
fish        generate the autocompletion script for fish
powershell  generate the autocompletion script for powershell
zsh         generate the autocompletion script for zsh

Flags:
-h, --help   help for completion

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs completion [command] --help" for more information about a command.

hpvs crypto --help

Example Output

List crypto

Usage:
hpvs crypto [command]

Available Commands:
list        List crypto

Flags:
-h, --help          Help for crypto
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs crypto [command] --help" for more information about a command.

hpvs deploy --help

Example Output

Deploy virtual servers

Usage:
hpvs deploy [flags]

Flags:
    --config string         YAML configuration file for the virtual server deployment
    --exclude strings       Virtual servers e.g vs1,vs2; to be excluded from
                            deploying, other vs will be included for deployment, by default all
                            vs will be deployed
-h, --help                  help for deploy
    --include strings       Virtual servers e.g vs1,vs2; to be included for
                            deploying, other vs will be excluded from deployment by default all
                            vs will be deployed
    --templatefile string   YAML resource template file for the virtual server deployment
-u, --update                If -u is passed virtual server deployment setup gets updated

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

hpvs help --help

Example Output

Help provides help for any command in the application.
Simply type hpvs help [path to command] for full details.

Usage:
hpvs help [command] [flags]

Flags:
-h, --help   help for help

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

hpvs host --help

Example Output

add, delete, update, list, unset, show, set Host

Usage:
hpvs host [command]

Available Commands:
add         Add host
delete      Delete host
list        List host
set         Set host
show        Show host
unset       Unset host
update      Update host

Flags:
-h, --help   Help for host

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs host [command] --help" for more information about a command.

hpvs image --help

Example Output

list, delete, show, load, pull Image

Usage:
hpvs image [command]

Available Commands:
delete      Delete image
list        List image
load        Upload image
pull        Pull image
show        Show image

Flags:
-h, --help          Help for image
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs image [command] --help" for more information about a command.

hpvs network --help

Example Output

list, create, update, delete, show Network

Usage:
hpvs network [command]

Available Commands:
create      Create network
delete      Delete network
list        List network
show        Show network
update      Update network

Flags:
-h, --help          Help for network
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs network [command] --help" for more information about a command.

hpvs quotagroup --help

Example Output

create, delete, list, show, update Quotagroup

Usage:
hpvs quotagroup [command]

Available Commands:
create      Create quotagroup
delete      Delete quotagroup
list        List quotagroup
show        Show quotagroup
update      Update quotagroup

Flags:
-h, --help          Help for quotagroup
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs quotagroup [command] --help" for more information about a command.

hpvs regfile --help

Example Output

Generate encrypted repository registration file. If you have already image build on s390x arch

Usage:
hpvs regfile [command]

Available Commands:
create      Create encrypted repository registration file

Flags:
-h, --help   Help for regfile

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs regfile [command] --help" for more information about a command.

hpvs registry --help

Example Output

add, delete, update, list, show Registry

Usage:
hpvs registry [command]

Available Commands:
add         Add registry
delete      Delete registry
list        List registry
show        Show registry
update      Update registry

Flags:
-h, --help   Help for registry
    --json   if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs registry [command] --help" for more information about a command.

hpvs repository --help

Example Output

list, register, delete, show, update Repository

Usage:
hpvs repository [command]

Available Commands:
delete      Delete repository
list        List repository
register    Register repository
show        Show repository
update      Update repository

Flags:
-h, --help          Help for repository
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs repository [command] --help" for more information about a command.

hpvs sb --help

Example Output

SecureBuild command

Usage:
hpvs sb [command]

Available Commands:
build       Securely build your image
clean       Secure build clean. It will clean vs data eg - logs
init        Initialize secure build configuration
log         Get logs
manifest    Get manifest file
pubkey      Get manifest public key
regfile     Get encrypted repository registration file
status      Get secure build status
update      Update secure build environment

Flags:
-h, --help   Help for sb

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs sb [command] --help" for more information about a command.

hpvs snapshot --help

Example Output

list, create, delete, restore Snapshot

Usage:
hpvs snapshot [command]

Available Commands:
create      Create snapshot
delete      Delete snapshot
list        List snapshots
restore     Restore snapshot

Flags:
-h, --help          Help for snapshot
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs snapshot [command] --help" for more information about a command.

hpvs undeploy --help

Example Output

Undeploy virtual servers

Usage:
hpvs undeploy [flags]

Flags:
    --config string     YAML configuration file used for the virtual server deployment
    --exclude strings   Virtual servers e.g vs1,vs2; to be excluded from
                        undeploying, other vs will be included for undeployment, by default all
                        vs will be undeployed
-h, --help              help for undeploy
    --include strings   Virtual servers e.g vs1,vs2; to be included for
                        undeploying, other vs will be excluded from undeployment by default all
                        vs will be undeployed

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

hpvs version --help

Example Output

Print hpvs version

Usage:
hpvs version [flags]

Flags:
-h, --help   Help for version

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

hpvs vs --help

Example Output

create, delete, list, log, restart, show, start, stop VS

Usage:
hpvs vs [command]

Available Commands:
create      Create virtual server
delete      Delete virtual server
list        List virtual servers
log         Get virtual server log
restart     Restart virtual server
show        Show virtual server
start       Start virtual server
stop        Stop virtual server
update      Update virtual server

Flags:
-h, --help          Help for vs
    --host string   Host LPAR name
    --json          if --json flag is passed , the output will be in json format

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

Use "hpvs vs [command] --help" for more information about a command.

You can even dive into the Available Commands of the above commands with another --help

hpvs sb build --help

Example Output

Securely build your image

Usage:
hpvs sb build [flags]

Flags:
    --config string   Config file path
-h, --help            Help for build
    --timeout int     Build timeout in minutes (default 10)

Global Flags:
    --debug                   If --debug is passed, it will enable debug logs
    --log-output-dir string   Set log output directory

For further exploration of the Hyper Protect Virtual Servers CLI see the Knowledge Center

Add Docker registry to use for secure build¶

Info

In this section you will add the details to connect to your Docker Hub Registry so your secure build container can push your securely built images there. Don't worry, your Docker token is safely encrypted on your Skytap Linux VM using the HPVS Registry CLI Encryption Key referenced in the key table.

See your current Docker registries with:

hpvs registry list

Example Output

+---------------+
| REGISTRY NAME |
+---------------+
+---------------+

Set your DOCKER_USERNAME to the username for your account on Docker Hub
Command SyntaxExample Command
export DOCKER_USERNAME="my_username"
export DOCKER_USERNAME="gmoney23"
Note

This will be the username you used when you created your Docker Hub account in the Prerequisites

Save your DOCKER_USERNAME to bashrc for later use.

echo "export DOCKER_USERNAME='${DOCKER_USERNAME}'" >> "${HOME}/.bashrc"

Set your DOCKER_PASSWORD to the token you created for this lab on Docker Hub.
Command SyntaxExample Command
export DOCKER_PASSWORD="my_docker_token"
export DOCKER_PASSWORD="123456789"
Note

This will be the Docker Hub token you created for the lab in the Prerequisites

Check your Docker Hub login credentials with a docker login and do a docker logout to remove unencrypted Docker credentials locally.

echo "${DOCKER_PASSWORD}" | docker login -u ${DOCKER_USERNAME} --password-stdin && docker logout

Successful login

WARNING! Your password will be stored unencrypted in /home/hyper-protect-lab/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded
Removing login credentials for https://index.docker.io/v1/

Failed Login

Please redo this section

Error response from daemon: Get https://registry-1.docker.io/v2/: unauthorized: incorrect username or password

Set your REGISTRY_NAME to a Docker registry placeholder name of your choosing.
Command SyntaxExample Command
export REGISTRY_NAME="my_registry"
export REGISTRY_NAME="g_docker_hub"
Save your REGISTRY_NAME to bashrc for future shells (in case you open new terminals)
```
echo "export REGISTRY_NAME='${REGISTRY_NAME}'" >> "${HOME}/.bashrc"
```
Add your Docker registry with:
```
echo "${DOCKER_PASSWORD}" | hpvs registry add \
--name "${REGISTRY_NAME}" --dct https://notary.docker.io \
--url docker.io --user "${DOCKER_USERNAME}"
```
Example Output
```
Enter Password:
```
Note

You can ignore the Enter Password: prompt because the command does that for you with the echo "${DOCKER_PASSWORD}" | before the hpvs registry add command.

List your registered Docker registries again to confirm your registry has been added.

hpvs registry list

Example Output

+---------------+
| REGISTRY NAME |
+---------------+
| g_docker_hub  |
+---------------+

Check the details of your added registry with

hpvs registry show --name "${REGISTRY_NAME}"

Example Output

+------+--------------------------+
| name | g_docker_hub             |
| user | gmoney23                 |
| dct  | https://notary.docker.io |
| url  | docker.io                |
+------+--------------------------+

Create directory for secure build lab and change directory¶

Set your secure build directory
```
export SB_DIR="$HOME/securebuild-lab"
```
Save SB_DIR to $HOME/.bashrc for future shells (in case you open new terminals)
```
echo "export SB_DIR='${SB_DIR}'" >> "${HOME}/.bashrc"
```
Create SB_DIR and change into it
```
mkdir -p "${SB_DIR}" && cd "${SB_DIR}"
```

Create SSH Key and Grant GitHub access¶

Info

This section goes through adding the GitHub SSH Key referenced in the key table to your GitHub account to enable cloning GitHub repositories via SSH for secure builds.

Create GitHub keys directory
```
mkdir -p "${SB_DIR}/github_keys"
```

Set GITHUB_SSH_KEY variable

export GITHUB_SSH_KEY="${SB_DIR}/github_keys/github_rsa"

Save GITHUB_SSH_KEY variable in bashrc for later use

echo "export GITHUB_SSH_KEY='${GITHUB_SSH_KEY}'" >> "${HOME}/.bashrc"

Create public and private key for GitHub access

ssh-keygen -t rsa -b 4096 -f "${GITHUB_SSH_KEY}" -N ''

Example Output

Generating public/private rsa key pair.
Your identification has been saved in /home/multiarch-lab/securebuild-lab/github_keys/github_rsa.
Your public key has been saved in /home/multiarch-lab/securebuild-lab/github_keys/github_rsa.pub.
The key fingerprint is:
SHA256:sbEfCzwyOz/LaZ4jSeKT+Aw7IWUr7YT6m8Hxv9Dq90k multiarch-lab@ubuntu
The key's randomart image is:
+---[RSA 4096]----+
|                 |
|                 |
|        o        |
|  o    . =       |
| =..  o S .      |
|+.=o...+ + o     |
|.=++o++.E o      |
|. +*+++=++       |
| .===oo*X+       |
+----[SHA256]-----+

Cat GitHub public key to terminal

cat "${GITHUB_SSH_KEY}.pub"

Example Output

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC6zsnjH4fXaR/imYkzRaYVgWsNVIY4LzCftygKGTFJVBDMqVErsbkvF810RUTPIIowwe7Bx2UGLtwv3kL2omUJaHjol/+nzQjdmFrV2qnZosMUCn4xSpdffCmMyFWE8FnWw1ZSc7STcTD/NFzLjrN/vbJgMvla0aSxsENio2RvyFQkMKbwfojE22Q/MOtJAg0wyr9/0JNXiAyLYUEwfi1qVoF4F1mvXgLtNgTSx4VzokUKBsiSaDDbEa70ik154dtWLY9nemUsrSfUluCrHLaJhUy9cg6Jc+/9tco0cZhyZDnLIhT/4+n1XGfZxb83c5WElrg/IEYHGOHfqp+lMfusMj/0ppopz+f66dWDabVQCbrkqa+yfbw0ItC0+sZ7opIYGRLt+OelkrIECo7utzCTxdCCJ+2iUIiBV14my7xAFR+fNLKzl9KD+FTT/QoUPlqTmUQNo6NFNGG15znWVRtMDOdDiA6fugl6RrFJHDpaw9/lh+7g7tqwHGF83ZomvvFdKFMsXY6JTpj6rb7gtKzEapB9imCr0aw0ZTWTdlzTs9ksSNr1gZRf/eiztP5puC4weGDRXVjPwHOFOGbUH7Wk8ywQAmUJdEg03bz01U1htYryiNTD4VD2QfVTmxTltocj/2yv7Apv6gQ+Gb0LsgTp2aWbAnbeWX7qfjpYt0j/iw== multiarch-lab@ubuntu

Copy your output (not the Example Output above) to the clipboard with ctrl+c.

Warning

The above copy command (ctrl+c) is saving the .pub public key NOT the private key. You keep the private key and GitHub uses the public key to verify that it is communicating with the owner of the private key (i.e. you).
Add this key to your public GitHub at https://github.com/settings/ssh/new
1. Login or confirm your password if prompted
2. Add SSH Key
3. See your new SSH key has been added with your chosen title.
Note

You created this public GitHub account in the Prerequisites (or already had one).

Scan for GitHub's public key (Done to trust GitHub connection the first time)

ssh-keyscan -H github.com >> "${HOME}/.ssh/known_hosts"

Example Output

# github.com:22 SSH-2.0-babeld-4f04c79d
# github.com:22 SSH-2.0-babeld-4f04c79d
# github.com:22 SSH-2.0-babeld-4f04c79d

Check that your GitHub key now has access to your account with:

ssh -T git@github.com -i "${GITHUB_SSH_KEY}"

Your key was added successfully

Warning: Permanently added the RSA host key for IP address '140.82.114.3' to the list of known hosts.
Hi siler23! You've successfully authenticated, but GitHub does not provide shell access.

Your key was NOT added Please redo this section

Warning: Permanently added the RSA host key for IP address '140.82.113.3' to the list of known hosts.
git@github.com: Permission denied (publickey).

Feel at ease knowing you will delete this key from your Github account in the cleanup phase of this lab so access will be revoked soon enough

Create your HPVS Secure Build Server¶

Export Variables set in previous sections to current terminal session¶

Source bashrc to set necessary variables if unset

source "${HOME}/.bashrc"

Set your provided number and save it for later use¶

You will be assigned a number for the lab so as not to interfere with other users.

Note

This table tells you which number you are assigned.

Set the HPVS_NUMBER variable with your assigned 2 digit number
Command SyntaxExample Command
export HPVS_NUMBER="your_assigned_number"
export HPVS_NUMBER="00"
Warning

Your user will NOT be 00. Please set the appropriate user you have been assigned.

Save your number to bashrc for later use.

echo "export HPVS_NUMBER='${HPVS_NUMBER}'" >> "${HOME}/.bashrc"

Set Secure Build Server Port
```
export SB_PORT=300${HPVS_NUMBER}
```

Save SB_PORT to bashrc for later use.

echo "export SB_PORT='${SB_PORT}'" >> "${HOME}/.bashrc"

Create Certificate and Key for server-side certificate checking in TLS¶

Info

In this process you will create the Secure Build Server Client Certificate and Key referenced in the key table. You will keep the private key on your Linux vm and pass the corresponding certificate to the secure build server you are deploying in this section. Then, whenever you interact with the secure build server to build your applications and get your manifest files it will check that your private key matches the public key of the certificate (i.e., server-side checking in mutual TLS) so that only you (or others / CI tools with the necessary private key) can access the server to perform secure build operations (hpvs sb commands) on it (i.e., build, log, status, manifest, etc.).

Generate rand file

openssl rand -out "${HOME}/.rnd" -hex 256

Make SB_DIR/sbs_keys directory to store secure build server keys and switch to it.
```
mkdir -p "${SB_DIR}/sbs_keys" && cd ${SB_DIR}/sbs_keys
```
Create a private key that will be used by the Secure Build Server certification authority
```
openssl genrsa -out ca.key 2048
```

Create the Secure Build Server certification authority

openssl req -new -x509 -key ca.key -days 730 -out ca.pem

Set environment variables that will be referenced in a configuration file used by subsequent openssl commands in the lab

export COMMON_NAME=server
export PATHLEN=CA:true
export SUBJECT_ALT_NAME=DNS:192.168.22.79:${SB_PORT},IP:192.168.22.79

Create the configuration file which will be used by subsequent openssl commands in the lab

cat << EOF > ${SB_DIR}/sbs_keys/openssl.cnf
# OpenSSL configuration file.
#

# Establish working directory.

dir   = .

[ ca ]
default_ca  = CA_default

[ CA_default ]
serial   = \$dir/serial
#database  = \${ENV::DIR}/index.txt
#new_certs_dir  = \$dir/newcerts
#private_key       = \$dir/ca.key
#certificate       = \$dir/ca.cer
default_days  = 730
default_md  = sha256
preserve  = no
email_in_dn  = no
nameopt   = default_ca
certopt   = default_ca
default_crl_days = 45
policy   = policy_match

[ policy_match ]
countryName  = match
stateOrProvinceName = optional
organizationName = match
organizationalUnitName = optional
commonName  = supplied
emailAddress  = optional

[ req ]
default_md  = sha256
distinguished_name = req_distinguished_name
prompt             = yes

[ req_distinguished_name ]
#countryName = Country
#countryName_default = US
#countryName_min = 2
#countryName_max = 2
#localityName = Locality
#localityName_default = Los Angeles
#organizationName = Organization
#organizationName_default = IBM
#commonName = Common Name
#commonName_max = 64

C  = US
ST = California
L  = Los Angeles
O  = IBM
CN = \${ENV::COMMON_NAME}

[ certauth ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
keyUsage = digitalSignature, keyEncipherment, dataEncipherment, keyCertSign, cRLSign
keyUsage = digitalSignature, keyEncipherment, dataEncipherment, keyCertSign, cRLSign
basicConstraints = \${ENV::PATHLEN}
#crlDistributionPoints = @crl

[ server ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
nsCertType = server
crlDistributionPoints = @crl
subjectAltName = \${ENV::SUBJECT_ALT_NAME}

[ client ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = clientAuth,msSmartcardLogin
nsCertType = client
crlDistributionPoints = @crl
authorityInfoAccess = @ocsp_section
subjectAltName = @alt_names

[ selfSignedServer ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
basicConstraints = CA:FALSE
subjectAltName = \${ENV::SUBJECT_ALT_NAME}
extendedKeyUsage = serverAuth

[ selfSignedClient ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
basicConstraints = CA:FALSE
subjectAltName = @alt_names
extendedKeyUsage = clientAuth

[ server_client ]
subjectKeyIdentifier = hash
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
basicConstraints = CA:FALSE
subjectAltName = \${ENV::SUBJECT_ALT_NAME}
crlDistributionPoints = @crl
extendedKeyUsage = serverAuth,clientAuth

[ v3_intermediate_ca ]
# Extensions for a typical intermediate CA 
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, \${ENV::PATHLEN}
keyUsage = critical, digitalSignature, cRLSign, keyCertSign
crlDistributionPoints = @crl
authorityInfoAccess = @ocsp_section

[ crl ]
URI=http://localhost/ca.crl

[ ocsp_section ]
OCSP;URI.0 = http://localhost:2560/ocsp

[ ocsp ]
# Extension for OCSP signing certificates 
basicConstraints = CA:FALSE
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, OCSPSigning

[alt_names]
# email= \${ENV::SUBJECT_ALT_NAME}
otherName=msUPN;UTF8:\${ENV::SUBJECT_ALT_NAME}

[v3_conf]
keyUsage = digitalSignature, keyEncipherment, dataEncipherment, keyCertSign, cRLSign
basicConstraints = CA:FALSE
EOF

Create a private key that will be used by the Secure Build Server
```
openssl genrsa -out server-key.pem 2048
```

Create the Secure Build Server certificate signing request

openssl req -new -key server-key.pem -out server.csr

Create the Secure Build Server certificate

openssl x509 -sha256 -req -in server.csr \
-CA ca.pem \
-CAkey ca.key \
-set_serial 8086 -extfile openssl.cnf \
-extensions server -days 730 -outform PEM \
-out server.pem

Create a private key for use by the client certificate
```
openssl genrsa -out client-key.pem 2048
```

Create the client certificate signing request

openssl req -new \
-key client-key.pem \
-out client.csr

Create the client certificate

openssl x509 -req -days 730 \
-in client.csr \
-CA ca.pem \
-CAcreateserial \
-CAkey ca.key \
-out client_cert.pem

Create environment variables

export ca_cert=$(echo $(cat ca.pem | base64) | tr -d ' ')
export client_cert=$(echo $(cat client_cert.pem | base64) | tr -d ' ')
export server_cert=$(echo $(cat server.pem | base64) | tr -d ' ')
export server_key=$(echo $(cat server-key.pem | base64) | tr -d ' ')

Switch back to main lab working directory

cd ${SB_DIR}

Create Quotagroup with storage for secure build server¶

hpvs quotagroup create --name "sb_user${HPVS_NUMBER}" --size=40GB

Example Output

+-------------+--------------+
| PROPERTIES  | VALUES       |
+-------------+--------------+
| Name        | sb_user00    |
| Filesystem  | btrfs        |
| Passthrough | false        |
| PoolID      | lv_data_pool |
| Size        | 40 GB        |
| Containers  |              |
| Available   | 39 GB        |
+-------------+--------------+

Create Secure Build Server¶

hpvs vs create --name sbserver_${HPVS_NUMBER} --repo SecureDockerBuild \
--tag 1.2.7.5 --cpu 2 --ram 2048 \
--quotagroup "{quotagroup = sb_user${HPVS_NUMBER}, mountid = new, mount = /newroot, filesystem = ext4, size = 4GB, reset_root=true}" \
--quotagroup "{quotagroup = sb_user${HPVS_NUMBER}, mountid = data, mount = /data, filesystem = ext4, size = 4GB}" \
--quotagroup "{quotagroup = sb_user${HPVS_NUMBER}, mountid = docker, mount = /docker, filesystem = ext4, size = 16GB}" \
--env={EX_VOLUMES="/docker,/data",ROOTFS_LOCK=y,CLIENT_CRT=$client_cert,CLIENT_CA=$ca_cert,SERVER_CRT=$server_cert,SERVER_KEY=$server_key,RUNQ_ROOTDISK=new} \
--ports "{containerport = 443, protocol = tcp, hostport = ${SB_PORT}}"

Example Output

+-------------+------------------------------+
| PROPERTIES  | VALUES                       |
+-------------+------------------------------+
| Name        | sbserver_00                  |
| CPU         | 2                            |
| Memory      | 2048                         |
| State       | running                      |
| Status      | Up Less than a second        |
| Networks    | Gateway:172.31.0.1           |
|             | IPAddress:172.31.0.2         |
|             | MacAddress:02:42:ac:1f:00:02 |
|             | Network:bridge               |
|             | Subnet:16                    |
| Ports       | GuestPort:30000              |
|             | LocalPort:443/tcp            |
| Quotagroups | [sb_user00]                  |
+-------------+------------------------------+

We can see the quotagroup is now being used with

hpvs quotagroup show --name "sb_user${HPVS_NUMBER}"

Example Output

+-------------+-----------------------------+
| PROPERTIES  | VALUES                      |
+-------------+-----------------------------+
| Name        | sb_user00                   |
| Filesystem  | btrfs                       |
| Passthrough | false                       |
| PoolID      | lv_data_pool                |
| Size        | 40 GB                       |
| Containers  | container_name:sbserver_00  |
|             | mount_ids:[new data docker] |
| Available   | 11 GB                       |
+-------------+-----------------------------+

The show output for the Hyper Protect Virtual Server was shown when it was deployed but we can bring it back up with

hpvs vs show --name "sbserver_${HPVS_NUMBER}"

Example Output

+-------------+------------------------------+
| PROPERTIES  | VALUES                       |
+-------------+------------------------------+
| Name        | sbserver_00                  |
| CPU         | 2                            |
| Memory      | 2048                         |
| State       | running                      |
| Status      | Up 2 minutes                 |
| Networks    | Gateway:172.31.0.1           |
|             | IPAddress:172.31.0.2         |
|             | MacAddress:02:42:ac:1f:00:02 |
|             | Network:bridge               |
|             | Subnet:16                    |
| Ports       | GuestPort:30000              |
|             | LocalPort:443/tcp            |
| Quotagroups | [sb_user00]                  |
+-------------+------------------------------+

Your secure build server is now up and running!

It is available at the IP Address of the Hyper Protect Virtual Server LPAR and port (GuestPort) specified.

You will use this secure build server to securely build your application in the next section.

Note

You can assign IP addresses and hostnames for containers as necessary for your purposes but using the docker network and host ports is a nice way to quickly get running without having to use up IP addresses on your network.

Securely Build your Application¶

Export Variables set in previous sections to current terminal session¶

Source bashrc to set necessary variables if unset

source "${HOME}/.bashrc"

Create repository registration GPG signing key¶

Info

This section creates the Repository Registration Signing Key referenced in the key table. The GNU Privacy Guard (GPG) utility (a free implementation of the OpenPGP standard or PGP) generates this key pair (protected by a user defined password) and then exports the public and private keys to files in the ${SB_DIR}/registration_keys/ directory. Later, you will employ these keys to sign a registration file for your securely built image to register it with your Hyper Protect Virtual Servers appliance such that only the holder of the private key can change the registered repository on the Hyper Protect Virtual Servers appliance.

Set key name
```
export keyName="secure_bitcoin_key${RANDOM}"
```
Info

${RANDOM} stores a pseudo-random number to use since GPG keys on a system must each have a unique key name (uid). This will make sure users can safely re-run commands for multiple runs if they so choose.

Set key passphrase

Command SyntaxExample Command

export passphrase="your_passphrase"

export passphrase="most_secure_pw_i_could_think_of"

Create directory to store Docker repository registration signing key material
```
mkdir -p "${SB_DIR}/registration_keys"
```

Create Key Definition

cat > "${SB_DIR}/registration_keys/${keyName}_definition_keys" <<EOF
%echo Generating registration definition key
Key-Type: RSA
Key-Length: 4096
Subkey-Type: RSA
Subkey-Length: 4096
Name-Real: ${keyName}
Expire-Date: 0
Passphrase: ${passphrase}
# Do a commit here, so that we can later print "done" :-)
%commit
%echo done
EOF

Generate Key pair

gpg --armor --batch \
--generate-key "${SB_DIR}/registration_keys/${keyName}_definition_keys"

Example Output

gpg: directory '/home/multiarch-lab/.gnupg' created
gpg: keybox '/home/multiarch-lab/.gnupg/pubring.kbx' created
gpg: Generating registration definition key
gpg: /home/multiarch-lab/.gnupg/trustdb.gpg: trustdb created
gpg: key 7E05CE05DFEBA2BC marked as ultimately trusted
gpg: directory '/home/multiarch-lab/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/multiarch-lab/.gnupg/openpgp-revocs.d/27FB55DC5F7FDF0598C9B1007E05CE05DFEBA2BC.rev'
gpg: done

Export Private key

gpg --armor --pinentry-mode=loopback --passphrase  "${passphrase}" \
--export-secret-keys "${keyName}" > "${SB_DIR}/registration_keys/${keyName}.private"

Export Public key

gpg --armor --export ${keyName} > "${SB_DIR}/registration_keys/${keyName}.pub"

List newly generated key files

 ls ${SB_DIR}/registration_keys/

Example Output

secure_bitcoin_key7750_definition_keys  secure_bitcoin_key7750.private  secure_bitcoin_key7750.pub

Set Build Configuration¶

Set Secure Build Lab IP Address
```
export SB_IP=192.168.22.79
```

Save Secure Build Lab IP Address for later use

echo "export SB_IP='${SB_IP}'" >> "${HOME}/.bashrc"

Set Secure Build GitHub repository

export GH_REPO="git@github.com:ibm-wsc/secure-bitcoin-wallet.git"

Set Docker Image Name
```
export IMAGE_NAME="hpvs_bc"
```

Set repository registration name

export REPO_ID="${IMAGE_NAME}_${HPVS_NUMBER}"

Save repository registration name for later use

echo "export REPO_ID='${REPO_ID}'" >> "${HOME}/.bashrc"

Create config file

cat > "${SB_DIR}/sb_config.yaml" <<EOF
secure_build_workers:
    sbs:
        url: 'https://${SB_IP}'
        port: '${SB_PORT}'
        cert_path: '${SB_DIR}/sbs_keys/client_cert.pem'
        key_path: '${SB_DIR}/sbs_keys/client-key.pem'
        ca_cert_path: '${SB_DIR}/sbs_keys/ca.pem'
    regfile:
        id: '${REPO_ID}'
    github:
        url: '${GH_REPO}'
        branch: 'master'
        ssh_private_key_path: '${GITHUB_SSH_KEY}'
        recurse_submodules: 'False'
        dockerfile_path: './Dockerfile'
        docker_build_path: './'
    docker:
        push_server: '${REGISTRY_NAME}'
        #base_server: '${REGISTRY_NAME}'
        pull_server: '${REGISTRY_NAME}'
        repo: '${DOCKER_USERNAME}/${IMAGE_NAME}'
        image_tag_prefix: 'latest'
        content_trust_base: 'False'
    #env:
    # You would enter environment variables that you want to use in your application container in the whitelist array.
    #    whitelist: []
    #build:
    # You would enter build parameters such as build args you want to use in your application container
    #    args: { 'ARG1' : 'VALUE1' }
    signing_key:
        private_key_path: '${SB_DIR}/registration_keys/${keyName}.private'
        public_key_path: '${SB_DIR}/registration_keys/${keyName}.pub'
EOF

Continue to the Build Application section if you are launching secure build for the first time or the Troubleshooting Secure Build section if things didn't go as planned your first go-round and you are trying to get back on the right track.

Build Application¶

Info

In this section, you finally use all of your configuration information to build your application securely over TLS by connecting to the secure build server you deployed in the previous part of the lab with the Secure Build Server Client Certificate and Key. This build securely updates the application using Docker Content Trust, an implementation of The Update Framework. This involves securely signing a series of metadata files with corresponding keys (Root Key, Image Signing "Targets" Key, Snapshot Key, and Timestamp Key referenced in the key table) and pushing this trust metadata to a Notary Server to provide assurances regarding the integrity of the Docker Images when users pull them to run in their environments. This conforms to The Update Framework Specification

Additionally, this process generates a Manifest Signing Key which it employs to sign the contents of the build for attestation of the build contents by internal and/or third party auditors. The Manifest Signing Key is discussed in more detail in the Verify your application section later in the lab.

Initialize Secure Build Hyper Protect Virtual Server with configuration file generated in the Set Build Configuration section
```
hpvs sb init --config "${SB_DIR}/sb_config.yaml"
```
Example Output
```
{"status":"OK"}
```

Launch secure build with a timeout of 20 minutes to complete using the configuration file generated in the Set Build Configuration section

hpvs sb build \
--timeout 20 \
--config "${SB_DIR}/sb_config.yaml"

Tip

The following build will take anywhere from 15-20 minutes to complete. While this is ongoing, you should open a new tab in your terminal to check the automatically updating logs and build status (steps for doing this are detailed in the next few steps). If this command times out please check the status as in step 4 to make sure nothing went wrong. It might just be that your build took too long and everything will be ok. If something did go wrong, visit the Troubleshooting Secure Build section.

Note

The secure build is asynchronous so if the command gets interrupted here don't worry!

Example Output after running 15-20 minutes to completion

+--------+-------------------------+
| status | OK: async build started |
+--------+-------------------------+
##############################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################################
+---------------------+--------------------------------------------------------------------------------------------+
| root_ssh_enabled    | false                                                                                      |
| status              | success                                                                                    |
| build_name          | docker.io.gmoney23.hpvs_bc_a.latest-b3416d8.2020-06-23_22-12-54.183641                     |
| image_tag           | latest-b3416d8                                                                             |
| manifest_key_gen    | soft_crypto                                                                                |
| manifest_public_key | manifest.docker.io.gmoney23.hpvs_bc_a.latest-b3416d8.2020-06-23_22-12-54.183641-public.pem |
+---------------------+--------------------------------------------------------------------------------------------+

Please look at the logs in another terminal window while the secure build is running (don't interrupt the current terminal window which is waiting for the secure build)

hpvs sb log --config "${SB_DIR}/sb_config.yaml"

Example Truncated Output

2020-06-23 05:25:42,453  root       INFO    starting a build
2020-06-23 05:25:42,454  root       INFO    cleaning up the local github repo and the github access credential
2020-06-23 05:25:42,454  root       INFO    github_dir=secure-bitcoin-wallet
2020-06-23 05:25:42,454  root       INFO    cloning a github repo
2020-06-23 05:25:42,454  root       INFO    github_host=github.com
2020-06-23 05:25:42,454  root       INFO    cmd=ssh-keyscan github.com
2020-06-23 05:25:47,659  root       INFO    # github.com:22 SSH-2.0-babeld-7c96ae41
# github.com:22 SSH-2.0-babeld-b6072416
# github.com:22 SSH-2.0-babeld-b6072416
github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pL
.....

You can also look at the secure build status in another window. This can be useful if you accidentally interrupted the secure build command or it times out due to the timeout not being long enough. It will also fill out the additional fields that are initially blank when the build completes (such as build_name and manifest_public_key, etc.).

hpvs sb status --config "${SB_DIR}/sb_config.yaml"

Example Output

+---------------------+---------------+
| build_name          |               |
| image_tag           |               |
| manifest_key_gen    |               |
| manifest_public_key |               |
| root_ssh_enabled    | false         |
| status              | github cloned |
+---------------------+---------------+

If you see an error in your status

If you see that your build ran into an error please visit the Troubleshooting Secure Build section

You can continue to check the logs to monitor the progress of your secure build with the previous logs command
```
hpvs sb log --config "${SB_DIR}/sb_config.yaml"
```

When the secure build successfully completes, it will have ending logs similar to the following:

Example Output

2022-04-26 18:09:28,843  root       INFO    run: latest: digest: sha256:45cd2d06a2ef978cf1ae60b58833689ff2af1aff0b3d6aa2e69ea83378f6f22d size: 5549
2022-04-26 18:09:28,843  root       INFO    run: Signing and pushing trust metadata
2022-04-26 18:09:29,656  root       INFO    run: Successfully signed docker.io/gmoney23/hpvs_bc:latest
2022-04-26 18:09:29,661  root       INFO    run: return code = 0
2022-04-26 18:09:29,662  root       INFO    extracting an image keyid and key
2022-04-26 18:09:29,663  root       INFO    keyid=2092f4e8a72ab297e94a05c18a1ad5b558b9cdee3531018752cd23e238c02889
2022-04-26 18:09:29,663  root       INFO    publickey=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJrVENDQVRhZ0F3SUJBZ0lSQUlSUVpKVmR0QVJycGNnc1A3T0diRVF3Q2dZSUtvWkl6ajBFQXdJd0xqRXMKTUNvR0ExVUVBd3dqWkc5amEyVnlMbWx2TDNOcGJHeHBiV0Z1TDJod2RuTmZZbU5mTWpBeU1qQTBNall3SGhjTgpNakl3TkRJMk1UZ3dPVEkwV2hjTk16SXdOREl6TVRnd09USTBXakF1TVN3d0tnWURWUVFERENOa2IyTnJaWEl1CmFXOHZjMmxzYkdsdFlXNHZhSEIyYzE5aVkxOHlNREl5TURReU5qQlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDkKQXdFSEEwSUFCSUhqM1RLaDZPYmp4Z214allOZ3ZDSGlDSTNOOTlBZy8vS0lPc0hxR25SYUR6NU5LbEdMWktvOAoxaDRYaUgwRG92d1ZFMGUvdlZzM3V3dnlwT0JEYzNtak5UQXpNQTRHQTFVZER3RUIvd1FFQXdJRm9EQVRCZ05WCkhTVUVEREFLQmdnckJnRUZCUWNEQXpBTUJnTlZIUk1CQWY4RUFqQUFNQW9HQ0NxR1NNNDlCQU1DQTBrQU1FWUMKSVFEU2o4SzcvVDhRSWFLbVoyaEdSTTZnTkRsRE01L21UcUdQK09qc3NwWS9jZ0loQU43ZDM5RXlITkV3bFRUMApkMC9XaVcwejRCMWdMM1RyQVhFRDlwVUhoMVR5Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
2022-04-26 18:09:29,663  root       INFO    generating a config file
2022-04-26 18:09:29,664  root       INFO    create_and_push: SoftCrypto
2022-04-26 18:09:30,627  root       INFO    digest=7b997311130b0b0984e1b7cabd45e7b4a5461337d52dcb1b99be26849d7172d9
2022-04-26 18:09:30,627  root       INFO    block_size=64
2022-04-26 18:09:30,648  root       INFO    digest=7b997311130b0b0984e1b7cabd45e7b4a5461337d52dcb1b99be26849d7172d9
2022-04-26 18:09:30,650  root       INFO    signature=4e6b43530773245b8c04e016e8b112cfa8efab6621b84c9825d06c7fa7faba525c8cc97618313205bf46db123d8f53ca2377871b3daa6dec62e48fc539fd17c9796f5c395bd1a82b05e60d69796fea1baa7fb48b4f9ae0cd72c329121241b2e4f7a21d8bc6456fa921df2ab9b9a47974bfb841c540ff1bd9e9e350e9f9d1c5f4da3bef0857e3f21605e1131f4b6ca0a12db33ae57149e37718ef8e54b978769cbf8cf025d32323f1f488df6db9ffd6ec22ebad7daa67e99c3506b47bdefc0ebe3d0fe76edc6d19d38283a355f9d94eab20c3e3d32cdd6b5ae8f8e0f4748ffbfec10661f7aad9dbc3dd5017e42f4468f7ef5443303c694761d6ff8646382fda14
2022-04-26 18:09:30,650  root       INFO    verify=OK
2022-04-26 18:09:31,049  root       WARNING undefined MANIFEST_BUCKET_NAME
2022-04-26 18:09:31,049  root       WARNING skipping transferring a manifest to COS
2022-04-26 18:09:31,049  root       INFO    cleaning up the build environment
2022-04-26 18:09:31,049  root       INFO    github_dir=secure-bitcoin-wallet
2022-04-26 18:09:31,110  root       INFO    completed a build

When the secure build successfully completes, you can check the status again to see a status of success.

hpvs sb status --config "${SB_DIR}/sb_config.yaml"

Example Output

+---------------------+---------------------------------------------------------------------------------------------------+
| manifest_public_key | manifest.docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558-public.pem |
| root_ssh_enabled    | false                                                                                    |
| status              | success                                                                                  |
| build_name          | docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558                     |
| image_tag           | latest-941893e                                                                           |
| manifest_key_gen    | soft_crypto                                                                              |
+---------------------+------------------------------------------------------------------------------------------+

If you see an error in your status

If you see that your build ran into an error please visit the Troubleshooting Secure Build section

From the original terminal window, where you ran hpvs sb init, output the repository registration file.
```
echo "${passphrase}" | hpvs sb regfile \
--config "${SB_DIR}/sb_config.yaml" \
--out "${SB_DIR}/yaml.${REPO_ID}.enc"
```
Example Output
```
Enter Signing Private key passphrase:
```
Tip

The echo command takes care of the passphrase so you don't need to enter it manually.

Warning

If you run this command from a terminal window where you did not set the passphrase environment variable you will get an error saying openpgp: invalid data: private key checksum failure. You can also check to make sure you are in the right terminal window by running echo "${passphrase}" and the output should be the passphrase you set in the beginning of the "Create repository registration GPG signing key" section.

Troubleshooting Secure Build¶

Troubleshooting Instructions

If your build completed successfully, feel free to SKIP this section

If your build failed continue for instructions on how to find the happy path yet again.

If at any point you see an error in the status command you will need to restart your build with the following steps.

If the secure build command is still running in its own window please interrupt it with ctrl + c

Check the logs for more error information using:

hpvs sb log --config "${SB_DIR}/sb_config.yaml"

Correct whatever information was incorrect and go back through the steps in the Set Build Configuration section

Clean up the data (i.e. logs) from the old build with:

hpvs sb clean --config "${SB_DIR}/sb_config.yaml"

Update the secure build server with the new configuration
```
hpvs sb update --config "${SB_DIR}/sb_config.yaml"
```
Continue onward like you just initialized your build server (You did ... just for another time ) at Step 2 in the Build Application Section

Info

The next command you should run will be hpvs sb build (Step 2 in the Build Application Section)

Verify your application¶

Info

On the secure build server, the .tbz manifest file was hashed and then signed by the Manifest Signing Key referenced in the key table which only exists on the server (inside its secure environment). In steps 1-11 below, you are using the matching public key you will receive from the secure build server (using a secure TLS connection) in step 4 to "undo" this signature to reveal the original hash of the file. We then compare this hash to the hash of the file we have using the verify command in step 11. Verification OK means they are the same, implying that the .tbz file we have now was the same one that was signed by the manifest private key inside the safe confines of the secure build server.

Create directories for your manifest file information and change into your new manifest directory.
```
mkdir -p "${SB_DIR}/manifest/manifest_files" && cd "${SB_DIR}/manifest"
```

Save the build name from the status command as a variable

export BUILD_NAME="$(hpvs sb status --config "${SB_DIR}/sb_config.yaml" \
| grep build_name | egrep -ow 'docker.*[[:digit:]]')" && echo "${BUILD_NAME}"

Example Output

docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558

Get your application manifest

hpvs sb manifest --config "${SB_DIR}/sb_config.yaml" --name "${BUILD_NAME}"

Get your manifest public verification key
```
hpvs sb pubkey --config "${SB_DIR}/sb_config.yaml" --name "${BUILD_NAME}"
```
Info

Connections to the secure build server are secured using mutual TLS. This means that proper certificates and keys have to be used on the client side to access these files (as well as when doing the previous secure build commands). This adds a layer of security to make sure that the public key and manifest files are authentic and securely distributed.

Check that your application manifest and signing key were retrieved

ls

Example Output

docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558-public.pem
manifest.docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558.sig.tbz
manifest_files

Set MANIFEST to point to your manifest files.

export MANIFEST="${SB_DIR}/manifest/manifest.${BUILD_NAME}"

Set MAN_PUBKEY to point to your manifest public key.

export MAN_PUBKEY="${SB_DIR}/manifest/${BUILD_NAME}-public.pem"

Untar and unzip the manifest .sig.tbz file to reveal the .sig and .tbz files (and remove the original .sig.tbz)
```
tar -xjvf "${MANIFEST}.sig.tbz" && rm "${MANIFEST}.sig.tbz"
```
Example Output
```
manifest.docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558.tbz
manifest.docker.io.gmoney23.hpvs_bc.latest-941893e.2022-04-26_18-09-29.663558.sig
```
Note

The .sig.tbz was a tarball compressed using bzip2 compression of both a nested .tbz file (containing the manifest files) and a .sig file containing a signature of the nested .tbz to verify it with the public key retrieved using the hpvs sb pubkey command above saved in the file referenced by MAN_PUBKEY.

Convert the signature file to binary format

cat "${MANIFEST}.sig" | xxd -r -p > "${MANIFEST}.sig.bin"

Hash (SHA256) the manifest .tbz file (containing the manifest files)

openssl dgst -sha256 -binary -out "${MANIFEST}.tbz.sha256" "${MANIFEST}.tbz"

Verify that the .tbz manifest package was the one signed on the secure build server.
```
openssl dgst -sha256 -verify "${MAN_PUBKEY}" \
-signature "${MANIFEST}.sig.bin" "${MANIFEST}.tbz.sha256"
```
Success
```
Verified OK
```
Note

In this case, we are double hashing the .tbz file on the signature side which is why we hash the .tbz before the verify command here.

Untar and unzip the manifest .tbz file into the manifest_files directory.

tar -xjf "${MANIFEST}.tbz" -C "${SB_DIR}/manifest/manifest_files"

Change into the manifest_files directory with your manifest files and view the files in the directory.
```
cd "${SB_DIR}/manifest/manifest_files" && ls
```
Example Output
```
data  git  root_ssh
```
Manifest explanation

This manifest package contains three directories as shown above. The data directory contains the build.json (containing the build status of the directory updated after the image was pushed to its Docker Registry) and build.log (containing the logs from the secure build). The git directory contains the source code used for the build (cloned from git). Finally, the root_ssh directory contains any ssh material provided (if the user chose to use ssh) which is empty for us because we didn't enable ssh and provide ssh keys. This way no one can ssh into our secure build container.
What does this give me?

This gives you a way to see the collection of files used for your build at the time of the build and signed by the manifest private key which is secured in your secure build container. By retrieving the public key and verifying the signature of the package we and auditors can verify what was used for our secure image build. (Since the private key was generated in the secure build server we can trust it). This gives us verification of what was used in the build as well as the verification of the images themselves we get from Docker Content Trust.

Note

The secure build server also generates the keys for Docker Content Trust and stores them safely to provide a secure root of trust.

Remember the secure build server is running as a Hyper Protect Virtual Server and thus inherits all of the security features and assurances of Hyper Protect Virtual Servers.

Summary¶

Congratulations!!!

You have securely built your application and are ready to deploy it into a Hyper Protect Virtual Server in the next section.

Deploy your Securely Built Application as a Hyper Protect Virtual Server¶

Export Variables set in previous sections to current terminal session¶

Source bashrc to set necessary variables if unset

source "${HOME}/.bashrc"

Set up your Docker Image Repository¶

Register your repository

hpvs repository register \
--pgp="${SB_DIR}/yaml.${REPO_ID}.enc" \
--id="${REPO_ID}"

Example Output

+-----------------+------------------------------+
| repository name | docker.io/gmoney23/hpvs_bc_a |
| runtime         | runq                         |
+-----------------+------------------------------+

View your newly registered repository

hpvs repository show --id "${REPO_ID}"

Example Output

+-----------------+------------------------------+
| repository name | docker.io/gmoney23/hpvs_bc_a |
| runtime         | runq                         |
+-----------------+------------------------------+

Set up your Quotagroup for storage¶

Create Quotagroup

hpvs quotagroup create --name="${REPO_ID}" --size=5GB

Example Output

+-------------+---------------------+
| PROPERTIES  | VALUES              |
+-------------+---------------------+
| Name        | hpvs_bc_a_00        |
| Filesystem  | btrfs               |
| Passthrough | false               |
| PoolID      | lv_data_pool        |
| Size        | 5 GB                |
| Containers  |                     |
| Available   | 4 GB                |
+-------------+---------------------+

View your newly created quotagroup

hpvs quotagroup show --name "${REPO_ID}"

Example Output

+-------------+---------------------+
| PROPERTIES  | VALUES              |
+-------------+---------------------+
| Name        | hpvs_bc_a_00        |
| Filesystem  | btrfs               |
| Passthrough | false               |
| PoolID      | lv_data_pool        |
| Size        | 5 GB                |
| Containers  |                     |
| Available   | 4 GB                |
+-------------+---------------------+

Deploy your Application¶

Set App port
```
export APP_PORT=301${HPVS_NUMBER}
```

Create your Hyper Protect Virtual Server

hpvs vs create --name=${REPO_ID} --repo ${REPO_ID} \
--tag latest --cpu 2 --ram 2048 \
--quotagroup "{quotagroup = ${REPO_ID}, mountid = new, mount = /newroot, filesystem = btrfs, size = 4GB}" \
--ports "{containerport = 443, protocol = tcp, hostport = ${APP_PORT}}"

Example Output

+-------------+------------------------------+
| PROPERTIES  | VALUES                       |
+-------------+------------------------------+
| Name        | hpvs_bc_a_00                 |
| CPU         | 2                            |
| Memory      | 2048                         |
| State       | running                      |
| Status      | Up Less than a second        |
| Networks    | Gateway:172.31.0.1           |
|             | IPAddress:172.31.0.6         |
|             | MacAddress:02:42:ac:1f:00:06 |
|             | Network:bridge               |
|             | Subnet:16                    |
| Ports       | GuestPort:30100              |
|             | LocalPort:443/tcp            |
| Quotagroups | [hpvs_bc_a_00]               |
+-------------+------------------------------+

Check on the Quotagroup (and see the application is indeed using it)

hpvs quotagroup show --name "${REPO_ID}"

Example Output

+-------------+------------------------------------+
| PROPERTIES  | VALUES                             |
+-------------+------------------------------------+
| Name        | hpvs_bc_a_00                       |
| Filesystem  | btrfs                              |
| Passthrough | false                              |
| PoolID      | lv_data_pool                       |
| Size        | 5 GB                               |
| Containers  | container_name:hpvs_a_00           |
|             | mount_ids:[new]                    |
| Available   | 751 MB                             |
+-------------+------------------------------------+

We can see the Hyper Protect Virtual Server for our application is now taking up the majority of our Quotagroup.

If you ever need to check the Hyper Protect Virtual Server you can use the show command

hpvs vs show --name=${REPO_ID}

Example Output

+-------------+------------------------------+
| PROPERTIES  | VALUES                       |
+-------------+------------------------------+
| Name        | hpvs_bc_a_00                 |
| CPU         | 2                            |
| Memory      | 2048                         |
| State       | running                      |
| Status      | Up 5 minutes                 |
| Networks    | IPAddress:172.31.0.6         |
|             | MacAddress:02:42:ac:1f:00:06 |
|             | Network:bridge               |
|             | Subnet:16                    |
|             | Gateway:172.31.0.1           |
| Ports       | GuestPort:30100              |
|             | LocalPort:443/tcp            |
| Quotagroups | [hpvs_bc_a_00]               |
+-------------+------------------------------+

Access your application¶

Run the following command to print the address for your electrum wallet application:

echo "https://${SB_IP}:${APP_PORT}/electrum"

Example Output

https://192.168.22.79:30100/electrum

Your app is now up and running at the address printed in your terminal!

Tip

You can visit the IP address easily by right-clicking on the link (wih the line under it) in your terminal and selecting Open Link

Info

This application uses self-signed certificates so don't worry about the certificate warning you'll need to accept in your browser. Just click Advanced and then Accept the Risk and Continue Accept Risk

In the final part of this lab you will use your newly built application...

Welcome to the Secure Bitcoin Wallet on IBM LinuxONE¶

Overview¶

This application is a secure Electrum Bitcoin wallet found at this GitHub repository. You can use it to store the identities necessary to transact on the Bitcoin public blockchain network. While this version of the wallet is just a proof of concept, running this type of wallet on Hyper Protect enables you to protect your digital assets from bad actors such as malicious server administrators.

Info

This Electrum Bitcoin wallet functions regularly, while inheriting the security benefits of the Hyper Protect Virtual Server platform. This ensures that a legitimate version of the application is running (Secure Image Build process) and that administrators cannot compromise the application (Hyper Protect Virtual Server deployment).

Account Registration¶

Registering a fake account for lab purposes.

Choose Register since you won't have an existing account on the newly deployed server.
Enter the registration details you desire.

Tip

Do not worry about the information you enter on the registration page shown above as it won't map to anything. You just need your password to log back in if you log out of the application.

Wallet initialization¶

It's time to set up your Secure Electrum Bitcoin wallet itself!

Bring up the wallet screen
Enter in a password for your wallet and click Create Wallet
Load your newly created wallet to enable it
Reload the page.
Your wallet is ready for use in all of its glory

Receiving Bitcoins¶

A wallet without currency is blasphemy, so it's time to fill it on up with fake bitcoins.

Go to the Receive section of the wallet and get the bitcoin wallet address.

Info

This is the address whose allotted bitcoins you lay claim to.
Open this bitcoin test faucet site [click on the link] and use it to transfer bitcoin value to the Receiving address in your wallet from step 1 above.

Note

Instead of transacting on the "real" bitcoin blockchain network, we are using a testnet. This means that the network participants agree that the assets on the network have no value. Testnets are used for testing changes to the network, testing applications and introducing new users to the technical aspects of network. There are testnets for many of the public blockchain networks including of course bitcoin and ethereum. Test faucets (like the one we are using) act as distributors of tokens to other users on the testnet.
Switch back to your wallet tab and go to the History section and then reload the page.
You should now see your wallet address as the recipient of a pending transaction from the bitcoin testnet faucet.
After clicking for more information you get a detailed transaction overview

Info

The number of confirmations a block receives is the number of blocks deep the block that has included the blockchain transaction is. In other words, 1 confirmation means that the current head block includes the transaction. 2 confirmations means that the current head block's parent block contains the transaction and so on. The deeper the transaction is (more confirmations it has) the more mining power it would take to "reverse history" and undo the transaction.

Since there are 0 confirmations in the picture above, it means that the transaction is not yet included in a block. This is why it has no timestamp yet and its block number is listed as 0.
After waiting anywhere from a minute to a few minutes (depending on the current testnet traffic) you should see a confirmation on your transaction.

Tip

You will need to keep reloading the page for it to update. It doesn't update automatically.

There is now a timestamp and a block number!

Info

As time passes more confirmations will accumulate. You can check on the confirmations again at the end of the lab to show yourself this (Given enough time has passed for one or more additional confirmation(s) to occur).

Returning Bitcoins¶

Since you are feeling charitable you decide to transfer your testnet value back to the faucet's address.

Go back to the faucet site and get its bitcoin address
Tip

This address is here for easy copy and paste (ensure this matches what the application shows in the browser before using this, as the bitcoin address they use for returning funds changes occasionally):
```
tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt
```
Send bitcoins to faucet using Send section of wallet
Once sent you will see the Signed transaction information filled out on your wallet page.
You can go back to the bitcoin faucet site and see the transaction as green there with a sender of your address and a transaction ID matching the one you sent.
You can view both the initial received transaction and the newly sent transaction in the History tab of your bitcoin wallet.

Tip

You have to keep reloading the page for it to update with new confirmations.

Info

If you wait long enough, eventually these transactions will gain confirmations as in the picture below
You can continue to play around with the electrum wallet before moving on.

Summary¶

Success

You have participated in the bitcoin testnet using a securely built electrum bitcoin wallet powered by a Hyper Protect Virtual Server. Congratulations!!!

Now, it's time to clean up...

Clean up your Environment¶

Export Variables set in previous sections to current terminal session¶

Source bashrc to set necessary variables if unset

source "${HOME}/.bashrc"

Clean up Secure Build Server¶

Clean up virtual server

hpvs vs delete --name sbserver_${HPVS_NUMBER}

Clean up Quotagroup

hpvs quotagroup delete --name "sb_user${HPVS_NUMBER}"

Clean up Application¶

Clean up HPVS deployment
```
hpvs vs delete --name ${REPO_ID}
```

Clean up Quotagroup

hpvs quotagroup delete --name "${REPO_ID}"

Clean up Repository¶

hpvs repository  delete --id ${REPO_ID} --force

Example Output

+-------------------+-------------------------------------+
| ContainersDeleted | []                                  |
| ImagesDeleted     | [gmoney23/hpvs_bc_a:latest]         |
| RepositoryDeleted | docker.io/gmoney23/hpvs_bc_a        |
+-------------------+-------------------------------------+

Clean up Docker Token¶

Delete the existing Docker Token by logging into your Docker Hub account and following these instructions

Clean up GitHub ssh key¶

Delete the ssh key you added for the lab following steps 1-3 of these instructions. Stay logged in to GitHub as the next section also deals with your GitHub account.

Clean up GitHub personal access token¶

You should still be logged in to GitHub from the previous step. Click on your picture or avatar for your account and navigate to Settings->Developer Settings->Personal access tokens and delete the personal access token that you created for this lab. Ask an instructor for help if you have difficulty deleting this.

Clean up Lab directory¶

You can remove the directory you stored your files in throughout the lab. This is a personal choice as the lab machine will be deleted after the lab anyway.

rm -rf "${SB_DIR}"

Ended: Secure Image Build Lab

Glossary¶

This glossary of terms consolidates the terms for the Hyper Protect Virtual Servers offering in alphabetical order to help both customers and internal team members to understand our offering better.

Appliance¶

IBM Secure Service Container based appliance provided by an Appliance Vendor. From Hosting Appliance perspective, it is the combination of IBM Secure Service Container and the Hyper Protect Servers Hosting Appliance.

Appliance Administrator¶

The person administrating an appliance which includes tasks, such as configuring storage, or memory to the appliance or performing other configuration tasks through the API provided by SSC/the Hosting Appliance.

Appliance Operational Data¶

Metrics, logs, appliance dump data, error logs, stack traces, kernel dump, etc.

Appliance Protected Data¶

Appliance secrets, workload data, configuration data, settings, and other internal information stored by an appliance.

Appliance Vendor¶

An internal, or external exploiter of SSC, packaging SSC into an appliance.

BYOK¶

The abbreviation of Bring Your Own Key, which allows you to import your existing keys to Hyper Protect Crypto Services service instances that protect your keys with advanced encryption.

BYOI¶

The abbreviation of Bring Your Own Image, which is a part of the IBM Hyper Protect Virtual Servers solution to support the development and deployment of your own container images on top of the Secure Service Container framework.

Container¶

A runtime instance of an Open Container Image (OCI) image.

Crypto administrator¶

The person who signs commands that are issued to the crypto units. Multiple administrators can be added to one crypto unit to increase security.

Crypto units¶

A single unit that represents a hardware security module and the corresponding software stack that is dedicated to the hardware security module for cryptography.

Data encryption keys¶

A cryptographic key used to encrypt data that is stored in an application.

Datapool¶

Synonyms for Storage Pool.

Docker Content Trust¶

Docker Content Trust (DCT) is a feature in the Docker containerization platform that provides the ability to use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side or runtime verification of the integrity and publisher of specific image tags.

Through DCT, image publishers can sign their images and image consumers can ensure that the images they pull are signed. Publishers could be individuals or organizations manually signing their content or automated software supply chains signing content as part of their release process.

Docker registry¶

A Docker registry is a storage and content delivery system, holding named Docker images, available in different tagged versions.

EP11¶

The abbreviation of Enterprise PKCS #11, which is specifically designed for customers seeking support for open standards and enhanced security. The EP11 library provides an interface very similar to the industry-standard PKCS #11 API.

Envelope encryption¶

The process of encrypting data with a data encryption key and then encrypting the key with a root key that can be fully managed.

FIPS 140-2 compliance¶

An organization’s adherence to the Federal Information Processing Standards (FIPS) 140-2 standards. This standard specifies the security requirements that will be satisfied by a cryptographic module utilized within a security system protecting sensitive information. FIPS 140-2 outlines four levels of security:

Level 1 - the lowest level of security. It covers the basic security features in a cryptographic module.

Level 2 - improves the physical security aspects of cryptographic modules. Examples of required physical security measures are tamper-evident coatings, seals, or pick-resistant locks. Role-based authentication is included in this security level and ensures the operator accessing the module is authorized and is limited to their assigned actions.

Level 3 - requires enhanced physical security, potentially with products available from the private sector. A multi-chip embedded module has to be contained in a strong enclosure that zeroizes critical security parameters when it is removed. This security level also uses identity-based authentication.

Level 4 - requires tamper detection circuits to be able to detect any device penetration. This level is best for when cryptographic modules are in a physically unprotected environment that intruders can access. Modules must be able to detect fluctuations and zeroize themselves. Level 4 also protects against security compromises due to environmental conditions.

FIPS 197 compliance¶

An organization’s adherence to Federal Information Processing Standards (FIPS) 197 which is an algorithmic standard that addresses the Advanced Encryption Standard (AES). AES specifies a FIPS-approved cryptographic algorithm that can be used to protect electronic data. The AES algorithm is a symmetric block cipher that can encrypt and decrypt information.

GPG¶

The abbreviation of Gnu Privacy Guard, which is an open standard used for signing, encrypting, and decrypting texts with public and private keys to increase the security of communications.

GREP11¶

Represents Enterprise PKCS #11 (EP11) APIs over gRPC calls, which is designed to be a stateless interface for cryptographic operations on cloud.

gRPC¶

A modern open source high performance remote procedure call (RPC) framework that can connect services in and across data centers for load balancing, tracing, health checking, and authentication.

Hardware security module¶

A physical appliance that provides on-demand encryption, key management, and key storage as a managed service.

Hosting Appliance¶

A technical component within IBM Secure Service Container based appliances, providing the enablement for running Docker-based workloads.

Image¶

The basis of the containers. An image is an ordered collection of root file system changes and the corresponding execution parameters for use within a container runtime.

ISV¶

The abbreviation of Independent Software Vendor, who provides software solutions by developing and deploying containerized applications to the Secure Service Container partitions.

Master key¶

An encryption key that is used to protect a crypto unit. The master key provides full control of the hardware security module and ownership of the root of trust that encrypts the chain keys, including the root key and standard key.

Management Utilities¶

A set of applications to provide an alternate way of configuring Hyper Protect Crypto Services service instances using signature keys and master key parts stored on smart cards.

Management server¶

An x86 or s390x Linux management server used to run the commands provided by the Hyper Protect Virtual Servers offering, and administer the offering.

Manifest¶

A manifest is generated by the Secure Build for audit purpose, which contains a copy of the github project cloned by the Secure Build container, a copy of the build log, and a build.json with the build status.

Manifest public key¶

A manifest public key is used to verify the manifest generated by the Secure Build.

Manifest private key¶

A manifest private key is used to sign the manifest during the Secure Build.

Mutual TLS¶

Mutual authentication or two-way authentication refers to two parties authenticating each other at the same time. Mutual TLS is doing this over the TLS protocol.

Namespace¶

A namespace such as ibmzcontainers that contains a number of unique images. For examples, the images include hpvsop-base, hyperpcons-worker, hyperpcons-riaas, and so on.

Partition¶

A partition is the logic partition (LPAR) on the mainframe, and can be created by using the logic partitioning tools such as Hardware Management Console (HMC) or other logical partitioning tools.

PKCS #11¶

The abbreviation of Public-Key Cryptography Standards #11, which defines a platform-independent API to cryptographic tokens, such as HSM and smart cards.

Protected memory enclave¶

Defined private regions of memory whose contents are protected and unable to be read or saved to any process outside the enclave itself.

Quotagroup¶

The storage assigned to a workload running on an appliance. The appliance administrator assigns FCP, or ECKD based storage to an appliance. He then creates quotagroups, representing parts of the underlying storage. He finally assigns quotagroups to workloads through the appliance API.

Root keys¶

A symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service.

Registry¶

A Registry is a hosted service containing repositories of container images that responds to the Registry API. For example, Docker Hub.

Repository¶

A repository is a set of containerized images. A repository can be shared by pushing it to a registry server. Different images in the repository can be labeled using tags. For example, hpvsop-base.

Repository definition files¶

An encrypted registration file or a repository definition file is used to register the repository, for authentication or validation reasons, such that a Hosting Appliance will trust that the image, when pulled from the registry, is authentic.

Repository registration files¶

A cleartext Python or JSON format file, which is generated by the Secure Build container when the container is created. The JSON format repository registration file can be used as the direct input to generate an encrypted repository definition file.

runc¶

A CLI tool for spawning and running containers according to the Open Container Initiative (OCI) specification.

runq¶

An open-sourced hypervisor-based Docker runtime environment, which is based on runc to run regular containerized images in a lightweight KVM or Qemu virtual machine.

s390x¶

The underlying architecture of IBM Z or LinuxONE mainframe.

Secondary node¶

A cluster member that replicates the contents of the primary database in Hyper Protect DBaaS.

Smart cards¶

An HSM that looks like a credit card with an embedded chip. The chip is capable of performing a limited set of cryptographic operations and is loaded with custom software.

Smart card readers¶

A device that attaches to a workstation and allows the workstation to communicate with a smart card.

Smart Card Utility Program¶

The application installed as part of the Management Utilities. It sets up and manages the smart cards used by the Trusted Key Entry (TKE) application.

Signature key¶

An encryption key that is used by the crypto unit administrator to sign commands that are issued to the crypto unit.

Standard key¶

Another resource in Hyper Protect Crypto Services to directly encrypt and decrypt data.

Secure Build / Secure Image Build¶

The process of building the application code from a Git-like source repository into a container image for s390x architecture, signing the image by using the authentication keys, and publishing the image to the remote repository for later integration.

Secure Service Container¶

A container framework based on the runq technology, that is supported by the IBM Z or LinuxONE servers.

Secure Service Container partition¶

A type of logic partitions (LPARs) on the mainframe that runs the Secure Service Container framework.

SSH¶

The abbreviation of Secure Shell, which is a cryptographic network protocol for operating network services securely over an unsecured network by using public and private keys.

Storage Pool¶

A storage pool is a uniquely named collection of storage disks on which the appliance file system is mounted.

System Administrator¶

This role includes the system administrator of a machine, storage administrators, and network administrators.

tag¶

A tag is used to version images in a repository. For example, latest, 1.2.3.4-develop-a0d3aea, or s390x-develop-54a9045.

Trusted Key Entry application¶

The application installed as part of the Management Utilities. It uses smart cards to load master keys in service instances and to perform other configuration tasks for service instances.

Workload¶

The application and data provided and generated by a (running) Workload Image.

Workload Data¶

Workload user or workload client data, workload logs, workload secrets stored in the appliance.

Workload Image¶

A container-based image, provided by the Workload Vendor. An appliance only runs workload images which have been registered with the appliance through a repository definition file.

Workload User¶

The end-user of a workload.

Workload Vendor¶

The creator of a Docker image running on top of Hosting Appliance.

Other Resources¶

Hyper Protect Virtual Server Resources¶

Hyper Protect Resources¶

How to propose a change¶

On the page you want to make a change to, click on the pencil icon next to the page's title. This will take you to edit the page in Github.

You will see a message similar to the following: "You’re editing a file in a project you don’t have write access to. Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request."

Make your changes in Markdown. And submit for review.

The owners of this repo will review your pull request and accept or deny your change proposal.

There are other ways of doing a pull request, a Google search will lead you to those tutorials.