Securing Your Critical Workloads with IBM Hyper Protect Services

Front cover

Barry Silliman Sandeep Sarkar Diana Henderson Sarath Chandra Mekala Elton de Souza Vasfi Gucer Jin VanStee Qi Ye Jordan Cartwright Madhuri Gangireddy Matt Mondics Matthew Arnold Ravi Kumar Gullapalli Sandeep Ambekar

Redbooks

IBM Redbooks

Securing Your Critical Workloads with IBM Hyper Protect Services

March 2020

SG24-8469-00 Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

First Edition (March 2020)

This edition applies to IBM Hyper Protect Virtual Servers V1.2.0, IBM Hyper Protect Crypto Services V1.0.0 and IBM Hyper Protect DBaaS V1.0.0

© Copyright International Business Machines Corporation 2020. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents

Notices ...... vii Trademarks ...... viii

Preface ...... ix Authors...... x Now you can become a published author, too! ...... xiii Comments welcome...... xiii Stay connected to IBM Redbooks ...... xiv

Chapter 1. Introduction to IBM Hyper Protect Services ...... 1 1.1 Industry and IBM Hyper Protect Services portfolio overview ...... 2 1.2 Hyper Protect Crypto Services ...... 2 1.3 Hyper Protect Database as a Service ...... 3 1.4 Hyper Protect Virtual Servers ...... 4 1.5 Hyper Protect Virtual Servers (on-premises)...... 5 1.5.1 Building images with integrity: Securing continuous integration and continuous delivery ...... 6 1.5.2 Managing infrastructure with least privilege access to applications and data. . . . . 6 1.5.3 Deploying images with trusted provenance ...... 6 1.6 Security features ...... 6 1.6.1 Cryptography ...... 7 1.6.2 IBM Secure Service Container ...... 9

Chapter 2. IBM Cloud Hyper Protect Crypto Services...... 29 2.1 Overview ...... 30 2.2 Creating an instance of Hyper Protect Crypto Services on the public IBM Cloud. . . . . 30 2.2.1 Creating an instance by using the IBM Cloud console ...... 31 2.2.2 Getting your service instance ready for use ...... 37 2.3 Using the Key Management Services feature of Hyper Protect Crypto Services . . . . . 59 2.3.1 Creating a root key ...... 59 2.3.2 Creating a standard key ...... 64 2.3.3 Wrapping a standard key ...... 66 2.3.4 Unwrapping a standard key ...... 67 2.3.5 Importing a key as a root key ...... 68 2.3.6 Importing a key as a standard key ...... 71 2.3.7 Listing all keys...... 74 2.3.8 Listing a specific key ...... 78 2.4 Using the GREP11 feature of Hyper Protect Crypto Services ...... 81 2.4.1 Functions available with the GREP11 API ...... 83 2.5 Code examples ...... 86 2.5.1 Setting up the GREP11 API ...... 86 2.5.2 GREP11 code examples...... 86 2.6 Hyper Protect Crypto Services use cases...... 92 2.6.1 Protecting IBM Cloud services ...... 92 2.6.2 Using the GREP11 API...... 93

Chapter 3. IBM Cloud Hyper Protect DBaaS...... 95 3.1 Introduction to IBM Cloud Hyper Protect DBaaS ...... 96 3.2 Sizing and topology...... 97

© Copyright IBM Corp. 2020. All rights reserved. iii 3.3 Public Cloud Service instantiation...... 98 3.3.1 Prerequisites ...... 98 3.3.2 Web Interface ...... 98 3.3.3 IBM Cloud CLI...... 100 3.3.4 Hyper Protect DBaaS RESTful API...... 103 3.4 Administration and operations...... 105 3.4.1 Managing a Hyper Protect DBaaS Service...... 105 3.4.2 Managing database instances ...... 106 3.4.3 Managing database users...... 106 3.4.4 Logging and monitoring ...... 107 3.4.5 Back up and restore ...... 111 3.5 Security and compliance ...... 114 3.6 Use case: Encrypting databases with your keys protected...... 114 3.7 API interaction and code samples...... 115 3.7.1 Cloning the GitHub example Python code ...... 116 3.7.2 Setting up a Python virtual environment with requests ...... 116 3.7.3 Running the example file ...... 117

Chapter 4. IBM Cloud Hyper Protect Virtual Servers...... 119 4.1 Introduction to IBM Cloud Hyper Protect Virtual Servers ...... 120 4.2 IBM Cloud Hyper Protect Virtual Servers use cases...... 120 4.3 Public Cloud service instantiation ...... 121

Chapter 5. IBM Hyper Protect Virtual Servers on-premises ...... 125 5.1 Introduction to IBM Hyper Protect Virtual Servers on-premises ...... 126 5.2 IBM Hyper Protect Virtual Servers key features ...... 127 5.2.1 Trusted CI/CD ...... 128 5.2.2 GREP11 ...... 129 5.2.3 User management ...... 130 5.2.4 Bring Your Own Image ...... 130 5.2.5 Encryption ...... 130 5.3 IBM Hyper Protect Virtual Servers use cases ...... 131 5.4 IBM Hyper Protect Virtual Servers architecture overview ...... 133 5.5 A sample use case: Hyper Protect Virtual Server for secure storage ...... 138 5.5.1 Creating a Secure Storage Server in Hyper Protect Virtual Servers...... 140

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation ...... 143 6.1 Planning and prerequisites for Hyper Protect Virtual Servers on-premises ...... 144 6.2 Networking for Hyper Protect Virtual Servers ...... 149 6.2.1 Networking in Hosting Appliance (networking for Hyper Protect Virtual Servers containers) ...... 150 6.2.2 Creating an Ethernet interface ...... 151 6.2.3 Creating a VLAN interface ...... 155 6.3 Installation of Hyper Protect Virtual Servers components on-premises ...... 161 6.3.1 Preparing SSC LPAR for Hyper Protect Virtual Servers...... 161 6.3.2 Pushing the base images to the Docker repository...... 175 6.3.3 Secure Build Container ...... 177 6.3.4 Enabling monitoring on SSC LPAR...... 184 6.3.5 Integrating with EP11 Library (GREP11) ...... 186 6.4 Public Cloud service instantiation ...... 191

Chapter 7. IBM Hyper Protect Virtual Servers key features ...... 195 7.1 User roles in Hyper Protect Virtual Servers...... 196 7.2 Trusted CI/CD: Building and deploying containers securely ...... 197 iv Securing Your Critical Workloads with IBM Hyper Protect Services 7.2.1 Importance of establishing a trusted CI/CD pipeline...... 197 7.2.2 Trusted CICD pipeline architecture...... 198 7.2.3 Using the secure build application to build and store an image in a repository . 198 7.2.4 Building an image from a trusted base image...... 205 7.3 Monitoring ...... 206 7.3.1 Deploying a monitoring container ...... 206 7.3.2 Viewing the metrics from the monitoring service ...... 208 7.4 GREP11 (EP11 over gRPC) ...... 210 7.4.1 Checking the LPAR for GREP11 support ...... 210 7.4.2 Deploying a GREP11 container ...... 211 7.4.3 Adding GREP11 functionality into your applications...... 214 7.5 Bring Your Own Image (Trusted Repository Registration) ...... 216 7.5.1 Registering a repository as a trusted repository ...... 216 7.5.2 Creating a repository registration file for a repository to which a Secure Build Instance pushes images ...... 217 7.5.3 Creating a repository registration file to which a generic build server pushes images 217 7.5.4 Registering a repository on your SSC LPAR using the repository registration file . . 219 7.5.5 Registering repository by using public key and private key (optional) ...... 219 7.5.6 Deploying a securely built image from a trusted repository ...... 222

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services ...... 227 8.1 Secure Bitcoin Wallet ...... 228 8.1.1 Procure Hyper Protect Services in the IBM Cloud ...... 229 8.1.2 Logging in to your Hyper Protect Virtual Server and cloning the code repository 229 8.1.3 Building the wallet docker image...... 230 8.1.4 Running the wallet container...... 230 8.1.5 Using and testing the wallet ...... 231

Appendix A. Additional material ...... 239 Locating the GitHub material ...... 239 Cloning the GitHub material ...... 239

Related publications ...... 241 IBM Redbooks ...... 241 Online resources ...... 241 Help from IBM ...... 243

Contents v vi Securing Your Critical Workloads with IBM Hyper Protect Services Notices

This information was developed for products and services offered in the US. This material might be available from IBM in other languages. However, you may be required to own a copy of the product or product version in that language in order to access it.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive, MD-NC119, Armonk, NY 10504-1785, US

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk.

IBM may use or distribute any of the information you provide in any way it believes appropriate without incurring any obligation to you.

The performance data and client examples cited are presented for illustrative purposes only. Actual performance results may vary depending on specific configurations and operating conditions.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

Statements regarding IBM’s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to actual people or business enterprises is entirely coincidental.

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided “AS IS”, without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at “Copyright and trademark information” at http://www.ibm.com/legal/copytrade.shtml

The following terms are trademarks or registered trademarks of International Business Machines Corporation, and might also be trademarks or registered trademarks in other countries.

FICON® Parallel Sysplex® System z® IBM® Passport Advantage® z/OS® IBM Cloud™ POWER® z/VM® IBM Research™ Redbooks® IBM Z® Redbooks (logo) ®

The following terms are trademarks of other companies:

ITIL is a Registered Trade Mark of AXELOS Limited.

The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the exclusive licensee of Linus Torvalds, owner of the mark on a worldwide basis.

Java, and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Ansible, OpenShift, Red Hat, are trademarks or registered trademarks of Red Hat, Inc. or its subsidiaries in the United States and other countries.

VMware, VMware vSphere, and the VMware logo are registered trademarks or trademarks of VMware, Inc. or its subsidiaries in the United States and/or other jurisdictions.

Other company, product, or service names may be trademarks or service marks of others.

viii Securing Your Critical Workloads with IBM Hyper Protect Services Preface

Organizations must incorporate secure design practices in their development operations and embrace DevSecOps to protect their applications from the vulnerabilities and threat vectors that can compromise their data and potentially threaten their business.

IBM® Cloud Hyper Protect Services provide built-in data-at-rest and data-in-flight protection to help developers easily build secure cloud applications by using a portfolio of cloud services that are powered by IBM LinuxONE.

The LinuxONE platform ensures that client data is always encrypted, whether at rest or in transit. This feature gives customers complete authority over sensitive data and associated workloads (which restricts access, even for cloud admins) and helps them meet regulatory compliance requirements. LinuxONE also allows customers to build mission-critical applications that require quick time to market and dependable rapid expansion.

The purpose of this IBM Redbooks® publication is to: Introduce the IBM Hyper Protect Services that are running on IBM LinuxONE on the IBM Cloud™ and on-premise Provide high-level design architectures Describe deployment best practices Provide guides to getting started and examples of the use of the Hyper Protect Services

The target audience for this book is IBM Hyper Protect Virtual Services technical specialists, IT architects, and system administrators.

This book was produced by a team of specialists from around the world working at IBM Redbooks, Poughkeepsie Center.

Barry Silliman is a Consulting IT Specialist at the IBM Washington Systems Center in Herndon, Virginia, US. He is focused on enabling solutions, such as IBM Blockchain and Hyper Protect Services, on the IBM Z® and LinuxONE platforms. He has 36 years of experience in the IT industry (33 with IBM) and has held various support, testing, and development roles in systems and applications on mainframe and distributed platforms. Barry has a passion for educating and enabling others on new technologies and enjoys the constant challenge of explaining complex technical subjects in simple terms to his students and clients.

Diana Henderson is an Offering Manager in IBM Z as a Service organization that is focused on secure enclave technology deployments on IBM Z and LinuxONE servers. Previously, she held Offering Management positions in IBM Z hardware, Insurance, and Parallel Sysplex®, and technical roles in IBM Z and POWER® microprocessor development. Diana is an IBM Corporate Service Corps alumnus, having recently completed an assignment that focused on Education in Brazil.

Elton de Souza is the Chief Architect, Cloud Native Client Success on IBM Z where he leads OpenShift client engagements in-field by bootstrapping OCP on-premises and helping clients accelerate their cloud native modernization journey on the IBM Z and IBM LinuxONE platform. Although his primary focus is OpenShift on IBM Z, he brings integration skills with z/OS® Connect, z/OS Cloud Broker integration, public cloud (AWS) and cross-platform devOps. He has spent his entire career at IBM on the IBM Z platform, the first half being on the internals of IBM Java (garbage collection, virtual machine, and just-in-time compiler), followed by his work leading the IBM Z Ecosystem Innovation Lab where he focused on the use of open source software (OSS), such as Docker, Kubernetes, Spark, and MongoDB, with IBM Z based enterprises. He was then part of the Z-as-a-Service Innovation Lab that led to his current role of leading and executing on Cloud Native client engagements on the platform.

Jin VanStee is a technical sales and enablement leader in North America, focused on blockchain and Hyper Protect on IBM System z® and LinuxONE. She has 18 years of experience with IBM working on Linux and Z, and various enterprise software and cloud solutions. Before her current role, Jin worked as a systems and integration tester, as a client architect covering public and healthcare clients, and as a transformation leader. Jin is also a IBM Certified Executive IT Specialist.

x Securing your critical workloads with IBM Hyper Protect Services Jordan Cartwright is a Software Engineer in the US. He has 2 years of experience with IBM, working on Hyper Protect DBaaS, specializing in automation for Solution Test. His areas of expertise include CI/CD integration, build automations, API integration, and Python development.

Madhuri Gangireddy is a Software Engineer working in IBM systems from past 4 years. She is focused on the development of Hyper Protect Virtual Server on-premises solution for IBM Z systems. Her areas of expertise are in manual testing, CI/CD, Jenkins, and automating test scripts by using python and shell.

Matt Mondics is a technical specialist with the IBM Washington Systems Center who focuses on Red Hat OpenShift for IBM Z and related technologies, including IBM Secure Service Containers and Hyper Protect Services. Matt works with clients through demos, workshops, and Proofs of Concept to modernize IBM Z and LinuxONE environments to include containerized workloads through the use of private and public cloud platforms.

Matthew Arnold is a software engineer based at the IBM Hursley research and development laboratory in the United Kingdom. He has 8 years of experience developing software for IBM Linux on Z/LinuxONE and IBM Storage. His current focus for development is Hyper Protect Services for public cloud and private cloud. His areas of expertise include agile software development, cloud platform development, CI/CD, and system test.

Ravi Kumar Gullapalli is the Architect of IBM Hyper Protect Virtual Servers for on-premise. He has approximately 20 years of IT experience in the areas of Enterprise System software Research and Development designing and developing enterprise software, Virtualization, Private Cloud, Converged IT Systems, Security Services management, Threat modelling, SaaS/PaaS platform and services, workflow engine, and control systems design in hard disk drives for manufacturing and HP Non-Stop Enterprise platforms.

Preface xi Sandeep Ambekar is a Senior Manager at the IBM India Systems Lab, Bengaluru, India. He is responsible for Release Management and Development of Z Private Cloud Product, including Hyper Protect Virtual Server. He has 20 years of experience in the field of Systems Software and Firmware development, focused towards Virtualization, Enterprise Storage, Server, and on-premise cloud platforms and solutions.

Sandeep Sarkar is Software Engineer based at IBM India System Development Labs in Bengaluru, India. He has 7 years of experience in developing software for the financial and telecoms industries. He has been a microservice developer for 3 years and is a cloud native engineer. His main area of expertise are in logging and monitoring using ELK stack, CI/CD using Jenkins, automating using Python and Ansible, and containerizing and orchestrating using Docker and Kubernetes. He also enjoys troubleshooting and debugging. He is currently focused in development of Hyper Protect Virtual Server on-premise solution for Z systems.

Sarath Chandra Mekala is a Principal Engineer working with IBM India System Development Labs. He has approximately 18 years of experience developing highly scalable and resilient enterprise solutions, network security, and virtualization and micro services for public and private clouds. He has been a contributor to OpenStack Firewall as a Service and has been a tech evangelist and speaker at various OpenStack forums. Sarath is passionate about cloud security and is currently focused on developing IBM Hyper Protect Virtual Servers.

Vasfi Gucer is an IBM Redbooks Project Leader with the IBM International Technical Support Organization. He has more than 20 years of experience in the areas of systems management, networking hardware, and software. He writes extensively and teaches IBM classes worldwide about IBM products. His focus has been on cloud computing for the last 7 years. Vasfi is also an IBM Certified Senior IT Specialist, Project Management Professional (PMP), IT Infrastructure Library (ITIL) V2 Manager, and ITIL V3 Expert.

Qi Ye is an Executive IT Specialist at the IBM China Systems Lab. He is responsible for GCG and worldwide offering enablement for cloud, virtualization, and Linux on IBM LinuxONE and System Z. He has 15 years of mainframe and Linux experience with IBM, including Linux, z/VM®, KVM, z/OS, open sources software like OpenStack, and Kubernetes. Qi focuses on IBM Z and LinuxONE IT infrastructure, resiliency and cloud offerings, and solutions. Before he accepted the role at IBM Z and LinuxONE WW Offering Enablement, he worked in the IBM China Development Lab and IBM Growth Markets Unit.

xii Securing your critical workloads with IBM Hyper Protect Services Thanks to the following people for their contributions to this project:

Robert Haimowitz, Ann Lund, William White IBM Redbooks, Poughkeepsie Center

Rebecca Gott, Bryan Foley, Henry Welborn, Karunakar Bojjireddy, Mark Ver, John Harrison, Shalawn King, Stuart B. Tener, Paul Ayer IBM USA

Horst Hummel, Marco Pavone IBM Germany

Chris Poole, Will Chorlton, Jennifer Francis, Brian Venn, Tong Luo IBM UK

Volodymyr Paprotski IBM Canada

Xiao Yi Tian , Sibo Niu IBM China

Prabhat Ranjan IBM India

Now you can become a published author, too!

Here’s an opportunity to spotlight your skills, grow your career, and become a published author—all at the same time! Join an IBM Redbooks residency project and help write a book in your area of expertise, while honing your experience using leading-edge technologies. Your efforts will help to increase product acceptance and customer satisfaction, as you expand your network of technical contacts and relationships. Residencies run from two to six weeks in length, and you can participate either in person or as a remote resident working from your home base.

Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Comments welcome

Your comments are important to us!

We want our books to be as helpful as possible. Send us your comments about this book or other IBM Redbooks publications in one of the following ways: Use the online Contact us review Redbooks form found at: ibm.com/redbooks Send your comments in an email to: [email protected]

Preface xiii Mail your comments to: IBM Corporation, IBM Redbooks Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400

Stay connected to IBM Redbooks

Find us on Facebook: http://www.facebook.com/IBMRedbooks Follow us on Twitter: http://twitter.com/ibmredbooks Look for us on LinkedIn: http://www.linkedin.com/groups?home=&gid=2130806 Explore new Redbooks publications, residencies, and workshops with the IBM Redbooks weekly newsletter: https://www.redbooks.ibm.com/Redbooks.nsf/subscribe?OpenForm Stay current on recent Redbooks publications with RSS Feeds: http://www.redbooks.ibm.com/rss.html

xiv Securing your critical workloads with IBM Hyper Protect Services 1

Chapter 1. Introduction to IBM Hyper Protect Services

This chapter introduces the IBM Hyper Protect Services and includes the following topics: 1.1, “Industry and IBM Hyper Protect Services portfolio overview” on page 2 1.2, “Hyper Protect Crypto Services” on page 2 1.3, “Hyper Protect Database as a Service” on page 3 1.4, “Hyper Protect Virtual Servers” on page 4 1.5, “Hyper Protect Virtual Servers (on-premises)” on page 5 1.6, “Security features” on page 6

Organizations worldwide face challenges in protecting their enterprise. As malicious actors continue to evolve their methods to leverage vulnerabilities in enterprise systems, organization’s enterprise data remains at risk of breach. When considering the move to cloud, organizations come to expect that services operate in an always-on state and are quick to switch providers if they experience response times and uptimes that does not meet their expectations. Downtime can cost a brand its image, loyalty, and ultimately revenue.

Security and data protection are two of the biggest inhibitors to organizations that are moving sensitive data and applications to the cloud. No organization wants to be featured in the headlines because of a data breach. With data privacy laws emerging across all industries and worldwide, companies can find themselves liable to pay fines in the millions of dollars or even a percentage of their revenue (whichever is higher); therefore, the financial implications are significant.

When we think more about a company’s data, it is their intellectual property and their competitive differentiation. Organizations must protect their client data not only from a reputation consideration, but also because of audit requirements and the governance of consumer privacy laws. Ultimately, clients are faced with the opportunity, flexibility, and agility that cloud brings, but also must consider their security standards.

To address these concerns, IBM introduced the IBM Hyper Protect Services, which is a portfolio of services. This portfolio protects an enterprise’s most critical data while delivering cloud agility with the qualities of service that many organizations trusted for years to run their core workloads in their own data center.

The Hyper Protect Services are available in the IBM Cloud, deployed to IBM LinuxONE servers. These services are available in three multi-zone region sites worldwide (Dallas, Frankfurt, and Sydney) where each multi-zone-region (MZR) contains three availability zones or physical data centers with the LinuxONE hardware. If any disruption in service occurs, the clients’ data is backed up, protected, and can failover to another availability zone.

The following IBM Hyper Protect Services portfolio offerings are available: IBM Cloud Hyper Protect Crypto Services IBM Cloud Hyper Protect Database as a Service (DBaaS) IBM Cloud Hyper Protect Virtual Servers IBM Hyper Protect Virtual Servers (on-premises)

For more information, see this web page.

1.2 Hyper Protect Crypto Services

Enterprises are concerned about data security and compliance in the cloud, so encryption of that data becomes an imperative. However, this issue raises the following key challenges: Customers want to use their own key to encrypt, but who will manage and access those keys? Application developers want to focus on their application development without having to become security experts

2 Securing Your Critical Workloads with IBM Hyper Protect Services The IBM Cloud Hyper Protect Crypto Services delivers on both of these needs by offering key management and encryption application programming interfaces (APIs) to manage access to data and the lifecycle of encryption keys. Delivering on both of these needs is competitively differentiated when compared to other solutions that offer only one of the two capabilities.

Hyper Protect Crypto Services enables customers to control their cloud data encryption keys and cloud Hardware Security Module (HSM), which is built on industry-leading FIPS 140-2 Level 4 certified hardware. Built on LinuxONE technology, the service ensures that no one, including cloud administrators can access a user’s keys.

Another key capability is Keep Your Own Key (KYOK), compared to what is more common in the industry, Bring Your Own Key (BYOK). BYOK requires that users trust another entity to handle their keys when bringing them to the cloud. Conversely, with KYOK, users can maintain control of their keys. A client integrates them direct to the HSM as opposed to handing them over to a program that then stores the keys. In this manner, a user can keep their own data encryption keys with a dedicated customer-controlled HSM.

