AWS CloudHSM User Guide

User Manual:
Open the PDF directly: View PDF .
Page Count: 297
Download
Open PDF In Browser	View PDF
AWS CloudHSM
User Guide

AWS CloudHSM User Guide

AWS CloudHSM: User Guide

Copyright © 2018 Amazon Web Services, Inc. and/or its aﬃliates. 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 aﬃliated with, connected to, or sponsored by
Amazon.

AWS CloudHSM User Guide

Table of Contents
What Is AWS CloudHSM? .................................................................................................................... 1
Use Cases .................................................................................................................................. 1
Oﬄoad the SSL/TLS Processing for Web Servers ................................................................... 1
Protect the Private Keys for an Issuing Certiﬁcate 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 Oﬃcer (PRECO) ................................................................................................. 11
Crypto Oﬃcer (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 Certiﬁcates from the HSM ........................................................................................... 27
Get the Root Certiﬁcates ................................................................................................... 28
Verify Certiﬁcate Chains .................................................................................................... 29
Extract and Compare Public Keys ....................................................................................... 30
AWS CloudHSM Root Certiﬁcate ......................................................................................... 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 Conﬁguration ............................................................................................. 37
Install the Client (Windows) ....................................................................................................... 37

iii

AWS CloudHSM User Guide

Activate the Cluster .................................................................................................................. 38
Reconﬁgure 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 Oﬃcers ................................................................................... 62
Quorum Authentication for Crypto Oﬃcers ......................................................................... 66
Change the Quorum Value for Crypto Oﬃcers ..................................................................... 72
Command Line Tools ........................................................................................................................ 74
cloudhsm_mgmt_util ................................................................................................................ 74
Getting Started ................................................................................................................ 75
Reference ........................................................................................................................ 80
key_mgmt_util ....................................................................................................................... 119
Getting Started .............................................................................................................. 119
Reference ...................................................................................................................... 122
Conﬁgure 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 .................................................................................................................
KSP and CNG Providers ...........................................................................................................
Install the Providers ........................................................................................................
Prerequisites ..................................................................................................................
Code Sample .................................................................................................................
Integrating Third-Party Applications .................................................................................................
SSL/TLS Oﬄoad .....................................................................................................................
How It Works .................................................................................................................
SSL/TLS Oﬄoad on Linux ...............................................................................................
SSL/TLS Oﬄoad on Windows ..........................................................................................
Windows Server CA ................................................................................................................
Set Up Prerequisites .......................................................................................................
Create Windows Server CA ..............................................................................................
Sign a CSR .....................................................................................................................
Oracle Database Encryption .....................................................................................................
Set Up Prerequisites .......................................................................................................
Conﬁgure the Database ...................................................................................................
Monitoring Logs .............................................................................................................................
Getting Client Logs .................................................................................................................
Logging AWS CloudHSM API Calls with AWS CloudTrail ...............................................................
AWS CloudHSM Information in CloudTrail ..........................................................................
Understanding AWS CloudHSM Log File Entries ..................................................................
Monitoring Audit Logs ............................................................................................................
How Audit Logging Works ...............................................................................................
Viewing Audit Logs in CloudWatch Logs ............................................................................
Interpreting HSM Audit Logs ............................................................................................
Audit Log Reference .......................................................................................................
Getting Metrics ..............................................................................................................................
Getting CloudWatch Metrics .....................................................................................................
Troubleshooting .............................................................................................................................
Known Issues .........................................................................................................................
Known Issues for all HSM instances ..................................................................................
Known Issues for Amazon EC2 Instances Running Amazon Linux 2 ........................................
Known Issues for the PKCS #11 SDK .................................................................................
Known Issues for the JCE SDK ..........................................................................................
Known Issues for the OpenSSL SDK ..................................................................................
Lost Connection .....................................................................................................................
Keep HSM Users In Sync ..........................................................................................................
Verify Performance .................................................................................................................
Resolving Cluster Creation Failures ...........................................................................................
Add the Missing Permission .............................................................................................
Create the Service-Linked Role Manually ...........................................................................
Use a Nonfederated User ................................................................................................
Missing AWS CloudHSM Audit Logs in CloudWatch .....................................................................
Client and Software Information ......................................................................................................
Version History .......................................................................................................................
Current Version: 1.1.2 .....................................................................................................
Version: 1.1.1 .................................................................................................................
Version: 1.1.0 .................................................................................................................
Version: 1.0.18 ...............................................................................................................
Version 1.0.14 ................................................................................................................
Version 1.0.11 ................................................................................................................
Version 1.0.10 ................................................................................................................
Version 1.0.8 ..................................................................................................................
Version 1.0.7 ..................................................................................................................
Version 1.0.0 ..................................................................................................................
Supported Platforms ...............................................................................................................

v

202
203
203
204
204
209
209
209
210
224
236
236
237
238
239
240
241
244
244
245
245
246
247
247
248
250
260
262
262
263
263
263
265
265
267
267
268
270
270
273
274
274
274
275
276
276
276
278
281
283
285
285
286
286
287
287
287

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
• Oﬄoad the SSL/TLS Processing for Web Servers (p. 1)
• Protect the Private Keys for an Issuing Certiﬁcate Authority (CA) (p. 2)
• Enable Transparent Data Encryption (TDE) for Oracle Databases (p. 2)

Oﬄoad 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 conﬁrm the identity of the web server and establish a secure connection

1

AWS CloudHSM User Guide
Protect the Private Keys for an
Issuing Certiﬁcate 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 certiﬁcate to establish an
HTTPS session with each client. This process involves a lot of computation for the web server, but you
can oﬄoad some of this to the HSMs in your AWS CloudHSM cluster. This is sometimes known as SSL
acceleration. Oﬄoading 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 oﬄoad with AWS CloudHSM, see SSL/TLS Oﬄoad (p. 209).

Protect the Private Keys for an Issuing Certiﬁcate
Authority (CA)
In a public key infrastructure (PKI), a certiﬁcate authority (CA) is a trusted entity that issues digital
certiﬁcates. These digital certiﬁcates 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 certiﬁcates 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 oﬀer 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 diﬀerent 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
diﬃcult, but AWS CloudHSM does some of the undiﬀerentiated 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 diﬀerent 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 speciﬁed 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 ﬁgure. 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 ﬁgure represents an AWS CloudHSM cluster with three HSMs, each in a diﬀerent
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 conﬁguration ﬁle 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 diﬀerent 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
diﬀerent Availability Zones within an AWS Region.
For example, the following ﬁgure shows an Oracle database application that is distributed to two
diﬀerent 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, eﬀectively restoring your previous HSM.
You can also create a new cluster from an existing backup of a diﬀerent 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 certiﬁcates on the HSM.
• The HSM's conﬁguration 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 FIPSapproved 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 conﬁgured by AWS
CloudHSM.
The encryption processes are summarized in the following ﬁgure. 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 conﬁguration 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 traﬃc to the server only from client
instances in the security group. The client also checks the server's certiﬁcate 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
certiﬁcate that you signed with your own certiﬁcate authority (CA), and the client has the CA's root
certiﬁcate. Before the client–HSM encrypted connection is established, the client veriﬁes the HSM's
cluster certiﬁcate against its root certiﬁcate. The connection is established only when the client
successfully veriﬁes 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 diﬀerent
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 Oﬃcer (PRECO) (p. 11)
• Crypto Oﬃcer (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 Oﬃcer (PRECO)

Precrypto Oﬃcer (PRECO)
The precrypto oﬃcer (PRECO) is a temporary user that exists only on the ﬁrst HSM in an AWS CloudHSM
cluster. The ﬁrst 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 oﬃcer (CO). The PRECO user can only change its
own password and perform read-only operations on the HSM.

Crypto Oﬃcer (CO)
A crypto oﬃcer (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 Oﬃcer (p. 11) (PRECO)
to a crypto oﬃcer (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 Oﬃcer
(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 Oﬃcer
(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, ﬁrmware ID, etc.
²When an HSM is zeroized, all keys, certiﬁcates, 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 oﬀer 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 FIPSapproved security policies for the HSMs provided by AWS CloudHSM below.
FIPS Validation for Hardware Used by CloudHSM
Certiﬁcate #3254 was issued on August 2, 2018.
Certiﬁcate #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 speciﬁes 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 ﬁrst 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 aﬀect 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 Conﬁgure the AWS CloudHSM Client (Linux) (p. 35)
• Install and Conﬁgure the AWS CloudHSM Client (Windows) (p. 37)
• Activate the Cluster (p. 38)
• Reconﬁgure SSL with a New Certiﬁcate 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 deﬁnes an IAM service–linked role for your AWS account. The service–linked role
currently deﬁnes 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 speciﬁc 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 aﬀecting 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.
3.

In the navigation pane, choose Policies.
Choose Create policy.

4.
5.

Choose the JSON tab.
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 deﬁnes a
service-linked role named AWSServiceRoleForCloudHSM. The role is predeﬁned 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 deﬁned 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 ﬁrst 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 ﬁrst option, VPC with a Single Public Subnet. Then choose Select.

5.

For VPC name:, type an identiﬁable name such as CloudHSM. For Subnet name:, type an identiﬁable
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
conﬁguration 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 identiﬁable name such as CloudHSM private subnet.

b.

For VPC, choose the VPC that you created previously.

c.

For Availability Zone, choose the ﬁrst 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, certiﬁcates, and other data. If this happens, data created or modiﬁed 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 conﬁguration 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 aﬀected, 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 conﬁguration, 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   
{

"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 servicelinked 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.
2.

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
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.
5.
6.

Choose an instance type and then choose Next: Conﬁgure Instance Details.
For Network, choose the VPC that you previously created for your cluster.
For Subnet, choose the public subnet that you created for the VPC.

7.

For Auto-assign Public IP, choose Enable.

Choose Next: Add Storage and conﬁgure your storage.
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: Conﬁgure Security Group.
11. Select the default security group that was created for you when you created your cluster.
8.
9.

Note

To connect to a Windows Server EC2 instance, you must set one of your Inbound Rules to
RDP(3389) to allow incoming TCP traﬃc 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 traﬃc 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 Traﬃc 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 ﬁle, 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.
2.
3.

Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
Choose Initialize next to the cluster that you created previously.
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  --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 certiﬁcate signing request (CSR) generated by the cluster's ﬁrst 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 certiﬁcates or verify the HSMs.
Topics
• Overview (p. 25)
• Get Certiﬁcates from the HSM (p. 27)
• Get the Root Certiﬁcates (p. 28)
• Verify Certiﬁcate Chains (p. 29)
• Extract and Compare Public Keys (p. 30)
• AWS CloudHSM Root Certiﬁcate (p. 30)

Overview
To verify the identity of your cluster's ﬁrst HSM, complete the following steps:

25

AWS CloudHSM User Guide
Overview

1. Get the certiﬁcates and CSR (p. 27) – In this step, you get three certiﬁcates and a CSR from the
HSM. You also get two root certiﬁcates, one from AWS CloudHSM and one from the HSM hardware
manufacturer.
2. Verify the certiﬁcate chains (p. 29) – In this step, you construct two certiﬁcate chains, one to the
AWS CloudHSM root certiﬁcate and one to the manufacturer root certiﬁcate. Then you verify the
HSM certiﬁcate with these certiﬁcate 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
certiﬁcate and the cluster CSR, to ensure that they are the same. This should give you conﬁdence that
the CSR was generated by an authentic, trusted HSM.
The following diagram shows the CSR, the certiﬁcates, and their relationship to each other. The
subsequent list deﬁnes each certiﬁcate.

AWS Root Certiﬁcate
This is AWS CloudHSM's root certiﬁcate. You can view and download this certiﬁcate at https://
docs.aws.amazon.com/cloudhsm/latest/userguide/root-certiﬁcate.html (p. 30).

26

AWS CloudHSM User Guide
Get Certiﬁcates from the HSM

Manufacturer Root Certiﬁcate
This is the hardware manufacturer's root certiﬁcate. You can view and download this certiﬁcate at
https://www.cavium.com/LS/TAmanuCert/.
AWS Hardware Certiﬁcate
AWS CloudHSM created this certiﬁcate when it claimed the HSM hardware. This certiﬁcate asserts
that AWS CloudHSM owns the hardware.
Manufacturer Hardware Certiﬁcate
The HSM hardware manufacturer created this certiﬁcate when it manufactured the HSM hardware.
This certiﬁcate asserts that the manufacturer created the hardware.
HSM Certiﬁcate
The HSM certiﬁcate is generated by the FIPS-validated hardware when you create the ﬁrst HSM in
the cluster. This certiﬁcate asserts that the HSM hardware created the HSM.
Cluster CSR
The ﬁrst 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 Certiﬁcates from the HSM
To verify the identity and authenticity of your HSM, start by getting a CSR and ﬁve certiﬁcates. You get
three of the certiﬁcates 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 certiﬁcates (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 certiﬁcates and CSR are ready, you see links to download them.

Choose each link to download and save the CSR and certiﬁcates. To simplify the subsequent steps,
save all of the ﬁles to the same directory and use the default ﬁle names.

27

AWS CloudHSM User Guide
Get the Root Certiﬁcates

To get the CSR and HSM certiﬁcates (AWS CLI)
•

At a command prompt, run the describe-clusters command four times, extracting the CSR and
diﬀerent certiﬁcates each time and saving them to ﬁles.
a.

Issue the following command to extract the cluster CSR. Replace  with the ID of
the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds= \
--output text \
--query 'Clusters[].Certificates.ClusterCsr' \
> _ClusterCsr.csr

b.

Issue the following command to extract the HSM certiﬁcate. Replace  with the
ID of the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds= \
--output text \
--query 'Clusters[].Certificates.HsmCertificate'
\
> _HsmCertificate.crt

c.

Issue the following command to extract the AWS hardware certiﬁcate. Replace 
with the ID of the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds= \
--output text \
--query
'Clusters[].Certificates.AwsHardwareCertificate' \
> _AwsHardwareCertificate.crt

d.

Issue the following command to extract the manufacturer hardware certiﬁcate. Replace
 with the ID of the cluster that you created previously.
$ aws cloudhsmv2 describe-clusters --filters clusterIds= \
--output text \
--query
'Clusters[].Certificates.ManufacturerHardwareCertificate' \
> _ManufacturerHardwareCertificate.crt

To get the CSR and HSM certiﬁcates (AWS CloudHSM API)
•

Send a DescribeClusters request, then extract and save the CSR and certiﬁcates from the response.

Get the Root Certiﬁcates
Follow these steps to get the root certiﬁcates for AWS CloudHSM and the manufacturer. Save the root
certiﬁcate ﬁles to the directory that contains the CSR and HSM certiﬁcate ﬁles.

To get the AWS CloudHSM and manufacturer root certiﬁcates
1.
2.

Go to https://docs.aws.amazon.com/cloudhsm/latest/userguide/root-certiﬁcate.html (p. 30), and
then choose AWS_CloudHSM_Root-G1.zip. After you download the ﬁle, extract (unzip) its contents.
Go to https://www.cavium.com/LS/TAmanuCert/, and then choose Download Certiﬁcate. You
might need to right-click the Download Certiﬁcate link and then choose Save Link As... to save the
certiﬁcate ﬁle.

28

AWS CloudHSM User Guide
Verify Certiﬁcate Chains

Verify Certiﬁcate Chains
In this step, you construct two certiﬁcate chains, one to the AWS CloudHSM root certiﬁcate and one to
the manufacturer root certiﬁcate. Then use OpenSSL to verify the HSM certiﬁcate with each certiﬁcate
chain.
To create the certiﬁcate chains, open a Linux shell. You need OpenSSL, which is available in most
Linux shells, and you need the root certiﬁcate (p. 28) and HSM certiﬁcate ﬁles (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 certiﬁcate chain, use OpenSSL 1.0. Due to a change in OpenSSL certiﬁcate
veriﬁcation, the following instructions do not work with OpenSSL 1.1.

To verify the HSM certiﬁcate with the AWS CloudHSM root certiﬁcate
1.

Navigate to the directory where you saved the root certiﬁcate (p. 28) and HSM certiﬁcate
ﬁles (p. 27) that you downloaded. The following commands assume that all of the certiﬁcates are
in the current directory and use the default ﬁle names.
Use the following command to create a certiﬁcate chain that includes the AWS hardware certiﬁcate
and the AWS CloudHSM root certiﬁcate, in that order. Replace  with the ID of the
cluster that you created previously.
$ cat _AwsHardwareCertificate.crt \
AWS_CloudHSM_Root-G1.crt \
> _AWS_chain.crt

2.

Use the following OpenSSL command to verify the HSM certiﬁcate with the AWS certiﬁcate chain.
Replace  with the ID of the cluster that you created previously.
$ openssl verify -CAfile _AWS_chain.crt _HsmCertificate.crt
_HsmCertificate.crt: OK

To verify the HSM certiﬁcate with the manufacturer root certiﬁcate
1.

Use the following command to create a certiﬁcate chain that includes the manufacturer hardware
certiﬁcate and the manufacturer root certiﬁcate, in that order. Replace  with the ID
of the cluster that you created previously.
$ cat _ManufacturerHardwareCertificate.crt \
cavium_cert.crt \
> _manufacturer_chain.crt

2.

Use the following OpenSSL command to verify the HSM certiﬁcate with the manufacturer certiﬁcate
chain. Replace  with the ID of the cluster that you created previously.
$ openssl verify -CAfile _manufacturer_chain.crt _HsmCertificate.crt
_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 certiﬁcate 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 certiﬁcate.
$ openssl x509 -in _HsmCertificate.crt -pubkey -noout > _HsmCertificate.pub

2.

Use the following command to extract the public key from the cluster CSR.
$ openssl req -in _ClusterCsr.csr -pubkey -noout > _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 _HsmCertificate.pub _ClusterCsr.pub

After you verify the identity and authenticity of the HSM, proceed to Initialize the Cluster (p. 31).

AWS CloudHSM Root Certiﬁcate
Download the AWS CloudHSM root certiﬁcate: 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 certiﬁcates 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 certiﬁcate signing request (CSR) that
is generated by the cluster's ﬁrst 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 ﬁle. Replace  with the ID of the cluster that you created
previously (p. 21).
$ aws cloudhsmv2 describe-clusters --filters clusterIds= \
--output text \
--query 'Clusters[].Certificates.ClusterCsr' \
> _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 certiﬁcate 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 certiﬁcate.
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 oﬀsite
and oﬄine 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 certiﬁcate. The following example shows you how to create a key. After you have used the key to
create a self-signed certiﬁcate (see below), you should store it in a safe manner. To sign into your AWS
CloudHSM instance, the certiﬁcate must be present, but the private key does not. You use the key only
for speciﬁc 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 certiﬁcate
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 certiﬁcate using that key. The following example uses
OpenSSL and the private key that you created in the previous step to create a signing certiﬁcate. The
certiﬁcate 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 certiﬁcate ﬁle named customerCA.crt. Put this certiﬁcate on every host from
which you will connect to your AWS CloudHSM cluster. If you give the ﬁle a diﬀerent name or store it in a
path other than the root of your host, you should edit your client conﬁguration ﬁle accordingly. Use the
certiﬁcate and the private key you just created to sign the cluster certiﬁcate 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 certiﬁcate that you created in the previous
step.
$ openssl x509 -req -days 3652 -in _ClusterCsr.csr \
-CA customerCA.crt \
-CAkey customerCA.key \
-CAcreateserial \
-out _CustomerHsmCertificate.crt
Signature ok
subject=/C=US/ST=CA/O=Cavium/OU=N3FIPS/L=SanJose/CN=HSM::PARTN:, for FIPS mode
Getting CA Private Key
Enter pass phrase for customerCA.key:

This command creates a ﬁle named _CustomerHsmCertificate.crt. Use this ﬁle as
the signed certiﬁcate when you initialize the cluster.

Initialize the Cluster
Use your signed HSM certiﬁcate and your signing certiﬁcate 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 certiﬁcate signing request page, choose Next. If Next is not available, ﬁrst
choose one of the CSR or certiﬁcate links. Then choose Next.

4.

On the Sign certiﬁcate signing request (CSR) page, choose Next.

5.

On the Upload the certiﬁcates page, do the following:
a.

Next to Cluster certiﬁcate, choose Upload ﬁle. Then locate and select the HSM certiﬁcate that
you signed previously. If you completed the steps in the previous section, select the ﬁle named
_CustomerHsmCertificate.crt.

b.

Next to Issuing certiﬁcate, choose Upload ﬁle. Then select your signing certiﬁcate. If you
completed the steps in the previous section, select the ﬁle 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 certiﬁcate that you signed previously. If you completed the steps in the previous section,
it's saved in a ﬁle named _CustomerHsmCertificate.crt.
34

AWS CloudHSM User Guide
Install the Client (Linux)

• Your signing certiﬁcate. If you completed the steps in the previous section, the signing certiﬁcate
is saved in a ﬁle named customerCA.crt.

$ aws cloudhsmv2 initialize-cluster --cluster-id  \
--signed-cert file://_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 certiﬁcate that you signed previously.
• Your signing certiﬁcate.

Install and Conﬁgure 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 Conﬁgure the AWS
CloudHSM Client (Windows) (p. 37).
Topics
• Install the AWS CloudHSM Client and Command Line Tools (p. 35)
• Edit the Client Conﬁguration (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/cloudhsmclient-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/cloudhsmclient-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/cloudhsmclient-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/cloudhsmclient-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/cloudhsmclient-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/cloudhsmclient-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/cloudhsmclient_latest_amd64.deb

36

AWS CloudHSM User Guide
Edit the Client Conﬁguration

sudo dpkg -i cloudhsm-client_latest_amd64.deb

Edit the Client Conﬁguration
Before you can use the AWS CloudHSM client to connect to your cluster, you must edit the client
conﬁguration.

To edit the client conﬁguration
1.

Copy your issuing certiﬁcate—the one that you used to sign the cluster's certiﬁcate (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 certiﬁcate to this location.

2.

Use the following conﬁgure (p. 179) command to update the conﬁguration ﬁles 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 describeclusters AWS CLI command. In the command's output, the HSM's IP address is the value of the
EniIp ﬁeld. 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 
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 Conﬁgure 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 Conﬁgure the AWS CloudHSM
Client (Linux) (p. 35).

To install (or update) the latest client and command line tools
1.
2.

Connect to your Windows Server instance.
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.

4.

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.
Choose Close after the installer has ﬁnished.
The installer copies the following executable ﬁles 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 certiﬁcate and key ﬁles into the C:\ProgramData\Amazon
\CloudHSM folder:
• client.crt
• client.key
The installer copies the following conﬁguration ﬁles into the C:\ProgramData\Amazon\CloudHSM
\data folder:
• application.cfg
• cloudhsm_client.cfg
• cloudhsm_mgmt_util.cfg
5.
6.

Copy your self-signed issuing certiﬁcate—the one that you used to sign the cluster
certiﬁcate (p. 33)—to the C:\ProgramData\Amazon\CloudHSM folder.
Run the following command to update your conﬁguration ﬁles:
c:\Program Files\Amazon\CloudHSM>configure.exe -a 

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 oﬃcer (PRECO) (p. 10).
This a temporary user that exists only on the ﬁrst HSM in an AWS CloudHSM cluster. The ﬁrst 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 oﬃcer (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
LoginFailureCnt
1
0
2
0

5.

User Type
2FA
PRECO
NO
AU
NO

User Name

MofnPubKey

admin

NO

app_user

NO

Use the loginHSM command to log in to the HSM as the PRECO user. This is a temporary user that
exists on the ﬁrst 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 oﬃcer (CO).
aws-cloudhsm>changePswd PRECO admin 
*************************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 oﬀ-site storage.

39

AWS CloudHSM User Guide
Reconﬁgure SSL (Optional)

7.

(Optional) Use the listUsers command to verify that the user's type changed to crypto oﬃcer
(CO) (p. 11).
aws-cloudhsm>listUsers
Users on server 0(server1):
Number of users found:2
User Id
LoginFailureCnt
1
0
2
0

8.

User Type
2FA
CO
NO
AU
NO

User Name

MofnPubKey

admin

NO

app_user

NO

Use the quit command to stop the cloudhsm_mgmt_util tool.
aws-cloudhsm>quit

Reconﬁgure SSL with a New Certiﬁcate and Private
Key (Optional)
AWS CloudHSM uses an SSL certiﬁcate to establish a connection to an HSM. A default key and SSL
certiﬁcate are included when you install the client. You can, however, create and use your own.
Note that you will need the self–signed certiﬁcate (customerCA.crt) that you created when you
initialized (p. 33) your cluster.

To reconﬁgure SSL with a new certiﬁcate 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 certiﬁcate signing request (CSR). You will be asked
a series of questions for your certiﬁcate.
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
Reconﬁgure 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 certiﬁcate 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 certiﬁcate 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 certiﬁcate to the trust store. Create a hash of the certiﬁcate subject
name. This creates an index to allow the certiﬁcate to be looked up by that name. Create a ﬁle that
contains the certiﬁcate 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 ﬁgure 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, useast-2b, etc.
$ aws cloudhsmv2 create-hsm --cluster-id  --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.

Conﬁrm 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 identiﬁers:
• 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 identiﬁers, issue the describe-clusters command.
$ aws cloudhsmv2 delete-hsm --cluster-id  --eni-ip 
{
"HsmId": "hsm-lgavqitns2a"
}

To remove an HSM (AWS CloudHSM API)
•

Send a DeleteHsm request, specifying the cluster ID and an identiﬁer 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 diﬀerent 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 diﬀerent region, ﬁrst 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
simpliﬁcation 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 speciﬁed
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 diﬀerent 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 diﬀerent 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 describebackups command respectively.
$ aws cloudhsmv2 copy-backup-to-region --destination-region  \
--backup-id 
{
"DestinationBackup": {
"CreateTimestamp": 1531742400,
"SourceBackup": "backup-4kuraxsqetz",
"SourceCluster": "cluster-kzlczlspnho",
"SourceRegion": "us-east-1"
}
}

To copy a cluster backup to a diﬀerent 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, certiﬁcates, conﬁguration,
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 conﬁguration section, do the following:

4.

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.

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 conﬁguration, 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   
\
--source-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": ""
},
"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, certiﬁcates, conﬁguration, 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 ﬁrst 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": {
"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 describebackups 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 ﬁlter.
$ 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": {
"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.
2.
3.

Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
Choose the cluster that you are deleting. Then choose Delete cluster.
Conﬁrm 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": {
"Certificates": {
"ClusterCertificate": ""
},
"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 deﬁne. 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:

5.

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.

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  \
--tag-list Key="",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.
2.

Open the AWS CloudHSM console at https://console.aws.amazon.com/cloudhsm/.
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 
{
"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.
4.

Choose Tags.
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  \
--tag-key-list ""

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
oﬃcer (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 
*************************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 
*************************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   

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 ﬁrst ("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
LoginFailureCnt
2FA
1
PCO
0
NO
2
AU
0
NO
3
CO
0
NO
4
CU
0
NO
Users on server 1(10.0.3.11):
Number of users found:4

User Name

User Id
User Type
LoginFailureCnt
2FA
1
PCO
0
NO
2
AU
0
NO
3
CO
0
NO
4
CU
0
NO
Users on server 2(10.0.1.12):
Number of users found:4

User Name

User Id
LoginFailureCnt
1
0

User Type
2FA
PCO
NO

MofnPubKey

admin

NO

app_user

NO

example_officer

NO

example_user

NO

MofnPubKey

admin

NO

app_user

NO

example_officer

NO

example_user

NO

User Name
admin

54

MofnPubKey
NO

AWS CloudHSM User Guide
Change a User's Password

0
0
0

2
3
4

AU
NO
CO
NO
CU
NO

app_user

NO

example_officer

NO

example_user

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 
*************************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 
*************************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 casesensitive, but user names are not.
aws-cloudhsm>changePswd   

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  

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.
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

Key Handle: 524295

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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:
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

public key handle: 524294

private key handle: 524296

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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 deﬁned in NIST FIPS
publication 186-4.
Command: genECCKeyPair -i 14 -l ecc-p384
Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

public key handle: 524297

private key handle: 524298

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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
ﬁrst 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 ﬁle. 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 ﬁle into the HSM. To import an
encrypted key from a ﬁle 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 ﬁle 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.
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

Key Handle: 524300

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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 ﬁle 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.
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

Key Handle: 524301

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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 ﬁle named rsa2048.pub.
Command: importPubKey -f rsa2048.pub -l rsa2048-public-imported
Cfm3CreatePublicKey returned: 0x00 : HSM Return: SUCCESS
Public Key Handle: 524302
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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
ﬁrst 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
ﬁle. The export process requires a wrapping key, but the key in the ﬁle 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 ﬁle 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
ﬁle. However, the output ﬁle contains a plaintext (not wrapped) key. To export a wrapped
(encrypted) key to a ﬁle, use the wrapKey (p. 175) command.
• To export a private key, use the exportPrivateKey command. The following command
exports a private key to a ﬁle 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 ﬁle 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
Node id
Node id
Node id

Error
0 and
1 and
2 and

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
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 diﬀerent
HSM user, use the cloudhsm_mgmt_util (p. 74) command line tool. This is diﬀerent 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   

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 oﬃcers (COs) (p. 11) – Creating and deleting HSM users, and
changing a diﬀerent HSM user's password. For more information, see Using Quorum Authentication for
Crypto Oﬃcers (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 Oﬃcers: First Time Setup (p. 62)
• Using Quorum Authentication for Crypto Oﬃcers (p. 66)
• Change the Quorum Minimum Value for Crypto Oﬃcers (p. 72)

Overview of Quorum Authentication
The following steps summarize the quorum authentication processes. For the speciﬁc steps and tools,
see Using Quorum Authentication for Crypto Oﬃcers (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 Oﬃcers:
First Time Setup
The following topics describe the steps that you must complete to conﬁgure your HSM so that crypto
oﬃcers (COs) (p. 11) can use quorum authentication. You need to do these steps only once when you
ﬁrst conﬁgure quorum authentication for COs. After you complete these steps, see Using Quorum
Authentication for Crypto Oﬃcers (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
LoginFailureCnt
1
0
2
0
3
0
4
0
5
0

User Type
2FA
PCO
NO
AU
NO
CO
NO
CO
NO
CO
NO

User Name

MofnPubKey

admin

NO

app_user

NO

officer1

NO

officer2

NO

officer3

NO

62

AWS CloudHSM User Guide
First Time Setup for Crypto Oﬃcers
CO
NO
7
CO
0
NO
Users on server 1(10.0.1.4):
Number of users found:7
0

6

User Id
LoginFailureCnt
1
0
2
0
3
0
4
0
5
0
6
0
7
0

User Type
2FA
PCO
NO
AU
NO
CO
NO
CO
NO
CO
NO
CO
NO
CO
NO

officer4

NO

officer5

NO

User Name

MofnPubKey

admin

NO

app_user

NO

officer1

NO

officer2

NO

officer3

NO

officer4

NO

officer5

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 diﬀerent 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 ﬁle 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 Oﬃcers

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 ﬁle that contains the CO's key. This ﬁle 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
LoginFailureCnt
1
0
2
0
3
0
4
0
5
0
6
0
7
0

User Type
2FA
PCO
NO
AU
NO
CO
NO
CO
NO
CO
NO
CO
NO
CO
NO

User Name

MofnPubKey

admin

NO

app_user

NO

officer1

YES

officer2

YES

officer3

YES

officer4

YES

officer5

YES

64

AWS CloudHSM User Guide
First Time Setup for Crypto Oﬃcers
Users on server 1(10.0.1.4):
Number of users found:7
User Id
LoginFailureCnt
1
0
2
0
3
0
4
0
5
0
6
0
7
0

User Type
2FA
PCO
NO
AU
NO
CO
NO
CO
NO
CO
NO
CO
NO
CO
NO

User Name

MofnPubKey

admin

NO

app_user

NO

officer1

YES

officer2

YES

officer3

YES

officer4

YES

officer5

YES

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 Oﬃcers (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.
3.
4.

Use the enable_e2e command to establish end-to-end encrypted communication.
Use the loginHSM command to log in to the HSM as a CO. For more information, see Log in to the
HSMs (p. 80).
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 ﬁnal 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 Oﬃcers

In the preceding example, the ﬁrst number (3) identiﬁes the HSM service whose quorum minimum value
you are setting.
The following table lists the HSM service identiﬁers along with their names, descriptions, and the
commands that are included in the service.
Service Identiﬁer

Service Name

Service Description

HSM Commands

3

USER_MGMT

HSM user management

• createUser
• deleteUser
• changePswd (applies
only when changing
the password of a
diﬀerent HSM user)

4

MISC_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 Oﬃcers (p. 66).

Using Quorum Authentication for Crypto Oﬃcers
A crypto oﬃcer (CO) (p. 11) on the HSM can conﬁgure 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 conﬁgured 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 Oﬃcers
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 conﬁgured the HSM for quorum authentication for COs, do that now. For more
information, see First Time Setup for Crypto Oﬃcers (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 oﬃcer1 and saves the token to a ﬁle
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 ﬁle to use for storing the quorum token.
In the following command, 3 identiﬁes 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 Oﬃcers
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 diﬀerent ways to sign the token. The following example shows how to do it with
OpenSSL. To use a diﬀerent 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 (oﬃcer1) needs at least two approvals. The following example
commands show how two COs can use OpenSSL to cryptographically sign the token.
In the ﬁrst command, oﬃcer1 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 ﬁle that contains the CO's signing key.
• officer1.token.sig1 and officer1.token.sig2 – The name of the ﬁle to use for storing the
signature. Make sure to save each signature in a diﬀerent ﬁle.
• officer1.token – The name of the ﬁle 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, oﬃcer2 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 ﬁle. 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 ﬁle. For
more information, see the following example.

68

AWS CloudHSM User Guide
Quorum Authentication for Crypto Oﬃcers

Example – Create a token approval ﬁle and approve the signed token on the HSM
The token approval ﬁle is a text ﬁle in a particular format that the HSM requires. The ﬁle contains
information about the token, its approvers, and the approvers' signatures. The following shows an
example token approval ﬁle.
# 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 ﬁle, 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 ﬁle.
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 Oﬃcers
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 diﬀerent 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
LoginFailureCnt
1
0

User Type
2FA
PCO
NO

User Name
admin

70

MofnPubKey
NO

AWS CloudHSM User Guide
Quorum Authentication for Crypto Oﬃcers
AU
NO
3
CO
0
NO
4
CO
0
NO
5
CO
0
NO
6
CO
0
NO
7
CO
0
NO
8
CU
0
NO
Users on server 1(10.0.1.4):
Number of users found:8
0

2

User Id
LoginFailureCnt
1
0
2
0
3
0
4
0
5
0
6
0
7
0
8
0

app_user

NO

officer1

YES

officer2

YES

officer3

YES

officer4

YES

officer5

YES

user1

User Type
2FA
PCO
NO
AU
NO
CO
NO
CO
NO
CO
NO
CO
NO
CO
NO
CU
NO

User Name

NO

MofnPubKey

admin

NO

app_user

NO

officer1

YES

officer2

YES

officer3

YES

officer4

YES

officer5

YES

user1

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 Oﬃcers
=====================
Num of tokens = 0
listTokens success

Change the Quorum Minimum Value for Crypto
Oﬃcers
After you set the quorum minimum value (p. 65) so that crypto oﬃcers (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 identiﬁers along with their names, descriptions, and the
commands that are included in the service.
Service Identiﬁer

Service Name

Service Description

HSM Commands

3

USER_MGMT

HSM user management

• createUser
• deleteUser
• changePswd (applies
only when changing
the password of a
diﬀerent HSM user)

4

MISC_CO

Miscellaneous CO
service

• setMValue

To change the quorum minimum value for crypto oﬃcers
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).
Use the getMValue command to get the quorum minimum value for service 3. For more
information, see the following example.

4.
5.
6.

7.

Use the getMValue command to get the quorum minimum value for service 4. For more
information, see the following example.
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.
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 Oﬃcers

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)
• Conﬁgure 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 conﬁgure 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.
• conﬁgure (p. 179) updates your CloudHSM client conﬁguration ﬁles. 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 oﬃcers 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
ﬁrst time you use cloudhsm_mgmt_util and after you add or remove HSMs in your cluster. The steps
update the HSM list in the conﬁguration ﬁles that the AWS CloudHSM client and command line tools use.
Keeping these ﬁles 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 Conﬁguration Files (p. 76)
• Step 3: Start the AWS CloudHSM Client (p. 77)
• Step 4: Update the cloudhsm_mgmt_util Conﬁguration File (p. 77)

Step 1: Stop the AWS CloudHSM Client
Before you update the conﬁguration ﬁles 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 eﬀect.
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 Conﬁguration Files
This step uses the -a parameter of the Conﬁgure tool (p. 179) to add the elastic network interface (ENI)
IP address of one of the HSMs in the cluster to the conﬁguration ﬁle.
Amazon Linux
$ sudo /opt/cloudhsm/bin/configure -a 

Amazon Linux 2
$ sudo /opt/cloudhsm/bin/configure -a 

CentOS 6
$ sudo /opt/cloudhsm/bin/configure -a 

CentOS 7
$ sudo /opt/cloudhsm/bin/configure -a 

RHEL 6
$ sudo /opt/cloudhsm/bin/configure -a 

RHEL 7
$ sudo /opt/cloudhsm/bin/configure -a 

Ubuntu 16.04 LTS
$ sudo /opt/cloudhsm/bin/configure -a 

76

AWS CloudHSM User Guide
Getting Started

Windows
c:\Program Files\Amazon\CloudHSM>configure.exe -a 

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 conﬁguration ﬁle to query the cluster. Then it adds the ENI IP addresses of all HSMs in the
cluster to the cluster information ﬁle.
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 Conﬁguration File
The ﬁnal step uses the -m parameter of the Conﬁguration tool (p. 179) to copy the updated ENI IP
addresses from the cluster information ﬁle to the conﬁguration ﬁle 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 oﬃcer (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 
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   

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 oﬃcers 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 

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 diﬀerent syntax, diﬀerent output, and slightly diﬀerent
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

ﬁndAllKeys (p. 91)

Gets the keys that a user owns
CO, AU
or shares. Also gets a hash of the
key ownership and sharing data
for all keys on each HSM.

getAttribute (p. 94)

Gets an attribute value for an
AWS CloudHSM key and writes
it to a ﬁle or stdout (standard
output).

81

CU

AWS CloudHSM User Guide
Reference

Command

Description

User Type

getCert (p. 96)

Gets the certiﬁcate of a
particular HSM and saves it in a
desired certiﬁcate 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 CU
users.

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 oﬃcers (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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

82

AWS CloudHSM User Guide
Reference

User Type
The following users can run this command.
• Crypto oﬃcers (CO)
• Crypto users (CU)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
changePswd   

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 ﬁrst 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
LoginState
0
10.0.3.10
10.0.3.10
in as 'bob(CU)'
aws-cloudhsm> info server 1
Id
Name
Hostname
LoginState
0
10.0.3.10
10.0.3.10
in as 'bob(CU)'

Port

State

Partition

2225

Connected

hsm-aaaabbbbccc

Port

State

Partition

2225

Connected

hsm-ccccaaaabbb

Logged

Logged

To change his password, bob runs changePswd with a new password, newPasswerd.
When the command completes, the password change is eﬀective.
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 diﬀerent user. Any crypto oﬃcer (CO, PCO) can
change the password of any user on the HSMs without specifying the existing password.

83

AWS CloudHSM User Guide
Reference

The ﬁrst command uses info (p. 102) to conﬁrm that alice, a CO, is logged into the HSMs in the
cluster.
aws-cloudhsm>info server 0
Id
Name
Hostname
LoginState
0
10.0.3.10
10.0.3.10
as 'alice(CO)'
aws-cloudhsm>info server 1
Id
Name
Hostname
LoginState
0
10.0.3.10
10.0.3.10
as 'alice(CO)'

Port

State

Partition

2225

Connected

hsm-aaaabbbbccc

Port

State

Partition

2225

Connected

hsm-ccccaaaabbb

Logged in

Logged in

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 ﬁctitious
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
speciﬁed in the syntax diagram.
changePswd    [1FA | 2FA]


Speciﬁes 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

Speciﬁes the user's friendly name. This parameter is not case-sensitive. You cannot use changePswd
to change the user name.
Required: Yes

Speciﬁes 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 conﬁgured 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 oﬃcers (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.
However, if your HSM conﬁguration is inaccurate, the user might not be created on all HSMs. To add the
user to any HSMs in which it is missing, use the createUser command only on the HSMs that are missing
that user. To prevent conﬁguration errors, run the conﬁgure tool with the -m option.
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.
• Crypto oﬃcers (CO, PCO)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
User Type: Crypto oﬃcer (CO, PCO)
createUser    [1FA | 2FA]

Examples
These examples show how to use createUser to create new users in your HSMs.

85

AWS CloudHSM User Guide
Reference

Example : Create a Crypto Oﬃcer
This example creates a crypto oﬃcer (CO) on the HSMs in a cluster. The ﬁrst command uses loginHSM to
log in to the HSM as a crypto oﬃcer.
aws-cloudhsm> loginHSM CO admin 735782961
loginHSM success on server 0(10.0.0.1)
loginHSM success on server 1(10.0.0.2)
loginHSM success on server 1(10.0.0.3)

The second command uses the createUser command to create alice, a new crypto oﬃcer on the HSM.
The caution message explains that the command creates users on all of the HSMs in the cluster. But, if
the command fails on any HSMs, the user will not exist on those HSMs. To continue, type y.
The output shows that the new user was created on all three HSMs in the cluster.
aws-cloudhsm> createUser CO alice 391019314
*************************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)?Invalid option, please type 'y' or 'n'
Do you want to continue(y/n)?y
Creating User alice(CO) on 3 nodes

When the command completes, alice has the same permissions on the HSM as the admin CO user,
including changing the password of any user on the HSMs.
The ﬁnal command uses the listUsers (p. 105) command to verify that alice exists on all three HSMs
on the cluster. The output also shows that alice is assigned user ID 3.. You use the user ID to identify
alice in other commands, such as ﬁndAllKeys (p. 91).
aws-cloudhsm> listUsers
Users on server 0(10.0.0.1):
Number of users found:3
User Id
User Type
LoginFailureCnt
2FA
1
PCO
0
NO
2
AU
0
NO
3
CO
0
NO
Users on server 1(10.0.0.2):
Number of users found:3
User Id
LoginFailureCnt
1
0
2
0
3
0

User Type
2FA
PCO
NO
AU
NO
CO
NO

User Name
admin

MofnPubKey
YES

app_user

NO

alice

NO

User Name
admin

MofnPubKey
YES

app_user

NO

alice

NO

86

AWS CloudHSM User Guide
Reference

Users on server 1(10.0.0.3):
Number of users found:3
User Id
LoginFailureCnt
1
0
2
0
3
0

User Type
2FA
PCO
NO
AU
NO
CO
NO

User Name
admin

MofnPubKey
YES

app_user

NO

alice

NO

Example : Create a Crypto User
This example creates a crypto user (CU), bob, on the HSM. Crypto users can create and manage keys, but
they cannot manage users.
After you type y to respond to the caution message, the output shows that bob was created on all three
HSMs in the cluster. The new CU can log in to the HSM to create and manage keys.
The command used a password value of defaultPassword. Later, bob or any CO can use the
changePswd (p. 82) command to change his password.
aws-cloudhsm> createUser CU bob 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)?Invalid option, please type 'y' or 'n'
Do you want to continue(y/n)?y
Creating User bob(CU) on 3 nodes

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
createUser    [ 1FA | 2FA ]


Speciﬁes the type of user. This parameter is required.
For detailed information about the user types on an HSM, see HSM Users (p. 10).
Valid values:
• CO: Crypto oﬃcers can manage users, but they cannot manage keys.
• CU: Crypto users can create an manage keys and use keys in cryptographic operations.
• AU: Appliance users can clone and synchronize operations. One AU is created for you on each HSM
that you install.
PCO, PRECO, and preCO are also valid values, but they are rarely used. A PCO is functionally identical
to a CO user. A PRECO user is a temporary type that is created automatically on each HSM. The
PRECO is converted to a PCO when you assign a password during HSM activation (p. 38).

87

AWS CloudHSM User Guide
Reference

Required: Yes

Speciﬁes a friendly name for the user. The maximum length is 31 characters. The only special
character permitted is an underscore ( _ ).
You cannot change the name of a user after it is created. In cloudhsm_mgmt_util commands, the
user type and password are case-sensitive, but the user name is not.
Required: Yes

Speciﬁes a 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.
To change a user password, use changePswd. Any HSM user can change their own password, but CO
users can change the password of any user (of any type) on the HSMs.
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 conﬁgured for dual-factor authentication.
Required: No
Default: 1FA: Dual factor authentication is not enabled.

Related Topics
• listUsers (p. 105)
• deleteUser (p. 88)
• changePswd (p. 82)

deleteUser
The deleteUser command in cloudhsm_mgmt_util deletes a user from the HSMs. Only crypto oﬃcers
(COs and PCOs) can run this command, but any CO user can delete any user of any type from the HSMs.
However, you cannot delete a user who is logged into the AWS CloudHSM client, key_mgmt_util, or
cloudhsm_mgmt_util.

Warning

When you delete a crypto user (CU), all keys that the user owned are deleted, even if the keys
were shared with other users. To make accidental or malicious deletion of users less likely, use
quorum authentication (p. 66).
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.

88

AWS CloudHSM User Guide
Reference

• Crypto oﬃcers (CO, PCO)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
deleteUser  

Example
This example deletes a crypto oﬃcer (CO) from the HSMs in a cluster. The ﬁrst command uses listUsers
to list all users on the HSMs.
The output shows that user 3, alice, is a CO on the HSMs.
aws-cloudhsm> listUsers
Users on server 0(10.0.0.1):
Number of users found:3
User Id
User Type
LoginFailureCnt
2FA
1
PCO
0
NO
2
AU
0
NO
3
CO
0
NO
Users on server 1(10.0.0.2):
Number of users found:3
User Id
LoginFailureCnt
1
0
2
0
3
0

User Name
admin

User Type
2FA
PCO
NO
AU
NO
CO
NO

MofnPubKey
YES

app_user

NO

alice

NO

User Name
admin

MofnPubKey
YES

app_user

NO

alice

NO

Users on server 1(10.0.0.3):
Number of users found:3
User Id
LoginFailureCnt
1
0
2
0
3
0

User Type
2FA
PCO
NO
AU
NO
CO
NO

User Name
admin

MofnPubKey
YES

app_user

NO

alice

NO

The second command uses the deleteUser command to delete alice from the HSMs.
The output shows that the command succeeded on all three HSMs in the cluster.
aws-cloudhsm> deleteUser CO alice
Deleting user alice(CO) on 3 nodes
deleteUser success on server 0(10.0.0.1)
deleteUser success on server 0(10.0.0.2)

89

AWS CloudHSM User Guide
Reference
deleteUser success on server 0(10.0.0.3)

The ﬁnal command uses the listUsers (p. 105) command to verify that alice is deleted from all three
of the HSMs on the cluster.
aws-cloudhsm> listUsers
Users on server 0(10.0.0.1):
Number of users found:2
User Id
User Type
LoginFailureCnt
2FA
1
PCO
0
NO
2
AU
0
NO
Users on server 1(10.0.0.2):
Number of users found:2

User Name

User Id
User Type
LoginFailureCnt
2FA
1
PCO
0
NO
2
AU
0
NO
Users on server 1(10.0.0.3):
Number of users found:2

User Name

User Id
LoginFailureCnt
1
0
2
0

User Type
2FA
PCO
NO
AU
NO

admin
app_user

admin
app_user

User Name
admin
app_user

MofnPubKey
YES
NO

MofnPubKey
YES
NO

MofnPubKey
YES
NO

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
deleteUser  


Speciﬁes the type of user. This parameter is required.

Warning

When you delete a crypto user (CU), all keys that the user owned are deleted, even if the
keys were shared with other users. To make accidental or malicious deletion of users less
likely, use quorum authentication (p. 66).
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

Speciﬁes a friendly name for the user. The maximum length is 31 characters. The only special
character permitted is an underscore ( _ ).

90

AWS CloudHSM User Guide
Reference

You cannot change the name of a user after it is created. In cloudhsm_mgmt_util commands, the
user type and password are case-sensitive, but the user name is not.
Required: Yes

Related Topics
• listUsers (p. 105)
• createUser (p. 85)
• syncUser
• changePswd (p. 82)

ﬁndAllKeys
The findAllKeys command in cloudhsm_mgmt_util gets the keys that a speciﬁed crypto user (CU)
owns or shares. It also returns a hash of the user data on each of the HSMs. You can use the hash to
determine at a glance whether the users, key ownership, and key sharing data are the same on all HSMs
in the cluster.
findAllKeys returns public keys only when the speciﬁed CU owns the key, even though all CUs on the
HSM can use any public key. This behavior is diﬀerent from ﬁndKey (p. 133) in key_mgmt_util, which
returns public keys for all CU users.
Only crypto oﬃcers (COs and PCOs) and appliance users (AUs) can run this command. Crypto users (CUs)
can run the following commands:
• listUsers (p. 105) to ﬁnd all users
• ﬁndKey (p. 133) in key_mgmt_util to ﬁnd the keys that they can use
• getKeyInfo (p. 159) in key_mgmt_util to ﬁnd the owner and shared users of a particular key they own
or share
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following users can run this command.
• Crypto oﬃcers (CO, PCO)
• Appliance users (AU)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
findAllKeys   []

91

AWS CloudHSM User Guide
Reference

Examples
These examples show how to use findAllKeys to ﬁnd all keys for a user and get a hash of key user
information on each of the HSMs.

Example : Find the Keys for a CU
This example uses findAllKeys to ﬁnd the keys in the HSMs that user 4 owns and shares. The
command uses a value of 0 for the second argument to suppress the hash value. Because it omits the
optional ﬁle name, the command writes to stdout (standard output).
The output shows that user 4 can use 6 keys: 8, 9, 17, 262162, 19, and 31. The output uses an (s) to
indicate that keys 8, 9, and 262162 are explicitly shared, although it does not indicate whether user 4
owns or shares them. The keys that are not marked with (s) include symmetric and private keys that the
user 4 owns and does not share, and public keys that are available to all crypto users.
aws-cloudhsm> findAllKeys 4 0
Keys on server 0(10.0.0.1):
Number of keys found 6
number of keys matched from start index 0::6
8(s),9(s),17,262162(s),19,31
findAllKeys success on server 0(10.0.0.1)
Keys on server 1(10.0.0.2):
Number of keys found 6
number of keys matched from start index 0::6
8(s),9(s),17,262162(s),19,31
findAllKeys success on server 1(10.0.0.2)
Keys on server 1(10.0.0.3):
Number of keys found 6
number of keys matched from start index 0::6
8(s),9(s),17,262162(s),19,31
findAllKeys success on server 1(10.0.0.3)

Example : Verify That User Data Is Synchronized
This example uses findAllKeys to verify that all of the HSMs in the cluster contain the same users,
key ownership, and key sharing values. To do this, it gets a hash of the key user data on each HSM and
compares the hash values.
To get the key hash, the command uses a value of 1 in the second argument. The optional ﬁle name is
omitted, so the command writes the key hash to stdout.
The example speciﬁes user 6, but the hash value will be the same for any user that owns or shares any of
the keys on the HSMs. If the speciﬁed user does not own or share any keys, such as a CO, the command
does not return a hash value.
The output shows that the key hash is identical to both of the HSMs in the cluster. If one of the HSM had
diﬀerent users, diﬀerent key owners, or diﬀerent shared users, the key hash values would not be equal.
aws-cloudhsm> findAllKeys 6 1
Keys on server 0(10.0.0.1):
Number of keys found 3
number of keys matched from start index 0::3
8(s),9(s),11,17(s)
Key Hash:
55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49
findAllKeys success on server 0(10.0.0.1)

92

AWS CloudHSM User Guide
Reference
Keys on server 1(10.0.0.2):
Number of keys found 3
number of keys matched from start index 0::3
8(s),9(s),11,17(s)
Key Hash:
55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49
findAllKeys success on server 1(10.0.0.2)

This command demonstrates that the hash value represents the user data for all keys on the HSM. The
command uses the findAllKeys for user 3. Unlike user 6, who owns or shares just 3 keys, user 3 own or
shares 17 keys, but the key hash value is the same.
aws-cloudhsm> findAllKeys 3 1
Keys on server 0(10.0.0.1):
Number of keys found 17
number of keys matched from start index 0::17
6,7,8(s),11,12,14,262159,262160,17(s),262162(s),19(s),20,21,262177,262179,262180,262181
Key Hash:
55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49
findAllKeys success on server 0(10.0.0.1)
Keys on server 1(10.0.0.2):
Number of keys found 17
number of keys matched from start index 0::17
6,7,8(s),11,12,14,262159,262160,17(s),262162(s),19(s),20,21,262177,262179,262180,262181
Key Hash:
55655676c95547fd4e82189a072ee1100eccfca6f10509077a0d6936a976bd49
findAllKeys success on server 1(10.0.0.2)

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
findAllKeys   []


Gets all keys that the speciﬁed user owns or shares. Enter the user ID of a user on the HSMs. To ﬁnd
the user IDs of all users, use listUsers (p. 105).
All user IDs are valid, but findAllKeys returns keys only for crypto users (CUs).
Required: Yes

Includes (1) or excludes (0) a hash of the user ownership and sharing data for all keys in each HSM.
When the user id argument represents a user who owns or shares keys, the key hash is populated.
The key hash value is identical for all users who own or share keys on the HSM, even though they
own and share diﬀerent keys. However, when the user id represents a user who does not own or
share any keys, such as a CO, the hash value is not populated.
Required: Yes

Writes the output to the speciﬁed ﬁle.

93

AWS CloudHSM User Guide
Reference

Required: No
Default: Stdout

Related Topics
• changePswd (p. 82)
• deleteUser (p. 88)
• listUsers (p. 105)
• syncUser
• ﬁndKey (p. 133) in key_mgmt_util
• getKeyInfo (p. 159) in key_mgmt_util

getAttribute
The getAttribute command in cloudhsm_mgmt_util gets one attribute value for a key from all HSMs
in the cluster and writes it to stdout (standard output) or to a ﬁle. Only crypto users (CUs) can run this
command.
Key attributes are properties of a key. They include characteristics, like the key type, class, label, and ID,
and values that represent actions that you can perform on the key, like encrypt, decrypt, wrap, sign, and
verify.
You can use getAttribute only on keys that you own and key that are shared with you. You can run
this command or the getAttribute (p. 94) command in key_mgmt_util, which writes one or all of the
attribute values of a key to a ﬁle.
To get a list of attributes and the constants that represent them, use the listAttributes (p. 168)
command. To change the attribute values of existing keys, use setAttribute (p. 170) in key_mgmt_util
and setAttribute (p. 109) in cloudhsm_mgmt_util. For help interpreting the key attributes, see the Key
Attribute Reference (p. 176).
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following users can run this command.
• Crypto users (CU)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
getAttribute   []

94

AWS CloudHSM User Guide
Reference

Example
This example gets the value of the extractable attribute for a key in the HSMs. You can use a command
like this to determine whether you can export a key from the HSMs.
The ﬁrst command uses listAttributes to ﬁnd the constant that represents the extractable attribute.
The output shows that the constant for OBJ_ATTR_EXTRACTABLE is 354. You can also ﬁnd this
information with descriptions of the attributes and their values in the Key Attribute Reference (p. 176).
aws-cloudhsm> listAttributes
Following are the possible attribute values for getAttribute:
OBJ_ATTR_CLASS
OBJ_ATTR_TOKEN
OBJ_ATTR_PRIVATE
OBJ_ATTR_LABEL
OBJ_ATTR_KEY_TYPE
OBJ_ATTR_ENCRYPT
OBJ_ATTR_DECRYPT
OBJ_ATTR_WRAP
OBJ_ATTR_UNWRAP
OBJ_ATTR_SIGN
OBJ_ATTR_VERIFY
OBJ_ATTR_LOCAL
OBJ_ATTR_MODULUS
OBJ_ATTR_MODULUS_BITS
OBJ_ATTR_PUBLIC_EXPONENT
OBJ_ATTR_VALUE_LEN
OBJ_ATTR_EXTRACTABLE
OBJ_ATTR_KCV

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0
1
2
3
256
260
261
262
263
264
266
355
288
289
290
353
354
371

The second command uses getAttribute to get the value of the extractable attribute for the
key with key handle 262170 in the HSMs. To specify the extractable attribute, the command uses
354, the constant that represents the attribute. Because the command does not specify a ﬁle name,
getAttribute writes the output to stdout.
The output shows that the value of the extractable attribute is 1 on all of the HSM. This value indicates
that the owner of the key can export it. When the value is 0 (0x0), it cannot be exported from the HSMs.
You set the value of the extractable attribute when you create a key, but you cannot change it.
aws-cloudhsm> getAttribute 262170 354
Attribute Value on server 0(10.0.1.10):
OBJ_ATTR_EXTRACTABLE
0x00000001
Attribute Value on server 1(10.0.1.12):
OBJ_ATTR_EXTRACTABLE
0x00000001
Attribute Value on server 2(10.0.1.7):
OBJ_ATTR_EXTRACTABLE
0x00000001

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
getAttribute   []

95

AWS CloudHSM User Guide
Reference


Speciﬁes the key handle of the target key. You can specify only one key in each command. To get the
key handle of a key, use ﬁndKey (p. 133) in key_mgmt_util.
You must own the speciﬁed key or it must be shared with you. To ﬁnd the users of a key, use
getKeyInfo (p. 159) in key_mgmt_util.
Required: Yes

Identiﬁes the attribute. Enter a constant that represents an attribute, or 512, which represents
all attributes. For example, to get the key type, enter 256, which is the constant for the
OBJ_ATTR_KEY_TYPE attribute.
To list the attributes and their constants, use listAttributes (p. 168). For help interpreting the key
attributes, see the Key Attribute Reference (p. 176).
Required: Yes
<ﬁlename>
Writes the output to the speciﬁed ﬁle. Enter a ﬁle path.
If the speciﬁed ﬁle exists, getAttribute overwrites the ﬁle without warning.
Required: No
Default: Stdout

Related Topics
• getAttribute (p. 156) in key_mgmt_util
• listAttributes (p. 103)
• setAttribute (p. 109) in cloudhsm_mgmt_util
• setAttribute (p. 170) in key_mgmt_util
• Key Attribute Reference (p. 176)

getCert
With the getCert command in cloudhsm_mgmt_util, you can retrieve the certiﬁcates of a particular
HSM in a cluster. When you run the command, you designate the type of certiﬁcate to retrieve. To do
that, you use one of the corresponding integers as described in the Arguments (p. 97) section below.
To learn about the role of each of these certiﬁcates, see Verify HSM Identity (p. 25).
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following users can run this command.

96

AWS CloudHSM User Guide
Reference

• All users.

Prerequisites
Before you begin, you must enter server mode on the target HSM. For more information, see
server (p. 108).

Syntax
To use the getCert command once in server mode:
server> getCert  

Example
First, enter server mode. This command enters server mode on an HSM with server number 0.
aws-cloudhsm> server 0
Server is in 'E2' mode...

Then, use the getCert command. In this example, we use /tmp/PO.crt as the name of the ﬁle to
which the certiﬁcate will be saved and 4 (Customer Root Certiﬁcate) as the desired certiﬁcate type:
server0> getCert /tmp/PO.crt 4
getCert Success

Arguments
getCert  

<ﬁle-name>
Speciﬁes the name of the ﬁle to which the certiﬁcate is saved.
Required: Yes

An integer that speciﬁes the type of certiﬁcate to retrieve. The integers and their corresponding
certiﬁcate types are as follows:
• 1 – Manufacturer Root Certiﬁcate
• 2 – Manufacturer Hardware Certiﬁcate
• 4 – Customer Root Certiﬁcate
• 8 – Cluster Certiﬁcate (signed by Customer Root Certiﬁcate)
• 16 – Cluster Certiﬁcate (chained to the Manufacturer Root Certiﬁcate)
Required: Yes

Related Topics
• Start cloudhsm_mgmt_util (p. 78)
• server (p. 108)

97

AWS CloudHSM User Guide
Reference

getHSMInfo
The getHSMInfo command in cloudhsm_mgmt_util gets information about the hardware on which
each HSM runs, including the model, serial number, FIPS state, memory, temperature, and the
version numbers of the hardware and ﬁrmware. The information also includes the server ID that
cloudhsm_mgmt_util uses to refer to the HSM.
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.
• All users. You do not have to be logged in to run this command.

Syntax
This command has no parameters.
getHSMInfo

Example
This example uses getHSMInfo to get information about the HSMs in the cluster.
aws-cloudhsm> getHSMInfo
Getting HSM Info on 3 nodes
*** Server 0 HSM Info ***
Label
Model

:cavium
:NITROX-III CNN35XX-NFBE

Serial Number
HSM Flags
FIPS state

:3.0A0101-ICM000001
:0
:2 [FIPS mode with single factor authentication]

Manufacturer ID
Device ID
Class Code
System vendor ID
SubSystem ID

:
:10
:100000
:177D
:10

TotalPublicMemory
FreePublicMemory
TotalPrivateMemory
FreePrivateMemory

:560596
:294568
:0
:0

Hardware Major
Hardware Minor

:3
:0

Firmware Major
Firmware Minor

:2
:03

98

AWS CloudHSM User Guide
Reference

Temperature

:56 C

Build Number

:13

Firmware ID

:xxxxxxxxxxxxxxx

...

Related Topics
• info (p. 102)
• loginHSM

getKeyInfo
The getKeyInfo command in the key_mgmt_util returns the HSM user IDs of users who can use the key,
including the owner and crypto users (CU) with whom the key is shared. When quorum authentication
is enabled on a key, getKeyInfo also returns the number of users who must approve cryptographic
operations that use the key. You can run getKeyInfo only on keys that you own and keys that are shared
with you.
When you run getKeyInfo on public keys, getKeyInfo returns only the key owner, even though
all users of the HSM can use the public key. To ﬁnd the HSM user IDs of users in your HSMs, use
listUsers (p. 169). To ﬁnd the keys for a particular user, use ﬁndKey (p. 133) -u in key_mgmt_util.
Crypto oﬃcers can use ﬁndAllKeys (p. 91) in cloudhsm_mgmt_util.
You own the keys that you create. You can share a key with other users when you create it. Then, to share
or unshare an existing key, use shareKey (p. 112) in cloudhsm_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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.
• Crypto users (CU)

Syntax
getKeyInfo -k  []

Examples
These examples show how to use getKeyInfo to get information about the users of a key.

Example : Get the Users for an Asymmetric Key
This command gets the users who can use the AES (asymmetric) key with key handle 262162. The output
shows that user 3 owns the key and has shares it with users 4 and 6.

99

AWS CloudHSM User Guide
Reference

Only users 3, 4, and 6 can run getKeyInfo on key 262162.
aws-cloudhsm>getKeyInfo 262162
Key Info on server 0(10.0.0.1):
Token/Flash Key,
Owned by user 3
also, shared to following 2 user(s):
4
6
Key Info on server 1(10.0.0.2):
Token/Flash Key,
Owned by user 3
also, shared to following 2 user(s):
4
6

Example : Get the Users for a Symmetric Key Pair
These commands use getKeyInfo to get the users who can use the keys in an ECC (symmetric) key
pair (p. 151). The public key has key handle 262179. The private key has key handle 262177.
When you run getKeyInfo on the private key (262177), it returns the key owner (3) and crypto users
(CUs) 4, with whom the key is shared.
aws-cloudhsm>getKeyInfo -k 262177
Key Info on server 0(10.0.0.1):
Token/Flash Key,
Owned by user 3
also, shared to following 1 user(s):
4
Key Info on server 1(10.0.0.2):
Token/Flash Key,
Owned by user 3
also, shared to following 1 user(s):
4

When you run getKeyInfo on the public key (262179), it returns only the key owner, user 3.
aws-cloudhsm>getKeyInfo -k 262179
Key Info on server 0(10.0.3.10):
Token/Flash Key,
Owned by user 3
Key Info on server 1(10.0.3.6):

100

AWS CloudHSM User Guide
Reference

Token/Flash Key,
Owned by user 3

To conﬁrm that user 4 can use the public key (and all public keys on the HSM), use the -u parameter of
ﬁndKey (p. 133) in key_mgmt_util.
The output shows that user 4 can use both the public (262179) and private (262177) key in the key pair.
User 4 can also use all other public keys and any private keys that they have created or that have been
shared with them.
Command:

findKey -u 4

Total number of keys present 8
number of keys matched from start index 0::7
11, 12, 262159, 262161, 262162, 19, 20, 21, 262177, 262179
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Example : Get the Quorum Authentication Value (m_value) for a Key
This example shows how to get the m_value for a key. The m_value is the number of users in the
quorum who must approve any cryptographic operations that use the key and operations to share the
unshare the key.
When quorum authentication is enabled on a key, a quorum of users must approve any cryptographic
operations that use the key. To enable quorum authentication and set the quorum size, use the m_value parameter when you create the key.
This command uses genSymKey (p. 151) to create a 256-bit AES key that is shared with user 4. It uses
the m_value parameter to enable quorum authentication and set the quorum size to two users. The
number of users must be large enough to provide the required approvals.
The output shows that the command created key 10.
Command:

genSymKey -t 31 -s 32 -l aes256m2 -u 4 -m_value 2

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created.

Key Handle: 10

Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

This command uses getKeyInfo in cloudhsm_mgmt_util to get information about the users of key 10.
The output shows that the key is owned by user 3 and shared with user 4. It also shows that a quorum of
two users must approve every cryptographic operation that uses the key.
aws-cloudhsm>getKeyInfo 10
Key Info on server 0(10.0.0.1):
Token/Flash Key,

101

AWS CloudHSM User Guide
Reference
Owned by user 3
also, shared to following 1 user(s):
4
2 Users need to approve to use/manage this key
Key Info on server 1(10.0.0.2):
Token/Flash Key,
Owned by user 3
also, shared to following 1 user(s):
4
2 Users need to approve to use/manage this key

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
getKeyInfo -k  


Speciﬁes the key handle of one key in the HSM. Enter the key handle of a key that you own or share.
This parameter is required.
Required: Yes

Writes the output to the speciﬁed ﬁle, instead of stdout. If the ﬁle exists, the command overwrites it
without warning.
Required: No
Default: stdout

Related Topics
• getKeyInfo (p. 159) in key_mgmt_util
• ﬁndKey (p. 133) in key_mgmt_util
• ﬁndAllKeys (p. 91) in cloudhsm_mgmt_util
• listUsers (p. 105)
• shareKey (p. 112)

info
The info command in cloudhsm_mgmt_util gets information about each of the HSMs in the cluster,
including the host name, port, IP address and the name and type of the user who is logged in to
cloudhsm_mgmt_util on the HSM.
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.

102

AWS CloudHSM User Guide
Reference

If you add or delete HSMs, update the conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.
• All users. You do not have to be logged in to run this command.

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
info server 

Example
This example uses info to get information about an HSM in the cluster. The command uses 0 to refer to
the ﬁrst HSM in the cluster. The output shows the IP address, port, and the type and name of the current
user.
aws-cloudhsm> info server 0
Id
Name
Hostname
LoginState
0
10.0.0.1
10.0.0.1
Logged in as 'testuser(CU)'

Port
2225

State

Partition

Connected

hsm-udw0tkfg1ab

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
info server 


Speciﬁes the server ID of the HSM. The HSMs are assigned ordinal numbers that represent the
order in which they are added to the cluster, beginning with 0. To ﬁnd the server ID of an HSM, use
getHSMInfo.
Required: Yes

Related Topics
• getHSMInfo (p. 98)
• loginHSM and logoutHSM (p. 106)

listAttributes
The listAttributes command in cloudhsm_mgmt_util lists the attributes of an AWS CloudHSM
key and the constants that represent them. You use these constants to identify the attributes in
getAttribute (p. 94) and setAttribute (p. 109) commands.

103

AWS CloudHSM User Guide
Reference

For help interpreting the key attributes, see the Key Attribute Reference (p. 176).
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

User Type
The following users can run this command.
• All users. You do not have to be logged in to run this command.

Syntax
listAttributes [-h]

Example
This command lists the key attributes that you can get and change in key_mgmt_util and the constants
that represent them. For help interpreting the key attributes, see the Key Attribute Reference (p. 176).
To represent all attributes, use 512.
Command: listAttributes
Description
===========
The following are all of the possible attribute values for getAttribute.
OBJ_ATTR_CLASS
OBJ_ATTR_TOKEN
OBJ_ATTR_PRIVATE
OBJ_ATTR_LABEL
OBJ_ATTR_KEY_TYPE
OBJ_ATTR_ID
OBJ_ATTR_SENSITIVE
OBJ_ATTR_ENCRYPT
OBJ_ATTR_DECRYPT
OBJ_ATTR_WRAP
OBJ_ATTR_UNWRAP
OBJ_ATTR_SIGN
OBJ_ATTR_VERIFY
OBJ_ATTR_LOCAL
OBJ_ATTR_MODULUS
OBJ_ATTR_MODULUS_BITS
OBJ_ATTR_PUBLIC_EXPONENT
OBJ_ATTR_VALUE_LEN
OBJ_ATTR_EXTRACTABLE
OBJ_ATTR_KCV

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0
1
2
3
256
258
259
260
261
262
263
264
266
355
288
289
290
353
354
371

Parameters
-h
Displays help for the command.
Required: Yes

Related Topics
• getAttribute (p. 94)

104

AWS CloudHSM User Guide
Reference

• setAttribute (p. 109)
• Key Attribute Reference (p. 176)

listUsers
The listUsers command in the cloudhsm_mgmt_util gets the users in each of the HSMs, along with their
user type and other attributes. All types of users can run this command. You do not even need to be
logged in to cloudhsm_mgmt_util to run this command.
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.
• All users. You do not need to be logged in to run this command.

Syntax
This command has no parameters.
listUsers

Example
This command lists the users on each of the HSMs in the cluster and displays their attributes. You can
use the User ID attribute to identify users in other commands, such as deleteUser, changePswd, and
ﬁndAllKeys.
aws-cloudhsm> listUsers
Users on server 0(10.0.0.1):
Number of users found:6
User Id
User Type
2FA
1
PCO
NO
2
AU
NO
3
CU
NO
4
CU
NO
5
CO
NO
6
CO
NO
Users on server 1(10.0.0.2):
Number of users found:5
User Id
2FA

User Type

User Name
admin

MofnPubKey

LoginFailureCnt

YES

0

app_user

NO

0

crypto_user1

NO

0

crypto_user2

NO

0

officer1

YES

0

officer2

NO

0

User Name

105

MofnPubKey

LoginFailureCnt

AWS CloudHSM User Guide
Reference
1
NO
2
NO
3
NO
4
NO
5
NO

PCO

admin

YES

0

AU

app_user

NO

0

CU

crypto_user1

NO

0

CU

crypto_user2

NO

0

CO

officer1

YES

0

The output includes the following user attributes:
• User ID: Identiﬁes the user in key_mgmt_util and cloudhsm_mgmt_util (p. 74) commands.
• User type (p. 10): Determines the operations that the user can perform on the HSM.
• User Name: Displays the user-deﬁned friendly name for the user.
• MofnPubKey: Indicates whether the user has registered a key pair for signing quorum authentication
tokens (p. 61).
• LoginFailureCnt: Indicates the number of times the user has unsuccessfully logged in.
• 2FA: Indicates that the user has enabled multi-factor authentication.

Related Topics
• listUsers (p. 169) in key_mgmt_util
• createUser (p. 85)
• deleteUser (p. 88)
• changePswd (p. 82)

loginHSM and logoutHSM
You can use the loginHSM and logoutHSM commands in cloudhsm_mgmt_util to log in and out of each
HSM in a cluster. Any user of any type can use these commands.
Before you run these cloudhsm_mgmt_util commands, you must start cloudhsm_mgmt_util (p. 78).
If you add or delete HSMs, update the conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective on all HSMs in
the cluster.

User Type
The following users can run these commands.
• Precrypto oﬃcer (PRECO)
• Crypto oﬃcer (CO)
• Crypto user (CU)
• Appliance user (AU)

Syntax
Because these commands do not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagrams.

106

AWS CloudHSM User Guide
Reference

loginHSM   

logoutHSM

Examples
These examples show how to use loginHSM and logoutHSM to log in and out of all HSMs in a cluster.

Example : Log In to the HSMs in a Cluster
This command logs in to all HSMs in a cluster with the credentials of a CO user named admin and
a password of co12345. The output shows that the command was successful and that the user has
connected to the HSMs (which, in this case, are server 0 and server 1).
aws-cloudhsm>loginHSM CO admin co12345
loginHSM success on server 0(10.0.2.9)
loginHSM success on server 1(10.0.3.11)

Example : Log Out of an HSM
This command logs out of the HSMs that you are currently logged in to (which, in this case, are
server 0 and server 1). The output shows that the command was successful and that the user has
disconnected from the HSMs.
aws-cloudhsm>logoutHSM
logoutHSM success on server 0(10.0.2.9)
logoutHSM success on server 1(10.0.3.11)

Arguments
Because these commands do not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagrams.
loginHSM   


Speciﬁes the type of user who is logging in to the HSMs. For more information, see User
Type (p. 106) above.
Required: Yes

Speciﬁes the user name of the user who is logging in to the HSMs.
Required: Yes

Speciﬁes the password of the user who is logging in to the HSMs.

107

AWS CloudHSM User Guide
Reference

Required: Yes

Related Topics
• Getting Started with cloudhsm_mgmt_util (p. 75)
• Activate the Cluster (p. 38)

server
Normally, when you issue a command in cloudhsm_mgmt_util, the command eﬀects all HSMs in the
designated cluster (global mode). However, there may be circumstances for which you need to issue
commands to a single HSM. For instance, in the event that automatic synchronization fails, you may
need to sync keys and users on an HSM in order to maintain consistency across the cluster. You can use
the server command in the cloudhsm_mgmt_util to enter server mode and interact directly with a
particular HSM instance.
Upon successful initiation, the aws-cloudhsm> command prompt is replaced with the server>
command prompt.
In order to exit server mode, use the exit command. Upon successful exit, you will be returned to the
cloudhsm_mgmt_util command prompt.
Before you run any cloudhsm_mgmt_util command, you must start cloudhsm_mgmt_util (p. 78).

User Type
The following users can run this command.
• All users.

Prerequisites
In order to enter server mode, you must ﬁrst know the server number of the target HSM. Server numbers
are listed in the trace output generated by cloudhsm_mgmt_util upon initiation. Server numbers are
assigned in the same order that the HSMs appear in the conﬁguration ﬁle. For this example, we assume
that server 0 is the server that corresponds to the desired HSM.

Syntax
To start server mode:
server 

To exit server mode:
server> exit

Example
This command enters server mode on an HSM with server number 0.
aws-cloudhsm> server 0

108

AWS CloudHSM User Guide
Reference
Server is in 'E2' mode...

In order to exit server mode, use the exit command.
server0> exit

Arguments
server 


Speciﬁes the server number of the target HSM.
Required: Yes
There are no arguments for the exit command.

Related Topics
• Start cloudhsm_mgmt_util (p. 78)
• syncKey (p. 115)
• createUser (p. 85)
• deleteUser (p. 88)

setAttribute
The setAttribute command in cloudhsm_mgmt_util changes the value of the label, encrypt, decrypt,
wrap, and unwrap attributes of a key in the HSMs. You can also use the setAttribute (p. 170) command
in key_mgmt_util to convert a session key to a persistent key. You can only change the attributes of keys
that you own.
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 conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following users can run this command.
• Crypto users (CU)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
setAttribute  

109

AWS CloudHSM User Guide
Reference

Example
This example shows how to disable the decrypt functionality of a symmetric key. You can use a command
like this one to conﬁgure a wrapping key, which should be able to wrap and unwrap other keys but not
encrypt or decrypt data.
The ﬁrst step is to create the wrapping key. This command uses genSymKey (p. 151) in key_mgmt_util
to generate a 256-bit AES symmetric key. The output shows that the new key has key handle 14.
$

genSymKey -t 31 -s 32 -l aes256

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created.

Key Handle: 14

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Next, we want to conﬁrm the current value of the decrypt attribute. To get the attribute ID of the
decrypt attribute, use listAttributes (p. 103). The output shows that the constant that represents the
OBJ_ATTR_DECRYPT attribute is 261. For help interpreting the key attributes, see the Key Attribute
Reference (p. 176).
aws-cloudhsm> listAttributes
Following are the possible attribute values for getAttribute:
OBJ_ATTR_CLASS
OBJ_ATTR_TOKEN
OBJ_ATTR_PRIVATE
OBJ_ATTR_LABEL
OBJ_ATTR_KEY_TYPE
OBJ_ATTR_ENCRYPT
OBJ_ATTR_DECRYPT
OBJ_ATTR_WRAP
OBJ_ATTR_UNWRAP
OBJ_ATTR_SIGN
OBJ_ATTR_VERIFY
OBJ_ATTR_LOCAL
OBJ_ATTR_MODULUS
OBJ_ATTR_MODULUS_BITS
OBJ_ATTR_PUBLIC_EXPONENT
OBJ_ATTR_VALUE_LEN
OBJ_ATTR_EXTRACTABLE
OBJ_ATTR_KCV

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0
1
2
3
256
260
261
262
263
264
266
355
288
289
290
353
354
371

To get the current value of the decrypt attribute for key 14, the next command uses
getAttribute (p. 94) in cloudhsm_mgmt_util.
The output shows that the value of the decrypt attribute is true (1) on both HSMs in the cluster.
aws-cloudhsm> getAttribute 14 261
Attribute Value on server 0(10.0.0.1):
OBJ_ATTR_DECRYPT
0x00000001
Attribute Value on server 1(10.0.0.2):
OBJ_ATTR_DECRYPT
0x00000001

110

AWS CloudHSM User Guide
Reference

This command uses setAttribute to change the value of the decrypt attribute (attribute 261) of key
14 to 0. This disables the decrypt functionality on the key.
The output shows that the command succeeded on both HSMs in the cluster.
aws-cloudhsm> setAttribute 14 261 0
*************************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
setAttribute success on server 0(10.0.0.1)
setAttribute success on server 1(10.0.0.2)

The ﬁnal command repeats the getAttribute command. Again, it gets the decrypt attribute (attribute
261) of key 14.
This time, the output shows that the value of the decrypt attribute is false (0) on both HSMs in the
cluster.
aws-cloudhsm>getAttribute 14 261
Attribute Value on server 0(10.0.3.6):
OBJ_ATTR_DECRYPT
0x00000000
Attribute Value on server 1(10.0.1.7):
OBJ_ATTR_DECRYPT
0x00000000

Arguments
setAttribute  


Speciﬁes the key handle of a key that you own. You can specify only one key in each command. To
get the key handle of a key, use ﬁndKey (p. 133) in key_mgmt_util. To ﬁnd the users of a key, use
getKeyInfo (p. 99).
Required: Yes

Speciﬁes the constant that represents the attribute that you want to change. You can
specify only one attribute in each command. To get the attributes and their integer values,
use listAttributes (p. 168). For help interpreting the key attributes, see the Key Attribute
Reference (p. 176).
Valid values:
• 3 – OBJ_ATTR_LABEL.
• 260 – OBJ_ATTR_ENCRYPT.
• 261 – OBJ_ATTR_DECRYPT.
• 262 – OBJ_ATTR_WRAP.
• 263 – OBJ_ATTR_UNWRAP.
Required: Yes

111

AWS CloudHSM User Guide
Reference

Related Topics
• setAttribute (p. 170) in key_mgmt_util
• getAttribute (p. 94)
• listAttributes (p. 103)
• Key Attribute Reference (p. 176)

quit
The quit command in the cloudhsm_mgmt_util exits the cloudhsm_mgmt_util. Any user of any type can
use this command.
Before you run any cloudhsm_mgmt_util command, you must start cloudhsm_mgmt_util (p. 78).

User Type
The following users can run this command.
• All users. You do not need to be logged in to run this command.

Syntax
quit

Example
This command exits cloudhsm_mgmt_util. Upon successful completion, you are returned to your regular
command line. This command has no output parameters.
aws-cloudhsm> quit
disconnecting from servers, please wait...

Related Topics
• Getting Started with cloudhsm_mgmt_util (p. 75)
• Start cloudhsm_mgmt_util (p. 78)

shareKey
The shareKey command in cloudhsm_mgmt_util shares and unshares keys that you own with other
crypto users. Only the key owner can share and unshare a key. You can also share a key when you create
it.
Users who share the key can use the key in cryptographic operations, but they cannot delete, export,
share, or unshare the key, or change its attributes. When quorum authentication is enabled on a key, the
quorum must approve any operations that share or unshare the key.
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.

112

AWS CloudHSM User Guide
Reference

If you add or delete HSMs, update the conﬁguration ﬁles (p. 75) that the AWS CloudHSM client and
the command line tools use. Otherwise, the changes that you make might not be eﬀective for all HSMs
in the cluster.

User Type
The following types of users can run this command.
• Crypto users (CU)

Syntax
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
User Type: Crypto user (CU)
shareKey   <(share/unshare key?) 1/0>

Example
The following examples show how to use shareKey to share and unshare keys that you own with other
crypto users.

Example : Share a Key
This example uses shareKey to share an ECC private key (p. 151) that the current user owns with
another crypto user on the HSMs. Public keys are available to all users of the HSM, so you cannot share
or unshare them.
The ﬁrst command uses getKeyInfo (p. 99) to get the user information for key 262177, an ECC private
key on the HSMs.
The output shows that key 262177 is owned by user 3, but is not shared.
aws-cloudhsm>getKeyInfo 262177
Key Info on server 0(10.0.3.10):
Token/Flash Key,
Owned by user 3
Key Info on server 1(10.0.3.6):
Token/Flash Key,
Owned by user 3

This example uses shareKey to share key 262177 with user 4, another crypto user on the HSMs. The ﬁnal
argument uses a value of 1 to indicate a share operation.
The output shows that the operation succeeded on both HSMs in the cluster.
aws-cloudhsm>shareKey 262177 4 1
*************************CAUTION********************************
This is a CRITICAL operation, should be done on all nodes in the

113

AWS CloudHSM User Guide
Reference
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
shareKey success on server 0(10.0.3.10)
shareKey success on server 1(10.0.3.6)

To verify that the operation succeeded, the example repeats the ﬁrst getKeyInfo command.
The output shows that key 262177 is now shared with user 4.
aws-cloudhsm>getKeyInfo 262177
Key Info on server 0(10.0.3.10):
Token/Flash Key,
Owned by user 3
also, shared to following 1 user(s):
4
Key Info on server 1(10.0.3.6):
Token/Flash Key,
Owned by user 3
also, shared to following 1 user(s):
4

Example : Unshare a Key
This example unshares a symmetric key, that is, it removes a crypto user from the list of shared users for
the key.
This command uses shareKey to remove user 4 from the list of shared users for key 6. The ﬁnal argument
uses a value of 0 to indicate an unshare operation.
The output shows that the command succeeded on both HSMs. As a result, user 4 can no longer use key
6 in cryptographic operations.
aws-cloudhsm>shareKey 6 4 0
*************************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
shareKey success on server 0(10.0.3.10)
shareKey success on server 1(10.0.3.6)

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.

114

AWS CloudHSM User Guide
Reference

shareKey   <(share/unshare key?) 1/0>


Speciﬁes the key handle of a key that you own. You can specify only one key in each command. To
get the key handle of a key, use ﬁndKey (p. 133) in key_mgmt_util. To verify that you own a key,
use getKeyInfo (p. 99).
Required: Yes

Speciﬁes the user ID the crypto user (CU) with whom you are sharing or unsharing the key. To ﬁnd
the user ID of a user, use listUsers (p. 105).
Required: Yes

To share the key with the speciﬁed user, type 1. To unshare the key, that is, to remove the speciﬁed
user from the list of shared users for the key, type 0.
Required: Yes

Related Topics
• getKeyInfo (p. 99)

syncKey
You can use the syncKey command in cloudhsm_mgmt_util to manually synchronize keys across HSM
instances within a cluster or across cloned clusters. In general, you will not need to use this command,
as HSM instances within a cluster sync keys automatically. However, key synchronization across cloned
clusters must be done manually. Cloned clusters are usually created in diﬀerent AWS Regions in order to
simplify the global scaling and disaster recovery processes.
You cannot use syncKey to synchronize keys across arbitrary clusters: one of the clusters must have
been created from a backup of the other. Additionally, both clusters must have consistent CO and CU
credentials in order for the operation to be successful. For more information, see HSM Users (p. 10).
To use syncKey, you must ﬁrst create an AWS CloudHSM conﬁguration ﬁle that speciﬁes one HSM from
the source cluster and one from the destination cluster. This will allow cloudhsm_mgmt_util to connect
to both HSM instances. Use this conﬁguration ﬁle to start cloudhsm_mgmt_util (p. 78). Then log
in (p. 80) with the credentials of a CO or a CU who owns the keys you want to synchronize. For further
instructions on how to create this conﬁguration ﬁle, see the conﬁguration ﬁle instructions (p. 118)
below.

User Type
The following types of users can run this command.
• Crypto oﬃcers (CO)
• Crypto users (CU)

Note

COs can use syncKey on any keys, while CUs can only use this command on keys that they own.
For more information, see

115

AWS CloudHSM User Guide
Precrypto Oﬃcer (PRECO)

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 Oﬃcer (PRECO) (p. 11)
• Crypto Oﬃcer (CO) (p. 11)
• Crypto User (CU) (p. 11)
• Appliance User (AU) (p. 11)
• HSM User Permissions Table (p. 11)

Precrypto Oﬃcer (PRECO)
The precrypto oﬃcer (PRECO) is a temporary user that exists only on the
ﬁrst HSM in an AWS CloudHSM cluster. The ﬁrst 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 oﬃcer (CO). The PRECO user can only change its own password and
perform read-only operations on the HSM.

Crypto Oﬃcer (CO)
A crypto oﬃcer (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
Oﬃcer (p. 11) (PRECO) to a crypto oﬃcer (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).

116

AWS CloudHSM User Guide
HSM User Permissions Table

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.
Get basic
cluster info¹

Yes

Yes

Yes

Yes

Zeroize an
HSM²

Yes

Yes

Yes

Yes

Change own
password

Yes

Yes

Yes

Not
applicable

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

Crypto
Oﬃcer (CO)

Crypto User
(CU)

Appliance
User (AU)

Unauthenticated
User

¹Basic cluster information includes the number of HSMs in the cluster and
each HSM's IP address, model, serial number, device ID, ﬁrmware ID, etc.
²When an HSM is zeroized, all keys, certiﬁcates, 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).

117

AWS CloudHSM User Guide
HSM User Permissions Table

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

(p. 10).

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

Prerequisites
Before you begin, you must know the key handle of the key on the source HSM to be synchronized
with the destination HSM. To ﬁnd the key handle, use the listUsers (p. 105) command to list all
identiﬁers for named users. Then, use the ﬁndAllKeys (p. 91) command to ﬁnd all keys that belong to
a particular user. In this example, we assume that the key handle to be synchronized is 261251.
You also need to know the server IDs assigned to the source and destination HSMs, which are shown
in the trace output returned by cloudhsm_mgmt_util upon initiation. These are assigned in the same
order that the HSMs appear in the conﬁguration ﬁle. For this example, we assume that server 0 is the
source HSM, and server 1 is the destination HSM.

Create a Conﬁguration File for syncKey Across Cloned Clusters
Create a copy of your current conﬁg ﬁle (/opt/cloudhsm/etc/cloudhsm_mgmt_config.cfg). For
this example, change the copy's name to clustersync.cfg.
Edit clustersync.cfg to include the Elastic Network Interface (ENI) IPs of the two HSMs to be synced.
We recommend that you specify the source HSM ﬁrst, followed by the destination HSM. To ﬁnd the ENI
IP of an HSM, use the describe-clusters CLI command.
Initialize cloudhsm_mgmt_util with the new conﬁg ﬁle by issuing the following command:
aws-cloudhsm> /opt/cloudhsm/bin/cloudhsm_mgmt_util /opt/cloudhsm/etc/clustersync.cfg

Check the status messages returned to ensure that the cloudhsm_mgmt_util is connected to both
HSMs and determine which of the returned ENI IPs corresponds to each cluster. Then, enter server mode
on the source HSM by issuing the server command. In this example, server 0 is the HSM instance from
the source cluster, and server 1 is the HSM instance from the destination cluster.

Syntax
Note

To run syncKey, ﬁrst enter server mode on the HSM, which contains the key to be synchronized.
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
User Type: Crypto user (CU)
syncKey  

Example
Run the server command to log into the source HSM and enter server mode.
aws-cloudhsm> server 0

118

AWS CloudHSM User Guide
key_mgmt_util

Now run the syncKey command.
aws-cloudhsm> syncKey 261251 1
syncKey success

Arguments
Because this command does not have named parameters, you must enter the arguments in the order
speciﬁed in the syntax diagram.
syncKey  


Speciﬁes the key handle of the key to sync. You can specify only one key in each command. To get
the key handle of a key, use ﬁndAllKeys (p. 91) while logged in to an HSM server.
Required: Yes

Speciﬁes the number of the server to which you are syncing a key.
Required: Yes

Related Topics
• listUsers (p. 105)
• ﬁndAllKeys (p. 91)
• describe-clusters in AWS CLI

key_mgmt_util
The key_mgmt_util command line tool helps Crypto Users (CU) manage keys in the HSMs. It includes
multiple commands that generate, delete, import, and export keys, get and set attributes, ﬁnd keys, and
perform cryptographic operations.
For a quick start, see Getting Started with key_mgmt_util (p. 119). For detailed information about the
commands, see key_mgmt_util Command Reference (p. 122). For help interpreting the key attributes,
see the Key Attribute Reference (p. 176).
To use key_mgmt_util if you are using Linux, connect to your client instance and then see Install and
Conﬁgure the AWS CloudHSM Client (Linux) (p. 35). If you are using Windows, see Install and Conﬁgure
the AWS CloudHSM Client (Windows) (p. 37).
Topics
• Getting Started with key_mgmt_util (p. 119)
• key_mgmt_util Command Reference (p. 122)

Getting Started with key_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

119

AWS CloudHSM User Guide
Getting Started

key_mgmt_util (p. 122)tool includes commands to manage keys. To get started with the
key_mgmt_util command line tool, see the following topics.
Topics
• Set Up key_mgmt_util (p. 120)
• Basic Usage of key_mgmt_util (p. 121)
If you encounter an error message or unexpected outcome for a command, see the Troubleshooting AWS
CloudHSM (p. 263) topics for help. For details about the key_mgmt_util commands, see key_mgmt_util
Command Reference (p. 122).

Set Up key_mgmt_util
Complete the following setup before you use key_mgmt_util.

Start the AWS CloudHSM Client
Before you use key_mgmt_util, you must start the AWS CloudHSM client. The client is a daemon that
establishes end-to-end encrypted communication with the HSMs in your cluster. The key_mgmt_util
tool uses the client connection to communicate with the HSMs in your cluster. Without it, key_mgmt_util
doesn't work.
To start the AWS CloudHSM client
Use the following command to start the AWS CloudHSM client.
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

120

AWS CloudHSM User Guide
Getting Started

Windows
C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:
\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg

Start key_mgmt_util
After you start the AWS CloudHSM client, use the following command to start key_mgmt_util.
Amazon Linux
$ /opt/cloudhsm/bin/key_mgmt_util

Amazon Linux 2
$ /opt/cloudhsm/bin/key_mgmt_util

RHEL 6
$ /opt/cloudhsm/bin/key_mgmt_util

RHEL 7
$ /opt/cloudhsm/bin/key_mgmt_util

CentOS 6
$ /opt/cloudhsm/bin/key_mgmt_util

CentOS 7
$ /opt/cloudhsm/bin/key_mgmt_util

Ubuntu 16.04 LTS
$ /opt/cloudhsm/bin/key_mgmt_util

Windows
c:\Program Files\Amazon\CloudHSM>key_mgmt_util.exe

The prompt changes to Command: when key_mgmt_util is running.
If the command fails, such as returning a Daemon socket connection error message, try updating
your conﬁguration ﬁle (p. 268).

Basic Usage of key_mgmt_util
See the following topics for the basic usage of the key_mgmt_util tool.
Topics

121

AWS CloudHSM User Guide
Reference

• Log In to the HSMs (p. 122)
• Log Out from the HSMs (p. 122)
• Stop key_mgmt_util (p. 122)

Log In to the HSMs
Use the loginHSM command to log in to the HSMs. The following command logs in as a crypto user
(CU) (p. 10) named example_user. The output indicates a successful login for all three HSMs in the
cluster.
Command: loginHSM -u CU -s example_user -p 
Cfm3LoginHSM returned: 0x00 : HSM Return: SUCCESS
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

The following shows the syntax for the loginHSM command.
Command:

loginHSM -u  -s  -p 

Log Out from the HSMs
Use the logoutHSM command to log out from the HSMs.
Command: logoutHSM
Cfm3LogoutHSM returned: 0x00 : HSM Return: SUCCESS
Cluster
Node id
Node id
Node id

Error
0 and
1 and
2 and

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

Stop key_mgmt_util
Use the exit command to stop key_mgmt_util.
Command:

exit

key_mgmt_util Command Reference
The key_mgmt_util command line tool helps you to manage keys in the HSMs in your cluster, including
creating, deleting, and ﬁnding keys and their attributes. It includes multiple commands, each of which is
described in detail in this topic.
For a quick start, see Getting Started with key_mgmt_util (p. 119). For help interpreting the key
attributes, see the Key Attribute Reference (p. 176). For information about the cloudhsm_mgmt_util
command line tool, which includes commands to manage the HSM and users in your cluster, see
cloudhsm_mgmt_util (p. 74).
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

122

AWS CloudHSM User Guide
Reference

To list all key_mgmt_util commands, type:
Command: help

To get help for a particular key_mgmt_util command, type:
Command:  -h

To end your key_mgmt_util session, type:
Command: exit

The following topics describe commands in key_mgmt_util.

Note

Some commands in key_mgmt_util and cloudhsm_mgmt_util have the same names. However,
the commands typically have diﬀerent syntax, diﬀerent output, and slightly diﬀerent
functionality.
Command

Description

aesWrapUnwrap (p. 124)

Encrypts and decrypts the contents of a key in a
ﬁle on disk.

deleteKey (p. 126)

Deletes a key from the HSMs.

Error2String (p. 128)

Gets the error that corresponds to a
key_mgmt_util hexadecimal error code.

exSymKey (p. 129)

Exports a plaintext copy of a symmetric key from
the HSMs to a ﬁle on disk.

ﬁndKey (p. 133)

Search for keys by key attribute value.

ﬁndSingleKey (p. 137)

Veriﬁes that a key exists on all HSMs in the cluster.

genDSAKeyPair (p. 137)

Generates a Digital Signing Algorithm (DSA) key
pair in your HSMs.

genECCKeyPair (p. 142)

Generates an Elliptic Curve Cryptography (ECC)
key pair in your HSMs.

genPBEKey (p. 146)

(This command is not supported on the FIPSvalidated HSMs.)

genRSAKeyPair (p. 146)

Generates an RSA asymmetric key pair in your
HSMs.

genSymKey (p. 151)

Generates a symmetric key in your HSMs

getAttribute (p. 156)

Gets the attribute values for an AWS CloudHSM
key and writes them to a ﬁle.

getKeyInfo (p. 159)

Gets the HSM user IDs of users who can use the
key.
If the key is quorum controlled, it gets the number
of users in the quorum.

123

AWS CloudHSM User Guide
Reference

Command

Description

imSymKey (p. 162)

Imports a plaintext copy of a symmetric key from
a ﬁle into the HSM.

listAttributes (p. 168)

Lists the attributes of an AWS CloudHSM key and
the constants that represent them.

listUsers (p. 169)

Gets the users in the HSMs, their user type and ID,
and other attributes.

setAttribute (p. 170)

Converts a session key to a persistent key.

unWrapKey (p. 172)

Imports a wrapped (encrypted) key from a ﬁle into
the HSMs.

wrapKey (p. 175)

Exports an encrypted copy of a key from the HSM
to a ﬁle on disk

aesWrapUnwrap
The aesWrapUnwrap command encrypts or decrypts the contents of a ﬁle on disk. This command is
designed to wrap and unwrap encryption keys, but you can use it on any ﬁle that contains less than 4 KB
(4096 bytes) of data.
aesWrapUnwrap uses AES Key Wrap. It uses an AES key on the HSM as the wrapping or unwrapping key.
Then it writes the result to another ﬁle on disk.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
aesWrapUnwrap -h
aesWrapUnwrap -m 
-f 
-w 
[-i ]
[-out ]

Examples
These examples show how to use aesWrapUnwrap to encrypt and decrypt an encryption key in a ﬁle.

Example : Wrap an Encryption Key
This command uses aesWrapUnwrap to wrap a Triple DES symmetric key that was exported from the
HSM in plaintext (p. 129) into the 3DES.key ﬁle. You can use a similar command to wrap any key saved
in a ﬁle.
The command uses the -m parameter with a value of 1 to indicate wrap mode. It uses the -w parameter
to specify an AES key in the HSM (key handle 6) as the wrapping key. It writes the resulting wrapped key
to the 3DES.key.wrapped ﬁle.
The output shows that the command was successful and that the operation used the default IV, which is
preferred.

124

AWS CloudHSM User Guide
Reference

Command:

aesWrapUnwrap -f 3DES.key -w 6 -m 1 -out 3DES.key.wrapped

Warning: IV (-i) is missing.
0xA6A6A6A6A6A6A6A6 is considered as default IV
result data:
49 49 E2 D0 11 C1 97 22
17 43 BD E3 4E F4 12 75
8D C1 34 CF 26 10 3A 8D
6D 0A 7B D5 D3 E8 4D C2
79 09 08 61 94 68 51 B7
result written to file 3DES.key.wrapped
Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

Example : Unwrap an Encryption Key
This example shows how to use aesWrapUnwrap to unwrap (decrypt) a wrapped (encrypted) key in a ﬁle.
You might want to do an operation like this one before importing a key to the HSM. For example, if you
try to use the imSymKey (p. 162) command to import an encrypted key, it returns an error because the
encrypted key doesn't have the format that is required for a plaintext key of that type.
The command unwraps the key in the 3DES.key.wrapped ﬁle and writes the plaintext to the
3DES.key.unwrapped ﬁle. The command uses the -m parameter with a value of 0 to indicate unwrap
mode. It uses the -w parameter to specify an AES key in the HSM (key handle 6) as the wrapping key. It
writes the resulting wrapped key to the 3DES.key.unwrapped ﬁle.
Command:

aesWrapUnwrap -m 0 -f 3DES.key.wrapped -w 6 -out 3DES.key.unwrapped

Warning: IV (-i) is missing.
0xA6A6A6A6A6A6A6A6 is considered as default IV
result data:
14 90 D7 AD D6 E4 F5 FA
A1 95 6F 24 89 79 F3 EE
37 21 E6 54 1F 3B 8D 62
result written to file 3DES.key.unwrapped
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS

Parameters
-h
Displays help for the command.
Required: Yes
-m
Speciﬁes the mode. To wrap (encrypt) the ﬁle content, type 1; to unwrap (decrypt) the ﬁle content,
type 0.
Required: Yes
-f
Speciﬁes the ﬁle to wrap. Enter a ﬁle that contains less than 4 KB (4096 bytes) of data. This
operation is designed to wrap and unwrap encryption keys.
Required: Yes

125

AWS CloudHSM User Guide
Reference

-w
Speciﬁes the wrapping key. Type the key handle of an AES key on the HSM. This parameter is
required. To ﬁnd key handles, use the ﬁndKey (p. 133) command.
To create a wrapping key, use genSymKey (p. 151) to create an AES key (type 31). To verify
that a key can be used as a wrapping key, use getAttribute (p. 156) to get the value of the
OBJ_ATTR_WRAP attribute, which is represented by constant 262.

Note

Key handle 4 represents an unsupported internal key. We recommend that you use an AES
key that you create and manage as the wrapping key.
Required: Yes
-i
Speciﬁes an alternate initial value (IV) for the algorithm. Use the default value unless you have a
special condition that requires an alternative.
Default: 0xA6A6A6A6A6A6A6A6. The default value is deﬁned in the AES Key Wrap algorithm
speciﬁcation.
Required: No
-out
Speciﬁes an alternate name for the output ﬁle that contains the wrapped or unwrapped key. The
default is wrapped_key (for wrap operations) and unwrapped_key (for unwrap operations) in the
local directory.
If the ﬁle exists, the aesWrapUnwrap overwrites it without warning. If the command fails,
aesWrapUnwrap creates an output ﬁle with no contents.
Default: For wrap: wrapped_key. For unwrap: unwrapped_key.
Required: No

Related Topics
• exSymKey (p. 129)
• imSymKey (p. 162)
• unWrapKey (p. 172)
• wrapKey (p. 175)

deleteKey
The deleteKey command in key_mgmt_util deletes a key from the HSM. You can only delete one key at a
time. Deleting one key in a key pair has no eﬀect on the other key in the pair.
Only the key owner can delete a key. Users who share the key can use it in cryptographic operations, but
not delete it.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
deleteKey -h

126

AWS CloudHSM User Guide
Reference

deleteKey -k

Examples
These examples show how to use deleteKey to delete keys from your HSMs.

Example : Delete a Key
This command deletes the key with key handle 6. When the command succeeds, deleteKey returns
success messages from each HSM in the cluster.
Command: deleteKey -k 6
Cfm3DeleteKey returned: 0x00 : HSM Return: SUCCESS
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

Example : Delete a Key (Failure)
When the command fails because no key has the speciﬁed key handle, deleteKey returns an invalid
object handle error message.
Command: deleteKey -k 252126
Cfm3FindKey returned: 0xa8 : HSM Error: Invalid object handle is passed to this
operation
Cluster Error Status
Node id 1 and err state 0x000000a8 : HSM Error: Invalid object handle is passed to
this operation
Node id 2 and err state 0x000000a8 : HSM Error: Invalid object handle is passed to
this operation

When the command fails because the current user is not the owner of the key, the command returns an
access denied error.
Command:

deleteKey -k 262152

Cfm3DeleteKey returned: 0xc6 : HSM Error: Key Access is denied.

Parameters
-h
Displays command line help for the command.
Required: Yes
-k
Speciﬁes the key handle of the key to delete. To ﬁnd the key handles of keys in the HSM, use
ﬁndKey (p. 133).
Required: Yes

127

AWS CloudHSM User Guide
Reference

Related Topics
• ﬁndKey (p. 133)

Error2String
The Error2String helper command in key_mgmt_util returns the error that corresponds to a
key_mgmt_util hexadecimal error code. You can use this command when troubleshooting your
commands and scripts.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
Error2String -h
Error2String -r 

Examples
These examples show how to use Error2String to get the error string for a key_mgmt_util error code.

Example : Get an Error Description
This command gets the error description for the 0xdb error code. The description explains that an
attempt to log in to key_mgmt_util failed because the user has the wrong user type. Only crypto users
(CU) can log in to key_mgmt_util.
Command:

Error2String -r 0xdb

Error Code db maps to HSM Error: Invalid User Type.

Example : Find the Error Code
This example shows where to ﬁnd the error code in a key_mgmt_util error. The error code, 0xc6, appears
after the string: Cfm3command-name returned: .
In this example, getKeyInfo (p. 159) indicates that the current user (user 4) can use the key in
cryptographic operations. Nevertheless, when the user tries to use deleteKey (p. 126) to delete the key,
the command returns error code 0xc6.

Command:

deleteKey -k 262162

Cfm3DeleteKey returned: 0xc6 : HSM Error: Key Access is denied
Cluster Error Status
Command:

getKeyInfo -k 262162

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3
also, shared to following 1 user(s):

128

AWS CloudHSM User Guide
Reference
4

If the 0xc6 error is reported to you, you can use an Error2String command like this one to look up the
error. In this case, the deleteKey command failed with an access denied error because the key is shared
with the current user but owned by a diﬀerent user. Only key owners have permission to delete a key.
Command:

Error2String -r 0xa8

Error Code c6 maps to HSM Error: Key Access is denied

Parameters
-h
Displays help for the command.
Required: Yes
-r
Speciﬁes a hexadecimal error code. The 0x hexadecimal indicator is required.
Required: Yes

exSymKey
The exSymKey command in the key_mgmt_util tool exports a plaintext copy of a symmetric
key from the HSM and saves it in a ﬁle on disk. To export an encrypted (wrapped) copy of a key,
use wrapKey (p. 175). To import a plaintext key, like the ones that exSymKey exports, use
imSymKey (p. 162).
During the export process, exSymKey uses an AES key that you specify (the wrapping key) to wrap
(encrypt) and then unwrap (decrypt) the key to be exported. However, the result of the export operation
is a plaintext (unwrapped) key on disk.
Only the owner of a key, that is, the CU user who created the key, can export it. Users who share the key
can use it in cryptographic operations, but they cannot export it.
The exSymKey operation copies the key material to a ﬁle that you specify, but it does not remove
the key from the HSM, change its key attributes (p. 176), or prevent you from using the key in
cryptographic operations. You can export the same key multiple times.
exSymKey exports only symmetric keys. To export public keys, use exPubKey. To export private keys, use
exportPrivateKey.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
exSymKey -h
exSymKey -k 
-w 
-out 
[-m 4]
[-wk  ]

129

AWS CloudHSM User Guide
Reference

Examples
These examples show how to use exSymKey to export symmetric keys that you own from your HSMs.

Example : Export a 3DES Symmetric Key
This command exports a Triple DES (3DES) symmetric key (key handle 7). It uses an existing AES key (key
handle 6) in the HSM as the wrapping key. Then it writes the plaintext of the 3DES key to the 3DES.key
ﬁle.
The output shows that key 7 (the 3DES key) was successfully wrapped and unwrapped, and then written
to the 3DES.key ﬁle.

Warning

Although the output says that a "Wrapped Symmetric Key" was written to the output ﬁle, the
output ﬁle contains a plaintext (unwrapped) key.
Command: exSymKey -k 7 -w 6 -out 3DES.key
Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "3DES.key"

Example : Exporting with Session-Only Wrapping Key
This example shows how to use a key that exists only in the session as the wrapping key. Because the key
to be exported is wrapped, immediately unwrapped, and delivered as plaintext, there is no need to retain
the wrapping key.
This series of commands exports an AES key with key handle 8 from the HSM. It uses an AES session key
created especially for the purpose.
The ﬁrst command uses genSymKey (p. 151) to create a 256-bit AES key. It uses the -sess parameter
to create a key that exists only in the current session.
The output shows that the HSM creates key 262168.
Command:

genSymKey -t 31 -s 32 -l AES-wrapping-key -sess

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created.

Key Handle: 262168

Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS

Next, the example veriﬁes that key 8, the key to be exported, is a symmetric key that is extractable. It
also veriﬁes that the wrapping key, key 262168, is an AES key that exists only in the session. You can use
the ﬁndKey (p. 133) command, but this example exports the attributes of both keys to ﬁles and then
uses grep to ﬁnd the relevant attribute values in the ﬁle.
These commands use getAttribute with an -a value of 512 (all) to get all attributes for keys 8
and 262168. For information about the key attributes, see the the section called “Key Attribute
Reference” (p. 176).
getAttribute -o 8 -a 512 -out attributes/attr_8
getAttribute -o 262168 -a 512 -out attributes/attr_262168

130

AWS CloudHSM User Guide
Reference

These commands use grep to verify the attributes of the key to be exported (key 8) and the session-only
wrapping key (key 262168).
// Verify that the key to be exported is a symmetric key.
$ grep -A 1 "OBJ_ATTR_CLASS" attributes/attr_8
OBJ_ATTR_CLASS
0x04
// Verify that the key to be exported is extractable.
$ grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_8
OBJ_ATTR_EXTRACTABLE
0x00000001
// Verify that the wrapping key is an AES key
$ grep -A 1 "OBJ_ATTR_KEY_TYPE" attributes/attr_262168
OBJ_ATTR_KEY_TYPE
0x1f
// Verify that the wrapping key is a session key
$ grep -A 1 "OBJ_ATTR_TOKEN" attributes/attr_262168
OBJ_ATTR_TOKEN
0x00
// Verify that the wrapping key can be used for wrapping
$ grep -A 1 "OBJ_ATTR_WRAP" attributes/attr_262168
OBJ_ATTR_WRAP
0x00000001

Finally, we use an exSymKey command to export key 8 using the session key (key 262168) as the
wrapping key.
When the session ends, key 262168 no longer exists.
Command:

exSymKey -k 8 -w 262168 -out aes256_H8.key

Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "aes256_H8.key"

Example : Use an External Unwrapping Key
This example shows how to use an external unwrapping key to export a key from the HSM.
When you export a key from the HSM, you specify an AES key on the HSM to be the wrapping key. By
default, that wrapping key is used to wrap and unwrap the key to be exported. However, you can use the
-wk parameter to tell exSymKey to use an external key in a ﬁle on disk for unwrapping. When you do,
the key speciﬁed by the -w parameter wraps the target key, and the key in the ﬁle speciﬁed by the -wk
parameter unwraps the key.
Because the wrapping key must be an AES key, which is symmetric, the wrapping key in the HSM and
unwrapping key on disk must be have the same key material. To do this, you must import the wrapping
key to the HSM or export the wrapping key from the HSM before the export operation.
This example creates a key outside of the HSM and imports it into the HSM. It uses the internal copy of
the key to wrap a symmetric key that is being exported, and the copy of key in the ﬁle to unwrap it.
The ﬁrst command uses OpenSSL to generate a 256-bit AES key. It saves the key to the aes256forImport.key ﬁle. The OpenSSL command does not return any output, but you can use several

131

AWS CloudHSM User Guide
Reference

commands to conﬁrm its success. This example uses the wc (wordcount) tool, which conﬁrms that the ﬁle
that contains 32 bytes of data.
$

openssl rand -out keys/aes256-forImport.key 32

$ wc keys/aes256-forImport.key
0 2 32 keys/aes256-forImport.key

This command uses the imSymKey command to import the AES key from the aes256-forImport.key
ﬁle to the HSM. When the command completes, the key exists in the HSM with key handle 262167 and
in the aes256-forImport.key ﬁle.
Command:

imSymKey -f keys/aes256-forImport.key -t 31 -l aes256-imported -w 6

Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Unwrapped.

Key Handle: 262167

Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

This command uses the key in an export operation. The command uses exSymKey to export key 21,
a 192-bit AES key. To wrap the key, it uses key 262167, which is the copy that was imported into the
HSM. To unwrap the key, it uses the same key material in the aes256-forImport.key ﬁle. When the
command completes, key 21 is exported to the aes192_h21.key ﬁle.
Command:

exSymKey -k 21 -w 262167 -out aes192_H21.key -wk aes256-forImport.key

Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "aes192_H21.key"

Parameters
-h
Displays help for the command.
Required: Yes
-k
Speciﬁes the key handle of the key to export. This parameter is required. Enter the key handle
of a symmetric key that you own. This parameter is required. To ﬁnd key handles, use the
ﬁndKey (p. 133) command.
To verify that a key can be exported, use the getAttribute (p. 156) command to get the value of the
OBJ_ATTR_EXTRACTABLE attribute, which is represented by constant 354. Also, you can export only
keys that you own. To ﬁnd the owner of a key, use the getKeyInfo (p. 159) command.
Required: Yes
-w
Speciﬁes the key handle of the wrapping key. This parameter is required. To ﬁnd key handles, use the
ﬁndKey (p. 133) command.

132

AWS CloudHSM User Guide
Reference

A wrapping key is a key in the HSM that is used to encrypt (wrap) and then decrypt (unwrap) the key
to be exported. Only AES keys can be used as wrapping keys.
You can use any AES key (of any size) as a wrapping key. Because the wrapping key wraps, and then
immediately unwraps, the target key, you can use as session-only AES key as a wrapping key. To
determine whether a key can be used as a wrapping key, use getAttribute (p. 156) to get the value
of the OBJ_ATTR_WRAP attribute, which is represented by the constant 262. To create a wrapping
key, use genSymKey (p. 151) to create an AES key (type 31).
If you use the -wk parameter to specify an external unwrapping key, the -w wrapping key is used to
wrap, but not to unwrap, the key during export.

Note

Key 4 represents an unsupported internal key. We recommend that you use an AES key that
you create and manage as the wrapping key.
Required: Yes
-out
Speciﬁes the path and name of the output ﬁle. When the command succeeds, this ﬁle contains the
exported key in plaintext. If the ﬁle already exists, the command overwrites it without warning.
Required: Yes
-m
Speciﬁes the wrapping mechanism. The only valid value is 4, which represents the NIST_AES_WRAP
mechanism.
Required: No
Default: 4
-wk
Use the AES key in the speciﬁed ﬁle to unwrap the key that is being exported. Enter the path and
name of a ﬁle that contains a plaintext AES key.
When you include this parameter. exSymKey uses the key in the HSM that is speciﬁed by the -w
parameter to wrap the key that is being exported and it uses the key in the -wk ﬁle to unwrap it. The
-w and -wk parameter values must resolve to the same plaintext key.
Required: No
Default: Use the wrapping key on the HSM to unwrap.

Related Topics
• genSymKey (p. 151)
• imSymKey (p. 162)
• wrapKey (p. 175)

ﬁndKey
Use the ﬁndKey command in key_mgmt_util to search for keys by the values of the key attributes. When
a key matches all the criteria that you set, ﬁndKey returns the key handle. With no parameters, ﬁndKey
returns the key handles of all the keys that you can use in the HSM. To ﬁnd the attribute values of a
particular key, use getAttribute (p. 156).

133

AWS CloudHSM User Guide
Reference

Like all key_mgmt_util commands, ﬁndKey is user speciﬁc. It returns only the keys that the current user
can use in cryptographic operations. This includes keys that current user owns and keys that have been
shared with the current user.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
findKey -h
findKey [-c ]
[-t ]
[-l ]
[-id ]
[-sess (0 | 1)]
[-u ]
[-m ]
[-kcv ]

Examples
These examples show how to use ﬁndKey to ﬁnd and identify keys in your HSMs.

Example : Find All Keys
This command ﬁnds all keys for the current user in the HSM. The output includes keys that the user owns
and shares, and all public keys in the HSMs.
To get the attributes of a key with a particular key handle, use getAttribute (p. 156). To
determine whether the current user owns or shares a particular key, use getKeyInfo (p. 159) or
ﬁndAllKeys (p. 91) in cloudhsm_mgmt_util.
Command: findKey
Total number of keys present 13
number of keys matched from start index 0::12
6, 7, 524296, 9, 262154, 262155, 262156, 262157, 262158, 262159, 262160, 262161, 262162
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Example : Find Keys by Type, User, and Session
This command ﬁnds persistent AES keys that the current user and user 3 can use. (User 3 might be able
to use other keys that the current user cannot see.)
Command: findKey -t 31 -sess 0 -u 3

Example : Find Keys by Class and Label
This command ﬁnds all public keys for the current user with the 2018-sept label.
Command: findKey -c 2 -l 2018-sept

134

AWS CloudHSM User Guide
Reference

Example : Find RSA Keys by Modulus
This command ﬁnds RSA keys (type 0) for the current user that were created by using the modulus in the
m4.txt ﬁle.
Command: findKey -t 0 -m m4.txt

Parameters
-h
Displays help for the command.
Required: Yes
-t
Finds keys of the speciﬁed type. Enter the constant that represents the key class. For example, to
ﬁnd 3DES keys, type -t 21.
Valid values:
• 0: RSA
• 1: DSA
• 3: EC
• 16: GENERIC_SECRET
• 18: RC4
• 21: Triple DES (3DES)
• 31: AES
Required: No
-c
Finds keys in the speciﬁed class. Enter the constant that represents the key class. For example, to
ﬁnd public keys, type -c 2.
Valid values for each key type:
• 2: Public. This class contains the public keys of public–private key pairs.
• 3: Private. This class contains the private keys of public–private key pairs.
• 4: Secret. This class contains all symmetric keys.
Required: No
-l
Finds keys with the speciﬁed label. Type the exact label. You cannot use wildcard characters or
regular expressions in the --l value.
Required: No
-id
Finds the key with the speciﬁed ID. Type the exact ID string. You cannot use wildcard characters or
regular expressions in the -id value.
Required: No
-sess
Finds keys by session status. To ﬁnd keys that are valid only in the current session, type 1. To ﬁnd
persistent keys, type 0.

135

AWS CloudHSM User Guide
Reference

Required: No
-u
Finds keys the speciﬁed users and the current user share. Type a comma-separated list of HSM user
IDs, such as -u 3 or -u 4,7. To ﬁnd the IDs of users on an HSM, use listUsers (p. 169).
When you specify one user ID, ﬁndKey returns the keys for that user. When you specify multiple user
IDs, ﬁndKey returns the keys that all the speciﬁed users can use.
Because ﬁndKey only returns keys that the current user can use, the -u results are always identical
to or a subset of the current user's keys. To get all keys that are owned by or shared with any user,
crypto oﬃcers (COs) can use ﬁndAllKeys (p. 91) in cloudhsm_mgmt_util.
Required: No
-m
Finds keys that were created by using the RSA modulus in the speciﬁed ﬁle. Type the path to ﬁle that
stores the modulus.
Required: No
-kcv
Finds keys with the speciﬁed key check value.
The key check value (KCV) is an 8-byte hash or checksum of a key. The HSM calculates a KCV when it
generates the key. You can also calculate a KCV outside of the HSM, such as after you export a key.
You can then compare the KCV values to conﬁrm the identity and integrity of the key. To get the KCV
of a key, use getAttribute (p. 156).
AWS CloudHSM uses the following standard method to generate a key check value:
• Symmetric keys: First 8 bytes of the result of encrypting 16 zero-ﬁlled bytes with the key.
• Asymmetric key pairs: First 8 bytes of the modulus hash.
Required: No

Output
The ﬁndKey output lists the total number of matching keys and their key handles.
Command: findKey
Total number of keys present 10
number of keys matched from start index 0::9
6, 7, 8, 9, 10, 11, 262156, 262157, 262158, 262159
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Related Topics
• ﬁndSingleKey (p. 137)
• getKeyInfo (p. 159)
• getAttribute (p. 156)
• ﬁndAllKeys (p. 91) in cloudhsm_mgmt_util

136

AWS CloudHSM User Guide
Reference

• Key Attribute Reference (p. 176)

ﬁndSingleKey
The ﬁndSingleKey command in the key_mgmt_util tool veriﬁes that a key exists on all HSMs in the
cluster.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
findSingleKey -h
findSingleKey -k 

Example
Example
This command veriﬁes that key 252136 exists on all three HSMs in the cluster.
Command: findSingleKey -k 252136
Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS
Cluster
Node id
Node id
Node id

Error
2 and
1 and
0 and

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

Parameters
-h
Displays help for the command.
Required: Yes
-k
Speciﬁes the key handle of one key in the HSM. This parameter is required.
To ﬁnd key handles, use the ﬁndKey (p. 169) command.
Required: Yes

Related Topics
• ﬁndKey (p. 169)
• getKeyInfo (p. 169)
• getAttribute (p. 133)

genDSAKeyPair
The genDSAKeyPair command in the key_mgmt_util tool generates a Digital Signing Algorithm (DSA)
key pair in your HSMs. You must specify the modulus length; the command generates the modulus value.

137

AWS CloudHSM User Guide
Reference

You can also assign an ID, share the key with other HSM users, create nonextractable keys, and create
keys that expire when the session ends. When the command succeeds, it returns the key handles that
the HSM assigns to the public and private keys. You can use the key handles to identify the keys to other
commands.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Tip

To ﬁnd the attributes of a key that you have created, such as the type, length, label, and ID, use
getAttribute (p. 156). To ﬁnd the keys for a particular user, use getKeyInfo (p. 159). To ﬁnd
keys based on their attribute values, use ﬁndKey (p. 133).

Syntax
genDSAKeyPair -h
genDSAKeyPair -m 
-l 
[-id ]
[-min_srv ]
[-m_value <0..8>]
[-nex]
[-sess]
[-timeout  ]
[-u ]
[-attest]

Examples
These examples show how to use genDSAKeyPair to create a DSA key pair.

Example : Create a DSA Key Pair
This command creates a DSA key pair with a DSA label. The output shows that the key handle of the
public key is 19 and the handle of the private key is 21.
Command: genDSAKeyPair -m 2048 -l DSA
Cfm3GenerateKeyPair: returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:

public key handle: 19

private key handle: 21

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Example : Create a Session-Only DSA Key Pair
This command creates a DSA key pair that is valid only in the current session. The command assigns a
unique ID of DSA_temp_pair in addition to the required (nonunique) label. You might want to create
a key pair like this to sign and verify a session-only token. The output shows that the key handle of the
public key is 12 and the handle of the private key is 14.
Command: genDSAKeyPair -m 2048 -l DSA-temp -id DSA_temp_pair -sess
Cfm3GenerateKeyPair: returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:

public key handle: 12

Cluster Error Status

138

private key handle: 14

AWS CloudHSM User Guide
Reference
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

To conﬁrm that the key pair exists only in the session, use the -sess parameter of ﬁndKey (p. 133)
with a value of 1 (true).
Command: findKey -sess 1
Total number of keys present 2
number of keys matched from start index 0::1
12, 14
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Example : Create a Shared, Nonextractable DSA Key Pair
This command creates a DSA key pair. The private key is shared with three other users, and it cannot be
exported from the HSM. Public keys can be used by any user and can always be extracted.
Command:

genDSAKeyPair -m 2048 -l DSA -id DSA_shared_pair -nex -u 3,5,6

Cfm3GenerateKeyPair: returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:

public key handle: 11

private key handle: 19

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Example : Create a Quorum-Controlled Key Pair
This command creates a DSA key pair with the label DSA-mV2. The command uses the -u parameter to
share the private key with user 4 and 6. It uses the -m_value parameter to require a quorum of at least
two approvals for any cryptographic operations that use the private key. The command also uses the attest parameter to verify the integrity of the ﬁrmware on which the key pair is generated.
The output shows that the command generates a public key with key handle 12 and a private key with
key handle 17, and that the attestation check on the cluster ﬁrmware passed.
Command:

genDSAKeyPair -m 2048 -l DSA-mV2 -m_value 2 -u 4,6 -attest

Cfm3GenerateKeyPair: returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:

public key handle: 12

private key handle: 17

Attestation Check : [PASS]
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

This command uses getKeyInfo (p. 159) on the private key (key handle 17). The output conﬁrms that
the key is owned by the current user (user 3) and that it is shared with users 4 and 6 (and no others). The
output also shows that quorum authentication is enabled and the quorum size is two.

139

AWS CloudHSM User Guide
Reference
Command:

getKeyInfo -k 17

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3
also, shared to following 2 user(s):
4
6
2 Users need to approve to use/manage this key

Parameters
-h
Displays help for the command.
Required: Yes
-m
Speciﬁes the length of the modulus in bits. The only valid value is 2048.
Required: Yes
-l
Speciﬁes a user-deﬁned label for the key pair. Type a string. The same label applies to both keys in
the pair
You can use any phrase that helps you to identify the key. Because the label does not have to be
unique, you can use it to group and categorize keys.
Required: Yes
-id
Speciﬁes a user-deﬁned identiﬁer for the key pair. Type a string that is unique in the cluster. The
default is an empty string. The ID that you specify applies to both keys in the pair.
Default: No ID value.
Required: No
-min_srv
Speciﬁes the minimum number of HSMs on which the key is synchronized before the value of the timeout parameter expires. If the key is not synchronized to the speciﬁed number of servers in the
time allotted, it is not created.
AWS CloudHSM automatically synchronizes every key to every HSM in the cluster. To speed up your
process, set the value of min_srv to less than the number of HSMs in the cluster and set a low
timeout value. Note, however, that some requests might not generate a key.
Default: 1
Required: No
-m_value
Speciﬁes the number of users who must approve any cryptographic operation that uses the private
key in the pair. Type a value from 0 to 8.

140

AWS CloudHSM User Guide
Reference

This parameter establishes a quorum authentication requirement for the private key. The default
value, 0, disables the quorum authentication feature for the key. When quorum authentication is
enabled, the speciﬁed number of users must sign a token to approve cryptographic operations that
use the private key, and operations that share or unshare the private key.
To ﬁnd the m_value of a key, use getKeyInfo (p. 159).
This parameter is valid only when the -u parameter in the command shares the key pair with
enough users to satisfy the m_value requirement.
Default: 0
Required: No
-nex
Makes the private key nonextractable. The private key that is generated cannot be exported from
the HSM (p. 59). Public keys are always extractable.
Default: Both the public and private keys in the key pair are extractable.
Required: No
-sess
Creates a key that exists only in the current session. The key cannot be recovered after the session
ends.
Use this parameter when you need a key only brieﬂy, such as a wrapping key that encrypts, and
then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to
decrypt after the session ends.
To change a session key to a persistent (token) key, use setAttribute (p. 170).
Default: The key is persistent.
Required: No
-timeout
Speciﬁes how long (in seconds) the command waits for a key to be synchronized to the number of
HSMs speciﬁed by the min_srv parameter.
This parameter is valid only when the min_srv parameter is also used in the command.
Default: No timeout. The command waits indeﬁnitely and returns only when the key is synchronized
to the minimum number of servers.
Required: No
-u
Shares the private key in the pair with the speciﬁed users. This parameter gives other HSM crypto
users (CUs) permission to use the private key in cryptographic operations. Public keys can be used by
any user without sharing.
Type a comma-separated list of HSM user IDs, such as -u 5,6. Do not include the HSM user ID of the
current user. To ﬁnd HSM user IDs of CUs on the HSM, use listUsers (p. 169). To share and unshare
existing keys, use shareKey.
Default: Only the current user can use the private key.
Required: No

141

AWS CloudHSM User Guide
Reference

-attest
Runs an integrity check that veriﬁes that the ﬁrmware on which the cluster runs has not been
tampered with.
Default: No attestation check.
Required: No

Related Topics
• genRSAKeyPair (p. 146)
• genSymKey (p. 151)
• genECCKeyPair (p. 142)

genECCKeyPair
The genECCKeyPair command in the key_mgmt_util tool generates an Elliptic Curve Cryptography
(ECC) key pair in your HSMs. You must specify the elliptic curve type and a label for the keys. You can
also share the private key with other CU users, create non-extractable keys, quorum-controlled keys, and
keys that expire when the session ends. When the command succeeds, it returns the key handles that the
HSM assigns to the public and private ECC keys. You can use the key handles to identify the keys to other
commands.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Tip

To ﬁnd the attributes of a key that you have created, such as the type, length, label, and ID, use
getAttribute (p. 156). To ﬁnd the keys for a particular user, use getKeyInfo (p. 159). To ﬁnd
keys based on their attribute values, use ﬁndKey (p. 133).

Syntax
genECCKeyPair -h
genECCKeyPair -i 
-l 
[-id ]
[-min_srv ]
[-m_value <0..8>]
[-nex]
[-sess]
[-timeout  ]
[-u ]
[-attest]

Examples
These examples show how to use genECCKeyPair to create ECC key pairs in your HSMs.

Example : Create and Examine an ECC Key Pair
This command creates an ECC key pair using an NID_sect571r1 elliptic curve and an ecc12 label. The
output shows that the key handle of the private key is 262177 and the key handle of the public key is
262179. The label applies to both the public and private keys.

142

AWS CloudHSM User Guide
Reference

Command: genECCKeyPair -i 12 -l ecc12
Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:
Cluster
Node id
Node id
Node id

Error
2 and
1 and
0 and

public key handle: 262179

private key handle: 262177

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

After generating the key, you might want to examine its attributes. The next command uses
getAttribute (p. 156) to write all of the attributes (represented by the constant 512) of the new ECC
private key to the attr_262177 ﬁle.
Command: getAttribute -o 262177 -a 512 -out attr_262177
got all attributes of size 529 attr cnt 19
Attributes dumped into attr_262177
Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS

This command gets the content of the attr_262177 attribute ﬁle. The output shows that the key is
an elliptic curve private key that can be used for signing, but not for encrypting, decrypting, wrapping,
unwrapping, or verifying. The key is persistent and exportable.
$

cat attr_262177

OBJ_ATTR_CLASS
0x03
OBJ_ATTR_KEY_TYPE
0x03
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x00
OBJ_ATTR_DECRYPT
0x00
OBJ_ATTR_WRAP
0x00
OBJ_ATTR_UNWRAP
0x00
OBJ_ATTR_SIGN
0x01
OBJ_ATTR_VERIFY
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
ecc2
OBJ_ATTR_ID
OBJ_ATTR_VALUE_LEN
0x0000008a
OBJ_ATTR_KCV
0xbbb32a
OBJ_ATTR_MODULUS

143

AWS CloudHSM User Guide
Reference

044a0f9d01d10f7437d9fa20995f0cc742552e5ba16d3d7e9a65a33e20ad3e569e68eb62477a9960a87911e6121d112b698e469
OBJ_ATTR_MODULUS_BITS
0x0000019f

Example Using an Invalid EEC Curve
This command attempts to create an ECC key pair by using an NID_X9_62_prime192v1 curve. Because
this elliptic curve is not valid for FIPS-mode HSMs, the command fails. The message reports that a server
in the cluster is unavailable, but this does not typically indicate a problem with the HSMs in the cluster.
Command:

genECCKeyPair -i 1 -l ecc1

Cfm3GenerateKeyPair returned: 0xb3 : HSM Error: This operation violates the current
configured/FIPS policies
Cluster Error Status
Node id 0 and err state 0x30000085 : HSM CLUSTER ERROR: Server in cluster is
unavailable

Parameters
-h
Displays help for the command.
Required: Yes
-i
Speciﬁes the identiﬁer for the elliptic curve. Enter an identiﬁer (1 - 15).
Valid values:
• 1: NID_X9_62_prime192v1
• 2: NID_X9_62_prime256v1
• 3: NID_sect163k1
• 4: NID_sect163r2
• 5: NID_sect233k1
• 6: NID_sect233r1
• 7: NID_sect283k1
• 8: NID_sect283r1
• 9: NID_sect409k1
• 10: NID_sect409r1
• 11:NID_sect571k1
• 12: NID_sect571r1
• 13: NID_secp224r1
• 14:NID_secp384r1
• 15: NID_secp521r1
Required: Yes
-l
Speciﬁes a user-deﬁned label for the key pair. Type a string. The same label applies to both keys in
the pair
You can use any phrase that helps you to identify the key. Because the label does not have to be
unique, you can use it to group and categorize keys.

144

AWS CloudHSM User Guide
Reference

Required: Yes
-id
Speciﬁes a user-deﬁned identiﬁer for the key pair. Type a string that is unique in the cluster. The
default is an empty string. The ID that you specify applies to both keys in the pair.
Default: No ID value.
Required: No
-min_srv
Speciﬁes the minimum number of HSMs on which the key is synchronized before the value of the timeout parameter expires. If the key is not synchronized to the speciﬁed number of servers in the
time allotted, it is not created.
AWS CloudHSM automatically synchronizes every key to every HSM in the cluster. To speed up your
process, set the value of min_srv to less than the number of HSMs in the cluster and set a low
timeout value. Note, however, that some requests might not generate a key.
Default: 1
Required: No
-m_value
Speciﬁes the number of users who must approve any cryptographic operation that uses the private
key in the pair. Type a value from 0 to 8.
This parameter establishes a quorum authentication requirement for the private key. The default
value, 0, disables the quorum authentication feature for the key. When quorum authentication is
enabled, the speciﬁed number of users must sign a token to approve cryptographic operations that
use the private key, and operations that share or unshare the private key.
To ﬁnd the m_value of a key, use getKeyInfo (p. 159).
This parameter is valid only when the -u parameter in the command shares the key pair with
enough users to satisfy the m_value requirement.
Default: 0
Required: No
-nex
Makes the private key nonextractable. The private key that is generated cannot be exported from
the HSM (p. 59). Public keys are always extractable.
Default: Both the public and private keys in the key pair are extractable.
Required: No
-sess
Creates a key that exists only in the current session. The key cannot be recovered after the session
ends.
Use this parameter when you need a key only brieﬂy, such as a wrapping key that encrypts, and
then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to
decrypt after the session ends.
To change a session key to a persistent (token) key, use setAttribute (p. 170).
Default: The key is persistent.

145

AWS CloudHSM User Guide
Reference

Required: No
-timeout
Speciﬁes how long (in seconds) the command waits for a key to be synchronized to the number of
HSMs speciﬁed by the min_srv parameter.
This parameter is valid only when the min_srv parameter is also used in the command.
Default: No timeout. The command waits indeﬁnitely and returns only when the key is synchronized
to the minimum number of servers.
Required: No
-u
Shares the private key in the pair with the speciﬁed users. This parameter gives other HSM crypto
users (CUs) permission to use the private key in cryptographic operations. Public keys can be used by
any user without sharing.
Type a comma-separated list of HSM user IDs, such as -u 5,6. Do not include the HSM user ID of the
current user. To ﬁnd HSM user IDs of CUs on the HSM, use listUsers (p. 169). To share and unshare
existing keys, use shareKey.
Default: Only the current user can use the private key.
Required: No
-attest
Runs an integrity check that veriﬁes that the ﬁrmware on which the cluster runs has not been
tampered with.
Default: No attestation check.
Required: No

Related Topics
• genSymKey (p. 151)
• genRSAKeyPair (p. 146)
• genDSAKeyPair (p. 137)

genPBEKey
The genPBEKey command in the key_mgmt_util tool generates a Triple DES (3DES) symmetric key
based on a password. This command is not supported on the FIPS-validated HSMs that AWS CloudHSM
provides.
To create symmetric keys, use genSymKey (p. 151). To create asymmetric key pairs, use
genRSAKeyPair (p. 146), genDSAKeyPair (p. 137), or genECCKeyPair (p. 142).

genRSAKeyPair
The genRSAKeyPair command in the key_mgmt_util tool generates an RSA asymmetric key pair. You
specify the key type, modulus length, and a public exponent. The command generates a modulus of
the speciﬁed length and creates the key pair. You can assign an ID, share the key with other HSM users,
create nonextractable keys and keys that expire when the session ends. When the command succeeds, it
returns a key handle that the HSM assigns to the key. You can use the key handle to identify the key to
other commands.

146

AWS CloudHSM User Guide
Reference

Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Tip

To ﬁnd the attributes of a key that you have created, such as the type, length, label, and ID, use
getAttribute (p. 156). To ﬁnd the keys for a particular user, use getKeyInfo (p. 159). To ﬁnd
keys based on their attribute values, use ﬁndKey (p. 133).

Syntax
genRSAKeyPair -h
genRSAKeyPair -m 
-e 
-l 
[-id ]
[-min_srv ]
[-m_value <0..8>]
[-nex]
[-sess]
[-timeout  ]
[-u ]
[-attest]

Examples
These examples show how to use genRSAKeyPair to create asymmetric key pairs in your HSMs.

Example : Create and Examine an RSA Key Pair
This command creates an RSA key pair with a 2048-bit modulus and an exponent of 65541. The output
shows that the public key handle is 262159 and the private key handle is 262160.
Command: genRSAKeyPair -m 2048 -e 65541 -l rsa_test
Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair: public key handle: 262159 private key handle: 262160
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

The next command uses getAttribute (p. 133) to get the attributes of the public key that we just
created. It writes the output to the attr_262159 ﬁle. It is followed by a cat command that gets
the content of the attribute ﬁle. For help interpreting the key attributes, see the Key Attribute
Reference (p. 176).
The resulting hexadecimal values conﬁrm that it is a public key (OBJ_ATTR_CLASS 0x02) with a type of
RSA (OBJ_ATTR_KEY_TYPE 0x00). You can use this public key to encrypt (OBJ_ATTR_ENCRYPT 0x01),
but not to decrypt (OBJ_ATTR_DECRYPT 0x00) or wrap (OBJ_ATTR_WRAP 0x00). The results also
include the key length (512, 0x200), the modulus, the modulus length (2048, 0x800), and the public
exponent (65541, 0x10005).
Command:

getAttribute -o 262159 -a 512 -out attr_262159

got all attributes of size 731 attr cnt 20
Attributes dumped into attr_262159 file
Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS

147

AWS CloudHSM User Guide
Reference
$ cat attr_262159
OBJ_ATTR_CLASS
0x02
OBJ_ATTR_KEY_TYPE
0x00
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x00
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x00
OBJ_ATTR_WRAP
0x00
OBJ_ATTR_UNWRAP
0x00
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY
0x01
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x00
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
rsa_test
OBJ_ATTR_ID
OBJ_ATTR_VALUE_LEN
0x00000200
OBJ_ATTR_KCV
0x0a4364
OBJ_ATTR_MODULUS
9162b8d5d01d7b5b1179686d15e74d1dd38eaa5b6e64673195aaf951df8828deeca002c215d4209a
c0bf90a9587ddca7f6351d5d4df0f6201b65daccd9955e4f49a819c0d39cb6717623bfa33436facc
835c15961a58a63ca25bf0d2d4888d77418c571c190f8cc5a82483050658c00df4658dff248202bc
95e886b1b5c7a981f09b0eb4f606641efe09bf3881f63c90d4a4415219ba796df449862b9d9c2a78
d1c24fff56cf9b25f2b7dee44e200dd9550bd097a7044b22ca004033236bc708a0bad4a111533ed4
6d049e5ec0b449b4a3877e566b0ce9d0a60fd1c15352b131ccc234f1719bed3918df579a66e7fff2
9dc80dc5dbbf6e3d7d092d67c6abca7d
OBJ_ATTR_MODULUS_BITS
0x00000800
OBJ_ATTR_PUBLIC_EXPONENT
0x010005

Example : Generate a Shared RSA Key Pair
This command generates an RSA key pair and shares the private key with user 4, another CU on the HSM.
The command uses the m_value parameter to require at least two approvals before the private key in
the pair can be used in a cryptographic operation. When you use the m_value parameter, you must also
use -u in the command and the m_value cannot exceed the total number of users (number of values in
-u + owner).
Command:

genRSAKeyPair -m 2048 -e 195193 -l rsa_mofn -id rsa_mv2 -u 4 -m_value 2

Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:

public key handle: 27

private key handle: 28

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

148

AWS CloudHSM User Guide
Reference
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS

Parameters
-h
Displays help for the command.
Required: Yes
-m
Speciﬁes the length of the modulus in bits. The minimum value is 2048.
Required: Yes
-e
Speciﬁes the public exponent. The value must be an odd number greater than or equal to 65537.
Required: Yes
-l
Speciﬁes a user-deﬁned label for the key pair. Type a string. The same label applies to both keys in
the pair
You can use any phrase that helps you to identify the key. Because the label does not have to be
unique, you can use it to group and categorize keys.
Required: Yes
-id
Speciﬁes a user-deﬁned identiﬁer for the key pair. Type a string that is unique in the cluster. The
default is an empty string. The ID that you specify applies to both keys in the pair.
Default: No ID value.
Required: No
-min_srv
Speciﬁes the minimum number of HSMs on which the key is synchronized before the value of the timeout parameter expires. If the key is not synchronized to the speciﬁed number of servers in the
time allotted, it is not created.
AWS CloudHSM automatically synchronizes every key to every HSM in the cluster. To speed up your
process, set the value of min_srv to less than the number of HSMs in the cluster and set a low
timeout value. Note, however, that some requests might not generate a key.
Default: 1
Required: No
-m_value
Speciﬁes the number of users who must approve any cryptographic operation that uses the private
key in the pair. Type a value from 0 to 8.
This parameter establishes a quorum authentication requirement for the private key. The default
value, 0, disables the quorum authentication feature for the key. When quorum authentication is
enabled, the speciﬁed number of users must sign a token to approve cryptographic operations that
use the private key, and operations that share or unshare the private key.
To ﬁnd the m_value of a key, use getKeyInfo (p. 159).

149

AWS CloudHSM User Guide
Reference

This parameter is valid only when the -u parameter in the command shares the key pair with
enough users to satisfy the m_value requirement.
Default: 0
Required: No
-nex
Makes the private key nonextractable. The private key that is generated cannot be exported from
the HSM (p. 59). Public keys are always extractable.
Default: Both the public and private keys in the key pair are extractable.
Required: No
-sess
Creates a key that exists only in the current session. The key cannot be recovered after the session
ends.
Use this parameter when you need a key only brieﬂy, such as a wrapping key that encrypts, and
then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to
decrypt after the session ends.
To change a session key to a persistent (token) key, use setAttribute (p. 170).
Default: The key is persistent.
Required: No
-timeout
Speciﬁes how long (in seconds) the command waits for a key to be synchronized to the number of
HSMs speciﬁed by the min_srv parameter.
This parameter is valid only when the min_srv parameter is also used in the command.
Default: No timeout. The command waits indeﬁnitely and returns only when the key is synchronized
to the minimum number of servers.
Required: No
-u
Shares the private key in the pair with the speciﬁed users. This parameter gives other HSM crypto
users (CUs) permission to use the private key in cryptographic operations. Public keys can be used by
any user without sharing.
Type a comma-separated list of HSM user IDs, such as -u 5,6. Do not include the HSM user ID of the
current user. To ﬁnd HSM user IDs of CUs on the HSM, use listUsers (p. 169). To share and unshare
existing keys, use shareKey.
Default: Only the current user can use the private key.
Required: No
-attest
Runs an integrity check that veriﬁes that the ﬁrmware on which the cluster runs has not been
tampered with.
Default: No attestation check.
Required: No

150

AWS CloudHSM User Guide
Reference

Related Topics
• genSymKey (p. 151)
• createKeyPair
• genDSAKeyPair (p. 137)
• genECCKeyPair (p. 142)

genSymKey
The genSymKey command in the key_mgmt_util tool generates a symmetric key in your HSMs. You
can specify the key type and size, assign an ID and label, and share the key with other HSM users. You
can also create nonextractable keys and keys that expire when the session ends. When the command
succeeds, it returns a key handle that the HSM assigns to the key. You can use the key handle to identify
the key to other commands.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Tip

To ﬁnd the attributes of a key that you have created, such as the type, length, label, and ID, use
getAttribute (p. 156). To ﬁnd the keys for a particular user, use getKeyInfo (p. 159). To ﬁnd
keys based on their attribute values, use ﬁndKey (p. 133).

Syntax
genSymKey -h
genSymKey -t 
-s 
-l 
[-id ]
[-min_srv ]
[-m_value <0..8>]
[-nex]
[-sess]
[-timeout  ]
[-u ]
[-attest]

Examples
These examples show how to use genSymKey to create symmetric keys in your HSMs.

Example : Generate an AES Key
This command creates a 256-bit AES key with an aes256 label. The output shows that the key handle of
the new key is 6.
Command: genSymKey -t 31 -s 32 -l aes256
Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created.

Key Handle: 6

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

151

AWS CloudHSM User Guide
Reference

Example : Create a Session Key
This command creates a nonextractable 192-bit AES key that is valid only in the current session. You
might want to create a key like this to wrap (and then immediately unwrap) a key that is being exported.
Command: genSymKey -t 31 -s 24 -l tmpAES -id wrap01 -nex -sess

Example : Return Quickly
This command creates a generic 512-byte key with a label of IT_test_key. The command does not
wait for the key to be synchronized to all HSMs in the cluster. Instead, it returns as soon as the key is
created on any one HSM (-min_srv 1) or in 1 second (-timeout 1), whichever is shorter. If the key
is not synchronized to the speciﬁed minimum number of HSMs before the timeout expires, it is not
generated. You might want to use a command like this in a script that creates numerous keys, like the
for loop in the following example.
Command: genSymKey -t 16 -s 512 -l IT_test_key -min_srv 1 -timeout 1
$

for i in {1..30};
do /opt/cloudhsm/bin/key_mgmt_util Cfm3Util singlecmd loginHSM -u CU -s example_user p example_pwd genSymKey -l aes -t 31 -s 32 -min_srv 1 -timeout 1;
done;

Example : Create a Quorum Authorized Generic Key
This command creates a 2048-bit generic secret key with the label generic-mV2. The command uses
the -u parameter to share the key with another CU, user 6. It uses the -m_value parameter to require a
quorum of at least two approvals for any cryptographic operations that use the key. The command also
uses the -attest parameter to verify the integrity of the ﬁrmware on which the key is generated.
The output shows that the command generated a key with key handle 9 and that the attestation check
on the cluster ﬁrmware passed.

Command:

genSymKey -t 16 -s 2048 -l generic-mV2 -m_value 2 -u 6 -attest

Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Created.

Key Handle: 9

Attestation Check : [PASS]
Cluster Error Status
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Example : Create and Examine a Key
This command creates a Triple DES key with a 3DES_shared label and an ID of IT-02. The key can be
used by the current user, and users 4 and 5. The command fails if the ID is not unique in the cluster or if
the current user is user 4 or 5.
The output shows that the new key has key handle 7.
Command: genSymKey -t 21 -s 24 -l 3DES_shared -id IT-02 -u 4,5
Cfm3GenerateSymmetricKey returned: 0x00 : HSM Return: SUCCESS

152

AWS CloudHSM User Guide
Reference
Symmetric Key Created.

Key Handle: 7

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

To verify that the new 3DES key is owned by the current user and shared with users 4 and 5, use
getKeyInfo (p. 159). The command uses the handle that was assigned to the new key (Key Handle:
7).
The output conﬁrms that the key is owned by user 3 and shared with users 4 and 5.
Command:

getKeyInfo -k 7

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3
also, shared to following 2 user(s):
4, 5

To conﬁrm the other properties of the key, use getAttribute (p. 156). The ﬁrst command uses
getAttribute to get all attributes (-a 512) of key handle 7 (-o 7). It writes them to the attr_7 ﬁle.
The second command uses cat to get the contents of the attr_7 ﬁle.
This command conﬁrms that key 7 is a 192-bit (OBJ_ATTR_VALUE_LEN 0x00000018 or 24-byte) 3DES
(OBJ_ATTR_KEY_TYPE 0x15) symmetric key (OBJ_ATTR_CLASS 0x04) with a label of 3DES_shared
(OBJ_ATTR_LABEL 3DES_shared) and an ID of IT_02 (OBJ_ATTR_ID IT-02). The key is persistent
(OBJ_ATTR_TOKEN 0x01) and extractable (OBJ_ATTR_EXTRACTABLE 0x01) and can be used for
encryption, decryption, and wrapping.
For help interpreting the key attributes, see the Key Attribute Reference (p. 176).
Command:

getAttribute -o 7 -a 512 -attr_7

got all attributes of size 444 attr cnt 17
Attributes dumped into attr_7 file
Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS
$

cat attr_7

OBJ_ATTR_CLASS
0x04
OBJ_ATTR_KEY_TYPE
0x15
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x01
OBJ_ATTR_WRAP
0x00
OBJ_ATTR_UNWRAP
0x00
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY

153

AWS CloudHSM User Guide
Reference
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
3DES_shared
OBJ_ATTR_ID
IT-02
OBJ_ATTR_VALUE_LEN
0x00000018
OBJ_ATTR_KCV
0x59a46e

Parameters
-h
Displays help for the command.
Required: Yes
-t
Speciﬁes the type of the symmetric key. Enter the constant that represents the key type. For
example, to create an AES key, type -t 31.
Valid values:
• 16: GENERIC_SECRET. A generic secret key is a byte array that does not conform to any particular
standard, such as the requirements for an AES key.
• 18: RC4. RC4 keys are not valid on FIPS-mode HSMs
• 21: Triple DES (3DES).
• 31: AES
Required: Yes
-s
Speciﬁes the key size in bytes. For example, to create a 192-bit key, type 24.
Valid values for each key type:
• AES: 16 (128 bits), 24 (192 bits), 32 (256 bits)
• 3DES: 24 (192 bits)
• RC4: <256 (2048 bits)
• Generic Secret: <3584 (28672 bits)
Required: Yes
-l
Speciﬁes a user-deﬁned label for the key. Type a string.
You can use any phrase that helps you to identify the key. Because the label does not have to be
unique, you can use it to group and categorize keys.
Required: Yes
-attest
Runs an integrity check that veriﬁes that the ﬁrmware on which the cluster runs has not been
tampered with.

154

AWS CloudHSM User Guide
Reference

Default: No attestation check.
Required: No
-id
Speciﬁes a user-deﬁned identiﬁer for the key. Type a string that is unique in the cluster. The default
is an empty string.
Default: No ID value.
Required: No
-min_srv
Speciﬁes the minimum number of HSMs on which the key is synchronized before the value of the timeout parameter expires. If the key is not synchronized to the speciﬁed number of servers in the
time allotted, it is not created.
AWS CloudHSM automatically synchronizes every key to every HSM in the cluster. To speed up your
process, set the value of min_srv to less than the number of HSMs in the cluster and set a low
timeout value. Note, however, that some requests might not generate a key.
Default: 1
Required: No
-m_value
Speciﬁes the number of users who must approve any cryptographic operation that uses the key.
Type a value from 0 to 8.
This parameter establishes a quorum authentication requirement for the key. The default value, 0,
disables the quorum authentication feature for the key. When quorum authentication is enabled, the
speciﬁed number of users must sign a token to approve cryptographic operations that use the key,
and operations that share or unshare the key.
To ﬁnd the m_value of a key, use getKeyInfo (p. 159).
This parameter is valid only when the -u parameter in the command shares the key with enough
users to satisfy the m_value requirement.
Default: 0
Required: No
-nex
Makes the key nonextractable. The key that is generated cannot be exported from the HSM (p. 59).
Default: The key is extractable.
Required: No
-sess
Creates a key that exists only in the current session. The key cannot be recovered after the session
ends.
Use this parameter when you need a key only brieﬂy, such as a wrapping key that encrypts, and
then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to
decrypt after the session ends.
To change a session key to a persistent (token) key, use setAttribute (p. 170).

155

AWS CloudHSM User Guide
Reference

Default: The key is persistent.
Required: No
-timeout
Speciﬁes how long (in seconds) the command waits for a key to be synchronized to the number of
HSMs speciﬁed by the min_srv parameter.
This parameter is valid only when the min_srv parameter is also used in the command.
Default: No timeout. The command waits indeﬁnitely and returns only when the key is synchronized
to the minimum number of servers.
Required: No
-u
Shares the key with the speciﬁed users. This parameter gives other HSM crypto users (CUs)
permission to use this key in cryptographic operations.
Type a comma-separated list of HSM user IDs, such as -u 5,6. Do not include the HSM user ID of the
current user. To ﬁnd HSM user IDs of CUs on the HSM, use listUsers (p. 169). To share and unshare
existing keys, use shareKey.
Default: Only the current user can use the key.
Required: No

Related Topics
• exSymKey (p. 129)
• genRSAKeyPair (p. 146)
• genDSAKeyPair (p. 137)
• genECCKeyPair (p. 142)

getAttribute
The getAttribute command in key_mgmt_util writes one or all of the attribute values for an AWS
CloudHSM key to a ﬁle. If the attribute you specify does not exist for the key type, such as the modulus
of an AES key, getAttribute returns an error.
Key attributes are properties of a key. They include characteristics, like the key type, class, label, and ID,
and values that represent actions that you can perform with the key, like encrypt, decrypt, wrap, sign,
and verify.
You can use getAttribute only on keys that you own and key that are shared with you. You can run this
command or the getAttribute (p. 94) command in cloudhsm_mgmt_util, which gets one attribute
value of a key from all HSMs in a cluster, and writes it to stdout or to a ﬁle.
To get a list of attributes and the constants that represent them, use the listAttributes (p. 168)
command. To change the attribute values of existing keys, use setAttribute (p. 170) in key_mgmt_util
and setAttribute (p. 109) in cloudhsm_mgmt_util. For help interpreting the key attributes, see the Key
Attribute Reference (p. 176).
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

156

AWS CloudHSM User Guide
Reference

Syntax
getAttribute -h
getAttribute -o 
-a 
-out 

Examples
These examples show how to use getAttribute to get the attributes of keys in your HSMs.

Example : Get the Key Type
This example gets the type of the key, such an AES, 3DES, or generic key, or an RSA or elliptic curve key
pair.
The ﬁrst command runs listAttributes (p. 168), which gets the key attributes and the constants that
represent them. The output shows that the constant for key type is 256. For help interpreting the key
attributes, see the Key Attribute Reference (p. 176).
Command: listAttributes
Description
===========
The following are all of the possible attribute values for getAttributes.
OBJ_ATTR_CLASS
OBJ_ATTR_TOKEN
OBJ_ATTR_PRIVATE
OBJ_ATTR_LABEL
OBJ_ATTR_KEY_TYPE
OBJ_ATTR_ID
OBJ_ATTR_SENSITIVE
OBJ_ATTR_ENCRYPT
OBJ_ATTR_DECRYPT
OBJ_ATTR_WRAP
OBJ_ATTR_UNWRAP
OBJ_ATTR_SIGN
OBJ_ATTR_VERIFY
OBJ_ATTR_LOCAL
OBJ_ATTR_MODULUS
OBJ_ATTR_MODULUS_BITS
OBJ_ATTR_PUBLIC_EXPONENT
OBJ_ATTR_VALUE_LEN
OBJ_ATTR_EXTRACTABLE
OBJ_ATTR_KCV

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0
1
2
3
256
258
259
260
261
262
263
264
266
355
288
289
290
353
354
371

The second command runs getAttribute. It requests the key type (attribute 256) for key handle 524296
and writes it to the attribute.txt ﬁle.
Command: getAttribute -o 524296 -a 256 -out attribute.txt
Attributes dumped into attribute.txt file

The ﬁnal command gets the content of the key ﬁle. The output reveals that the key type is 0x15 or
21, which is a Triple DES (3DES) key. For deﬁnitions of the class and type values, see the Key Attribute
Reference (p. 176).
$ cat attribute.txt
OBJ_ATTR_KEY_TYPE

157

AWS CloudHSM User Guide
Reference
0x00000015

Example : Get All Attributes of a Key
This command gets all attributes of the key with key handle 6 and writes them to the attr_6 ﬁle. It uses
an attribute value of 512, which represents all attributes.
Command: getAttribute -o 6 -a 512 -out attr_6
got all attributes of size 444 attr cnt 17
Attributes dumped into attribute.txt file
Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS>

This command shows the content of a sample attribute ﬁle with all attribute values. Among the values, it
reports that key is a 256-bit AES key with an ID of test_01 and a label of aes256.The key is extractable
and persistent, that is, not a session-only key. For help interpreting the key attributes, see the Key
Attribute Reference (p. 176).
$

cat attribute.txt

OBJ_ATTR_CLASS
0x04
OBJ_ATTR_KEY_TYPE
0x15
OBJ_ATTR_TOKEN
0x01
OBJ_ATTR_PRIVATE
0x01
OBJ_ATTR_ENCRYPT
0x01
OBJ_ATTR_DECRYPT
0x01
OBJ_ATTR_WRAP
0x01
OBJ_ATTR_UNWRAP
0x01
OBJ_ATTR_SIGN
0x00
OBJ_ATTR_VERIFY
0x00
OBJ_ATTR_LOCAL
0x01
OBJ_ATTR_SENSITIVE
0x01
OBJ_ATTR_EXTRACTABLE
0x01
OBJ_ATTR_LABEL
aes256
OBJ_ATTR_ID
test_01
OBJ_ATTR_VALUE_LEN
0x00000020
OBJ_ATTR_KCV
0x1a4b31

Parameters
-h
Displays help for the command.

158

AWS CloudHSM User Guide
Reference

Required: Yes
-o
Speciﬁes the key handle of the target key. You can specify only one key in each command. To get the
key handle of a key, use ﬁndKey (p. 133).
Also, you must own the speciﬁed key or it must be shared with you. To ﬁnd the users of a key, use
getKeyInfo (p. 159).
Required: Yes
-a
Identiﬁes the attribute. Enter a constant that represents an attribute, or 512, which represents
all attributes. For example, to get the key type, type 256, which is the constant for the
OBJ_ATTR_KEY_TYPE attribute.
To list the attributes and their constants, use listAttributes (p. 168). For help interpreting the key
attributes, see the Key Attribute Reference (p. 176).
Required: Yes
-out
Writes the output to the speciﬁed ﬁle. Type a ﬁle path. You cannot write the output to stdout.
If the speciﬁed ﬁle exists, getAttribute overwrites the ﬁle without warning.
Required: Yes

Related Topics
• getAttribute (p. 94) in cloudhsm_mgmt_util
• listAttributes (p. 168)
• setAttribute (p. 170)
• ﬁndKey (p. 133)
• Key Attribute Reference (p. 176)

getKeyInfo
The getKeyInfo command in the key_mgmt_util returns the HSM user IDs of users who can use the key,
including the owner and crypto users (CU) with whom the key is shared. When quorum authentication
is enabled on a key, getKeyInfo also returns the number of users who must approve cryptographic
operations that use the key. You can run getKeyInfo only on keys that you own and keys that are shared
with you.
When you run getKeyInfo on public keys, getKeyInfo returns only the key owner, even though
all users of the HSM can use the public key. To ﬁnd the HSM user IDs of users in your HSMs, use
listUsers (p. 169). To ﬁnd the keys for a particular user, use ﬁndKey (p. 133) -u.
You own the keys that you create. You can share a key with other users when you create it. Then, to share
or unshare an existing key, use shareKey (p. 112) in cloudhsm_mgmt_util.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
getKeyInfo -h

159

AWS CloudHSM User Guide
Reference

getKeyInfo -k 

Examples
These examples show how to use getKeyInfo to get information about the users of a key.

Example : Get the Users for a Symmetric Key
This command gets the users who can use the AES (symmetric) key with key handle 9. The output shows
that user 3 owns the key and has shared it with user 4.
Command:

getKeyInfo -k 9

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3
also, shared to following 1 user(s):
4

Example : Get the Users for an Asymmetric Key Pair
These commands use getKeyInfo to get the users who can use the keys in an RSA (asymmetric) key pair.
The public key has key handle 21. The private key has key handle 20.
When you run getKeyInfo on the private key (20), it returns the key owner (3) and crypto users (CUs) 4
and 5, with whom the key is shared.
Command:

getKeyInfo -k 20

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3
also, shared to following 2 user(s):
4
5

When you run getKeyInfo on the public key (21), it returns only the key owner (3).
Command:

getKeyInfo -k 21

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3

To conﬁrm that user 4 can use the public key (and all public keys on the HSM), use the -u parameter of
ﬁndKey (p. 133).
The output shows that user 4 can use both the public (21) and private (20) key in the key pair. User 4 can
also use all other public keys and any private keys that they have created or that have been shared with
them.
Command: findKey -u 4
Total number of keys present 8
number of keys matched from start index 0::7

160

AWS CloudHSM User Guide
Reference
11, 12, 262159, 262161, 262162, 19, 20, 21
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Example : Get the Quorum Authentication Value (m_value) for a Key
This example shows how to get the m_value for a key, that is, the number of users in the quorum who
must approve any cryptographic operations that use the key.
When quorum authentication is enabled on a key, a quorum of users must approve any cryptographic
operations that use the key. To enable quorum authentication and set the quorum size, use the m_value parameter when you create the key.
This command uses genRSAKeyPair (p. 146) to create an RSA key pair that is shared with user 4. It
uses the m_value parameter to enable quorum authentication on the private key in the pair and set the
quorum size to two users. The number of users must be large enough to provide the required approvals.
The output shows that the command created public key 27 and private key 28.
Command:

genRSAKeyPair -m 2048 -e 195193 -l rsa_mofn -id rsa_mv2 -u 4 -m_value 2

Cfm3GenerateKeyPair returned: 0x00 : HSM Return: SUCCESS
Cfm3GenerateKeyPair:

public key handle: 27

private key handle: 28

Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
Node id 1 and err state 0x00000000 : HSM Return: SUCCESS

This command uses getKeyInfo to get information about the users of the private key. The output shows
that the key is owned by user 3 and shared with user 4. It also shows that a quorum of two users must
approve every cryptographic operation that uses the key.
Command:

getKeyInfo -k 28

Cfm3GetKey returned: 0x00 : HSM Return: SUCCESS
Owned by user 3
also, shared to following 1 user(s):
4
2 Users need to approve to use/manage this key

Parameters
-h
Displays command line help for the command.
Required: Yes
-k
Speciﬁes the key handle of one key in the HSM. Enter the key handle of a key that you own or share.
This parameter is required.
To ﬁnd key handles, use the ﬁndKey (p. 169) command.

161

AWS CloudHSM User Guide
Reference

Required: Yes

Related Topics
• getKeyInfo (p. 99) in cloudhsm_mgmt_util
• listUsers (p. 169)
• ﬁndKey (p. 133)
• ﬁndAllKeys (p. 91) in cloudhsm_mgmt_util

imSymKey
The imSymKey command in the key_mgmt_util tool imports a plaintext copy of a symmetric key from a
ﬁle into the HSM. You can use it to import keys that you generate by any method outside of the HSM and
keys that were exported from an HSM, such as the keys that the exSymKey (p. 129), command writes to
a ﬁle.
During the import process, imSymKey uses an AES key that you select (the wrapping key) to wrap
(encrypt) and then unwrap (decrypt) the key to be imported. However, imSymKey works only on ﬁles
that contain plaintext keys. To export and import encrypted keys, use the wrapKey (p. 175) and
unWrapKey (p. 172) commands.
Also, the imSymKey command exports only symmetric keys. To import public keys, use importPubKey.
To import private keys, use importPrivateKey or wrapKey.
Imported keys work very much like keys generated in the HSM. However, the value of the
OBJ_ATTR_LOCAL attribute (p. 176) is zero, which indicates that it was not generated locally. You
can use the following command to share a symmetric key as you import it. You can use the shareKey
command in cloudhsm_mgmt_util (p. 74) to share the key after it is imported.
imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5

After you import a key, be sure to mark or delete the key ﬁle. This command does not prevent you from
importing the same key material multiple times. The result, multiple keys with distinct key handles and
the same key material, make it diﬃcult to track use of the key material and prevent it from exceeding its
cryptographic limits.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
imSymKey -h
imSymKey -f 
-w 
-t 
-l 
[-id ]
[-sess]
[-wk  ]
[-attest]
[-min_srv ]
[-timeout  ]
[-u ]

162

AWS CloudHSM User Guide
Reference

Examples
These examples show how to use imSymKey to import symmetric keys into your HSMs.

Example : Import an AES Symmetric Key
This example uses imSymKey to import an AES symmetric key into the HSMs.
The ﬁrst command uses OpenSSL to generate a random 256-bit AES symmetric key. It saves the key in
the aes256.key ﬁle.
$

openssl rand -out aes256-forImport.key 32

The second command uses imSymKey to import the AES key from the aes256.key ﬁle into the HSMs. It
uses key 20, an AES key in the HSM, as the wrapping key and it speciﬁes a label of imported. Unlike the
ID, the label does not need to be unique in the cluster. The value of the -t (type) parameter is 31, which
represents AES.
The output shows that the key in the ﬁle was wrapped and unwrapped, then imported into the HSM,
where it was assigned the key handle 262180.
Command:

imSymKey -f aes256.key -w 20 -t 31 -l imported
Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Unwrapped.
Cluster
Node id
Node id
Node id

Error
1 and
0 and
2 and

Key Handle: 262180

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

The next command uses getAttribute (p. 156) to get the OBJ_ATTR_LOCAL attribute (attribute
355 (p. 176)) of the newly imported key and writes it to the attr_262180 ﬁle.
Command: getAttribute -o 262180 -a 355 -out attributes/attr_262180
Attributes dumped into attributes/attr_262180_imported file
Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS

When you examine the attribute ﬁle, you can see that the value of the OBJ_ATTR_LOCAL attribute is
zero, which indicates that the key material was not generated in the HSM.
$ cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000

Example : Move a Symmetric Key Between Clusters
This example shows how to use exSymKey and imSymKey to move a plaintext AES key between clusters.
You might use a process like this one to create an AES wrapping that exists on the HSMs both clusters.
Once the shared wrapping key is in place, you can use wrapKey (p. 175) and unWrapKey (p. 172) to
move encrypted keys between the clusters.
The CU user who performs this operation must have permission to log in to the HSMs on both clusters.

163

AWS CloudHSM User Guide
Reference

The ﬁrst command uses exSymKey to export key 14, a 32-bit AES key, from the cluster 1 into the
aes.key ﬁle. It uses key 6, an AES key on the HSMs in cluster 1, as the wrapping key.
Command: exSymKey -k 14 -w 6 -out aes.key
Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS
Wrapped Symmetric Key written to file "aes.key"

The user then logs into key_mgmt_util in cluster 2 and runs an imSymKey command to import the key in
the aes.key ﬁle into the HSMs in cluster 2. This command uses key 252152, an AES key on the HSMs in
cluster 2, as the wrapping key.
Because the wrapping keys that exSymKey and imSymKey use wrap and immediately unwrap the target
keys, the wrapping keys on the diﬀerent clusters need not be the same.
The output shows that the key was successfully imported into cluster 2 and assigned a key handle of 21.
Command:

imSymKey -f aes.key -w 262152 -t 31 -l xcluster
Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Unwrapped.
Cluster
Node id
Node id
Node id

Error
1 and
0 and
2 and

Key Handle: 21

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

To prove that key 14 of cluster 1 and key 21 in cluster 2 have the same key material, get the key check
value (KCV) of each key. If the KCV values are the same, the key material is the same.
The following command uses getAttribute (p. 156) in cluster 1 to write the value of the KCV attribute
(attribute 371) of key 14 to the attr_14_kcv ﬁle. Then, it uses a cat command to get the content of the
attr_14_kcv ﬁle.
Command: getAttribute -o 14 -a 371 -out attr_14_kcv
Attributes dumped into attr_14_kcv file
$ cat attr_14_kcv
OBJ_ATTR_KCV
0xc33cbd

This similar command uses getAttribute (p. 156) in cluster 2 to write the value of the KCV attribute
(attribute 371) of key 21 to the attr_21_kcv ﬁle. Then, it uses a cat command to get the content of the
attr_21_kcv ﬁle.
Command: getAttribute -o 21 -a 371 -out attr_21_kcv
Attributes dumped into attr_21_kcv file
$ cat attr_21_kcv
OBJ_ATTR_KCV
0xc33cbd

164

AWS CloudHSM User Guide
Reference

The output shows that the KCV values of the two keys are the same, which proves that the key material is
the same.
Because the same key material exists in the HSMs of both clusters, you can now share encrypted keys
between the clusters without ever exposing the plaintext key. For example, you can use the wrapKey
command with wrapping key 14 to export an encrypted key from cluster 1, and then use unWrapKey
with wrapping key 21 to import the encrypted key into cluster 2.

Example : Import a Session Key
This command uses the -sess parameters of imSymKey to import a 192-bit Triple DES key that is valid
only in the current session.
The command uses the -f parameter to specify he ﬁle that contains the key to import, the -t parameter
to specify the key type, and the -w parameter to specify the wrapping key. It uses the -l parameter to
specify a label that categorizes the key and the -id parameter to create a friendly, but unique, identiﬁer
for the key. It also uses the -attest parameter to verify the ﬁrmware that is importing the key.
The output shows that the key was successfully wrapped and unwrapped, imported into the HSM, and
assigned the key handle 37. Also, the attestation check passed, which indicates that the ﬁrmware has not
been tampered.
Command:

imSymKey -f 3des192.key -w 6 -t 21 -l temp -id test01 -sess -attest
Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS
Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS
Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS
Symmetric Key Unwrapped.

Key Handle: 37

Attestation Check : [PASS]
Cluster Error Status
Node id 0 and err state 0x00000000 : HSM Return: SUCCESS

Next, you can use the getAttribute (p. 156) or ﬁndKey (p. 133) commands to verify the attributes of
the newly imported key. The following command uses findKey to verify that key 37 has the type, label,
and ID speciﬁed by the command, and that it is a session key. A shown on line 5 of the output, findKey
reports that the only key that matches all of the attributes is key 37.
Command: findKey -t 21 -l temp -id test01 -sess 1
Total number of keys present 1
number of keys matched from start index 0::0
37
Cluster
Node id
Node id
Node id

Error
1 and
0 and
2 and

Status
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS
err state 0x00000000 : HSM Return: SUCCESS

Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

Parameters
-attest
Runs an integrity check that veriﬁes that the ﬁrmware on which the cluster runs has not been
tampered with.

165

AWS CloudHSM User Guide
Reference

Default: No attestation check.
Required: No
-f
Speciﬁes the ﬁle that contains that key to import.
The ﬁle must contain a plaintext copy of an AES or Triple DES key of the speciﬁed length. RC4 and
DES keys are not valid on FIPS-mode HSMs.
• AES: 16, 24 or 32 bytes
• Triple DES (3DES): 24 bytes
Required: Yes
-h
Displays help for the command.
Required: Yes
-id
Speciﬁes a user-deﬁned identiﬁer for the key. Type a string that is unique in the cluster. The default
is an empty string.
Default: No ID value.
Required: No
-l
Speciﬁes a user-deﬁned label for the key. Type a string.
You can use any phrase that helps you to identify the key. Because the label does not have to be
unique, you can use it to group and categorize keys.
Required: Yes
-min_srv
Speciﬁes the minimum number of HSMs on which the key is synchronized before the value of the timeout parameter expires. If the key is not synchronized to the speciﬁed number of servers in the
time allotted, it is not created.
AWS CloudHSM automatically synchronizes every key to every HSM in the cluster. To speed up your
process, set the value of min_srv to less than the number of HSMs in the cluster and set a low
timeout value. Note, however, that some requests might not generate a key.
Default: 1
Required: No
-sess
Creates a key that exists only in the current session. The key cannot be recovered after the session
ends.
Use this parameter when you need a key only brieﬂy, such as a wrapping key that encrypts, and
then quickly decrypts, another key. Do not use a session key to encrypt data that you might need to
decrypt after the session ends.
To change a session key to a persistent (token) key, use setAttribute (p. 170).
Default: The key is persistent.

166

AWS CloudHSM User Guide
Reference

Required: No
-timeout
Speciﬁes how long (in seconds) the command waits for a key to be synchronized to the number of
HSMs speciﬁed by the min_srv parameter.
This parameter is valid only when the min_srv parameter is also used in the command.
Default: No timeout. The command waits indeﬁnitely and returns only when the key is synchronized
to the minimum number of servers.
Required: No
-t
Speciﬁes the type of the symmetric key. Enter the constant that represents the key type. For
example, to create an AES key, enter -t 31.
Valid values:
• 21: Triple DES (3DES).
• 31: AES
Required: Yes
-u
Shares the key you are importing with speciﬁed users. This parameter gives other HSM crypto users
(CUs) permission to use this key in cryptographic operations.
Type one ID or a comma-separated list of HSM user IDs, such as -u 5,6. Do not include the
HSM user ID of the current user. To ﬁnd the an ID, you can use the listUsers command in the
cloudhsm_mgmt_util command line tool or the listUsers command in the key_mgmt_util command
line tool.
Required: No
-w
Speciﬁes the key handle of the wrapping key. This parameter is required. To ﬁnd key handles, use the
ﬁndKey (p. 133) command.
A wrapping key is a key in the HSM that is used to encrypt ("wrap") and then decrypt ("unwrap) the
key during the import process. Only AES keys can be used as wrapping keys.
You can use any AES key (of any size) as a wrapping key. Because the wrapping key wraps, and then
immediately unwraps, the target key, you can use as session-only AES key as a wrapping key. To
determine whether a key can be used as a wrapping key, use getAttribute (p. 156) to get the value
of the OBJ_ATTR_WRAP attribute (262). To create a wrapping key, use genSymKey (p. 151) to
create an AES key (type 31).
If you use the -wk parameter to specify an external wrapping key, the -w wrapping key is used to
unwrap, but not to wrap, the key that is being imported.

Note

Key 4 is an unsupported internal key. We recommend that you use an AES key that you
create and manage as the wrapping key.
Required: Yes
-wk
Use the AES key in the speciﬁed ﬁle to wrap the key that is being imported. Enter the path and name
of a ﬁle that contains a plaintext AES key.

167

AWS CloudHSM User Guide
Reference

When you include this parameter. imSymKey uses the key in the -wk ﬁle to wrap the key being
imported and it uses the key in the HSM that is speciﬁed by the -w parameter to unwrap it. The -w
and -wk parameter values must resolve to the same plaintext key.
Default: Use the wrapping key on the HSM to unwrap.
Required: No

Related Topics
• genSymKey (p. 151)
• exSymKey (p. 129)
• wrapKey (p. 175)
• unWrapKey (p. 172)
• exportPrivateKey
• exportPubKey

listAttributes
The listAttributes command in key_mgmt_util lists the attributes of an AWS CloudHSM key
and the constants that represent them. You use these constants to identify the attributes in
getAttribute (p. 156) and setAttribute (p. 170) commands. For help interpreting the key attributes,
see the Key Attribute Reference (p. 176).
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
This command has no parameters.
listAttributes

Example
This command lists the key attributes that you can get and change in key_mgmt_util and the constants
that represent them. For help interpreting the key attributes, see the Key Attribute Reference (p. 176).
To represent all attributes in the getAttribute (p. 156) command in key_mgmt_util, use 512.
Command: listAttributes
Following are the possible attribute values for getAttributes:
OBJ_ATTR_CLASS
OBJ_ATTR_TOKEN
OBJ_ATTR_PRIVATE
OBJ_ATTR_LABEL
OBJ_ATTR_KEY_TYPE
OBJ_ATTR_ENCRYPT
OBJ_ATTR_DECRYPT
OBJ_ATTR_WRAP
OBJ_ATTR_UNWRAP
OBJ_ATTR_SIGN
OBJ_ATTR_VERIFY
OBJ_ATTR_LOCAL

=
=
=
=
=
=
=
=
=
=
=
=

0
1
2
3
256
260
261
262
263
264
266
355

168

AWS CloudHSM User Guide
Reference
OBJ_ATTR_MODULUS
OBJ_ATTR_MODULUS_BITS
OBJ_ATTR_PUBLIC_EXPONENT
OBJ_ATTR_VALUE_LEN
OBJ_ATTR_EXTRACTABLE
OBJ_ATTR_KCV

=
=
=
=
=
=

288
289
290
353
354
371

Related Topics
• listAttributes (p. 103) in cloudhsm_mgmt_util
• getAttribute (p. 156)
• setAttribute (p. 170)
• Key Attribute Reference (p. 176)

listUsers
The listUsers command in the key_mgmt_util gets the users in the HSMs, along with their user type and
other attributes.
In key_mgmt_util, listUsers returns output that represents all HSMs in the cluster, even if they are not
consistent. To get information about the users in each HSM, use the listUsers (p. 169) command in
cloudhsm_mgmt_util.
The user commands in key_mgmt_util, listUsers and getKeyInfo, are read-only commands that
crypto users (CUs) have permission to run. The remaining user management commands are part of
cloudhsm_mgmt_util. They are run by crypto oﬃcers (CO) who have user management permissions.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
listUsers
listUsers -h

Example
This command lists the users of HSMs in the cluster and their attributes. You can use the User ID
attribute to identify users in other commands, such as ﬁndKey (p. 133), getAttribute (p. 156), and
getKeyInfo (p. 159).
Command:

listUsers
Number Of Users found 4

Index
LoginFailureCnt
1
0
2
0
3
0
4
0
5
0

NO
NO
NO
NO
NO

User ID
2FA
1

User Type

User Name

PCO

admin

NO

2

AU

app_user

NO

3

CU

alice

YES

4

CU

bob

NO

5

CU

trent

YES

169

MofnPubKey

AWS CloudHSM User Guide
Reference

Cfm3ListUsers returned: 0x00 : HSM Return: SUCCESS

The output includes the following user attributes:
• User ID: Identiﬁes the user in key_mgmt_util and cloudhsm_mgmt_util (p. 74) commands.
• User type (p. 10): Determines the operations that the user can perform on the HSM.
• User Name: Displays the user-deﬁned friendly name for the user.
• MofnPubKey: Indicates whether the user has registered a key pair for signing quorum authentication
tokens (p. 61).
• LoginFailureCnt:
• 2FA: Indicates that the user has enabled multi-factor authentication.

Parameters
-h
Displays help for the command.
Required: Yes

Related Topics
• listUsers (p. 169) in cloudhsm_mgmt_util
• ﬁndKey (p. 133)
• getAttribute (p. 156)
• getKeyInfo (p. 159)

setAttribute
The setAttribute command in key_mgmt_util converts a key that is valid only in the current session to a
persistent key that exists until you delete it. It does this by changing the value of the token attribute of
the key (OBJ_ATTR_TOKEN) from false (0) to true (1). You can only change the attributes of keys that you
own.
You can also use the setAttribute command in cloudhsm_mgmt_util to change the label, wrap,
unwrap, encrypt, and decrypt attributes.
Before you run any key_mgmt_util command, you must start key_mgmt_util (p. 121) and
login (p. 122) to the HSM as a crypto user (CU).

Syntax
setAttribute -h
setAttribute -o
AWS CloudHSM User Guide

Navigation menu

Versions of this User Manual:

Views

Navigation
