AWS CloudHSM User Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 297 [warning: Documents this large are best viewed by clicking the View PDF Link!]

AWS CloudHSM
User Guide
AWS CloudHSM User Guide
AWS CloudHSM: User Guide
Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
AWS CloudHSM User Guide
Table of Contents
What Is AWS CloudHSM? .................................................................................................................... 1
Use Cases .................................................................................................................................. 1
Ooad the SSL/TLS Processing for Web Servers ................................................................... 1
Protect the Private Keys for an Issuing Certificate Authority (CA) .............................................. 2
Enable Transparent Data Encryption (TDE) for Oracle Databases .............................................. 2
Clusters ..................................................................................................................................... 2
Cluster Architecture ............................................................................................................ 3
Cluster Synchronization ...................................................................................................... 4
Cluster High Availability and Load Balancing ......................................................................... 5
Backups .................................................................................................................................... 6
Overview of Backups .......................................................................................................... 6
Security of Backups ............................................................................................................ 7
Durability of Backups ......................................................................................................... 8
Frequency of Backups ......................................................................................................... 8
Client Tools and Libraries ............................................................................................................ 8
AWS CloudHSM Client ........................................................................................................ 9
AWS CloudHSM Command Line Tools ................................................................................. 10
AWS CloudHSM Software Libraries ..................................................................................... 10
HSM Users ............................................................................................................................... 10
Precrypto Ocer (PRECO) ................................................................................................. 11
Crypto Ocer (CO) ........................................................................................................... 11
Crypto User (CU) .............................................................................................................. 11
Appliance User (AU) .......................................................................................................... 11
HSM User Permissions Table .............................................................................................. 11
Compliance .............................................................................................................................. 12
Pricing .................................................................................................................................... 13
Regions ................................................................................................................................... 13
Limits ..................................................................................................................................... 13
Getting Started ................................................................................................................................ 15
Create IAM Administrators ......................................................................................................... 15
Create an IAM User and Administrator Group ....................................................................... 16
Restrict User Permissions to What's Necessary for AWS CloudHSM .......................................... 17
Understanding Service-Linked Roles ................................................................................... 19
Create a VPC ........................................................................................................................... 20
Create a Private Subnet ............................................................................................................ 21
Create a Cluster ....................................................................................................................... 21
Launch an EC2 Client ................................................................................................................ 23
Launch an EC2 Client ........................................................................................................ 23
Create an HSM ......................................................................................................................... 24
Verify HSM Identity (Optional) ................................................................................................... 25
Overview ......................................................................................................................... 25
Get Certicates from the HSM ........................................................................................... 27
Get the Root Certicates ................................................................................................... 28
Verify Certicate Chains .................................................................................................... 29
Extract and Compare Public Keys ....................................................................................... 30
AWS CloudHSM Root Certicate ......................................................................................... 30
Initialize the Cluster .................................................................................................................. 31
Get the Cluster CSR .......................................................................................................... 32
Sign the CSR ................................................................................................................... 33
Initialize the Cluster .......................................................................................................... 34
Install the Client (Linux) ............................................................................................................ 35
Install the AWS CloudHSM Client and Command Line Tools ................................................... 35
Edit the Client Conguration ............................................................................................. 37
Install the Client (Windows) ....................................................................................................... 37
iii
AWS CloudHSM User Guide
Activate the Cluster .................................................................................................................. 38
Recongure SSL (Optional) ........................................................................................................ 40
Managing Clusters ............................................................................................................................ 42
Adding or Removing HSMs ........................................................................................................ 42
Adding an HSM ................................................................................................................ 42
Removing an HSM ............................................................................................................ 44
Copying a Backup Across Regions ............................................................................................... 45
Creating a Cluster From a Backup .............................................................................................. 46
Deleting and Restoring a Backup ................................................................................................ 47
Deleting a Cluster .................................................................................................................... 48
Tagging Resources .................................................................................................................... 49
Adding or Updating Tags .................................................................................................. 50
Listing Tags ..................................................................................................................... 51
Removing Tags ................................................................................................................. 52
Managing HSM Users and Keys .......................................................................................................... 53
Managing HSM Users ................................................................................................................ 53
Create Users .................................................................................................................... 53
List Users ........................................................................................................................ 54
Change a User's Password ................................................................................................. 55
Delete Users .................................................................................................................... 55
Managing Keys ......................................................................................................................... 56
Generate Keys .................................................................................................................. 56
Import Keys ..................................................................................................................... 57
Export Keys ..................................................................................................................... 59
Delete Keys ..................................................................................................................... 60
Share and Unshare Keys .................................................................................................... 60
Quorum Authentication (M of N) ................................................................................................ 61
Overview of Quorum Authentication .................................................................................. 61
Additional Details about Quorum Authentication .................................................................. 62
First Time Setup for Crypto Ocers ................................................................................... 62
Quorum Authentication for Crypto Ocers ......................................................................... 66
Change the Quorum Value for Crypto Ocers ..................................................................... 72
Command Line Tools ........................................................................................................................ 74
cloudhsm_mgmt_util ................................................................................................................ 74
Getting Started ................................................................................................................ 75
Reference ........................................................................................................................ 80
key_mgmt_util ....................................................................................................................... 119
Getting Started .............................................................................................................. 119
Reference ...................................................................................................................... 122
Congure Tool ....................................................................................................................... 179
Syntax ........................................................................................................................... 179
Examples ....................................................................................................................... 179
Parameters .................................................................................................................... 180
Related Topics ................................................................................................................ 182
Using the Software Libraries ............................................................................................................ 183
PKCS #11 Library ................................................................................................................... 183
Installing the PKCS #11 Library ........................................................................................ 183
Authenticating to PKCS #11 ............................................................................................. 188
Supported PKCS #11 Key Types ....................................................................................... 189
Supported PKCS #11 Mechanisms ..................................................................................... 189
Supported PKCS #11 API operations ................................................................................. 190
OpenSSL Dynamic Engine ........................................................................................................ 192
Installing the OpenSSL Dynamic Engine ............................................................................ 192
Java Library ........................................................................................................................... 194
Installing the Java Library ............................................................................................... 195
Supported Mechanisms ................................................................................................... 199
Sample Prerequisites ....................................................................................................... 202
iv
AWS CloudHSM User Guide
Java Samples ................................................................................................................. 202
KSP and CNG Providers ........................................................................................................... 203
Install the Providers ........................................................................................................ 203
Prerequisites .................................................................................................................. 204
Code Sample ................................................................................................................. 204
Integrating Third-Party Applications ................................................................................................. 209
SSL/TLS Ooad ..................................................................................................................... 209
How It Works ................................................................................................................. 209
SSL/TLS Ooad on Linux ............................................................................................... 210
SSL/TLS Ooad on Windows .......................................................................................... 224
Windows Server CA ................................................................................................................ 236
Set Up Prerequisites ....................................................................................................... 236
Create Windows Server CA .............................................................................................. 237
Sign a CSR ..................................................................................................................... 238
Oracle Database Encryption ..................................................................................................... 239
Set Up Prerequisites ....................................................................................................... 240
Congure the Database ................................................................................................... 241
Monitoring Logs ............................................................................................................................. 244
Getting Client Logs ................................................................................................................. 244
Logging AWS CloudHSM API Calls with AWS CloudTrail ............................................................... 245
AWS CloudHSM Information in CloudTrail .......................................................................... 245
Understanding AWS CloudHSM Log File Entries .................................................................. 246
Monitoring Audit Logs ............................................................................................................ 247
How Audit Logging Works ............................................................................................... 247
Viewing Audit Logs in CloudWatch Logs ............................................................................ 248
Interpreting HSM Audit Logs ............................................................................................ 250
Audit Log Reference ....................................................................................................... 260
Getting Metrics .............................................................................................................................. 262
Getting CloudWatch Metrics ..................................................................................................... 262
Troubleshooting ............................................................................................................................. 263
Known Issues ......................................................................................................................... 263
Known Issues for all HSM instances .................................................................................. 263
Known Issues for Amazon EC2 Instances Running Amazon Linux 2 ........................................ 265
Known Issues for the PKCS #11 SDK ................................................................................. 265
Known Issues for the JCE SDK .......................................................................................... 267
Known Issues for the OpenSSL SDK .................................................................................. 267
Lost Connection ..................................................................................................................... 268
Keep HSM Users In Sync .......................................................................................................... 270
Verify Performance ................................................................................................................. 270
Resolving Cluster Creation Failures ........................................................................................... 273
Add the Missing Permission ............................................................................................. 274
Create the Service-Linked Role Manually ........................................................................... 274
Use a Nonfederated User ................................................................................................ 274
Missing AWS CloudHSM Audit Logs in CloudWatch ..................................................................... 275
Client and Software Information ...................................................................................................... 276
Version History ....................................................................................................................... 276
Current Version: 1.1.2 ..................................................................................................... 276
Version: 1.1.1 ................................................................................................................. 278
Version: 1.1.0 ................................................................................................................. 281
Version: 1.0.18 ............................................................................................................... 283
Version 1.0.14 ................................................................................................................ 285
Version 1.0.11 ................................................................................................................ 285
Version 1.0.10 ................................................................................................................ 286
Version 1.0.8 .................................................................................................................. 286
Version 1.0.7 .................................................................................................................. 287
Version 1.0.0 .................................................................................................................. 287
Supported Platforms ............................................................................................................... 287
v
AWS CloudHSM User Guide
Document History .......................................................................................................................... 290
vi
AWS CloudHSM User Guide
Use Cases
What Is AWS CloudHSM?
AWS CloudHSM provides hardware security modules in the AWS Cloud. A hardware security module
(HSM) is a computing device that processes cryptographic operations and provides secure storage for
cryptographic keys.
When you use an HSM from AWS CloudHSM, you can perform a variety of cryptographic tasks:
Generate, store, import, export, and manage cryptographic keys, including symmetric keys and
asymmetric key pairs.
Use symmetric and asymmetric algorithms to encrypt and decrypt data.
Use cryptographic hash functions to compute message digests and hash-based message
authentication codes (HMACs).
Cryptographically sign data (including code signing) and verify signatures.
Generate cryptographically secure random data.
If you want a managed service for creating and controlling your encryption keys, but you don't want or
need to operate your own HSM, consider using AWS Key Management Service.
To learn more about what you can do with AWS CloudHSM, see the following topics. When you are ready
to get started with AWS CloudHSM, see Getting Started (p. 15).
Topics
AWS CloudHSM Use Cases (p. 1)
AWS CloudHSM Clusters (p. 2)
AWS CloudHSM Cluster Backups (p. 6)
AWS CloudHSM Client Tools and Software Libraries (p. 8)
HSM Users (p. 10)
Compliance (p. 12)
Pricing (p. 13)
Regions (p. 13)
AWS CloudHSM Limits (p. 13)
AWS CloudHSM Use Cases
A hardware security module (HSM) in AWS CloudHSM can help you accomplish a variety of goals.
Topics
Offload the SSL/TLS Processing for Web Servers (p. 1)
Protect the Private Keys for an Issuing Certificate Authority (CA) (p. 2)
Enable Transparent Data Encryption (TDE) for Oracle Databases (p. 2)
Offload the SSL/TLS Processing for Web Servers
Web servers and their clients (web browsers) can use Secure Sockets Layer (SSL) or Transport Layer
Security (TLS). These protocols confirm the identity of the web server and establish a secure connection
1
AWS CloudHSM User Guide
Protect the Private Keys for an
Issuing Certificate Authority (CA)
to send and receive webpages or other data over the internet. This is commonly known as HTTPS.
The web server uses a public–private key pair and an SSL/TLS public key certificate to establish an
HTTPS session with each client. This process involves a lot of computation for the web server, but you
can offload some of this to the HSMs in your AWS CloudHSM cluster. This is sometimes known as SSL
acceleration. Offloading reduces the computational burden on your web server and provides extra
security by storing the server's private key in the HSMs.
For information about setting up SSL/TLS offload with AWS CloudHSM, see SSL/TLS Offload (p. 209).
Protect the Private Keys for an Issuing Certificate
Authority (CA)
In a public key infrastructure (PKI), a certificate authority (CA) is a trusted entity that issues digital
certificates. These digital certificates bind a public key to an identity (a person or organization) by means
of public key cryptography and digital signatures. To operate a CA, you must maintain trust by protecting
the private key that signs the certificates issued by your CA. You can store the private key in the HSM in
your AWS CloudHSM cluster, and use the HSM to perform the cryptographic signing operations.
Enable Transparent Data Encryption (TDE) for Oracle
Databases
Some versions of Oracle's database software offer a feature called Transparent Data Encryption (TDE).
With TDE, the database software encrypts data before storing it on disk. The data in the database's table
columns or tablespaces is encrypted with a table key or tablespace key. These keys are encrypted with
the TDE master encryption key. You can store the TDE master encryption key in the HSMs in your AWS
CloudHSM cluster, which provides additional security.
For information about setting up Oracle TDE with AWS CloudHSM, see Oracle Database
Encryption (p. 239).
AWS CloudHSM Clusters
AWS CloudHSM provides hardware security modules (HSMs) in a cluster. A cluster is a collection of
individual HSMs that AWS CloudHSM keeps in sync. You can think of a cluster as one logical HSM. When
you perform a task or operation on one HSM in a cluster, the other HSMs in that cluster are automatically
kept up to date.
You can create a cluster that has from 1 to 28 HSMs (the default limit (p. 13) is 6 HSMs per AWS
account per AWS Region). You can place the HSMs in different Availability Zones in an AWS Region.
Adding more HSMs to a cluster provides higher performance. Spreading clusters across Availability Zones
provides redundancy and high availability.
Making individual HSMs work together in a synchronized, redundant, highly available cluster can be
difficult, but AWS CloudHSM does some of the undifferentiated heavy lifting for you. You can add and
remove HSMs in a cluster and let AWS CloudHSM keep the HSMs connected and in sync for you.
To create a cluster, see Getting Started (p. 15).
For more information about clusters, see the following topics.
Topics
Cluster Architecture (p. 3)
2
AWS CloudHSM User Guide
Cluster Architecture
Cluster Synchronization (p. 4)
Cluster High Availability and Load Balancing (p. 5)
Cluster Architecture
When you create a cluster, you specify an Amazon Virtual Private Cloud (VPC) in your AWS account and
one or more subnets in that VPC. We recommend that you create one subnet in each Availability Zone
(AZ) in your chosen AWS Region. To learn how, see Create a Private Subnet (p. 21).
Each time you create an HSM, you specify the cluster and Availability Zone for the HSM. By putting the
HSMs in different Availability Zones, you achieve redundancy and high availability in case one Availability
Zone is unavailable.
When you create an HSM, AWS CloudHSM puts an elastic network interface (ENI) in the specified subnet
in your AWS account. The elastic network interface is the interface for interacting with the HSM. The
HSM resides in a separate VPC in an AWS account that is owned by AWS CloudHSM. The HSM and its
corresponding network interface are in the same Availability Zone.
To interact with the HSMs in a cluster, you need the AWS CloudHSM client software. Typically you install
the client on Amazon EC2 instances, known as client instances, that reside in the same VPC as the HSM
ENIs, as shown in the following figure. That's not technically required though; you can install the client
on any compatible computer, as long as it can connect to the HSM ENIs. The client communicates with
the individual HSMs in your cluster through their ENIs.
The following figure represents an AWS CloudHSM cluster with three HSMs, each in a different
Availability Zone in the VPC.
3
AWS CloudHSM User Guide
Cluster Synchronization
Cluster Synchronization
In an AWS CloudHSM cluster, AWS CloudHSM keeps the keys on the individual HSMs in sync. You don't
need to do anything to synchronize the keys on your HSMs. To keep the users and policies on each HSM
in sync, update the AWS CloudHSM client configuration file before you manage HSM users (p. 53). For
more information, see Keep HSM Users In Sync (p. 270).
4
AWS CloudHSM User Guide
Cluster High Availability and Load Balancing
When you add a new HSM to a cluster, AWS CloudHSM makes a backup of all keys, users, and policies on
an existing HSM. It then restores that backup onto the new HSM. This keeps the two HSMs in sync.
If the HSMs in a cluster fall out of synchronization, AWS CloudHSM automatically resynchronizes them.
To enable this, AWS CloudHSM uses the credentials of the appliance user (p. 10). This user exists on all
HSMs provided by AWS CloudHSM and has limited permissions. It can get a hash of objects on the HSM
and can extract and insert masked (encrypted) objects. AWS cannot view or modify your users or keys
and cannot perform any cryptographic operations using those keys.
Cluster High Availability and Load Balancing
When you create an AWS CloudHSM cluster with more than one HSM, you automatically get load
balancing. Load balancing means that the AWS CloudHSM client (p. 8) distributes cryptographic
operations across all HSMs in the cluster based on each HSM's capacity for additional processing.
When you create the HSMs in different AWS Availability Zones, you automatically get high availability.
High availability means that you get higher reliability because no individual HSM is a single point
of failure. We recommend that you have a minimum of two HSMs in each cluster, with each HSM in
different Availability Zones within an AWS Region.
For example, the following figure shows an Oracle database application that is distributed to two
different Availability Zones. The database instances store their master keys in a cluster that includes an
HSM in each Availability Zone. AWS CloudHSM automatically synchronizes the keys to both HSMs so that
they are immediately accessible and redundant.
5
AWS CloudHSM User Guide
Backups
AWS CloudHSM Cluster Backups
AWS CloudHSM makes periodic backups of your cluster. You can't instruct AWS CloudHSM to make
backups anytime that you want, but you can take certain actions that result in AWS CloudHSM making a
backup. For more information, see the following topics.
When you add an HSM to a cluster that previously contained one or more active HSMs, AWS CloudHSM
restores the most recent backup onto the new HSM. This means that you can use AWS CloudHSM to
manage an HSM that you use infrequently. When you don't need to use the HSM, you can delete it, which
triggers a backup. Later, when you need to use the HSM again, you can create a new HSM in the same
cluster, effectively restoring your previous HSM.
You can also create a new cluster from an existing backup of a different cluster. You must create the new
cluster in the same AWS Region that contains the existing backup.
Topics
Overview of Backups (p. 6)
Security of Backups (p. 7)
Durability of Backups (p. 8)
Frequency of Backups (p. 8)
Overview of Backups
Each backup contains encrypted copies of the following data:
All users (COs, CUs, and AUs) (p. 10) on the HSM.
All key material and certificates on the HSM.
The HSM's configuration and policies.
AWS CloudHSM stores the backups in a service-controlled Amazon Simple Storage Service (Amazon S3)
bucket in the same AWS Region as your cluster.
6
AWS CloudHSM User Guide
Security of Backups
Security of Backups
When AWS CloudHSM makes a backup from the HSM, the HSM encrypts all of its data before sending it
to AWS CloudHSM. The data never leaves the HSM in plaintext form.
To encrypt its data, the HSM uses a unique, ephemeral encryption key known as the ephemeral backup
key (EBK). The EBK is an AES 256-bit encryption key generated inside the HSM when AWS CloudHSM
makes a backup. The HSM generates the EBK, then uses it to encrypt the HSM's data with a FIPS-
approved AES key wrapping method that complies with NIST special publication 800-38F. Then the HSM
gives the encrypted data to AWS CloudHSM. The encrypted data includes an encrypted copy of the EBK.
To encrypt the EBK, the HSM uses another encryption key known as the persistent backup key (PBK).
The PBK is also an AES 256-bit encryption key. To generate the PBK, the HSM uses a FIPS-approved key
derivation function (KDF) in counter mode that complies with NIST special publication 800-108. The
inputs to this KDF include the following:
A manufacturer key backup key (MKBK), permanently embedded in the HSM hardware by the hardware
manufacturer.
An AWS key backup key (AKBK), securely installed in the HSM when it's initially configured by AWS
CloudHSM.
The encryption processes are summarized in the following figure. The backup encryption key represents
the persistent backup key (PBK) and the ephemeral backup key (EBK).
7
AWS CloudHSM User Guide
Durability of Backups
AWS CloudHSM can restore backups onto only AWS-owned HSMs made by the same manufacturer.
Because each backup contains all users, keys, and configuration from the original HSM, the restored HSM
contains the same protections and access controls as the original. The restored data overwrites all other
data that might have been on the HSM prior to restoration.
A backup consists of only encrypted data. Before each backup is stored in Amazon S3, it's encrypted
again under an AWS Key Management Service (AWS KMS) customer master key (CMK).
Durability of Backups
AWS CloudHSM stores cluster backups in an Amazon S3 bucket in an AWS account that AWS CloudHSM
controls. The durability of backups is the same as any object stored in Amazon S3. Amazon S3 is
designed to deliver 99.999999999% durability.
Frequency of Backups
AWS CloudHSM makes a cluster backup at least once per 24 hours. In addition to recurring daily backups,
AWS CloudHSM makes a backup when you perform any of the following actions:
Initialize the cluster (p. 31).
Add an HSM to an initialized cluster (p. 42).
Remove an HSM from a cluster (p. 44).
AWS CloudHSM Client Tools and Software
Libraries
To manage and use the HSMs in your cluster, you use the AWS CloudHSM client software. The client
software includes several components, as described in the following topics.
Topics
AWS CloudHSM Client (p. 9)
AWS CloudHSM Command Line Tools (p. 10)
AWS CloudHSM Software Libraries (p. 10)
8
AWS CloudHSM User Guide
AWS CloudHSM Client
AWS CloudHSM Client
The AWS CloudHSM client is a daemon that you install and run on your application hosts. The client
establishes and maintains a secure, end-to-end encrypted connection with the HSMs in your AWS
CloudHSM cluster. The client provides the fundamental connection between your application hosts
and your HSMs. Most of the other AWS CloudHSM client software components rely on the client to
communicate with your HSMs. To get started with the AWS CloudHSM client if you are using Linux, see
Install the Client (Linux) (p. 35). If you are using Windows, see Install the Client (Windows) (p. 37).
AWS CloudHSM Client End-to-End Encryption
Communication between the AWS CloudHSM client and the HSMs in your cluster is encrypted from end
to end. Only your client and your HSMs can decrypt the communication.
The following process explains how the client establishes end-to-end encrypted communication with an
HSM.
1. Your client establishes a Transport Layer Security (TLS) connection with the server that hosts your
HSM hardware. Your cluster's security group allows inbound traffic to the server only from client
instances in the security group. The client also checks the server's certificate to ensure that it's a
trusted server.
2. Next, the client establishes an encrypted connection with the HSM hardware. The HSM has the cluster
certificate that you signed with your own certificate authority (CA), and the client has the CA's root
certificate. Before the client–HSM encrypted connection is established, the client verifies the HSM's
cluster certificate against its root certificate. The connection is established only when the client
successfully verifies that the HSM is trusted. The client–HSM encrypted connection goes through the
client–server connection established previously.
9
AWS CloudHSM User Guide
AWS CloudHSM Command Line Tools
AWS CloudHSM Command Line Tools
The AWS CloudHSM client software includes two command line tools. You use the command line tools to
manage the users and keys on the HSMs. For example, you can create HSM users, change user passwords,
create keys, and more. For information about these tools, see Command Line Tools (p. 74).
AWS CloudHSM Software Libraries
You can use the AWS CloudHSM software libraries to integrate your applications with the HSMs in your
cluster and use them for cryptoprocessing. For more information about installing and using the different
libraries, see Using the Software Libraries (p. 183).
HSM Users
Most operations that you perform on the HSM require the credentials of an HSM user. The HSM
authenticates each HSM user by means of a user name and password.
Each HSM user has a type that determines which operations the user is allowed to perform on the HSM.
The following topics explain the types of HSM users.
Topics
Precrypto Officer (PRECO) (p. 11)
Crypto Officer (CO) (p. 11)
Crypto User (CU) (p. 11)
Appliance User (AU) (p. 11)
HSM User Permissions Table (p. 11)
10
AWS CloudHSM User Guide
Precrypto Officer (PRECO)
Precrypto Officer (PRECO)
The precrypto officer (PRECO) is a temporary user that exists only on the first HSM in an AWS CloudHSM
cluster. The first HSM in a new cluster contains a PRECO user with a default user name and password.
To activate a cluster (p. 38), you log in to the HSM and change the PRECO user's password. When you
change the password, the PRECO user becomes a crypto officer (CO). The PRECO user can only change its
own password and perform read-only operations on the HSM.
Crypto Officer (CO)
A crypto officer (CO) can perform user management operations. For example, a CO can create and delete
users and change user passwords. For more information, see the HSM User Permissions Table (p. 11).
When you activate a new cluster (p. 38), the user changes from a Precrypto Officer (p. 11) (PRECO)
to a crypto officer (CO).
Crypto User (CU)
A crypto user (CU) can perform the following key management and cryptographic operations.
Key management – Create, delete, share, import, and export cryptographic keys.
Cryptographic operations – Use cryptographic keys for encryption, decryption, signing, verifying, and
more.
For more information, see the HSM User Permissions Table (p. 11).
Appliance User (AU)
The appliance user (AU) can perform cloning and synchronization operations. AWS CloudHSM uses
the AU to synchronize the HSMs in an AWS CloudHSM cluster. The AU exists on all HSMs provided by
AWS CloudHSM, and has limited permissions. For more information, see the HSM User Permissions
Table (p. 11).
AWS uses the AU to perform cloning and synchronization operations on your cluster's HSMs. AWS cannot
perform any operations on your HSMs except those granted to the AU and unauthenticated users. AWS
cannot view or modify your users or keys and cannot perform any cryptographic operations using those
keys.
HSM User Permissions Table
The following table lists HSM operations and whether each type of HSM user can perform them.
Crypto Officer
(CO)
Crypto User (CU) Appliance User
(AU)
Unauthenticated
User
Get basic cluster
info¹
Yes Yes Yes Yes
Zeroize an HSM² Yes Yes Yes Yes
Change own
password
Yes Yes Yes Not applicable
11
AWS CloudHSM User Guide
Compliance
Crypto Officer
(CO)
Crypto User (CU) Appliance User
(AU)
Unauthenticated
User
Change any user's
password
Yes No No No
Add, remove users Yes No No No
Get sync status³ Yes Yes Yes No
Extract, insert
masked objects⁴
Yes Yes Yes No
Create, share,
delete keys
No Yes No No
Encrypt, decrypt No Yes No No
Sign, verify No Yes No No
Generate digests
and HMACs
No Yes No No
¹Basic cluster information includes the number of HSMs in the cluster and each HSM's IP address, model,
serial number, device ID, firmware ID, etc.
²When an HSM is zeroized, all keys, certificates, and other data on the HSM is destroyed. You can use
your cluster's security group to prevent an unauthenticated user from zeroizing your HSM. For more
information, see Create a Cluster (p. 21).
³The user can get a set of digests (hashes) that correspond to the keys on the HSM. An application can
compare these sets of digests to understand the synchronization status of HSMs in a cluster.
⁴Masked objects are keys that are encrypted before they leave the HSM. They cannot be decrypted
outside of the HSM. They are only decrypted after they are inserted into an HSM that is in the same
cluster as the HSM from which they were extracted. An application can extract and insert masked objects
to synchronize the HSMs in a cluster.
Compliance
AWS and AWS Marketplace partners offer many solutions for protecting data in AWS. However, some
applications and data are subject to strict contractual or regulatory requirements for managing and
using cryptographic keys. Relying on a FIPS-validated HSM can help you meet corporate, contractual,
and regulatory compliance requirements for data security in the AWS Cloud. You can review the FIPS-
approved security policies for the HSMs provided by AWS CloudHSM below.
FIPS Validation for Hardware Used by CloudHSM
Certificate #3254 was issued on August 2, 2018.
Certificate #2850 was issued on February 27, 2017.
FIPS 140-2 Compliance
The Federal Information Processing Standard (FIPS) Publication 140-2 is a US government security
standard that specifies security requirements for cryptographic modules that protect sensitive
information. The HSMs provided by AWS CloudHSM comply with FIPS 140-2 level 3.
12
AWS CloudHSM User Guide
Pricing
PCI DSS Compliance
The Payment Card Industry Data Security Standard (PCI DSS) is a proprietary information security
standard administered by the PCI Security Standards Council. The HSMs provided by AWS CloudHSM
comply with PCI DSS.
Pricing
With AWS CloudHSM, you pay by the hour with no long-term commitments or upfront payments. For
more information, see AWS CloudHSM Pricing on the AWS website.
Regions
Visit AWS Regions and Endpoints in the AWS General Reference or the AWS Region Table to see the
regional and Availability Zone support for AWS CloudHSM.
Like most AWS resources, clusters and HSMs are used regionally. To create an HSM in more than one
region, you must first create a cluster in that region. You cannot reuse or extend a cluster across regions.
You must perform all the required steps listed in Getting Started with AWS CloudHSM (p. 15) to
create a new cluster in a new region.
Note
AWS CloudHSM may not be available across all Availability Zones in a given region. However,
this should not affect performance, as AWS CloudHSM automatically load balances across all
HSMs in a cluster.
AWS CloudHSM Limits
The following limits apply to your AWS CloudHSM resources per AWS Region and AWS account.
Service Limits
Item Default Limit Hard Limit
Clusters 4 N/A
HSMs 6 N/A
HSMs per cluster N/A 28
System Limits
Item Hard Limit
Keys per cluster 3500
Number of users per cluster 1024
Maximum length of a user name 31 characters
Required password length 7 to 32 characters
Maximum number of concurrent clients 1024
13
AWS CloudHSM User Guide
Limits
To request an increase in the number of clusters or HSMs, use the service limit increase form in the AWS
Support Center.
14
AWS CloudHSM User Guide
Create IAM Administrators
Getting Started with AWS CloudHSM
The following topics contain information to help you create, initialize, and activate an AWS CloudHSM
cluster. After you complete the instructions included in these topics, you'll be ready to manage users,
manage clusters, and perform cryptographic operations using the included software libraries.
To get started with AWS CloudHSM
1. Follow the steps in Create IAM Administrators (p. 15) to set up your IAM users and groups.
2. Follow the steps in Create a Cluster (p. 21).
3. Follow the steps in Create an HSM (p. 24).
4. (Optional) Follow the steps in Verify HSM Identity (Optional) (p. 25) to verify the identity and
authenticity of the cluster's HSM.
5. Follow the steps in Initialize the Cluster (p. 31).
6. (First time only) Follow the steps in Launch an EC2 Client (p. 23).
7. (First time only) Follow the steps in Install the Client (Linux) (p. 35) if you are using Linux or Install
the Client (Windows) (p. 37) if you are using Windows.
8. Follow the steps in Activate the Cluster (p. 38).
Topics
Create IAM Administrative Groups (p. 15)
Create a Virtual Private Cloud (VPC) (p. 20)
Create a Private Subnet (p. 21)
Create a Cluster (p. 21)
Launch an Amazon EC2 Client Instance (p. 23)
Create an HSM (p. 24)
Verify the Identity and Authenticity of Your Cluster's HSM (Optional) (p. 25)
Initialize the Cluster (p. 31)
Install and Configure the AWS CloudHSM Client (Linux) (p. 35)
Install and Configure the AWS CloudHSM Client (Windows) (p. 37)
Activate the Cluster (p. 38)
Reconfigure SSL with a New Certificate and Private Key (Optional) (p. 40)
Create IAM Administrative Groups
As a best practice, don't use your AWS account root user to interact with AWS, including AWS CloudHSM.
Instead, use AWS Identity and Access Management (IAM) to create an IAM user, IAM role, or federated
user. Follow the steps in the Create an IAM User and Administrator Group (p. 16) section to create an
administrator group and attach the AdministratorAccess policy to it. Then create a new administrator
user and add the user to the group. Add additional users to the group as needed. Each user you add
inherits the AdministratorAccess policy from the group.
Another best practice is to create an AWS CloudHSM administrator group that has only the permissions
required to run AWS CloudHSM. Add individual users to this group as needed. Each user inherits the
15
AWS CloudHSM User Guide
Create an IAM User and Administrator Group
limited permissions that are attached to the group rather than full AWS access. The Restrict User
Permissions to What's Necessary for AWS CloudHSM (p. 17) section that follows contains the policy
that you should attach to your AWS CloudHSM administrator group.
AWS CloudHSM defines an IAM service–linked role for your AWS account. The service–linked role
currently defines permissions that allow your account to log AWS CloudHSM events. The role can be
created automatically by AWS CloudHSM or manually by you. You cannot edit the role, but you can
delete it. For more information, see the Understanding Service-Linked Roles (p. 19) section that
follows.
Topics
Create an IAM User and Administrator Group (p. 16)
Restrict User Permissions to What's Necessary for AWS CloudHSM (p. 17)
Understanding Service-Linked Roles (p. 19)
Create an IAM User and Administrator Group
Start by creating an IAM user along with an administrator group for that user.
To create an IAM user for yourself and add the user to an Administrators group
1. Use your AWS account email address and password to sign in as the AWS account root user to the
IAM console at https://console.aws.amazon.com/iam/.
Note
We strongly recommend that you adhere to the best practice of using the Administrator
IAM user below and securely lock away the root user credentials. Sign in as the root user
only to perform a few account and service management tasks.
2. In the navigation pane of the console, choose Users, and then choose Add user.
3. For User name, type Administrator.
4. Select the check box next to AWS Management Console access, select Custom password, and then
type the new user's password in the text box. You can optionally select Require password reset to
force the user to create a new password the next time the user signs in.
5. Choose Next: Permissions.
6. On the Set permissions page, choose Add user to group.
7. Choose Create group.
8. In the Create group dialog box, for Group name type Administrators.
9. For Filter policies, select the check box for AWS managed - job function.
10. In the policy list, select the check box for AdministratorAccess. Then choose Create group.
11. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to
see the group in the list.
12. Choose Next: Review to see the list of group memberships to be added to the new user. When you
are ready to proceed, choose Create user.
You can use this same process to create more groups and users, and to give your users access to your
AWS account resources. To learn about using policies to restrict users' permissions to specific AWS
resources, go to Access Management and Example Policies.
You can create multiple administrators in your account and add each to the Administrators group. To
sign in to the AWS Management Console, each user needs an AWS account ID or alias. To get these, see
Your AWS Account ID and Its Alias in the IAM User Guide.
16
AWS CloudHSM User Guide
Restrict User Permissions to What's
Necessary for AWS CloudHSM
Restrict User Permissions to What's Necessary for
AWS CloudHSM
We recommend that you create an IAM administrators group for AWS CloudHSM that contains only the
permissions required to run AWS CloudHSM. Attach the policy below to your group. Add IAM users to the
group as needed. Each user that you add inherits the policy from the group.
In addition to an IAM administrators group, we recommend that you create user groups with appropriate
permissions to ensure that only trusted users have access to critical API operations. For example,
you may want to create a read-only user group that permits access only to the DescribeClusters and
DescribeBackups. Make sure that the group does not allow a user to delete clusters or HSMs. This way,
you won't have to worry about an untrusted user affecting availability of a production workload.
As new AWS CloudHSM management features are added over time, you can ensure that only trusted
users are given immediate access. By assigning limited permissions to policies at creation, you can
manually assign new feature permissions to them later.
To create a customer managed policy
1. Sign in to the IAM console using the credentials of an AWS administrator.
2. In the navigation pane, choose Policies.
3. Choose Create policy.
4. Choose the JSON tab.
5. Copy one of the following policies and paste it into the JSON editor based on the type of user policy
you wish to make.
Read-Only User
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"cloudhsm:DescribeClusters",
"cloudhsm:DescribeBackups",
"cloudhsm:ListTags"
],
"Resource": "*"
}
}
The preceding policy allows access to the AWS CloudHSM DescribeClusters and
DescribeBackups API operations. It also includes additional permissions for select Amazon
Elastic Compute Cloud (Amazon EC2) actions. However, it does not allow the user to delete
clusters or HSMs.
Power User
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"cloudhsm:DescribeClusters",
"cloudhsm:DescribeBackups",
"cloudhsm:CreateCluster",
"cloudhsm:CreateHsm",
"cloudhsm:RestoreBackup",
17
AWS CloudHSM User Guide
Restrict User Permissions to What's
Necessary for AWS CloudHSM
"cloudhsm:CopyBackupToRegion",
"cloudhsm:InitializeCluster",
"cloudhsm:ListTags",
"cloudhsm:TagResource",
"cloudhsm:UntagResource",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DetachNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:CreateSecurityGroup",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:RevokeSecurityGroupEgress",
"ec2:DescribeSecurityGroups",
"ec2:DeleteSecurityGroup",
"ec2:CreateTags",
"ec2:DescribeVpcs",
"ec2:DescribeSubnets",
"iam:CreateServiceLinkedRole"
],
"Resource": "*"
}
}
The preceding policy allows access to the AWS CloudHSM DescribeClusters,
DescribeBackups, CreateCluster, CreateHsm, RestoreBackup, CopyBackupToRegion,
InitializeCluster, ListTags, TagResources, and UntagResources API operations. It
also includes additional permissions for select Amazon Elastic Compute Cloud (Amazon EC2)
actions. However, it does not allow the user to delete clusters or HSMs.
Admin User
{
"Version":"2012-10-17",
"Statement":{
"Effect":"Allow",
"Action":[
"cloudhsm:*",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeNetworkInterfaceAttribute",
"ec2:DetachNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:CreateSecurityGroup",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:RevokeSecurityGroupEgress",
"ec2:DescribeSecurityGroups",
"ec2:DeleteSecurityGroup",
"ec2:CreateTags",
"ec2:DescribeVpcs",
"ec2:DescribeSubnets",
"iam:CreateServiceLinkedRole"
],
"Resource":"*"
}
}
The preceding policy allows access a AWS CloudHSM API operations, including the ability to
delete HSMs and clusters. It also includes additional permissions for select Amazon Elastic
Compute Cloud (Amazon EC2) actions.
6. Choose Review policy.
18
AWS CloudHSM User Guide
Understanding Service-Linked Roles
7. For Name, type a relevant policy name. For instance, if this is a policy for read-only users, you might
use CloudHsmReadOnlyUserPolicy.
8. (Optional) Type a description.
9. Choose Create policy.
The preceding policies include the iam:CreateServiceLinkedRole action. You must include this
action to allow AWS CloudHSM to automatically create the AWSServiceRoleForCloudHSM service-linked
role in your account. This role allows AWS CloudHSM to log events. See the following section for more
information about the AWSServiceRoleForCloudHSM service-linked role.
To create an AWS CloudHSM user group
1. Sign in to the IAM console using the credentials of an AWS administrator.
2. In the navigation pane, choose Groups.
3. Choose Create New Group.
4. For Group Name, type a relevant user group name, such as CloudHsmReadOnlyUsers.
5. For Policy Type, choose Customer Managed.
6. Select the check box for preferred user policy and choose Next Step.
7. Choose Create Group.
Note
When you use the AWS CloudHSM console or API, AWS CloudHSM takes additional actions on
your behalf to manage certain Amazon EC2 resources. This happens, for example, when you
create and delete clusters and HSMs.
Understanding Service-Linked Roles
The IAM policy that you created previously to Restrict User Permissions to What's Necessary for AWS
CloudHSM (p. 17) includes the iam:CreateServiceLinkedRole action. AWS CloudHSM defines a
service-linked role named AWSServiceRoleForCloudHSM. The role is predefined by AWS CloudHSM and
includes permissions that AWS CloudHSM requires to call other AWS services on your behalf. The role
makes setting up your service easier because you don’t need to manually add the role policy and trust
policy permissions.
The role policy allows AWS CloudHSM to create Amazon CloudWatch Logs log groups and log streams
and write log events on your behalf. You can view it below and in the IAM console.
{
"Version": "2018-06-12",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams"
],
"Resource": [
"arn:aws:logs:*:*:*"
]
}
]
}
19
AWS CloudHSM User Guide
Create a VPC
The trust policy for the AWSServiceRoleForCloudHSM role allows AWS CloudHSM to assume the role.
{
"Version": "2018-06-12",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cloudhsm.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
Creating a Service-Linked Role (Automatic)
AWS CloudHSM creates the AWSServiceRoleForCloudHSM role when you create a cluster if you include
the iam:CreateServiceLinkedRole action in the permissions that you defined when you created
the AWS CloudHSM administrators group. See Restrict User Permissions to What's Necessary for AWS
CloudHSM (p. 17).
If you already have one or more clusters and just want to add the AWSServiceRoleForCloudHSM role,
you can use the console, the create-cluster command, or the CreateCluster API operation to create a
cluster. Then use the console, the delete-cluster command, or the DeleteCluster API operation to delete
it. Creating the new cluster creates the service-linked role and applies it to all clusters in your account.
Alternatively, you can create the role manually. See the following section for more information.
Note
You do not need to perform all of the steps outlined in Getting Started with
AWS CloudHSM (p. 15) to create a cluster if you are only creating it to add the
AWSServiceRoleForCloudHSM role.
Creating a Service-Linked Role (Manual)
You can use the IAM console, AWS CLI, or API to create the AWSServiceRoleForCloudHSM service-linked
role. For more information, see Creating a Service-Linked Role in the IAM User Guide.
Editing the Service-Linked Role
AWS CloudHSM does not allow you to edit the AWSServiceRoleForCloudHSM service-linked role. After
the role is created, for example, you cannot change its name because various entities might reference
the role by name. Also, you cannot change the role policy. You can, however, use IAM to edit the role
description. For more information, see Editing a Service–Linked Role in the IAM User Guide.
Deleting the Service-Linked Role
You cannot delete a service-linked role as long as a cluster to which it has been applied still exists. To
delete the role, you must first delete each HSM in your cluster and then delete the cluster. Every cluster
in your account must be deleted. You can then use the IAM console, AWS CLI, or API to delete the role.
For more information about deleting a cluster, see Deleting an AWS CloudHSM Cluster (p. 48). For
more information, about deleting a role, see Deleting a Service-Linked Role in the IAM User Guide.
Create a Virtual Private Cloud (VPC)
If you don't already have a virtual private cloud (VPC), create one now.
20
AWS CloudHSM User Guide
Create a Private Subnet
To create a VPC
1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
2. On the navigation bar, use the region selector to choose one of the AWS Regions where AWS
CloudHSM is currently supported.
3. Choose Start VPC Wizard.
4. Choose the first option, VPC with a Single Public Subnet. Then choose Select.
5. For VPC name:, type an identifiable name such as CloudHSM. For Subnet name:, type an identifiable
name such as CloudHSM public subnet. Leave all other options set to their defaults. Then
choose Create VPC. After the VPC is created, choose OK.
Create a Private Subnet
Create a private subnet (a subnet with no internet gateway attached) for each Availability Zone where
you want to create an HSM. Private subnets are available across all AWS Availability Zones. Even if AWS
CloudHSM is not supported in a certain Availability Zone, the HSM cluster still performs as expected
if support is added later. Creating a private subnet in each Availability Zone provides the most robust
configuration for high availability. Visit AWS Regions and Endpoints in the AWS General Reference or the
AWS Region Table to see the regional and zone availability for AWS CloudHSM.
To create the private subnets in your VPC
1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
2. In the navigation pane, choose Subnets. Then choose Create Subnet.
3. In the Create Subnet dialog box, do the following:
a. For Name tag, type an identifiable name such as CloudHSM private subnet.
b. For VPC, choose the VPC that you created previously.
c. For Availability Zone, choose the first Availability Zone in the list.
d. For CIDR block, type the CIDR block to use for the subnet. If you used the default values for the
VPC in the previous procedure, then type 10.0.1.0/28.
Choose Yes, Create.
4. Repeat steps 2 and 3 to create subnets for each remaining Availability Zone in the region. For the
subnet CIDR blocks, you can use 10.0.2.0/28, 10.0.3.0/28, and so on.
Create a Cluster
A cluster is a collection of individual HSMs. AWS CloudHSM synchronizes the HSMs in each cluster so that
they function as a logical unit.
Important
When you create a cluster, AWS CloudHSM creates a service-linked role named
AWSServiceRoleForCloudHSM. If AWS CloudHSM cannot create the role or the role does not
already exist, you may not be able to create a cluster. For more information, see Resolving
Cluster Creation Failures (p. 273). For more information about service–linked roles, see
Understanding Service-Linked Roles (p. 19).
When you create a cluster, AWS CloudHSM creates a security group for the cluster on your behalf. This
security group controls network access to the HSMs in the cluster. It allows inbound connections only
from Amazon Elastic Compute Cloud (Amazon EC2) instances that are in the security group. By default,
21
AWS CloudHSM User Guide
Create a Cluster
the security group doesn't contain any instances. Later, you launch a client instance (p. 23) and add it
to this security group.
Warning
The cluster's security group prevents unauthorized access to your HSMs. Anyone that can access
instances in the security group can access your HSMs. Most operations require a user to log in
to the HSM, but it's possible to zeroize HSMs without authentication, which destroys the key
material, certificates, and other data. If this happens, data created or modified after the most
recent backup is lost and unrecoverable. To prevent this, ensure that only trusted administrators
can access the instances in the cluster's security group or modify the security group.
You can create a cluster from the AWS CloudHSM console, the AWS Command Line Interface (AWS CLI),
or the AWS CloudHSM API.
To create a cluster (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. On the navigation bar, use the region selector to choose one of the AWS Regions where AWS
CloudHSM is currently supported.
3. Choose Create cluster.
4. In the Cluster configuration section, do the following:
a. For VPC, select the VPC that you created.
b. For AZ(s), next to each Availability Zone, choose the private subnet that you created.
Note
Even if AWS CloudHSM is not supported in a given Availability Zone, performance
should not be affected, as AWS CloudHSM automatically load balances across all HSMs
in a cluster. See AWS CloudHSM Regions and Endpoints in the AWS General Reference to
see Availability Zone support for AWS CloudHSM.
5. Choose Next: Review.
6. Review your cluster configuration, and then choose Create cluster.
To create a cluster (AWS CLI)
At a command prompt, run the create-cluster command. Specify the HSM instance type and the
subnet IDs of the subnets where you plan to create HSMs. Use the subnet IDs of the private subnets
that you created. Specify only one subnet per Availability Zone.
$ aws cloudhsmv2 create-cluster --hsm-type hsm1.medium --subnet-ids <subnet ID
1> <subnet ID 2> <subnet ID N>
{
"Cluster": {
"BackupPolicy": "DEFAULT",
"VpcId": "vpc-50ae0636",
"SubnetMapping": {
"us-west-2b": "subnet-49a1bc00",
"us-west-2c": "subnet-6f950334",
"us-west-2a": "subnet-fd54af9b"
},
"SecurityGroup": "sg-6cb2c216",
"HsmType": "hsm1.medium",
"Certificates": {},
"State": "CREATE_IN_PROGRESS",
"Hsms": [],
"ClusterId": "cluster-igklspoyj5v",
"CreateTimestamp": 1502423370.069
}
22
AWS CloudHSM User Guide
Launch an EC2 Client
}
To create a cluster (AWS CloudHSM API)
Send a CreateCluster request. Specify the HSM instance type and the subnet IDs of the subnets
where you plan to create HSMs. Use the subnet IDs of the private subnets that you created. Specify
only one subnet per Availability Zone.
If your attempts to create a cluster fail, it might be related to problems with the AWS CloudHSM service-
linked roles. For help on resolving the failure, see Resolving Cluster Creation Failures (p. 273).
Launch an Amazon EC2 Client Instance
To interact with and manage your AWS CloudHSM cluster and HSM instances, you must be able to
communicate with the elastic network interfaces of your HSMs. The easiest way to do this is to use an
Amazon EC2 instance in the same VPC as your cluster (see below). You can also use the following AWS
resources to connect to your cluster:
Amazon VPC Peering
AWS Direct Connect
VPN Connections
Launch an EC2 Client
The AWS CloudHSM documentation typically assumes that you are using an EC2 instance in the same
VPC and Availability Zone (AZ) in which you create your cluster.
To create an Amazon EC2 client instance
1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
2. Choose Launch instance on the EC2 Dashboard.
3. Select an Amazon Machine Image (AMI). Choose a Linux AMI or a Windows Server AMI.
Note
If you are using an AMI that uses Amazon Linux 2, see Known Issues for Amazon EC2
Instances Running Amazon Linux 2 (p. 265) for additional setup instructions.
4. Choose an instance type and then choose Next: Configure Instance Details.
5. For Network, choose the VPC that you previously created for your cluster.
6. For Subnet, choose the public subnet that you created for the VPC.
7. For Auto-assign Public IP, choose Enable.
8. Choose Next: Add Storage and configure your storage.
9. Choose Next: Add Tags and add any name–value pairs that you want to associate with the instance.
We recommend that you at least add a name. Choose Add Tag and type a name for the Key and up
to 255 characters for the Value.
10. Choose Next: Configure Security Group.
11. Select the default security group that was created for you when you created your cluster.
Note
To connect to a Windows Server EC2 instance, you must set one of your Inbound Rules to
RDP(3389) to allow incoming TCP traffic on port 3389. To connect to a Linux EC2 instance,
you must set one of your Inbound Rules to SSH(22) to allow incoming TCP traffic on port
23
AWS CloudHSM User Guide
Create an HSM
22. Specify the source IP addresses that can connect to your instance. You should not
specify 0.0.0.0/0 because that will open your instance to access by anyone.
If you want your EC2 instance to be able to connect to the internet, set the Outbound Rules
on your security group to allow ALL Traffic on all ports to a destination of 0.0.0.0/0.
You cannot edit security groups on this page. To set inbound and outbound rules, create a
new security group or use the Amazon EC2 console to update your security group rules.
12. Choose Review and Launch.
13. On the Review Instance Launch page, choose Launch.
14. When prompted for a key pair, choose Create a new key pair, enter a name for the key pair, and
then choose Download Key Pair. This is the only chance for you to save the private key file, so
be sure to download it and store it in a safe place. You must provide the name of your key pair
when you launch an instance and the corresponding private key each time that you connect to the
instance. Then choose the key pair that you created when getting set up.
Alternatively, you can use an existing key pair. Choose Choose an existing key pair, and then choose
the desired key pair.
Warning
Don't choose Proceed without a key pair. If you launch your instance without a key pair,
you won't be able to connect to it.
When you are ready, select the acknowledgement check box, and then choose Launch Instances.
For more information about creating a Linux Amazon EC2 client, see Getting Started with Amazon EC2
Linux Instances. For information about connecting to the running client, see the following topics:
Connecting to Your Linux Instance Using SSH
Connecting to Your Linux Instance from Windows Using PuTTY
For more information about creating a Windows Amazon EC2 client, see Getting Started with Amazon
EC2 Windows Instances. For more information about connecting to your Windows client, see Connect to
Your Windows Instance.
Note that you can use your EC2 instance to run all of the AWS CLI commands contained in this guide. If
the AWS CLI is not installed, you can download it from AWS Command Line Interface. If you are using
Windows, you can download and run a 64-bit or 32-bit Windows installer. If you are using Linux or
macOS, you can install the CLI using pip.
To communicate with the HSMs in your cluster, you must install the AWS CloudHSM client software on
your instance. For more information if you are using Linux, see Install the Client (Linux) (p. 35). For
more information if you are using Windows, see Install the Client (Windows) (p. 37).
Create an HSM
After you create a cluster, you can create an HSM. However, before you can create an HSM in your
cluster, the cluster must be in the uninitialized state. To determine the cluster's state, view the clusters
page in the AWS CloudHSM console, use the AWS CLI to run the describe-clusters command, or send
a DescribeClusters request in the AWS CloudHSM API. You can create an HSM from the AWS CloudHSM
console, the AWS CLI, or the AWS CloudHSM API.
To create an HSM (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose Initialize next to the cluster that you created previously.
3. Choose an Availability Zone (AZ) for the HSM that you are creating. Then choose Create.
24
AWS CloudHSM User Guide
Verify HSM Identity (Optional)
To create an HSM (AWS CLI)
At a command prompt, run the create-hsm command. Specify the cluster ID of the cluster that you
created previously and an Availability Zone for the HSM. Specify the Availability Zone in the form of
us-west-2a, us-west-2b, etc.
$ aws cloudhsmv2 create-hsm --cluster-id <cluster ID> --availability-zone <Availability
Zone>
{
"Hsm": {
"HsmId": "hsm-ted36yp5b2x",
"EniIp": "10.0.1.12",
"AvailabilityZone": "us-west-2a",
"ClusterId": "cluster-igklspoyj5v",
"EniId": "eni-5d7ade72",
"SubnetId": "subnet-fd54af9b",
"State": "CREATE_IN_PROGRESS"
}
}
To create an HSM (AWS CloudHSM API)
Send a CreateHsm request. Specify the cluster ID of the cluster that you created previously and an
Availability Zone for the HSM.
After you create a cluster and HSM, you can optionally verify the identity of the HSM (p. 25), or
proceed directly to Initialize the Cluster (p. 31).
Verify the Identity and Authenticity of Your
Cluster's HSM (Optional)
To initialize your cluster, you sign a certificate signing request (CSR) generated by the cluster's first HSM.
Before you do this, you might want to verify the identity and authenticity of the HSM.
Note
This process is optional. However, it works only until a cluster is initialized. After the cluster is
initialized, you cannot use this process to get the certificates or verify the HSMs.
Topics
Overview (p. 25)
Get Certificates from the HSM (p. 27)
Get the Root Certificates (p. 28)
Verify Certificate Chains (p. 29)
Extract and Compare Public Keys (p. 30)
AWS CloudHSM Root Certificate (p. 30)
Overview
To verify the identity of your cluster's first HSM, complete the following steps:
25
AWS CloudHSM User Guide
Overview
1. Get the certificates and CSR (p. 27) – In this step, you get three certificates and a CSR from the
HSM. You also get two root certificates, one from AWS CloudHSM and one from the HSM hardware
manufacturer.
2. Verify the certificate chains (p. 29) – In this step, you construct two certificate chains, one to the
AWS CloudHSM root certificate and one to the manufacturer root certificate. Then you verify the
HSM certificate with these certificate chains to determine that AWS CloudHSM and the hardware
manufacturer both attest to the identity and authenticity of the HSM.
3. Compare public keys (p. 30) – In this step, you extract and compare the public keys in the HSM
certificate and the cluster CSR, to ensure that they are the same. This should give you confidence that
the CSR was generated by an authentic, trusted HSM.
The following diagram shows the CSR, the certificates, and their relationship to each other. The
subsequent list defines each certificate.
AWS Root Certificate
This is AWS CloudHSM's root certificate. You can view and download this certificate at https://
docs.aws.amazon.com/cloudhsm/latest/userguide/root-certificate.html (p. 30).
26
AWS CloudHSM User Guide
Get Certificates from the HSM
Manufacturer Root Certificate
This is the hardware manufacturer's root certificate. You can view and download this certificate at
https://www.cavium.com/LS/TAmanuCert/.
AWS Hardware Certificate
AWS CloudHSM created this certificate when it claimed the HSM hardware. This certificate asserts
that AWS CloudHSM owns the hardware.
Manufacturer Hardware Certificate
The HSM hardware manufacturer created this certificate when it manufactured the HSM hardware.
This certificate asserts that the manufacturer created the hardware.
HSM Certificate
The HSM certificate is generated by the FIPS-validated hardware when you create the first HSM in
the cluster. This certificate asserts that the HSM hardware created the HSM.
Cluster CSR
The first HSM creates the cluster CSR. When you sign the cluster CSR (p. 33), you claim the
cluster. Then, you can use the signed CSR to initialize the cluster (p. 34).
Get Certificates from the HSM
To verify the identity and authenticity of your HSM, start by getting a CSR and five certificates. You get
three of the certificates from the HSM, which you can do with the AWS CloudHSM console, the AWS
Command Line Interface (AWS CLI), or the AWS CloudHSM API.
To get the CSR and HSM certificates (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose Initialize next to the cluster that you created previously.
3. When the certificates and CSR are ready, you see links to download them.
Choose each link to download and save the CSR and certificates. To simplify the subsequent steps,
save all of the files to the same directory and use the default file names.
27
AWS CloudHSM User Guide
Get the Root Certificates
To get the CSR and HSM certificates (AWS CLI)
At a command prompt, run the describe-clusters command four times, extracting the CSR and
different certificates each time and saving them to files.
a. Issue the following command to extract the cluster CSR. Replace <cluster ID> with the ID of
the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds=<cluster ID> \
--output text \
--query 'Clusters[].Certificates.ClusterCsr' \
> <cluster ID>_ClusterCsr.csr
b. Issue the following command to extract the HSM certificate. Replace <cluster ID> with the
ID of the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds=<cluster ID> \
--output text \
--query 'Clusters[].Certificates.HsmCertificate'
\
> <cluster ID>_HsmCertificate.crt
c. Issue the following command to extract the AWS hardware certificate. Replace <cluster ID>
with the ID of the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds=<cluster ID> \
--output text \
--query
'Clusters[].Certificates.AwsHardwareCertificate' \
> <cluster ID>_AwsHardwareCertificate.crt
d. Issue the following command to extract the manufacturer hardware certificate. Replace
<cluster ID> with the ID of the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds=<cluster ID> \
--output text \
--query
'Clusters[].Certificates.ManufacturerHardwareCertificate' \
> <cluster
ID>_ManufacturerHardwareCertificate.crt
To get the CSR and HSM certificates (AWS CloudHSM API)
Send a DescribeClusters request, then extract and save the CSR and certificates from the response.
Get the Root Certificates
Follow these steps to get the root certificates for AWS CloudHSM and the manufacturer. Save the root
certificate files to the directory that contains the CSR and HSM certificate files.
To get the AWS CloudHSM and manufacturer root certificates
1. Go to https://docs.aws.amazon.com/cloudhsm/latest/userguide/root-certificate.html (p. 30), and
then choose AWS_CloudHSM_Root-G1.zip. After you download the file, extract (unzip) its contents.
2. Go to https://www.cavium.com/LS/TAmanuCert/, and then choose Download Certificate. You
might need to right-click the Download Certificate link and then choose Save Link As... to save the
certificate file.
28
AWS CloudHSM User Guide
Verify Certificate Chains
Verify Certificate Chains
In this step, you construct two certificate chains, one to the AWS CloudHSM root certificate and one to
the manufacturer root certificate. Then use OpenSSL to verify the HSM certificate with each certificate
chain.
To create the certificate chains, open a Linux shell. You need OpenSSL, which is available in most
Linux shells, and you need the root certificate (p. 28) and HSM certificate files (p. 27) that you
downloaded. However, you do not need the AWS CLI for this step, and the shell does not need to be
associated with your AWS account.
Note
To verify the certificate chain, use OpenSSL 1.0. Due to a change in OpenSSL certificate
verification, the following instructions do not work with OpenSSL 1.1.
To verify the HSM certificate with the AWS CloudHSM root certificate
1. Navigate to the directory where you saved the root certificate (p. 28) and HSM certificate
files (p. 27) that you downloaded. The following commands assume that all of the certificates are
in the current directory and use the default file names.
Use the following command to create a certificate chain that includes the AWS hardware certificate
and the AWS CloudHSM root certificate, in that order. Replace <cluster ID> with the ID of the
cluster that you created previously.
$ cat <cluster ID>_AwsHardwareCertificate.crt \
AWS_CloudHSM_Root-G1.crt \
> <cluster ID>_AWS_chain.crt
2. Use the following OpenSSL command to verify the HSM certificate with the AWS certificate chain.
Replace <cluster ID> with the ID of the cluster that you created previously.
$ openssl verify -CAfile <cluster ID>_AWS_chain.crt <cluster ID>_HsmCertificate.crt
<cluster ID>_HsmCertificate.crt: OK
To verify the HSM certificate with the manufacturer root certificate
1. Use the following command to create a certificate chain that includes the manufacturer hardware
certificate and the manufacturer root certificate, in that order. Replace <cluster ID> with the ID
of the cluster that you created previously.
$ cat <cluster ID>_ManufacturerHardwareCertificate.crt \
cavium_cert.crt \
> <cluster ID>_manufacturer_chain.crt
2. Use the following OpenSSL command to verify the HSM certificate with the manufacturer certificate
chain. Replace <cluster ID> with the ID of the cluster that you created previously.
$ openssl verify -CAfile <cluster ID>_manufacturer_chain.crt <cluster
ID>_HsmCertificate.crt
<cluster ID>_HsmCertificate.crt: OK
29
AWS CloudHSM User Guide
Extract and Compare Public Keys
Extract and Compare Public Keys
Use OpenSSL to extract and compare the public keys in the HSM certificate and the cluster CSR, to
ensure that they are the same.
To compare the public keys, use your Linux shell. You need OpenSSL, which is available in most Linux
shells, but you do not need the AWS CLI for this step The shell does not need to be associated with your
AWS account.
To extract and compare the public keys
1. Use the following command to extract the public key from the HSM certificate.
$ openssl x509 -in <cluster ID>_HsmCertificate.crt -pubkey -noout > <cluster
ID>_HsmCertificate.pub
2. Use the following command to extract the public key from the cluster CSR.
$ openssl req -in <cluster ID>_ClusterCsr.csr -pubkey -noout > <cluster
ID>_ClusterCsr.pub
3. Use the following command to compare the public keys. If the public keys are identical, the
following command produces no output.
$ diff <cluster ID>_HsmCertificate.pub <cluster ID>_ClusterCsr.pub
After you verify the identity and authenticity of the HSM, proceed to Initialize the Cluster (p. 31).
AWS CloudHSM Root Certificate
Download the AWS CloudHSM root certificate: AWS_CloudHSM_Root-G1.zip.
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 17952736724058547791 (0xf924eeeecf9ea64f)
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US,
ST=Virginia,
L=Herndon,
O=Amazon Web Services INC.,
OU=CloudHSM,
CN=AWS CloudHSM Root G1
Validity
Not Before: Apr 28 08:37:46 2017 GMT
Not After : Apr 26 08:37:46 2027 GMT
Subject: C=US,
ST=Virginia,
L=Herndon,
O=Amazon Web Services INC.,
OU=CloudHSM,
CN=AWS CloudHSM Root G1
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:c8:e3:f6:2a:e0:1f:1e:66:73:00:1e:57:dc:3e:
30
AWS CloudHSM User Guide
Initialize the Cluster
69:f1:9b:73:73:24:58:60:85:80:45:99:a2:85:3f:
e7:f9:67:41:9f:39:d2:e8:e1:88:ec:18:07:5c:38:
98:25:5a:45:5f:1f:c4:60:0e:29:e4:ac:65:f0:b6:
92:83:34:62:1a:e7:c6:ae:0f:40:66:52:bb:0b:6a:
c6:78:27:57:d6:32:3b:6c:0a:83:7d:a7:e9:a1:6c:
10:46:27:74:2c:6e:86:3a:fd:71:18:1f:84:8e:00:
84:bb:00:dc:57:d8:48:94:5c:13:7a:ff:3b:37:52:
60:cd:5a:64:57:35:95:df:67:68:39:e2:f9:85:ad:
59:ee:a6:9a:97:75:35:f4:e1:32:08:d3:0e:2f:bc:
33:04:f3:34:e8:c9:b5:18:fd:69:83:e0:b7:5a:b4:
3f:ce:1c:2f:b5:1e:0f:4f:15:f0:27:00:23:67:d5:
b8:2c:cb:d6:ef:eb:34:25:80:28:33:fa:e6:3a:31:
58:7a:0b:fd:4f:6d:d3:1c:64:10:47:8c:4f:ab:e3:
61:0c:a2:a9:0b:2d:e6:59:f4:1c:2c:92:2a:a4:f9:
a4:83:21:3a:66:dc:c7:75:06:15:fe:83:9d:f8:25:
7f:3b:66:e8:aa:9f:d1:e5:ba:1d:5a:c5:2e:21:ee:
52:61
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
27:00:6B:50:D5:4F:38:8A:35:21:38:D3:0D:A9:5E:D2:10:39:A4:EB
X509v3 Authority Key Identifier:
keyid:27:00:6B:50:D5:4F:38:8A:35:21:38:D3:0D:A9:5E:D2:10:39:A4:EB
X509v3 Basic Constraints:
CA:TRUE
Signature Algorithm: sha256WithRSAEncryption
71:ff:e5:46:27:9c:d0:85:97:5e:c0:82:9a:d4:1b:48:96:75:
2a:40:32:07:80:95:c5:eb:26:1b:46:37:7e:86:12:99:68:b1:
15:bb:f5:55:85:6f:a2:e4:28:70:47:73:07:84:fc:12:28:cc:
8b:3e:b8:f6:60:85:bb:23:6a:cb:6e:a7:ed:82:7e:ed:64:9c:
c1:df:c8:51:db:b9:a4:76:ee:ba:53:aa:e7:30:86:74:5e:be:
2f:1a:c1:88:30:c4:61:02:50:9f:c9:80:7b:7e:f5:1e:49:c8:
6c:1a:39:00:4d:98:1e:21:26:4a:02:f5:d5:3e:6c:47:d9:9c:
94:6f:d7:25:2e:1d:7c:a3:18:ee:8a:32:8a:15:f3:85:39:76:
c3:b9:ba:4e:58:0c:5b:65:44:2e:eb:ab:6c:27:9a:a6:67:df:
22:d4:81:02:2e:c6:34:1b:fe:55:31:8b:d5:73:57:d8:0e:0d:
5a:27:7d:ce:3d:3b:84:80:b3:32:00:e0:6a:f0:32:8a:85:2a:
f8:de:20:bf:65:f7:c9:a8:42:c9:cb:fa:03:d4:10:29:5e:25:
63:a5:71:06:2e:72:78:8a:05:c3:f9:56:e9:b1:e4:2b:6e:f7:
46:5d:b3:12:ed:14:2a:51:d4:56:56:48:ab:7d:fe:d6:49:af:
d6:8e:84:62
Initialize the Cluster
Complete the steps in the following topics to initialize your AWS CloudHSM cluster.
Note
Before you initialize the cluster, review the process by which you can verify the identity and
authenticity of the HSMs (p. 25). This process is optional and works only until a cluster is
initialized. After the cluster is initialized, you cannot use this process to get your certificates or
verify the HSMs.
Topics
Get the Cluster CSR (p. 32)
Sign the CSR (p. 33)
Initialize the Cluster (p. 34)
31
AWS CloudHSM User Guide
Get the Cluster CSR
Get the Cluster CSR
Before you can initialize the cluster, you must download and sign a certificate signing request (CSR) that
is generated by the cluster's first HSM. If you followed the steps to verify the identity of your cluster's
HSM (p. 25), you already have the CSR and you can sign it. Otherwise, get the CSR now by using the
AWS CloudHSM console, the AWS Command Line Interface (AWS CLI), or the AWS CloudHSM API.
To get the CSR (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose Initialize next to the cluster that you created previously (p. 21).
3. When the CSR is ready, you see a link to download it.
Choose Cluster CSR to download and save the CSR.
To get the CSR (AWS CLI)
At a command prompt, run the following describe-clusters command, which extracts the
CSR and saves it to a file. Replace <cluster ID> with the ID of the cluster that you created
previously (p. 21).
$ aws cloudhsmv2 describe-clusters --filters clusterIds=<cluster ID> \
--output text \
--query 'Clusters[].Certificates.ClusterCsr' \
> <cluster ID>_ClusterCsr.csr
To get the CSR (AWS CloudHSM API)
1. Send a DescribeClusters request.
2. Extract and save the CSR from the response.
32
AWS CloudHSM User Guide
Sign the CSR
Sign the CSR
Currently, you must create a self-signed signing certificate and use it to sign the CSR for your cluster.
You do not need the AWS CLI for this step, and the shell does not need to be associated with your AWS
account. To sign the CSR, you must do the following:
1. Get the CSR (see Get the Cluster CSR (p. 32)).
2. Create a private key.
3. Use the private key to create a signing certificate.
4. Sign your cluster CSR.
Create a private key
Use the following command to create a private key. For a production cluster, the key should be created
in a secure manner using a trusted source of randomness. We recommend that you use a secured offsite
and offline HSM or the equivalent. Store the key safely. If you can demonstrate that you own the key, you
can also demonstrate that you own the cluster and the data it contains.
During development and test, you can use any convenient tool (such as OpenSSL) to create and sign the
cluster certificate. The following example shows you how to create a key. After you have used the key to
create a self-signed certificate (see below), you should store it in a safe manner. To sign into your AWS
CloudHSM instance, the certificate must be present, but the private key does not. You use the key only
for specific purposes such as restoring from a backup.
$ openssl genrsa -aes256 -out customerCA.key 2048
Generating RSA private key, 2048 bit long modulus
........+++
............+++
e is 65537 (0x10001)
Enter pass phrase for customerCA.key:
Verifying - Enter pass phrase for customerCA.key:
Use the private key to create a self-signed certificate
The trusted hardware that you use to create the private key for your production cluster should also
provide a software tool to generate a self-signed certificate using that key. The following example uses
OpenSSL and the private key that you created in the previous step to create a signing certificate. The
certificate is valid for 10 years (3652 days). Read the on-screen instructions and follow the prompts.
$ openssl req -new -x509 -days 3652 -key customerCA.key -out customerCA.crt
Enter pass phrase for customerCA.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:
33
AWS CloudHSM User Guide
Initialize the Cluster
This command creates a certificate file named customerCA.crt. Put this certificate on every host from
which you will connect to your AWS CloudHSM cluster. If you give the file a different name or store it in a
path other than the root of your host, you should edit your client configuration file accordingly. Use the
certificate and the private key you just created to sign the cluster certificate signing request (CSR) in the
next step.
Sign the Cluster CSR
The trusted hardware that you use to create your private key for your production cluster should also
provide a tool to sign the CSR using that key. The following example uses OpenSSL to sign the cluster's
CSR. The example uses your private key and the self-signed certificate that you created in the previous
step.
$ openssl x509 -req -days 3652 -in <cluster ID>_ClusterCsr.csr \
-CA customerCA.crt \
-CAkey customerCA.key \
-CAcreateserial \
-out <cluster ID>_CustomerHsmCertificate.crt
Signature ok
subject=/C=US/ST=CA/O=Cavium/OU=N3FIPS/L=SanJose/CN=HSM:<HSM identifer>:PARTN:<partition
number>, for FIPS mode
Getting CA Private Key
Enter pass phrase for customerCA.key:
This command creates a file named <cluster ID>_CustomerHsmCertificate.crt. Use this file as
the signed certificate when you initialize the cluster.
Initialize the Cluster
Use your signed HSM certificate and your signing certificate to initialize your cluster. You can use the
AWS CloudHSM console, the AWS CLI, or the AWS CloudHSM API.
To initialize a cluster (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose Initialize next to the cluster that you created previously.
3. On the Download certificate signing request page, choose Next. If Next is not available, first
choose one of the CSR or certificate links. Then choose Next.
4. On the Sign certificate signing request (CSR) page, choose Next.
5. On the Upload the certificates page, do the following:
a. Next to Cluster certificate, choose Upload file. Then locate and select the HSM certificate that
you signed previously. If you completed the steps in the previous section, select the file named
<cluster ID>_CustomerHsmCertificate.crt.
b. Next to Issuing certificate, choose Upload file. Then select your signing certificate. If you
completed the steps in the previous section, select the file named customerCA.crt.
c. Choose Upload and initialize.
To initialize a cluster (AWS CLI)
At a command prompt, run the initialize-cluster command. Provide the following:
The ID of the cluster that you created previously.
The HSM certificate that you signed previously. If you completed the steps in the previous section,
it's saved in a file named <cluster ID>_CustomerHsmCertificate.crt.
34
AWS CloudHSM User Guide
Install the Client (Linux)
Your signing certificate. If you completed the steps in the previous section, the signing certificate
is saved in a file named customerCA.crt.
$ aws cloudhsmv2 initialize-cluster --cluster-id <cluster ID> \
--signed-cert file://<cluster
ID>_CustomerHsmCertificate.crt \
--trust-anchor file://customerCA.crt
{
"State": "INITIALIZE_IN_PROGRESS",
"StateMessage": "Cluster is initializing. State will change to INITIALIZED upon
completion."
}
To initialize a cluster (AWS CloudHSM API)
Send an InitializeCluster request with the following:
The ID of the cluster that you created previously.
The HSM certificate that you signed previously.
Your signing certificate.
Install and Configure the AWS CloudHSM Client
(Linux)
To interact with the HSM in your AWS CloudHSM cluster, you need the AWS CloudHSM client software
for Linux. You should install it on the Linux EC2 client instance that you created previously. You can
also install a client if you are using Windows. For more information, see Install and Configure the AWS
CloudHSM Client (Windows) (p. 37).
Topics
Install the AWS CloudHSM Client and Command Line Tools (p. 35)
Edit the Client Configuration (p. 37)
Install the AWS CloudHSM Client and Command Line
Tools
Complete the steps in the following procedure to install the AWS CloudHSM client and command line
tools.
To install (or update) the client and command line tools
1. Connect to your client instance.
2. Use the following commands to download and then install the client and command line tools.
Amazon Linux
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-
client-latest.el6.x86_64.rpm
35
AWS CloudHSM User Guide
Install the AWS CloudHSM Client and Command Line Tools
sudo yum install -y ./cloudhsm-client-latest.el6.x86_64.rpm
Amazon Linux 2
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-
client-latest.el7.x86_64.rpm
sudo yum install -y ./cloudhsm-client-latest.el7.x86_64.rpm
CentOS 6
sudo yum install wget
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-
client-latest.el6.x86_64.rpm
sudo yum install -y ./cloudhsm-client-latest.el6.x86_64.rpm
CentOS 7
sudo yum install wget
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-
client-latest.el7.x86_64.rpm
sudo yum install -y ./cloudhsm-client-latest.el7.x86_64.rpm
RHEL 6
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL6/cloudhsm-
client-latest.el6.x86_64.rpm
sudo yum install -y ./cloudhsm-client-latest.el6.x86_64.rpm
RHEL 7
sudo yum install wget
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/EL7/cloudhsm-
client-latest.el7.x86_64.rpm
sudo yum install -y ./cloudhsm-client-latest.el7.x86_64.rpm
Ubuntu 16.04 LTS
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Xenial/cloudhsm-
client_latest_amd64.deb
36
AWS CloudHSM User Guide
Edit the Client Configuration
sudo dpkg -i cloudhsm-client_latest_amd64.deb
Edit the Client Configuration
Before you can use the AWS CloudHSM client to connect to your cluster, you must edit the client
configuration.
To edit the client configuration
1. Copy your issuing certificate—the one that you used to sign the cluster's certificate (p. 33)—to
the following location on the client instance: /opt/cloudhsm/etc/customerCA.crt. You need
AWS account root user permissions on the client instance to copy your certificate to this location.
2. Use the following configure (p. 179) command to update the configuration files for the AWS
CloudHSM client and command line tools, specifying the IP address of the HSM in your cluster. To
get the HSM's IP address, view your cluster in the AWS CloudHSM console, or run the describe-
clusters AWS CLI command. In the command's output, the HSM's IP address is the value of the
EniIp field. If you have more than one HSM, choose the IP address for any of the HSMs; it doesn't
matter which one.
sudo /opt/cloudhsm/bin/configure -a <IP address>
Updating server config in /opt/cloudhsm/etc/cloudhsm_client.cfg
Updating server config in /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
3. Go to Activate the Cluster (p. 38).
Install and Configure the AWS CloudHSM Client
(Windows)
To interact with an HSM in your AWS CloudHSM cluster, you need the AWS CloudHSM client software for
Windows. You should install it on the Windows Server instance that you created previously. You can also
install a client if you are using Linux. For more information, see Install and Configure the AWS CloudHSM
Client (Linux) (p. 35).
To install (or update) the latest client and command line tools
1. Connect to your Windows Server instance.
2. Download the AWSCloudHSMClient-latest.msi installer.
3. Go to your download location and run the AWSCloudHSMClient-latest.msi installer. Follow the
installer instructions.
Important
You must run the installer with administrative privileges.
The installer automatically registers the Cryptography API: Next Generation (CNG) and Key Storage
Providers (KSPs) for AWS CloudHSM. To uninstall the AWS CloudHSM client software for Windows,
run the installer again and follow the uninstall instructions.
4. Choose Close after the installer has finished.
The installer copies the following executable files into the C:\Program Files\Amazon\CloudHSM
folder:
37
AWS CloudHSM User Guide
Activate the Cluster
cloudhsm_client.exe
cloudhsm_mgmt_util.exe
cng_config.exe
configure.exe
key_mgmt_util.exe
ksp_config.exe
pkpspeed_blocking.exe
The installer copies the following certificate and key files into the C:\ProgramData\Amazon
\CloudHSM folder:
client.crt
client.key
The installer copies the following configuration files into the C:\ProgramData\Amazon\CloudHSM
\data folder:
application.cfg
cloudhsm_client.cfg
cloudhsm_mgmt_util.cfg
5. Copy your self-signed issuing certificate—the one that you used to sign the cluster
certificate (p. 33)—to the C:\ProgramData\Amazon\CloudHSM folder.
6. Run the following command to update your configuration files:
c:\Program Files\Amazon\CloudHSM>configure.exe -a <HSM IP address>
7. Go to Activate the Cluster (p. 38).
Activate the Cluster
When you activate an AWS CloudHSM cluster, the cluster's state changes from initialized to active. You
can then manage the HSM's users (p. 53) and use the HSM (p. 183).
To activate the cluster, log in to the HSM with the credentials of the precrypto officer (PRECO) (p. 10).
This a temporary user that exists only on the first HSM in an AWS CloudHSM cluster. The first HSM in
a new cluster contains a PRECO user with a default user name and password. When you change the
password, the PRECO user becomes a crypto officer (CO).
To activate a cluster
1. Connect to the client instance that you launched in previously. For more information, see Launch an
Amazon EC2 Client Instance (p. 23). You can launch a Linux instance or a Windows Server.
2. Use the following command to start the cloudhsm_mgmt_util command line utility.
Note
If you are using an AMI that uses Amazon Linux 2, see Known Issues for Amazon EC2
Instances Running Amazon Linux 2 (p. 265).
Amazon Linux
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
38
AWS CloudHSM User Guide
Activate the Cluster
Ubuntu
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Windows
c:\Program Files\Amazon\CloudHSM>cloudhsm_mgmt_util.exe c:\ProgramData\Amazon
\CloudHSM\data\cloudhsm_mgmt_util.cfg
3. Use the enable_e2e command to enable end-to-end encryption.
aws-cloudhsm>enable_e2e
E2E enabled on server 0(server1)
4. (Optional) Use the listUsers command to display the existing users.
aws-cloudhsm>listUsers
Users on server 0(server1):
Number of users found:2
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PRECO admin NO
0 NO
2 AU app_user NO
0 NO
5. Use the loginHSM command to log in to the HSM as the PRECO user. This is a temporary user that
exists on the first HSM in your cluster.
aws-cloudhsm>loginHSM PRECO admin password
loginHSM success on server 0(server1)
6. Use the changePswd command to change the password for the PRECO user. When you change the
password, the PRECO user becomes a crypto officer (CO).
aws-cloudhsm>changePswd PRECO admin <NewPassword>
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Changing password for admin(PRECO) on 1 nodes
We recommend that you write down the new password on a password worksheet. Do not lose the
worksheet. We recommend that you print a copy of the password worksheet, use it to record your
critical HSM passwords, and then store it in a secure place. We also recommended that you store a
copy of this worksheet in secure off-site storage.
39
AWS CloudHSM User Guide
Reconfigure SSL (Optional)
7. (Optional) Use the listUsers command to verify that the user's type changed to crypto officer
(CO) (p. 11).
aws-cloudhsm>listUsers
Users on server 0(server1):
Number of users found:2
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 CO admin NO
0 NO
2 AU app_user NO
0 NO
8. Use the quit command to stop the cloudhsm_mgmt_util tool.
aws-cloudhsm>quit
Reconfigure SSL with a New Certificate and Private
Key (Optional)
AWS CloudHSM uses an SSL certificate to establish a connection to an HSM. A default key and SSL
certificate are included when you install the client. You can, however, create and use your own.
Note that you will need the self–signed certificate (customerCA.crt) that you created when you
initialized (p. 33) your cluster.
To reconfigure SSL with a new certificate and private key
1. Create a private key using the following OpenSSL command:
openssl genrsa -out ssl-client.key 2048
Generating RSA private key, 2048 bit long modulus
........+++
............+++
e is 65537 (0x10001)
2. Use the following OpenSSL command to create a certificate signing request (CSR). You will be asked
a series of questions for your certificate.
openssl req -new -sha256 -key ssl-client.key -out ssl-client.csr
Enter pass phrase for ssl-client.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:
Organization Name (eg, company) [Default Company Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:
Email Address []:
40
AWS CloudHSM User Guide
Reconfigure SSL (Optional)
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
3. Sign the CSR with the customerCA.crt certificate that you created when you initialized your
cluster.
openssl x509 -req -days 3652 -in ssl-client.csr \
-CA customerCA.crt \
-CAkey customerCA.key \
-CAcreateserial \
-out ssl-client.crt
Signature ok
subject=/C=US/ST=WA/L=Seattle/O=Example Company/OU=sales
Getting CA Private Key
4. Copy your key and certificate to the appropriate directory. In Linux, use the following commands.
The configure --ssl option became available with version 1.0.14 of the AWS CloudHSM client.
sudo cp ssl-client.crt /opt/cloudhsm/etc/
sudo cp ssl-client.key /opt/cloudhsm/etc/
sudo /opt/cloudhsm/bin/configure --ssl --pkey /opt/cloudhsm/etc/ssl-client.key --cert /
opt/cloudhsm/etc/ssl-client.crt
5. Add the customerCA.crt certificate to the trust store. Create a hash of the certificate subject
name. This creates an index to allow the certificate to be looked up by that name. Create a file that
contains the certificate with the hash name.
openssl x509 -in /opt/cloudhsm/etc/customerCA.crt -hash | head -n 1
1234abcd
sudo cp /opt/cloudhsm/etc/customerCA.crt /opt/cloudhsm/etc/certs/1234abcd.0
41
AWS CloudHSM User Guide
Adding or Removing HSMs
Managing AWS CloudHSM Clusters
You can manage your AWS CloudHSM clusters from the AWS CloudHSM console or one of the AWS SDKs
or command line tools. For more information, see the following topics.
To create a cluster, see Getting Started (p. 15).
Topics
Adding or Removing HSMs in an AWS CloudHSM Cluster (p. 42)
Copying a Backup Across Regions (p. 45)
Creating an AWS CloudHSM Cluster from a Previous Backup (p. 46)
Deleting and Restoring an AWS CloudHSM Cluster Backup (p. 47)
Deleting an AWS CloudHSM Cluster (p. 48)
Tagging AWS CloudHSM Resources (p. 49)
Adding or Removing HSMs in an AWS CloudHSM
Cluster
To scale up or down your AWS CloudHSM cluster, add or remove HSMs by using the AWS CloudHSM
console or one of the AWS SDKs or command line tools.
Topics
Adding an HSM (p. 42)
Removing an HSM (p. 44)
Adding an HSM
The following figure illustrates the events that occur when you add an HSM to a cluster.
42
AWS CloudHSM User Guide
Adding an HSM
1. You add a new HSM to a cluster. The following procedures explain how to do this from the AWS
CloudHSM console, the AWS Command Line Interface (AWS CLI), and the AWS CloudHSM API.
This is the only action that you take. The remaining events occur automatically.
2. AWS CloudHSM makes a backup copy of an existing HSM in the cluster. For more information, see
Backups (p. 6).
3. AWS CloudHSM restores the backup onto the new HSM. This ensures that the HSM is in sync with the
others in the cluster.
4. The existing HSMs in the cluster notify the AWS CloudHSM client that there's a new HSM in the
cluster.
5. The client establishes a connection to the new HSM.
43
AWS CloudHSM User Guide
Removing an HSM
To add an HSM (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose a cluster for the HSM that you are adding.
3. On the HSMs tab, choose Create HSM.
4. Choose an Availability Zone (AZ) for the HSM that you are creating. Then choose Create.
To add an HSM (AWS CLI)
At a command prompt, issue the create-hsm command, specifying a cluster ID and an Availability
Zone for the HSM that you are creating. If you don't know the cluster ID of your preferred cluster,
issue the describe-clusters command. Specify the Availability Zone in the form of us-east-2a, us-
east-2b, etc.
$ aws cloudhsmv2 create-hsm --cluster-id <cluster ID> --availability-zone <Availability
Zone>
{
"Hsm": {
"State": "CREATE_IN_PROGRESS",
"ClusterId": "cluster-5a73d5qzrdh",
"HsmId": "hsm-lgavqitns2a",
"SubnetId": "subnet-0e358c43",
"AvailabilityZone": "us-east-2c",
"EniId": "eni-bab18892",
"EniIp": "10.0.3.10"
}
}
To add an HSM (AWS CloudHSM API)
Send a CreateHsm request, specifying the cluster ID and an Availability Zone for the HSM that you
are creating.
Removing an HSM
You can remove an HSM by using the AWS CloudHSM console, the AWS CLI, or the AWS CloudHSM API.
To remove an HSM (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose the cluster that contains the HSM that you are removing.
3. On the HSMs tab, choose the HSM that you are removing. Then choose Delete HSM.
4. Confirm that you want to delete the HSM. Then choose Delete.
To remove an HSM (AWS CLI)
At a command prompt, issue the delete-hsm command. Pass the ID of the cluster that contains the
HSM that you are deleting and one of the following HSM identifiers:
The HSM ID (--hsm-id)
The HSM IP address (--eni-ip)
The HSM's elastic network interface ID (--eni-id)
44
AWS CloudHSM User Guide
Copying a Backup Across Regions
If you don't know the values for these identifiers, issue the describe-clusters command.
$ aws cloudhsmv2 delete-hsm --cluster-id <cluster ID> --eni-ip <HSM IP address>
{
"HsmId": "hsm-lgavqitns2a"
}
To remove an HSM (AWS CloudHSM API)
Send a DeleteHsm request, specifying the cluster ID and an identifier for the HSM that you are
deleting.
Copying a Backup Across Regions
AWS CloudHSM allows you to copy a backup of a cluster into a different region, where it can then
be used to create a new cluster as a clone of the original. AWS CloudHSM Cluster Backups (p. 6) are
packages of encrypted data that contain the elements of a particular cluster. In order to clone a
cluster into a different region, first copy the cluster backup to the destination region and then create
a new cluster from the copied backup. You may want to do this for a number of reasons, including
simplification of the disaster recovery process.
You can copy a cluster backup across regions from the AWS Command Line Interface (AWS CLI), or the
AWS CloudHSM API. Upon issuing the copy-backup-to-region command, the copied backup appears in
the destination region with a CREATE_IN_PROGRESS status. Upon successful completion, the status of
the copied backup is READY.
In the event that the copy-backup-to-region command cannot be successfully completed, the status
of the copied backup is DELETED. Check your input parameters for errors and ensure that the specified
source backup is not in a DELETED state before rerunning the operation.
For information on how to create a cluster from a backup, see Creating an AWS CloudHSM Cluster from a
Previous Backup (p. 46).
Important
Note the following:
To copy a cluster backup to a destination region, your account must have the proper IAM
policy permissions. In order to copy the backup to a different region, your IAM policy must
allow access to the source region in which the backup is located. Once copied across regions,
your IAM policy must allow access to the destination region in order to interact with the
copied backup, which includes using the CreateCluster operation. For more information, see
Restrict User Permissions to What's Necessary for AWS CloudHSM (p. 15).
The original cluster and the cluster that may be built from a backup in the destination region
are not linked. You must manage each of these clusters independently. For more information,
see Managing AWS CloudHSM Clusters (p. 42)
Backups cannot be copied into or out of the AWS GovCloud (US), as it is a restricted region.
To copy a cluster backup to a different region (AWS CLI)
At a command prompt, run the copy-backup-to-region command. Specify the destination region
and either the cluster ID of the source cluster or the backup ID of the source backup. If you specify
a backup ID, the associated backup is copied. If you specify a cluster ID, the most recent available
45
AWS CloudHSM User Guide
Creating a Cluster From a Backup
backup of the associated cluster is copied. If you provide both, the backup ID provided is used
by default. If you don't know the cluster ID or backup ID, run the describe-clusters or describe-
backups command respectively.
$ aws cloudhsmv2 copy-backup-to-region --destination-region <destination region> \
--backup-id <backup ID>
{
"DestinationBackup": {
"CreateTimestamp": 1531742400,
"SourceBackup": "backup-4kuraxsqetz",
"SourceCluster": "cluster-kzlczlspnho",
"SourceRegion": "us-east-1"
}
}
To copy a cluster backup to a different region (AWS CloudHSM API)
Send a CopyBackupToRegion request. Specify the destination region and the cluster ID or most
recent backup ID of the cluster to be copied.
Creating an AWS CloudHSM Cluster from a
Previous Backup
To restore an AWS CloudHSM cluster from a previous backup, you create a new cluster and specify the
backup to restore. After you create the cluster, you don't need to initialize or activate it. You can just
add an HSM to the cluster. This HSM contains the same users, key material, certificates, configuration,
and policies that were in the backup that you restored. For more information about backups, see
Backups (p. 6).
You can restore a cluster from a backup from the AWS CloudHSM console, the AWS Command Line
Interface (AWS CLI), or the AWS CloudHSM API.
To create a cluster from a previous backup (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose Create cluster.
3. In the Cluster configuration section, do the following:
a. For VPC, choose a VPC for the cluster that you are creating.
b. For AZ(s), choose a private subnet for each Availability Zone that you are adding to the cluster.
4. In the Cluster source section, do the following:
a. Choose Restore cluster from existing backup.
b. Choose the backup that you are restoring.
5. Choose Next: Review.
6. Review your cluster configuration, then choose Create cluster.
To create a cluster from a previous backup (AWS CLI)
At a command prompt, issue the create-cluster command. Specify the HSM instance type, the
subnet IDs of the subnets where you plan to create HSMs, and the backup ID of the backup that you
are restoring. If you don't know the backup ID, issue the describe-backups command.
46
AWS CloudHSM User Guide
Deleting and Restoring a Backup
$ aws cloudhsmv2 create-cluster --hsm-type hsm1.medium \
--subnet-ids <subnet ID 1> <subnet ID 2> <subnet ID N>
\
--source-backup-id <backup ID>
{
"Cluster": {
"HsmType": "hsm1.medium",
"VpcId": "vpc-641d3c0d",
"Hsms": [],
"State": "CREATE_IN_PROGRESS",
"SourceBackupId": "backup-rtq2dwi2gq6",
"BackupPolicy": "DEFAULT",
"SecurityGroup": "sg-640fab0c",
"CreateTimestamp": 1504907311.112,
"SubnetMapping": {
"us-east-2c": "subnet-0e358c43",
"us-east-2a": "subnet-f1d6e798",
"us-east-2b": "subnet-40ed9d3b"
},
"Certificates": {
"ClusterCertificate": "<certificate string>"
},
"ClusterId": "cluster-jxhlf7644ne"
}
}
To create a cluster from a previous backup (AWS CloudHSM API)
Send a CreateCluster request. Specify the HSM instance type, the subnet IDs of the subnets where
you plan to create HSMs, and the backup ID of the backup that you are restoring.
To create an HSM that contains the same users, key material, certificates, configuration, and policies that
were in the backup that you restored, add an HSM (p. 42) to the cluster.
Deleting and Restoring an AWS CloudHSM Cluster
Backup
AWS CloudHSM Cluster Backups (p. 6) are packages of encrypted data that contain the elements of a
particular cluster. Backups are generated once a day, as well as whenever an HSM is added to a cluster.
You may want to remove certain cryptographic materials from your AWS environment, such as an
expired key or inactive user. In order to remove these materials, you first delete them from your HSMs. To
ensure that deleted information is not restored when initializing a new cluster with an old backup, you
must then delete all existing backups of the cluster. To do this, you use the AWS Command Line Interface
(AWS CLI), or the AWS CloudHSM API.
A backup must be in the READY state in order to be deleted. You can check the status of a backup by
using the describe-backups command from the AWS CLI, or with the DescribeBackups API call.
Upon successful deletion, a backup is in the PENDING_DELETION state for 7 days, during which time it
can be restored with the restore-backup command. After the deletion window has passed, the target
backup can no longer be restored.
47
AWS CloudHSM User Guide
Deleting a Cluster
To delete and restore a backup (AWS CLI)
1. At a command prompt, run the delete-backup command, passing the ID of the backup to be
deleted. If you don't know the backup ID, run the describe-backups command.
$ aws cloudhsmv2 delete-backup --backup-id <backup ID>
{
"Backup": {
"CreateTimestamp": 1534461854.64,
"ClusterId": "cluster-dygnwhmscg5",
"BackupId": "backup-ro5c4er4aac",
"BackupState": "PENDING_DELETION",
"DeleteTimestamp": 1536339805.522
}
}
2. To restore a backup, issue the restore-backup command, passing the ID of a backup that is in
the PENDING_DELETION state. You can check the status of a backup by issuing the describe-
backups command with the ID of the target backup. If you would like to see a list of all
backups in the PENDING_DELETION state, run the describe-backups command and include
states=PENDING_DELETION as a filter.
$ aws cloudhsmv2 describe-backups --filters states=PENDING_DELETION
{
"Backups": [
{
"BackupId": "backup-ro5c4er4aac",
"BackupState": "PENDING_DELETION",
"CreateTimestamp": 1534461854.64,
"ClusterId": "cluster-dygnwhmscg5",
"DeleteTimestap": 1536339805.522,
}
}
$ aws cloudhsmv2 restore-backup --backup-id <backup ID>
{
"Backup": {
"ClusterId": "cluster-dygnwhmscg5",
"CreateTimestamp": 1534461854.64,
"BackupState": "READY",
"BackupId": "backup-ro5c4er4aac"
}
}
To delete and restore a backup (AWS CloudHSM API):
1. To delete a backup, send a DeleteBackup request, specifying the ID of the backup to be deleted.
2. To restore a backup, send a RestoreBackup request, specifying the ID of the backup to be restored.
Deleting an AWS CloudHSM Cluster
Before you can delete a cluster, you must remove all HSMs from the cluster. For more information, see
Removing an HSM (p. 44).
After you remove all HSMs, you can delete a cluster by using the AWS CloudHSM console, the AWS
Command Line Interface (AWS CLI), or the AWS CloudHSM API.
48
AWS CloudHSM User Guide
Tagging Resources
To delete a cluster (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose the cluster that you are deleting. Then choose Delete cluster.
3. Confirm that you want to delete the cluster, then choose Delete.
To delete a cluster (AWS CLI)
At a command prompt, issue the delete-cluster command, passing the ID of the cluster that you are
deleting. If you don't know the cluster ID, issue the describe-clusters command.
$ aws cloudhsmv2 delete-cluster --cluster-id <cluster ID>
{
"Cluster": {
"Certificates": {
"ClusterCertificate": "<certificate string>"
},
"SourceBackupId": "backup-rtq2dwi2gq6",
"SecurityGroup": "sg-40399d28",
"CreateTimestamp": 1504903546.035,
"SubnetMapping": {
"us-east-2a": "subnet-f1d6e798",
"us-east-2c": "subnet-0e358c43",
"us-east-2b": "subnet-40ed9d3b"
},
"ClusterId": "cluster-kdmrayrc7gi",
"VpcId": "vpc-641d3c0d",
"State": "DELETE_IN_PROGRESS",
"HsmType": "hsm1.medium",
"StateMessage": "The cluster is being deleted.",
"Hsms": [],
"BackupPolicy": "DEFAULT"
}
}
To delete a cluster (AWS CloudHSM API)
Send a DeleteCluster request, specifying the ID of the cluster that you are deleting.
Tagging AWS CloudHSM Resources
A tag is a label that you assign to an AWS resource. You can assign tags to your AWS CloudHSM clusters.
Each tag consists of a tag key and a tag value, both of which you define. For example, the tag key might
be Cost Center and the tag value might be 12345. Tag keys must be unique for each cluster.
You can use tags for a variety of purposes. One common use is to categorize and track your AWS costs.
You can apply tags that represent business categories (such as cost centers, application names, or
owners) to organize your costs across multiple services. When you add tags to your AWS resources, AWS
generates a cost allocation report with usage and costs aggregated by tags. You can use this report
to view your AWS CloudHSM costs in terms of projects or applications, instead of viewing all AWS
CloudHSM costs as a single line item.
For more information about using tags for cost allocation, see Using Cost Allocation Tags in the AWS
Billing and Cost Management User Guide.
You can use the AWS CloudHSM console or one of the AWS SDKs or command line tools to add, update,
list, and remove tags.
49
AWS CloudHSM User Guide
Adding or Updating Tags
Topics
Adding or Updating Tags (p. 50)
Listing Tags (p. 51)
Removing Tags (p. 52)
Adding or Updating Tags
You can add or update tags from the AWS CloudHSM console, the AWS Command Line Interface (AWS
CLI), or the AWS CloudHSM API.
To add or update tags (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose the cluster that you are tagging.
3. Choose Tags.
4. To add a tag, do the following:
a. Choose Add Tag.
b. For Tag Key, type a key for the tag.
c. (Optional) For Tag Value, type a value for the tag.
d. Choose the action for adding a tag, as shown in the following image.
5. To update a tag, do the following:
a. Choose the tag value to update.
Note
If you update the tag key for an existing tag, the console deletes the existing tag and
creates a new one.
b. Type the new tag value. Then choose the action for updating a tag, as shown in the following
image.
50
AWS CloudHSM User Guide
Listing Tags
To add or update tags (AWS CLI)
1. At a command prompt, issue the tag-resource command, specifying the tags and the ID of the
cluster that you are tagging. If you don't know the cluster ID, issue the describe-clusters command.
$ aws cloudhsmv2 tag-resource --resource-id <cluster ID> \
--tag-list Key="<tag key>",Value="<tag value>"
2. To update tags, use the same command but specify an existing tag key. When you specify a new tag
value for an existing tag, the tag is overwritten with the new value.
To add or update tags (AWS CloudHSM API)
Send a TagResource request. Specify the tags and the ID of the cluster that you are tagging.
Listing Tags
You can list tags for a cluster from the AWS CloudHSM console, the AWS CLI, or the AWS CloudHSM API.
To list tags (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose the cluster whose tags you are listing.
3. Choose Tags.
To list tags (AWS CLI)
At a command prompt, issue the list-tags command, specifying the ID of the cluster whose tags you
are listing. If you don't know the cluster ID, issue the describe-clusters command.
$ aws cloudhsmv2 list-tags --resource-id <cluster ID>
{
"TagList": [
{
"Key": "Cost Center",
"Value": "12345"
}
]
51
AWS CloudHSM User Guide
Removing Tags
}
To list tags (AWS CloudHSM API)
Send a ListTags request, specifying the ID of the cluster whose tags you are listing.
Removing Tags
You can remove tags from a cluster by using the AWS CloudHSM console, the AWS CLI, or the AWS
CloudHSM API.
To remove tags (console)
1. Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
2. Choose the cluster whose tags you are removing.
3. Choose Tags.
4. Next to the tag that you are removing, choose the action for deleting a tag, as shown in the
following image.
To remove tags (AWS CLI)
At a command prompt, issue the untag-resource command, specifying the tag keys of the tags that
you are removing and the ID of the cluster whose tags you are removing. When you use the AWS CLI
to remove tags, specify only the tag keys, not the tag values.
$ aws cloudhsmv2 untag-resource --resource-id <cluster ID> \
--tag-key-list "<tag key>"
To remove tags (AWS CloudHSM API)
Send an UntagResource request in the AWS CloudHSM API, specifying the ID of the cluster and the
tags that you are removing.
52
AWS CloudHSM User Guide
Managing HSM Users
Managing HSM Users and Keys in
AWS CloudHSM
Before you can use your AWS CloudHSM cluster for cryptoprocessing, you must create users and
keys on the HSMs in your cluster. See the following topics for more information about using the AWS
CloudHSM command line tools to manage HSM users and keys. You can also learn how to use quorum
authentication (also known as M of N access control).
Topics
Managing HSM Users in AWS CloudHSM (p. 53)
Managing Keys in AWS CloudHSM (p. 56)
Enforcing Quorum Authentication (M of N Access Control) (p. 61)
Managing HSM Users in AWS CloudHSM
To manage users on the HSMs in your AWS CloudHSM cluster, use the AWS CloudHSM command
line tool known as cloudhsm_mgmt_util. Before you can manage users, you must start
cloudhsm_mgmt_util, enable end-to-end encryption, and log in to the HSMs. For more information, see
cloudhsm_mgmt_util (p. 74).
To manage HSM users, log in to the HSM with the user name and password of a cryptographic
officer (p. 11) (CO). Only COs can manage other users. The HSM contains a default CO named admin. You
set this user's password when you activated the cluster (p. 38).
Topics
Create Users (p. 53)
List Users (p. 54)
Change a User's Password (p. 55)
Delete Users (p. 55)
Create Users
Use the createUser (p. 85) command to create a user on the HSM. The following examples create new
CO and CU users, respectively. For information about user types, see HSM Users (p. 10).
aws-cloudhsm>createUser CO example_officer <password>
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
53
AWS CloudHSM User Guide
List Users
Creating User example_officer(CO) on 3 nodes
aws-cloudhsm>createUser CU example_user <password>
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Creating User example_user(CU) on 3 nodes
The following shows the syntax for the createUser (p. 85) command. User types and passwords are
case-sensitive in cloudhsm_mgmt_util commands, but user names are not.
aws-cloudhsm>createUser <user type> <user name> <password>
List Users
Use the listUsers (p. 105) command to list the users on each HSM in the cluster. All HSM user
types (p. 10) can use this command; it's not restricted to COs.
The PCO is the first ("primary") CO created on each HSM. It has the same permissions on the HSM as any
other CO.
aws-cloudhsm>listUsers
Users on server 0(10.0.2.9):
Number of users found:4
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO example_officer NO
0 NO
4 CU example_user NO
0 NO
Users on server 1(10.0.3.11):
Number of users found:4
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO example_officer NO
0 NO
4 CU example_user NO
0 NO
Users on server 2(10.0.1.12):
Number of users found:4
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
54
AWS CloudHSM User Guide
Change a User's Password
2 AU app_user NO
0 NO
3 CO example_officer NO
0 NO
4 CU example_user NO
0 NO
Change a User's Password
Use the changePswd command to change the password for the any user. All HSM user types (p. 10)
can issue this command, but only COs can change the password for other users. Crypto users (CUs) and
appliance users (AUs) can change only their own password. The following examples change the password
for the CO and CU users that were created in the Create Users (p. 53) examples.
aws-cloudhsm>changePswd CO example_officer <new password>
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Changing password for example_officer(CO) on 3 nodes
aws-cloudhsm>changePswd CU example_user <new password>
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Changing password for example_user(CU) on 3 nodes
The following shows the syntax for the changePswd command. User types and passwords are case-
sensitive, but user names are not.
aws-cloudhsm>changePswd <user type> <user name> <new password>
Warning
The CO cannot change the password for a user (CO or CU) who is currently logged in.
Delete Users
Use the deleteUser command to delete a user. The following examples delete the CO and CU users that
were created in the Create Users (p. 53) examples.
aws-cloudhsm>deleteUser CO example_officer
Deleting user example_officer(CO) on 3 nodes
deleteUser success on server 0(10.0.2.9)
deleteUser success on server 1(10.0.3.11)
deleteUser success on server 2(10.0.1.12)
aws-cloudhsm>deleteUser CU example_user
55
AWS CloudHSM User Guide
Managing Keys
Deleting user example_user(CU) on 3 nodes
deleteUser success on server 0(10.0.2.9)
deleteUser success on server 1(10.0.3.11)
deleteUser success on server 2(10.0.1.12)
The following shows the syntax for the deleteUser command.
aws-cloudhsm>deleteUser <user type> <user name>
Warning
Deleting a CU user will orphan all of the keys owned by that CU and make them unusable. You
will not receive any warning that the user you are about to delete still owns keys in the cluster.
Managing Keys in AWS CloudHSM
To manage keys on the HSMs in your AWS CloudHSM cluster, use the key_mgmt_util (p. 119) command
line tool. Before you can manage keys, you must start the AWS CloudHSM client, start key_mgmt_util,
and log in to the HSMs.
To manage keys, log in to the HSM (p. 122) with the user name and password of a crypto user (CU).
Only CUs can create keys. Keys are inherently owned and managed by the CU who created them.
Topics
Generate Keys (p. 56)
Import Keys (p. 57)
Export Keys (p. 59)
Delete Keys (p. 60)
Share and Unshare Keys (p. 60)
Generate Keys
To generate keys on the HSM, use the command that corresponds to the type of key that you want to
generate.
Generate Symmetric Keys
Use the genSymKey (p. 151) command to generate AES, triple DES, and other types of symmetric keys.
To see all available options, use the genSymKey -h command.
The following example creates a 256-bit AES key.
Command: genSymKey -t 31 -s 32 -l aes256
Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created. Key Handle: 524295
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
56
AWS CloudHSM User Guide
Import Keys
Generate RSA Key Pairs
To generate an RSA key pair, use the genRSAKeyPair (p. 146) command. To see all available options, use
the genRSAKeyPair -h command.
The following example generates an RSA 2048-bit key pair.
Command: genRSAKeyPair -m 2048 -e 65537 -l rsa2048
Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair: public key handle: 524294 private key handle: 524296
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
Generate ECC (Elliptic Curve Cryptography) Key Pairs
To generate an ECC key pair, use the genECCKeyPair (p. 142) command. To see all available options,
including a list of the supported elliptic curves, use the genECCKeyPair -h command.
The following example generates an ECC key pair using the P-384 elliptic curve defined in NIST FIPS
publication 186-4.
Command: genECCKeyPair -i 14 -l ecc-p384
Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair: public key handle: 524297 private key handle: 524298
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
Import Keys
To import secret keys—that is, symmetric keys and asymmetric private keys—into the HSM, you must
first create a wrapping key on the HSM. You can import public keys directly without a wrapping key.
Import Secret Keys
Complete the following steps to import a secret key. Before you import a secret key, save it to a file. Save
symmetric keys as raw bytes, and asymmetric private keys in PEM format.
This example shows how to import a plaintext secret key from a file into the HSM. To import an
encrypted key from a file into the HSM, use the unWrapKey (p. 172) command.
To import a secret key
1. Use the genSymKey (p. 151) command to create a wrapping key. The following command creates
a 128-bit AES wrapping key that is valid only for the current session. You can use a session key or a
persistent key as a wrapping key.
Command: genSymKey -t 31 -s 16 -sess -l import-wrapping-key
Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created. Key Handle: 524299
57
AWS CloudHSM User Guide
Import Keys
Cluster Error Status
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
2. Use one of the following commands, depending on the type of secret key that you are importing.
To import a symmetric key, use the imSymKey command. The following command imports an AES
key from a file named aes256.key using the wrapping key created in the previous step. To see all
available options, use the imSymKey -h command.
Command: imSymKey -f aes256.key -t 31 -l aes256-imported -w 524299
Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Unwrapped. Key Handle: 524300
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
To import an asymmetric private key, use the importPrivateKey command. The following
command imports a private key from a file named rsa2048.key using the wrapping key created
in the previous step. To see all available options, use the importPrivateKey -h command.
Command: importPrivateKey -f rsa2048.key -l rsa2048-imported -w 524299
BER encoded key length is 1216
Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS
Private Key Unwrapped. Key Handle: 524301
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
Import Public Keys
Use the importPubKey command to import a public key. To see all available options, use the
importPubKey -h command.
The following example imports an RSA public key from a file named rsa2048.pub.
Command: importPubKey -f rsa2048.pub -l rsa2048-public-imported
Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS
Public Key Handle: 524302
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
58
AWS CloudHSM User Guide
Export Keys
Export Keys
To export secret keys—that is, symmetric keys and asymmetric private keys—from the HSM, you must
first create a wrapping key. You can export public keys directly without a wrapping key.
Only the key owner can export a key. Users with whom the key is shared can use the key in cryptographic
operations, but they cannot export it. When running this example, be sure to export a key that you
created.
Important
The exSymKey (p. 129) command writes a plaintext (unencrypted) copy of the secret key to a
file. The export process requires a wrapping key, but the key in the file is not a wrapped key. To
export a wrapped (encrypted) copy of a key, use the wrapKey (p. 175) command.
Export Secret Keys
Complete the following steps to export a secret key.
To export a secret key
1. Use the genSymKey (p. 151) command to create a wrapping key. The following command creates a
128-bit AES wrapping key that is valid only for the current session.
Command: genSymKey -t 31 -s 16 -sess -l export-wrapping-key
Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created. Key Handle: 524304
Cluster Error Status
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
2. Use one of the following commands, depending on the type of secret key that you are exporting.
To export a symmetric key, use the exSymKey (p. 129) command. The following command
exports an AES key to a file named aes256.key.exp. To see all available options, use the
exSymKey -h command.
Command: exSymKey -k 524295 -out aes256.key.exp -w 524304
Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "aes256.key.exp"
Note
The command's output says that a "Wrapped Symmetric Key" is written to the output
file. However, the output file contains a plaintext (not wrapped) key. To export a wrapped
(encrypted) key to a file, use the wrapKey (p. 175) command.
To export a private key, use the exportPrivateKey command. The following command
exports a private key to a file named rsa2048.key.exp. To see all available options, use the
exportPrivateKey -h command.
Command: exportPrivateKey -k 524296 -out rsa2048.key.exp -w 524304
Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
59
AWS CloudHSM User Guide
Delete Keys
PEM formatted private key is written to rsa2048.key.exp
Export Public Keys
Use the exportPubKey command to export a public key. To see all available options, use the
exportPubKey -h command.
The following example exports an RSA public key to a file named rsa2048.pub.exp.
Command: exportPubKey -k 524294 -out rsa2048.pub.exp
PEM formatted public key is written to rsa2048.pub.key
Cfm3ExportPubKey returned: 0x00 : HSM Return: SUCCESS
Delete Keys
Use the deleteKey (p. 126) command to delete a key, as in the following example. Only the key owner
can delete a key.
Command: deleteKey -k 524300
Cfm3DeleteKey returned: 0x00 : HSM Return: SUCCESS
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
Share and Unshare Keys
In AWS CloudHSM, the CU who creates the key owns it. The owner manages the key, can export and
delete it, and can use the key in cryptographic operations. The owner can also share the key with other
CU users. Users with whom the key is shared can use the key in cryptographic operations, but they
cannot export or delete the key, or share it with other users.
You can share keys with other CU users when you create the key, such as by using the -u parameter of
the genSymKey (p. 151) or genRSAKeyPair (p. 146) commands. To share existing keys with a different
HSM user, use the cloudhsm_mgmt_util (p. 74) command line tool. This is different from most of the
tasks documented in this section, which use the key_mgmt_util (p. 119) command line tool.
Before you can share a key, you must start cloudhsm_mgmt_util, enable end-to-end encryption, and
log in to the HSMs. To share a key, log in to the HSM as the crypto user (CU) that owns the key. Only key
owners can share a key.
Use the shareKey command to share or unshare a key, specifying the handle of the key and the IDs of
the user or users. To share or unshare with more than one user, specify a comma-separated list of user
IDs. To share a key, use 1 as the command's last parameter, as in the following example. To unshare, use
0.
aws-cloudhsm>shareKey 524295 4 1
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
60
AWS CloudHSM User Guide
Quorum Authentication (M of N)
Do you want to continue(y/n)?y
shareKey success on server 0(10.0.2.9)
shareKey success on server 1(10.0.3.11)
shareKey success on server 2(10.0.1.12)
The following shows the syntax for the shareKey command.
aws-cloudhsm>shareKey <key handle> <user ID> <Boolean: 1 for share, 0 for unshare>
Enforcing Quorum Authentication (M of N Access
Control)
The HSMs in your AWS CloudHSM cluster support quorum authentication, which is also known as M of
N access control. With quorum authentication, no single user on the HSM can do quorum-controlled
operations on the HSM. Instead, a minimum number of HSM users (at least 2) must cooperate to do
these operations. With quorum authentication, you can add an extra layer of protection by requiring
approvals from more than one HSM user.
Quorum authentication can control the following operations:
HSM user management by crypto officers (COs) (p. 11) – Creating and deleting HSM users, and
changing a different HSM user's password. For more information, see Using Quorum Authentication for
Crypto Officers (p. 66).
The following topics provide more information about quorum authentication in AWS CloudHSM.
Topics
Overview of Quorum Authentication (p. 61)
Additional Details about Quorum Authentication (p. 62)
Using Quorum Authentication for Crypto Officers: First Time Setup (p. 62)
Using Quorum Authentication for Crypto Officers (p. 66)
Change the Quorum Minimum Value for Crypto Officers (p. 72)
Overview of Quorum Authentication
The following steps summarize the quorum authentication processes. For the specific steps and tools,
see Using Quorum Authentication for Crypto Officers (p. 66).
1. Each HSM user creates an asymmetric key for signing. He or she does this outside of the HSM, taking
care to protect the key appropriately.
2. Each HSM user logs in to the HSM and registers the public part of his or her signing key (the public
key) with the HSM.
3. When an HSM user wants to do a quorum-controlled operation, he or she logs in to the HSM and gets
a quorum token.
4. The HSM user gives the quorum token to one or more other HSM users and asks for their approval.
5. The other HSM users approve by using their keys to cryptographically sign the quorum token. This
occurs outside the HSM.
6. When the HSM user has the required number of approvals, he or she logs in to the HSM and gives the
quorum token and approvals (signatures) to the HSM.
61
AWS CloudHSM User Guide
Additional Details about Quorum Authentication
7. The HSM uses the registered public keys of each signer to verify the signatures. If the signatures are
valid, the HSM approves the token.
8. The HSM user can now do a quorum-controlled operation.
Additional Details about Quorum Authentication
Note the following additional information about using quorum authentication in AWS CloudHSM.
An HSM user can sign his or her own quorum token—that is, the requesting user can provide one of
the required approvals for quorum authentication.
You choose the minimum number of quorum approvers for quorum-controlled operations. The
smallest number you can choose is two (2). For HSM user management operations by COs, the largest
number you can choose is twenty (20).
The HSM can store up to 1024 quorum tokens. If the HSM already has 1024 tokens when you try to
create a new one, the HSM purges one of the expired tokens. By default, tokens expire ten minutes
after their creation.
Using Quorum Authentication for Crypto Officers:
First Time Setup
The following topics describe the steps that you must complete to configure your HSM so that crypto
officers (COs) (p. 11) can use quorum authentication. You need to do these steps only once when you
first configure quorum authentication for COs. After you complete these steps, see Using Quorum
Authentication for Crypto Officers (p. 66).
Topics
Prerequisites (p. 62)
Create and Register a Key for Signing (p. 63)
Set the Quorum Minimum Value on the HSM (p. 65)
Prerequisites
To understand this example, you should be familiar with the cloudhsm_mgmt_util command line
tool (p. 74). In this example, the AWS CloudHSM cluster has two HSMs, each with the same COs, as
shown in the following output from the listUsers command. For more information about creating users,
see Managing HSM Users (p. 53).
aws-cloudhsm>listUsers
Users on server 0(10.0.2.14):
Number of users found:7
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO officer1 NO
0 NO
4 CO officer2 NO
0 NO
5 CO officer3 NO
0 NO
62
AWS CloudHSM User Guide
First Time Setup for Crypto Officers
6 CO officer4 NO
0 NO
7 CO officer5 NO
0 NO
Users on server 1(10.0.1.4):
Number of users found:7
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO officer1 NO
0 NO
4 CO officer2 NO
0 NO
5 CO officer3 NO
0 NO
6 CO officer4 NO
0 NO
7 CO officer5 NO
0 NO
Create and Register a Key for Signing
To use quorum authentication, each CO must create an asymmetric key for signing (a signing key). This is
done outside of the HSM.
There are many different ways to create and protect a personal signing key. The following example
shows how to do it with OpenSSL.
Example – Create a personal signing key with OpenSSL
The following example demonstrates how to use OpenSSL to create a 2048-bit RSA key that is protected
by a pass phrase. To use this example, replace officer1.key with the name of the file where you want
to store the key.
$ openssl genrsa -out officer1.key -aes256 2048
Generating RSA private key, 2048 bit long modulus
.....................................+++
.+++
e is 65537 (0x10001)
Enter pass phrase for officer1.key:
Verifying - Enter pass phrase for officer1.key:
Each CO should create his or her own key.
After creating a key, the CO must register the public part of the key (the public key) with the HSM.
To register a public key with the HSM
1. Use the following command to start the cloudhsm_mgmt_util command line tool.
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
2. Use the enable_e2e command to establish end-to-end encrypted communication.
3. Use the loginHSM command to log in to the HSM as a CO. For more information, see Log in to the
HSMs (p. 80).
63
AWS CloudHSM User Guide
First Time Setup for Crypto Officers
4. Use the registerMofnPubKey command to register the public key. For more information, see the
following example or use the help registerMofnPubKey command.
Example – Register a public key with the HSM
The following example shows how to use the registerMofnPubKey command in the
cloudhsm_mgmt_util command line tool to register a CO's public key with the HSM. To use this
command, the CO must be logged in to the HSM. Replace these values with your own:
key_match_string – An arbitrary string that is used to match the public and private keys. You can
use any string for this value. The cloudhsm_mgmt_util command line tool encrypts this string with
the private key, and then sends the encrypted blob and the plaintext string to the HSM. The HSM uses
the public key to decrypt the encrypted blob, and then compares the decrypted string to the plaintext
string. If the strings match, the HSM registers the public key; otherwise it doesn't.
officer1 – The user name of the CO who is registering the public key. This must be the same CO who
is logged in to the HSM and is running this command.
officer1.key – The name of the file that contains the CO's key. This file must contain the complete
key (not just the public part) because the cloudhsm_mgmt_util command line tool uses the private key
to encrypt the key match string.
When prompted, type the pass phrase that protects the CO's key.
aws-cloudhsm>registerMofnPubKey CO key_match_string officer1 officer1.key
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Enter PEM pass phrase:
registerMofnPubKey success on server 0(10.0.2.14)
registerMofnPubKey success on server 1(10.0.1.4)
Each CO must register his or her public key with the HSM. After all COs register their public keys, the
output from the listUsers command shows this in the MofnPubKey column, as shown in the following
example.
aws-cloudhsm>listUsers
Users on server 0(10.0.2.14):
Number of users found:7
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO officer1 YES
0 NO
4 CO officer2 YES
0 NO
5 CO officer3 YES
0 NO
6 CO officer4 YES
0 NO
7 CO officer5 YES
0 NO
64
AWS CloudHSM User Guide
First Time Setup for Crypto Officers
Users on server 1(10.0.1.4):
Number of users found:7
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO officer1 YES
0 NO
4 CO officer2 YES
0 NO
5 CO officer3 YES
0 NO
6 CO officer4 YES
0 NO
7 CO officer5 YES
0 NO
Set the Quorum Minimum Value on the HSM
To use quorum authentication for COs, a CO must log in to the HSM and then set the quorum minimum
value, also known as the m value. This is the minimum number of CO approvals that are required to
perform HSM user management operations. Any CO on the HSM can set the quorum minimum value,
including COs that have not registered a key for signing. You can change the quorum minimum value at
any time; for more information, see Change the Quorum Value for Crypto Officers (p. 72).
To set the quorum minimum value on the HSM
1. Use the following command to start the cloudhsm_mgmt_util command line tool.
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
2. Use the enable_e2e command to establish end-to-end encrypted communication.
3. Use the loginHSM command to log in to the HSM as a CO. For more information, see Log in to the
HSMs (p. 80).
4. Use the setMValue command to set the quorum minimum value. For more information, see the
following example or use the help setMValue command.
Example – Set the quorum minimum value on the HSM
This example uses a quorum minimum value of two. You can choose any value from two to twenty, up
to the total number of COs on the HSM. In this example, the HSM has six COs (the PCO user (p. 11) is the
same as a CO), so the maximum possible value is six.
To use the following example command, replace the final number (2) with the preferred quorum
minimum value.
aws-cloudhsm>setMValue 3 2
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Setting M Value(2) for 3 on 2 nodes
65
AWS CloudHSM User Guide
Quorum Authentication for Crypto Officers
In the preceding example, the first number (3) identifies the HSM service whose quorum minimum value
you are setting.
The following table lists the HSM service identifiers along with their names, descriptions, and the
commands that are included in the service.
Service Identifier Service Name Service Description HSM Commands
3USER_MGMT HSM user management createUser
deleteUser
changePswd (applies
only when changing
the password of a
different HSM user)
4MISC_CO Miscellaneous CO
service
setMValue
To get the quorum minimum value for a service, use the getMValue command, as in the following
example.
aws-cloudhsm>getMValue 3
MValue of service 3[USER_MGMT] on server 0 : [2]
MValue of service 3[USER_MGMT] on server 1 : [2]
The output from the preceding getMValue command shows that the quorum minimum value for HSM
user management operations (service 3) is now two.
After you complete these steps, see Using Quorum Authentication for Crypto Officers (p. 66).
Using Quorum Authentication for Crypto Officers
A crypto officer (CO) (p. 11) on the HSM can configure quorum authentication for the following
operations on the HSM:
Creating HSM users
Deleting HSM users
Changing another HSM user's password
After the HSM is configured for quorum authentication, COs cannot perform HSM user management
operations on their own. The following example shows the output when a CO attempts to create a new
user on the HSM. The command fails with a RET_MXN_AUTH_FAILED error, which indicates that quorum
authentication failed.
aws-cloudhsm>createUser CU user1 password
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Creating User user1(CU) on 2 nodes
66
AWS CloudHSM User Guide
Quorum Authentication for Crypto Officers
createUser failed: RET_MXN_AUTH_FAILED
creating user on server 0(10.0.2.14) failed
Retry/Ignore/Abort?(R/I/A):A
To perform an HSM user management operation, a CO must complete the following tasks:
1. Get a quorum token (p. 67).
2. Get approvals (signatures) from other COs (p. 68).
3. Approve the token on the HSM (p. 68).
4. Perform the HSM user management operation (p. 70).
If you have not yet configured the HSM for quorum authentication for COs, do that now. For more
information, see First Time Setup for Crypto Officers (p. 62).
Get a Quorum Token
First the CO must use the cloudhsm_mgmt_util command line tool to request a quorum token.
To get a quorum token
1. Use the following command to start the cloudhsm_mgmt_util command line tool.
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
2. Use the enable_e2e command to establish end-to-end encrypted communication.
3. Use the loginHSM command to log in to the HSM as a CO. For more information, see Log in to the
HSMs (p. 80).
4. Use the getToken command to get a quorum token. For more information, see the following
example or use the help getToken command.
Example – Get a quorum token
This example gets a quorum token for the CO with user name officer1 and saves the token to a file
named officer1.token. To use the example command, replace these values with your own:
officer1 – The name of the CO who is getting the token. This must be the same CO who is logged in
to the HSM and is running this command.
officer1.token – The name of the file to use for storing the quorum token.
In the following command, 3 identifies the service for which you can use the token that you are getting.
In this case, the token is for HSM user management operations (service 3). For more information, see Set
the Quorum Minimum Value on the HSM (p. 65).
aws-cloudhsm>getToken 3 officer1 officer1.token
getToken success on server 0(10.0.2.14)
Token:
Id:1
Service:3
Node:1
Key Handle:0
User:officer1
getToken success on server 1(10.0.1.4)
Token:
67
AWS CloudHSM User Guide
Quorum Authentication for Crypto Officers
Id:1
Service:3
Node:0
Key Handle:0
User:officer1
Get Signatures from Approving COs
A CO who has a quorum token must get the token approved by other COs. To give their approval, the
other COs use their signing key to cryptographically sign the token. They do this outside the HSM.
There are many different ways to sign the token. The following example shows how to do it with
OpenSSL. To use a different signing tool, make sure that the tool uses the CO's private key (signing key)
to sign a SHA-256 digest of the token.
Example – Get signatures from approving COs
In this example, the CO that has the token (officer1) needs at least two approvals. The following example
commands show how two COs can use OpenSSL to cryptographically sign the token.
In the first command, officer1 signs his or her own token. To use the following example commands,
replace these values with your own:
officer1.key and officer2.key – The name of the file that contains the CO's signing key.
officer1.token.sig1 and officer1.token.sig2 – The name of the file to use for storing the
signature. Make sure to save each signature in a different file.
officer1.token – The name of the file that contains the token that the CO is signing.
$ openssl dgst -sha256 -sign officer1.key -out officer1.token.sig1 officer1.token
Enter pass phrase for officer1.key:
In the following command, officer2 signs the same token.
$ openssl dgst -sha256 -sign officer2.key -out officer1.token.sig2 officer1.token
Enter pass phrase for officer2.key:
Approve the Signed Token on the HSM
After a CO gets the minimum number of approvals (signatures) from other COs, he or she must approve
the signed token on the HSM.
To approve the signed token on the HSM
1. Create a token approval file. For more information, see the following example.
2. Use the following command to start the cloudhsm_mgmt_util command line tool.
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
3. Use the enable_e2e command to establish end-to-end encrypted communication.
4. Use the loginHSM command to log in to the HSM as a CO. For more information, see Log in to the
HSMs (p. 80).
5. Use the approveToken command to approve the signed token, passing the token approval file. For
more information, see the following example.
68
AWS CloudHSM User Guide
Quorum Authentication for Crypto Officers
Example – Create a token approval file and approve the signed token on the HSM
The token approval file is a text file in a particular format that the HSM requires. The file contains
information about the token, its approvers, and the approvers' signatures. The following shows an
example token approval file.
# For "Multi Token File Path", type the path to the file that contains
# the token. You can type the same value for "Token File Path", but
# that's not required. The "Token File Path" line is required in any
# case, regardless of whether you type a value.
Multi Token File Path = officer1.token;
Token File Path = ;
# Total number of approvals
Number of Approvals = 2;
# Approver 1
# Type the approver's type, name, and the path to the file that
# contains the approver's signature.
Approver Type = 2; # 2 for CO, 1 for CU
Approver Name = officer1;
Approval File = officer1.token.sig1;
# Approver 2
# Type the approver's type, name, and the path to the file that
# contains the approver's signature.
Approver Type = 2; # 2 for CO, 1 for CU
Approver Name = officer2;
Approval File = officer1.token.sig2;
After creating the token approval file, the CO uses the cloudhsm_mgmt_util command line tool to log
in to the HSM. The CO then uses the approveToken command to approve the token, as shown in the
following example. Replace approval.txt with the name of the token approval file.
aws-cloudhsm>approveToken approval.txt
approveToken success on server 0(10.0.2.14)
approveToken success on server 1(10.0.1.4)
When this command succeeds, the HSM has approved the quorum token. To check the status of a token,
use the listTokens command, as shown in the following example. The command's output shows that the
token has the required number of approvals.
The token validity time indicates how long the token is guaranteed to persist on the HSM. Even after the
token validity time elapses (zero seconds), you can still use the token.
aws-cloudhsm>listTokens
=====================
Server 0(10.0.2.14)
=====================
-------- Token - 0 ----------
Token:
Id:1
Service:3
Node:1
Key Handle:0
User:officer1
Token Validity: 506 sec
Required num of approvers : 2
Current num of approvals : 2
Approver-0: officer1
69
AWS CloudHSM User Guide
Quorum Authentication for Crypto Officers
Approver-1: officer2
Num of tokens = 1
=====================
Server 1(10.0.1.4)
=====================
-------- Token - 0 ----------
Token:
Id:1
Service:3
Node:0
Key Handle:0
User:officer1
Token Validity: 506 sec
Required num of approvers : 2
Current num of approvals : 2
Approver-0: officer1
Approver-1: officer2
Num of tokens = 1
listTokens success
Use the Token for User Management Operations
After a CO has a token with the required number of approvals, as shown in the previous section, the CO
can perform one of the following HSM user management operations:
Create an HSM user with the createUser (p. 85) command
Delete an HSM user with the deleteUser command
Change a different HSM user's password with the changePswd command
For more information about using these commands, see Managing HSM Users (p. 53).
The CO can use the token for only one operation. When that operation succeeds, the token is no longer
valid. To do another HSM user management operation, the CO must get a new quorum token, get new
signatures from approvers, and approve the new token on the HSM.
In the following example command, the CO creates a new user on the HSM.
aws-cloudhsm>createUser CU user1 password
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Creating User user1(CU) on 2 nodes
After the previous command succeeds, a subsequent listUsers command shows the new user.
aws-cloudhsm>listUsers
Users on server 0(10.0.2.14):
Number of users found:8
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
70
AWS CloudHSM User Guide
Quorum Authentication for Crypto Officers
2 AU app_user NO
0 NO
3 CO officer1 YES
0 NO
4 CO officer2 YES
0 NO
5 CO officer3 YES
0 NO
6 CO officer4 YES
0 NO
7 CO officer5 YES
0 NO
8 CU user1 NO
0 NO
Users on server 1(10.0.1.4):
Number of users found:8
User Id User Type User Name MofnPubKey
LoginFailureCnt 2FA
1 PCO admin NO
0 NO
2 AU app_user NO
0 NO
3 CO officer1 YES
0 NO
4 CO officer2 YES
0 NO
5 CO officer3 YES
0 NO
6 CO officer4 YES
0 NO
7 CO officer5 YES
0 NO
8 CU user1 NO
0 NO
If the CO tries to perform another HSM user management operation, it fails with a quorum
authentication error, as shown in the following example.
aws-cloudhsm>deleteUser CU user1
Deleting user user1(CU) on 2 nodes
deleteUser failed: RET_MXN_AUTH_FAILED
deleteUser failed on server 0(10.0.2.14)
Retry/rollBack/Ignore?(R/B/I):I
deleteUser failed: RET_MXN_AUTH_FAILED
deleteUser failed on server 1(10.0.1.4)
Retry/rollBack/Ignore?(R/B/I):I
The listTokens command shows that the CO has no approved tokens, as shown in the following example.
To perform another HSM user management operation, the CO must get a new quorum token, get new
signatures from approvers, and approve the new token on the HSM.
aws-cloudhsm>listTokens
=====================
Server 0(10.0.2.14)
=====================
Num of tokens = 0
=====================
Server 1(10.0.1.4)
71
AWS CloudHSM User Guide
Change the Quorum Value for Crypto Officers
=====================
Num of tokens = 0
listTokens success
Change the Quorum Minimum Value for Crypto
Officers
After you set the quorum minimum value (p. 65) so that crypto officers (COs) (p. 11) can use quorum
authentication, you might want to change the quorum minimum value. The HSM allows you to change
the quorum minimum value only when the number of approvers is the same or higher than the current
quorum minimum value. For example, if the quorum minimum value is two, at least two COs must
approve to change the quorum minimum value.
To get quorum approval to change the quorum minimum value, you need a quorum token for the
setMValue command (service 4). To get a quorum token for the setMValue command (service 4), the
quorum minimum value for service 4 must be higher than one. This means that before you can change
the quorum minimum value for COs (service 3), you might need to change the quorum minimum value
for service 4.
The following table lists the HSM service identifiers along with their names, descriptions, and the
commands that are included in the service.
Service Identifier Service Name Service Description HSM Commands
3USER_MGMT HSM user management createUser
deleteUser
changePswd (applies
only when changing
the password of a
different HSM user)
4MISC_CO Miscellaneous CO
service
setMValue
To change the quorum minimum value for crypto officers
1. Use the following command to start the cloudhsm_mgmt_util command line tool.
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
2. Use the enable_e2e command to establish end-to-end encrypted communication.
3. Use the loginHSM command to log in to the HSM as a CO. For more information, see Log in to the
HSMs (p. 80).
4. Use the getMValue command to get the quorum minimum value for service 3. For more
information, see the following example.
5. Use the getMValue command to get the quorum minimum value for service 4. For more
information, see the following example.
6. If the quorum minimum value for service 4 is lower than the value for service 3, use the setMValue
command to change the value for service 4. Change the value for service 4 to one that is the same
or higher than the value for service 3. For more information, see the following example.
7. Get a quorum token (p. 67), taking care to specify service 4 as the service for which you can use
the token.
72
AWS CloudHSM User Guide
Change the Quorum Value for Crypto Officers
8. Get approvals (signatures) from other COs (p. 68).
9. Approve the token on the HSM (p. 68).
10. Use the setMValue command to change quorum minimum value for service 3 (user management
operations performed by COs).
Example – Get quorum minimum values and change the value for service 4
The following example command shows that the quorum minimum value for service 3 is currently two.
aws-cloudhsm>getMValue 3
MValue of service 3[USER_MGMT] on server 0 : [2]
MValue of service 3[USER_MGMT] on server 1 : [2]
The following example command shows that the quorum minimum value for service 4 is currently one.
aws-cloudhsm>getMValue 4
MValue of service 4[MISC_CO] on server 0 : [1]
MValue of service 4[MISC_CO] on server 1 : [1]
To change the quorum minimum value for service 4, use the setMValue command, setting a value that is
the same or higher than the value for service 3. The following example sets the quorum minimum value
for service 4 to two (2), the same value that is set for service 3.
aws-cloudhsm>setMValue 4 2
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Setting M Value(2) for 4 on 2 nodes
The following commands show that the quorum minimum value is now two for service 3 and service 4.
aws-cloudhsm>getMValue 3
MValue of service 3[USER_MGMT] on server 0 : [2]
MValue of service 3[USER_MGMT] on server 1 : [2]
aws-cloudhsm>getMValue 4
MValue of service 4[MISC_CO] on server 0 : [2]
MValue of service 4[MISC_CO] on server 1 : [2]
73
AWS CloudHSM User Guide
cloudhsm_mgmt_util
AWS CloudHSM Command Line
Tools
AWS CloudHSM provides command line tools for managing and using AWS CloudHSM.
Topics
cloudhsm_mgmt_util (p. 74)
key_mgmt_util (p. 119)
Configure Tool (p. 179)
Manage Clusters and HSMs
These tools get, create, delete, and tag AWS CloudHSM clusters and HSMs:
CloudHSMv2 commands in AWS Command Line Interface (AWS CLI). To use these commands, you
need to install and configure AWS CLI.
HSM2 PowerShell cmdlets in the AWSPowerShell module. These cmdlets are available in a
Windows PowerShell module and a cross-platform PowerShell Core module.
Manage Users
This tool creates and deletes HSM users, including implementing quorum authentication of user
management tasks:
cloudhsm_mgmt_util (p. 74). This tool is included in the AWS CloudHSM client software.
Manage Keys
This tool creates, deletes, imports, and exports symmetric keys and asymmetric key pairs:
key_mgmt_util (p. 119). This tool is included in the AWS CloudHSM client software.
Helper Tools
These tools help you to use the tools and software libraries.
configure (p. 179) updates your CloudHSM client configuration files. This enables the AWS
CloudHSM to synchronize the HSMs in a cluster.
pkpspeed (p. 270) measures the performance of your HSM hardware independent of software
libraries.
cloudhsm_mgmt_util
The cloudhsm_mgmt_util command line tool helps crypto officers manage users in the HSMs. It includes
tools that create, delete, and list users, and change user passwords.
cloudhsm_mgmt_util also includes commands that allow crypto users (CUs) to share keys and get and
set key attributes. These commands complement the key management commands in the primary key
management tool, key_mgmt_util (p. 119).
74
AWS CloudHSM User Guide
Getting Started
For a quick start, see Getting Started with cloudhsm_mgmt_util (p. 75). For detailed
information about the cloudhsm_mgmt_util commands and examples of using the commands, see
cloudhsm_mgmt_util Command Reference (p. 80).
Topics
Getting Started with cloudhsm_mgmt_util (p. 75)
cloudhsm_mgmt_util Command Reference (p. 80)
Getting Started with cloudhsm_mgmt_util
AWS CloudHSM includes two command line tools with the AWS CloudHSM client software (p. 35).
The cloudhsm_mgmt_util (p. 80) tool includes commands to manage HSM users. The
key_mgmt_util (p. 122) tool includes commands to manage keys. To get started with the
cloudhsm_mgmt_util command line tool, see the following topics.
Topics
Prepare to run cloudhsm_mgmt_util (p. 75)
Basic Usage of cloudhsm_mgmt_util (p. 78)
Prepare to run cloudhsm_mgmt_util
Complete the following steps before you use cloudhsm_mgmt_util. You need to do these steps the
first time you use cloudhsm_mgmt_util and after you add or remove HSMs in your cluster. The steps
update the HSM list in the configuration files that the AWS CloudHSM client and command line tools use.
Keeping these files updated helps AWS CloudHSM to synchronize data and maintain consistency across
all HSMs in the cluster.
Topics
Step 1: Stop the AWS CloudHSM Client (p. 75)
Step 2: Update the AWS CloudHSM Configuration Files (p. 76)
Step 3: Start the AWS CloudHSM Client (p. 77)
Step 4: Update the cloudhsm_mgmt_util Configuration File (p. 77)
Step 1: Stop the AWS CloudHSM Client
Before you update the configuration files that the AWS CloudHSM and command line tools use, stop the
AWS CloudHSM client. If the client is already stopped, running the stop command has no harmful effect.
Amazon Linux
$ sudo stop cloudhsm-client
Amazon Linux 2
$ sudo service cloudhsm-client stop
CentOS 6
$ sudo stop cloudhsm-client
75
AWS CloudHSM User Guide
Getting Started
CentOS 7
$ sudo service cloudhsm-client stop
RHEL 6
$ sudo stop cloudhsm-client
RHEL 7
$ sudo service cloudhsm-client stop
Ubuntu 16.04 LTS
$ sudo service cloudhsm-client stop
Windows
You can use Ctrl+C to stop the client.
Step 2: Update the AWS CloudHSM Configuration Files
This step uses the -a parameter of the Configure tool (p. 179) to add the elastic network interface (ENI)
IP address of one of the HSMs in the cluster to the configuration file.
Amazon Linux
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
Amazon Linux 2
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
CentOS 6
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
CentOS 7
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
RHEL 6
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
RHEL 7
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
Ubuntu 16.04 LTS
$ sudo /opt/cloudhsm/bin/configure -a <HSM ENI IP>
76
AWS CloudHSM User Guide
Getting Started
Windows
c:\Program Files\Amazon\CloudHSM>configure.exe -a <HSM ENI IP>
To get the ENI IP address of an HSM in your cluster, you can use the DescribeClusters command, the
describe-clusters CLI operation, or the Get-HSM2Cluster PowerShell cmdlet. Type only one ENI IP
address. It does not matter which ENI IP address you use.
Step 3: Start the AWS CloudHSM Client
Next, start or restart the AWS CloudHSM client. When the AWS CloudHSM client starts, it uses the ENI IP
address in its configuration file to query the cluster. Then it adds the ENI IP addresses of all HSMs in the
cluster to the cluster information file.
Amazon Linux
$ sudo start cloudhsm-client
Amazon Linux 2
$ sudo service cloudhsm-client start
CentOS 6
$ sudo start cloudhsm-client
CentOS 7
$ sudo service cloudhsm-client start
RHEL 6
$ sudo start cloudhsm-client
RHEL 7
$ sudo service cloudhsm-client start
Ubuntu 16.04 LTS
$ sudo service cloudhsm-client start
Windows
C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:
\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg
Step 4: Update the cloudhsm_mgmt_util Configuration File
The final step uses the -m parameter of the Configuration tool (p. 179) to copy the updated ENI IP
addresses from the cluster information file to the configuration file that cloudhsm_mgmt_util uses. If
you skip this step, you might run into synchronization problems, such as inconsistent user data (p. 270)
in your cluster's HSMs.
77
AWS CloudHSM User Guide
Getting Started
Amazon Linux
$ sudo /opt/cloudhsm/bin/configure -m
Amazon Linux 2
$ sudo /opt/cloudhsm/bin/configure -m
CentOS 6
$ sudo /opt/cloudhsm/bin/configure -m
CentOS 7
$ sudo /opt/cloudhsm/bin/configure -m
RHEL 6
$ sudo /opt/cloudhsm/bin/configure -m
RHEL 7
$ sudo /opt/cloudhsm/bin/configure -m
Ubuntu 16.04 LTS
$ sudo /opt/cloudhsm/bin/configure -m
Windows
c:\Program Files\Amazon\CloudHSM>configure.exe -m
When this step is complete, you are ready to start cloudhsm_mgmt_util. If you add or delete HSMs at any
time, be sure to repeat this procedure before using cloudhsm_mgmt_util.
Basic Usage of cloudhsm_mgmt_util
See the following topics for the basic usage of the cloudhsm_mgmt_util tool.
Note
The cloudhsm_mgmt_util tool doesn't support autocompleting commands with the Tab key.
Don't use the Tab key with cloudhsm_mgmt_util, because that can make the tool unresponsive.
Topics
Start cloudhsm_mgmt_util (p. 78)
Enable End-to-End Encryption (p. 79)
Log in to the HSMs (p. 80)
Log Out from the HSMs (p. 80)
Stop cloudhsm_mgmt_util (p. 80)
Start cloudhsm_mgmt_util
Use the following command to start cloudhsm_mgmt_util.
78
AWS CloudHSM User Guide
Getting Started
Amazon Linux
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Amazon Linux 2
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
CentOS 6
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
CentOS 7
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
RHEL 6
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
RHEL 7
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Ubuntu 16.04 LTS
$ /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/cloudhsm_mgmt_util.cfg
Windows
C:\Program Files\Amazon\CloudHSM>cloudhsm_mgmt_util.exe C:\ProgramData\Amazon\CloudHSM
\data\cloudhsm_mgmt_util.cfg
Output should be similar to the following depending on how many HSMs you have.
Connecting to the server(s), it may take time
depending on the server(s) load, please wait...
Connecting to server '10.0.2.9': hostname '10.0.2.9', port 2225...
Connected to server '10.0.2.9': hostname '10.0.2.9', port 2225.
Connecting to server '10.0.3.11': hostname '10.0.3.11', port 2225...
Connected to server '10.0.3.11': hostname '10.0.3.11', port 2225.
Connecting to server '10.0.1.12': hostname '10.0.1.12', port 2225...
Connected to server '10.0.1.12': hostname '10.0.1.12', port 2225.
The prompt changes to aws-cloudhsm> when cloudhsm_mgmt_util is running.
Enable End-to-End Encryption
Use the enable_e2e command to establish end-to-end encrypted communication between
cloudhsm_mgmt_util and the HSMs in your cluster. You should enable end-to-end encryption each time
you start cloudhsm_mgmt_util.
79
AWS CloudHSM User Guide
Reference
aws-cloudhsm>enable_e2e
E2E enabled on server 0(10.0.2.9)
E2E enabled on server 1(10.0.3.11)
E2E enabled on server 2(10.0.1.12)
Log in to the HSMs
Use the loginHSM command to log in to the HSMs. Any user of any type can use this command to log in
to the HSMs.
The command in the following example logs in admin, which is the default crypto officer (CO) (p. 10).
You set this user's password when you activated the cluster (p. 38). The output shows that the command
logged in the admin user to all of the HSMs in the cluster.
Warning
When you log in to cloudhsm_mgmt_util, verify that the ENI IP addresses in the success
messages exactly match the ENI IP addresses of all HSMs in the cluster. If they do not, stop
and run all steps in the the section called “Prepare to run cloudhsm_mgmt_util” (p. 75)
procedure.
To get the ENI IP addresses of the HSMs in your cluster, the DescribeClusters operation, the
describe-clusters command, or the Get-HSM2Cluster PowerShell cmdlet.
aws-cloudhsm>loginHSM CO admin <password>
loginHSM success on server 0(10.0.2.9)
loginHSM success on server 1(10.0.3.11)
loginHSM success on server 2(10.0.1.12)
The following shows the syntax for the loginHSM command.
aws-cloudhsm>loginHSM <user type> <user name> <password>
Log Out from the HSMs
Use the logoutHSM command to log out of the HSMs.
aws-cloudhsm>logoutHSM
logoutHSM success on server 0(10.0.2.9)
logoutHSM success on server 1(10.0.3.11)
logoutHSM success on server 2(10.0.1.12)
Stop cloudhsm_mgmt_util
Use the quit command to stop cloudhsm_mgmt_util.
aws-cloudhsm>quit
disconnecting from servers, please wait...
cloudhsm_mgmt_util Command Reference
The cloudhsm_mgmt_util command line tool helps crypto officers manage users in the HSMs. It also
includes commands that allow crypto users (CUs) to share keys, and get and set key attributes. These
commands complement the primary key management commands in the key_mgmt_util (p. 119)
command line tool.
80
AWS CloudHSM User Guide
Reference
For a quick start, see Getting Started with cloudhsm_mgmt_util (p. 75).
Before you run any cloudhsm_mgmt_util command, you must start cloudhsm_mgmt_util (p. 78),
enable end-to-end encryption (p. 79), and log in (p. 80) to the HSM. Be sure that you log in with
the user account type that can run the commands you plan to use.
To list all cloudhsm_mgmt_util commands, run the following command:
aws-cloudhsm> help
To get the syntax for a cloudhsm_mgmt_util command, run the following command:
aws-cloudhsm> help <command-name>
To run a command, enter the command name, or enough of the name to distinguish it from the names
of other cloudhsm_mgmt_util commands.
For example, to get a list of users on the HSMs, enter listUsers or listU.
aws-cloudhsm> listUsers
To end your cloudhsm_mgmt_util session, run the following command:
aws-cloudhsm> quit
For help interpreting the key attributes, see the Key Attribute Reference (p. 176).
The following topics describe commands in cloudhsm_mgmt_util.
Note
Some commands in key_mgmt_util and cloudhsm_mgmt_util have the same names. However,
the commands typically have different syntax, different output, and slightly different
functionality.
Command Description User Type
changePswd (p. 82) Changes the passwords of users
on the HSMs. Any user can
change their own password. COs
can change anyone's password.
CO
createUser (p. 85) Creates users of all types on the
HSMs.
CO
deleteUser (p. 88) Deletes users of all types from
the HSMs.
CO
findAllKeys (p. 91) Gets the keys that a user owns
or shares. Also gets a hash of the
key ownership and sharing data
for all keys on each HSM.
CO, AU
getAttribute (p. 94) Gets an attribute value for an
AWS CloudHSM key and writes
it to a file or stdout (standard
output).
CU
81
AWS CloudHSM User Guide
Reference
Command Description User Type
getCert (p. 96) Gets the certificate of a
particular HSM and saves it in a
desired certificate format.
All.
getHSMInfo (p. 98) Gets information about the
hardware on which an HSM is
running.
All. Login is not required.
getKeyInfo (p. 98) Gets owners, shared users, and
the quorum authentication
status of a key.
All. Login is not required.
info (p. 102) Gets information about an
HSM, including the IP address,
hostname, port, and current
user.
All. Login is not required.
listUsers (p. 105) Gets the users in each of the
HSMs, their user type and ID,
and other attributes.
All. Login is not required.
loginHSM and
logoutHSM (p. 106)
Log in and log out of an HSM. All.
quit (p. 112) Quits cloudhsm_mgmt_util. All. Login is not required.
server (p. 108) Enters and exits server mode on
an HSM.
All.
setAttribute (p. 109) Changes the values of the label,
encrypt, decrypt, wrap, and
unwrap attributes of an existing
key.
CU
shareKey (p. 112) Shares an existing key with other
users.
CU
syncKey (p. 115) Syncs a key across cloned AWS
CloudHSM clusters.
CU, CO
changePswd
The changePswd command in cloudhsm_mgmt_util changes the password of an existing user on the
HSMs in the cluster.
Any user can change their own password. Crypto officers (COs and PCOs) can also change the password
of any other user. You do not need to enter the current password to make the change. However, you
cannot change the password of a user who is logged into the AWS CloudHSM client or key_mgmt_util.
Before you run any cloudhsm_mgmt_util command, you must start cloudhsm_mgmt_util (p. 78)
and log in (p. 80) to the HSM. Be sure that you log in with the user account type that can run the
commands you plan to use.
If you add or delete HSMs, update the configuration files (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be effective for all HSMs
in the cluster.
82
AWS CloudHSM User Guide
Reference
User Type
The following users can run this command.
Crypto officers (CO)
Crypto users (CU)
Syntax
Because this command does not have named parameters, you must enter the arguments in the order
specified in the syntax diagram.
changePswd <user-type> <user-name> <password>
Examples
These examples show how to use changePassword to create new users in your HSMs.
Example : Change Your Password
Any user on the HSMs can use changePswd to change their own password.
The first command uses info (p. 102) to get the current user. The output shows that the current user,
bob, is a crypto user (CU).
aws-cloudhsm> info server 0
Id Name Hostname Port State Partition
LoginState
0 10.0.3.10 10.0.3.10 2225 Connected hsm-aaaabbbbccc Logged
in as 'bob(CU)'
aws-cloudhsm> info server 1
Id Name Hostname Port State Partition
LoginState
0 10.0.3.10 10.0.3.10 2225 Connected hsm-ccccaaaabbb Logged
in as 'bob(CU)'
To change his password, bob runs changePswd with a new password, newPasswerd.
When the command completes, the password change is effective.
aws-cloudhsm> createUser CU bob newPasswerd
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Changing password for bob(CU) on 2 nodes
Example : Change the Password of Another User
This example shows how to change the password of a different user. Any crypto officer (CO, PCO) can
change the password of any user on the HSMs without specifying the existing password.
83
AWS CloudHSM User Guide
Reference
The first command uses info (p. 102) to confirm that alice, a CO, is logged into the HSMs in the
cluster.
aws-cloudhsm>info server 0
Id Name Hostname Port State Partition
LoginState
0 10.0.3.10 10.0.3.10 2225 Connected hsm-aaaabbbbccc Logged in
as 'alice(CO)'
aws-cloudhsm>info server 1
Id Name Hostname Port State Partition
LoginState
0 10.0.3.10 10.0.3.10 2225 Connected hsm-ccccaaaabbb Logged in
as 'alice(CO)'
This command uses changePswd to change the password of officer1, another CO on the HSMs. In
this case, the command resets the password to defaultPassword, the password that this fictitious
enterprise uses as its default. Later, officer1 can reset their password to a more secure value.
aws-cloudhsm>changePswd CO officer1 defaultPassword
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the
cluster. Cav server does NOT synchronize these changes with the
nodes on which this operation is not executed or failed, please
ensure this operation is executed on all nodes in the cluster.
****************************************************************
Do you want to continue(y/n)?y
Changing password for officer1(CO) on 2 nodes
Arguments
Because this command does not have named parameters, you must enter the arguments in the order
specified in the syntax diagram.
changePswd <user-type> <user-name> <password> [1FA | 2FA]
<user-type>
Specifies the current type of the user whose password you are changing. You cannot use
changePswd to change the user type.
Valid values are CO, CU, AU, PCO, and PRECO.
To get the user type, use listUsers (p. 105). For detailed information about the user types on an
HSM, see HSM Users (p. 10).
Required: Yes
<user-name>
Specifies the user's friendly name. This parameter is not case-sensitive. You cannot use changePswd
to change the user name.
Required: Yes
<password>
Specifies a new password for the user. Enter a string of 7 to 32 characters. This value is case
sensitive. The password appears in plaintext when you type it.
84
AWS CloudHSM User Guide
Reference
Required: Yes
1FA | 2FA
Enables or disables dual-factor authentication for the new user. Enter 1FA or 2FA.
This parameter is valid only when the cluster has been configured for dual-factor authentication.
Required: No
Default: 1FA. Dual factor authentication is not enabled.
Related Topics
listUsers (p. 105)
createUser (p. 85)
deleteUser (p. 88)
createUser
The createUser command in cloudhsm_mgmt_util creates a user on the HSMs. Only crypto officers (COs
and PCOs) can run this command. When you create a user, you specify the user type (CO or CU), a user
name, and a password. When the command succeeds, it creates the user in all HSMs in the cluster