By using Hyper Protect Crypto Services, developers can design and code applications with a standard API that requests encryption. This feature enables organizations to invoke security without their development teams needing to become encryption experts. Data integrity is enabled through digital signing and confidentiality from the data encryption. Applications can use Public Key Cryptographic Standards 11 (PKCS #11) library to perform specific cryptographic functions, such as digital signing and validation and Security Socket Layer (SSL) offloading.

In addition, this service is built with a cloud CLI for the HSM Key Ceremony process for the user to take ownership of the cloud HSM. The service uses the same key provider API as IBM Key Protect, which is the multi-tenant key management service that provides a consistent approach for adopting IBM Cloud services.

Hyper Protect Crypto Services can also integrate with IBM Cloud data and storage services and VMware vSphere and Virtual SAN (VSAN) for providing data at rest encryption.

For more information about Hyper Protect Crypto Services, see Chapter 2, “IBM Cloud Hyper Protect Crypto Services” on page 29 and this web page.

1.3 Hyper Protect Database as a Service

The IBM Cloud Hyper Protect Database as a Service (DBaaS) solution allows for the provisioning and management of highly secured databases to provide data confidentiality to mission critical workloads without the need for a traditional Database Administrator (DBA) to maintain it.

Imagine a development organization wants to build an application in the cloud; however, with security top of mind and organizational concerns about cloud, management is instead considering pulling the application back behind the firewall for protection. It might even be necessary to get sign off on the architecture from the Chief Security Officer who considers the following key questions: Is our customer’s data safe in the cloud? How can we ensure that the data is protected from internal and external threats? Will it integrate well? How easy will it be to get started? Can we get the same level of security and performance in the cloud as we do with our on-premises solution today?

Chapter 1. Introduction to IBM Hyper Protect Services 3 Hyper Protect DBaaS offers complete data confidentiality for data that is hosted in the cloud so that even the cloud administrators cannot access customer data. The solution is deployed on IBM LinuxONE technology with industry-leading data confidentiality through built-in workload isolation, restricted administrator access, tamper protection from privileged user access, with vertical and scale and performance, all to enable users to maintain complete control over their data in the cloud.

This service offers standard APIs to provision, manage, maintain, and monitor multiple databases. This solution is built with High Availability where every deployment is built as a highly available clustered configuration, including three-node clusters (1 primary, 2 replica) with each deployed instance that is hosted on LinuxONE in a Multi-Zone Region (MZR) setup within an IBM Cloud region, which daily automated backups. Hyper Protect DBaaS also supports industry certifications, such as the General Data Privacy Regulation (GDPR) and clients’ regulatory compliance activities.

Currently, the following options are available: IBM Hyper Protect DBaaS for MongoDB IBM Hyper Protect DBaaS for PostgreSQL

For more information about IBM Hyper Protect DBaaS, see Chapter 3, “IBM Cloud Hyper Protect DBaaS” on page 95, and see this web page.

1.4 Hyper Protect Virtual Servers

The adoption of cloud brought rapid business changes over the past decade. What remains is a challenge in the migration of workloads and data from highly regulated industries, such as Financial Services, healthcare, telecommunications, and government. Market analysis shows that 80% of workloads are still being run on-premises given concerns about moving sensitive data to the cloud and risk of data compromise.

For example, healthcare is a multi-trillion dollar industry in the United States and features unique challenges when it comes to securing data. With medical records of millions of people, health systems are regulated by tight federal laws, such as Health Insurance Portability and Accountability Act (HIPAA) and General Data Protection Regulation (GDPR).

However, as the healthcare structure continues to evolve, healthcare companies are pressured to adapt. Examples of this adaptation include moving sensitive data to the cloud and taking advantage of the latest technology in the hopes of reducing costs and improving patient outcomes.

Naturally, these changes are attracting critics amid heightened attention to data privacy, and the healthcare industry is not alone in hesitating to move to cloud.

Hyper Protect Virtual Servers is an offering that alleviates these concerns.

IBM Cloud Hyper Protect Virtual Servers is the industry’s first customer-managed, LinuxONE-based virtual server platform in the public cloud. It provides customers with complete authority over their LinuxONE-based workloads without the cloud administrators accessing their data. Customers manage their LinuxONE-based workloads through users who instantiate their own Linux virtual servers with their own public SSH key to maintain. Users can build their applications and create development and test environments and use them for Disaster Recovery (DR) or geographic expansions where a client wants a presence but cannot build a complete data center on their own.

4 Securing Your Critical Workloads with IBM Hyper Protect Services As LinuxONE-based virtual servers on the IBM Cloud, Hyper Protect Virtual Servers include security that is enforced at the hardware layer, not just depending on software policies or operational best practices. Only the user who provisioned the virtual server with their public SSH key can access it (not even the cloud administrators are granted this access).

With IBM LinuxONE and Secure Service Container technology, Hyper Protect Virtual Servers provide built-in pervasive encryption of data at rest and in flight and tamper protection from inside and outside threats. This feature can give organizations peace of mind that highly sensitive data, such as medical records, are protected always.

Hyper Protect Virtual servers also give users high reliability and availability for mission critical applications. Workloads are deployed on highly performance Linux virtual machines, and an instance can be built as a highly available cluster with Multi-Zone Region support. Overall, IBM Cloud Hyper Protect Virtual Servers offers users complete control and hyper security, without compromising performance.

For more information, see Chapter 4, “IBM Cloud Hyper Protect Virtual Servers” on page 119, and this web page.

1.5 Hyper Protect Virtual Servers (on-premises)

Hyper Protect Virtual Servers Offering delivers unique security capabilities to protect applications on-premises deployed to IBM LinuxONE or IBM Z servers.

Many organizations must protect their mission-critical applications in production, but security threats can also surface during the development and pre-production phases. Also, during deployment and production, insiders who manage the infrastructure that hosts critical applications might pose a threat because of their super-user credentials and level of access to secrets or encryption keys. Organizations must incorporate secure design practices in their development operations and embrace DevSecOps to protect their applications from the vulnerabilities and threat vectors that can compromise their data and potentially threaten their business.

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

Hyper Protect Virtual Servers enables the following security benefits: Developers to securely build their applications in a trusted environment with integrity IT infrastructure providers to manage the servers and virtualized environment where the applications are deployed without having access to those applications or their sensitive data Application users to validate that those securely built applications originate from a trusted source by integrating this validation into their own auditing processes Chief Information Security Officers (CISOs) to be confident that their data is protected and private from internal and external threats

Chapter 1. Introduction to IBM Hyper Protect Services 5 1.5.1 Building images with integrity: Securing continuous integration and continuous delivery

Developers can securely build their own applications by using the Hyper Protect Virtual Servers secure build Continuous Integration Continuous Delivery (CICD) pipeline flow to sign their applications and sign and encrypt the application configuration information. Through this CICD, developers can validate the code that is used to build their images and reassure their users of the integrity level of their applications.

Hyper Protect Virtual Servers can also use the IBM Crypto Express hardware security module with FIPS 140-2 Level 4-certified cryptographic capabilities to generate public or private key pairs for signing and encrypting the securely built, and signed application images that are deployed as virtual servers.

1.5.2 Managing infrastructure with least privilege access to applications and data

After deploying signed Hyper Protect Virtual Servers images, infrastructure providers can manage the underlying infrastructure that hosts the images without accessing the application’s sensitive data to ensure separation of duties and access. The Hyper Protect Virtual Server image, which is deployed in a Secure Service Container appliance, can be managed by using: Only RESTful APIs alone Disabled Secure Shell (SSH) for production builds Enabled SSH for development builds

Multiple management options provide provides a flexible choice in access level to match the lifecycle stage of the application.

1.5.3 Deploying images with trusted provenance

The origin of Hyper Protect Virtual Servers images can be validated to ensure that the image to be deployed and its components come from a trusted source, such as an ISV organization or internal development team. The images can be checked to verify that no back door is introduced during the image build. Users of Hyper Protect Virtual Servers application images can use an image’s manifest during an audit to approve an image for deployment.

For more information, see Chapter 5, “IBM Hyper Protect Virtual Servers on-premises” on page 125, and this web page.

1.6 Security features

The Hyper Protect services are based on Secure Service Container on IBM LinuxONE, which is the most secured platform in the industry. In this section, we describe the following security features that are used by the Hyper Protect services: Cryptography Secure Service Container Encryption key management

6 Securing Your Critical Workloads with IBM Hyper Protect Services 1.6.1 Cryptography

Hyper Protect services on IBM Cloud and on-premises are hosted on the most secure platform; that is, IBM LinuxONE. In this section, we describe some cryptographic concepts to help you understand some security features on this platform.

Keys In modern cryptography, keys must be kept secret. Depending on the effort that is made to protect the key, keys are classified into the following levels: A clear key is a key that is transferred from the application in clear text to the cryptographic function. The key value is stored in the clear (at least briefly) somewhere in unprotected memory areas. Therefore, the key can be made available to someone under certain circumstances who is accessing this memory area. This risk must be considered when clear keys are used. However, many applications exist where this risk can be accepted. For example, the transaction security for the (widely used) encryption methods Secure Sockets Layer (SSL) and Transport Layer Security (TLS) is based on clear keys. The value of a protected key is stored in only clear in memory areas that cannot be read by applications or users. The key value does not exist outside of the physical hardware, although the hardware might not be tamper-resistant. The principle of protected keys is unique to IBM Z and LinuxONE systems. For a secure key, the key value does not exist in clear format outside of a special hardware device (HSM), which must be secured and tamper-resistant. A secure key is protected from disclosure and misuse, and can be used for the trusted execution of cryptographic algorithms on highly sensitive data. If used and stored outside of the HSM, a secure key must be encrypted with a master key, which is created within the HSM and never leaves the HSM. On IBM LinuxONE, secure keys are in IBM Crypto Express adapters, which is described in “IBM Crypto Express adapter”.

CP Assist for Cryptographic Functions On each processor unit, or core, of the LinuxONE server, an independent cryptographic coprocessor that is named CP Assist for Cryptographic Functions (CPACF) is available. The CPACF coprocessor is not classified as an HSM. It is not suitable for handling algorithms that use secure keys. However, it can be used for algorithms that use clear keys and protected keys.

The CPACF offers a set of symmetric cryptographic functions that enhances the encryption and decryption performance of clear key operations. CPACF is designed to facilitate the privacy of cryptographic key material when used for data encryption through key wrapping implementation. It ensures that key material is not visible to applications or operating systems during encryption operations. Because CPACF is on the same processor unit (PU), it runs at processor speed (5.2 GHz). Therefore, it is a fast cryptographic device that performs synchronous cryptographic operations.

CPACF offers a set of symmetric cryptographic functions (for example, AES and DES) that enhances the encryption and decryption performance of clear key operations. These functions are for SSL, virtual private network (VPN), and data-storing applications that do not require FIPS 140-2 Level 4 security.

CPACF can encrypt up to 13 GB of data per second per core. Using CPACF is shown to give performance improvements of up to 6x and is best suited for symmetric, high-speed bulk encryption.

Chapter 1. Introduction to IBM Hyper Protect Services 7 IBM Crypto Express adapter IBM Z and LinuxONE includes a PCIe cryptographic adapter feature that is exclusive to this platform, which is designed for FIPS 140-2 Level 4 certification. This feature is an HSM that is compliant with PCI-HSM certifications and provides a secure programming and hardware environment on which crypto processes are run. It provides tamper-sensing and tamper-responding high-performance cryptographic operations.

Each cryptographic adapter can be configured in one of the following configurations: Secure IBM CCA coprocessor (CEX7C) for FIPS 140-2 Level 4 certification. Accelerator (CEX7A) for acceleration of public key and private key cryptographic operations that are used with SSL/TLS processing. Secure IBM Enterprise PKCS #11 (EP11) coprocessor (CEX7P) implements an industry-standardized set of services that adheres to the PKCS #11 specification V2.20 and more recent amendments. This mode introduced the PKCS #11 secure key function. In EP11, keys can be generated and securely wrapped under the EP11 Master Key. A TKE workstation is always required to support the administration of the Crypto Express7S when it is configured in EP11 mode.

These modes can be configured by using the SE. The PCIe adapter must be configured offline to change the mode.

Trust Key Entry workstation The Trust Key Entry (TKE) workstation is an optional feature that offers key management functions. The TKE provides a secure, remote, and flexible method of providing Master Key Part Entry and to remotely manage PCIe cryptographic coprocessors. The cryptographic functions on the TKE are run by one PCIe cryptographic coprocessor. The TKE workstation communicates with the IBM Z or LinuxONE system through a TCP/IP connection. TKE securely manages multiple cryptographic modules that run in Common Cryptographic Architecture (CCA) or IBM Enterprise PKCS#11 (EP11) and use compliant-level hardware-based key management techniques from a single point of control.

8 Securing Your Critical Workloads with IBM Hyper Protect Services 1.6.2 IBM Secure Service Container

IBM Secure Service Container provides the base infrastructure on IBM LinuxONE for an integration of operating system, middleware, and software components, that are packaged to work autonomously and provide core services and infrastructure with focus on consumability and security.

Figure 1-1 shows an overview of the Secure Service Container.

Figure 1-1 Secure Service Container

The Secure Service Container focuses specifically on protections from misuse of privileged user credentials, and delivers this protection and other security capabilities that applications or code can use without changing the code. In addition, the Secure Service Container framework encrypts the underlying infrastructure data in flight and at rest, which prevents access to memory or processor state, deploys to a Logical Partition certified for EAL5+ level isolation, and prevents direct access to the embedded operating system. The Secure Service Container provides communication and management through well-defined APIs in the appliance framework.

Security mechanisms The following security mechanisms are also applied to protect the data in the Secure Service Container: Persistence data is encrypted by using the automatic file system encryption technology Linux Unified Key Setup (LUKS). The encryption keys are stored within appliances and are not accessible by administrators. Keys are managed based on the appliance lifecycle. The Docker container data that is mounted to disk is also encrypted.

Chapter 1. Introduction to IBM Hyper Protect Services 9 In-flight data is encrypted by using the automatic network encryption technology Transport Layer Security (TLS). Data is transferred through encrypted management REST API interfaces among Secure Service Container partitions. Diagnostic data is encrypted, which includes first-failure data capture (FFDC) data that is required to fix problems, dump data (including log message buffers) and so on. Such data is accessible to the service team only. Operating system access to the underlying Secure Service Container appliance is prohibited. Back doors to this host level are eliminated because SSH is disabled on the Secure Service Container partitions by default. Access to the cluster nodes are available by way of SSH keys that are protected by the cloud administrator. Users traditionally with operating system access cannot access application data and customer data.

Note: The IBM Secure Service Container encrypts your data at-rest and in-flight by way of CPACF on IBM LinuxONE at CPU speed. Optionally, to provide the most secure environment that is compliant with FIPS 140-2 Level 4 certification, it also uses PCI-HSM on LinuxONE for secure keys management by way of configuring the PCI-HSM, or crypto adapters, with the EP11 mode.

Encryption algorithms that are used for storage and data transport are provided by the IBM Secure Service Container in the IBM Hyper Protect Services.

IBM Hyper Protect Services are based on the Secure Service Container technology. They inherit all the security mechanisms that are provided by the Secure Service Container, as described in “Security mechanisms” on page 9.

Note: As of this writing, secure keys management in IBM Hyper Protect Services uses EP11 library and APIs, including IBM Cloud Hyper Protect Crypto Service and IBM Hyper Protect Virtual Servers on-premises.

10 Securing Your Critical Workloads with IBM Hyper Protect Services 2

Chapter 2. IBM Cloud Hyper Protect Crypto Services

key management and cloud hardware security module (HSM) to help you to take control of your cloud data encryption keys and cloud hardware security modules.

This chapter includes the following topics: 2.1, “Overview” on page 30 2.2, “Creating an instance of Hyper Protect Crypto Services on the public IBM Cloud” on page 30 2.3, “Using the Key Management Services feature of Hyper Protect Crypto Services” on page 59 2.4, “Using the GREP11 feature of Hyper Protect Crypto Services” on page 81 2.5, “Code examples” on page 86 2.6, “Hyper Protect Crypto Services use cases” on page 92

IBM Cloud Hyper Protect Crypto Services (Hyper Protect Crypto Services) is a dedicated key management service and hardware security module (HSM) that uses FIPS 140-2 Level 4 certified hardware and is available in the public IBM Cloud.

The key management service that is offered by Hyper Protect Crypto Services uses the same API, called Key Protect API that is offered by another IBM Cloud service offering called Key Protect Services. Hyper Protect Crypto Services’ key management service feature the following advantages over the key management service that is offered by Key Protect Services: Hyper Protect Crypto Services clients each have a dedicated HSM crypto unit (a single-tenant model), whereas multiple Key Protect Services clients share an HSM (a multi-tenant model). The HSM devices that are used in Hyper Protect Crypto Services are certified at FIPS 140-2 Level 4, which is the highest protection level that is defined by the standard. The HSM devices that are used in the Key Protect Services are certified at FIPS 140-2 Level 3.

Note: For more information about the differences between the various FIPS 140-2 security levels, see this web page.

For more information about the official FIPS 140-2 specification, which is from the United States Government’s National Institute of Standards and Technology (NIST), see the NIST’s publication, Security Requirements for Cryptographic Modules.

Hyper Protect Crypto Services offers more functionality that is not available in Key Protect Services, called GREP11. This API allows cryptographic operations, such as key generation, for symmetric keys and asymmetric key pairs, encryption and decryption, hashing, and digital signatures to occur securely within the HSM.

2.2 Creating an instance of Hyper Protect Crypto Services on the public IBM Cloud

An instance of Hyper Protect Crypto Services can be created by using the IBM Cloud console (the IBM Cloud user interface that is available on the internet from your browser) or the IBM Cloud command line interface (CLI).

For more information, see the following resources: Creating an instance by using the IBM Cloud console Creating an instance by using the IBM Cloud CLI

For this chapter, we created an instance by using the IBM Cloud console, as described next.

30 Securing Your Critical Workloads with IBM Hyper Protect Services 2.2.1 Creating an instance by using the IBM Cloud console

For our example, we show you how to create an instance of Hyper Protect Crypto Services by using the IBM Cloud console, which is the user interface that is available at this website.

Tip: The authors used Chrome Version 79.0.3945.79 running on macOS Catalina version 10.15.1 for the figures and snippets of the IBM Cloud console that are shown in this chapter.

For more information about supported browsers, see this web page.

We assume that you have an IBM Cloud account with which you can perform the tasks that are shown in this chapter.

Logging in to your IBM Cloud account Browse to https://cloud.ibm.com and you should see a login window that is similar to the example that is shown in Figure 2-1.

Figure 2-1 IBM Cloud log in window

Enter your IBM Cloud user ID and click Continue to continue the authentication process.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 31 Listing your IBM Cloud resources After you are authenticated, click the Navigation Menu icon (the one with three horizontal bars, often referred to as a “hamburger menu”) in the upper left, and choose Resource List, as shown in Figure 2-2.

Figure 2-2 Navigation menu

32 Securing Your Critical Workloads with IBM Hyper Protect Services A window opens in which a list of resources is shown, which are grouped by category. If you are an IBM Cloud client, you might have resources available. The example that is shown in Figure 2-3 shows that our account does not have any resources defined.

Figure 2-3 Resource list

Finding Hyper Protect Crypto Services in the IBM Cloud catalog Click Catalog in the menu bar in the upper right of your IBM Cloud console, as shown in Figure 2-4.

Figure 2-4 Catalog link in menu bar

Chapter 2. IBM Cloud Hyper Protect Crypto Services 33 Select Security and Identity from the list of service categories on the left side of your IBM Cloud console, as shown in Figure 2-5.

Figure 2-5 Services categories

34 Securing Your Critical Workloads with IBM Hyper Protect Services Scroll down to find the tile for the Hyper Protect Crypto Services service (see Figure 2-6). Click it to begin the process of provisioning an instance of the service.

Figure 2-6 Tile for Hyper Protect Crypto Services

Choosing settings and creating your service instance Clicking the tile opens a window in which you can specify settings for your instance. We entered the following values: Select a region: We selected Dallas from the list of regions in which the service is available (Dallas, Sydney, and Frankfurt at the time this publication was written. More regions might host the service in the future). Service name: We entered a name of my-hpcs-instance. Resource group: We accepted the default. By using resource groups, you can organize your IBM Cloud account resources for access control and billing purposes. If you use this feature and use defined resource groups, select the suitable group (the choice is up to you). For more information about resource groups, see this web page. Tags: We left this field blank. Tags are optional. For more information, hover over the information tooltip that is next to the Tags label Number of crypto units: We selected 2 - (multi-zone for high availability). Although you can choose 1 unit for development or testing purposes, 2 is the minimum recommendation for production usage.

After you chose your settings, you might want to click View Terms in the Summary pane on the right or estimate your costs by using the link in the Summary pane.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 35 When you are ready, click Create in the Summary pane. Figure 2-7 shows an example of this window after it is completed with our settings.

Note: Figure 2-7 shows the price of the service at time of this writing. You might see a different price in your configuration.

Figure 2-7 Instance settings and Summary pane

After you click Create, your Hyper Protect Crypto Services instance is created and you see a Getting Started window that is similar to the example that is shown in Figure 2-8 on page 37. The next section describes how to use these Getting Started instructions to make your new instance usable.

36 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 2-8 Getting started

2.2.2 Getting your service instance ready for use

Before you begin working through this section, click Manage on the left side of the window. You find that your service instance is not ready to use yet. Notice the error message that is shown in Figure 2-9 that says “The HSM master key is not configured.”

Figure 2-9 HSM master key is not configured

Chapter 2. IBM Cloud Hyper Protect Crypto Services 37 Note: That error message, “HSM master key is not configured” is a succinct summary of what you need to do to make your Hyper Protect Crypto Services instance usable.

You have control over a master key for your crypto units. You create it, load it into your HSMs, and activate it. This master key never leaves the HSM. Even IBM Cloud administrators cannot retrieve this key.

The HSM is certified at Security Level 4 of the United States government’s Federal Information Processing Standard (FIPS) 140-2.Security Level 4 is the highest security level defined in this FIPS 140-2 standard.

For more information about the FIPS 140-2 specification, see SECURITY REQUIREMENTS FOR CRYPTOGRAPHIC MODULES.

FIPS 140-2 Level 4 means that the HSM responds to virtually all attempts at tampering by destroying all critical security parameters; that is, the master key. It is almost impossible for a malicious actor to steal your master key from the HSM.

Click Getting Started again to return to the Getting Started window and you can begin the process to get your instance ready. We went through this process and found it to be straightforward, but we think we can ease and enhance the experience for you by offering some tips, notes, and extra explanations along the way. Figure 2-10 is a repetition of Figure 2-8 on page 37, but we added callout letters to each step (and tips or notes or extra explanations where appropriate) for each callout letter.

Figure 2-10 Getting started with callout letters

38 Securing Your Critical Workloads with IBM Hyper Protect Services Note: Consider the following points: Our notes for each section are meant to supplement the instructions in the Getting Started page. We recommend that you read our tips for each section, and then perform the instructions for that section in the Getting Started page with our tips in mind. When clicking a link in the instructions, we recommend that you open the link in a new tab (often available by way of the menu by right-clicking in most browsers) so that you do not lose your place in the Getting Started page.

Tips for “a”: Verify API endpoint The box in the flowchart that is shown in Figure 2-10 on page 38 that corresponds to our callout letter “a” maps to Step 1 in the Before you begin section in the Getting Started page.

Installing IBM Cloud CLI if necessary The IBM Cloud command line interface (CLI) must be installed on your workstation for this step and all proceeding steps. You might question why step “b” is labeled “Set up CLI” if the CLI is required for step “a”. The reason is that step “b” likely is better named “Set up Key Protect plug-in” and we provide our justification for this opinion in the next section.

You can determine whether you have the IBM Cloud CLI installed by using the command that is shown in Example 2-1.

Example 2-1 ibmcloud command $ ibmcloud --version ibmcloud version 0.20.0+5d69177-2019-10-31T09:49:54+00:00

If you do not receive output that displays a version number, but instead receive a message indicating that ibmcloud command is not found, see this web page for more information about how to install the IBM Cloud CLI.

Important: You must ensure that you can successfully run the command that is shown in Example 2-1 before you can perform any of the remaining tasks necessary to get your service instance ready to use.

Finding the name of your region If you created your service instance by using the IBM Cloud console as we suggested, you selected one of the regions that were available at the time of this writing: Dallas, Sydney, or Frankfurt.

Step 1 in the Before you begin section of the IBM Cloud dashboard specifies the ibmcloud target -r command in which we must supply the correct value for . Because choose Dallas for our instance, we tried the command as shown in Example 2-2; however, we received an error.

Example 2-2 ibmcloud target command $ ibmcloud target -r dallas FAILED Could not get region: Region 'dallas' was not found.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 39 You can run the command that is shown in Example 2-3 to list the available regions, which shows a mapping of Display name to Name for the various regions.

Example 2-3 Listing available regions $ ibmcloud regions Listing regions...

Name Display name au-syd Sydney in-che Chennai jp-osa Osaka jp-tok Tokyo kr-seo Seoul eu-de Frankfurt eu-gb London us-south Dallas us-south-test Dallas Test us-east Washington DC $

Therefore, in our case, we were successful by running the command that is shown in Example 2-4.

Example 2-4 Targeting the correct region $ ibmcloud target -r us-south Switched to region us-south

Success criteria for “a”: Verify API endpoint Guided by the preceding tips, you should be able to successfully run the ibmcloud target command that is suitable to your region, which is similar to the example that is shown in Example 2-4.

Tips for “b”: Set up CLI The box in the flowchart that is shown in Figure 2-10 on page 38 that corresponds to our callout letter “b” maps to Step 2 in the Before you begin section in the Getting Started window of the IBM Cloud dashboard.

The following IBM Cloud CLI plug-ins are applicable to a Hyper Protect Crypto Services instance: The IBM Cloud CLI Key Protect plug-in The installation of this plug-in is described next. The IBM Cloud CLI Trusted Key Entry plug-in The installation of this plug-in is described in “Tips for “c”: Installing TKE plug-in” on page 42.

Displaying your installed plug-ins first You can run the command that is shown in Example 2-5, which shows the plug-ins that are installed. You can see that the list does not include the Key Protect plug-in.

Example 2-5 ibmcloud plug-in list $ ibmcloud plugin list

40 Securing Your Critical Workloads with IBM Hyper Protect Services Listing installed plug-ins...

Plugin Name Version Status cloud-functions/wsk/functions/fn 1.0.36 cloud-object-storage 1.1.1 container-registry 0.1.437 container-service/kubernetes-service 0.4.64 dev 2.4.0 $

Follow the instructions in the first link to install the Key Protect plug-in Click the first link in Step 2 in the Before you begin section of the IBM Cloud dashboard. This link is under the words: Install the IBM Key Protect for IBM Cloud plug-in.

You are directed to enter several commands. Example 2-6 shows our output after we entered the command to install the Key Protect plug-in. Your output should be similar, although your version number might differ.

Example 2-6 Installing the Key Protect plug-in $ ibmcloud plugin install key-protect -r 'IBM Cloud' Looking up 'key-protect' from repository 'IBM Cloud'... Plug-in 'key-protect/kp 0.3.9' found in repository 'IBM Cloud' Attempting to download the binary file... 11.64 MiB / 11.64 MiB [======] 100.00% 3s 12210532 bytes downloaded Installing binary... OK Plug-in 'key-protect 0.3.9' was successfully installed into /Users/silliman/.bluemix/plugins/key-protect. Use 'ibmcloud plugin show key-protect' to show its details. $

Optional: Skip the link for setting up the CLI The second section in Step 2 of the Before you begin section of the IBM Cloud dashboard reads After installation, see Setting up the CLI for detailed configuration steps. You can skip clicking this link for now because you do not need to use the Key Protect plug-in for any of the other steps to get your instance ready to use (you use only the Trusted Key Entry plug-in for this process). For more information about the use of and setting up the Key Protect plug-in, see 2.3, “Using the Key Management Services feature of Hyper Protect Crypto Services” on page 59.

Success criteria for “b”: Set up CLI Run the ibmcloud plugin show key-protect command and you see output that is similar to what is shown in Example 2-7.

Example 2-7 Show Key Protect plug-in information $ ibmcloud plugin show key-protect

Plugin Name key-protect Plugin Version 0.3.9 Plugin SDK Version 0.3.0

Chapter 2. IBM Cloud Hyper Protect Crypto Services 41 Minimal IBM Cloud CLI version required N/A

Commands: kp Manage encryption keys on IBM Cloud kp create Create a key or import your own key kp delete Delete a key. The key and its associated data are permanently deleted. This action cannot be undone. kp get Get a key. The key and its associated data will be displayed kp import-token Prepare your root key for a secure import kp list List the keys that are available in your service instance kp policy Manage policies that are associated with a key kp region-set Target a different Key Protect regional endpoint kp rotate Rotate a root key kp unwrap Unwrap a data encryption key kp wrap Wrap a data encryption key kp help Show help

Tips for “c”: Installing TKE plug-in The box in the flowchart that is shown in Figure 2-10 on page 38 that corresponds to our callout letter “c” maps to Step 3 in the Before you begin section in the Getting Started page of the IBM Cloud dashboard.

Example 2-8 shows our output from this step.

Example 2-8 Installing Trusted Key Entry plug-in $ ibmcloud plugin install tke Looking up 'tke' from repository 'IBM Cloud'... Plug-in 'tke 0.0.11' found in repository 'IBM Cloud' Attempting to download the binary file... 11.65 MiB / 11.65 MiB [======] 100.00% 2s 12213760 bytes downloaded Installing binary... OK Plug-in 'tke 0.0.11' was successfully installed into /Users/silliman/.bluemix/plugins/tke. Use 'ibmcloud plugin show tke' to show its details. $

Success criteria for “c”: Install TKE plug-in Run the ibmcloud plugin show tke command and you see output that is similar to what is shown in Example 2-9.

Example 2-9 Show Trusted Key Entry plug-in details $ ibmcloud plugin show tke

Plugin Name tke Plugin Version 0.0.11 Plugin SDK Version 0.3.0 Minimal IBM Cloud CLI version required N/A

Commands:

42 Securing Your Critical Workloads with IBM Hyper Protect Services tke A CLI plug-in to manage crypto units in the IBM Cloud tke mks Lists EP11 master key parts stored on this workstation. tke mk-add Creates and saves a new EP11 master key part. tke mk-rm Removes an EP11 master key part from this workstation. tke sigkeys Lists the signature keys stored on this workstation. tke sigkey-add Generates and saves a new signature key. tke sigkey-rm Removes a signature key from this workstation. tke sigkey-sel Selects the signature key to use to sign commands. tke cryptounits Displays the crypto units for the current resource group. tke cryptounit-add Adds crypto units to the set of crypto units to work with. tke cryptounit-rm Removes crypto units from the set of crypto units to work with. tke cryptounit-admins Lists administrators installed in the selected crypto units. tke cryptounit-admin-add Adds a crypto unit administrator to the selected crypto units. tke cryptounit-admin-rm Removes a crypto unit administrator from the selected crypto units. tke cryptounit-compare Compares configuration settings of the selected crypto units. tke cryptounit-exit-impr Exits imprint mode in the selected crypto units. tke cryptounit-zeroize Zeroizes the selected crypto units. tke cryptounit-mk Displays master key registers for the selected crypto units. tke cryptounit-mk-clrcur Clears the current master key register. tke cryptounit-mk-clrnew Clears the new master key register. tke cryptounit-mk-commit Commits the new master key register. tke cryptounit-mk-setimm Does set immediate on the master key registers. tke cryptounit-mk-load Loads the new master key register.

You can also enter the ibmcloud plugin list command and you see the key-protect and tke plug-ins listed in the output, as shown in Example 2-10.

Example 2-10 Listing all plug-ins $ ibmcloud plugin list Listing installed plug-ins...

Plugin Name Version Status container-registry 0.1.437 container-service/kubernetes-service 0.4.64 dev 2.4.0 key-protect 0.3.9 tke 0.0.11 cloud-functions/wsk/functions/fn 1.0.36 cloud-object-storage 1.1.1 $

Tips for “d”: Setting up local directory for key files The box in the flowchart that is shown in Figure 2-10 on page 38 that corresponds to our callout letter “d” maps to Step 4 in the Before you begin section in the Getting Started page of the IBM Cloud dashboard.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 43 Creating an empty directory for use with the TKE plug-in The TKE plug-in uses an environment variable that is named CLOUDTKEFILES to specify the directory where it stores artifacts and status information. We recommend that you create an empty directory so that only files of interest to the TKE plug-in are stored in it.

Example 2-11 shows the commands that we used to create a directory, switch to that directory, set the suitable environment variable (CLOUDTKEFILES) to this directory, and then show that our new directory is empty.

Example 2-11 Setting CLOUDTKEFILES to an empty directory $ mkdir tke-files $ cd tke-files $ export CLOUDTKEFILES=`pwd` $ tree .

0 directories, 0 files

Deciding whether to set CLOUDTKEFILES env variable “permanently” The instructions in this step describe how to set this environment variable permanently, the exact steps depend on your operating system. This step is not necessary if you want to set the environment variable each time you need it. However, if you decide not to set the environment variable permanently, ensure that you devise a means to remember which directory you used.

Success criteria for “d”: Setting up local directory for key files Ensure that the environment variable CLOUDTKEFILES is set to an existing directory, preferably one that you just created and so it is empty.

Tips for “e”: Displaying assigned crypto units The box in the flowchart that is shown in Figure 2-10 on page 38 that corresponds to our callout letter “e” maps to the first command that is listed in the Adding or removing crypto units that are assigned to a user account section in the Getting Started page of the IBM Cloud dashboard; that is, the ibmcloud tke cryptounits command

Targeting the suitable resource group If you enter the command as shown in the instructions in the IBM Cloud dashboard, you might receive an error message if you did not target a resource group previously. For example, we saw the error that is shown in Example 2-12.

Example 2-12 No resource group targeted $ ibmcloud tke cryptounits FAILED No resource group targeted.

Crypto units are associated with a resource group. Use 'ibmcloud target -g RESOURCE_GROUP' to target a resource group.

44 Securing Your Critical Workloads with IBM Hyper Protect Services The solution is to issue the command that was suggested in the error output, substituting RESOURCE_GROUP with the name of the resource group that you used when you defined your Hyper Protect Crypto Services instance. Because we used the default resource group, we issued the command that is shown in Example 2-13.

Example 2-13 Target a resource group $ ibmcloud target -g default Targeted resource group default

API endpoint: https://cloud.ibm.com Region: us-south User: Account: Resource group: default CF API endpoint: Org: Space:

Tip: If you are managing Cloud Foundry applications and services - Use 'ibmcloud target --cf' to target Cloud Foundry org/space interactively, or use 'ibmcloud target --cf-api ENDPOINT -o ORG -s SPACE' to target the org/space. - Use 'ibmcloud cf' if you want to run the Cloud Foundry CLI with current IBM Cloud CLI context.

Note: Consider the following points: You can find the resource groups that are associated with your IBM Cloud account by using the ibmcloud resource groups command. Your cryptounits likely include a value of “false” in the Selected column.

Enter the ibmcloud tke cryptounits command.

The sample output that is shown for this command in the Getting Started section of the IBM Cloud dashboard shows the cryptounits with a value of true in the Selected column. This outcome is unlikely to be the case for you because it is the next step that changes this value from false to true. Example 2-14 shows the output we received when we ran this command for the first time.

Example 2-14 Crypto Units before being selected $ ibmcloud tke cryptounits Verifying the OA certificate chain for serial number 93AAAURS... Successfully verified the OA certificate chain for 93AAAURS.

Verifying the OA certificate chain for serial number 93AAAP0L... Successfully verified the OA certificate chain for 93AAAP0L.

API endpoint: https://cloud.ibm.com Region: us-south User: Account: Resource group: default

SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3

Chapter 2. IBM Cloud Hyper Protect Crypto Services 45 CRYPTO UNIT NUM SELECTED LOCATION 1 false [us-south].[AZ3-CS3].[03].[09] 2 false [us-south].[AZ2-CS2].[03].[12]

Note: all crypto units in a service instance must be configured the same. Use 'ibmcloud tke cryptounit-compare' to check how crypto units are configured. $

Success criteria for “e”: Displaying assigned crypto units Ensure that your output from the ibmcloud tke cryptounits command looks similar to our output from Example 2-14 on page 45. Also, ensure that the number of crypto units that is shown matches the number you asked for when you created your service instance. It is acceptable if they show false in the Selected column; the next step in the process flow sets this status to true.

Tips for “f”: Adding crypto units The box in the flowchart that is shown in Figure 2-10 on page 38 that corresponds to our callout letter “f” maps to the second command that is listed in the Adding or removing crypto units section of the IBM Cloud dashboard that are assigned to a user account section in the Getting Started page: the ibmcloud tke cryptounit-add command

The two crypto units that are assigned to our instance both must be selected so that the TKE plug-in commands in subsequent steps are targeted to both crypto units, which is a necessary condition to load the Master Key. The ibmcloud tke cryptounit-add command is used to select the crypto units. A single invocation of the command will perform the following tasks: Display the current state of the crypto units (not selected) Prompt for the crypto units to select Display the state of the crypto units after selecting the unit numbers you enter at the prompt

Example 2-15 shows the output and prompts from our invocation of the command. At the end of the output, our crypto units have true for the Selected column, which is a necessary condition to proceed.

Example 2-15 ibmcloud tke cryptounit-add command $ ibmcloud tke cryptounit-add

API endpoint: https://cloud.ibm.com Region: us-south User: Account: Resource group: default

SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM SELECTED LOCATION 1 false [us-south].[AZ3-CS3].[03].[09] 2 false [us-south].[AZ2-CS2].[03].[12]

Note: all crypto units in a service instance must be configured the same. Use 'ibmcloud tke cryptounit-compare' to check how crypto units are configured.

Enter a list of CRYPTO UNIT NUM to add, separated by spaces:

46 Securing Your Critical Workloads with IBM Hyper Protect Services > 1 2 OK

API endpoint: https://cloud.ibm.com Region: us-south User: Account: Resource group: default

SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM SELECTED LOCATION 1 true [us-south].[AZ3-CS3].[03].[09] 2 true [us-south].[AZ2-CS2].[03].[12]

Note: all crypto units in a service instance must be configured the same. Use 'ibmcloud tke cryptounit-compare' to check how crypto units are configured. $

Note: The third command in the Adding or removing crypto units section of the IBM Cloud dashboard that are assigned to a user account section in the Getting Started page (that is, the ibmcloud tke cryptounit-rm command) is not necessary in this flow. This command changes crypto units from true to false in the Selected column. We are trying to go from false to true; therefore, this command does not need to be issued here.

Success criteria for “f”: Adding crypto units The end of the output from the preceding command from Example 2-15 on page 46 suggests using the ibmcloud tke cryptounit-compare command to ensure that the two crypto units are configured identically. This command can be used to ensure success in this step for the following reasons: The command fails if no crypto units in the Selected column are set to true. The command indicates at the bottom of the IBM Cloud dashboard if your selected crypto units are configured the same.

Your goal is to run the command that is shown in Example 2-16 and ensure that the number of crypto units that is shown in the command output matches your expectation. Also, that the end of the output shows the message: All crypto units are configured the same.

Example 2-16 ibmcloud tke cryptounit-compare command $ ibmcloud tke cryptounit-compare

IMPRINT MODE SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM IMPRINT MODE 1 Yes 2 Yes

CRYPTO UNIT ADMINISTRATORS SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM ADMIN NAME SUBJECT KEY IDENTIFIER 1 No administrators 2 No administrators

Chapter 2. IBM Cloud Hyper Protect Crypto Services 47 NEW MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Empty 00000000000000000000000000000000 00000000000000000000000000000000 2 Empty 00000000000000000000000000000000 00000000000000000000000000000000

CURRENT MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Empty 00000000000000000000000000000000 00000000000000000000000000000000 2 Empty 00000000000000000000000000000000 00000000000000000000000000000000

==> All crypto units are configured the same. <== $

Tip: If only one crypto unit is in your service instance (for example, for development or test purposes), you do not receive the “All crypto units are configured the same” message. Instead, you should receive the “Only one crypto unit is selected” message. However, it is still useful for you to run the command to learn more information about the current state of your single crypto unit.

In our example output, the two crypto units are configured the same, as expected. However, a close inspection of the output reveals the following conditions about the state of the crypto units that must change before they are ready for production use: The crypto units are in Imprint Mode. No administrators are authorized for the crypto units. No master keys are loaded into the crypto units.

We resolve these impediments to production use by using the commands that are in the remainder of the flow diagram that is shown in Example 2-15 on page 46.

Note: Imprint Mode allows unauthenticated commands to be targeted to the crypto unit. Fortunately, about the only useful thing you can do is to define one or more administrators to the crypto unit and then permanently exit Imprint Mode. Then, all commands must be authenticated with an administrator password.

Becoming familiar with the files in your ${CLOUDTKEFILES} directory At this point, two files are in the directory that is pointed to by your CLOUDTKEFILES environment variable. We show these two files by using the tree command (see Example 2-17).

Example 2-17 Listing of our TKE-related files directory $ cd ${CLOUDTKEFILES} $ tree . . ??? CRYPTOMODULES ??? DOMAINS

48 Securing Your Critical Workloads with IBM Hyper Protect Services 0 directories, 2 files

Tip: These two files store information in JSON format. We recommend installing the jq utility, which can make JSON much more readable.

For example, the raw content of our CRYPTODOMAINS file without the use of jq is shown in the following example:

$ cat CRYPTOMODULES [{"serial_num":"93AAAURS","public_key":"04015e2b3ca39cacc113b2ae0cc683b4e334dd2 b4e07834af537c6912d4e836fcd42c8997f63d3e2916dbdfef19dd361c23dc7a83e0b4fe5fdbc75 4eef355fdcc3938c0017da1b575220240e53f90e5508e84cfc1496126f2596771b6b15af68e7b5e a7c999a45cd30359c57bde535e61d9bda80c89de7f430c79467c8405541f2b66b0a02"},{"seria l_num":"93AAAP0L","public_key":"0401b36988b53e19954daecbc5295ba52cce85fe9886d0b 758c427d0da46c66b7ccae662cb8d65d04b8fd4bd2bfb7f16ba92b494fa0e1fa8531eff893ca2d0 0147df2b00145ce6db8f7975cd891f58bde48ef366079b20452da93fda0d07f650ace39eba78cd1 60b1978e5257e2e06ba3c6389201ada7c621eb9d46c4972db1845a363e9d9"}]

The contents of the same file is shown with the use of the jq utility in the following example:

$ jq '.' CRYPTOMODULES [ { "serial_num": "93AAAURS", "public_key": "04015e2b3ca39cacc113b2ae0cc683b4e334dd2b4e07834af537c6912d4e836fcd42c8997f63d3 e2916dbdfef19dd361c23dc7a83e0b4fe5fdbc754eef355fdcc3938c0017da1b575220240e53f90 e5508e84cfc1496126f2596771b6b15af68e7b5ea7c999a45cd30359c57bde535e61d9bda80c89d e7f430c79467c8405541f2b66b0a02" }, { "serial_num": "93AAAP0L", "public_key": "0401b36988b53e19954daecbc5295ba52cce85fe9886d0b758c427d0da46c66b7ccae662cb8d65 d04b8fd4bd2bfb7f16ba92b494fa0e1fa8531eff893ca2d00147df2b00145ce6db8f7975cd891f5 8bde48ef366079b20452da93fda0d07f650ace39eba78cd160b1978e5257e2e06ba3c6389201ada 7c621eb9d46c4972db1845a363e9d9" } ]

For more information about installing jq on your operating system, search the topic by using your preferred search engine.

Tips for “g”: Creating signature keys The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “g” maps to Step 1 in the Loading Master Keys section in the Getting Started page of the IBM Cloud dashboard.

We are in Imprint Mode, but soon we exit Imprint Mode. After we leave that mode, all TKE plug-in commands that are send to the crypto units must be signed. In this step, we create signature keys that are used to sign commands when we are no longer in Imprint Mode.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 49 After we leave Imprint Mode, all TKE plug-in commands that are sent to the crypto units must be signed.

We created two signature keys: one with a user name of tke-admin and the second with a user name of tke-backup-admin. We also gave each signature key a unique, strong password.

After creating the keys, we observed three new files in our CLOUDTKEFILES directory, which are highlighted in bold in Example 2-18.

Example 2-18 TKE-related files directory after adding signature keys $ tree . ??? 1.sigkey ??? 2.sigkey ??? CRYPTOMODULES ??? DOMAINS ??? SIGKEYS

0 directories, 5 files

The two *.sigkey files are the signature key files. The SIGKEYS file contains metadata about both keys, as shown in Example 2-19.

Example 2-19 SIGKEYS metadata file $ jq '.' SIGKEYS { "1": "1.sigkey", "2": "2.sigkey" }

We used the ibmcloud tke sigkey-sel command to select the tke-admin key to be our signing key. Then, we observed that a new file named SELECTED was created. Example 2-20 shows the commands that we used.

Example 2-20 Selecting a signing key $ ibmcloud tke sigkey-sel

KEYNUM DESCRIPTION SUBJECT KEY IDENTIFIER 1 tke-admin 700228a495244bb232344ae668d1fc... 2 tke-backup-admin 329272e405f1547fbe7f757238f7a5...

A current signature key has not been selected.

Enter the KEYNUM to make the current signature key: > 1 Enter the password for the signature key file: > OK tke-admin (700228a495244bb232344ae668d1fc...) has been made the current signature key.

$ tree . .

50 Securing Your Critical Workloads with IBM Hyper Protect Services ??? 1.sigkey ??? 2.sigkey ??? CRYPTOMODULES ??? DOMAINS ??? SELECTED ??? SIGKEYS

0 directories, 6 files $ jq '.' SELECTED { "current-sigkey-fn": "1.sigkey", "ski": "700228a495244bb232344ae668d1fc912e8414b512a6aee3a6fdc3c45ba51b2b" }

Success criteria for “g”: Creating signature keys You should be able to use the commands that are described in Step 1 in the Loading Master Keys section in the Getting Started page of the IBM Cloud dashboard to create one or more signature keys. Then, you select one of those keys to be the current signature key, similar to what was shown in the examples in this section of the IBM Cloud dashboard.

Tips for “h”: Adding an administrator The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “h” maps to Step 2 in the Loading Master Keys section in the Getting Started page of the IBM Cloud dashboard.

We followed this section and made the following observations: We used the ibmcloud tke cryptounit-admins command to see that we had no administrators added to our crypto units. We assigned our primary administrator, tke-admin, to our crypto-units by using the ibmcloud tke cryptounit-admin-add command. We verified we were successful by using the ibmcloud tke cryptounit-admins command.

Success criteria for “h”: Adding an administrator You should be able to follow the pattern that we used to ensure that you have one or more administrators added to your crytpo units. You can use our commands and output as a guide, as shown in Example 2-21.

Example 2-21 Adding an administrator to crypto units $ ibmcloud tke cryptounit-admins

No crypto unit administrators for service instance 57e89643-f274-4a8d-9d37-74bd7dc67ee3 $ ibmcloud tke cryptounit-admin-add

KEYNUM DESCRIPTION SUBJECT KEY IDENTIFIER 1 tke-admin 700228a495244bb232344ae668d1fc... 2 tke-backup-admin 329272e405f1547fbe7f757238f7a5... tke-admin (700228a495244bb232344ae668d1fc...) is the current signature key.

Enter the KEYNUM of the administrator signature key you wish to load: > 1 Enter the password for the administrator signature key file:

Chapter 2. IBM Cloud Hyper Protect Crypto Services 51 > OK The crypto unit administrator was added to the selected crypto units. $ ibmcloud tke cryptounit-admins

SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM ADMIN NAME SUBJECT KEY IDENTIFIER 1 tke-admin 700228a495244bb232344ae668d1fc... 2 tke-admin 700228a495244bb232344ae668d1fc...

Tips for “i”: Exit imprint mode The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “i” maps to Step 3 in the Loading Master Keys section in the Getting Started page of the IBM Cloud dashboard.

Tip - run ibmcloud tke cryptounit-compare first Only a single command is listed in this step, but we encourage you to run the ibmcloud tke cryptounit-compare command first for the following reasons: You can observe that your crypto units are currently in Imprint Mode, which provides a contrast to when we suggest you run this command again for the success criteria for this step. You can see the administrators that you assigned to the crypto units.

Our example output is shown in Example 2-22.

Example 2-22 ibmcloud tke cryptounit-compare command while still in Imprint mode $ ibmcloud tke cryptounit-compare

IMPRINT MODE SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM IMPRINT MODE 1 Yes 2 Yes

CRYPTO UNIT ADMINISTRATORS SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM ADMIN NAME SUBJECT KEY IDENTIFIER 1 tke-admin 700228a495244bb232344ae668d1fc... 2 tke-admin 700228a495244bb232344ae668d1fc...

NEW MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Empty 00000000000000000000000000000000 00000000000000000000000000000000 2 Empty 00000000000000000000000000000000 00000000000000000000000000000000

CURRENT MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3

52 Securing Your Critical Workloads with IBM Hyper Protect Services CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Empty 00000000000000000000000000000000 00000000000000000000000000000000 2 Empty 00000000000000000000000000000000 00000000000000000000000000000000

==> All crypto units are configured the same. <==

Tip: Enter ibmcloud tke cryptounit-compare after exiting Imprint Mode After you run the ibmcloud tke cryptounit-exit-impr command per the Getting Started page, we recommend that you run ibmcloud tke cryptounit-compare again so that you can verify that your crypto units are no longer in Imprint Mode. Our output that is shown in Example 2-23 provides an indication that we have left Imprint Mode for our crypto units because of the value No in the IMPRINT MODE column near the top of the output.

Example 2-23 ibmcloud tke cryptounit-compare command after exiting Imprint mode $ ibmcloud tke cryptounit-compare

IMPRINT MODE SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM IMPRINT MODE 1 No 2 No

==> All crypto units are configured the same. <==

Chapter 2. IBM Cloud Hyper Protect Crypto Services 53 Success criteria for “i”: Exit imprint mode Ensure that the results of an ibmcloud tke cryptounit-compare command show that your crypto units are no longer in Imprint Mode.

Tips for “j”: Create master key parts The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “j” maps to Step 4 in the Loading Master Keys section in the Getting Started page.

Deciding how to create your master key parts The instructions in the Getting Started page offer the following ways to create master key parts: ibmcloud tke mk-add --random Generates and saves a random master key part ibmcloud tke mk-add --value Allows you to enter and save a known master key part

Unless you want to duplicate an existing master key (perhaps from an on-premises key infrastructure), we suggest that you choose the first alternative and allow the IBM Cloud TKE plug-in randomly generate a master key part for you.

You can create as many master key parts as you want. However, when you load a master key, you can specify only two or three key parts.

We show in Example 2-24 that we created five master key parts, although we can specify only two or three of them later when we load the master key.

Example 2-24 Listing master key parts with ibmcloud tke mks $ ibmcloud tke mks

KEYNUM DESCRIPTION VERIFICATION PATTERN 1 master-key-part-1 dfdaf6ae7b7be598a8c6235dad793f54 01ea7d6c1e27cce38688cfdfecbd2a5b 2 master-key-part-2 f377197929adbbffd97faff21e29d568 485032e96f6abb17be7d6e58b10f64ac 3 master-key-part-3 f0986375a4175394a6d51254e2c43a0f 619d1b40ba27e319e79dd4956cc278cc 4 master-key-part-4 17970848b3fabf86660f33032b0ef075 95d716cf1fd4a3f623244df121e360d3 5 master-key-part-5 40d3f6b3151424309e3c365c5b0058f9 2decbd7c1bcce0c3c0e4d5c18f0c746e

We also show in bold text in Example 2-25 the five individual key part files (*.mkpart) and then we display the contents of the MKPART file, which keeps track of these key part files.

Example 2-25 MKPART file $ tree . . ??? 1.mkpart ??? 1.sigkey ??? 2.mkpart ??? 2.sigkey

54 Securing Your Critical Workloads with IBM Hyper Protect Services ??? 3.mkpart ??? 4.mkpart ??? 5.mkpart ??? CRYPTOMODULES ??? DOMAINS ??? MKPARTS ??? SELECTED ??? SIGKEYS

0 directories, 12 files $ jq '.' MKPARTS { "1": "1.mkpart", "2": "2.mkpart", "3": "3.mkpart", "4": "4.mkpart", "5": "5.mkpart" }

Success criteria for “j”: Creating master key parts You do not have to create five master key parts as we did for our example, but you must create at least two key parts and list them by using the ibmcloud tke mks command, as we did in Example 2-25 on page 54. You should also create a strong password for each master key part and store this password securely.

Tips for “k”: Load new master key register The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “k” maps to Step 5 in the Loading Master Keys section in the Getting Started page.

Have your passwords ready When you load your master key parts, you need your administrator signature key password. Then, you need the passwords for the master key parts that you choose to load. Example 2-26 shows the command, the input prompts, and the output where we specified three of our five master key parts. You can see where we were prompted to enter the necessary passwords.

Example 2-26 Loading master key parts $ ibmcloud tke cryptounit-mk-load

Enter the KEYNUM values of the master key parts you wish to load. 2 or 3 values must be specified, separated by spaces.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 55 > 4 1 3 Enter the password for the current signature key file: > Enter the password for key file 4 > Enter the password for key file 1 > Enter the password for key file 3 > OK The new master key register has been loaded in the selected crypto units.

NEW MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Full Uncommitted 20300d0371c2fc3e51c92a9b04c8c92b 3480d23546754b598be393bff042c8f1 2 Full Uncommitted 20300d0371c2fc3e51c92a9b04c8c92b 3480d23546754b598be393bff042c8f1

Tip: Run ibmcloud tke cryptounit-compare after loading the master key parts We found that running the ibmcloud tke cryptounit-compare command frequently during the flow is helpful in gaining an understanding of how the crypto units work. Run it again and you see that your master key is in the NEW MASTER KEY REGISTER but not in the CURRENT MASTER KEY REGISTER, and that your master key is in the Full Uncommitted state, as in our output shows in Example 2-27.

Example 2-27 cryptounit-compare after loading master key parts $ ibmcloud tke cryptounit-compare

IMPRINT MODE SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM IMPRINT MODE 1 No 2 No

CURRENT MASTER KEY REGISTER

56 Securing Your Critical Workloads with IBM Hyper Protect Services SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Empty 00000000000000000000000000000000 00000000000000000000000000000000 2 Empty 00000000000000000000000000000000 00000000000000000000000000000000

==> All crypto units are configured the same. <==

Note: When your master key is in the Full Uncommitted state, you can clear it out of the register if you decide you want to reload another key from a different combination of master key parts. For example, you can use the ibmcloud tke cryptounit-mk-clrnew command to clear the NEW MASTER KEY REGISTER and load different master key parts. If you loaded the same master key parts again, even if in a different order (for example, if you specified ‘4 3 1’ instead of ‘4 1 3’), you receive the same VERIFICATION PATTERN, which we confirmed in our lab.

Success criteria for “k”: Load new master key register You achieved success if you can run the ibmcloud tke cryptounit-compare command and see that each NEW MASTER KEY REGISTER is in the Full Uncommitted state, and you have the reassuring “All crypto units are configured the same” message at the end of your command output.

Tips for “l”: Commit master key register The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “l” maps to Step 6 in the Loading Master Keys section in the Getting Started page.

The instructions specify a single command, ibmcloud tke cryptounit-mk-commit. Run it and your NEW MASTER KEY REGISTER state changes to Full Committed.

Success criteria for “l”: Commit master key register Run the ibmcloud tke cryptounit-compare command and ensure that each crypto unit has its NEW MASTER KEY REGISTER in the Full Committed state, which is similar to what is shown in Example 2-28.

Example 2-28 cryptounit-compare after committing master key parts $ ibmcloud tke cryptounit-compare

IMPRINT MODE SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM IMPRINT MODE 1 No 2 No

Chapter 2. IBM Cloud Hyper Protect Crypto Services 57 NEW MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Full Committed 20300d0371c2fc3e51c92a9b04c8c92b 3480d23546754b598be393bff042c8f1 2 Full Committed 20300d0371c2fc3e51c92a9b04c8c92b 3480d23546754b598be393bff042c8f1

==> All crypto units are configured the same. <==

Note: We discovered through experimentation that you can still clear the key from the NEW MASTER KEY REGISTER by using the ibmcloud tke cryptounit-mk-clrnew command, even in the Full Committed state.

Tips for “m”: Activate master key The box in the flowchart that is shown in Example 2-15 on page 46 that corresponds to our callout letter “m” maps to Step 7 in the Loading Master Keys section in the Getting Started page.

Tip: Ignore the warning message if this is your first time initializing the service The only command that is documented in Getting Started page for this task is ibmcloud tke cryptounit-mk-setimm. This command presents a warning message. Because this instance is your first time initializing the service instance, it is safe to reply y to continue, as shown in Example 2-29.

Example 2-29 ibmcloud tke cryptounit-mk-setimm command $ ibmcloud tke cryptounit-mk-setimm Warning! Any key storage associated with the targeted service instance must be prepared to accept the new master key value before running this command. Otherwise, key storage may become unusable. Do you want to continue? Answer [y/N]: > y Enter the password for the current signature key file: > OK Set immediate completed successfully in the selected crypto units.

58 Securing Your Critical Workloads with IBM Hyper Protect Services CURRENT MASTER KEY REGISTER SERVICE INSTANCE: 57e89643-f274-4a8d-9d37-74bd7dc67ee3 CRYPTO UNIT NUM STATUS VERIFICATION PATTERN 1 Valid 20300d0371c2fc3e51c92a9b04c8c92b 3480d23546754b598be393bff042c8f1 2 Valid 20300d0371c2fc3e51c92a9b04c8c92b 3480d23546754b598be393bff042c8f1

Success criteria for ‘m’ - Activate master keys You see that the keys moved from your NEW MASTER KEY REGISTER to your CURRENT MASTER KEY REGISTER and that they are in a Valid state.

Your Hyper Protect Crypto Services instance is now ready to use.

2.3 Using the Key Management Services feature of Hyper Protect Crypto Services

Hyper Protect Crypto Services provides a key management service that allows you to create the following types of keys: Standard keys Standard keys are used to encrypt and decrypt data. You can import keys, create standard keys, and retrieve standard keys for usage within your application. Root keys Root keys are symmetric keys that are used to encrypt and decrypt standard keys. You can import keys and create root keys. However, unlike standard keys, you cannot retrieve a root key.

You can work with standard keys and root keys by using one of the following methods: Hyper Protect Crypto Services GUI Hyper Protect Crypto Services key management API Key Protect plug-in to the IBM Cloud CLI

2.3.1 Creating a root key

A root key can be created by using several methods. Those methods are described in this section.

Creating a root key by using the Hyper Protect Crypto Services GUI For more information about creating a root key by using the Hyper Protect Crypto Services GUI, see this web page.

We followed the instructions that are provided at this web page and named our new root key my-root-key-created-from-GUI. The service automatically assigns a unique ID to the key; therefore, our key is identified by the meaningful name we assigned when it was created and the service-assigned unique ID (see Figure 2-11 on page 60).

Chapter 2. IBM Cloud Hyper Protect Crypto Services 59 Figure 2-11 Root key created with the Hyper Protect Crypto Services GUI

Creating a root key by using the Key Management API Hyper Protect Crypto Services provides a key management API to store, retrieve, and generate encryption keys.

Tip: Ensure that you targeted the correct region and resource group for your Hyper Protect Crypto Services instance. For example, we issued the ibmcloud target -r us-south -g default command to access our instance.

For more information about creating a root key by using the Key Management API, see this web page.

Setup required to use the Key Management API To use the API successfully, you must obtain the following information: An access token, which is based on your IBM Cloud ID and grants that you access for a period Your Hyper Protect Crypto Services instance ID A Key Management endpoint URL for your Hyper Protect Crypto Services instance

How to set up an environment variable that is named ACCESS_TOKEN to contain our access token is shown in Example 2-30. In the example, we use “before” and “after” echo commands to ensure that our chosen environment variable name is not in use and to see the value of our access token.

Example 2-30 Setting an environment variable with an access token $ echo ${ACCESS_TOKEN}

$ export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`

$ echo ${ACCESS_TOKEN} Bearer eyJraWQiOiIyMDE5MDcyNCIsImFsZyI6IlJTMjU2In0..PTva4SCx0PGNG_hgXP9aavS-qQlK3fs6NP3lw_Ujl0HVmxg_ixmE2G6S5WlKAX_6EsVa8e7mpdK hfB--atcjZkL90auQkE40TfZyqWiLM2hIxv9F3S6deFDF_TYzF5XvhksEzasRW8oYpnx_DVC36TmW9MMzW GPy-CZ1OnGHIiF2vhyN0lFFXwwHyAt9293TMPQcfsiCr8Fd8gXHtAPqEbzqplvLj2L43p2JZVvqrl5sScs 3xmD3f1RMpEpDgZpq2auY44Rx4pgFbelwfLBog_HL6w7JVj14K3ItF8E7pHZfMCjysrjHLIYee5l3B0CSh gs-QbMrCHmv8Xz-LIvDNQ

60 Securing Your Critical Workloads with IBM Hyper Protect Services Note: The access tokens are valid for one hour after creation. If you receive an error message that indicates that your token is expired, reissue the export command that is shown in Example 2-30 on page 60. An error message we received when we tried to use the API with an expired token is shown in the following example:

{"metadata":{"collectionType":"application/vnd.ibm.kms.error+json","collectionT otal":1},"resources":[{"errorMsg":"Unauthorized: Token is expired"}]}

How to set up an environment variable that is named KP_INSTANCE_ID to contain the ID of our Hyper Protect Crypto Services instance is shown in Example 2-31.

Example 2-31 Setting an environment variable with the service instance ID $ echo ${KP_INSTANCE_ID}

$ export KP_INSTANCE_ID=`ibmcloud resource service-instance "my-hpcs-instance" --output json | jq -r '.[].guid'` $ echo ${KP_INSTANCE_ID} 57e89643-f274-4a8d-9d37-74bd7dc67ee3

An endpoint of your Key Management API must be assigned to an environment variable named KP_PRIVATE_ADDR. You can see your endpoints from the Hyper Protect Crypto Services GUI by selecting the Key management endpoint URL tab, as shown in Figure 2-12.

Figure 2-12 Finding your Key Management Endpoint URL

We clicked the icon to the right of our Public endpoint to copy it into the clipboard and then assigned, it to the KP_PRIVATE_ADDR environment variable, as shown in Example 2-32.

Example 2-32 setting KP_PRIVATE_ADDR environment variable $ echo ${KP_PRIVATE_ADDR}

$ export KP_PRIVATE_ADDR=https://api.us-south.hs-crypto.cloud.ibm.com:8449 $ echo ${KP_PRIVATE_ADDR} https://api.us-south.hs-crypto.cloud.ibm.com:8449

Note: Whether you use your Public or Private key management endpoint URL depends on whether your IBM Cloud account is enabled to use the IBM Cloud Private network. In either case, the endpoint URL is set to the environment variable named KP_PRIVATE_ADDR.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 61 Creating a root key after initial setup is complete We can now run the Key Management API after having set environment variables for the three pieces of information we need.

Note: Consider the following points: The documentation demonstrates the API by using the curl command-line utility, and we do so here as well. For production usage, you likely are starting the API call from a program in a language that probably has its own conventions to start an API or the ability to start the curl command from within the program. We provided a URL for reference at the beginning of “Creating a root key by using the Key Management API” on page 60. The examples that are provided are useful; however, the HTTP headers that are used in those examples are delimited with single quotation marks, which did not allow the proper substitution of our environment variable values. Therefore, although most of the examples in this section are inspired by those examples, we repeat them here with double quotation marks, which delimits HTTP header values as needed for suitable substitution of our environment variables at the command line when curl is used.

Example 2-33 shows the curl command that we used to create a root key by using the Key Management API.

Example 2-33 Creating new root key with API $ curl -X POST https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" -H 'content-type: application/vnd.ibm.kms.key+json' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "my-root-key-created-from-API", "description": "Root Key created with Key Management API", "extractable": false } ] }'

If you carefully review the command input that is shown in Example 2-33, you see that the word root appears twice: in the name that we used for the key (my-root-key-created-from-API), and in the description we used for the key. However, it is not evident what part of the input determines whether this key is a root key that is created or is a standard key.

Whether a root key or a standard key is created is determined by the value of the extractable name/value pair within the object in the resources name/value array. Because we specified a value of false, a root key is created. A root key can never be extracted from the service.

62 Securing Your Critical Workloads with IBM Hyper Protect Services Example 2-34 shows the output we received from our key creation request from Example 2-33 on page 62, (formatted for readability).

Example 2-34 Output from the command to create a root key with the API { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "id": "2742bd50-3f55-47c4-a02e-83bafd73a7e6", "type": "application/vnd.ibm.kms.key+json", "name": "my-root-key-created-from-API", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:2742bd50-3f55-47c4-a02e-83bafd73a7e6", "extractable": false, "imported": false } ] }

Creating a root key by using the Key Protect plug-in to the IBM Cloud CLI

Example 2-35 shows creating a root key by using the Key Protect plug-in to the IBM Cloud CLI. We only needed to provide a name for our new key because the plug-in’s create command creates a root key by default.

Example 2-35 Creating a root key with the Key Protect CLI plug-in $ ibmcloud kp create my-root-key-created-from-CLI --output json { "id": "24ef84fd-56af-45b2-aa75-1df710f8154b", "name": "my-root-key-created-from-CLI", "type": "application/vnd.ibm.kms.key+json", "extractable": false, "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:24ef84fd-56af-45b2-aa75-1df710f8154b" }

Tip: We added the optional --output json argument to our command that is shown in Example 2-35 because it shows us that it was a root key that is created (as indicated by the “extractable”: false name/value pair in the output). By default, the output is easier to use but less detailed; you are given the key name and key ID, but not visual proof that it was a root key that was created.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 63 2.3.2 Creating a standard key

Several methods are available for creating a standard key. These methods are described in this section.

Creating a standard key with the Hyper Protect Crypto Services GUI For more information about creating a standard key by suing the Hyper Protect Crypto Services GUI, see this web page.

We followed the instructions at that web page and named our new standard key my-standard-key-created-from-GUI. The service automatically assigns a unique ID to the key. As you can see in Figure 2-13, our key is identified by the meaningful name we assigned when it was created and by the service-assigned unique ID. We highlighted the standard key in Figure 2-13 to differentiate it from the root keys that we created previously.

Figure 2-13 A standard key created from the GUI

Creating a standard key by using the Key Management API For more information about creating a standard key by using the Key Management API, see this web page.

Example 2-36 shows our invocation of the Key Management API by using curl, and the output from the command.

Note: We piped the output of the command to the jq utility so that the output JSON formats well.

Example 2-36 Creating a standard key with the API $ curl -X POST https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" -H 'content-type: application/vnd.ibm.kms.key+json' -H 'prefer: return=representation' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "my-standard-key-created-from-API", "description": "Standard Key created with Key Management API", "extractable": true } ]

64 Securing Your Critical Workloads with IBM Hyper Protect Services }' | jq '.' # *** End of command input; command output starts below *** { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "id": "8d54378f-7501-4606-8754-ba81d57568d3", "type": "application/vnd.ibm.kms.key+json", "name": "my-standard-key-created-from-API", "description": "Standard Key created with Key Management API", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:8d54378f-7501-4606-8754-ba81d57568d3", "algorithmType": "AES", "payload": "RqkDdAyzqhSi0Fz4gj7A/jmbKzi/qk3vkv9rBx2X7KE=", "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-03T00:42:03Z", "algorithmMetadata": { "bitLength": "256", "mode": "CBC_PAD" }, "extractable": true, "imported": false, "algorithmMode": "CBC_PAD", "algorithmBitSize": 256 } ] }

You use the “extractable”: true JSON name/value pair in the input to inform the service that you want a standard key; that is, a key that you can extract for later use. Because the key is extractable, we added an HTTP Header to our input (prefer: return=representation), which tells the service to return the new key to us in the value of the payload name/value pair.

The value that is returned is a base64-encoded 256-bit AES symmetric key. If we omitted the prefer header or specified prefer: return=minimal, we do not receive the key because the payload name/value pair is absent from the response.

Creating a standard key by using the Key Protect plug-in to the IBM Cloud CLI

Example 2-37 shows the creation of a standard key by using the Key Protect plug-in to the IBM Cloud CLI. The --standard-key argument in the command is how we ask for a standard key to be created. Without this argument, a root key is created. We also pipe the command output to the jq utility to make the output easier to read.

Example 2-37 Creating a standard key with the Key Protect plug-in $ ibmcloud kp create my-standard-key-created-from-CLI --standard-key --output json | jq '.' { "id": "c085d537-bd0a-4884-94e0-3d05316bb618",

Chapter 2. IBM Cloud Hyper Protect Crypto Services 65 "name": "my-standard-key-created-from-CLI", "type": "application/vnd.ibm.kms.key+json", "extractable": true, "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:c085d537-bd0a-4884-94e0-3d05316bb618" }

2.3.3 Wrapping a standard key

You can wrap a standard key with a root key. This ability means that you encrypt the standard key with a root key. It is a convention within the security community to use the term “wrap” to refer to encrypting a key.

A root key never leaves the Hyper Protect Crypto Services instance. Therefore, wrapping a standard key with a root key provides a safe way to store or backup your standard key. Even if it is lost or stolen while wrapped by the root key, the plaintext content of the key cannot be determined. Therefore, it cannot be used by a malicious actor for encrypting new data or decrypting any data that might be encrypted by the key while it was unwrapped.

Hyper Protect Crypto Services offers two ways to wrap a standard key: by using the Key Management API or the Key Protect plug-in to the IBM Cloud CLI.

Wrapping a standard key by using the Key Management API For more information about wrapping a standard key by using the Key Management API, see this web page.

Example 2-38 shows our invocation of the Key Management API to wrap a key (by using curl) and the output from the command.

Example 2-38 Wrapping a key with the Key Management API $ curl -X POST \ > https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys/ab70b62d-5995-4a64-9 75a-4826166222ef?action=wrap \ > -H "accept: application/vnd.ibm.kms.key_action+json" \ > -H "authorization: ${ACCESS_TOKEN}"\ > -H "bluemix-instance: ${KP_INSTANCE_ID}" \ > -H "content-type: application/vnd.ibm.kms.key_action+json" \ > -d '{ > "plaintext": "uLPdvFAzmYr+A3YTPXPD7s8B2E8nOBlHaScwEH00yUk=" > }' {"ciphertext":"eyJjaXBoZXJ0ZXh0IjoibGRBdVNMeHhBT1Bod21yMkM1T1JGSSs1dWxlOEhyR0dvai9 jSFJRQnRXSWFIOHYvTEpMbGRra3dNaHBwSFl0ciIsIml2IjoiZGpMeXNvdnY1R0t5TnhzOSt0bnY0Zz09I iwidmVyc2lvbiI6IjQuMC4wIiwiaGFuZGxlIjoiYWI3MGI2MmQtNTk5NS00YTY0LTk3NWEtNDgyNjE2NjI yMmVmIn0="}

The ID of the root key that you want to use for wrapping is part of the URL (ab70b62d-5995-4a64-975a-4826166222ef) in Example 2-38.

The key that you want to wrap is passed (encoded with base64 encoding) in the POST data as the value of the plaintext JSON name/value pair (uLPdvFAzmYr+A3YTPXPD7s8B2E8nOBlHaScwEH00yUk=) in Example 2-38.

66 Securing Your Critical Workloads with IBM Hyper Protect Services The wrapped key is returned (base64-encoded) in the response as the value of the ciphertext JSON name/value pair in Example 2-38 on page 66: eyJjaXBoZXJ0ZXh0IjoibGRBdVNMeHhBT1Bod21yMkM1T1JGSSs1dWxlOEhyR0dvai9jSFJRQnRXSWFIOH YvTEpMbGRra3dNaHBwSFl0ciIsIml2IjoiZGpMeXNvdnY1R0t5TnhzOSt0bnY0Zz09IiwidmVyc2lvbiI6 IjQuMC4wIiwiaGFuZGxlIjoiYWI3MGI2MmQtNTk5NS00YTY0LTk3NWEtNDgyNjE2NjIyMmVmIn0=

Important: Be wary of persisting the unwrapped key anywhere. Instead, use it in your application or service to encrypt or decrypt your data, but dispose of it when you are finished using it and do not persist it anywhere outside of your Hyper Protect Crypto Services instance.

Wrapping a standard key by using the IBM Cloud CLI Key Protect plug-in

Example 2-39 shows the wrapping of a standard key by using the Key Protect plug-in to the IBM Cloud CLI.

Example 2-39 Wrapping a key with the Key Protect plug-in $ ibmcloud kp wrap ab70b62d-5995-4a64-975a-4826166222ef -p uLPdvFAzmYr+A3YTPXPD7s8B2E8nOBlHaScwEH00yUk= -o json

{ "Ciphertext": "eyJjaXBoZXJ0ZXh0IjoiZCtYdGRBVGp5VlkrR2VhNnJzeVJoeUlYU0lJNVd6NTZPOE1odS92c3J0b1B2e jVyNEY0aVptNVVLTzl5QVNaNSIsIml2IjoiMXpxa20vV1lBdTZqRHJFV0huWm0wUT09IiwidmVyc2lvbiI 6IjQuMC4wIiwiaGFuZGxlIjoiYWI3MGI2MmQtNTk5NS00YTY0LTk3NWEtNDgyNjE2NjIyMmVmIn0=" }

In Example 2-39, the same root key ID was specified to the kp wrap command and the same key payload was given as were used in the API example from Example 2-38 on page 66. As a result (and as expected), the output ciphertext is the same from both examples.

2.3.4 Unwrapping a standard key

If you stored a wrapped key and want to use it for encrypting or decrypting data, you must unwrap it first. Hyper Protect Crypto Services offers two ways to unwrap the wrapped key: by using the Key Management API or the Key Protect plug-in to the IBM Cloud CLI.

Unwrapping a standard key by using the Key Management API For more information about unwrapping a standard key by using the Key Management API, see this web page.

Example 2-40 shows our invocation of the Key Management API to unwrap a wrapped key (by using curl) and the output from the command.

Example 2-40 Unwrapping a key with the API $ curl -X POST \ > 'https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys/ab70b62d-5995-4a64- 975a-4826166222ef?action=unwrap' \ > -H 'accept: application/vnd.ibm.kms.key_action+json' \ > -H "authorization: ${ACCESS_TOKEN}" \ > -H "bluemix-instance: ${KP_INSTANCE_ID}" \ > -H 'content-type: application/vnd.ibm.kms.key_action+json' \

Chapter 2. IBM Cloud Hyper Protect Crypto Services 67 > -d '{"ciphertext":"eyJjaXBoZXJ0ZXh0IjoiR0tHNU5IZ0tVQVVXNjRpalFaeEU1SDI2SU5rTnlQU1FiWE JTN21VejVBZFdNWC9Oa3YzQ0t2ZFB2dFo1S1pyeCIsIml2IjoiMG9FRmJMWEIxY2V6RlBkTGxDUHY3Zz09 IiwidmVyc2lvbiI6IjQuMC4wIiwiaGFuZGxlIjoiYWI3MGI2MmQtNTk5NS00YTY0LTk3NWEtNDgyNjE2Nj IyMmVmIn0="}'

{"plaintext":"uLPdvFAzmYr+A3YTPXPD7s8B2E8nOBlHaScwEH00yUk="}

The base64-encoded wrapped key is passed as input as the value of the ciphertext JSON name/value pair. The response contains the base64-encoded key in the value of the plaintext JSON name/value pair.

You can decode the base64-encoded key and then use it for encrypting and decrypting your data, after which you dispose of your local copy of the unwrapped key. The only place it remains is in unwrapped form is in your Hyper Protect Crypto Services instance.

Unwrapping a standard key by using the IBM Cloud CLI Key Protect plug-in

Example 2-41 shows the unwrapping of a wrapped key by using the Key Protect plug-in to the IBM Cloud CLI.

Example 2-41 Unwrapping a key with the Key Protect CLI plug-in $ ibmcloud kp unwrap ab70b62d-5995-4a64-975a-4826166222ef eyJjaXBoZXJ0ZXh0IjoiR0tHNU5IZ0tVQVVXNjRpalFaeEU1SDI2SU5rTnlQU1FiWEJTN21VejVBZFdNWC 9Oa3YzQ0t2ZFB2dFo1S1pyeCIsIml2IjoiMG9FRmJMWEIxY2V6RlBkTGxDUHY3Zz09IiwidmVyc2lvbiI6 IjQuMC4wIiwiaGFuZGxlIjoiYWI3MGI2MmQtNTk5NS00YTY0LTk3NWEtNDgyNjE2NjIyMmVmIn0= -o json

{ "Plaintext": "uLPdvFAzmYr+A3YTPXPD7s8B2E8nOBlHaScwEH00yUk=", "Rewrapped Plaintext": "" }

Whereas with the ibmcloud kp wrap command you pass in the base64-encoded standard key and receive the wrapped key back as ciphertext, with the ibmcloud kp unwrap command, you pass in the wrapped key and receive the base64-encoded standard key (unwrapped) as plaintext.

2.3.5 Importing a key as a root key

In section 2.3.1, “Creating a root key” on page 59, we described creating a root key in Hyper Protect Crypto Services. In that example, the key is created for you, it cannot be retrieved, and you do not even know the key’s contents. You can import a known key into Hyper Protect Crypto Services to be used as a root key.

Important: You can import a key as a root key. After the root key is created in your Hyper Protect Crypto Services instance, it is protected and cannot be extracted. However, the Hyper Protect Crypto Services instance has no awareness of or control over how securely you protected that key before importing it into Hyper Protect Crypto Services.

68 Securing Your Critical Workloads with IBM Hyper Protect Services For the examples in this section, we used the popular openssl toolkit to generate a random number, 32 bytes (that is, 256-bits), which serve as our key that we import. We asked that this number is saved to a file in base64-encoded form. We then displayed the base64-encoded value of the key by using the cat command because we use this value in this section. Example 2-42 shows these commands.

Example 2-42 Using openssl to generate a 256-bit random number to be used as a root key $ openssl rand -base64 -out materialForRootKeyImport.b64 32 $ cat materialForRootKeyImport.b64 OM7NMY5Lt4yKXUdrkhVA1NbikSFNThIjlBpq+tO3yG0=

Importing a root key by using the Hyper Protect Crypto Services GUI For more information about the process of importing a root key by using the Hyper Protect Crypto Services GUI, see this web page.

We followed the instructions at this web page and named our imported root key my-root-key-imported-from-GUI.

Figure 2-14 shows where we entered our base64-encoded key into the suitable field in the Add key window.

Figure 2-14 Importing a key as a root key with the GUI

Chapter 2. IBM Cloud Hyper Protect Crypto Services 69 The service automatically assigns a unique ID to the key; therefore, as you can see in Figure 2-15, our key is identified by the meaningful name we assigned when it was created and the service-assigned unique ID.

Figure 2-15 Using the GUI to list the root key we imported with the GUI

Tip: We created seven keys thus far, but we entered the word imported in the search field to narrow the number of keys that is shown to us.

Importing a root key with the Key Management API For more information about how to import a root key by using the Key Management API, see this web page.

Example 2-43 shows the curl command that we used to import a root key by using the Key Management API, along with the command output.

Example 2-43 Importing a root key with the API $ curl -X POST https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" -H 'content-type: application/vnd.ibm.kms.key+json' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "my-root-key-imported-from-API", "description": "Root Key imported with Key Management API", "extractable": false, "payload": "OM7NMY5Lt4yKXUdrkhVA1NbikSFNThIjlBpq+tO3yG0=" } ] }' | jq '.'

{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "id": "a3eba8cc-e3eb-4b8d-a4fb-bb4ee0587fe1", "type": "application/vnd.ibm.kms.key+json", "name": "my-root-key-imported-from-API", "state": 1,

70 Securing Your Critical Workloads with IBM Hyper Protect Services "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:a3eba8cc-e3eb-4b8d-a4fb-bb4ee0587fe1", "extractable": false, "imported": true } ] }

Importing a root key by using the Key Protect plug-in to the IBM Cloud CLI

Example 2-44 shows importing a root key by using the Key Protect plug-in to the IBM Cloud CLI. We specify the key material to be imported as the value of the -k argument to the ibmcloud kp create command.

Example 2-44 Importing a root key with the Key Protect CLI plug-in $ ibmcloud kp create my-root-key-imported-from-CLI -k OM7NMY5Lt4yKXUdrkhVA1NbikSFNThIjlBpq+tO3yG0= --output json

{ "id": "7552cc3f-fcb1-4169-8891-81a772da969f", "name": "my-root-key-imported-from-CLI", "type": "application/vnd.ibm.kms.key+json", "extractable": false, "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:7552cc3f-fcb1-4169-8891-81a772da969f" }

2.3.6 Importing a key as a standard key

In section 2.3.2, “Creating a standard key” on page 64, we described creating a standard key in Hyper Protect Crypto Services. In that example, the key is created for you. You can import a known key into Hyper Protect Crypto Services to be used as a standard key.

Important: Although the key you import as a standard key is stored securely within your Hyper Protect Crypto Services instance, Hyper Protect Crypto Services is not aware of nor can control how securely you protected that key before importing it into Hyper Protect Crypto Services.

For the examples in this section, we used the popular openssl toolkit to generate a random number 32 bytes (that is, 256-bits), which serves as our key that we import. We asked that this number is saved to a file in base64-encoded form. We then displayed the base64-encoded value of by using with the cat command because we use this value in this section. Example 2-45 shows these commands.

Example 2-45 Using openssl to generate a 256-bit random number to be used as a standard key $ openssl rand -base64 -out materialForStandardKeyImport.b64 32 $ cat materialForStandardKeyImport.b64

Chapter 2. IBM Cloud Hyper Protect Crypto Services 71 DIBMiLfvsIcAjQ+plED63soHlZbaPNSH50Dzp9IoP4Q=

Importing a standard key by using the Hyper Protect Crypto Services GUI

For more information about importing a standard key by using the Hyper Protect Crypto Services GUI, see this web page.

We followed the instructions at this web page and named our imported standard key my-standard-key-imported-from-GUI. Figure 2-16 shows where we entered our base64-encoded key into the correct field in the Add key window.

Figure 2-16 Importing an existing key as a standard key with the GUI

The service automatically assigns a unique ID to the key. As you can see in Figure 2-17, our key is identified by the meaningful name we assigned when it was created and the service-assigned unique ID.

Figure 2-17 Using the GUI to list the standard key we imported with the GUI

72 Securing Your Critical Workloads with IBM Hyper Protect Services Importing a standard key with the Key Management API For more information about importing a standard key by using the Key Management API, see this web page.

Example 2-46 shows the curl command that we used to import a standard key by using the Key Management API, along with the command output.

Example 2-46 Importing a standard key with the API $ curl -X POST https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" -H 'content-type: application/vnd.ibm.kms.key+json' -d '{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "my-standard-key-imported-from-API", "description": "Standard Key imported with Key Management API", "extractable": true, "payload": "DIBMiLfvsIcAjQ+plED63soHlZbaPNSH50Dzp9IoP4Q=" } ] }' | jq '.'

{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "id": "753ef33a-0617-45b8-bd2f-ac49fb8c00ac", "type": "application/vnd.ibm.kms.key+json", "name": "my-standard-key-imported-from-API", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:753ef33a-0617-45b8-bd2f-ac49fb8c00ac", "extractable": true, "imported": true } ] }

It is the “extractable” :true JSON name/value pair in the POST data that indicates that this key is a standard key, in contrast to a root key that is specified by using “extractable”: false.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 73 Importing a standard key by using the IBM Cloud CLI Key Protect plug-in Example 2-47 shows importing a standard key by using the Key Protect plug-in to the IBM Cloud CLI. We specify the key material to be imported as the value of the -k argument to the ibmcloud kp create command, and we add the --standard-key argument to the command to indicate that we want to import a standard key rather than a root key.

Example 2-47 Importing a standard key using the Key Protect CLI plug-in $ ibmcloud kp create my-standard-key-imported-from-CLI -k DIBMiLfvsIcAjQ+plED63soHlZbaPNSH50Dzp9IoP4Q= --standard-key --output json

{ "id": "af4a1b2e-da60-45a1-96dd-ddb72108fe26", "name": "my-standard-key-imported-from-CLI", "type": "application/vnd.ibm.kms.key+json", "extractable": true, "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:af4a1b2e-da60-45a1-96dd-ddb72108fe26" }

2.3.7 Listing all keys

You can obtain a list of the keys you are storing in your Hyper Protect Crypto Services instance by using the Hyper Protect Crypto Services GUI, the Key Management API, or the Key Protect plug-in to the IBM Cloud CLI.

We created the following keys in the service during writing this chapter: Three new root keys: One each by using GUI, API, and CLI Three new standard keys: One each by using GUI, API, and CLI Three imported root keys: One each by using GUI, API, and CLI Three imported standard keys: One each by using GUI, API, and CLI

Next, we describe how to list these keys by using the GUI, API, and CLI.

Listing all keys from the Hyper Protect Crypto Services GUI For more information about viewing a list of your keys from the Hyper Protect Crypto Services GUI, see this web page.

We followed these instructions to obtain the list (as shown in Figure 2-18 on page 75) of the twelve keys we created.

74 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 2-18 Viewing a list of keys from the GUI

Click the column headers to sort on a particular column and to set the order of sorting to ascending or descending. We show the keys sorted in ascending order in the Name column. We also changed the setting for Items per page from 10 to 50 so that we can see all 12 keys in one window.

Listing all keys from the Key Management API For more information about retrieving a list of your keys from the Key Management API, see this web page.

Example 2-48 shows the curl command that we used to list all of the keys with the API, along with a sample of the command output, which is truncated for brevity.

Example 2-48 Listing keys with the API $ curl -X GET https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys -H 'accept: application/vnd.ibm.collection+json' -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" | jq ‘.’

{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 12 }, "resources": [ { "id": "af4a1b2e-da60-45a1-96dd-ddb72108fe26", "type": "application/vnd.ibm.kms.key+json", "name": "my-standard-key-imported-from-CLI", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:af4a1b2e-da60-45a1-96dd-ddb72108fe26",

Chapter 2. IBM Cloud Hyper Protect Crypto Services 75 "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-07T19:43:52Z", "lastUpdateDate": "2020-01-07T19:43:52Z", "algorithmMetadata": { "bitLength": "256", "mode": "CBC_PAD" }, "extractable": true, "imported": true, "algorithmMode": "CBC_PAD", "algorithmBitSize": 256 }, // output for 10 of our 12 keys truncated for brevity { "id": "ab70b62d-5995-4a64-975a-4826166222ef", "type": "application/vnd.ibm.kms.key+json", "name": "my-root-key-created-from-GUI", "description": "...", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:ab70b62d-5995-4a64-975a-4826166222ef", "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-02T19:26:30Z", "lastUpdateDate": "2020-01-02T19:26:30Z", "algorithmMetadata": { "bitLength": "256", "mode": "CBC_PAD" }, "extractable": false, "imported": false, "algorithmMode": "CBC_PAD", "algorithmBitSize": 256 } ] }

The API listed all 12 of our keys, but we removed all but two of the keys from Example 2-48 on page 75 for brevity.

We show in Example 2-49 a repetition of the command where we use the jq utility to parse the output so that we receive a list of key names and IDs only and an indication for each key of whether it is a standard key.

Example 2-49 jq utility $ curl -X GET https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys -H 'accept: application/vnd.ibm.collection+json' -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" | jq ". | .resources[] | { id: .id, name: .name, standardKey: .extractable}"

{ "id": "af4a1b2e-da60-45a1-96dd-ddb72108fe26", "name": "my-standard-key-imported-from-CLI", "standardKey": true }

76 Securing Your Critical Workloads with IBM Hyper Protect Services { "id": "753ef33a-0617-45b8-bd2f-ac49fb8c00ac", "name": "my-standard-key-imported-from-API", "standardKey": true } { "id": "d6e1ad6b-a948-4233-a449-897a9c029f25", "name": "my-standard-key-imported-from-GUI", "standardKey": true } { "id": "7552cc3f-fcb1-4169-8891-81a772da969f", "name": "my-root-key-imported-from-CLI", "standardKey": false } { "id": "a3eba8cc-e3eb-4b8d-a4fb-bb4ee0587fe1", "name": "my-root-key-imported-from-API", "standardKey": false } { "id": "19cd78f5-4b78-4ff1-abe3-a5d35f43b4e2", "name": "my-root-key-created-from-API", "standardKey": false } { "id": "07e9af0b-b28e-46e1-bff5-2823bf5c9b72", "name": "my-root-key-imported-from-GUI", "standardKey": false } { "id": "c085d537-bd0a-4884-94e0-3d05316bb618", "name": "my-standard-key-created-from-CLI", "standardKey": true } { "id": "8d54378f-7501-4606-8754-ba81d57568d3", "name": "my-standard-key-created-from-API", "standardKey": true } { "id": "c1c05794-2117-4918-9b3e-5b08dd72a485", "name": "my-standard-key-created-from-GUI", "standardKey": true } { "id": "24ef84fd-56af-45b2-aa75-1df710f8154b", "name": "my-root-key-created-from-CLI", "standardKey": false } { "id": "ab70b62d-5995-4a64-975a-4826166222ef", "name": "my-root-key-created-from-GUI", "standardKey": false

Chapter 2. IBM Cloud Hyper Protect Crypto Services 77 }

Listing all keys from the Key Protect plug-in to the IBM Cloud CLI Example 2-50 shows a simple list of available keys that was obtained from the Key Protect plug-in to the IBM Cloud CLI.

Example 2-50 Listing keys with the Key Protect CLI plug-in $ ibmcloud kp list Retrieving keys...

SUCCESS

Key ID Key Name af4a1b2e-da60-45a1-96dd-ddb72108fe26 my-standard-key-imported-from-CLI 753ef33a-0617-45b8-bd2f-ac49fb8c00ac my-standard-key-imported-from-API d6e1ad6b-a948-4233-a449-897a9c029f25 my-standard-key-imported-from-GUI 7552cc3f-fcb1-4169-8891-81a772da969f my-root-key-imported-from-CLI a3eba8cc-e3eb-4b8d-a4fb-bb4ee0587fe1 my-root-key-imported-from-API 19cd78f5-4b78-4ff1-abe3-a5d35f43b4e2 my-root-key-created-from-API 07e9af0b-b28e-46e1-bff5-2823bf5c9b72 my-root-key-imported-from-GUI c085d537-bd0a-4884-94e0-3d05316bb618 my-standard-key-created-from-CLI 8d54378f-7501-4606-8754-ba81d57568d3 my-standard-key-created-from-API c1c05794-2117-4918-9b3e-5b08dd72a485 my-standard-key-created-from-GUI 24ef84fd-56af-45b2-aa75-1df710f8154b my-root-key-created-from-CLI ab70b62d-5995-4a64-975a-4826166222ef my-root-key-created-from-GUI

Tip: You can add the --output json argument to the command that is shown in Example 2-50 to get more output for each key, in JSON format, which is similar to the output that the API provides.

2.3.8 Listing a specific key

You can list a specific key, and, if it is a standard key, you can optionally retrieve the key.

Listing a specific key by using the Key Management API To get a specific key by using the API, you add the key ID to the end of the path of the URL for the GET request.

Example 2-51 shows an example where we list the information for a specific root key with an ID of ab70b62d-5995-4a64-975a-4826166222ef. We receive information about the key, but because it is a root key, we cannot receive the key value, by design.

Example 2-51 Listing a specific root key with the API $ curl -X GET https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys/ab70b62d-5995-4a64-9 75a-4826166222ef -H 'accept: application/vnd.ibm.collection+json' -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" | jq '.'

{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1

78 Securing Your Critical Workloads with IBM Hyper Protect Services }, "resources": [ { "id": "ab70b62d-5995-4a64-975a-4826166222ef", "type": "application/vnd.ibm.kms.key+json", "name": "my-root-key-created-from-GUI", "description": "...", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:ab70b62d-5995-4a64-975a-4826166222ef", "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-02T19:26:30Z", "lastUpdateDate": "2020-01-02T19:26:30Z", "algorithmMetadata": { "bitLength": "256", "mode": "CBC_PAD" }, "extractable": false, "imported": false, "algorithmMode": "CBC_PAD", "algorithmBitSize": 256 } ] }

Example 2-52 shows a request for a standard key. Because standard keys are extractable, along with the information about the key, we also receive the base64-encoded key in the response as the value of the payload JSON name/value pair.

Example 2-52 Listing a specific standard key with the API $ curl -X GET https://api.us-south.hs-crypto.cloud.ibm.com:8449/api/v2/keys/c1c05794-2117-4918-9 b3e-5b08dd72a485 -H 'accept: application/vnd.ibm.collection+json' -H "authorization: ${ACCESS_TOKEN}" -H "bluemix-instance: ${KP_INSTANCE_ID}" | jq '.'

{ "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "id": "c1c05794-2117-4918-9b3e-5b08dd72a485", "type": "application/vnd.ibm.kms.key+json", "name": "my-standard-key-created-from-GUI", "description": "...", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:c1c05794-2117-4918-9b3e-5b08dd72a485", "payload": "zcKgeWMPS4D2dF0OHRYwaF0EPiMl/4AVVigVlFYSf0I=", "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-02T23:34:25Z", "lastUpdateDate": "2020-01-02T23:34:25Z",

Chapter 2. IBM Cloud Hyper Protect Crypto Services 79 "algorithmMetadata": { "bitLength": "256", "mode": "CBC_PAD" }, "extractable": true, "imported": false, "algorithmMode": "CBC_PAD", "algorithmBitSize": 256 } ] }

Listing a specific key with the Key Protect plug-in of the IBM Cloud CLI Example 2-53 shows the use of the Key Protect plug-in of the IBM Cloud CLI to list a specific root key.

Example 2-53 Listing a specific root key with the Key Protect CLI plug-in with JSON output $ ibmcloud kp get ab70b62d-5995-4a64-975a-4826166222ef --output json | jq '.'

{ "id": "ab70b62d-5995-4a64-975a-4826166222ef", "name": "my-root-key-created-from-GUI", "description": "...", "type": "application/vnd.ibm.kms.key+json", "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-02T19:26:30Z", "extractable": false, "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:ab70b62d-5995-4a64-975a-4826166222ef" }

Example 2-54 shows the listing of the same key but without specifying the JSON output format.

Example 2-54 Listing a specific root key with the Key Protect CLI plug-in with default output $ ibmcloud kp get ab70b62d-5995-4a64-975a-4826166222ef Grabbing info for key id: ab70b62d-5995-4a64-975a-4826166222ef...

SUCCESS

Key ID Key Name Description Creation Date Expiration Date ab70b62d-5995-4a64-975a-4826166222ef my-root-key-created-from-GUI ... 2020-01-02 19:26:30 +0000 UTC Key does not expire

80 Securing Your Critical Workloads with IBM Hyper Protect Services Example 2-55 shows listing a specific standard key by using the Key Protect plug-in with the default output format. Although it is a standard key, the key material is not shown.

Example 2-55 Listing a specific standard key with the Key Protect CLI plug-in with default output $ ibmcloud kp get d6e1ad6b-a948-4233-a449-897a9c029f25 Grabbing info for key id: d6e1ad6b-a948-4233-a449-897a9c029f25...

SUCCESS

Key ID Key Name Description Creation Date Expiration Date d6e1ad6b-a948-4233-a449-897a9c029f25 my-standard-key-imported-from-GUI ... 2020-01-07 19:10:28 +0000 UTC Key does not expire

If you add the --output json argument to the preceding command, you receive the base64-encoded key material for a standard key as part of the output, as the value for the payload JSON name/value pair, as shown in Example 2-56.

Example 2-56 Listing a specific standard key with the Key Protect CLI plug-in with JSON output $ ibmcloud kp get d6e1ad6b-a948-4233-a449-897a9c029f25 --output json | jq '.'

{ "id": "d6e1ad6b-a948-4233-a449-897a9c029f25", "name": "my-standard-key-imported-from-GUI", "description": "...", "type": "application/vnd.ibm.kms.key+json", "createdBy": "IBMid-120000Q681", "creationDate": "2020-01-07T19:10:28Z", "extractable": true, "payload": "DIBMiLfvsIcAjQ+plED63soHlZbaPNSH50Dzp9IoP4Q=", "state": 1, "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/1e963a246cc69a44df65e277e14239d5:57e89 643-f274-4a8d-9d37-74bd7dc67ee3:key:d6e1ad6b-a948-4233-a449-897a9c029f25" }

2.4 Using the GREP11 feature of Hyper Protect Crypto Services

Hyper Protect Crypto Services offers an API called GREP11 with which you can perform cryptographic operations on your data within the secure boundaries of the hardware security module (HSM) that is associated with your Hyper Protect Crypto Services instance.

The name GREP11 is derived from a combination of the communications protocol (gRPC) that an application uses to communicate with an IBM-provided EP11 library. The name EP11 is derived from the phrase Enterprise PKCS#11. EP11 offers an interface that is similar to the Public Key Cryptography #11 (PKCS#11) standard, which is a widely used Oasis standard.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 81 The EP11 and PKCS#11 interfaces feature the following major differences: With EP11 the cryptographic material, such as keys, is stored outside of the HSM This material is safe to store outside of the HSM because it is always wrapped with a key that can be used only inside the HSM; that is, the returned cryptographic material is usable only within the HSM. With EP11 the HSM device is stateless, as opposed to most PKCS#11 implementations where the HSM device is considered stateful For more information about the advantages of choosing a stateless model for the backend HSM device, see Chapter 2: Sessions and state Enterprise PKCS#11 (EP11) Library structure.

IBM’s EP11 interface offers features that are not available in the PKCS#11 specification that IBM considers appealing to enterprises (the phrase Enterprise PKCS#11 from which the name EP11 is derived). The following features are available: Cryptographic objects that are generated by EP11 that are stored outside of the HSM are always protected with an authenticated encryption scheme, which prevents many of the attacks that are possible when PKCS#11 is used without an authenticated encryption scheme. EP11 prevents you from wrapping a key with a weaker key, something that can be done in the PKCS#11 specification. EP11 offers the following convenience functions for several cryptographic operations that allows an operation that requires multiple function calls under the PKCS#11 standard to be completed in a single function call under EP11: – DigestSingle() – EncryptSingle() – DecryptSingle() – SignSingle() – VerifySingle()

82 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 2-19 shows three choices for the function call flow for several of the cryptographic operations, with the choice on the left (“Cipher Flow 1”) that shows the convenience function that is provided by IBM. In Figure 2-19, the generic term Cipher is used because the Digest, Encrypt, Decrypt, Sign, and Verify operations each offers these choices.

Figure 2-19 Function call sequence flows for several of the GREP11 operations

2.4.1 Functions available with the GREP11 API

The Hyper Protect Crypto Services documentation provides the GREP11 API reference at https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-grep11-api-ref.

GREP11 offers 35 functions, each belonging to one of the following categories: Key generation (3 functions): – GenerateKey() – GenerateKeyPair() – DeriveKey() Digesting (5 functions): – DigestInit() – Digest() – DigestUpdate() – DigestFinal() – DigestSingle() Signing and verification (10 functions): – SignInit() –Sign()

Chapter 2. IBM Cloud Hyper Protect Crypto Services 83 – SignUpdate() – SignFinal() – SignSingle() – VerifyInit() –Verify() – VerifyUpdate() – VerifyFinal() – VerifySingle() Encryption and Decryption (10 functions): –DecryptInit() –Decrypt() – DecryptUpdate() – DecryptFinal() – DecryptSingle() – EncryptInit() – Encrypt() – EncryptUpdate() – EncryptFinal() – EncryptSingle() Random numbers (1 function): GenerateRandom() Key transport (2 functions): – UnwrapKey() – WrapKey() Queries (3 functions): – GetAttributeValue() – GetMechanismInfo() – GetMechanismList() Administration (1 function): SetAttributeValue()

Key generation function notes Use the GenerateKey() function to create a symmetric key. This function is used in the Example_encryptAndDecrypt function and in the Example_wrapAndUnwrapKey function in the server_test.go program in the GREP11 sample code for the Go language that is described at this web page.

Use the GenerateKeyPair() function to create an asymmetric (that is, public and private) key pair. This function is used in the following functions: Example_signAndVerifyUsingRSAKeyPair Example_signAndVerifyUsingECDSAKeyPair Example_signAndVerifyToTestErrorHandling Example_wrapAndUnwrapKey Example_deriveKey in the server_test.go program GenerateECDSAKeyPair function in the tls_test.go program (both are in the GREP11 sample code for Go)

Use the DeriveKey() function to create a secret symmetric key from a base key, which is typically used in key exchange algorithms. This function is used in the Example_deriveKey function in server_test.go from the GREP11 sample code for Go.

84 Securing Your Critical Workloads with IBM Hyper Protect Services Digesting function notes A single-part digest (that is, hashing) operation can be performed by using a lone DigestSingle() function call or a DigestInit() function call followed by a Digest() function call.

A multiple-part digest operation is performed with a DigestInit() function call, followed by two or more DigestUpdate() function calls, followed by a DigestFinal() function call.

The Example_digest function in server_test.go from the GREP11 sample code for Go provides examples of both a single-part and a multiple-part digest operation.

Signing and verification function notes A single-part digital signature sign operation can be performed by using a lone SignSingle() function call or a SignInit() function call followed by a Sign() function call.

A multiple-part digital signature sign operation can be performed by using a SignInit() function call, followed by two or more SignUpdate() calls, followed by a SignFinal() function call.

Single-part and multiple-part digital signature verification operations can be performed in the same manner; that is, the function names begin with Verify instead of Sign.

Single-part signing and verification operations are demonstrated in three different functions in the server_test.go program in the GREP11 sample code for Go- in the following functions: Example_signAndVerifyUsingRSAKeyPair Example_signAndVerifyUsingECDSAKeyPair Example_signAndVerifyToTestErrorHandling

Encryption and decryption function notes A single-part data encryption operation can be performed by using a lone EncryptSingle() function call, or an EncryptInit() function call followed by an Encrypt() function call.

A multiple-part data encryption operation is performed by using an EncryptInit() call, followed by two or more EncryptUpdate() calls, followed by an EncryptFinal() function call.

Single-part and multiple-part data decryption operations are performed in a similar manner, with the function names that start with Decrypt instead of Encrypt.

In the server_test.go program in the GREP11 sample code for Go, an example of multi-part encryption and multi-part decryption is provided in the Example_encryptAndDecrypt function, and an example of single-part encryption and decryption is given in the Example_deriveKey function.

Random numbers function notes The GenerateRandom() function is useful to generate Initialization Vectors. The GREP11 sample code for Go provides examples of GenerateRandom() in two functions in server_test.go: in the Example_encryptAndDecrypt and Example_deriveKey functions.

Key transport function notes The key transport functions are useful for securely transporting keys from one party to another. A typical use case is where the sender of the key wraps it with the recipient’s public key and sends it to the recipient. This process is secure because only the recipient can decrypt it with their corresponding private key.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 85 The WrapKey() and UnwrapKey() functions are demonstrated in the Example_wrapAndUnwrapKey function in the server_test.go program in the GREP11 sample code for Go.

Queries function notes Attributes can be bound to a key, which can be used to restrict the types of operations that can be performed with the key within the HSM. For example, it is considered a good practice to use different keys for different purposes; therefore, do not use the same key that you use to encrypt and decrypt data to also create a digest, or to wrap and unwrap other keys. You can bind attributes to a key to restrict its functionality to enforce best practices. By using the GetAttributeValue() function, you can see which attributes were bound to a key.

EP11 borrows the usage of the PKCS#11 term mechanism, which is defined in the PKCS#11 specification as a process that is used to implement a cryptographic operation. The GetMechanismList() function provides a list of all of the mechanisms that are supported by the HSM. The GetMechanismInfo() function provides information about a specific mechanism.

The Example_getMechanismInfo function in the server_test.go program in the GREP11 sample code for Go shows the use of GetMechanismList() and GetMechanismInfo().

Administration function notes By using the SetAttributeValue() function, you can change the attributes of a key. EP11 currently allows only Boolean attributes to be changed. Attributes that contain numeric or string values cannot be changed. For more information about attributes and Boolean attributes, see 2.2.5 and 2.2.6 in Enterprise PKCS#11 (EP11) Library structure.

2.5 Code examples

IBM Cloud Hyper Protect Crypto Services provides an Enterprise PKCS #11 (EP11) API over gRPC (also referred to as GREP11 API) to remotely access the Hyper Protect Crypto Services service instance for data encryption and management.

This section describes the steps to set up the GREP11 API, and then the Go and Node.js code examples for accessing GREP11 functions.

For more information about GREP11 APIs, see this IBM Cloud web page.

2.5.1 Setting up the GREP11 API

The first step in the set up process is to instantiate the IBM Cloud Hyper Protect Crypto Service and configure the master key. For more information about that process, see 2.2, “Creating an instance of Hyper Protect Crypto Services on the public IBM Cloud” on page 30.

2.5.2 GREP11 code examples

At the time of this writing, a GitHub repository with Go and Node.js code examples is available. The code examples allow you to test the GREP11 API and show you how to start various GREP11 functions.

This section describes setting up your environment to run Go programs, followed by setting up and running the Go sample code.

86 Securing Your Critical Workloads with IBM Hyper Protect Services Setting up Go tools For more information about installing Go tools for your specific platform, see this web page.

Complete the following steps: 1. Go code is typically organized into one workspace. For more information about setting up your Go workspace, see this web page. The workspace that is shown in Example 2-57 includes the Go workspace set up in the user’s home directory. When you first set up your Go workspace, no content is included in the bin and src directories.

Example 2-57 Example Go workspace directory structure $ pwd /Users/user1/go $ tree -L 5 . ??? bin ? ??? go-outline ? ??? hello ??? src ??? hello ??? hello.go

10 directories, 8 files

2. Set your GOLANG environment variable according to the instructions that are provided at this web page. In Example 2-58, the GOPATH is set to the workspace that was set up in the previous step.

Example 2-58 Setting the GOPATH environment variable $ export GOPATH=/Users/user1/go $ echo $GOPATH /Users/user1/go

Cloning the GitHub code example repository Next, you must clone the GitHub code example repository.

Create a directory into which the GitHub repo is cloned. The suggestion is to clone the GitHub repo to the $GOPATH/src/github.com/ibm-developer/ directory. Therefore, if this directory does not exist on your system, you must create the directories first. Then, issue the git clone command to clone the following repository: https://github.com/ibm-developer/ibm-cloud-hyperprotectcrypto.git

Example 2-59 shows this workflow. (If you do not have the git CLI, you can also download the repository directly from the GitHub website.

Example 2-59 Cloning the GitHub code example repository $ cd $GOPATH $ mkdir src/github.com $ mkdir src/github.com/ibm-developer $ cd src/github.com/ibm-developer $ git clone https://github.com/ibm-developer/ibm-cloud-hyperprotectcrypto.git Cloning into 'ibm-cloud-hyperprotectcrypto'... remote: Enumerating objects: 383, done. remote: Counting objects: 100% (383/383), done.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 87 remote: Compressing objects: 100% (331/331), done. remote: Total 795 (delta 129), reused 53 (delta 52), pack-reused 412 Receiving objects: 100% (795/795), 9.28 MiB | 13.13 MiB/s, done. Resolving deltas: 100% (213/213), done.

Directory structure of code example repository After cloning the GitHub repository, your directory structure should look similar to the example that is shown in Example 2-60.

Note: Because the repository is constantly being updated, your directory structure might look different from what is presented here.

Example 2-60 Directory structure of GREP11 code sample GitHub repository $ tree -L 3 . ??? ibm-cloud-hyperprotectcrypto ??? Gopkg.lock ??? Gopkg.toml ??? LICENSE ??? Makefile ??? README.md ??? golang ? ??? README.md ? ??? ep11 ? ??? examples ? ??? func_workflow.drawio ? ??? func_workflow.svg ? ??? grpc ? ??? mock ? ??? util ??? js ? ??? examples ? ??? fabric ? ??? index.js ? ??? lib ? ??? package-lock.json ? ??? package.json ??? protos ? ??? server.proto ??? vendor ??? github.com ??? golang.org ??? google.golang.org

Getting API key, EP11 address, and service instance ID To perform cryptographic operations by using GREP11 API, generate a GREP11 API request and then, pass the GREP11 API endpoint URL, service ID API key, IAM endpoint, and instance ID through the API call.

This section describes how to obtain your service ID API key, get your IAM endpoint information, your GREP 11 API endpoint URL, and your service instance ID. You need these four pieces of information to run the code examples.

88 Securing Your Critical Workloads with IBM Hyper Protect Services Setting up an IAM service ID API key Use the IBM Cloud IAM windows to setup a service ID API Key for use with HPCS. For more information about that process, see this web page.

Because this key is displayed only once after you create it, copy and save the key to somewhere that is secure.

Getting your IAM endpoint information For IBM Cloud, the IAM endpoint is https://iam.cloud.ibm.com.

Retrieve your GREP 11 API endpoint URL Go to your Hyper Protect Crypto Service Dashboard in the IBM Cloud. In the Manage section, select the EP11 Endpoint URL tab. Copy the address, as shown in Figure 2-20.

Figure 2-20 Retrieving the Hyper Protect Crypto Service EP11 Endpoint URL

Retrieve Hyper Protect Crypto Service instance ID Use the IBM Cloud CLI with the TKE CLI plug-in to retrieve the service instance ID of your Hyper Protect Crypto Service. Complete the following steps: 1. Log in to IBM Cloud by using the ibmcloud CLI: a. Use the IBM Cloud CLI to generate your IAM Access Token. To do this, you must ensure that you have the latest version of ibmcloud CLI installed. For more information about this process, see this web page. In addition, the ibmcloud tke plug-in is required. For more information, see this web page. b. Log in to IBM Cloud. On your IBM Cloud dashboard, select the person icon on the upper right corner and then, select the Log in to CLI and API option. c. Copy the IBM Cloud CLI command that is displayed in the pop-up window. d. Paste the command into a terminal command prompt and select the region that your Hyper Protect Crypto Service is in (see Example 2-61).Depending on your ibmcloud CLI version, your specific output might look different.

Example 2-61 ibmcloud CLI login $ ibmcloud login -a https://cloud.ibm.com -u passcode -p xxxxxxxx API endpoint: https://cloud.ibm.com

Chapter 2. IBM Cloud Hyper Protect Crypto Services 89 Authenticating... OK

Targeted account user1's Account (xxxxxxxxxxxxxxxxxxxxxxxxx) <-> xxxxxx

Select a region (or press enter to skip): 1. au-syd 2. in-che 3. jp-osa 4. jp-tok 5. kr-seo 6. eu-de 7. eu-gb 8. us-south 9. us-south-test 10. us-east Enter a number> 8 Targeted region us-south

API endpoint: https://cloud.ibm.com Region: us-south User: [email protected] Account: user1's Account (xxxxxxxx) <-> xxxxxx Resource group: No resource group targeted, use 'ibmcloud target -g RESOURCE_GROUP' CF API endpoint: Org: Space:

2. Set your target resource group. In Example 2-62, the resource group is “default” (depending on your ibmcloud CLI version, your specific output might look different).

Example 2-62 Selecting a resource group by using the ibmcloud CLI $ ibmcloud target -g default Targeted resource group default

API endpoint: https://cloud.ibm.com Region: us-south User: [email protected] Account: user1's Account (xxxxxxxx) <-> xxxxxx Resource group: default CF API endpoint: Org: Space:

90 Securing Your Critical Workloads with IBM Hyper Protect Services Tip: If you are managing Cloud Foundry applications and services - Use 'ibmcloud target --cf' to target Cloud Foundry org/space interactively, or use 'ibmcloud target --cf-api ENDPOINT -o ORG -s SPACE' to target the org/space. - Use 'ibmcloud cf' if you want to run the Cloud Foundry CLI with current IBM Cloud CLI context.

Now you are ready to retrieve your unique Hyper Protect Crypto Service Instance ID. 3. Ensure that you have the ibmcloud tke plug-in installed. For more information, see this web page. 4. Set up your CLOUDTKEFILES environment variable in your terminal. This environment variable points to your TKE files that are generated during the master key initialization (see 2.2, “Creating an instance of Hyper Protect Crypto Services on the public IBM Cloud” on page 30). The CLOUDTKEFILEs are in the user’s home directory, as shown in Example 2-63.

Example 2-63 Setting the CLOUDTKEFILES environment variable $ CLOUDTKEFILES=/Users/jinvanstee/hyperprotect/tkefiles

5. Run the ibmcloud tke command to display your cryptounits, which display your service instance ID. (Depending on the version of the ibmcloud tke plug-in that you use, your output might vary slightly from what is shown in Example 2-64.)

Example 2-64 Displaying cryptounits using the ibmcloud TKE CLI $ ibmcloud tke cryptounits Verifying the OA certificate chain for serial number xxxxx... Successfully verified the OA certificate chain for xxxxx.

API endpoint: https://cloud.ibm.com Region: us-south User: [email protected] Account: user1's Account (xxxxxxxxxx) Resource group: default

SERVICE INSTANCE: 468a3400-7d20-4f91-aaef-5ebb1b14beea CRYPTO UNIT NUM SELECTED LOCATION 1 true [us-south].[AZ2-CS2].[01].[06]

Note: all crypto units in a service instance must be configured the same. Use 'ibmcloud tke cryptounit-compare' to check how crypto units are configured.

The service instance ID that is shown in Example 2-64 is: 468a3400-7d20-4f91-aaef-5ebb1b14beea

Running Go code example Now you have the IAM Service API Key, IAM endpoint, Service Instance ID, and the EP11 endpoint URL of your Hyper Protect Crypto Service. You are ready to run the Go code example.

For more information about running the sample code, see the readme file that is documented in this GitHub repo.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 91 Running Node.js code example For more information about running the Node code example, see the readme file that is documented in this GitHub repo.

2.6 Hyper Protect Crypto Services use cases

Hyper Protect Crypto Services features the following use cases: Protecting IBM Cloud services that offer integration with the key management service feature of Hyper Protect Crypto Services. For more information, see 2.6.1, “Protecting IBM Cloud services” on page 92. Using the GREP11 API for performing cryptographic operations, protected by a FIPS 140-2 Level 4-certified hardware security module (HSM). For more information, see 2.6.2, “Using the GREP11 API” on page 93.

2.6.1 Protecting IBM Cloud services

The following services are offered in the IBM Cloud also offer integration with Hyper Protect Crypto Services to allow you to provide extra protection: Hyper Protect DBaaS for PostgreSQL Hyper Protect DBaaS for MongoDB IBM Cloud Object Storage IBM Cloud Block Storage for Virtual Private Cloud IBM Cloud Virtual Servers for Virtual Private Cloud Key Management Interoperability Protocol (KMIP) for VMware on IBM Cloud HyTrust DataControl for IBM Cloud IBM Cloud Kubernetes Service (IKS) Red Hat OpenShift on IBM Cloud

Tip: This list is expected to grow over time as more services that are offered in the IBM Cloud add support for integration with Hyper Protect Crypto Services. For more information about the list of services, see this web page.

The official hHyper Protect Crypto Services documentation describes the types of protection that is offered by each service.

Although the exact implementation of the integration can vary for each service, enabling the integration of an IBM Cloud service with Hyper Protect Crypto Services uses the following general process: Use IBM Cloud Identity and Access Management (IAM) to assign access rights to the Hyper Protect Crypto Services service instance from the IBM Cloud service that offers integration to Hyper Protect Crypto Services Create a root key in your dedicated Hyper Protect Crypto Services keystore. This key might be a new root key that was created by the Hyper Protect Crypto Services service or an existing key you choose to import into the service. Configure the IBM Cloud service offering integration with the instructions it provides about how to integrate with Hyper Protect Crytpo Services. This task typically involves selecting your Hyper Protect Crypto Services instance that you authorized to the service through IAM and then selecting the root key that you want to use for the service.

92 Securing Your Critical Workloads with IBM Hyper Protect Services The service uses the Key Protect API on your behalf to call Hyper Protect Crypto Services to create a data-encryption key (DEK) that it uses for encryption and decryption of data within the service. The service protects your data and your key: – The service uses the Key Protect API to wrap the DEK with the root key that you assigned to the service. It stores this wrapped DEK, which is secure because this DEK cannot be used in its wrapped state and the root key that wrapped it is stored securely in your Hyper Protect Crypto Services keystore. – When your service needs to use the DEK, it uses the Key Protect API to unwrap the DEK so that it can be used for encryption and decryption. The service does not persist the unwrapped DEK on persistent storage; instead, it removes it from volatile memory when it is no longer needed.

Tutorials are available that demonstrate how to integrate Hyper Protect Crypto Services into solutions that use other IBM Cloud services. Click Tutorials in left navigation pane at this web page for the following tutorials: Using IBM Cloud Hyper Protect Crypto Services to encrypt VMware disks Applying end to end security to a cloud application Enhancing security of your deployed application

2.6.2 Using the GREP11 API

All of the cryptographic operations that are started through the GREP11 API are performed inside of the boundaries of the FIPS 140-2 Level 4-certified HSM. These operations can help organizations comply with internal security requirements and external regulatory or industry-specific requirements.

You can perform the following cryptographic operations with the GREP11 API: Key generation Data encryption and decryption Digital signature signing and verification Wrapping and unwrapping keys Deriving keys Creating message digests (hashing)

You can access the GREP11 API that is offered by your Hyper Protect Crypto Services instance from your existing applications (on-premises or in the cloud) if your application includes authorization to access and network addressability to your Hyper Protect Crypto Services instance.

Keys that are returned by the GREP11 API are returned in the form of an object called a key blob. This key blob is wrapped by the HSM master key that only you can control and access. Not even IBM Cloud administrators can access this HSM master key.

Note: The public key part of a public/private (that is, asymmetric) key pair can be extracted from a key blob object in decrypted form outside the HSM because by definition the public key is safe to share.

Chapter 2. IBM Cloud Hyper Protect Crypto Services 93 The key blobs that are created by the GREP11 API are not stored within the HSM. It is your responsibility to store them. You can store them with confidence knowing that these key blobs are unusable outside of your Hyper Protect Crypto Services instance, unless you explicitly defined other Crypto Express cards in your computing infrastructure to use the same Master Key that you used for your Hyper Protect Crypto Services instance.

94 Securing Your Critical Workloads with IBM Hyper Protect Services 3

Chapter 3. IBM Cloud Hyper Protect DBaaS

This chapter introduces IBM Cloud Hyper Protect DBaaS and includes the following topics: 3.1, “Introduction to IBM Cloud Hyper Protect DBaaS” on page 96 3.2, “Sizing and topology” on page 97 3.3, “Public Cloud Service instantiation” on page 98 3.4, “Administration and operations” on page 105 3.5, “Security and compliance” on page 114 3.6, “Use case: Encrypting databases with your keys protected” on page 114 3.7, “API interaction and code samples” on page 115

IBM Cloud Hyper Protect DBaaS (Hyper Protect DBaaS) is a solution that offers clients the ability to easily provision fully managed and highly secured database environments for enterprise workloads with sensitive information without the need for specialized database administration (DBA) skills.

Hyper Protect DBaaS is built upon IBM LinuxOne technologies that provide built-in encryption along with abilities for excellent scaling and performance. These features allow for workload isolation that keeps data owners in complete control of their data. The solution provides a developer-friendly platform with fully managed logging, monitoring, backups, high availability, and scaling solutions, which enables developers to focus on higher value application development rather than the management of the environment.

Figure 3-1 shows the Hyper Protect DBaaS service instance.

Figure 3-1 Hyper Protect DBaaS service instance

96 Securing Your Critical Workloads with IBM Hyper Protect Services 3.2 Sizing and topology

The Hyper Protect DBaaS provides different sizes in terms of database instances. Different type of databases might have different memory and storage in the versions, including the following example for Hyper Protect DBaaS for PostgreSQL: Free (30 days availability): – 1 GB memory – 2 GB of data storage Small: – 32 GB memory – 320 GB of data storage Medium: – 64 GB memory – 640 GB of data storage Large: – 128 GB memory – 1280 GB of data storage

You can select a suitable size of a database instance based on your workload requirements. After an instance is created, you can migrate your own data to the database by using a memory dump and restore function of the databases. For more information about migrating PostreSQL databases to the Hyper Protect DBaaS for PostgreSQL, see this IBM Cloud web page.

As of this writing, the Hyper Protect DBaaS service provides 99.95% of high availability and reliability for mission-critical workloads. After an instance is created, IBM Cloud Hyper Protect DBaaS provides automatic in-region data redundancy and failover by default.

By default, your Hyper Protect DBaaS service instance consists of three nodes: one primary and two secondary nodes in three different availability zones in your selected IBM Cloud region. The data in your primary node is automatically replicated to secondary nodes (replicas) with low latency (see Figure 3-2).

Figure 3-2 Hyper Protect DBaaS high availability

Chapter 3. IBM Cloud Hyper Protect DBaaS 97 When your primary node fails, a secondary node in the cluster is selected as the primary to prevent your applications from being affected. In this way, you have automatic high availability within one region for your data.

From Disaster Recovery perspective, to create cross-region data redundancy, you need to regularly back up your complete databases from your service instance in a region. When the region is unavailable, you can provision a new service instance in another available region to restore your database manually. The time that it takes to restore varies because it depends on the size of your data and network condition.

Also, IBM Cloud Hyper Protect DBaaS automatically triggers a backup of your complete database once every 24 hours. These encrypted backups are available for the last seven days and redundantly available on local storage in all availability zones of the supported regions. You can open a support request to restore your database by IBM support.

3.3 Public Cloud Service instantiation

The Hyper Protect DBaaS service has different options available for service instantiation through the following methods of interaction: Web Interface (GUI) IBM Cloud command-line-interface (CLI) Hyper Protect DBaaS RESTful API

3.3.1 Prerequisites

The IBM Hyper Protect DBaaS service shares a set of prerequisites with the other Hyper Protect Cloud services. To begin the service instantiation process, it is assumed that the following prerequisites were met: Supported browser Installation of: – IBM Cloud command-line-interface (CLI) – IBM Cloud DBaaS CLI plug-in

3.3.2 Web Interface

This section describes creating a Hyper Protect DBaaS service instance on IBM Cloud by using the web interface (GUI). It is assumed that you meet the prerequisites that are described in 6.1, “Planning and prerequisites for Hyper Protect Virtual Servers on-premises” on page 144.

Complete the following steps: 1. Log in to your IBM Cloud account at https://cloud.ibm.com/login. 2. From the IBM account dashboard click Catalog in the top menu bar, as shown in Figure 3-3 on page 99.

98 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 3-3 IBM Cloud Dashboard

3. Enter Hyper Protect DBaaS into the search bar and choose which database offering to provision for use, such as Hyper Protect DBaaS for MongoDB or Hyper Protect DBaaS for PostgreSQL, as shown in Figure 3-4.

Figure 3-4 Catalog search results for Hyper Protect DBaaS for MongoDB and PostgreSQL

4. After selecting which database offering to provision, choose a deployment region on the service create page.

Note: IBM Cloud offers multiple availability zones in regions across the globe to host your Hyper Protect DBaaS service instance, such as Dallas, Frankfurt, or Sydney.

5. Choose a pricing plan and sizing. An example pricing option for Hyper Protect DBaaS is shown in Figure 3-5 on page 100. For more information about sizing, see 3.2, “Sizing and topology” on page 97.

Chapter 3. IBM Cloud Hyper Protect DBaaS 99 Figure 3-5 Hyper Protect DBaaS for MongoDB pricing plans

Note: Free Plan instances are for evaluation only and not suitable for production workloads. Free Hyper Protect DBaaS services are automatically deleted after a period of 30 days.

6. Configure your resource by setting the Service Name, Resource Group, Tags (optional), Database Cluster Name, the database administrator user name, and database administrator password. 7. Agree to the terms and select Create.

3.3.3 IBM Cloud CLI

This section describes instantiating a Hyper Protect DBaaS service instance on IBM Cloud by using the IBM Cloud command-line-interface (CLI) and DBaaS CLI plug-in. It is assumed that the prerequisites that are outlined in 3.3.1, “Prerequisites” on page 98 are met.

To verify the installation of the IBM Cloud CLI and the DBaaS plug-in, use the ibmcloud command. The system shows dbaas in the list of available commands.

100 Securing Your Critical Workloads with IBM Hyper Protect Services Logging in to the IBM Cloud CLI Before issuing a create service command, authenticate the IBM Cloud CLI by issuing the following example command: ibmcloud login --sso -a https://cloud.ibm.com

For more information and reference material about all options for authentication, see this IBM Cloud CLI documentation.

The CLI prompts for a one-time authorization code that can be opened in the default browser or by copying the link into a supported browser, as shown in the output in Example 3-1.

Example 3-1 Authentication output from IBM Cloud CLI using SSO Get One Time Code from https://identity-2.us-south.iam.cloud.ibm.com/identity/passcode to proceed. Open the URL in the default browser? [Y/n] > n One Time Code > Authenticating... OK

Targeting a resource group After authenticating with the IBM Cloud CLI, target a resource group by using the ibmcloud target command to direct your deployments. In the following example, the resource group Default is used: ibmcloud target -g Default

For more information about resource groups, see this IBM Cloud web page.

Choosing a target region IBM Cloud provides various service endpoints in regions across the globe that can be used to deploy services. Selecting a region correspond to the geographical deployment of the Hyper Protect DBaaS service instance.

To locate a region, use the ibmcloud regions command as shown in Example 3-2.

Example 3-2 IBM Cloud CLI output of regions ~$ ibmcloud regions Listing regions...

Name Display name au-syd Sydney jp-tok Tokyo eu-de Frankfurt eu-gb London us-south Dallas us-east Washington DC

Note: At the time of this writing, IBM Cloud Hyper Protect DBaaS is supported in the us-south, eu-de, and au-syd regions. Current supported regions can be referenced in the documentation for the service.

Chapter 3. IBM Cloud Hyper Protect DBaaS 101 Creating a service instance To create a service instance by using the IBM Cloud CLI, use the ibmcloud resource service-instance-create command as described next.

To view all the available options for Hyper Protect DBaaS services, run a catalog search, as shown in Example 3-3.

Example 3-3 IBM Cloud CLI Catalog Search command ibmcloud catalog search --kind service hyperp-dbaas

After deciding on the type of database to provision, Example 3-4 and Example 3-5 show how the command can be issued. The CLI parameters are listed in Table 3-1.

Example 3-4 Creating a MongoDB service instance using the IBM CLI ibmcloud resource service-instance-create ExampleMongoDB hyperp-dbaas-mongodb mongodb-free us-east -p '{"name":"DBaaSMongoCLICluster", "admin_name":"admin","password":"passWORD4User19", "confirm_password":"passWORD4User19", "license_agree":["agreed"]}'

Example 3-5 Creating a PostgreSQL service instance using the IBM CLI ibmcloud resource service-instance-create ExamplePostgreSQL hyperp-dbaas-postgresql postgresql-free us-east -p '{"name":"DBaaSPostgresCLICluster", "admin_name":"admin","password":"passWORD4User19", "confirm_password":"passWORD4User19", "license_agree":["agreed"]}'

Table 3-1 CLI parameters Parameter Definition

ExamplePostgreSQL The name of the service instance.

hyperp-dbaas-postgresql The catalog name of Hyper Protect DBaaS for PostgreSQL.

postgresql-free The service plan name.

us-east The region where the service is deployed.

-p A JSON sting that contains parameters for instantiation. For more information, see the documentation about service instances.

This creation process takes a few minutes to complete. The status of the new service can be verified through the IBM Cloud CLI by using the ibmcloud resource service-instances command, as shown in Example 3-6. When the service state is active, the database is ready to use.

Example 3-6 Output of a DBaaS instance, ready to use, in the active state ~$ ibmcloud resource service-instances Retrieving instances with type service_instance in resource group Default in all locations under account Jordan Cartwright as [email protected]... OK Name Location State Type MyDBaaSIns03 us-east active service_instance

102 Securing Your Critical Workloads with IBM Hyper Protect Services Alternatively, the service creation progress can also be seen in the web interface for IBM Cloud on the Resource list page.

Note: For more information about other DBaaS CLI plug-in commands, see this web page.

3.3.4 Hyper Protect DBaaS RESTful API

This section describes instantiating a Hyper Protect DBaaS service instance on IBM Cloud by using the Hyper Protect DBaaS RESTful API. It is assumed that you meet the prerequisites that are outlined in 3.3.1, “Prerequisites” on page 98.

Generating an API key A customer API key is needed for communicating with the DBaaS RESTful API. Complete the following steps to obtain a key for use on the account: 1. On the IBM Cloud dashboard, select Manage → Access (IAM). 2. From the IAM dashboard, select IBM Cloud API Keys. 3. Click Create an IBM Cloud API Key on this page. In the modal window, enter a name and description for the API key. Click Create. You can copy your API key and download a JSON file that contains information about your API key. An example of this file is shown in Example 3-7.

Note: This information cannot be seen after leaving the page. Take note of this value now. An option to download the API key JSON file also is available.

Example 3-7 Generated API key output { "name": "My API key", "description": "DBaaS Manager Key", "createdAt": "2019-12-05T18:58+0000", "apiKey": "******" }

Choosing a DBaaS Manager Creating a Hyper Protect service instance requires direct communication to the dbaas manager in the region of deployment. This requirement exists because the dbaas manager represents the region to which you are deploying.

Chapter 3. IBM Cloud Hyper Protect DBaaS 103 The current supported regions are shown in Figure 3-6.

Figure 3-6 DBaaS Managers

Authenticating by using the API After obtaining an API key for use with the Hyper Protect DBaaS API, users must authenticate with the API directly to request an access token for commands to be issued against the DBaaS service.

For secure data transfer, retrieve the certificate authority (CA) file from the service dashboard. This file should be used in configurations with all API requests to ensure that all communication that is started through the API is secure.

Example 3-8 shows the auth api call by using the api that is generated from in Example 3-7 on page 103 in the create api key section. We are also directly communicating with the Dallas dbaas manager by using the Dallas host name from Figure 3-6.

Example 3-8 API authentication call curl -X GET -H "accept: application/json" -H "api_key: *****" --cacert /etc/ssl/certs/cert.pem https://dbaas900.hyperp-dbaas.cloud.ibm.com:20000/api/v1/auth/token

This Authentication request returns the user ID of the account and the access token for use in subsequent api calls for interacting with the Hyper Protect DBaaS service. An example of this output is shown in Example 3-9.

Example 3-9 Authentication request output

{ "access_token": "IyMDE5MDc……XkQMVSi", "user_id": "fc335ed……713" }

Tip: The generated access token expires in 1 hour from the time it is generated. After this time, another call to the authentication endpoint is required to continue issuing API calls to the DBaaS Managers.

104 Securing Your Critical Workloads with IBM Hyper Protect Services Issuing a create service request Using the access token that is generated from the previous section, an account owner can issue the create service call to provision an instance of the Hyper Protect DBaaS service on IBM Cloud by following the example that is shown in Example 3-10.

Example 3-10 Create PostgreSQL service instance using the API curl -X POST \ "https://:/api/v1/{user_id}/services" \ -d '{"catalog": "hyperp-dbaas-postgresql", "name": , "resource_group": "Default", "plan": "postgresql-free", "admin_name": "admin", "password": }' \ -H "x-auth-token: {access_token}" \ -H "content-type: application/json" \ -H "accept: application/json" \ -H "accept-license-agreement: yes"

This command from Example 3-10 is issuing a POST request against the Hyper Protect DBaaS APIs services endpoint to create a PostgreSQL cluster on the IBM cloud account with the associated API key.

We are creating a free Hyper Protect DBaaS PostgreSQL instance with the administrator user named admin.

3.4 Administration and operations

Hyper Protect DBaaS supports various levels of administration oversight for the service.

3.4.1 Managing a Hyper Protect DBaaS Service

Managing a Hyper Protect DBaaS service can be done through the IBM Cloud dashboard under the Services section on the Resource List page. On this page, administrators can use the Actions Menu by clicking the three dots button that is on the right of the targeted service instance.

Clicking the name of a Hyper Protect DBaaS service brings administrators to the service dashboard for that selected service. This management interface enables the use of more fine-tuned options for administrative management of a Hyper Protect DBaaS service.

Service overview The service overview page shows general information about the Hyper Protect DBaaS service, such as the plan overview that includes storage, memory, and nodes that are associated with the database cluster. The overview page also gives administrators quick insight to the number of users and databases that are on the service cluster.

The overview page is also the location for users to retrieve their certificate authority (CA) file to form a secure connection to their database. Many administrative tasks can be performed from this page.

Changing the name of a service From the Resource List page, account administrators can select the Actions Menu and select the Edit Name option to update the name of the service.

Chapter 3. IBM Cloud Hyper Protect DBaaS 105 Under the service dashboard for a Hyper Protect DBaaS service, administrators can click the Service Instance Actions Menu to the right of the overview page and select Rename Service to edit the Service name.

Deleting a service From the Resource List page, account administrators can select the Actions Menu and choose the Delete option to remove the service from your account. When a service is deleted, all data that is associated with the Hyper Protect DBaaS service is gone and permanently inaccessible.

3.4.2 Managing database instances

Managing a Hyper Protect database instance can be done through the IBM Cloud dashboard from the Resource List page. Select a Hyper Protect Service to enter the management interface

Creating databases Administrators can create databases on the database page under the Hyper Protect DBaaS management interface. This task can also be done by using the Hyper Protect DBaaS RESTful API, which is described in 3.7, “API interaction and code samples” on page 115.

To create a database from the management interface, browse to the databases page on your Hyper Protect DBaaS service. Administrators can use the Create button to easily deploy a new database on their cluster. After completing the required fields for creating the database, click Create to create the database on the cluster that is ready for interaction.

Deleting databases Created databases can also be deleted from the database page on the management interface by clicking a database and selecting Delete. Multiple databases can be deleted at once by selecting the databases before clicking Delete. Also, this action is supported by using the Hyper Protect DBaaS RESTful API (see 3.7, “API interaction and code samples” on page 115).

3.4.3 Managing database users

Managing database users for a Hyper Protect DBaaS instance can be done through the management interface, which is similar to managing databases.

Creating database users To create users on a Hyper Protect database, browse to the Resource List from the IBM Cloud dashboard. Select the database instance to which users are to be added. On the Management Interface page, select the users page and click Create.

106 Securing Your Critical Workloads with IBM Hyper Protect Services In the Create User window, enter the name of the user, a user password, and authentication options for that user to control access on the database (see Figure 3-7).

Figure 3-7 Create User window

Database users also can be created in the database by connecting to the database instance by using tools, such as Mongo shell for MongoDB or psql for PostgreSQL.

Deleting database users Administrators can remove users from their database through the user page on the service management interface.

Multiple users can be deleted at once by selecting the users for deletion and then clicking Delete.

3.4.4 Logging and monitoring

In this section, the logging and monitoring functions are described.

Logging Hyper Protect DBaaS allows for log downloading through the Nodes page under the management interface dashboard for a database cluster. On the Nodes page, users can choose a replica to download specific log files or all log files for the database replica. An example of the nodes page is shown in Figure 3-8 on page 108.

Chapter 3. IBM Cloud Hyper Protect DBaaS 107 Figure 3-8 Log files from the Nodes page

IBM Log Analysis with LogDNA In addition to downloading the logs, users can set up external logging through integration with a Log DNA instance on IBM Cloud for more log analysis.

Complete the following steps to set up your Hyper Protect DBaaS: 1. Ensure that you are logged in to an IBM account on IBM Cloud. 2. Create a LogDNA instance by browsing to the Observability dashboard on IBM Cloud. To do this, open the hamburger menu on the left side of the IBM Cloud dashboard and select Observability. 3. On the Observability page, select Create logging instance under IBM Log Analysis with LogDNA. The following page prompts you for information that is needed to create the logging instance. Enter a meaningful name for the LogDNA instance, choose a deployment region, resource group, and a pricing plan for your instance to determine log retention.

Note: The region that is selected is the region that features monitored logging. This region is the same region to which the Hyper Protect DBaaS instance was deployed.

4. After providing the information to create your IBM LogDNA instance, select Create and browse back to your DBaaS service to enable logging. To enable logging on the DBaaS cluster, browse to the service management page and click the Logging tab. 5. Click Enable logging. After that process completes, click View logs in LogDNA. 6. You are returned to the Logging Observability page where you see your created instance of LogDNA. At the top of this page, click Configure platform services logs. This process allows the linking for the IBM Cloud region to be directed to the instance of LogDNA. When opening the configure platform services logs link, choose the region that your Hyper Protect DBaaS and LogDNA instance are in. 7. Choose the instance of LogDNA that displays the logs. 8. Click Save. An example of this configuration is shown in Figure 3-9 on page 109.

108 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 3-9 Configure platform services logs for LogDNA

At this point, the LogDNA instance is fully configured to display the logs from the Hyper Protect DBaaS service. Starting LogDNA by clicking View in LogDNA on the Logging Observability page opens a new window of LogDNA (see Figure 3-10).

Note: it can take some time for LogDNA to register the DBaaS instance as a source for logs initially. After this process, registered logs are shown in the main window.

Figure 3-10 LogDNA user interface

Chapter 3. IBM Cloud Hyper Protect DBaaS 109 Monitoring a database As with logging, database monitoring is disabled on a Hyper Protect DBaaS service by default. Complete the following steps to enable monitoring on your cluster: 1. Ensure that access to a Cloud Foundry organization and space in Dallas, Frankfurt, or Sydney exist. To verify this information, from the IBM Cloud menu bar, click Manage → Access (IAM) → Users and then, click the user name to manage. 2. Click Cloud Foundry access. Expanding the organization that you are apart of displays the cloud foundry information. If this information is not displayed, see the Cloud Foundry documentation. 3. After confirming that Cloud Foundry is set up correctly on the account, browse to the Monitoring page on the DBaaS service management interface and click Enable Monitoring. 4. After monitoring is configured, click View monitoring information in Grafana. Grafana 4 is started in a new window where configuring a monitoring dashboard is available. 5. On Grafana, create a dashboard by clicking Home and then, clicking Create New. The available metrics that can be monitored are the percentage of memory usage inside your cluster’s replicas. Figure 3-11 shows an example of a configured dashboard in Grafana.

Figure 3-11 DBaaS Grafana Dashboard

In addition to IBM Cloud monitoring, external tools can be used, such as MongoDB Compass and pgAdmin, to connect to and interact with a Hyper Protect DBaaS instance.

110 Securing Your Critical Workloads with IBM Hyper Protect Services 3.4.5 Back up and restore

As described in 3.2, “Sizing and topology” on page 97, the Hyper Protect DBaaS includes automatic database backups in all availability zones every 24 hours by default. You can restore from those backups within last 7 days by way of IBM Support.

In some cases, you want to make more backups manually to increase your data availability. Take disaster recovery scenario for example; you might want to back up your database to a cloud Object Storage in a different region and restore it to another database instance.

This section describes manual backup a database, with PostgreSQL and MongoDB, to IBM Object Storage and restore the data to another database instance.

Before you back up your database to IBM Object Storage, you must create an IBM Object Storage in another IBM Cloud region (for example, in the UK) first, while your database is in Dallas, US. For more information about creating an IBM Object Storage, bucket, and service credentials, see the documentation at this IBM Cloud web page.

After you create an IBM Object Storage, you can use an Object Storage client to access the data that is in the storage bucket.

Note: Many third-party Object Storage clients are available. You can use any s3 client that you prefer. In this section, s3cmd is used to complete the Object Storage operations.

The s3cmd tool is available at the GitHub website.

Backing up PostreSQL database to IBM Object Storage In this example, a sample database sakila is in Dallas region. Example 3-11 shows the command to back up the data to your local disk.

Example 3-11 Backup database to local disk # pg_dump -h dbaas901.hyperp-dbaas.cloud.ibm.com -p 28154 -U db01 -d sakila -f sakila.dump

After the back-up is done, you can use the s3 client to upload the data to the IBM Object Storage (see Example 3-12).

Example 3-12 Upload data to IBM Object Storage # s3cmd ls 2019-12-05 16:18 s3://s3-bucket-database

# s3cmd put sakila.dump s3://s3-bucket-database upload: 'sakila.dump' -> 's3://s3-bucket-database/sakila.dump' [1 of 1] 3084689 of 3084689 100% in 0s 3.95 MB/s done

# s3cmd la 2019-12-05 21:34 3084689 s3://s3-bucket-database/sakila.dump

Chapter 3. IBM Cloud Hyper Protect DBaaS 111 When it is needed, you can download the file from the Object Storage and restore the data to a database instance (see Example 3-13).

Example 3-13 Restore data # psql -h dbaas901.hyperp-dbaas.cloud.ibm.com -p 28154 -U db01 -d sakila -f sakila.dump SET SET SET SET SET set_config ------

(1 row)

SET SET SET SET ALTER SCHEMA CREATE EXTENSION CREATE EXTENSION CREATE TYPE ALTER TYPE CREATE DOMAIN ALTER DOMAIN CREATE FUNCTION ALTER FUNCTION CREATE FUNCTION ALTER FUNCTION CREATE FUNCTION ALTER FUNCTION CREATE FUNCTION ... setval ------32098 (1 row)

setval ------16049 (1 row)

setval ------2 (1 row)

112 Securing Your Critical Workloads with IBM Hyper Protect Services Backing up MongoDB database to IBM Object Storage In this example, a sample database that is named inventory is in Dallas region. Example 3-14 shows the command to back up the data to your local disk.

Example 3-14 Backup database #mongodump --host "mongo/dbaas30.hyperp-dbaas.cloud.ibm.com:28032,dbaas31.hyperp-dbaas.cloud.ibm.com :28117,dbaas29.hyperp-dbaas.cloud.ibm.com:28242" --ssl --username mongo --authenticationDatabase admin --db inventory --sslCAFile cert_mongo.pem --out listing.dump

2019-12-06T16:06:19.681+0000writing inventory.listings to 2019-12-06T16:06:20.846+0000[...... ] inventory.listings 101/48377 (0.2%) 2019-12-06T16:06:23.846+0000[###...... ] inventory.listings 7821/48377 (16.2%) 2019-12-06T16:06:26.846+0000[########...... ] inventory.listings 16459/48377 (34.0%) 2019-12-06T16:06:29.846+0000[############...... ] inventory.listings 24890/48377 (51.5%) 2019-12-06T16:06:32.846+0000[################...... ] inventory.listings 33463/48377 (69.2%) 2019-12-06T16:06:35.846+0000[####################....] inventory.listings 41847/48377 (86.5%) 2019-12-06T16:06:37.742+0000[########################] inventory.listings 48377/48377 (100.0%) 2019-12-06T16:06:37.742+0000done dumping inventory.listings (48377 documents)

After the back-up is complete, you can use the s3 client to upload the data to the IBM Object Storage, as shown in Example 3-12 on page 111.

When it is needed, you can download the files from the Object Storage and restore the data to a database instance, as shown in Example 3-15.

Example 3-15 Restore data to MongoDB # mongorestore --host "mongo/dbaas30.hyperp-dbaas.cloud.ibm.com:28032,dbaas31.hyperp-dbaas.cloud.ibm.com :28117,dbaas29.hyperp-dbaas.cloud.ibm.com:28242" --ssl --username mongo --authenticationDatabase admin --db inventory_new --sslCAFile cert_mongo.pem listing.dump/inventory

2019-12-06T16:22:53.585+0000the --db and --collection args should only be used when restoring from a BSON file. Other uses are deprecated and will not exist in the future; use --nsInclude instead 2019-12-06T16:22:53.585+0000building a list of collections to restore from listing.dump/inventory dir 2019-12-06T16:22:53.627+0000reading metadata for inventory_new.listings from listing.dump/inventory/listings.metadata.json 2019-12-06T16:22:53.674+0000restoring inventory_new.listings from listing.dump/inventory/listings.bson 2019-12-06T16:22:56.142+0000[####...... ] inventory_new.listings 49.6MB/275MB (18.1%) 2019-12-06T16:22:59.142+0000[#########...... ] inventory_new.listings 111MB/275MB (40.4%)

Chapter 3. IBM Cloud Hyper Protect DBaaS 113 2019-12-06T16:23:02.142+0000[###############...... ] inventory_new.listings 178MB/275MB (64.9%) 2019-12-06T16:23:05.142+0000[#####################...] inventory_new.listings 247MB/275MB (89.7%) 2019-12-06T16:23:06.691+0000[########################] inventory_new.listings 275MB/275MB (100.0%) 2019-12-06T16:23:06.692+0000no indexes to restore 2019-12-06T16:23:06.692+0000finished restoring inventor_new.listings (48377 documents) 2019-12-06T16:23:06.692+0000done

3.5 Security and compliance

The data at-rest and data in-transit of the Hyper Protect DBaaS is highly encrypted by a dedicated Hardware Security Module (HSM) by default. The entire database environment is a secure enclave.

The data is encrypted based on FIPS 140-2 Level 4-certified HSM, which is the highest level of security in the industry. Access to the service occurs over HTTPS, which is the service that uses Transport Layer Security (TLS) 1.2 protocol to encrypt data in transit. Therefore, no one else, including IBM Cloud administrators, can access the data in your databases in the cloud without keys. Only Environment Log information is included outside of secure enclave for the IBM SRE team.

The Hyper Protect DBaaS service features the following industry and security compliance certifications: FIPS 140-2 Level 4 GDPR ISO 27001, 27017, 27018 HIPAA

For more information about IBM Cloud, see this web page.

3.6 Use case: Encrypting databases with your keys protected

The data in Hyper Protect DBaaS service on the IBM Cloud is pervasively encrypted with HSM by default by randomly generated keys. The Hyper Protect DBaaS service supports scenarios of keep your own key (KYOK) and bring your own key (BYOK).

Therefore, you can use IBM Cloud Hyper Protect Crypto Services to create, add, and manage encryption keys and associate the keys with your Hyper Protect DBaaS service instances to encrypt your databases. In that way, you can fully control over your encryption keys.

Complete the following steps to integrate the Hyper Protect Crypto Service and Hyper Protect DBaaS: 1. Create an instance of Hyper Protect Crypto Service. 2. In the Hyper Protect Crypto Service, create or import a root key. 3. Complete the following steps to grant authorization to Hyper Protect DBaaS instances by using the Hyper Protect Crypto service with IAM in your account: a. From the menu bar, click Manage → Access (IAM).

114 Securing Your Critical Workloads with IBM Hyper Protect Services b. In the side navigation, click Authorizations. c. Click Create. d. In the Source service menu, select Hyper Protect DBaaS for MongoDB. e. In the Source service instance menu, select All service instances. f. In the Target service menu, select Hyper Protect Crypto Services. g. In the Target service instance menu, select the service instance to authorize. h. Enable the Reader role. i. Click Authorize. 4. Create an instance of Hyper Protect DBaaS and select your Hyper Protect Crypto Service instance and root key. An example of creating a Hyper Protect DBaaS for MongoDB is shown in Figure 3-12.

Figure 3-12 Create Hyper Protect DBaaS for MongoDB with KYOK/BYOK

Note: If you delete your keys in the Hyper Protect Crypto Service, you cannot recover your data from the backups because even the IBM Cloud administrator cannot access your data. However, if you have manual backups and store the backups in other places, you might recover your data by using restoring a backup into a new DB instance.

3.7 API interaction and code samples

Hyper Protect DBaaS supports interaction through a robust API built on the principles of RESTful interaction. For more information about the methods that are available to customers in the API, see this web page.

Chapter 3. IBM Cloud Hyper Protect DBaaS 115 The Hyper Protect DBaaS API uses token authentication. Therefore, before issuing requests against a DBaaS manager, an access token must be requested from the API. This process can be done by sending a post request to the auth/token endpoint. An example of this process is shown in Example 3-8 on page 104, which uses the curl package.

After receiving an authentication token from the API, users can interact with various endpoints that encompass interaction with the DBaaS clusters, service, users, databases, and instances. For more information about these interaction methods, see the API documentation.

The examples from the documentation pages were created by using the curl command. However, the API also can be wrapped by other languages, such as Python, to interact with the DBaaS REST API. The example from the GitHub repository provides basic wrapping options for some of the DBaaS API endpoints by sing Python 3 and the Requests package.

3.7.1 Cloning the GitHub example Python code

The example code from GitHub can be cloned from this repository. Example 3-16 shows the git command that is used.

Example 3-16 Cloning the GitHub example repository $ git clone https://github.com/IBMRedbooks/SG248469-Securing-your-critical-workloads-with-IBM- Hyper-Protect-Services.git Cloning into 'SG248469-Securing-your-critical-workloads-with-IBM-Hyper-Protect-Services'... remote: Enumerating objects: 3, done. remote: Counting objects: 100% (3/3), done. remote: Compressing objects: 100% (2/2), done. remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 Unpacking objects: 100% (3/3), done.

3.7.2 Setting up a Python virtual environment with requests

After cloning the repository from GitHub, you can initialize a Python virtual environment to keep an installation of Python separated from this example (see Example 3-17).

Example 3-17 Set up a python virtual environment $ python3 -m venv venv $ source venv/bin/activate (venv) $ pip install requests Collecting requests Using cached https://files.pythonhosted.org/packages/51/bd/23c926cd341ea6b7dd0b2a00aba99ae0f828 be89d72b2190f27c11d4b7fb/requests-2.22.0-py2.py3-none-any.whl Collecting certifi>=2017.4.17 (from requests) Using cached https://files.pythonhosted.org/packages/b9/63/df50cac98ea0d5b006c55a399c3bf1db9da7 b5a24de7890bc9cfd5dd9e99/certifi-2019.11.28-py2.py3-none-any.whl Collecting idna<2.9,>=2.5 (from requests) Using cached https://files.pythonhosted.org/packages/14/2c/cd551d81dbe15200be1cf41cd03869a46fe7 226e7450af7a6545bfc474c9/idna-2.8-py2.py3-none-any.whl

116 Securing Your Critical Workloads with IBM Hyper Protect Services Collecting urllib3!=1.25.0,!=1.25.1,<1.26,>=1.21.1 (from requests) Using cached https://files.pythonhosted.org/packages/b4/40/a9837291310ee1ccc242ceb6ebfd9eb21539 649f193a7c8c86ba15b98539/urllib3-1.25.7-py2.py3-none-any.whl Collecting chardet<3.1.0,>=3.0.2 (from requests) Using cached https://files.pythonhosted.org/packages/bc/a9/01ffebfb562e4274b6487b4bb1ddec7ca55e c7510b22e4c51f14098443b8/chardet-3.0.4-py2.py3-none-any.whl Installing collected packages: certifi, idna, urllib3, chardet, requests Successfully installed certifi-2019.11.28 chardet-3.0.4 idna-2.8 requests-2.22.0 urllib3-1.25.7

A virtual environment can be created by using many methods, which can be used in place of this example. After setting up the environment for the example code, open the variables.py file in the repository to input the cluster ID, IBM Cloud API Key, and the DBaaS manager IP address for the region to which your cluster is deployed.

Also, include the path to the downloaded cert.pem file, from the IBM Cloud dashboard. Including this path ensures that API communication is carried out over SSL for optimal secure communication with the DBaaS Manager. A sample variables file is shown in Example 3-18.

Note: DBaaS Manager IP address is shown in Figure 3-6 on page 104.

Example 3-18 Sample variables.py file # User Configuration dbaas_manager_ip = "{dbaas-manager-ip}" port = "20000" cluster_guid = "{cluster-id}" api_key = “{ibmcloud_api_key}” path_to_cert = "cert.pem"

3.7.3 Running the example file

With the user variables configured, the example code can now be run. Example 3-19 shows a valid command that can be used to run the example file.

Example 3-19 Running the example.py file (venv) $ python3 example.py

Running the command runs the example.py file with Python3 and output information about your cluster, a list of users on the cluster, details about the administrator user on the cluster, and a list of all users on the cluster with their details. The example file also prints all cluster names on the account and their IDs.

This feature can be helpful when API calls are mixed to return more complex information. Example 3-20 on page 117, which is from the GitHub repository example.py file, uses the Python API class to combine the list users endpoint with user details endpoint to return a list of all users and their information on a cluster.

Example 3-20 Return a list of all users and their details cluster_users = dbaas_manager.user_list(cluster_id=cluster_guid).json()['users'] all_users_with_details = []

Chapter 3. IBM Cloud Hyper Protect DBaaS 117 for user in cluster_users: response = dbaas_manager.user_show( cluster_id=cluster_guid, user_id=f"{user['auth_db']}.{user['name']}" ) all_users_with_details.append(response.json()) print(all_users_with_details)

The examples from this folder are a brief demonstration on how Python can be used to write a wrapper around the DBaaS APIs to be used within programs or automation.

118 Securing Your Critical Workloads with IBM Hyper Protect Services 4

Chapter 4. IBM Cloud Hyper Protect Virtual Servers

This chapter introduces IBM Cloud Hyper Protect Virtual Servers and includes the following topics: 4.1, “Introduction to IBM Cloud Hyper Protect Virtual Servers” on page 120 4.2, “IBM Cloud Hyper Protect Virtual Servers use cases” on page 120 4.3, “Public Cloud service instantiation” on page 121

IBM Cloud Hyper Protect Virtual Servers is the industry’s first customer-managed LinuxONE-based virtual servers offering in the public cloud. The offering gives clients complete authority over their workloads, and ensures confidentiality of code, data, and business IP within a secure environment. This solution allows a client’s public cloud to use IBM LinuxONE, the industry’s most secure enterprise server for Linux-based workloads.

IBM Cloud Hyper Protect Virtual Servers includes the following benefits: Run workloads and protect sensitive data, code, and business IP through built-in data at rest and runtime encryption. Ensure security and confidentiality through industry compliance and certifications. Easily provision, manage, maintain, and monitor instances in the IBM Cloud by using a standard UI. No IBM Z hardware and skills required; IBM Z technology is accessed without having to purchase, install, and maintain the required hardware.

Note: This chapter focuses on the public cloud offering. For more information about IBM Hyper Protect Virtual Servers on-premises, see Chapter 5, “IBM Hyper Protect Virtual Servers on-premises” on page 125.

4.2 IBM Cloud Hyper Protect Virtual Servers use cases

The following IBM Cloud Hyper Protect Virtual Servers use cases are described: Digital Asset Custody Fintech start-ups are rapidly upending the establishment financial services industry by innovating on traditional and blockchain banking services. Institutional investors, crypto-hedge funds, exchanges, token issuance platforms, private banking, Wall Street titans, and others started using digital assets for lending, depository, escrow, and payments services. This new financial infrastructure is built on a foundation of institutional digital asset custody. IBM Hyper Protect Virtual Servers offer a global, standardized, resilient, and compliant custody service for the safekeeping of institutional digital asset investments. In a highly regulated industry with valuable assets being digitized, security is a top priority. This solution provides all of the security without sacrificing scale or performance. At the same time, it is important for Fintech companies and their establishment competitors to remain innovative and competitive in this changing market, which makes cloud adoption inevitable. Clients need a solution that is resilient, compliant, and secure, not only because of cloud security policies and best practices, but enforced at the hardware level. IBM Cloud Hyper Protect Virtual Servers provide the highest level of security at the hardware level and can be adopted by Fintech companies to grow and innovate with the cloud, without worrying about the security of their data.

120 Securing Your Critical Workloads with IBM Hyper Protect Services Migrating Monolithic Applications to the cloud For many companies, migrating business-critical applications to the cloud is hindered by fears around security, privacy, and regulation. Companies spent decades hardening the security around their on-premises data and workloads, so the idea of trusting a third-party organization to manage business and mission-critical applications was out the question. Many clients in regulated industries, such as Government, Banking, Healthcare, and Telecommunications, require highly secure compute resources to meet data privacy and geo-and industry-specific regulations. This reason is why so many companies migrated only their supporting applications to a public cloud, but did not touch their critical applications. For example, in the US Healthcare industry, the Health Insurance Portability & Accountability Act (HIPAA) is the primary law that covers the collection, use, exchange, and protection of patient information. Although most (if not all) public cloud providers are actively working to make their platforms HIPAA-compliant, steep penalties and potentially dangerous results for patients because of a breach slowed public cloud adoption for critical applications in the industry. HIPAA is one of many industry certifications that IBM Hyper Protect Virtual Servers supports. IBM Hyper Protect Virtual Servers enable Healthcare companies to move their critical workloads and applications to the cloud, while maintaining on-premises level security, privacy, and compliance. LinuxONE Clients who want to use IBM Cloud for Dev/Test/Backup IBM LinuxONE users who are familiar with the platform and understand its strengths around security, resiliency, and availability are often uncertain about the use of a different platform (especially a public cloud) for workloads that are typically run on LinuxONE. However, cloud platforms feature unmatched ability to scale across multiple geographies to provide benefits that clients cannot usually find in an on-premises server infrastructure. The combination of that level of horizontal agility with LinuxONE’s unmatched dynamic vertical scaling of cores, memory, and I/O, and the security benefits of the hardware creates the ideal host for development and testing, backups, and innovation in the cloud. IBM Cloud Hyper Protect Virtual Servers are ideal for LinuxONE clients looking for cost efficient ways of developing and testing, hosting disaster recovery, and experimenting with new capabilities in the cloud.

4.3 Public Cloud service instantiation

This section describes the steps to instantiate a virtual server.

Deploying an instance Perform the following steps to deploy an instance: 1. In the IBM Cloud, open the Hyper Protect Virtual Server service in the catalog. 2. Select and input required parameters, including deployed region, instance name, ssh public key, as shown in Figure 4-1 on page 122. Then, click Create to create an instance.

Chapter 4. IBM Cloud Hyper Protect Virtual Servers 121 Figure 4-1 Deploying a Hyper Protect Virtual Server instance in IBM Cloud

3. Check the instance status in the Resource list page, as shown in Figure 4-2. It takes several minutes to complete the deployment. After the deployment is done, the status shows as provisioned.

Figure 4-2 IBM Cloud Hyper Protect Virtual Server instance status

122 Securing Your Critical Workloads with IBM Hyper Protect Services Viewing the instance details After the instance is provisioned, you can open the instance to see the details, as shown in Figure 4-3.

Figure 4-3 IBM Cloud Hyper Protect Virtual Server instance

Accessing your virtual server You can get the virtual server’s public and internal IP addresses from the instance details page and access the virtual server by way of ssh, as shown in Example 4-1.

Example 4-1 Access the Hyper Protect Virtual Server instance # ssh -i redbook [email protected] The authenticity of host '169.63.212.8 (169.63.212.8)' can't be established. ECDSA key fingerprint is SHA256:zsh2ZfgkfEX2n60DANflQFM7zOYQj9IZZfMS9iK+E28. ECDSA key fingerprint is MD5:25:33:b9:cf:e2:e6:d3:31:47:9f:f7:36:66:48:8d:49. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '169.63.212.8' (ECDSA) to the list of known hosts. Unauthorized access to this machine is prohibited. Welcome to Ubuntu 18.04.3 LTS (GNU/Linux 4.15.0-62-generic s390x)

* Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage

The programs included with the Ubuntu system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright.

Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law.

Unauthorized access to this machine is prohibited. root@57c931651964:~#

Chapter 4. IBM Cloud Hyper Protect Virtual Servers 123 124 Securing Your Critical Workloads with IBM Hyper Protect Services 5

Chapter 5. IBM Hyper Protect Virtual Servers on-premises

This chapter introduces IBM Hyper Protect Services on-premises offering and includes the following topics: 5.1, “Introduction to IBM Hyper Protect Virtual Servers on-premises” on page 126 5.2, “IBM Hyper Protect Virtual Servers key features” on page 127 5.3, “IBM Hyper Protect Virtual Servers use cases” on page 131 5.4, “IBM Hyper Protect Virtual Servers architecture overview” on page 133 5.5, “A sample use case: Hyper Protect Virtual Server for secure storage” on page 138

IBM Hyper Protect Virtual Servers on-premises (referred to as IBM Hyper Protect Virtual Servers) is a virtualization platform that protects and hosts Linux container workloads on IBM Z and LinuxONE servers throughout their lifecycle, build, management, and deployment phases. This solution delivers the security that is needed to protect mission-critical applications in hybrid multicloud deployments.

IBM Hyper Protect Virtual Servers offering provide an encrypted environment (data at-rest and data in-flight), with peer-to-peer and peer-to-host isolation that protects container applications from access by way of hardware and operating system administrator credentials, whether access is accidental or malicious, and internal or external to an organization.

These servers ensure that your applications can be deployed and managed from trusted sources without the infrastructure team accessing the data, secrets, or application.

IBM Cloud Hyper Protect Virtual Servers address the security concerns of regulated enterprises. To provision one of these Linux Virtual Servers in the public cloud, it requires the user to provide a public SSH key, which means that only the user can access.

These Virtual Servers are built on IBM LinuxONE technology, which provides built-in workload isolation, tamper protection from privileged user access, and encryption of all data at-rest and in-flight. IBM Cloud Hyper Protect Virtual Servers provide data protection and security in the cloud without sacrificing vertical scalability or performance.

IBM Hyper Protect Virtual Servers enable the following users: Developers to securely build their applications in a trusted environment with integrity. IT infrastructure providers to manage the servers and virtualized environment where the applications are deployed without accessing those applications or their sensitive data. Application users to validate that those securely built applications originate from a trusted source by integrating this validation into their own auditing processes. Chief Information Security Officers (CISOs) to be confident that their data is protected and private from internal and external threats.

IBM Hyper Protect Virtual Servers includes the following key benefits: Protect workloads from internal threats Hyper Protect Virtual Servers is the evolution of the IBM Secure Service Container for IBM Cloud Private. As with Secure Service Container technology, Hyper Protect Virtual Servers protect your workloads from internal and external threats. On premises, the enhanced capabilities provide developers with security throughout the entire development lifecycle. Apply cloud native app development Empower developers with familiar tools and an automated, continuous software delivery pipeline to develop in a private, public, or hybrid cloud. Hyper Protect Services provide secure cloud services for on- and off-premises deployments.

126 Securing Your Critical Workloads with IBM Hyper Protect Services Simplify management Fully integrate IBM Z and LinuxONE into a hybrid multicloud environment and manage everything from behind the firewall. Hyper Protect Virtual Servers reduce user management of low-level execution environment and uses EAL5+ certified LPARs for peer isolation. Although cloud and infrastructure providers cannot access your sensitive data, they can manage images by using APIs. Extend encryption everywhere Advanced data encryption, key management, and tamper-resistance incorporates security and compliance as a part of DevSecOps, rather than adding in security measures after the fact. Application secrets are encrypted, which ensures that the confidentiality of the application is protected. Cloud providers and system administrators cannot access data, which protects against insider threats and malicious attacks. Maintain image integrity With IBM Hyper Protect Virtual Servers, developers can securely build source files, starting with the containerized application. Solution developers can keep image integrity, knowing it contains only what is intended, and maintain confidence in the deployed application’s origin. Build securely with trusted CI/CD All images can be encrypted and securely built with a trusted CI/CD flow. Developers can build images and ensure that users can validate their origin, which removes the possibility of a back door introduction during the build process. Signed container images inherit security without any code changes, which preventing access to data while it is being processed in the database.

5.2 IBM Hyper Protect Virtual Servers key features

An IBM Hyper Protect Virtual Servers solution is deployed to a Secure Service Container based logical partition (LPAR). It uses IBM Secure Service Container technology to integrate security directly into the solution.

Although security policies and best practices are still a fundamental piece of enterprise security, a technological layer of security bolsters the enterprise’s ability to protect its sensitive data and workloads, even from threat vectors, such as internal threats and leaked privileged credentials.

IBM Hyper Protect Virtual Servers expand on the security benefits of IBM Secure Service Containers. This expansion creates a secure enclave to host the most secure data and applications by deploying into the virtual machine, with no need to modify the code of the application itself.

IBM Hyper Protect Virtual Servers use operational assurance to data protection and technical insurance (see Figure 5-1 on page 128). It is not technically possible for IBM or other parties to access data in the Secure Service Container.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 127 Figure 5-1 Operational assurance versus technical assurance

The following features are described in this section: Trusted CI/CD GREP11 User management Bring Your Own Image Encryption

5.2.1 Trusted CI/CD

Continuous Integration and Continuous Delivery (CI/CD) is a core principle of DevOps, and one of the main drivers behind cloud computing.

Continuous integration (CI) is a DevOps practice in which each developer integrates their work with the main branch of code regularly and consistently (preferably once a day, or many times a day). Continuous delivery (CD) is another DevOps practice that focuses on delivering any validated changes to code (updates, bug fixes, even new features) to users as quickly and safely as possible.

Continuous delivery picks up where continuous integration ends. It automates the delivery of applications to selected infrastructure environments. It also ensures automated pushing of code changes to different environments, such as development, testing, and production.

This practice of automated pushing and delivering of new code opens the door for vulnerabilities that might pass unnoticed. What occurs when a malicious actor gains access to the build process or repository from which the code is automatically updated?

Secure Build The first step to ensure the code or application that is running in your virtual server is safe is to ensure that the build process is not vulnerable. Without the proper security at build, application developers can deliberately or accidentally introduce vulnerabilities into the source. Application builders also can build alternative source code and introduce harmful artifacts.

128 Securing Your Critical Workloads with IBM Hyper Protect Services IBM Secure Service Container technology contains features that alleviate this risk, such as static code scanning, to identify common coding errors and image scanning to identify if an image contains a component that is known to be vulnerable.

IBM Hyper Protect Virtual Servers contains a component that is called the Secure Build Server (SBS), which is packaged as a container and loaded into the Secure Service Container by using a command line tool. By using the securebuild command, you can build, tag, sign, and push images to a trusted repository.

For more information about Trusted CI/CD and Secure Build, see 7.2, “Trusted CI/CD: Building and deploying containers securely” on page 197.

Repository Registration The Secure Build feature works hand-in-hand with Repository Registration. From a Secure Build, containerized application images are signed with GNU Privacy Guard (GPG) keys when published, and verified again when it is deployed. The signing keys are generated within the secure build process and your private keys are never revealed. Only the images that are generated by using the secure build procedure can be uploaded to the organization’s container repository and installed onto the Secure Service Container partitions. The repository and the containerized images are protected with different keys on different stages.

The Secure Service Container partition pulls images from only the registered repository, and creates Hyper Protect Virtual Server instances of those images on the partition. Registration is simple with a few standard commands.

For more information about the commands that are required to register and use your repository with Hyper Protect Virtual Server images, see IBM Knowledge Center.

For more information about Repository registration, see 7.5, “Bring Your Own Image (Trusted Repository Registration)” on page 216.

5.2.2 GREP11

IBM Hyper Protect Virtual Servers provides Enterprise PKCS #11 over gRPC containers for crypto operations, such as key generation, encryption, decryption, and data wrapping and unwrapping. With the Enterprise PKCS #11 over gRPC (GREP11) containers, you can integrate your application with the asymmetric (public and private) key pairs that are generated by the Hardware Security Modules (HSM) on the IBM Z or LinuxONE servers. GREP11 is a stateless interface for cryptographic operations on cloud.

Note: IBM Hyper Protect Virtual Servers Version 1.2.0 allows a solution developer to access crypto express domain and use it to generate the asymmetric (public or private) key pairs for signing or encrypting as needed by the deployed application. An enhancement is planed in 2020 for a post GA version where a solution developer can access crypto express domain and use it to generate the asymmetric (public/private) key pairs for signing: The application in the secure build flow The built manifest file from the secure build flow

For more information about GREP11, see 7.4, “GREP11 (EP11 over gRPC)” on page 210.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 129 5.2.3 User management

One of the primary concerns that IBM Hyper Protect Virtual Servers mitigates is attack vectors from internal threats. Historically, enterprise security focused on building walls around the organization to protect from external threats. However, recent studies show that most data leaks and breaches are the result of malicious actors inside the organization, or the leaking of those individuals’ internal credentials. Firewalls, remediation of vulnerable software, and strict security policies do not do much to prevent an employee with root access to the system from stealing sensitive data.

On traditional cloud platforms (public cloud and on-premises), typically a single superuser (cluster administrator or similar role) has full access to the solution stack, from hardware to the containerized applications that are running in the environment.

With Hyper Protect Virtual Servers, administrative responsibilities are split between various roles, and each role accesses only the parts of the environment for which that role is responsible. If each administrative role is given to separate individuals in the organization, one person cannot access all of the data that is present in the virtual machine.

For more information about user management, see 7.1, “User roles in Hyper Protect Virtual Servers” on page 196.

5.2.4 Bring Your Own Image

IBM Hyper Protect Virtual Servers allow the deployment of images from only trusted, registered repositories into the hosting appliance. This feature prevents users from loading potentially harmful images from external repositories that are not officially trusted by the organization. Because this feature is part of IBM Secure Service Container technology and the hosting appliance, registered repositories are not a new feature.

However, a limitation with registered repositories was that only IBM can create the necessary JSON registration files. IBM Hyper Protect Virtual Servers introduces Bring Your Own Image (BYOI), a new feature that allows users to create their own JSON registration files so organizations can decide for themselves which registry they want to trust, and then deploy images from that registry.

For more information about Bring Your Own Image, see 7.5, “Bring Your Own Image (Trusted Repository Registration)” on page 216.

5.2.5 Encryption

IBM Hyper Protect Virtual Servers provide various security advantages by using the IBM Secure Service Container as the solution’s hosting environment.

IBM Secure Service Container supports the deployment of software container technology without requiring application changes to use the security capabilities. To gain these security capabilities, a user must deploy only their workload into the Secure Service Container. This feature is especially useful considering the regulatory focus on protecting critical data from internal and external threats, as shown in the following examples: The infrastructure and data are protected against access and abuse by root users, system administrator credentials, and other privileged user access. Infrastructure management organizations can manage the physical IT infrastructure without having visibility to the user’s applications and customer data.

130 Securing Your Critical Workloads with IBM Hyper Protect Services As a system or appliance administrator who manages the underlying infrastructure, you can download the appliance, deploy it, and then make it available on their system for their developers.

A developer can focus on creating their containerized solution and deploy it into this environment, and still know that their solution is not visible to the system administrator.

Various security mechanisms are applied to protect the data in the IBM Hyper Protect Virtual servers. For more information, see 5.5, “A sample use case: Hyper Protect Virtual Server for secure storage” on page 138.

For more information about the cryptographic capabilities of the Secure Service Container web server and other solution components, see IBM Knowledge Center.

5.3 IBM Hyper Protect Virtual Servers use cases

As enterprises move their data to the cloud, concerns around security, privacy, and regulation inhibit many enterprises from moving their sensitive data and workloads. As the probability of a breach rises every day, so too does the costs that are associated with breaches; that is, costs because downtime, fines, and damage to brand image can be steep.

IBM Hyper Protect Virtual Servers incorporate the security capabilities of Secure Service Containers with the cloud, so that stakeholders can be comfortable knowing that their data and workloads are protected by the IBM LinuxONE platform, even in the cloud.

IBM Hyper Protect Virtual Servers also provide a way to deploy a virtual server in a Secure Service Container to ensure confidentiality of data and code that is run within that virtual server. No external access to data is possible, even for privileged users, such as cloud administrators. Only the user who provisioned the virtual server with the public keys can access the virtual server.

A virtual server with this high level of security is applicable to use cases across businesses and workloads of all types, for on-premises and public cloud environments. The following sections describe a few examples of IBM Hyper Protect Virtual Servers that are in use around the world.

An organization might be inclined to keep all of their data and workloads on their own hardware, in their own data center, or managed by their own people for many reasons, including the following examples: Compliance Many regulated industries, such as Financial Services, Healthcare, and Government feature strict requirements about where data is located, and who can access it. Many countries, states, and other levels of government have their own compliance standards that must also be met. Protection of intellectual property Some companies are not limited by compliance, but because of the sensitive nature of their data and intellectual property, they do not trust a third party to host it. Instead, they want to rely on themselves to manage the security and privacy responsibilities.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 131 However, the need to keep data in-house does not need to be a reason to avoid cloud technology altogether. IBM Hyper Protect Virtual Servers can be integrated into an on-premises, private cloud infrastructure to gain all of the benefits of a cloud platform while retaining complete control of the data, security, and management.

IBM Hyper Protect Virtual Servers protect Linux workloads on IBM Z and LinuxONE throughout their lifecycle build management and deployment. This solution delivers the security that is needed to protect mission-critical applications in hybrid multi-cloud deployments.

Consider the following IBM Hyper Protect Virtual Servers on-premises use cases: Digital asset custody In recent years, the video game industry transformed into an online and digital market, rather than distributing physical copies of their games for consoles. This digital transformation means that the gaming industry is a prime candidate for a cloud platform. A large gaming company wanted on-demand environments for their developers with easy integration into existing facilities, services instead of hardware purchases, and environmental control. The company tapped into an IBM Hyper Protect Virtual Server in a private cloud that is connected to customer facilities, which gives developers the needed environments while satisfying administrators’ requirement for control and visibility. Workload sensitivity A financial services firm wanted a retail payment fraud prevention production environment. Because of workload sensitivity, the firm did not consider public cloud an option. Its IT leaders wanted environmental control and security, bare metal database servers for performance, advanced storage features, and reliable, consistent pricing. IBM created three interconnected private clouds (two in North America and one in Europe), which provided the environments they needed and were close to their operations and customers.

132 Securing Your Critical Workloads with IBM Hyper Protect Services 5.4 IBM Hyper Protect Virtual Servers architecture overview

Figure 5-2 shows the IBM Hyper Protect Virtual Servers on-premises architecture.

Source code repository App User

Virtual Virtual Virtual Virtual Server Server Server Server Command Line Interface CLI

Appliance Appliance Monitoring` Grep11 Secure Monitoring Build Application

kernel kernel kernel kernel qemu qemu qemu qemu runc runq runq runq runq Grep11 Monitoring Secure Build Cloud Private Virtual Servers Virtual Docker Engine REST Registration Files

Secure Service Container HostingAppliance for IBM Z Container Service Secure REST SSC LPAR PR/SM

Container Qemu instance Runcinstance Runqinstance More Information on runQ repository : https://github.com/gotoz/runq

Figure 5-2 Hyper Protect Virtual Servers on-premises architecture

The following a various components are part of the Hyper protect Virtual Servers on-premises solution: PR/SM Processor Resources/System Manager is a type1 hypervisor that allows multiple logical partitions that share same resources, such as CPU, IO channels, and LAN interfaces. SSC LPAR The partition that is LPAR type runs on IBM Z servers that are based on Secure Service Container framework. Secure Service Container Secure Service Container is a container technology that is a runq-based, virtualized Docker container environment that provides containers isolation and data protection on top of the IBM Z or LinuxONE servers.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 133 Hosting Appliance A software appliance that supports REST API access to the resources on the Secure Service Container. Docker Engine Open source containerization technology with workflows to build and containerize applications. runq runq is a specialized Docker runtime environment that is used to create a dedicated QEMU virtual machine (VM) for each instantiated Docker image. It also provides for each of those QEMU VMs a dedicated guest operating system kernel, and later used as the runtime environment for workloads. It is 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. runc runc is a CLI tool for creating and running containers according to the Open Container Initiative (OCI) specification. Hyper Protect Virtual Server IBM Hyper Protect Virtual Server for on-premises provides a secure virtualized infrastructure for private cloud deployments; that is, to protect the entire lifecycle of critical Linux workloads during their build, deployment, and management on-premises. Command Line Interface Tool A management server or node where the CLI is available to manage the lifecycle operations of various containers that are deployed on Hyper Protect Virtual Servers on-premises solution. It provides the following command set: – Automate the base infrastructure of the IBM Cloud Private worker and proxy nodes by using the isolated VM image. – Create and manage the Hyper Protect Virtual Server container. – Securely build and publish your applications as containerized workloads. – Deploy your containerized workloads to the Secure Service Container framework. – Monitor IBM Hyper Protect appliance health, such as the usage of CPU, memory, disk, and uptime. – Provide Enterprise PKCS #11 (EP11) interfaces for crypto operations, such as key generation, encryption, decryption, and data wrapping and unwrapping in EP11 over gRPC (GREP11) client applications.

134 Securing Your Critical Workloads with IBM Hyper Protect Services Secure Build Server The container that provides 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. Figure 5-3 shows the Secure Build Server.

IBM Hyper Protect Virtual Servers

GitAPI Secure Build Server compatible src repository securebuildCLIcommands

DockerHub Repo SBSActions API compatible Reg Build repository img REST Status

Docker notary Update

Manif log S3API S3 est compatible storage HPVS Base Image kernel qemu runq securebuildb ild config Docker EngineREST (securebuild.ya ml) Secure Service REST Container

Figure 5-3 Secure Build Server

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 by using tags; for example, hpvsop-base. Registry A registry is a hosted service that contains repositories of container images that respond to the Registry API; for example, Docker Hub. Registration files A registration file is used to register the repository for authentication or validation reasons, such that a Hosting Appliance trusts that the image is authentic when pulled from the registry.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 135 Bring Your Own Image (BYOI) A base image of Hyper Protect Virtual Server container that can be used to host customer application code. Customer can create to build an image by using this base image and application code that uses BYOI capability that is provided in Hyper Protect Virtual Server on-premises solution. Figure 5-4 shows the BYOI registration files flow.

Figure 5-4 Bring Your Own Image (BYOI)

hpvsop-base The Docker image of the base Hyper Protect Virtual Server image without the SSH daemon

136 Securing Your Critical Workloads with IBM Hyper Protect Services Appliance monitoring Monitoring images that enable in gathering metrics, such as CPU, memory, disk, uptime, and load from Secure Service Container. Two containers support of monitoring appliance level metrics, such as CPU, memory, disk, up-time, and load from Secure Service Container: One container operates on runq, the other container operates on runc. Figure 5-5 shows the monitoring containers integration.

Monitoring https Client

runc runq 5.1 Get metrics

Host Container Monitoring Container

Docker Engine SecureServiceContainer SSCLPAR

Figure 5-5 Monitoring containers integration

PKCS#11 and EP11 PKCS #11 is a Public Key Cryptography Standard that defines a platform-independent API to cryptographic tokens, such as hardware security modules (HSM) and smart cards. EP11 (Enterprise PKCS #11) is a library that is implemented by the Cryptographic Service Providers (CS) back end. GREP11 GREP11 is a Container (GREP11-container) that provides Enterprise PKCS #11 (EP11) interfaces over gRPC, which communicates with Hardware Security Module (HSM). This container provides interfaces for crypto operations, such as encrypt, decrypt, get mechanisms, wrap, and unwrap. Figure 5-6 on page 138 shows the Grep-11 integration architecture.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 137 Domain-1 Domain-2

runq runqrunq runq

Grep11runq HPVS1runq Grep11runq HPVS2runq Container Container

Grep11 Grep11 Libep11 Libep11 HSM – Hardware library client library client EP11 - gRPCapp EP11 - gRPC app

Security Module

3 3

R R

D t

m c

l s

F Docker Engine

S F

p i

G Secure Service Container y

G C

P Zcrypt (

F R R HSM Zcrypt ( device HSM driver) device SSCLPAR driver)

HSM to LPAR domain configuration HMC

Figure 5-6 GREP11 integration architecture

5.5 A sample use case: Hyper Protect Virtual Server for secure storage

In a cloud native environment, applications are deployed as microservices. Using stateless systems does not work well for applications that are prone to failure. To enable effective recovery from application failures, data persistency is necessary. To persist the data, system administrators must provision volumes that need to be used by the applications for storage.

With more data, the responsibility of securing it also increases. System administrators must answer the following questions before configuring these data volumes: Where should the secondary volumes be stored? How will the volumes be managed? How are applications going to access these volumes? Should the data be replicated or distributed storage?

Third-party software defined storage solutions are available that can help system administrators with challenges. But, how to secure this environment? With more security in place, a chance of overdoing it is possible, which results in a complicated environment that is difficult to manage and troubleshoot.

While deploying any new applications, system administrators must ensure that enough security is in place to prevent unauthorized application deployment. With images built into docker, a probability exists that those images might include vulnerable software.

138 Securing Your Critical Workloads with IBM Hyper Protect Services When new applications are deployed, a system administrator must answer the following questions: How secure is this application? Is it going to make my platform vulnerable? How can any unauthorized application be prevented from being deployed in my platform? How can applications be prevented from accessing unauthorized directories?

When developers want to deploy a custom application in a private cloud, they must answer the following questions: Does the platform support custom applications? How can the application be deployed in the cloud environment? How it is going to be accessible by others? Will it get enough resources?

Hyper Protect Virtual Server answers most of these questions through the following features: Because ssh is disabled, no user can log in to the LPAR, which is the host of these applications. Every Docker image must be signed and uploaded into the repository. Unsigned docker images are not deployed into the LPAR. Developers can configure the required storage and CPU requirements for their application by using a configuration file. The Hyper Protect Virtual Servers CLI use this script to deploy the container. All containers that are deployed are runq containers as opposed to runc containers. The runc containers are a process that is running within a namespace; runq containers are almost a virtual machine. Users cannot mount any system directory into a container; therefore, the host is secured any unauthorized access and data leakage. Every image is associated with a repository definition file. These repository definition files are blueprints of runq containers. They contain information, such as the location of the image in repository and access credentials. Encrypting these files ensures the prevention of unnecessary data breaches. Monitoring servers enable system administrators to collect system-related data. Users can deploy the Prometheus server to publish the details. With features, such as Bring Your Own Image (BYOI) and Secure Build Server, customers can deploy their own custom images security. Also, unauthorized application deployment is prevented. GREP11 enables customers to take advantage of the hardware accelerated support of crypto operations. Currently, this feature enables developers and customers to manage keys and secrets securely. The communication follows the gRPC standard along with the PKCS 11 standard for cryptographic operations; therefore, the name GREP11. Hyper Protect Virtual Servers makes it impossible to steal secrets and keys and customers do not need to worry about the performance implications because cryptographic operation can be resource hogging.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 139 5.5.1 Creating a Secure Storage Server in Hyper Protect Virtual Servers

As described in 5.5, “A sample use case: Hyper Protect Virtual Server for secure storage” on page 138, in the world of cloud native applications where microservices come and go, it is important to persist data for effective recovery. Various technologies exist in the marketplace that provide data persistence. For this solution, use of GlusterFS is described next.

GlusterFS is a popular software-defined storage solution that is used for managing volumes. It is open source in nature and enables system administrators to provision distributed, replicated, or distributed-replicated volumes.

Customers can build GlusterFS containers with glusterfs-server and glusterfs-client packages, sign the image, and host it in an image repository by using a secure build server. Then, this image can be deployed in a Hyper Protect Virtual Servers environment by using the hpvs-cli command, such as HPVS create.

Containers in a Hyper Protect Virtual Servers environment are not typical Docker containers; they also are not virtual machines. For clarity, we say that these are Virtual Servers, which are little more than a Docker container, but little less than virtual machine (see Figure 5-7).

Figure 5-7 Sample container

140 Securing Your Critical Workloads with IBM Hyper Protect Services Because GlusterFS server listens to port 24006 and 24007, applications can use GlusterFS client packages to communicate with the server and run volume management commands. Developers can write their own application to monitor the GlusterFS server by using api calls by using Python.

Chapter 5. IBM Hyper Protect Virtual Servers on-premises 141 142 Securing Your Critical Workloads with IBM Hyper Protect Services 6

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation

This chapter discusses IBM Hyper Protect Virtual Servers on-premises prerequisites and installation and includes the following topics: 6.1, “Planning and prerequisites for Hyper Protect Virtual Servers on-premises” on page 144 6.2, “Networking for Hyper Protect Virtual Servers” on page 149 6.3, “Installation of Hyper Protect Virtual Servers components on-premises” on page 161 6.4, “Public Cloud service instantiation” on page 191

In this section, we discuss the requirements for Hyper Protect Virtual Servers on-premises (which is referred to as IBM Hyper Protect Virtual Servers) installation. For a basic installation, you need one Linux Management server and one Secure Service Container (SSC).

Note: For more information about IBM Hyper Protect Virtual Servers (previously known as Secure Service Container for IBM Cloud Private), see the following resources: IBM Knowledge Center Chapter 3: Secure Service Container installation and configuration of Implementation Guide for IBM Blockchain Platform for Multicloud, SG24-8458.

Table 6-1 lists the configuration parameters that are used for the Management Server.

Table 6-1 Configuration parameters for the Management Server Parameter Resource Value Example Where to get

1 Architecture x86 or s390x s390x Cloud administrator Linux

2 Host name management_server hostname

3 Primary Network eth0 ifconfig -a interface Controller (NIC)

4 Management Server IP 10.152.151.100 ifconfig -a (inet addr parameter in the result)

5 Password for the user root_user_password System administrator root

6 Internal IP address 192.168.40.251 Network administrator

7 NIC for internal network eth1 Network administrator

8 Subnet mask for internal 192.168.40.0/24 Network administrator IP

9 Gateway for internal IP 192.168.40.1 Network administrator

Table 6-2 lists the configuration parameters that are used for the SSC LPAR.

Table 6-2 Configuration parameters for the SSC LPAR Parameter Resource Value Example Where to get

1 Partition IP 10.152.151.105 System address administrator

2 Master ID ssc_master_user System administrator

3 Master password ssc_master_pass System word administrator

144 Securing Your Critical Workloads with IBM Hyper Protect Services Parameter Resource Value Example Where to get

4 Storage disks for 3600507630affc42 System quotagroups 70000000000020 administrator resizing 00 (FCP) or 0.0.78CA (IBM FICON® DASD)

The following minimum requirements must be met to deploy Hyper Protect Virtual Servers services: 2 IFLs 12 GB RAM 190 GB storage (50 GB for the hosting appliance, 100 GB in the storage pool for one Hyper Protect Virtual Server container, and 40 GB for one Secure Build container)

Table 6-3 lists the configuration parameters that are used for the Secure Build Container server.

Table 6-3 Configuration parameters for the Secure Build Container server Parameter Resource Value Example Where to get

1 Partition IP address 10.152.151.105 System administrator

2 Secure Build container securebuild1 Cloud administrator name

3 CPU thread number 2 System administrator

4 Memory (GB) 12 System administrator

5 Storage for the Secure 10 System administrator Build container application (GB)

6 Storage for the Docker 16 System administrator images built by Secure Build (GB)

7 Storage for logs 2 System administrator configuration data for the Secure Build Container (GB)

8 Quotagroup of Secure myquotagroup Cloud administrator Build container

9 Connection method IP System administrator (port-mapping/IP)

10 Internal network name encf900_internal_netw Cloud administrator orka

11 Internal IP address 192.168.40.6 Cloud administrator (only needed if an internal network is used)

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 145 Parameter Resource Value Example Where to get

12 External IP address 164.23.2.77 System administrator (only needed if an external network is used)

13 Forward port for 10433 System administrator external (only needed if an external IP address is not assigned)

14 Repository ID of the SecureDockerBuild Cloud administrator Secure build container image

15 Tag of the Secure build latest Cloud administrator container image

16 Repository ID for your MyDockerApp Cloud administrator apps

17 Source code repository github.com:MyOrg/my- App developer or ISV URL docker-app.git

18 Source code branch dev App developer or ISV

19 Private key for Source App developer or ISV code repository

20 Remote docker registry docker.io Cloud administrator server

21 Remote docker docker_base_user/My Cloud administrator repository name for DockerApp built images

22 Remote docker registry docker_base_user Cloud administrator user name to register the base images

23 Remote docker registry passw0rd Cloud administrator user password to register the base images

24 Remote docker registry docker_writable_user Cloud administrator user name to push the images

25 Remote docker registry passw0rd Cloud administrator user password to push the images

26 Cloud Object Storage 0viPH...kliJ Cloud administrator service API key (Optional)

27 Cloud Object Storage my-cos-bucket1 Cloud administrator service bucket (Optional)

146 Securing Your Critical Workloads with IBM Hyper Protect Services Parameter Resource Value Example Where to get

28 Cloud Object Storage crn:v1...::1 Cloud administrator service resource crn (Optional)

29 Cloud Object Storage iam.cloud.ibm.com Cloud administrator service auth_endpoint (Optional)

30 Cloud Object Storage s3.....cloud Cloud administrator service end_point (Optional) a. Because the internal network name is dynamically generated (depending on the customer’s hardware), this parameter might be different in your environment.

Table 6-4 lists the configuration parameters that are used to create repository definition files.

Table 6-4 Configuration parameters to create repository definition files Parameter Resource Value Example Where to get

1 Repository name docker.io/docker_ Cloud base_user/MyDoc administrator kerApp

2 Readonly Docker docker_readonly_ Cloud Hub user ID user administrator

3 Docker Hub User docker_password Cloud password administrator

4 The public key isv_user.pub App developer or ISV

5 The private key isv_user.private App developer or ISV

Table 6-5 lists the configuration parameters that are used to create Hyper Protect Virtual Servers.

Table 6-5 Configuration parameters to create Hyper Protect Virtual Servers Parameter Resource Value Example Where to get

1 Partition IP 10.152.151.105 System address administrator

2 External network encf900_network Cloud name administrator

3 Container external 164.20.5.78 Cloud IP address administrator

4 Internal network encf900_internal_ Cloud name networka administrator

5 Internal IP address 192.168.40.188 Cloud administrator

6 Parent device encf900 Appliance administrator

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 147 Parameter Resource Value Example Where to get

7 Gateway 192.168.40.1 Cloud administrator

8 Subnet 192.168.40.0/24 Cloud administrator

9 Repository name MyDockerApp Cloud administrator

10 Image tag latest Cloud administrator

11 CPU threads 2 Cloud number administrator

12 Memory size (GB) 12 Cloud administrator

13 Quotagroup size 100G Cloud (GB) administrator a. Because an internal network name is dynamically generated (depending upon the customer’s hardware), this parameter might be different in your environment.

Table 6-6 lists the configuration parameters that are used to create the Monitoring component.

Table 6-6 Configuration parameters to create the Monitoring component Parameter Resource Value Example Where to get

1 Partition IP address 10.152.151.105 System administrator

2 Domain suffix first System administrator

3 DNS name example.com System administrator

4 Connection method 8443 System (port-mapping/IP) administrator

5 Private key for the server.key openssl utility monitoring infrastructure

6 Certificate for the server-certificate. openssl utility monitoring pem infrastructure

7 Certificates for the client-certificate.p openssl utility monitoring client em

Table 6-7 lists the configuration parameters to create and configure the GREP11 container.

Table 6-7 Configuration parameters to create and configure the GREP11 container Parameter Resource Value Example Where to get

1 Partition IP 10.152.151.105 System address administrator

148 Securing Your Critical Workloads with IBM Hyper Protect Services Parameter Resource Value Example Where to get

2 Crypto domain 09.000b System name administrator

3 Domain suffix grep11 System administrator

4 DNS name example.com System administrator

5 Connection IP System method administrator (port-mapping/IP)

6 Internal network my-private-netwo System name rk-namea administrator

7 IP address 192.168.10.106 System administrator

8 TLS key and key.pem, openssl utility certificate cert.pem a. Because an internal network name is dynamically generated (depending on the customer’s hardware), this parameter might be different in your environment.

6.2 Networking for Hyper Protect Virtual Servers

IBM Hyper Protect Virtual Servers support Open Systems Adapter (OSA) for networking on IBM Z and LinuxONE servers that are configured for SSC LPAR. In addition, this OSA card can be virtualized when attached to SSC LPAR.

Networking in LPAR The network interface is a software driver component of the operating system that uses OSA for networking. OSA supports the following types of network interfaces: Ethernet This interface works with OSA in promiscuous mode and forwards all packets to and from the switch. Whenever any other LPAR broadcasts a packet for address resolution (ARP), that LPAR interacts with this interface type. As a result, the network can experience slow periods if many LPARs are connected to the same switch and running concurrent start and stop operations frequently. VLAN This interface supports Ethernet packets that are tagged with a VLAN for network isolation. In addition, IP ranges might be reused by using a different VLAN ID. Bond This interface can be used for fail-over scenarios. A bond interface might be connected to more than one OSA and if one OSA is not functioning, the bond interface steers network traffic to another OSA, which enables the fail-over scenario.

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 149 Figure 6-1 shows the network architecture.

Figure 6-1 Network architecture

6.2.1 Networking in Hosting Appliance (networking for Hyper Protect Virtual Servers containers)

Hyper Protect Virtual Servers is based on a Docker (runq) engine. Therefore, it often uses a Docker bridge interface to communicate between Hyper Protect Virtual Servers virtual machine images (VMs) and components that are outside of the LPAR. The Docker bridge interface can be created on top of a network interface of LPAR (Ethernet, VLAN, or Bond).

The following types of Docker bridge interfaces are available: Bridge This type of Docker bridge interface is used when VMs want to communicate among themselves and VMs can access data that is outside of the LPAR through NAT. However, the problem with this type of networking is that we cannot communicate VMs from outside with the same network that VMs uses. To access the VM’s services, we must use a Port Address Translation (PAT) to access VMs from outside of the network by using the LPAR’s network (not directly by using the VM's network). macvlan This type of Docker bridge interface is used to communicate with VMs in the LPAR from outside the LPAR by using the same network that the VM acquired. In this case, the VM’s MAC address is registered to the OSA and switch and it directly falls under the switch network.

150 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 6-2 shows the networking in Hosting Appliance.

Figure 6-2 Networking in Hosting Appliance

6.2.2 Creating an Ethernet interface

Complete the following steps to create an Ethernet interface: 1. In your SSC UI (https://), click the Networks section. 2. Click the + icon and select Ethernet, as shown in Figure 6-3.

Figure 6-3 Network Connections window

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 151 A window opens in which you are prompted for the network information, as shown in Figure 6-4.

Figure 6-4 Entering network information

3. In the General tab, add the following information (see Figure 6-5 on page 153): – Network Device: Add any device in the range that is allocated to your OSA. Start by entering the device number. The auto suggest shows the available devices. Select one available device (for example, 0.0.f709). – Connection Name: Is automatically populated to enccw0.0.f709. – Port: 0

152 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 6-5 General tab information

4. In the IPV4 tab, make the following selections (see Figure 6-6 on page 154): – Addresses: Manual – Gateway: 192.168.40.1 – Address: 192.168.40.2 – Prefix: 24

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 153 Figure 6-6 IPv4 tab information

5. Click Add (see Figure 6-7).

Figure 6-7 Clicking Add

154 Securing Your Critical Workloads with IBM Hyper Protect Services A enccw0.0.f709 device is now added to the 192.168.40.0/24 network on which you can create your containers.

6.2.3 Creating a VLAN interface

Complete the following steps to create a VLAN interface: 1. In your SSC UI, click the Networks section. 2. Click the + icon and select VLAN (see Figure 6-8).

Figure 6-8 Selecting VLAN

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 155 A window opens in which you are prompted to enter the network information, as shown in Figure 6-9.

Figure 6-9 Add VLAN Connection: General tab

156 Securing Your Critical Workloads with IBM Hyper Protect Services 3. To add a parent device, click the + icon. In the window that opens, add the network device that is provided by the OSA for VLAN (see Figure 6-10).

Figure 6-10 Adding the network device

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 157 4. Click Create. Now, the Parent device is available in the drop-down menu (see Figure 6-12 on page 159).

Figure 6-11 Parent device is available

158 Securing Your Critical Workloads with IBM Hyper Protect Services 5. Under the General tab (see Figure 6-12.), add the following information: – Parent Device: Select the device that you added. In this case, encf300. – VLAN ID: Add your VLAN ID; for example, 1121. – Connection Name: Is automatically populated with vlan0f300.1121. – VLAN Device: Is automatically populated with vlan0f300.1121.

Figure 6-12 Completing information in the General tab

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 159 6. Click the IPV4 tab and enter the following information, as shown in Figure 6-13: – Address: Manual – Gateway: 192.168.40.1 – Address: 192.168.40.2 – Prefix: 24

Figure 6-13 Completing information in the IPV4 tab

160 Securing Your Critical Workloads with IBM Hyper Protect Services 7. Click Add (see Figure 6-14).

Figure 6-14 Clicking Add

Now you have a vlan0f300.1121 device added to 192.168.40.0/24 network on which you can create your containers.

6.3 Installation of Hyper Protect Virtual Servers components on-premises

In this section, we described how to install each component in the Hyper Protect Virtual Servers offering.

6.3.1 Preparing SSC LPAR for Hyper Protect Virtual Servers

To install Hyper Protect Virtual Servers components, complete the following steps: 1. Download the Hyper Protect Virtual Servers package from the IBM Passport Advantage® website. After it is downloaded, extract the contents of the build by using the following command: tar -xvzf CC37UEN.tar.gz

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 161 The folders listed as shown in Figure 6-15.

Figure 6-15 Listed folders

2. Log in to SSC LPAR at http:// (see Figure 6-16).

Figure 6-16 Logging in to SSCC LPAR

162 Securing Your Critical Workloads with IBM Hyper Protect Services 3. Click the Installer option. The window that is shown in Figure 6-17 opens.

Figure 6-17 Invoke Installer window

4. Export any active appliance configuration. Then, invoke the installer and accept the message to restart, as shown in Figure 6-18.

Figure 6-18 Confirming invoking the installer

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 163 A confirmation message is shown (see Figure 6-19).

Figure 6-19 Confirmation message

5. The Login window opens, as shown in Figure 6-20.

Figure 6-20 Login window

164 Securing Your Critical Workloads with IBM Hyper Protect Services 6. Log in again by using your user ID and password (see Figure 6-21).

Figure 6-21 Entering user ID and password

7. The installation window opens. Click the + button to select the SSC Hosting Appliance image (see Figure 6-22).

Figure 6-22 Welcome window

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 165 8. Select the SSC Appliance image and click Open (see Figure 6-23).

Figure 6-23 Selecting the SSCC Appliance image

166 Securing Your Critical Workloads with IBM Hyper Protect Services 9. Select the disk, as shown in Figure 6-24.

Figure 6-24 Selecting the disk

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 167 10.Confirm the appliance installation (see Figure 6-25).

Figure 6-25 Confirming the appliance

168 Securing Your Critical Workloads with IBM Hyper Protect Services After a few minutes, the appliance is installed and is routed to the Login window, as shown in Figure 6-26.

Figure 6-26 Appliance is installed and routed to the Login window

11.Click Storage on the left side menu bar (see Figure 6-27).

Figure 6-27 Clicking Storage

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 169 12.Select LV Data Pool (see Figure 6-28).

Figure 6-28 Selecting LV Data Pool

13.Select the disks from the available devices (see Figure 6-29).

Figure 6-29 Selecting disks

170 Securing Your Critical Workloads with IBM Hyper Protect Services 14.Assign disks to pool (see Figure 6-30).

Figure 6-30 Assigning disks to pool

15.Verify the disks and click Continue, as shown in Figure 6-31.

Important: Disks are formatted in this step.

Figure 6-31 Verifying disks

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 171 The disks are then formatted, as shown in Figure 6-32.

Figure 6-32 Disks are formatted

14.Verify that the status is correctly reflected (see Figure 6-33).

Figure 6-33 Verifying status

172 Securing Your Critical Workloads with IBM Hyper Protect Services 15.Click Networks, as shown in Figure 6-34.

Figure 6-34 Selecting networks

16.Click the + button to add a network (see Figure 6-35).

Figure 6-35 Adding a network

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 173 17.Define the new network according to your network topology (see Figure 6-36).

Figure 6-36 Defining the network

21. Verify that the network is correctly displayed (see Figure 6-37).

Figure 6-37 Verifying that network is displayed correctly

The Hosting Appliance is now set up on the SSC LPAR.

174 Securing Your Critical Workloads with IBM Hyper Protect Services 6.3.2 Pushing the base images to the Docker repository

Complete the following steps to push the base images to the Docker repository: 1. After the Hosting Appliance image is installed (as described in 6.3.1, “Preparing SSC LPAR for Hyper Protect Virtual Servers” on page 161), load the CLI image on your Linux Management Server by using the following command: docker load -i hpvs-cli-installer.docker-image.tar The CLI docker images display after you run the docker images command, as shown in Figure 6-38.

Important: Two images are available. The image to be used depends upon the type of Linux Management Server that is used. The image with TAG containing 1.2.0.s390x must be used if the Linux Management Server is Z s390x architecture. If the Linux Management Server is a x86 machine, use the image with TAG shown as 1.2.0.

Figure 6-38 List of Docker images

Use the Hyper Protect Virtual Servers on-premises CLI Docker image as shown in Figure 6-38 based on the type of Linux Management Server architecture for the various CLI commands. The document shows the command samples for x86: –x86: ibmzcontainers/hpvs-cli-installer:1.2.0 – s390x: ibmzcontainers/hpvs-cli-installer:1.2.0.s390x 2. Check that you enable Docker Content Trust (DCT) for your remote docker registry server by using the export DOCKER_CONTENT_TRUST=1 command. 3. The Hyper Protect Virtual Servers base images, which are part of this offering in your Docker hub, must be registered. Load the Hyper Protect Virtual Servers base images onto your Linux Management Server by completing the following steps: a. Go to the hpvs-cli config directory and extract the base images into different folders, as shown in Example 6-1.

Example 6-1 Extract the base images into different folders #cd /root/hpvs/VS/hpvs-cli/config

# mkdir HpvsopBase # mkdir HpvsopBaseSSH

# tar -xvf HpvsopBase.tar.gz -C HpvsopBase.tar.gz.sig HpvsopBase.py-rel.enc

# tar -xvf HpvsopBaseSSH.tar.gz -C HpvsopBaseSSH.tar.gz.sig HpvsopBaseSSH.py-rel.enc

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 175 b. Create the Docker loadable binary under the same directory. The following warning message is displayed: gpg: Can't check signature: No public key can be safely ignored when running the following gpg commands. gpg /HpvsopBase.tar.gz.sig gpg HpvsopBaseSSH.tar.gz.sig c. Install the base images by using the following Docker load commands: docker load -i /HpvsopBase.tar.gz docker load -i /HpvsopBaseSSH.tar.gz d. Run the docker images command to check whether the base images are loaded into the local registry successfully (see Figure 6-39).

Figure 6-39 docker images command

4. Register the base images in the Docker hub. Here, we use the SSH-enabled base image. In our example (per the Docker account), one private repository is available. Therefore, a private repository was created that is named redbooksuser1/hpvsop-base-ssh. 5. Use the docker tag command to tag the base images with the same ID that is used by the CLI tool. For example, 1.2.0 is the tag ID of the CLI tool that you can get by running the docker images command. Run the commands that are shown in Example 6-2 to tag both base images.

Example 6-2 Tagging both base images docker tag ibmzcontainers/hpvsop-base-ssh:1.2.0- abcedfg docker_base_user/hpvsop-base-ssh:1.2.0- abcedfg

docker tag ibmzcontainers/hpvsop-base:1.2.0- abcedfg docker_base_user/hpvsop-base:1.2.0- abcedf

Figure 6-40 shows the output of the command.

Figure 6-40 Tagging the base images

6. Run the docker login docker.io command. Enter the Docker credentials for a successful login. 7. Push the base images to your remote docker repository by using the docker push command, as shown in the following example: docker push redbooksuser1/hpvsop-base-ssh:1.2.0.-release-5c5f656

176 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 6-41 shows the output of this command.

Figure 6-41 Push the base images to your remote docker repository

Figure 6-42 shows the base image in the Docker repository.

Figure 6-42 Base image in the docker repository

6.3.3 Secure Build Container

Complete the following steps to create the Secure Build Container: 1. Load the SecureDockerBuild image on to your SSC LPAR by copying the image from securebuild-cli/config folder to hpvs-cli/config. 2. Load the SecureBuild image onto the LPAR by using the following command: docker run --rm -it -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 image load -i SecureDockerBuild.tar.gz --lpar [LPARNAMEORADDRESS]

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 177 3. After the image is loaded, you can check whether the image is loaded successfully by using the following command: docker run --rm -it -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 image list --lpar [LPARNAMEORADDRESS] Figure 6-43 shows the output of the command.

Figure 6-43 Checking if the image is loaded successfully

4. Configure the hosts file and securebuild.yaml file under the securebuild-cli/config directory. For more information about networking, see 6.1, “Planning and prerequisites for Hyper Protect Virtual Servers on-premises” on page 144. A sample hosts file configuration is shown in Example 6-3.

Example 6-3 Sample hosts file configuration (only the first line of the RSA key is shown) [lpars] rest_user="" rest_pass=""

#For example: 10.20.30.40 rest_user="root" rest_pass="!W3Tx567@j"

A sample securebuild.yaml looks as below: secure_build_workers: - container: port: '21442' #Port mapping for Securebuild Container ipaddress: '' name: '' quotagroup_name: 'securebuild-qg' imagetag: '' #For ex: 1.2.0-release-hash repoid: 'SecureDockerBuild' delete_quotagroup_on_container_delete: 'true' #20 GB Quota Group size quotagroup_size: '20' root_volume_size: '10' docker_volume_size: '20' data_volume_size: '10' #cpu: '4' #Default 1 memory: '4098' lpar:

178 Securing Your Critical Workloads with IBM Hyper Protect Services ipaddress: '' network: name: 'bridge' regfile: id: '' github: url: '[email protected]:/.git' branch: 'master' #SSH Key registered with Github. Available in ~/.ssh/id_ras.pub. #Note: Passphrase should not be set on the SSH key during generation. key: | -----BEGIN RSA PRIVATE KEY----- YEDVKgIBAAKCAgEA1Y5ALt1iUnxC4ShAU0cmCiWWYcGPEgwogwNl2e0ceHDRhgLF ...... -----END RSA PRIVATE KEY----- docker: repo: '/' image_tag_prefix: 'latest' user: '' password: '' push_server: 'docker.io' base_user: '' base_password: '' base_server: 'docker.io'

5. After configuring the hosts file and securebuild.yaml, create the securebuild container by using the following command: docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 securebuild create --name . Figure 6-44 shows the output of this command.

Figure 6-44 Creating the securebuild container

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 179 6. The container is created successfully. Check the status of the container by using the following command: docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 securebuild status --name Figure 6-45 shows the output of this command.

Figure 6-45 Checking the status of the container

7. Update the Dockerfile of your application code to include the base image. Update the Dockerfile of your application code to ensure that the /usr/bin/initHPVSoP.sh script is part of the initialization code that is defined with the ENTRYPOINT clause. The /usr/bin/initHPVSop.sh script must be invoked correctly to maintain the security and integrity of the Docker images that you are building. If the ENTRYPOINT clause is configured with your own script, you must include a call to /usr/bin/initHPVSop.sh in your own initialization processing. The Dockerfile that is shown in Example 6-4 shows how to call the initialization code in the hpvsop-base parent Docker image. The initialization processing in the application Dockerfile is performed by the script.

Example 6-4 Dockerfile example FROM docker_base_user/hpvsop-base:1.2.0-release-abcdefg COPY .sh /usr/bin RUN chmod +x /usr/bin/.sh # Execute initialization code ENTRYPOINT ["/usr/bin/.sh"]

In the .sh initialization script, you must include a call to /usr/bin/initHPVSop.sh: ...source /usr/bin/initHPVSoP.sh...... 8. Commit the changes to your application code into the Git repository. Build your application code to a s390x compatible container image, and push it to your Docker Hub repository by using the following command: docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 securebuild build --name

180 Securing Your Critical Workloads with IBM Hyper Protect Services The output of the command is shown in Figure 6-46.

Figure 6-46 Pushing the image to your Docker Hub repository

9. After the securedocker build command is completed, you can check the status of the container. If the Docker image is successfully built, it show the success message without any errors. If the build fails, the respective error message is shown (see Figure 6-47).

Figure 6-47 Build status

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 181 10.Verify whether the Docker image is built successfully by checking in the Docker hub (see Figure 6-48).

Figure 6-48 Verifying that the docker image is built successfully by checking in the Docker hub

The securebuild build command creates the following files for later use: An unsigned repository registration python file in the clear text, which you can use the credential and public key information when creating the repository definition file: docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 securebuild regfile --regfile-type full --name An unsigned repository registration JSON file in the clear text, which you can use as an input to the regfile encrypt command with a self-generated GPG key pair to create a signed and encrypted repository definition file. Use the following command to retrieve this JSON file (see Figure 6-49 on page 183): docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 securebuild regfile --name

182 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 6-49 Retrieving the JSON file

A signed manifest file for the application and the public key that is used for signing the manifest. Use the following command to retrieve the signed manifest file (see Figure 6-50): docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 securebuild manifest --name

Figure 6-50 Retrieving the signed manifest file

The public key used to verify the signature on the manifest file. If you configured IBM Cloud Object Store (COS) to store your manifest files, the manifest file for each build is automatically pushed to COS after each build (see Figure 6-51 on page 184): docker run --rm -it -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.21.0 securebuild public-key --name

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 183 Figure 6-51 Manifest file pushed to COS after each build

6.3.4 Enabling monitoring on SSC LPAR

You can monitor various components by using the monitoring infrastructure that is provided by IBM Hyper Protect Virtual Servers.

Note: The monitoring metrics are collected from Secure Service Container partitions. Only Hyper Protect hosting appliance and Secure Service Container partition level metrics are supported for IBM Hyper Protect Virtual Servers v1.1.0.

This procedure is intended for users with the role cloud administrator.

Before you begin, ensure that the following prerequisites are met: The IP address of the Secure Service Container partition is available. Port 8443 is available for the monitoring infrastructure on the Secure Service Container partition. IBM Hyper Protect Virtual Servers CLI tools are installed on the x86 or Linux on IBM Z/LinuxONE (such as s390x architecture) management server.

For monitoring, the following containers are created: Monitoring Collectd-Host

Complete the following steps to configure monitoring on an SSC LPAR: 1. Under the monitoring-cli folder, create a hosts file with the connection information for the underlying RESTful API calls to the Secure Service Container partitions where the monitoring infrastructure is created. You can use the hosts.example file as the reference when configuring the hosts file. 2. Generate certificates for the secure communication between the Hyper Protect monitoring infrastructure (server) and the monitoring client. The monitor client invokes the collectd-exporter endpoint on the server to show the collected metrics.

184 Securing Your Critical Workloads with IBM Hyper Protect Services Note: When you generate certificates, use collectdhost-. or *. as the common name. A wildcard certificate with *. common name can be used across multiple partitions.

3. Create the ./config/monitoring.yaml file with the settings for your monitoring infrastructure. You can use the ./config/monitoring.yaml.example file as the reference when configuring the monitoring.yaml file. 4. After configuring the monitoring.yaml, create the Monitoring containers by using the following command (see Figure 6-52): docker run --rm -it -v $(pwd):/monitoring-cli/config ibmzcontainers/hpvs-cli-installer:1.2.0 monitoring create

Figure 6-52 Creating the Monitoring containers

5. After the containers are successfully created, you can collect the metrics by using the wget command or by configuring any one of the tools that show the metrics in graphical manner (for example, Prometheus). We are the wget method to collect the metrics of the SSC LPAR, as shown in the following example: wget https://collectdhost-first.bell.com:8443/metrics --ca-certificate=server-certificate.pem --certificate=client-certificate.pem --private-key=client-key.pem Example 6-5 on page 186 shows the output of this command.

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 185 Example 6-5 wget command [root@hurlnxa5:keys]# wget https://collectdhost-first.bell.com:8443/metrics --ca-certificate=mon-certificate.pem --certificate=prom-certificate.pem --private-key=prom-key.pem --2020-03-16 10:12:57-- https://collectdhost-first.bell.com:8443/metrics Resolving collectdhost-first.bell.com (collectdhost-first.bell.com)... 9.20.6.57 Connecting to collectdhost-first.bell.com (collectdhost-first.bell.com)|9.20.6.57|:8443... connected. HTTP request sent, awaiting response... 200 OK Length: 6929 (6.8K) [text/plain] Saving to: 'metrics'

100%[======>] 6,929 --.-K/s in 0s

2020-03-16 10:12:57 (49.8 MB/s) - 'metrics' saved [6929/6929]

6.3.5 Integrating with EP11 Library (GREP11)

You can create an EP11 over gRPC (GREP11) container on the Secure Service Container partition. Then, you can use the Hardware Security Module (HSM) to generate asymmetric (public and private) key pairs for signing or encrypting as needed by the deployed applications.

This procedure is intended for users with the role cloud administrator.

Before you begin, complete the following tasks: Check with your system administrator that the crypto express domain is configured in the EP11 mode. Check with your system administrator that the master key is initialized. Ensure that IBM Hyper Protect Virtual Servers CLI tools are installed on the x86 or Linux on IBM Z / LinuxONE (such as s390x architecture) management server.

To configure the GREP11 service for your Hyper Protect Virtual Servers container, create certificates that are used for secure communication. The certificates can be generated by using one-way TLS communication or mutual TLS communication. In our example, we use mutual TLS communication to generate certificates.

186 Securing Your Critical Workloads with IBM Hyper Protect Services Complete the following steps to create the CA certificate for mutual authentication over TLS by using the golang-massl utility: 1. Install the cfssl toolkit by using the apt-get installation golang-cfssl command. 2. Generate the CA certificate and private key by using the golang-mass utility and the certificate from the trusted CA (see Figure 6-53).

Figure 6-53 golang-mass utility

3. Copy these certificates in grep11-cli/config directory as shown in the following examples: – cp -p server.pem grep11-cli/config/ – cp -p server-key.pem grep11-cli/config/ – cp -p ca.pem grep11-cli/config/ 4. After the certificates are generated successfully and configured in the grep11 directory, modify the hosts file by adding the SSC LPAR IP and the credentials. Then, get the crypto domain list on the HSM by using the crypto list command (see Figure 6-54 on page 188): docker run --rm -it -v $(pwd):/grep11-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0.s390x crypto list

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 187 Figure 6-54 Crypto list command

5. Update the grep11-config.yaml file for your GREP11 containers (for example, parameters crypto_domain name, IP, and certificates details).

Note: If you want the GREP11 container in your network of IBM Hyper Protect Virtual Servers and accessible internally, you must set the key network_name and IP to be part of your IBM Hyper Protect Virtual Servers network (the port always is 9876). The network_name can be created as VLAN or Ethernet type connection on the Secure Service Container partition.

6. After the grep11-config.yaml is configured, use the following command to create GREP11 container: docker run --rm -it -v $(pwd):/grep11-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0.s390x grep11 create 7. After the GREP11 container is created, check the status of the GREP11 container by using the following command (see Figure 6-55 on page 189): docker run --rm -it -v $(pwd):/grep11-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0.s390x grep11 status

188 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 6-55 Checking the status of the GREP11 container

8. After the GREP11 is created successfully, verify whether the application is configured correctly by using the GREP11 service. 9. The following Golang code examples show how to generate asymmetric (public and private) key pairs by using the GREP11 API, and assumes that more required Golang packages are included by way of import statements, such as the gRPC, http, and pb github.com/ibm-developer/ibm-cloud-hyperprotectcrypto/golang/grpc statement used by GREP11 to perform API function calls.

Note: You must use certificate-based authentication as shown in the following code examples to access the GREP11 container on the Secure Service Container partition.

10.For one-way TLS authentication, use the code snippet that is shown in Example 6-6.

Example 6-6 Code snippet # The URL of GREP11 container in this example grep11.example.com:21876 const address = "grep11.example.com:21876" # cert.pem is the same server certificate because it is one way TLS var cert, _ = credentials.NewClientTLSFromFile("cert.pem", "") var callOpts = []grpc.DialOption{ grpc.WithTransportCredentials(cert), } func Example_getMechanismInfo() { conn, err := grpc.Dial(address, callOpts...) if err != nil { panic(fmt.Errorf("Could not connect to server: %s", err)) } defer conn.Close()

cryptoClient := pb.NewCryptoClient(conn)

mechanismListRequest := &pb.GetMechanismListRequest{}

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 189 mechanismListResponse, err := cryptoClient.GetMechanismList(context.Background(), mechanismListRequest) if err != nil { panic(fmt.Errorf("Get mechanism list error: %s", err)) } fmt.Printf("Got mechanism list:\n%v ...\n", mechanismListResponse.Mechs[:1])

mechanismInfoRequest := &pb.GetMechanismInfoRequest{ Mech: ep11.CKM_RSA_PKCS, } _, err = cryptoClient.GetMechanismInfo(context.Background(), mechanismInfoRequest) if err != nil { panic(fmt.Errorf("Get mechanism info error: %s", err)) } }

8. For mutual TLS authentication, use the following code snippet. # The URL of GREP11 container in this example grep11.example.com:21876 const address = "grep11.example.com:21876" var ( # client certificate crt = "client.pem" # client private key key = "client-key.pem" # CA certificate ca = "ca.pem" ) var certificate, _ = tls.LoadX509KeyPair(crt, key) var certPool = x509.NewCertPool() var cacert, _ = ioutil.ReadFile(ca) var a = certPool.AppendCertsFromPEM(cacert) var creds = credentials.NewTLS(&tls.Config{ ServerName: address, // NOTE: this is required! Certificates: []tls.Certificate{certificate}, RootCAs: certPool, }) var callOpts = []grpc.DialOption{ grpc.WithTransportCredentials(creds), } func Example_getMechanismInfo() { conn, err := grpc.Dial(address, grpc.WithTransportCredentials(creds)) if err != nil { panic(fmt.Errorf("Could not connect to server: %s", err)) } defer conn.Close()

cryptoClient := pb.NewCryptoClient(conn)

mechanismListRequest := &pb.GetMechanismListRequest{} mechanismListResponse, err := cryptoClient.GetMechanismList(context.Background(), mechanismListRequest) if err != nil { panic(fmt.Errorf("Get mechanism list error: %s", err)) }

190 Securing Your Critical Workloads with IBM Hyper Protect Services fmt.Printf("Got mechanism list:\n%v ...\n", mechanismListResponse.Mechs[:1])

6.4 Public Cloud service instantiation

The Hyper Protect Virtual Server service is also available on the IBM Cloud. This section describes the steps that are used to instantiate a virtual server

Deploying an instance Complete the following steps to deploy an instance: 1. In the IBM Cloud, open the Hyper Protect Virtual Server service in the catalog. 2. Select and enter the required parameters, including deployed region, instance name, and ssh public key, as shown in Figure 6-56 on page 192. Then, click Create to create an instance.

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 191 Figure 6-56 Deploying a Hyper Protect Virtual Server instance in IBM Cloud

3. Check the instance status in the Resource list page, as shown in Figure 6-57. The deployment process takes several minutes to complete. After the process is done, the status shows as: provisioned.

Figure 6-57 IBM Cloud Hyper Protect Virtual Server instance status

192 Securing Your Critical Workloads with IBM Hyper Protect Services Viewing the instance details After the instance is provisioned, you can open the instance to see the details, as shown in Figure 6-58.

Figure 6-58 IBM Cloud Hyper Protect Virtual Server instance

Accessing your virtual server You can get the virtual server’s public and internal IP addresses from the instance details page and access the virtual server by way of SSH, as shown in Example 6-7.

Example 6-7 Accessing the Hyper Protect Virtual Server instance # ssh -i redbook [email protected] The authenticity of host '169.63.212.8 (169.63.212.8)' can't be established. ECDSA key fingerprint is SHA256:zsh2ZfgkfEX2n60DANflQFM7zOYQj9IZZfMS9iK+E28. ECDSA key fingerprint is MD5:25:33:b9:cf:e2:e6:d3:31:47:9f:f7:36:66:48:8d:49. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '169.63.212.8' (ECDSA) to the list of known hosts. Unauthorized access to this machine is prohibited. Welcome to Ubuntu 18.04.3 LTS (GNU/Linux 4.15.0-62-generic s390x)

* Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage

The programs included with the Ubuntu system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright.

Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law.

Unauthorized access to this machine is prohibited. root@57c931651964:~#

Chapter 6. IBM Hyper Protect Virtual Servers on-premises installation 193 194 Securing Your Critical Workloads with IBM Hyper Protect Services 7

Chapter 7. IBM Hyper Protect Virtual Servers key features

In this chapter, we discuss the key features of Hyper Protect Virtual Servers and for each feature, explain step-by-step how to enable and start using that feature.

This chapter includes the following topics: 7.1, “User roles in Hyper Protect Virtual Servers” on page 196 7.2, “Trusted CI/CD: Building and deploying containers securely” on page 197 7.3, “Monitoring” on page 206 7.4, “GREP11 (EP11 over gRPC)” on page 210 7.5, “Bring Your Own Image (Trusted Repository Registration)” on page 216

In this section, we discuss the different roles and responsibilities that are involved in the administration of a Hyper Protect Virtual Servers cloud platform. We also describe how this separation of user roles and limiting of the permissions of each role achieves a heightened level of security for critical workloads in the public cloud and the private cloud.

In a typical cloud platform, public or private, user roles that have low-level administrative permissions to access the infrastructure underlying the cloud typically can access the containers that are running in the cloud, the workloads that are running in those containers, and the data those containers use. Even if the administrators secure the cloud from threats from outside the organization, a threat exist from persons inside the organization who hold administrative user roles, tamper with the workloads that are running on the cloud, or steal data or secrets that the cloud stores.

Hyper Protect Virtual Servers feature many administrator roles, each with their own responsibilities. The preferred practice is that a different person in the organization holds each of the following user roles to prevent one person from having administrative access to too many of the resources in the cloud: IBM Z System Administrator Creates and manages Logical Partitions (LPARs) and is responsible for the low-level provisioning and management of the IBM Z mainframe or IBM LinuxONE server systems. Appliance Manager Deploys and manages the Secure Service Container (SSC) application that allows the dynamic provisioning of network, storage, and container resources onto which the LPAR the Appliance Manager installs SSC. An Application Manager can build a secure cloud on the LPAR by using the SCC application. Application Manager Deploys containerized applications onto the LPAR that is running SSC application (SSC LPAR). Application Builder Builds and validates containerized applications to run on the SSC LPAR. Application Developer Writes containerized applications that the Application Builder builds, and the Application Manager then deploys to the SSC LPAR. Application User Interacts with the containerized applications or virtual servers that are deployed on the SSC LPAR. Independent software vendor (ISV) Creates and distributes applications to for Application Managers from different businesses or organizations to run on their private cloud. In Hyper Protect Virtual Servers, the ISV creates containerized applications to run on the SSC LPARs that the ISV’s customers create.

196 Securing Your Critical Workloads with IBM Hyper Protect Services The Appliance Manager, Application Manager, and IBM Z System Administrator cannot access the containerized applications or the data those applications use when the containers run inside an SSC LPAR. Therefore, a cloud for your critical workloads that uses Hyper Protect Virtual Servers, which uses the SSC technology along with advanced security features native to the Linux on Z platform such as encryption of data at rest and in-flight, is secure from insider threats.

IBM Cloud Hyper Protect Virtual Servers uses the same SSC technology to protect your critical workloads that are running in the IBM public cloud. Therefore, IBM service engineers who act as the Application Manager, Appliance Manager, and IBM Z System Administrator roles cannot access a Cloud Hyper Protect Virtual Servers instance. Those IBM administrators also cannot access the data and secrets that are associated with an instance.

Access to containers and the data the containers use is possible only by using private credentials (such as an SSH private key or authentication token) that only the Application User knows and can access. A typical use case for interaction with a Hyper Protect Virtual Servers container is to restrict the methods by which an Application User can interact with the container to only the end points of that containerized application’s REST API. This restriction further reduces the attack surface of the container because it does not include general-purpose access by way of SSH or a similar interface. This preferred practice is for designing containerized applications that run on Hyper Protect Virtual Servers.

7.2 Trusted CI/CD: Building and deploying containers securely

In this section, we discuss how, for on-premises installations, Hyper Protect Virtual Servers enables a heightened level of security and traceability in your CI/CD pipeline through the Hyper Protect Virtual Servers Trusted CI/CD infrastructure. By using an example, we also demonstrate how to use this infrastructure to build an application image, sign it, and push it to a trusted repository in a container registry.

7.2.1 Importance of establishing a trusted CI/CD pipeline

An organization that wants to build a highly secure cloud to run critical workloads requires a solution where only trusted images can run on the secure cloud. Allowing any workload to run on the cloud introduces exploitable vulnerabilities, including the following examples: The Application Manager can create an instance of an insecure application from an image in a public container registry. Public registries, such as Docker Hub (docker.io), contain many unofficial repositories that include widely varying standards of quality that an image must meet before a developer can push an image to that repository. For example, a particular repository can allow developers to push an image to it even if that image has known vulnerabilities. Allowing the Application Manager to deploy a container from any public repository means that the Application Manager can deploy images with vulnerabilities into your cloud. An Application Developer can build a malicious image and upload it to a repository that an Application Manager decided to trust. The Application Developer understands the image build pipeline and can use that knowledge to build an image with a vulnerability that the build pipeline does not detect. An Application Manager must audit how the Application Builder built an image and what source code the Application Builder used to build it before deploying the image.

Chapter 7. IBM Hyper Protect Virtual Servers key features 197 A bad actor can tamper with an Application Builder’s build environment, or the CI/CD pipeline. This tampering results in the Application Builder unintentionally building and uploading a compromised image to the repository. This process can happen if a user with lower-level administrative role, such as the Appliance Manager, can access the container or virtual machine that is building the image. The result of this tampering is that the build process pushes an image to your trusted repository, which is not the same as the image Application Builder thinks they built.

The Trusted CI/CD feature of Hyper Protect Virtual Servers establishes trust, security, and provenance at every step of the image deployment process, from build, to storage, to instantiation, to avoid introducing these attack vectors into your build process. It prevents you from introducing compromised containers into your cloud.

7.2.2 Trusted CICD pipeline architecture

In this section, we describe the pipeline that creates trusted images that an Application Manager can deploy as Hyper Protect Virtual Servers container instances.

The Application Manager creates one instance of the Secure Build application, is a Hyper Protect Virtual Servers container, on the SSC LPAR for each image the Application Builder wants to build. The Hyper Protect Virtual Servers software package includes the Secure Build container image. The Application Manager loads this image onto the SSC LPAR during installation. For more information about the process for loading this image onto the SSC LPAR and creating an instance of a Secure Build container, see 6.3.3, “Secure Build Container” on page 177.

A secure build instance reviews the source code for a containerized application from GitHub and builds the application image by using Docker. Because the secure build instance runs in the SSC LPAR, administrative users cannot access the secure build instance and they cannot tamper with the image build process.

Each secure build instance must push the image that it builds to a separate repository. An Application Builder cannot reconfigure a secure build instance to make it push images to a different repository after the Secure Build image pushes an image to its associated repository.

Also, a new secure build instance cannot push an image to a repository that is associated with a different secure build instance. This feature ensures that only one build machine can push images to a particular repository, which ensures the provenance of the images in that repository.

The secure build instance also generates a signed manifest file whenever it completes a build. The manifest file can be used to audit what source code the secure build instance that is used during the build that generated the manifest file and how it built the image.

After a secure build instance pushes an image to a repository, the Application Manager cannot deploy that image immediately. The Application Manager must first register the repository on the SSC before deploying images from it by using a registration file that the Application Builder or ISV signed and encrypted.

7.2.3 Using the secure build application to build and store an image in a repository

In this section, we describe the steps to build an application image and push it to a repository by using an instance of the Secure Build application.

198 Securing Your Critical Workloads with IBM Hyper Protect Services The Application Builder must run this procedure.

As an Application Builder, you need one uninitialized secure build instance running on your SSC LPAR to complete these steps. For more information about how to set up Secure Build Container, see 6.3.3, “Secure Build Container” on page 177.

For more information about creating an uninitialized secure build instance, see Chapter 6, “IBM Hyper Protect Virtual Servers on-premises installation” on page 143.

You must obtain the IP address and port the Application Manager that is assigned to the new secure build instance.

For this procedure, you need an account on github.com, and you need to add your SSH public key to your github.com account. For more information about how to generate a public and private SSH key pair and add the public key from the key pair to your github.com account, see this web page.

You need an account on a supported container registry service (Docker Hub or IBM Cloud Container Registry) that can pull and push images to a repository in that container registry.

For this procedure, you need a workstation or server to use as your management host (see Table 6-1 on page 144 for prerequisites) to use as your management host.

Copy the Hyper Protect Virtual Servers software package tarball to your management host and extract its contents. On the management host, complete the following steps: 1. Open a terminal. 2. Browse to the directory to which you extracted the Hyper Protect Virtual Servers software package. 3. Load the Docker image for the Hyper Protect Virtual Servers CLI Tool onto the management host by using the following command: docker load -i hpvs-cli-installer.docker-image.tar

Note: On some systems, running Docker commands requires the user account that runs the command to have root privileges.

4. From the current working directory, browse to the VS/securebuild-cli/config directory. This directory is used to store configuration files for secure build instances. 5. Copy the hosts.example file named hosts. This file defines the details of your SSC LPAR. 6. In the file hosts, replace the example IP address with the IP address of your SSC LPAR. Leave the rest_user and rest_pass parameters empty.

The rest of this example involves building a containerized application that is based on the Disaster Donations Website code pattern. The GitHub repository for this book links to this repository. For more information about finding the code pattern, see this web page.

Then, click IBM/disaster-donations-website on that web page.

Complete the following steps to define the configuration of your secure build instance for building the Disaster Donations Website code pattern images: 1. Copy the securebuild.yaml.example file named securebuild.yaml. This file contains the configuration information that defines the secure build instances that run on your LPAR. 2. In the securebuild.yaml file, replace the example values with values for your secure build instance and the image from the GitHub project you want to build.

Chapter 7. IBM Hyper Protect Virtual Servers key features 199 Table 7-1 lists the important parameters the securebuild.yaml configuration file and the values you need to set those parameters to build the images for the back-end and front-end services for the Disaster Donations Website.

Table 7-1 Parameters the securebuild.yaml configuration file Category Name Description Example Value

container name Container name of the secure build secure-build-frontend instance. Obtain your real container name from your Application Manager.

port Port the secure build instance’s Obtain this from your Application Manager. REST API is accessible on. This is 443 if the secure build instance has its own dedicated IP address.

ipaddress IP address the secure build Obtain this from your Application Manager. instance’s REST API is accessible This is the same as the SSC IP address if the on. Secure Build uses port forwarding to an SSC port.

github url GitHub SSH URL of the GitHub [email protected]:IBM/disaster-donations-web repository from which you are site.git. building.

branch Branch of the GitHub project to check master out and build from.

docker_build Path to the directory in the GitHub frontend/ _path repository to use as the build context (if building the front-end image) or when building the image. backend/ (if building the back-end image)

key Private key for the public key that is associated with your GitHub account. The secure build instance uses this key to clone the GitHub repository.

200 Securing Your Critical Workloads with IBM Hyper Protect Services Category Name Description Example Value docker repo Repository that the secure build mynamespace/ddwbackend instance pushes the image to which it or builds. mynamespace/ddwfrontend

You cannot change this after you initialize a Secure Build container.

user User name for the container registry account the secure build instance uses to push the image it builds to its repository.

password Password for the container registry account the secure build instance uses to push the image it builds to its repository.

push_server Container registry to which the us.icr.io Secure Build server pushes the image it builds.

base_user User name for the container registry account the secure build instance uses to pull down the base image for the image it builds.

base_passw ord

base_server Container registry from which the docker.io secure build instance pulls down the base image.

docker_cont True or False value that controls if the False ent_trust_ba Secure Build server can only build se images where Docker Content Trust signed the image’s base image.

image_pull_ User name for the container registry user account that the SSC uses to pull down the built image from its repository when deploying an instance of the image onto the SSC LPAR.

image_pull_ Password for the container registry password account that the SSC uses to pull down the built image from its repository when deploying and instance of the image onto the SSC LPAR. env whitelist Whitelist of environment variables For the back-end that an Application Manager can image:PASSWORD,USERNAME, pass into an instance of an image DBNAME,ENDPOINT, when its container starts. REPLICASET

Not required for the front-end image

Chapter 7. IBM Hyper Protect Virtual Servers key features 201 You can use the example values that are provided in Table 7-1 on page 200 to build a Node.js front end and a Python backend for the Disaster Donations Website application.

You must add your own GitHub private key, container registry credentials, and your secure build instance port and IP address to securebuild.yaml for each secure build instance you want to create.

Example values are not provided Table 7-1 on page 200 for these parameters.

You can use a single container registry user account's credentials for the user, password, base_user, base_password, image_pull_user, and image_pull_password.

You can define multiple secure build configurations in securebuild.yaml. For example, you can define one configuration to build the front-end image, and one to build the back-end image. If you have two secure build instances available, you can initialize one secure build instance with the configuration to build the front-end, and the other secure build instance with the configuration to build the backend.

Complete the following steps to initialize a secure build instance and use it to build and push an image: 1. To initialize your Secure Build container with the values in your securebuild.yaml configuration file, run the following command: docker run --rm -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:version securebuild init --name container_name Consider the following points: –Replace the version with the version of the Hyper Protect Virtual Servers CLI tool that you loaded from the hpvs-cli-installer.docker-image.tar tarball. – To check the version of the CLI tool, run the docker images command and look for the value in the TAG column in the row that contains ibmzcontainers/ssc4icp-cli-installer in the command output. 2. Look for the following statement in the command output of the previous docker run command, which shows that the command successfully initialized the secure build instance: "msg": "Initialize the Secure Build container using the values from securebuild.yaml: The Secure Build container was successfully initialized: OK" Alternatively, run following command to check that you successfully initialized your Secure Build container: docker run --rm -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:version securebuild status --name container_name 3. Look for the following message in the command output, which shows the Secure Build container is in the initialized state: "msg": "Build status - initialized" This command is also the command you use to view the overall status of a build the Secure Build container is running or completed. You can run the following command to create an alias of this command to make it convenient to quickly check the status of your secure build instance: alias secure-build-status='docker run --rm -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:version securebuild status --name container_name'

202 Securing Your Critical Workloads with IBM Hyper Protect Services This command displays no output if successful. If you run secure-build-status after defining this alias, the output is the same as the output from running the full docker run ... securebuild status command. 4. Run the following command to begin the build of your image on the secure build instance: docker run --rm -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:version securebuild build --name container_name 5. Look for the following message in the command output, which shows the secure build instance started the build of the image: "msg": "OK: async build started" 6. Check the overall build status by using the secure-build-status command. 7. Look for the following message, which indicates that the build completed successfully: "msg": "Build status - success"

Note: If the secure-build-status command does not display the message that is shown in Step 7 and does not display a failure message, the build is in progress. Wait for short time and check again by using secure-build-status until the command output displays the Build status - success message.

8. In your container registry account, browse to the repository defined as the repo in your securebuild.yaml configuration file. 9. Look for the image the Secure Build server builds in this repository. Figure 7-1 shows an example of viewing the images in an IBM Cloud Container Registry account.

Figure 7-1 Container registry

Chapter 7. IBM Hyper Protect Virtual Servers key features 203 10.Run the following commands to pull down the built image to your management host and validate that it is signed by Docker Content Trust (DCT): docker pull myreponame:latest docker trust inspect myreponame 11.Look for the following messages in the output of the second of the above two commands: "Name": "Root", "Keys": [ { "ID": "(hex)" } ] and "Name": "Repository", "Keys": [ { "ID": "(hex)" } ]

Note: The (hex) hexadecimal string identifies the root or repository key DCT that is used to sign the image.

12.Run the following command on a secure build instance that completed a build to download the manifest file for the last completed build: docker run --rm -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:version manifest status --name container_name 13.Look for the following command that retrieves the manifest file from the secure build instance, which indicates the command retrieved the manifest file from the secure build instance: TASK [securebuild-write-file : Write the application manifest to a file - /securebuild-cli/config/manifest.push_server.repo.tag.timestamp.sig.tbz] *** changed: [localhost] PLAY RECAP ********************************************************************* localhost : ok=5 changed=2 unreachable=0 failed=0 14.Make a note of the manifest name from the command output that is shown in the previous step. 15.Extract the manifest contents by using the following commands: tar -xf manifest_name.sig.tbz tar -xf manifest_name.tbz Consider the following points: – The first tar command extracts a manifest signature file, manifest_name.sig, and a manifest archive file, manifest_name.tbz. – The second tar command extracts the contents of the manifest archive file, which are listed in Table 7-2 on page 205.

204 Securing Your Critical Workloads with IBM Hyper Protect Services Table 7-2 Manifest archive file values Directory name File name File or directory contents

data/ build.json The configuration of the secure build instance that the instance used to do the build.

build.log The log for the build.

git/ The source code the Secure build instance that is used to do the build.

root_ssh/ N / A This directory is always empty.

7.2.4 Building an image from a trusted base image

Building your image by using the Secure Build builds trust into the parts of the image build process under your direct control. Most Application Builders build images from a base image rather than building the image from scratch. Therefore, control over part of the image build process (the part that builds the base image) is under control of a different person or entity.

Building image from a base image introduces a possible attack vector in that the Application Builder does not have control over who builds the base image and how the base image builder does so. Therefore, it is possible that the base image build was tampered with, or a base image builder knowingly pushed a version of the base image with a known vulnerability to the base image’s repository.

The mitigation for this attack vector is to build only your images to run as Hyper Protect Virtual Servers from a base image that the base image builder also built by using the Trusted CI/CD process.

IBM provides two base images that IBM has built by using the Trusted CI/CD, and validated they passed the IBM quality assurance and security testing process for images that are designed for Hyper Protect Virtual Servers. You can use these images as trusted base images for building your own images to run on Hyper Protect Virtual Servers.

IBM distributes a trusted base image that includes SSH that you can use to build your development images, and an image without SSH that you can use to build a locked-down production image for your production environments.

Complete the following steps to push the trusted base image without SSH that IBM distributes with Hyper Protect Virtual Servers to a repository in your container registry: 1. Open a terminal on your management host. 2. From the directory you extracted Hyper Protect Virtual Servers software package to, browse to the VS/monitoring-cli/hpvs-cli directory. 3. Run the mkdir hpvs-base command to create a directory to which the base image is extracted. 4. Run the tar -xf HpvsopBase.tar.gz -C hpvs-base/ command to extract the base image. 5. Run the cd hpvs-base; gpg HpvsopBase.tar.gz.gpg command to extract the base image Docker archive. Answer yes (y) to any questions the gpg command presents you. 6. Run the docker load -i HpvsopBase.tar.gz command to load the base image into Docker on your management host.

Chapter 7. IBM Hyper Protect Virtual Servers key features 205 7. Run the following commands to log in to your container registry account and push the base image to a repository in that container registry. Use the user name and password credentials for the container registry account you use for the base_user / base_password in your securebuild.yaml file: docker login -u username docker push username/hpvsop-base:latest 8. Repeat steps 1- 7, substituting hpvsop-base-ssh for hpvsop-ssh and HpvsopBaseSSH for HpvsopBase to push the trusted base image with SSH to your container registry account. 9. Replace the FROM line in the Dockerfile you use to build your image with FROM username/hpvsop-base:latest to build your image from the trusted base image without SSH. To build some images, you must add steps to your Dockerfile to install dependencies that the trusted base image does not include.

7.3 Monitoring

In this section, we discuss how to deploy a monitoring service onto your SSC LPAR to monitor the containers that are running on the SSC LPAR. This service allows you to monitor the status and health of your SSC LPAR.

7.3.1 Deploying a monitoring container

The Application Manager must run this procedure.

To deploy the Hyper Protect Virtual Servers’ monitoring service and connect a metrics viewing service to it, you must create two private key and public certificate pairs: a client private key and certificate, and a server public key and certificate.

Complete the following steps on your management host to deploy the monitoring service: 1. Open a terminal. 2. From the directory you extracted Hyper Protect Virtual Servers software package to, browse to the VS/monitoring-cli/config directory. 3. Create a copy of the hosts.example file named hosts. 4. In the hosts file, replace the example IP address with the IP address of your SSC LPAR. 5. In the hosts file, replace the example values for rest_user and rest_pass with your SSC LPAR User ID and password credentials. 6. Create a copy of the monitoring.yaml.example file named monitoring.yaml. 7. Enter the parameters in the monitoring.yaml file to define the configuration of your monitoring service The important parameters that appear in the monitoring.yaml monitoring service configuration file are listed in Table 7-3.

Table 7-3 Parameters in the monitoring.yaml file Category Name Description Example value

LPARS ipaddress IP Address of your SSC

containers List of the container template See Table 7-4 on definitions for the monitoring service page 207 template.

206 Securing Your Critical Workloads with IBM Hyper Protect Services Category Name Description Example value

monitoring-host name Name of the monitoring host container monitoring-host (one of the containers that the monitoring service consists of).

collectd-host name Name of the collectd host container collectd-host (one of the containers that the monitoring service consists of).

Consider the following points: – A monitoring service consists of two containers: a monitoring container, called monitoring-host in the monitoring.yaml file, and a collectd container, called collectd-host in the monitoring.yaml file. – To complete the monitoring.yaml configuration file, you must define the container templates for these two containers under the LPARS:containers: subsection. Table 7-4 lists the important parameters for these two container templates.

Table 7-4 Parameters for the monitoring-host and the collectd-host containers Container Container Parameter description Example value template name template parameter

monitoring-host private-key-server Path to the private key to /monitoring-cli/config/server. use with the monitoring key container

public-cert-server Path to the public server /monitoring-cli/config/server certificate to use with the -certificate.pem monitoring container

public-cert-client Path to the public client /monitoring-cli/config/client- certificate to use with the certificate.pem monitoring container

metric_dn_suffix Domain suffix for the first monitoring service

dns_name DNS name for the mymonitoring.com monitoring service

Name of the monitoring my-monitoring-host host container

collectd-host Name of the collectd host collectd-host container

monitoring-host private-key-server Path to the private key to /monitoring-cli/config/server. use with the monitoring key container

– The monitoring service uses the metric_dn_suffix and the dns_name parameters to construct a DNS name alias for the SSC IP address that a tool that collects and reports the logs from the monitoring service can use. For example, the monitoring service constructs the DNS name collectdhost-first.mymonitoring.com when the parameter metric_dn_suffix has the value first, and the parameter dns_name has the value mymonitoring.com.

Chapter 7. IBM Hyper Protect Virtual Servers key features 207 8. Run the following command to create the monitoring service, which creates instances of the collectd container and the monitoring container on your SSC LPAR: docker run --rm -v $(pwd):/monitoring-cli/config ibmzcontainers/hpvs-cli-installer:version monitoring create 9. Look for the following message in the command output, which indicates the command successfully created the two monitoring service containers: "msg": [ "LPAR_IP:monitoring-host", "LPAR_IP:collectd-host" ] 10.Run the following command by using curl to test the endpoint for the monitoring service: curl https://LPAR_IP:8443/metrics -k --cert client-certificate.pem --cacert server-certificate.pem --key client.key This shows that the monitoring service is available on the LPAR’s IP address on port 8443.

7.3.2 Viewing the metrics from the monitoring service

The monitoring service must send the metrics that it collects to a separate service that makes the metrics viewable. The preferred software to use with the Hyper Protect Virtual Servers monitoring service is Prometheus.

You can download the Prometheus software package tarball from this website.

In the unpackaged tarball, a YAML file, prometheus.yml, is included that contains the configuration settings the Prometheus executable uses when it runs.

Table 7-5 lists the parameters in the prometheus.yml file that you must set to make the Prometheus service connect to the monitoring service that is running on your SSC LPAR. This example assumes that you copied the server certificate, server-certificate.pem, the client certificate, client-certificate.pem, and the client private key, client.key, to the directory on your management host that contains the Prometheus executable and the prometheus.yml configuration file. In the following example, this directory is /opt/prom/.

Table 7-5 Parameters in the prometheus.yml file that you need to configure Category Name Example Value

global:tls_config ca_file /opt/prom/server-certificate.pem

cert_file /opt/prom/client-certificate.pem

key_file /opt/prom/client.key

server_name collectdhost-first.example.com

global:static_configs targets collectdhost-first.example.com:8443 (array)

In Table 7-5 on page 208 for the example parameters, the value of targets must be an array with a single element, colectdhost-first.example.com:8443. For example: targets: ['collctdhost-first.example.com:8443']

208 Securing Your Critical Workloads with IBM Hyper Protect Services Complete the following steps to start Prometheus and connect it to the monitoring service you deployed onto your SSC LPAR so that you can view the metrics the monitoring service collects: 1. Download the Prometheus software package to your management host. 2. On your management host, extract the Prometheus software package tarball. 3. Replace the parameters in the prometheus.yml file with the parameters for your monitoring service, including the paths to your server certificate, client certificate, and client key that you use with your monitoring service. 4. Run the Prometheus executable prometheus. 5. Open a web browser. 6. Browse to https://MANAGEMENT_HOST_IP:9090/graph to view the Prometheus web GUI. 7. To view the data for a metric that the monitoring service collects, complete the following steps: a. Select the tab Graph. b. Select the metric you want to view from the drop-down list next to the Execute button. c. Click Execute, as shown in Figure 7-2.

Figure 7-2 Prometheus select metric

Chapter 7. IBM Hyper Protect Virtual Servers key features 209 Figure 7-3 shows an example of the graph Prometheus can display for one of the metrics that monitoring service collects, collectd_load_shortterm.

Figure 7-3 Prometheus monitoring load

7.4 GREP11 (EP11 over gRPC)

In this section, we discuss requirements for deploying a Hyper Protect Virtual Servers GREP11 service. This service allows you to use the IBM Z or IBM LinuxONE server’s Hardware Security Module (HSM) to generate secrets, such as public and private key pairs, storing the private part of the secret securely in the HSM.

A GREP11 container is a microservice that runs on your SSC LPAR that provides an Enterprise PKCS #11 over gRPC (GREP11) API that enables you to call the cryptographic functions on the HSM from other microservices or applications, including from a Virtual Server that is running on your SSC LPAR. You can use the HSM cryptographic functions to encrypt and decrypt data, calculate the digest (hash value) of data, and sign and verify data. The HSM securely stores the private keys that the cryptographic operations use without exposing the private keys to system administrators.

Note: Two crypto domains across two crypto express cards are recommended for production environments for high availability purposes.

7.4.1 Checking the LPAR for GREP11 support

Note: The Application Manager must complete this process.

The system administrator must configure at least one EP11 mode Crypto Express Domain and initialize the master key.

210 Securing Your Critical Workloads with IBM Hyper Protect Services To check the crypto domains that are configured on your SSC LPAR, complete the following steps: 1. Open a terminal on your management host. 2. From the directory where you extracted the Hyper Protect Virtual Servers software package, browse to the VS/grep11-cli/config directory. 3. Create a copy of the hosts.example file named hosts. 4. In the file hosts, replace the value of IP with the IP address of your SSC LPAR, rest_user with the Secure Service Container User ID, and rest_pass with the password for the Secure Service Container User ID. 5. Run the following command to check the crypto configuration on your SSC LPAR: docker run --rm -v $(pwd):/grep11-cli/config ibmzcontainers/hpvs-cli-installer:version crypto list 6. Look for the following message in the output of the command, which indicates which crypto domains the system administrator configured on the SSC LPAR: "vfio_ap": [ "09.000a", "07.000a" ] Look for the following message in the output, which indicates the crypto domains, if any, that are already in use: "matrix": [ "07.000a" ]

In this example, the outputs show that the system administrator configured crypto domains 09.000a and 07.000a. Crypto domain 07.000a is in use. Therefore, only crypto domain 09.000a is available.

7.4.2 Deploying a GREP11 container

Client programs or services authenticate with a GREP11 service by using one-way authentication over TLS or mutual authentication over TLS. This method is different from the method a client uses to authenticate with a Hyper Protect Crypto Services instance, which uses your IBM Cloud API key and an IBM Cloud Identity and Access Management (IAM) endpoint for authentication.

For your client applications to authenticate with your GREP11 container, you must generate a set of certificates and private keys. Which and what type of certificates and private keys you need to generate depends on the authentication method you choose to use.

If you use one-way authentication over TLS, you musty generate a self-signed certificate and private key, which the client application and GREP11 service use.

If you use mutual authentication over TLS, you must generate a certificate authority (CA) certificate and private key. Then, use the CA certificate to generate a server certificate and private key pair, which you pass into the GREP11 container when you create it, and a client certificate and private key pair, which the client application uses.

Because the examples in this book use mutual authentication over TLS method, the names of the example certificate and private key files reflect this use.

Chapter 7. IBM Hyper Protect Virtual Servers key features 211 Complete the following steps to deploy a GREP11 service on your SSC LPAR: 1. Open a terminal on your management host. 2. Open the Hyper Protect Virtual Servers software package; then, browse to the VS/grep11-cli/config directory. 3. Create a copy of the grep11-config.yaml.example file called grep11-config.yaml. 4. Replace the example values in the grep11-config.yaml file with values for your SSC and for the GREP11 container you want to create. Table 7-6 lists the important parameters that appear in the grep11-confg.yaml grep11 container configuration file.

Table 7-6 Parameters in the grep11-confg.yaml file Category Name Description Example value

name Name of the GREP11 container my-grep11-container instance.

crypto_domain Crypto domain to use for the 09.000a GREP11 container.

network network_name Name of the network on the LPAR default to connect the GREP11 container to.

port Port on which to expose the 19876 GREP11 service that the GREP11 container provides. The default port is 9876

mutual_tls If true, the GREP11 service True requires a client to connect to it using mutual authentication over TLS. If false, the GREP11 service allows a client to connect to it using one-way authentication over TLS.

certificate The server certificate that mutual server.pem authentication over TLS uses, or the certificate that one-way authentication over TLS uses.

key The server private key that server-key.pem mutual authentication over TLS uses, or the private key that one-way authentication over TLS uses.

cacertificate The CA certificate that mutual ca.pem authentication over TLS uses.

– The value of crypto_domain must be one of the crypto domains that are found to be configured on the SSC LPAR as described in “Checking the LPAR for GREP11 support” on page 210. – If the value of network_name is default, the GREP11 container uses the default bridge network and the specified port on the SSC LPAR’s IP address. Otherwise, if network_name is specified as a named network on the SSC LPAR, another parameter, ip, must be specified under the category network.

212 Securing Your Critical Workloads with IBM Hyper Protect Services 5. Run the following command to create a GREP11 container that uses the configuration that is specified in your grep11-config.yaml file: docker run --rm -v $(pwd):/grep11-cli/config ibmzcontainers/hpvs-cli-installer:version grep11 create 6. Look for the following message in the output of the command, which indicates that the command successfully created the GREP11 container: "msg": "grep11 created successfully"

Figure 7-4 and Figure 7-5 show the start and end of the command output for an example of a successful invocation of the grep11 create command.

Figure 7-4 grep11 create command

Figure 7-5 Installation success result

7. Run the following command to check the status of the created GREP11 container: docker run --rm -v $(pwd):/grep11-cli/config ibmzcontainers/hpvs-cli-installer:version grep11 status 8. Look for the following message in the output of the command, which indicates that the GREP11 container is running: 'Status': 'running' 9. Figure 7-6 and Figure 7-7 on page 214 show the start and end of the command output for an example of a successful invocation of the grep11 status command, where the GREP11 container you are checking is running.

Figure 7-6 grep11 status command

Chapter 7. IBM Hyper Protect Virtual Servers key features 213 Figure 7-7 Status response

7.4.3 Adding GREP11 functionality into your applications

The GitHub repository provides source code example for using the GREP11 API that the GREP11 container provides. This book uses the examples for Golang. You can reuse code from these examples to add GREP11 functions to your own applications.

To authenticate with a Hyper Protect Virtual Servers GREP11 service, use your client certificate if you use one-way authentication over TLS. If you use mutual authentication over TLS, use the certificate authority (CA) certificate and your client private key. The following example explains how to run the suite of tests the Golang examples the ibm-cloud-hyperprotectcrypto repository provides against a gREP11 container using mutual authentication over TLS: 1. Install Golang on your management host. 2. Check and make a note of your GOPATH directory by running the go env command. 3. Create the src/github.com/ibm-developer/ subdirectory in your GOPATH directory. 4. Browse to the ibm-developer/ subdirectory in the directories you created. 5. Clone the repository https://github.com/mattarnoatibm/ibm-cloud-hyperprotectcrypto the ibm-developer/ directory. 6. Browse to the ibm-cloud-hyperprotectcrypto/golang/examples directory in the GitHub project that is cloned to your management host. 7. Open the server_test.go file. 8. Add the imports crypto/x509 and io/ioutil to the list of imports to use in the Golang program. 9. Replace the value of const address with the address and port of your gREP11 service. 10.Remove grpc.WithPerRPCCredentials(...) from []grpc.DialOption { ... }, which is the value of callOpts. 11.Add the keys and values that are listed in Table 7-7 to the tls.Config data structure grpc.WithTransportCredentials uses.

Table 7-7 keys and values for the tls.Config file Key name Key value

ServerName Address and port on which the gREP11 service is accessible. Usually, the address of your SSC and the port you assigned to your gREP11 container.

Certificates Array of TLS Certificate objects. For your gREP11 service, the key value must be a Certificate object that you use your client certificate and client private key to create.

214 Securing Your Critical Workloads with IBM Hyper Protect Services Key name Key value

RootCAs CertPool (certificate pool) object containing your CA certificate.

You can find it helpful to define a new function getCallOpts so that function that provides your array of grpc.DialOption objects for calling your gREP11 service is similar to the code example that is shown in Example 7-1.

Example 7-1 Code example const address = "myssc.mydatacenter.com:9876" const cert = "client.pem" const key = "client-key.pem" const ca = "ca.pem" func getCallOpts() []grpc.DialOption { certificate, _ := tls.LoadX509KeyPair(cert, key) cacert, _ := ioutil.ReadFile(ca) certPool := x509.NewCertPool() certPool.AppendCertsFromPEM(cacert) callOpts := []grpc.DialOption{ grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{ ServerName: address, Certificates: []tls.Certificate{certificate}, RootCAs: certPool, })), } return callOpts }

For brevity, the code example that is shown in Example 7-1 omits error handling code. 12.If you write a getCallOpts function, such as the function in Example 7-1, add the line of code callOpts := getCallOpts() at the start of each test case to retrieve the gRPC Dial Option. 13.If you are using one-way authentication over TLS, Figure 7-8 shows how to modify server_test.go to test your GREP11 container.

Figure 7-8 How to modify server_test.go to test your GREP11 container

Chapter 7. IBM Hyper Protect Virtual Servers key features 215 14.Run the go test -v command to run the suite of tests. 15.Look for the following output messages in the output of the command, which indicate each test in the test suit ran successfully and the test suite demonstrated each crypto function of gRPC11 / the HSM works for your HSM and gREP11 service: === RUN Example_getMechanismInfo --- PASS: Example_getMechanismInfo (1.04s) === RUN Example_encryptAndDecrypt --- PASS: Example_encryptAndDecrypt (2.34s) === RUN Example_digest --- PASS: Example_digest (1.90s) === RUN Example_signAndVerifyUsingRSAKeyPair --- PASS: Example_signAndVerifyUsingRSAKeyPair (2.21s) === RUN Example_signAndVerifyUsingECDSAKeyPair --- PASS: Example_signAndVerifyUsingECDSAKeyPair (1.64s) === RUN Example_signAndVerifyToTestErrorHandling --- PASS: Example_signAndVerifyToTestErrorHandling (1.54s) === RUN Example_wrapAndUnwrapKey --- PASS: Example_wrapAndUnwrapKey (2.00s) === RUN Example_deriveKey --- PASS: Example_deriveKey (2.10s) === RUN Example_tls --- PASS: Example_tls (1.11s)

7.5 Bring Your Own Image (Trusted Repository Registration)

The Application Manager must register a repository on the SSC as a trusted repository before the Application Manager can deploy instances of images from that repository to the SSC LPAR.

In this section, we discuss how to register two types of repositories: repositories that a Secure Build container pushes images to, and repositories that a generic build host, other than Secure Build that runs on LinuxONE or Linux on IBM Z and pushes images to with Docker Content Trust (DCT). An example of a generic build machine that runs on Linux on IBM Z or on LinuxONE is an IBM Cloud Hyper Protect Virtual Servers instance.

7.5.1 Registering a repository as a trusted repository

Before you deploy the image that your secure build instance or a generic build server that is built, you must register the repository that stores the image on your SSC LPAR. To register the repository, the Application Builder must retrieve an unsigned and unencrypted repository definition file from the secure build instance that built the image, sign, and encrypt the file, and then, give the signed and encrypted repository definition file to the Application Manager. The Application Manager can then register the repository by using the repository definition file.

A different process for creating the repository definition file exists if a generic build server builds and pushes the images to the repository you want to register. This process allows you to deploy images that your secure build instances did not build, but you trust and want to run on your SSC LPAR anyway.

216 Securing Your Critical Workloads with IBM Hyper Protect Services 7.5.2 Creating a repository registration file for a repository to which a Secure Build Instance pushes images

Note: The Application Builder must complete this process.

Complete the following steps to create a signed and encrypted repository definition file: 1. Open a terminal on your management host. 2. Run the following command to retrieve the unsigned and unencrypted repository definition file from a secure build instance that completed a build: docker run --rm -v $(pwd):/securebuild-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0 securebuild regfile --name container_name 3. Look for the following message in the command output, which indicates that the CLI command retrieved the repository definition file from the Secure Build container instance: TASK [securebuild-write-file : Write the application regfile to a file - /securebuild-cli/config/MyApp.json] *** This command retrieves the repository definition file as MyApp.json on your management host, in plaintext JSON format. 4. Rename this repository definition file to give it a unique name. For example, run the mv MyApp.json MyNewApp.json command. 5. Run the following command to sign and encrypt the repository definition, choosing passphrase to be a strong passphrase of your choice: docker run --rm -v $(pwd):/regfile-cli/config ibmzcontainers/hpvs-cli-installer:version regfile encrypt -ph passphrase -i MyFirstApp.json This command creates a signed and encrypted repository definition file that is named MyFirstApp.json-rel.enc if it succeeds. 6. Send your signed and encrypted repository registration file to your Application Manager so that the Application Manager can complete the process of registering the repository on your SSC LPAR.

7.5.3 Creating a repository registration file to which a generic build server pushes images

Note: The Application Builder complete this process.

The Application Manager can also complete this process if the Application Manager owns a container registry account that can pull down images from the repository the Application Manager wants to register.

You can create a repository definition file to register any repository that requires DCT to sign images that the build server pushes to that repository. Any build server that has access to the DCT root and repository private keys can push images to this type of repository; therefore, this method is less secure than pushing images to a repository by using Secure Build.

Chapter 7. IBM Hyper Protect Virtual Servers key features 217 Using a secure build instance to build your images so that a user cannot distribute the DCT keys that the build server uses to push the image to its repository is the preferred practice for building images to run on your SSC LPAR. However, if images exist that you trust and want to run with Hyper Protect Virtual Servers, the following process allows you to deploy these images to your SSC LPAR from the repository that stores them.

Complete the following steps to create a signed and encrypted repository definition file for a generic repository: 1. Open a terminal on your management host. 2. In any directory to which you have write permission, run the following command to create, sign, and encrypt a repository registration file (the command parameters define the repository that you want to create a repository registration file for): docker run --rm -v $(pwd):/regfile-cli/config ibmzcontainers/hpvs-cli-installer:version regfile create -r container_repo -s container_registry_server -u container_registry_username -p container_registry_password -e env_variables_whitelist -ph passphrase Table 7-8 lists the parameters that you must pass into the preceding command by using examples from the Disaster Donations Website code pattern back-end service.

Table 7-8 Parameters for the docker run command Flag Name Description Example value

r Repository name Name of the repository in the mynamespace/d container registry service to register. dwbackend

s Container DNS name of the container registry us.icr.io registry name service

u Container User name for the container registry registry account account that pulls images from the username repository to register.

p Container Password for the container registry registry account account that pulls images from the password repository to register.

e Environment Comma-separated whitelist of PASSWORD,US variables whitelist environment variables that the ERNAME, Application Manager can pass into a DBNAME,ENDP container on container instantiation. OINT, REPLICASET

ph Passphrase Passphrase for the key pair the command generates to encrypt the repository registration file.

– Choose passphrase to be a strong passphrase of your choice. – This command creates a signed and encrypted repository definition file named isv_definition_template.json-rel.enc if it succeeds.

Rename this file to the unique name that you want to register your repository under; for example, MyAppBackend.json-rel.enc.

If you are the Application Builder, send your signed and encrypted repository registration file to your Application Manager so that the Application Manager can complete the process of registering the repository on your SSC LPAR.

218 Securing Your Critical Workloads with IBM Hyper Protect Services 7.5.4 Registering a repository on your SSC LPAR using the repository registration file

Note: The Application Manager must complete this process.

Complete the following steps to register a signed and encrypted repository definition file on your SSC LPAR: 1. Open a terminal on your management host. 2. From the directory you extracted the Hyper Protect Virtual Servers software package to, browse to the VS/monitoring-cli/hpvs directory. 3. Create a copy of the hosts.example file that is named hosts. 4. In the hosts file, replace the example IP address with the IP address of your SSC LPAR. 5. In the hosts file, replace the example values for rest_user and rest_pass with your SSC LPAR user ID and password credentials. 6. Copy the signed and encrypted repository definition file that you received from your Application Builder or that you generated yourself, MyFirstApp.json-rel.enc, into the VS/monitoring-cli/hpvs directory. 7. Run the following command to register the repository on your SSC: docker run --rm -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-isntaller:version repository create --repoid MyApp --repofile MyFirstApp.json-rel.enc --lpar lpar_ip_address 8. Look for the following message in the output of the command, which indicates that the command successfully registered the repository on your SSC: "msg": { "repository_name":"docker.io/mynamespace/ddwbackend", "runtime": "runq" } This command uses the repository registration file MyFirstApp.json-rel.enc to register the repository under the identifier MyFirstApp. Replace MyFirstApp with the unique name you chose to identify the repository you want to register. Run the following command to tests that this repository has been registered: docker run --rm -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-isntaller:version repository list --lpar lpar_ip_address 9. Look for the following message in the command output, which indicates the command successfully registered the repository as a trusted repository: "MyFirstApp": { "repository_name": "myrepo", "runtime": "runq" }

7.5.5 Registering repository by using public key and private key (optional)

In 7.5.2, “Creating a repository registration file for a repository to which a Secure Build Instance pushes images” on page 217, we described encrypting repository definition files by using default configurations. The Application Manager can choose to generate custom public and private key to do the same. For this process, GPG tools must be installed.

Chapter 7. IBM Hyper Protect Virtual Servers key features 219 Complete the following steps: 1. To encrypt the repository definition file, the user must generate a key pair for signing, as shown in Example 7-2.

Example 7-2 Generating a key pair for signing export keyName=isv_user export passphrase=over-the-lazy-dog cat >isv_definition_keys < ${keyName}.private gpg --armor --export ${keyName} > ${keyName}.pub

2. After the keys are generated, copy the private and public key files under the regfile-cli/config directory. 3. By using the generated key pair, the Application Manager can sign and encrypt the repository definition file, as shown in the following example: docker run --rm -v $(pwd):/regfile-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0 regfile encrypt -K isv_user.private -k isv_user.pub -ph over-the-lazy-dog -i MyFirstApp.json

220 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 7-9 shows the output of this command.

Figure 7-9 Encrypting the repository definition file

4. After the encrypted repository file is present, we can register the repository on the SSC LPAR. For that, first we must copy the encrypted repository file under the hpvs-cli/config folder. After it is copied, use the following command to register the repository on the SSC LPAR.: docker run --rm -it -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0 repository create --lpar [LPARNAMEORADDRESS] --repoid MyDockerApp --repofile MyDockerApp.json-rel.enc 5. List the repository to verify that the repository was created successfully: docker run --rm -it -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-installer:1.1.0 repository list --lpar [LPARNAMEORADDRESS]

Chapter 7. IBM Hyper Protect Virtual Servers key features 221 As shown in Figure 7-10, testapp is a sample user-defined repository.

Figure 7-10 Repository list command

7.5.6 Deploying a securely built image from a trusted repository

Note: The Application Manager must complete the following procedure.

To deploy an instance of an image to your SSC LPAR from an image that is stored in a trusted repository that you registered on your SSC, you must add information that describes the container deployment you want to run in your Hyper Protect Virtual Servers configuration file, hpvs-config.yaml.

Complete the following steps to deploy your containers to your SSC LPAR: 1. Open a terminal on your management host. 2. Create a copy of the hpvs-config.yaml.example file that is named hpvs-config.yaml. 3. Enter the parameters in the hpvs-config.yaml file to define the configuration of your SSC LPAR and the containers that run on it: –In hpvs-config.yaml, you define container templates that describe the configuration of a type of container; then, you edit your LPAR definitions to define how many of each type of container you want to deploy and the IP addresses to assign to each container. – Table 7-9 on page 223 lists the important parameters that appear in the hpvs-config.yaml monitoring service configuration file.

222 Securing Your Critical Workloads with IBM Hyper Protect Services Table 7-9 Parameters in the hpvs-config.yaml monitoring service configuration file Category Name Description Example value

cluster name Name that identifies all the SSC mycluster LPARs in your private cloud.

LPARS (array) ipaddress IP address of an SSC LPAR.

name Name that identifies an SSC LPAR.

containers (array) Array of the container templates to run on the LPAR.

LPARS:-containe template Name that identifies the container mycontainertemplate rs: (array) template.

count Number of instances of the container template type to run on the LPAR.

networks (array) Array of the networks to connect to container instances.

LPARS:-containe network_name Name of a network to connect mynetwork rs:-networks: instances of the container to. (array) ip_address Array of IP addresses on the [x.x.x.1, x.x.x.2, (array) network to assign to the container x.x.x.3] instance; one IP address per container instance per network.

mycontainertemp Section that defines a particular late container template. One section per unique container template that is named in the LPARS section.

Table 7-10 lists the important parameters that appear in the container template definitions.

Table 7-10 Parameters in the container template definitions Name Description Example value

name The name of the container template. first-container-te mplate

repoid The identifier of the repository registration on the LPAR. MyApp

imagetag The tag name that identifies the image in the repository to latest use for the container deployments for this container template.

quotagroup_stor The amount of storage space each container instance 1GB age requires.

vs_index Unique index for each container template. Each container 10000 name is computed as name-(vs_index+container_index).

Chapter 7. IBM Hyper Protect Virtual Servers key features 223 Name Description Example value

networks: List of networks to connect the container to. mynetwork: subnet: For each, specify the network’s the network subnet, x.x.x.0/25 gateway, parent, and driver. gateway: x.x.x.1 If the parent is bridge (the Docker bridge network), you do parent: not need to specify the driver. mybasenetwork driver: macvlan

–The hpvs-config.yaml configuration file that is shown in Example 7-3 is a definition of an example deployment that uses the image that you built and the repository that you registered. – The use of this configuration file results in the deployment of three container instances from the image with the tag latest that the repository that is registered under MyRepoId stores cluster.

Example 7-3 hpvs-config.yaml configuration file cluster: name: MyClusterName

LPARS: - ipaddress: x.x.x.x name: MyLPARName containers: - template: MyFrontEndTemplateName count: 3 networks: - network_name: bridge ip_address: ['192.168.0.2, 192.168.0.3, 192.168.0.4']

MyFrontEndTemplateName: name: MyContainerName repoid: MyRepoId vs_index: 10000 imagetag: latest quotagroup_storage: 1GB networks: bridge: subnet: 192.168.0.0/25 gateway: 192.168.0.1 parent: bridge

4. Run the following command to apply this configuration to your SSC LPAR, which deploys the containers that you specified onto it: docker run --rm -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-isntaller:version hpvs create --lpar lpar_ip_address 5. Run the following command to view the containers that deployed to your Hyper Protect Virtual Servers LPAR: docker run --rm -v $(pwd):/hpvs-cli/config ibmzcontainers/hpvs-cli-isntaller:version hpvs list --lpar lpar_ip_address

224 Securing Your Critical Workloads with IBM Hyper Protect Services 6. Look for the following command outputs, which indicate that the command successfully deployed the containers that you specified in your hvps-config.yaml configuration file: "Image": "myrepo:latest", "Names": [ "MyContainerName-10001" ], "State": "Running", "Image": "myrepo:latest", "Names": [ "MyContainerName-10002" ], "State": "Running", "Image": "myrepo:latest", "Names": [ "MyContainerName-10003" ], "State": "Running", Because three container instances are used in this example, the name is MyContainerName, and the vs_index is 10000. The container names are: – MyContainerName-10001 – MyContainerName-10002 – MyContainerName-10003

Chapter 7. IBM Hyper Protect Virtual Servers key features 225 226 Securing Your Critical Workloads with IBM Hyper Protect Services 8

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services

This chapter covers the Secure Bitcoin Wallet use case that uses multiple Hyper Protect services.

The popularity of digital asset investment is on the rise. With more than 20% of institutional investors already exposed and many more exploring this new investment class, the safekeeping or custody of these assets became a critical aspect of the business.

CNBC reported that $1.1 billion USD worth of cryptocurrency was stolen in just the first half of 20181. Many hacks were due to insider attacks in which a system administrator was compromised or socially engineered to perform malicious actions.

According to Unbound Tech, a rogue insider was the reason behind Bithumb’s third hack in two years during which $20 million USD worth of crypto currencies were stolen2. Another popular attack is to target the crypto currency exchange or digital asset service provider directly. These companies must use multiple security practices and security technologies to safeguard their clients’ assets.

IBM LinuxONE with Hyper Protect Services offers a unique platform for digital asset service providers. With Hyper Protect Virtual Servers, clients have a secure enclave that protects against insider attacks and offers pervasive encryption at rest and in-flight.

With Hyper Protect Crypto Services, clients have FIPS 140-2 level 4 Hardware Security Modules that provide key management and an application programming interface to use for encryption of keystores, wallets, and application data. The Hyper Protect Virtual Server on-premises offering also provides a secure build process to ensure that the image that is deployed to the Hyper Protect Virtual Servers instance is signed and validated by authorized parties.

As a demonstration of some of these capabilities, IBM Research™ ported over a version of the popular Bitcoin Wallet called Electrum over to the s390x architecture. The Secure Bitcoin Wallet runs inside a Hyper Protect Virtual Servers and encrypts the wallet file by using the Hyper Protect Crypto Service to protect the encryption key.

The Secure Bitcoin Wallet GitHub repository is available at this web page.

The repository readme file discusses the Wallet code pattern in more detail and includes an architectural diagram of the components.

This section reviews the steps to deploy the Secure Bitcoin Wallet to a Hyper Protect Virtual Servers instance running in the cloud that accesses a Hyper Protect Crypto Service that also is running in the cloud.

The Secure Bitcoin Wallet repository is constantly being updated with new features. Review the repo often to get the latest code.

Note: The Secure Bitcoin Wallet is a demonstration code pattern. It connects to a Bitcoin Testnet, which is a test network and not the real Bitcoin network. The Bitcoin Testnet is used by developers to send and receive Bitcoins for testing purposes; therefore, the crypto currencies that are traded have no real value.

1 https://www.cnbc.com/2018/06/07/1-point-1b-in-cryptocurrency-was-stolen-this-year-and-it-was-easy-to -do.html 2 https://www.unboundtech.com/crypto-hacks-the-rise-of-the-rogue-insider/

228 Securing Your Critical Workloads with IBM Hyper Protect Services 8.1.1 Procure Hyper Protect Services in the IBM Cloud

First, procure the appropriate services in the IBM Cloud to host the Secure Bitcoin Wallet. You need a Hyper Protect Virtual Servers instance and a Hyper Protect Crypto Service instance.

For more information, see 4.3, “Public Cloud service instantiation” on page 121 to procure a Hyper Protect Virtual Servers instance running in the IBM Cloud.

For more information about instantiating a Hyper Protect Crypto Service instance, see 2.2, “Creating an instance of Hyper Protect Crypto Services on the public IBM Cloud” on page 30.

You must have the EP11 endpoint URL and Port number to run the Secure Bitcoin Wallet.

8.1.2 Logging in to your Hyper Protect Virtual Server and cloning the code repository

SSH into your Hyper Protect Virtual Servers instance by using your assigned public IP and your passphrase for your key if you set one up. If you did not set up a passphrase for your RSA key, you are logged in immediately without being prompted to enter one. Clone the Secure Bitcoin Wallet GitHub repository. The exact git command that is needed is shown in Example 8-1.

Example 8-1 Logging in to Hyper Protect Virtual Server and cloning the GitHub code repository $ ssh [email protected] Enter passphrase for key '/Users/newuser/.ssh/id_rsa': Welcome to Ubuntu 18.04.3 LTS (GNU/Linux 4.15.0-55-generic s390x)

* Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage

* Overheard at KubeCon: "microk8s.status just blew my mind".

https://microk8s.io/docs/commands#microk8s.status Last login: Thu Dec 19 17:53:23 2019 from 47.18.17.156 root@cc648b49b9d7:~#git clone https://github.com/IBM/secure-bitcoin-wallet.git Cloning into 'secure-bitcoin-wallet'... remote: Enumerating objects: 108, done. remote: Counting objects: 100% (108/108), done. remote: Compressing objects: 100% (73/73), done. remote: Total 311 (delta 53), reused 72 (delta 32), pack-reused 203 Receiving objects: 100% (311/311), 706.75 KiB | 6.79 MiB/s, done. Resolving deltas: 100% (144/144), done.

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services 229 8.1.3 Building the wallet docker image

Browse to the secure-bitcoin-wallet directory, check out the monolithic-multistage branch, and build your docker image. The build stage can take up to 30 minutes to complete because the process is a multi-stage Docker build that requires pulling down other Docker images and building many prerequisite packages (see Example 8-2).

Example 8-2 Building the Secure Bitcoin Wallet docker image root@cc648b49b9d7:~# ls secure-bitcoin-wallet root@cc648b49b9d7:~# cd secure-bitcoin-wallet root@cc648b49b9d7:~/secure-bitcoin-wallet# git checkout monolithic-multistage Branch 'monolithic-multistage' set up to track remote branch 'monolithic-multistage' from 'origin'. Switched to a new branch 'monolithic-multistage' root@cc648b49b9d7:~/secure-bitcoin-wallet# docker build -t secure-bitcoin-wallet ...... Successfully tagged secure-bitcoin-wallet:latest

Take care to place the period after the Docker build command. The output of the build command is not shown here. You see a stream of output as the Docker build progresses through this multi-stage build process.

After the build process completes, you see secure-bitcoin-wallet listed in your docker images output, as shown in Example 8-3.

Example 8-3 Output of docker images root@cc648b49b9d7:~# docker images REPOSITORY TAG IMAGE ID CREATED SIZE secure-bitcoin-wallet latest 6ed1f7db64f9 2 hours ago 1.47GB 799456bdd3fe 5 weeks ago 1.47GB python 3.7-slim-stretch 07d2600aaf3f 2 months ago 160MB node 10.16.0-stretch-slim dcdc4bb90cb0 5 months ago 156MB

8.1.4 Running the wallet container

Now that you built the wallet image, you can run the container and access the application by using a browser. First, set up the following environment variables as shown in Example 8-4.

Example 8-4 Environment variables to set before running wallet container $ WALLET_VOLUME= (e.g. alice) $ WALLET_USER= (e.g. demo0) $ PORT= $ ZHSM= (optional)

230 Securing Your Critical Workloads with IBM Hyper Protect Services Example 8-5 shows these environment variables set inside a Hyper Protect Virtual Servers container, with the ZHSM set to a Hyper Protect Crypto Service EP11 server address.

Example 8-5 Example environment variables root@cc648b49b9d7:~# WALLET_VOLUME=alice root@cc648b49b9d7:~# WALLET_USER=demo0 root@cc648b49b9d7:~# PORT=8443 root@cc648b49b9d7:~# ZHSM=ep11.us-south.hs-crypto.cloud.ibm.com:8367

Now, you are ready to run the wallet container. Use the command that is shown in Example 8-6 to start it. Then, run the docker ps command to confirm that the container is running.

Example 8-6 Running the wallet container and verifying that it started root@cc648b49b9d7:~# docker run -d -v ${WALLET_VOLUME}:/data -p ${PORT}:443 -e ZHSM=${ZHSM} --name ${WALLET_USER}-${WALLET_VOLUME}-wallet secure-bitcoin-wallet 997faaa320a49a8738df91480585ea1ea9027bf7e2d144af7e86691dd7bab8e8 root@cc648b49b9d7:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 997faaa320a4 secure-bitcoin-wallet "./entrypoint.sh" 7 seconds ago Up 5 seconds 0.0.0.0:8443->443/tcp demo0--wallet

8.1.5 Using and testing the wallet

Complete the following steps to use a web browser to access the Electrum wallet: 1. Access https://hostname:port/electrum from a browser with the port number that is specified for the container. For example, the environment variable PORT is set to 8443 in 8.1.4, “Running the wallet container” on page 230; therefore, point your browser to https://:8443/electrum. 2. Accept a warning to use a self-signed certificate. Then, you see the Electrum wallet page, as shown in Figure 8-1.

Figure 8-1 Login page of Electrum wallet

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services 231 3. Select Register and register a user as shown in Figure 8-2.

Figure 8-2 Register a user to the Electrum wallet

4. After you click Register, you are automatically logged on as Alice or the user that you registered as, and you see a window that is similar the example that is shown in Figure 8-3.

Figure 8-3 User’s log in view

5. Click the Wallet tab and you see the window that is shown in Figure 8-4 on page 233. Enter a Wallet password and leave the Seed field blank. Then, click Create wallet. After a few seconds, you see the following message: Your wallet created! Please load your wallet after recording your seed. You also see that the seed field is populated now. Record your seed value.

232 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 8-4 Your wallet was created view

Note: You can also choose to create a Multisig wallet (multi-signature wallet), which allows another person to cosign the wallet along with you. You need your cosigner’s public certificate to create this type of wallet.

6. After you recorded your seed information, click Load wallet. You see the window that is shown in Figure 8-5.

Figure 8-5 Wallet loaded

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services 233 7. Reload the wallet on your browser, wait a few seconds and then, your test wallet is displayed, as shown in Figure 8-6.

Figure 8-6 Wallet home page

8. Go to the Receive tab of the wallet, and copy the receiving address. In the example that is shown in Figure 8-7, the receiving address is: myBQabMFy528pr9Se4JJppszhFhjTWRed1.

Figure 8-7 Copy the wallet’s receiving address

9. Use a Bitcoin testnet faucet, such as to test receiving and sending Bitcoin to the testnet: https://bitcoinfaucet.uo1.net/send.php. 10.Paste your wallet’s receiving address into the Bitcoin address box, as shown in Figure 1-8. Enter the amount of Bitcoin you want to send from the testnet to your wallet, and click Send testnet bitcoins (see Figure 8-8 on page 235).

234 Securing Your Critical Workloads with IBM Hyper Protect Services Figure 8-8 Bitcoin testnet to test receiving and sending Bitcoin to the test network

11.Return to the test wallet view and go to the History tab. You see that the transaction is in the test wallet, as shown in Figure 8-9.

Figure 8-9 Wallet History view to see receive transaction

12.After waiting a few minutes, you see a green check mark next to the transaction, which indicates that the transaction was committed to the Bitcoin Testnet (see Figure 8-10).

Figure 8-10 Wallet History view to see committed receive transaction

13.You also see the previous transaction in the transaction history on the Bitcoin Testnet Faucet page: https://bitcoinfaucet.uo1.net/send.php.

Figure 8-11 Testnet Faucet transaction history showing send transaction

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services 235 14.Test sending the money back to the address at the Bitcoin Testnet page. The Testnet address that is listed on the web page (https://bitcoinfaucet.uo1.net/send.php) is 2NGZrVvZG92qGYqzTLjCAewvPZ7JE8S8VxE. As shown in the example in Figure 8-12, paste that address in the Destination address field, enter the wallet password that was set when the wallet was registered, and click Max to return everything in the wallet. You see that it is only returning 0.00009734 Bitcoins because a small transaction fee was deducted when the wallet received the Bitcoin.

Figure 8-12 Send Bitcoin to Testnet address

15.After you click Send, you see that the Partial transaction and Signed transaction fields are populated, as shown in Figure 8-13.

Figure 8-13 Sent Bitcoin to Testnet address

236 Securing Your Critical Workloads with IBM Hyper Protect Services 16.Return to the Testnet web page. In the transaction history section, you see a green box that indicates that a receive transaction is pending (see Figure 8-14).

Figure 8-14 Testnet page transaction history displays receive transaction pending

17.In your wallet history, another transaction is displayed that indicates that the send action is pending, as shown in Figure 8-15.

Figure 8-15 Wallet transaction history showing send transaction pending

18.After waiting approximately 1 minute, refresh the Wallet and you see that the send transaction completed (see Figure 8-16).

Figure 8-16 Wallet history view showing completed send transaction

What keeps the wallet secure is that administrators of the Hyper Protect Virtual Servers instance cannot see the transactions, they do not have SSH access to the instance (only you do), and even when they take a memory dump, the dump is encrypted.

The wallet is also encrypted by using a key that is wrapped by a root key that is protected by the Hyper Protect Crypto Service, which is FIPS 140-2 Level 4 compliant.

For more information about these services, see Chapter 2, “IBM Cloud Hyper Protect Crypto Services” on page 29, and Chapter 3, “IBM Cloud Hyper Protect DBaaS” on page 95.

Chapter 8. Secure Bitcoin Wallet: A sample use case that spans multiple IBM Hyper Protect services 237 238 Securing Your Critical Workloads with IBM Hyper Protect Services A

Appendix A. Additional material

This book refers to additional material that can be downloaded from the internet as described in the following sections.

Locating the GitHub material

The web material that is associated with this book is available in softcopy on the internet from the IBM Redbooks GitHub web page:

https://github.com/IBMRedbooks/SG248469-Securing-your-critical-workloads-with-IBM- Hyper-Protect-Services

Cloning the GitHub material

Complete the following steps to clone the GitHub repository for this book: 1. Download and install Git client if not installed from this web page. 2. Run the following command to clone the GitHub repository: git clone https://github.com/IBMRedbooks/SG248469-Securing-your-critical-workloads-with-I BM-Hyper-Protect-Services.git.

The publications that are listed in this section are considered particularly suitable for a more detailed discussion of the topics that are covered in this book.

IBM Redbooks

The IBM Redbooks publications Implementation Guide for IBM Blockchain Platform for Multicloud, SG24-8458, provides more information about the topic in this document. Note that this publication might be available in softcopy only.

You can search for, view, download, or order this documents and other Redbooks, Redpapers, Web Docs, draft, and additional materials, at the following website: ibm.com/redbooks

Online resources

The following websites are also relevant as further information sources: IBM Hyper Protect Virtual Servers v1.2.0 documentation: https://www.ibm.com/support/knowledgecenter/SSHPMH_1.2.0/kc_welcome_page.html Official FIPS 140-2 specification: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.140-2.pdf IBM Cloud console: https://cloud.ibm.com Creating a root key with the Hyper Protect Crypto Services GUI: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-create-root-keys# root-key-gui Creating a root key with the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-create-root-keys# root-key-api Creating a standard key with the Hyper Protect Crypto Services GUI: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-create-standard-k eys#standard-key-gui Creating a standard key with the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-create-standard-k eys#create-standard-key-api Wrapping a standard key with the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-wrap-keys#wrap-ke ys-api

© Copyright IBM Corp. 2020. All rights reserved. 241 Unwrapping a standard key with the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-wrap-keys#wrap-ke ys-api Importing a root key with the Hyper Protect Crypto Services GUI: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-import-root-keys# import-root-key-gui Importing a root key with the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-import-root-keys# import-root-key-api Importing a standard key with the Hyper Protect Crypto Services GUI: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-import-standard-k eys#import-standard-key-gui Importing a standard key with the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-import-standard-k eys#import-standard-key-api Listing all keys from the Hyper Protect Crypto Services GUI: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-view-keys#view-ke y-gui Listing all keys from the Key Management API: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-view-keys#retriev e-keys-api GREP11 API reference: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-grep11-api-ref GREP11 sample code for the Go language: https://cloud.ibm.com/docs/services/hs-crypto?topic=hs-crypto-grep11-api-ref#co de-example To set up Go tools: https://golang.org/doc/install To set up your Go workspace: https://golang.org/doc/code.html#Workspaces The IAM endpoint for IBM Cloud: https://iam.cloud.ibm.com Hyper Protect Crypto Services tutorials: https://cloud.ibm.com/docs/services/hs-crypto Secure Service Container for IBM Cloud Private installation: https://www.ibm.com/support/knowledgecenter/SSUPZ7_1.1.0/topics/install_ssc4icp .html

242 Securing Your Critical Workloads with IBM Hyper Protect Services Help from IBM

IBM Support and downloads ibm.com/support

IBM Global Services ibm.com/services

Related publications 243 244 Securing Your Critical Workloads with IBM Hyper Protect Services Securing Your Critical Workloads with IBM Hyper Protect Services (0.2”spine) 0.17”<->0.473” 90<->249 pages

Back cover

SG24-8469-00

0738458619

Printed in U.S.A.

® ibm.com/redbooks