Vous êtes sur la page 1sur 49

AWS CloudHSM

Getting Started Guide

AWS CloudHSM Getting Started Guide

Amazon Web Services

AWS CloudHSM Getting Started Guide

AWS CloudHSM: Getting Started Guide


Amazon Web Services
Copyright 2014 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
The following are trademarks of Amazon Web Services, Inc.: Amazon, Amazon Web Services Design, AWS, Amazon CloudFront,
Cloudfront, Amazon DevPay, DynamoDB, ElastiCache, Amazon EC2, Amazon Elastic Compute Cloud, Amazon Glacier, Kindle, Kindle
Fire, AWS Marketplace Design, Mechanical Turk, Amazon Redshift, Amazon Route 53, Amazon S3, Amazon VPC. In addition,
Amazon.com graphics, logos, page headers, button icons, scripts, and service names are trademarks, or trade dress of Amazon in
the U.S. and/or other countries. Amazon's trademarks and trade dress may not be used in connection with any product or service that
is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits
Amazon.
All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected
to, or sponsored by Amazon.

AWS CloudHSM Getting Started Guide

Getting Started with AWS CloudHSM ..................................................................................................... 1


What Is AWS CloudHSM? ...................................................................................................................... 1
Before You Begin ........................................................................................................................... 2
Getting Set Up with AWS CloudHSM ................................................................................................... 10
Configuring AWS CloudHSM ................................................................................................................ 11
Configuring Your HSM Appliance .......................................................................................................... 11
Configuring Your HSM Client ................................................................................................................ 14
Configuring the HSM Client Using Linux/UNIX ........................................................................... 14
Create a Network Trust Link using Linux/UNIX .................................................................. 15
Configuring the HSM Client Using Windows ............................................................................... 17
Create a Network Trust Link using Windows ...................................................................... 18
Operations and Maintenance ................................................................................................................ 21
Configuring High Availability and Load Balancing ................................................................................ 21
HA Failover and Auto-Recovery .................................................................................................. 26
Best Practices for High Availability and Load Balancing ............................................................. 26
Resynchronizing HSM Appliances ........................................................................................................ 29
Backing Up and Restoring HSM Data to a Luna SA Backup HSM ....................................................... 30
How to Stop Using an HSM .................................................................................................................. 35
Best Practices ....................................................................................................................................... 36
Troubleshooting .................................................................................................................................... 36
Appendices ........................................................................................................................................... 36
Connecting Multiple Client Instances to AWS CloudHSM with One Certificate .......................... 38
Integrating Third-Party Applications with AWS CloudHSM .......................................................... 40
Building a Test Application ........................................................................................................... 41
Building Your Own Applications ................................................................................................... 43
Where to Get Additional Help ............................................................................................................... 44
Document History ................................................................................................................................. 45

AWS CloudHSM Getting Started Guide


What Is AWS CloudHSM?

Getting Started with AWS


CloudHSM
AWS CloudHSM provides secure cryptographic key storage to customers by making hardware security
modules (HSMs) available in the AWS cloud.
This guide gives you a hands-on introduction to using AWS CloudHSM, by walking you through the steps
needed to set up and configure your HSM appliance, integrate third-party software applications with AWS
CloudHSM, and write a simple application that uses the HSM appliance. This guide also describes best
practices for using the AWS CloudHSM service.
Topics
What Is AWS CloudHSM? (p. 1)
Getting Set Up with AWS CloudHSM (p. 10)
Configuring AWS CloudHSM (p. 11)
Configuring Your HSM Appliance (p. 11)
Configuring Your HSM Client (p. 14)
Operations and Maintenance (p. 21)
Configuring High Availability and Load Balancing (p. 21)

Resynchronizing HSM Appliances (p. 29)


Backing Up and Restoring HSM Data to a Luna SA Backup HSM (p. 30)
How to Stop Using an HSM (p. 35)
Best Practices (p. 36)

Troubleshooting (p. 36)


Appendices (p. 36)

What Is AWS CloudHSM?


A hardware security module (HSM) is a hardware appliance that provides secure key storage and
cryptographic operations within a tamper-resistant hardware module. HSMs are designed to securely
store cryptographic key material and use the key material without exposing it outside the cryptographic
boundary of the appliance.

AWS CloudHSM Getting Started Guide


Before You Begin

AWS CloudHSM helps you meet corporate, contractual and regulatory compliance requirements for data
security by using dedicated HSM appliances within the AWS cloud. AWS and AWS Marketplace partners
offer a variety of solutions for protecting sensitive data within the AWS platform, but additional protection
is necessary for some applications and data that are subject to strict contractual or regulatory requirements
for managing cryptographic keys.
Until now, your only options were to maintain the sensitive data or the encryption keys protecting the
sensitive data in your on-premises data centers. However, those options either prevented you from
migrating these applications to the cloud or significantly slowed application performance. AWS CloudHSM
allows you to protect your encryption keys within HSMs that are designed and validated to government
standards for secure key management. You can securely generate, store, and manage the cryptographic
keys used for data encryption in a way that ensures that only you have access to the keys. AWS CloudHSM
helps you comply with strict key management requirements within the AWS cloud without sacrificing
application performance.
AWS CloudHSM works with Amazon Virtual Private Cloud (Amazon VPC). HSM appliances are provisioned
inside your VPC with an IP address that you specify, providing simple and private network connectivity
to your EC2 instances. Placing HSM appliances near your EC2 instances decreases network latency,
which can improve application performance. Your HSM appliances are dedicated exclusively to you and
are isolated from other AWS customers. Available in multiple regions and Availability Zones, AWS
CloudHSM can be used to build highly available and durable applications.
For more information on Amazon VPC, see What Is VPC? in the Amazon Virtual Private Cloud User
Guide.

Important
AWS strongly recommends that you use two or more HSM appliances in a high availability (HA)
configuration. The failure of a single HSM appliance in a non-HA configuration can result in the
permanent loss of keys and data. For information about how to set up a high availability
configuration, go to Configuring High Availability and Load Balancing (p. 21).

Before You Begin


Before you sign up for AWS CloudHSM, you must have an AWS account and a virtual private cloud
(VPC), which is an isolated portion of the AWS cloud, in the region where you want AWS CloudHSM
service. Security group rules are required to connect to AWS CloudHSM through your VPC. For more
information about Amazon VPC, see What Is VPC? in the Amazon Virtual Private Cloud User Guide.
There are two ways to set up your AWS CloudHSM environment:
Automatically: Use AWS CloudFormation templates to provision your AWS CloudHSM environment
automatically. For more information, see Automatically Setting Up Your AWS CloudHSM Environment
Using AWS CloudFormation (p. 3).
Manually: Create a VPC and security group rules (p. 6), and collect the information that is required
by AWS to provision your AWS CloudHSM service.

To create an AWS account and sign up for CloudHSM


1.

If you have an AWS account already, skip to the next step. If you don't have an AWS account, use
the following procedure to create one.
a.
b.

Go to http://aws.amazon.com and click Sign Up Now.


Follow the on-screen instructions.

Part of the sign-up process involves receiving a phone call and entering a PIN using the phone
keypad. AWS notifies you by email when your account is active and available for you to use.

AWS CloudHSM Getting Started Guide


Before You Begin

2.

3.

Sign up for AWS CloudHSM by clicking Contact Us on the AWS CloudHSM page, completing the
form, and selecting Start service or Try the service. The AWS CloudHSM team will contact you
with further instructions.
In the meantime, complete the steps below to create a VPC and security group rules, and collect the
information that is required by AWS to provision your AWS CloudHSM service. You can do this
automatically, using AWS CloudFormation (p. 3), or you can do it manually (p. 6).

Automatically Setting Up Your AWS CloudHSM Environment


Using AWS CloudFormation
You can use the AWS CloudFormation template provided by the AWS CloudHSM team to set up an
environment automatically for your AWS CloudHSM service. Complete the steps below to use AWS
CloudFormation to create several AWS resources, including a VPC, a subnet in the VPC, and an IAM
role that the AWS CloudHSM team uses in the provisioning process.
The following diagram demonstrates how AWS CloudFormation automatically sets up your AWS CloudHSM
environment.

The following components are set up by AWS CloudFormation:


1. A VPC.
2. An EC2 instance (m1.small running AWS x86 64-bit Linux) in the public subnet, with the SafeNet client
software already installed. The instance uses the key that you specified during the creation of the AWS
CloudFormation stack.

AWS CloudHSM Getting Started Guide


Before You Begin

3. Subnets are created as follows: one subnet that is publicly accessible, and one private subnet per
Availability Zone. For example:
For regions which have three Availability Zones, four VPC subnets are created: one subnet that is
publicly accessible (3a), and three private subnets (3b, 3c, and 3d).
For regions which have two Availability Zones, three subnets are created: one subnet that is publicly
accessible (3a), and two private subnets (3c and 3d).

Note
The AWS CloudHSM team provisions an HSM appliance into the private subnet, to isolate it
from the rest of the Internet.
4. Security groups that allow both SSH into the public subnet from the Internet, and SSH and NTLS into
the private subnet from the public subnet.
5. An Elastic IP address for the EC2 instance.
Also included are the IAM role needed for the AWS CloudHSM provisioning process, as well as IAM
credentials used to send an SNS notification of your stack's configuration to the AWS CloudHSM team.

To use AWS CloudFormation to set up your AWS CloudHSM environment automatically


1.
2.
3.
4.

5.

If you have not already done so, sign up for AWS CloudFormation. For more information, see Getting
Started with AWS CloudFormation in the AWS CloudFormation User Guide.
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
Select CloudFormation.
Click Create Stack. Give the stack a meaningful name, such as AWS CloudHSM environment.
Select Provide a Template URL, and type
http://cloudhsm.s3.amazonaws.com/cloudhsm-quickstart.json , then click Continue.

In KeyName, provide the name of an existing Amazon EC2 key pair and check I acknowledge that
this template may create IAM resources.

AWS CloudHSM Getting Started Guide


Before You Begin

6.

Add any tags you want to apply to the stack, then click Continue.

7.

Review your settings, then click Continue.

8.

When the EC2 instance boots, it creates data about your stack's configuration settings, such as the
private subnet ID and the IAM role ARN created for AWS CloudHSM.

Click your stack in the AWS CloudFormation console. This shows you the stack detail pane.
In the detail pane, click the Outputs tab to view the outputs associated with your stack. For more
information about stacks, see Viewing the Outputs of an AWS CloudFormation Stack in the AWS
CloudFormation User Guide.
10. Make note of the stack outputs, as you must provide these to the AWS CloudHSM team. After your
HSM appliance has been provisioned, you can configure the EC2 instance to connect to AWS
CloudHSM by following the instructions in Configuring Your HSM Client (p. 14).
11. You can now proceed to Getting Set Up with AWS CloudHSM (p. 10).
9.

AWS CloudHSM Getting Started Guide


Before You Begin

Manually Setting Up Your AWS CloudHSM Environment


After you create a VPC but before AWS can provision your AWS CloudHSM service, you must first give
AWS permission to attach the network interfaces of the HSMs inside your VPC. The steps below walk
you through how to create a VPC and add a new IAM role to allow AWS to create and attach an elastic
network interface (ENI) to your VPC. After you follow those steps, you must provide the information to
AWS that is required to provision your service. After you provide the necessary information, AWS creates
the ENI, attaches your HSM through the ENI, and sends you further instructions and credentials for logging
in to the HSM.

Note
These steps are not necessary if you have completed the steps in Automatically Setting Up Your
AWS CloudHSM Environment Using AWS CloudFormation (p. 3).

To create a VPC and security group rules


After you have created an AWS account and completed the form to sign up for AWS CloudHSM, use the
following procedure to create a VPC and security group rules. Whether you are creating a VPC for the
first time or you already have a VPC, you must add security groups and rules to connect to AWS
CloudHSM.
1.

In the Amazon VPC console, create a VPC, set up the VPC and Internet gateway, and set up a
security group.You must choose one of the following regions that currently support AWS CloudHSM:

us-east-1
eu-west-1
us-west-2
ap-southeast-2

For more information, see Getting Started with Amazon VPC in the Amazon Virtual Private Cloud
Getting Started Guide.

2.
3.

After setting up a security group but before you launch an instance, complete the following additional
steps.
In the NETWORK & SECURITY section of the navigation pane, select Security Groups, then select
the security group that you created for your VPC.
Create an RDP rule for inbound traffic. If you connect to your VPC via Windows Remote Desktop
Protocol (RDP):
a.

b.

4.

Create an SSH rule for inbound traffic. If you connect to your VPC via SSH:
a.

b.

5.

On the Inbound tab, in the Create a new rule: list, select RDP. Type the source IP address
range of the sites from which you will connect to your VPC, so that connections are only allowed
from your site. This opens port 3389, which is required if you are connecting to your instance
via Windows using RDP.
Click Add Rule, then click Apply Rule Changes.

On the Inbound tab, in the Create a new rule: list, select SSH, then enter the source IP address
range of the sites from which you will connect to your VPC, so that connections are only allowed
from your site. This opens port 22, so you can open a terminal connection to your VPC.
Click Add Rule, then click Apply Rule Changes.

Create a custom TCP rule for inbound traffic.

AWS CloudHSM Getting Started Guide


Before You Begin

6.

a.

On the Inbound tab, in the Create a new rule: list, select Custom TCP rule. In the Port range:
box, type 1792. In the Destination: box, type the IP address of your VPC subnet (for example,
10.0.0.0/16). This opens port 1792, which allows access via your VPC subnet.

b.

Click Add Rule, then click Apply Rule Changes.

Add outbound traffic rules.


a.

b.

On the Outbound tab, in the Create a new rule: list, select SSH. In the Destination: box, type
the IP address of your VPC subnet. This opens port 22, so you can open an SSH terminal
connection to the HSM appliance.
Click Add Rule, then click Apply Rule Changes.

c.

On the Outbound tab, in the Create a new rule: list, select Custom TCP rule. In the Port
range: box, type 1792. In the Destination: box, type the IP address of your VPC subnet. This
opens port 1792, which allows access via your VPC subnet.

d.

Click Add Rule, then click Apply Rule Changes.

Note
The security group rules provided here are the minimum set of rules that you need to get started
with the AWS CloudHSM service. For production deployments, you should define appropriate
rules to constrain network traffic according to your security policies and best practices.

To prepare to sign up for AWS CloudHSM


After completing the following steps, you will have the information AWS requires to sign you up for AWS
CloudHSM. Repeat these steps as necessary for each AWS CloudHSM you set up in each region.
1.
2.
3.
4.

Sign in to the AWS Management Console using the sign-in page.


Under Deployment and Management, select IAM.
Select Roles, and then click Create New Role to start the wizard.
Type a unique name for your AWS CloudHSM in the Role Name box (such as
CloudHSMYourCompanyName) and click Continue. The name must be unique and cannot contain
spaces.

5.

Under Select Role Type, select AWS Service Roles, and then click Select next to AWS CloudHSM.

AWS CloudHSM Getting Started Guide


Before You Begin

6.

Review the policy statement to confirm that you are granting permission to the AWS CloudHSM
service to perform the actions listed. These actions are required in order for the AWS CloudHSM
service to attach an ENI in your VPC. After reviewing and accepting the policy and permissions, click
Continue.

7.

Click Create Role.

8.

In the IAM console, select the role you just created, then select the Summary tab. Verify that the
information is correct, then note the role ARN to provide to AWS later.

AWS CloudHSM Getting Started Guide


Before You Begin

9.

Make note of the following values to provide to AWS:


The number of HSMs you have created in each region.
Your PGP public key, if you would like AWS to send you an encrypted email containing the HSM
password. For more information about creating a PGP key and receiving and decrypting
PGP-encrypted email, go to the definition of PGP on Wikipedia.
Subnet-ID value of the subnet to which you want your HSM appliance connected. To assign this
value, from the AWS Management Console, select Service, then VPC. Choose Subnets from the
navigation pane, then choose the subnet on which you want your HSM connected. Record the
subnet ID; for example, subnet-428104af.
The IP address of the HSM appliance.
Choose an available IP address on the subnet you selected in the previous step. You must
choose an IP address that is not in use by any other network device on the subnet.
Role ARN
To find your role ARN, from the AWS Management Console dashboard, select IAM, then Roles.
Select the role, then the Summary tab. The Role ARN is the first box.

To find your External ID, from the AWS Management Console dashboard, select IAM, then Roles.
Select the role, then the Trust Relationships tab. The External ID is in the Key:Value column.

AWS CloudHSM Getting Started Guide


Getting Set Up with AWS CloudHSM

10. Contact the AWS CloudHSM team with the information you collected in the previous step. The AWS
CloudHSM team creates an elastic network interface (ENI) on the subnet that you specified, assigns
to your HSM appliance the IP address that you specified, and sends you login credentials that allow
you to connect to your HSM appliance.
11. Proceed to Getting Set Up with AWS CloudHSM (p. 10).

Getting Set Up with AWS CloudHSM


The following diagram and procedures demonstrate how to set up AWS CloudHSM. After you complete
the procedures, you will have a running application that uses an HSM for cryptographic operations and
key storage.

This list summarizes the procedures needed to get up and running with AWS CloudHSM. Step-by-step
instructions are detailed in the sections below.
1. If you have not already done so, follow the steps in the previous section to create a VPC and security
group rules (p. 6). This allows you to connect from your instance to your HSM appliance.
2. If you are manually (p. 6) setting up your AWS CloudHSM environment, launch an EC2-VPC
instance (p. 11). Your application and the HSM client that communicates with the HSM appliance run
on this instance.

Note
These steps are not necessary if you have completed the steps in Automatically Setting Up
Your AWS CloudHSM Environment Using AWS CloudFormation (p. 3).
3. Initialize and configure HSM appliances (p. 11).
4. (Optional) Initialize, connect and configure your on-premise HSM appliances (p. 14).
5. Configure your HSM client (p. 14).
6. Configure HA (p. 21).
7. Select from the following two options:
Integrate AWS CloudHSM with third-party software applications. For more information, see Integrating
Third-Party Applications with AWS CloudHSM (p. 40).
Building a Test Application (p. 41) to prepare to Building Your Own Applications (p. 43).

10

AWS CloudHSM Getting Started Guide


Configuring AWS CloudHSM

Important
This guide provides an abbreviated set of instructions that allow you to get started quickly with
your AWS CloudHSM service. To secure production deployments, be sure to read the detailed
descriptions and background information provided in the SafeNet Luna SA documentation in
order to get a deeper understanding of the operation of the HSM. This guide does not attempt
to provide those important details, which are essential for secure operation of the HSM.

Configuring AWS CloudHSM


When you sign up for AWS CloudHSM, you receive an IP address and unique login credentials (username
and password) for each HSM appliance. When you set up and configure your HSM, you may find it useful
to keep track of your configuration information. For more information, go to Worksheet for Luna Appliance
and HSM Setup in the SafeNet Luna SA documentation.
When you are finished, store the completed worksheet in a secure location for future reference. It is also
recommended that you store at least one copy of the worksheet in secure offsite storage.

Note
These steps are not necessary if you have completed the steps in Automatically Setting Up Your
AWS CloudHSM Environment Using AWS CloudFormation (p. 3).

To launch an EC2-VPC instance


Use the following procedure to launch an instance in your VPC. You must first create a VPC and security
group rules. For more information, see Create a VPC and security group rules (p. 6).
1.
2.
3.

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.


From the navigation bar, select the region in which your VPC is located (for example, us-east).
Click Launch Instance, click Classic Wizard, and then click Continue.

Note
We recommend using the Classic Wizard to create your instance, so that you can select
your VPC.
4.
5.
6.
7.
8.
9.

Choose an AMI, then click Select.


Under Launch Info, select VPC. Select your VPC, then select your subnet and click Continue. In
the next dialog box, accept the defaults and click Continue, then click Continue again.
In the Value box, enter a name for your instance and click Continue.
If you already have a key pair, select it from the list; otherwise, click Create a New Key Pair.
Select the security group you created earlier in this procedure, and click Continue. Review your
instance details, then click Launch.
Create an Elastic IP address. For more information, see Getting Started with Amazon VPC in the
Amazon Virtual Private Cloud Getting Started Guide.

Configuring Your HSM Appliance


When you sign up for AWS CloudHSM, you receive an IP address and unique login credentials (username
and password) for each HSM appliance.
When you set up and configure your HSM appliance, you may find it useful to keep track of your
configuration information. For more information, go to Worksheet for Luna Appliance and HSM Setup in
the SafeNet Luna SA documentation.

11

AWS CloudHSM Getting Started Guide


Configuring Your HSM Appliance

When you are finished, store the completed worksheet in a secure location for future reference. It is also
recommended that you store at least one copy of the worksheet in secure offsite storage.

To initialize and configure HSM appliances


Use the following procedures to initialize the HSM appliance and configure the HSM client. Repeat as
needed for each appliance or client.
1.

After AWS connects your HSM to your VPC, confirm that the elastic network interface (ENI) exists
and confirm its IP address. To find the new ENI of the HSM, from the AWS Management Console
dashboard, select EC2, then Network Interfaces. On the Viewing menu, select All VPC Network
Interfaces. The table contains an ENI, which has the private IP address of your HSM.

2.

Apply the security group that you created earlier to the ENI that AWS created for you, which is the
ENI of your HSM.
a.

Right-click the row containing that IP address, select Change Security Groups, then select the
security group you created for your VPC.

Note
If you completed the steps in Automatically Setting Up Your AWS CloudHSM
Environment Using AWS CloudFormation (p. 3), Security Groups were created
automatically.
b.

3.

(Optional) To aid in troubleshooting network connectivity to your HSM appliance, add incoming
and outgoing rules to your security group for ICMP Echo Request and Echo Reply. These allow
you to ping the HSM appliance, and allows the HSM appliance to respond.

From within an instance running in the VPC, use your login credentials to connect to your HSM client
over SSH. If your instance is a Windows instance, use PuTTY or a similar SSH client for Windows
to connect to the HSM and perform the steps below.

[ec2-user@client-ip bin]$ ssh manager@[hsm ip address]

4.

Change the manager password that was provided to you, by executing the following:
lunash:> user password

You are prompted to enter the new password twice. For more information, go to password in the
User Commands Menu section of the SafeNet Luna SA documentation. Note the new password on
your worksheet.
5.

(Optional) Set the time zone, system date and time. For more information, go to Set System Date
and Time in the SafeNet Luna SA documentation.

Note
AWS configures the time of each HSM to use the UTC time zone. This is also the default
setting for Amazon Linux AMIs. Only change the time zone if your HSM client uses a different
time zone than UTC.
If you change the time zone, you must set it before setting the system date and time;
otherwise, the time zone change adjusts the time you just set.
6.

To monitor the HSM via syslog, you cannot add the IP address of your syslog collector directly in
the HSM configuration. Contact AWS Support and provide the IP addresses of your syslog monitoring
servers. AWS will then perform the required configuration to set up syslog monitoring, and let you
know when the setup is complete. Please remember to add a rule to your security group to allow
syslog traffic on port 514.

12

AWS CloudHSM Getting Started Guide


Configuring Your HSM Appliance

7.

Initialize the HSM partition by executing the following:

lunash:> hsm init -label myLuna

The label (-label MyLuna) should be given a unique name without spaces or special characters.

Note
If you plan to use HA and load balancing among multiple HSM appliances as recommended
by AWS see Configuring High Availability and Load Balancing (p. 21) for additional
instructions.
For more information, go to Use hsm-init to Initialize an HSM in the SafeNet Luna SA documentation.
Initializing an HSM permanently deletes the keys and entire cryptographic domain on the HSM. After
initializing the HSM, any previously existing keys are destroyed.

8.

Initializing an HSM also creates the HSM Administrator account and requires that a password be
created and assigned to that account. Make a note of the password on your worksheet and do not
lose it. It is also recommended that you store at least one copy of the worksheet in secure offsite
storage. AWS does not have the ability to recover your key material from an HSM for which you do
not have the proper HSM administrator credentials.
Create a key pair for the HSM server. This generates a certificate from the public key.

lunash:> sysconf regenCert

9.

For more information, go to Generate a New HSM Server Certificate in the SafeNet Luna SA
documentation.
Make an association between the HSM appliance and an NTLS interface by executing the following:

lunash:> ntls bind eth0

For more information, go to the ntls bind Command in the SafeNet Luna SA documentation.
10. Execute the following commands to log in to the HSM appliance using the appropriate password,
and then create a partition:

lunash:> hsm login


lunash:> partition create -partition myPartition1

The partition (-partition MyPartition1) should be given a unique name without spaces or
special characters.
11. When prompted, type proceed.
12. Supply the appropriate new HSM partition password when prompted. Write down this password, as
it will be used in the following situations:
To authenticate the administrator performing partition management tasks via lunash.
To authenticate client applications that want to use the HSM appliance.

13

AWS CloudHSM Getting Started Guide


Configuring Your HSM Client

For more information, go to Create an HSM partition in the SafeNet Luna SA documentation.

To initialize, connect, and configure your on-premises HSM appliances

(Optional) Connect your on-premise SafeNet Luna SA HSM appliances in your data center to your
AWS instances using VPN or AWS Direct Connect. For more information, see the AWS Direct
Connect detail page.

Configuring Your HSM Client


When you configure the HSM client, you install the client software and accept the license agreement.
Topics
Configuring the HSM Client Using Linux/UNIX (p. 14)
Configuring the HSM Client Using Windows (p. 17)

Configuring the HSM Client Using Linux/UNIX


Note
If you have completed the steps in Automatically Setting Up Your AWS CloudHSM Environment
Using AWS CloudFormation (p. 3), skip to Creating a Network Trust Link Between the Client
and the HSM Appliance Using Linux/UNIX (p. 15).

To configure an HSM client using Linux/UNIX


These instructions are for the AWS Linux x86 64-bit AMI, and may require changes based on your system
architecture.
1.
2.
3.

Connect to the AWS instance that is running in your VPC.


Install the Luna SA client tools. For more information, go to Installing the Luna Software in the SafeNet
Luna SA documentation.
Use the following links to download the HSM client software to your home directory, and the client
patch to your EC2 instance:
Client software
Client patch

4.

From the client instance command prompt, extract and install the HSM client software and answer
yes to all prompts:
[ec2-user@client-ip bin]$ tar -xvf Luna_5.1_Client_Software.tar
[ec2-user@client-ip bin]$ cd 610-011477-003/linux/x86/64/
[ec2-user@client-ip bin]$ sudo sh install.sh

Note
In the second command above, [610-011477-003] changes with each version of the client
software.
5.

Install the client patch and answer yes to all prompts:

14

AWS CloudHSM Getting Started Guide


Configuring the HSM Client Using Linux/UNIX

[ec2-user@client-ip bin]$ cd ~
[ec2-user@client-ip bin]$ tar -xvf Luna_5.1.1_Client_Patch.tar
[ec2-user@client-ip bin]$ cd 630-010275-001/linux/x86/64/
[ec2-user@client-ip bin]$ sudo sh install.sh

Creating a Network Trust Link Between the Client and the


HSM Appliance Using Linux/UNIX
To create a network trust Link between the client and the HSM appliance
These instructions are for the AWS Linux x86 64-bit AMI, and may require changes based on your system
architecture.
1.

Copy the server (HSM) certificate from the HSM appliance to the client instance. For more information,
go to Importing the server certificate onto the client in the SafeNet Luna SA documentation.
[ec2-user@client-ip bin]$ cd /usr/lunasa/bin
[ec2-user@client-ip bin]$ sudo scp manager@[hsm ip address]:server.pem .

Note
The dot (.) at the end of the command provides an instruction to "place the resulting file in
the current directory".
2.

Register the HSM certificate with the client:

[ec2-user@client-ip bin]$ sudo ./vtl addServer -n [hsm ip address] -c serv


er.pem

The following confirmation message appears:


New server [hsm ip address] successfully added to server list.

3.

Create a client certificate using the IP address of your client instance:

Note
If you prefer, you can create a certificate that uses a name instead of an IP address. You
can also create certificates to be shared among multiple instances. For more information,
see Creating an AMI with the HSM Client Configuration (p. 38).
[ec2-user@client-ip bin]$ sudo ./vtl createCert -n [client IP address]
Private Key created and written to:
/usr/lunasa/cert/client/<client ip address>Key.pem

15

AWS CloudHSM Getting Started Guide


Configuring the HSM Client Using Linux/UNIX

Certificate created and written to:


/usr/lunasa/cert/client/<client ip address>.pem

4.

Copy the client certificate to the HSM. For more information, go to Export a Client Certificate to an
HSM Appliance (UNIX) in the SafeNet Luna SA documentation.
[ec2-user@client-ip bin]$ scp /usr/lunasa/cert/client/[client ip address].pem
manager@[hsm ip address]:

Note
The colon (:) after the destination is required. Without it, scp does not recognize the supplied
destination as a remote server.
5.

Using your login credentials to connect to your HSM client over SSH, register the client and assign
the client to a partition on the HSM appliance. For more information, go to Register the Client
Certificate to an HSM Server in the SafeNet Luna SA documentation.
[ec2-user@client-ip bin]$ ssh manager@[hsm appliance ip address]
lunash:> client register -client [clientname] -ip [hsm client ip address]
'client register' successful.

Note
You can create certificates to be shared among multiple instances. For more information,
see Creating an AMI with the HSM Client Configuration (p. 38).
6.

Assign your HSM client to a partition on your HSM appliance.

lunash:> client assignPartition -client [clientname] -partition [partition


name]

For more information, go to Assign a client to a Luna HSM partition in the SafeNet Luna SA
documentation.

7.

For more information on creating a partition, go to step 10 in Configuring Your HSM Appliance (p. 11).
Verify that the partition is assigned to the HSM client:

lunash:> client show -client myWindowsClient

8.

Log in to the HSM client, and verify that it has been properly configured by executing the following:

[ec2-user@client-ip bin]$ vtl verify

16

AWS CloudHSM Getting Started Guide


Configuring the HSM Client Using Windows

The response should be similar to the following:

Slot
====
1

Serial #
========
2279315

Label
=====
Partition1

If you get an error message, some part of the configuration may not have been properly completed.
Retrace the procedure.

Configuring the HSM Client Using Windows


To configure an HSM client using Windows
1.

Connect to the AWS instance that is running in your VPC.

2.

Install the Luna SA client tools. For more information, go to Installing the Luna Software in the SafeNet
Luna SA documentation.
Use the following links to download the HSM client software to your home directory and client patch
to your EC2 instance:

3.

Client software
Client patch

4.

Extract the software to a local directory using an unzip utility.

5.
6.

Browse to the appropriate subdirectory and install the HSM client software.
Accept the license agreement and click Next.

7.

Choose the default installation directory.

17

AWS CloudHSM Getting Started Guide


Configuring the HSM Client Using Windows

8.

Choose the default installation directory, choose a Complete setup, and then click Next.

9.

Click Install to proceed with the installation, then click Finish to exit the installer.

10. Extract the latest client software patch to a local directory using an unzip utility.

11. Browse to the appropriate subdirectory and repeat the steps above to install the Luna SA client
software.

Creating a Network Trust Link Between the Client and the


HSM Appliance Using Windows
To create a Network Trust Link between the client and the HSM appliance using Windows
1.

Copy the server (HSM) certificate from the HSM server to the client instance by typing the following
at a command prompt on the client:

C:> cd Program Files\LunaSA\

2.

Securely transfer the server .pem file from the HSM server, using the supplied pscp utility:

c:\Program Files\LunaSA\> pscp manager@[hsm ip address]:server.pem .


manager@myLuna's password:

18

AWS CloudHSM Getting Started Guide


Configuring the HSM Client Using Windows

server.pem
100%
|*******************************************************|
00:00

928

Note
The dot (.) at the end of the command provides an instruction to "place the resulting file in
the current directory".
3.

Verify that the server certificate has arrived on the client:

C:\Program Files\LunaSA\> dir server.pem

4.

Move the server certificate to the cert/server directory:

C:\Program Files\LunaSA\> move server.pem cert\server

5.

Register the HSM server certificate with the client.

Important
You must execute this command as an administrator. To do this, right-click the cmd.exe
window and select Run as Administrator.

C:\Program Files\LunaSA> vtl addServer -n [LunaSA hostname-or-IPaddress] c [serverCert-file]

This allows the client to create a secure connection with the HSM server.

6.

The vtl executable is located at c:\Program Files\LunaSA, unless you changed the default installation
directory.
Create a client certificate.

Important
You must execute this command as an administrator. To do this, right-click the cmd.exe
window and select Run as Administrator.

C:\Program Files\LunaSA\> vtl createCert

7.

-n [clientIPaddress]

Copy the client certificate to the HSM. For more information, see Export a Client Certificate to an
HSM Appliance (Windows) in the SafeNet Luna SA documentation.

C:\> cd \Program Files\LunaSA\cert\client


C:\Program Files\LunaSA\> ..\..\pscp [client-ip-address].pem manager@[hsm

19

AWS CloudHSM Getting Started Guide


Configuring the HSM Client Using Windows

ip address]:

Note
The colon (:) after the destination is required. Without it, scp does not recognize the supplied
destination as a remote server.

8.

The file arriving at the HSM is automatically placed in the appropriate directory. Do not specify a
directory for the destination.
Register the client and assign the client to a partition on the HSM appliance. Use your login credentials
to connect to your HSM client over SSH.

ssh manager@10.0.0.8 [hsm ip address]


lunash:> client register -client myWindowsClient -ip [client ip address]

'client register' successful.

9.

For more information, go to Register the Client Certificate to an HSM Server in the SafeNet Luna
SA documentation.
Assign a client to a partition on an HSM appliance.

lunash:> client assignpartition -client myWindowsClient -partition myParti


tion1

For more information, go to Assign a client to a Luna HSM partition in the SafeNet Luna SA
documentation.
10. Verify that the client has been properly configured by executing the following command.

Important
You must execute this command as an administrator. To do this, right-click the cmd.exe
window and select Run as Administrator.

vtl verify

11. Connect to the AWS instance running in your VPC.


12. On your client computer, open a command-line console.
13. Go to the LunaSA directory as shown below, and verify that the client has been properly configured
by executing the following command.

Important
You must execute this command as an administrator. To do this, right-click the cmd.exe
window and select Run as Administrator.

20

AWS CloudHSM Getting Started Guide


Operations and Maintenance

C:\Program Files\LunaSA> vtl verify

The response should be similar to the following:

Slot
====
1

Serial #
========
2279315

Label
=====
Partition1

If you get an error message, some part of the configuration may not have been properly completed.
Retrace the procedure.

Operations and Maintenance


AWS monitors your HSM appliances, and may correct minor configuration issues related to availability
of the appliance. Such operations will not interfere with your use of the HSM appliance.
If a management operation must be performed which could disrupt service, then AWS provides 24 hours'
notice before performing the operation.
It is possible that, in unforeseen circumstances, AWS might have to perform maintenance on an emergency
basis without prior notice. We try to avoid this situation. However, if availability is a concern, AWS strongly
recommends that you use two or more HSM appliances in separate Availability Zones in a high availability
configuration. The failure of a single HSM appliance in a non-HA configuration can result in the permanent
loss of keys and data.
AWS does not perform routine maintenance on HSM appliances in multiple Availability Zones within the
same region within the same 24-hour period.
For information about how to set up a high availability configuration, go to Configuring High Availability
and Load Balancing (p. 21).
For information about administration and maintenance of your HSM appliance, go to Administering Your
Luna SA in the SafeNet Luna SA documentation.

Configuring High Availability and Load


Balancing
Topics
HA Failover and Auto-Recovery (p. 26)
Best Practices for High Availability and Load Balancing (p. 26)
AWS recommends that you use two or more HSM appliances, in separate Availability Zones and in a
high availability (HA) configuration, to avoid data loss in the event that an Availability Zone becomes
unavailable.

21

AWS CloudHSM Getting Started Guide


Configuring High Availability and Load Balancing

Important
The failure of a single HSM appliance in a non-HA configuration can result in the permanent
loss of keys and data.
HA allows multiple HSM appliances to be grouped together to form one virtual device or logical unit as
seen from the client, similar to clustering or RAID technologies. In an HA configuration, service is maintained
even if one or several HSM appliances are unavailable. For example, if three HSM appliances are combined
into an HA group, service is maintained even if two HSM appliances are offline.
When configured for HA, each HSM appliance joins an HA group, managed through the HSM client. To
HSM clients, the HA group appears as a single HSM appliance. However, from an operational perspective,
the members in the HA group share the transaction load, synchronize data with each other, and gracefully
redistribute the processing capacity in the event of failure in a member machine, to maintain uninterrupted
service to clients. HA provides load balancing across all HSM members in the HA group to increase
performance and response time, while providing the assurance of high-availability service. All HSM
members in the HA group are active (rather than one active and the rest passive). Calls are passed from
each client application through the HSM client-side software (library) to one of the HSM members in the
HA group on a least-busy basis. However, operation requests directed at the virtual slot are served by
the primary appliance (the first member in the client's list) until that member reaches its capacity; at that
point, operations are directed to other members in the HA group.
For more information, go to HA with Luna SA in the SafeNet Luna SA documentation.

To configure HA redundancy and load balancing among your HSM appliances


1.
2.

Set up the network on your HSM appliances that will be used in the HA group. For more information,
go to Preparing to configure appliance network settings in the SafeNet Luna SA documentation.
Create the policy settings needed for HA by verifying that Enable cloning and Enable network
replication are set to Allowed in hsm showPolicies, as shown in the excerpt below. If they are
not set to Allowed, change them with hsm changePolicy -policy [policyCode] -value
[policyValue].

[myluna] lunash:> hsm showPolicies


HSM Label: myhsm
Serial #: 700022
Firmware: 6.2.1
The following capabilities describe this HSM, and cannot be altered
except via firmware or capability updates.
Description
===========

Value
=====

Enable cloning
.
.
.
Enable network replication
.
.
.

Allowed

Allowed

The following policies describe the current configuration of


this HSM and may by changed by the HSM Administrator.

22

AWS CloudHSM Getting Started Guide


Configuring High Availability and Load Balancing

Changing policies marked "destructive" will zeroize (erase


completely) the entire HSM.
Description
Value
Code
Destructive
===========
=====
====
===========
.
Allow cloning
On
7
Yes
.
.
Allow network replication
On
16
No
.
.
.
Command Result : 0 (Success)
[myluna] lunash:>

Note
Cloning to a hardware token is the backup method for which your HSM appliances are
configured. All HSM appliances in an HA group must use the same backup method.
3.

Initialize the HSM appliances into a common cloning domain. For password-authenticated appliances,
they must share the same domain string.

Warning
Initializing an HSM permanently deletes the keys and entire cryptographic domain on the
HSM. After initializing the HSM, any previously existing keys are destroyed. For more
information, go to Use hsm-init to Initialize an HSM in the SafeNet Luna SA documentation.

Note
If you have already configured your HSM appliance in Configuring Your HSM Client (p. 14),
the following steps help you reconfigure your HSM appliance for HA.
Three of the values are required, but the only one that you should type at the command
line is a label for the HSM (-label). Typing the password and the cloning domain at the
command line makes them visible to anyone who can see the computer screen, or to
anyone who later scrolls back in your console or ssh session buffer. If you omit the
password and the cloning domain, lunash prompts you for them, and hides your input
with ******** characters. This is preferable from a security standpoint. Additionally, you
are prompted to re-enter each string, thus helping to ensure that the string you type is
the one you meant to type.

lunash:> hsm -init -label myLuna


> Please enter a password for the security officer
> ********
Please re-enter password to confirm:
> ********
Please enter the cloning domain to use for initializing this
HSM (press <enter> to use the default domain):
> ********
Please re-enter domain to confirm:
> ********
CAUTION: Are you sure you wish to re-initialize this HSM?
All partitions and data will be erased.
Type 'proceed' to initialize the HSM, or 'quit' to quit now.

23

AWS CloudHSM Getting Started Guide


Configuring High Availability and Load Balancing

> proceed
hsm - init successful.

4.

On each HSM appliance, create a partition.

lunash:> partition create -partition myPartition1

5.

The partition (-partition MyPartition1) should be given a unique name without spaces or
special characters. For more information, go to Create an HSM partition in the SafeNet Luna SA
documentation.
When prompted, type proceed.

6.

Supply the appropriate HSM partition password when prompted.

7.

Change the partitions' passwords so that they match. The partitions do not need to have the same
labels, but they must have the same password.

lunash:> partition changePw -partition <partitionname> [-cu] [-newpw <parti


tionpassword>] [-oldpw <partitionpassword>]

8.

Record partition serial numbers and passwords, and store this information in a secure place.

lunash:> partition show

9. Proceed with a normal client setup as described in Configuring Your HSM Client (p. 14).
10. Register your client computer with each partition that will be part of the HA group. On each HSM
appliance, assign the partition to its respective HSM client; repeat for each HSM appliance in the HA
group.
lunash:> client assignPartition -client [clientname] -partition [Partition1]
lunash:> client assignPartition -client [clientname] -partition [Partition2]

11. Create a new HA group on the client, which consists of the following:
A unique label for the group.
The serial number of the primary partition (Partition1).
The password for the primary partition.
When you create this new HA group, the vtl utility also generates and assigns a serial number to
it.

Important
You must execute the next command as an administrator. To do this, right-click the cmd.exe
window and select Run as Administrator.

24

AWS CloudHSM Getting Started Guide


Configuring High Availability and Load Balancing

bash-2.05# ./vtl haAdmin -newGroup -serialNum 65003001 -label myHAgroup password userpin
New group with label "myHAgroup" created at group number 742276409.
Group configuration is:
HA Group Number: 742276409
HA Group Label: myHAgroup
Group Members: 65003001
Needs sync: no

12. Your chrystoki.conf (Linux/UNIX) or crystoki.ini (Windows) file should now have a new section:

VirtualToken = {
VirtualToken00Members = 65003001;
VirtualToken00SN = 742276409;
VirtualToken00Label = myHAgroup;
}

Important
Do not insert tab characters into the chrystoki.conf or crystoki.ini file.
13. Add another member to the HA group (Partition2 on the second appliance).

Important
You must execute the next command as an administrator. To do this, right-click the cmd.exe
window and select Run as Administrator.

bash-2.05# ./vtl haAdmin -addMember -group 742276409


-serialNum 65005001 -password userpin
Member 65005001 successfully added to group 742276409.
New group configuration is:
HA Group Number: 742276409
HA Group Label: myHAgroup
Group Members: 65003001, 65005001
Needs sync: no
Please use the command 'vtl haAdmin -synchronize' when you are ready to
replicate data between all members of the HA group.
(If you have additional members to add, you may wish to wait until you have
added them before synchronizing to save time by avoiding multiple synchron
izations.)

For more information, as well as additional optional checking and verification steps, go to Create
Client HA Group in the SafeNet Luna SA documentation.
14. Verify your setup, then point your client application at the HSM, referring to that HSM by the HA
group label that you assigned.

/usr/lunasa/bin/vtl haAdmin -show

25

AWS CloudHSM Getting Started Guide


HA Failover and Auto-Recovery

15. When an HA group is shared by multiple clients, the best practice is for these clients to select different
primary members. This provides better fault tolerance and load balancing of cryptographic operations.

HA Failover and Auto-Recovery


Configuring HA Failover
AWS and SafeNet recommend keeping the default 20-second failover timeout. This is configurable by
executing the following command:

/usr/lunasa/bin/configurator setValue -s "LunaSA Client" -e ReceiveTimeout -v


<milliseconds>

Enabling Auto-Recovery
Automatic recovery (autoRecovery) is disabled by default.

To enable auto-recovery

To enable autoRecovery, execute the following command:

/usr/lunasa/bin/vtl haAdmin -autoRecovery -retry <count>

Configuring the Retry Interval


To configure the retry interval

To configure the retry interval, execute the following command:

/usr/lunasa/bin/vtl haAdmin -autoRecovery -interval <seconds>

Best Practices for High Availability and Load


Balancing
General Best Practices
AWS recommends the following best practices for high availability (HA) and load balancing your HSM
appliances.

26

AWS CloudHSM Getting Started Guide


Best Practices for High Availability and Load Balancing

When an HA group is shared by multiple AWS CloudHSM clients, the best practice is for these clients
to select different primary HA members, for better fault tolerance and more equal distribution of the
workload of cryptographic operations.
For more information, see the following topics in the SafeNet Luna SA documentation:
Overview of Luna High Availability and Load Balancing
HA with Luna SA

Best Practices for Loss and Recovery


HA Recovery
HA recovery is hands-off resumption by failed HA group members. Prior to the introduction of this function,
the HA feature provided redundancy and performance, but required that a failed/lost group member be
manually reinstated. If the HA recovery feature is not switched on, HA still requires manual intervention
to reinstate members. A member of an HA group may fail for the following reasons:
The HSM appliance loses power, but regains power in less than the two hours that the HSM appliance
preserves its activation state.
The network connection is lost.
HA recovery works if the following are true:

HA autoRecovery is enabled.
The HA group has at least two nodes.
The HA node is reachable (connected) at startup.
The HA node recover retry limit is not reached. If it is reached or exceeded, the only option to restore
the downed connections is a manual recovery.

If all HA nodes fail (there are no links from the HSM client), recovery is not possible.
The HA recovery logic in the library makes its first attempt at recovering a failed member when your
application makes a call to its HSM appliance (the HA group). In other words, an idle HSM client does
not attempt a recovery.
However, a busy HSM client would notice a slight pause every minute, as the library attempts to recover
a dropped HA group members until the members are reinstated, or until the retry period has been
reached/exceeded and it stops trying. Therefore, set the retry period according to your normal operational
situation; for example, the types and durations of network interruptions you experience.
HA autoRecovery is not on by default. It must be explicitly enabled by executing the following command
from your HSM client:

lunash:> vtl haAdmin -autoRecovery

For more information on HA and autoRecovery, go to the following topics in the SafeNet Luna SA
documentation:
Configuring HA
Client - Create HA Group

27

AWS CloudHSM Getting Started Guide


Best Practices for High Availability and Load Balancing

Recovering From the Loss of a Subset of HA Members


If there is a loss of a subset of HA members, AWS recommends the following procedure to recover group
members.

To recover group members manually


1.

When you are notified by AWS that the connection has been recovered, execute the following
command to reintroduce disconnected members to the HA group:

/usr/lunasa/bin/vtl haAdmin -recover -group <group>

2.

AWS also recommends retrying the connection for a short period of time, so that any disconnections
caused by transient network outages can be automatically recovered. For example, retry the
connection 5 times, at an interval of one try every minute, as shown below.

/usr/lunasa/bin/vtl haAdmin -autoRecovery -interval 60


/usr/lunasa/bin/vtl haAdmin -autoRecovery -retry 5

3.

Reintroduce disconnected members to the group when notified by AWS of the connection recovery.

/usr/lunasa/bin/vtl haAdmin -recover -group <group>

If you don't want to recover the group members manually, but still want to minimize the overhead caused
by automatic recovery, use the following steps:

To recover group members and minimize recovery overhead

Retry the connection once every 3 minutes, until the connection is successful.

/usr/lunasa/bin/vtl haAdmin -autorecovery -interval 180


/usr/lunasa/bin/vtl haAdmin -autoRecovery -retry -1

To recover group members with a special cryptographic application

For special cryptographic applications, discuss with SafeNet and/or AWS on a case-by-case basis.

Recovering From the Loss of All HA Members


If there is a loss of all HA members (there is a complete loss of communication with all the members of
your HA group), you can use LunaSlotManager.reinitialize(). If you use

28

AWS CloudHSM Getting Started Guide


Resynchronizing HSM Appliances

LunaSlotManager.reinitialize(), you do not have to restart your applications. Alternately, you


can restart your applications and use manual recovery.

For more information about LunaSlotManager.reinitialize(), see LunaProvider: Recovering from


the Loss of all HA Members Using LunaSlotManager.reinitialize() in the SafeNet Luna SA Technical
Notes.
Important
LunaHAStatus.isOK() returns true only when all HA members are present. This method returns
false when at least one HA member is missing, and throws an exception when all HA members are
missing.
The HA-only option has to be enabled to keep the HA slot number unchanged.

Resynchronizing HSM Appliances


Topics
Resynchronizing HSM Appliances Using Linux/UNIX (p. 29)
Resynchronizing HSM Appliances Using Windows (p. 29)
This section explains how to resynchronize two HSM appliances after the HSM client loses connectivity
to one HSM appliance. If network connectivity is lost, the HSM client permanently stops trying to connect
to the HSM appliance after the retry period is exceeded. The retry period is number-of-retries *
retry-interval, where the default/recommended configuration is to retry 10 times with an interval of
60 seconds, for a total of 10 minutes. After the retry period is exceeded, the HSM client removes the
disconnected HSM appliance from the HA group, and it must be manually added back. Follow the
instructions below to recover a downed HSM appliance.

Important
Do not perform a manual resynchronization between the members of the HA group. For more
information, see Best Practices for Loss and Recovery (p. 27).

Resynchronizing HSM Appliances Using


Linux/UNIX
To resynchronize HSM appliances using Linux/UNIX

Execute the following command:


[ec2-user@client-ip bin]$ vtl haAdmin recover group [groupName] -serialNum
[PartitionSerial]

For more information, go to HA Operational Notes in the SafeNet Luna SA documentation.

Resynchronizing HSM Appliances Using Windows


To resynchronize HSM appliances using Windows

Execute the following command:

29

AWS CloudHSM Getting Started Guide


Backing Up and Restoring HSM Data to a Luna SA
Backup HSM
C:\Program Files\LunaSA> vtl haAdmin recover group [groupName] -serialNum
[PartitionSerial]

Backing Up and Restoring HSM Data to a Luna


SA Backup HSM
In addition to the AWS recommendation that you use two or more HSM appliances in a high availability
(HA) configuration to prevent the loss of keys and data, you can also perform a remote backup/restore
of a Luna SA 5.1 partition if you have purchased a Luna Backup HSM. For more information on the Luna
Backup HSM, download the Luna Backup HSM Product Brief.
The Luna Backup HSM ensures that your sensitive cryptographic material remains strongly protected in
hardware even when it is not being used. You can easily back up and duplicate keys securely to the Luna
Backup HSM for safekeeping in case of emergency, failure, or disaster.
The remote backup capabilities allow administrators to move copies of their sensitive cryptographic
material securely to other SafeNet HSMs. With a single Luna Backup HSM, an administrator can back
up and restore keys to and from up to 20 Luna HSM appliances.

Backing Up HSM Data Using Windows


To back up HSM data using Windows
1.
2.

3.

Connect the Luna Backup HSM to your HSM appliance using USB. For more information about the
Luna Backup HSM, see the see Luna Backup HSM Product Brief.
Install the Luna Remote Backup Driver (610-011646-001) from the following location:
http://c3.safenet-inc.com/downloads/F/E/FEAB55E0-5B3F-4DFD-8DEF-B068C5531AED/610-011646-001.tar
From your Windows computer's Control Panel, open Device Manager, select Luna G5 Device, then
right-click and select Update Driver Software.

4.

Complete the steps in Configuring AWS CloudHSM (p. 11), Configuring Your HSM Appliance (p. 11),
and Configuring Your HSM Client (p. 14).

5.

Use your login credentials to connect to your HSM client over SSH:

ssh manager@10.0.0.8 [hsm ip address]

6.

Execute the following command on your HSM client to display the details of the HSM appliance:

lunash:> hsm show

30

AWS CloudHSM Getting Started Guide


Backing Up HSM Data Using Windows

7.

Execute the following command on your HSM client to display the contents of the partition:

lunash:> par showc -par pm

8.

Establish an NTLS connection by executing the following command from the Windows command
prompt:

C:\Program Files\LunaSA> vtl ver

9.

List the available slots by executing the following command:

31

AWS CloudHSM Getting Started Guide


Backing Up HSM Data Using Windows

C:\Program Files\LunaSA> vtl listslots

10. Restore the Luna Backup HSM appliance to its factory settings by executing the following command:

C:\Program Files\LunaSA> vtl backup token factoryreset -target 2

11. Type yes to confirm.

12. Initialize the Luna Backup HSM appliance by executing the following command:

C:\Program Files\LunaSA> vtl backup token init -target 2 -label BackupHSM

13. Type yes when prompted to initialize the HSM, and no when prompted to use PED authentication.

Important
It is important that your HSM uses password authentication.

14. Execute the remote backup command:

C:\Program Files\LunaSA> vtl backup -source 1 -target 2 -partition pm_backup

15. Type yes when prompted to create the new backup.

32

AWS CloudHSM Getting Started Guide


Restoring HSM Data from a Luna Backup HSM

16. If you want to check the details of the backup, execute the following command:

C:\Program Files\LunaSA> vtl backup token show -target 2

Restoring HSM Data from a Luna Backup HSM


To restore HSM data
1.

Clear the contents of the partition by executing the following from your HSM client:

lunash:> partition clear -partition pm

2.

When prompted, enter your password for this partition.

3.

When prompted, type proceed.

4.

Verify that the partition is cleared by executing the following command:

lunash:> partition showcontents -partition pm

33

AWS CloudHSM Getting Started Guide


Restoring HSM Data from a Luna Backup HSM

5.

Confirm that no objects exist on the HSM client partition by executing the following command from
the Windows command prompt:

C:\Program Files\LunaSA> cmu li

6.

Initiate the restore by executing the following command:

C:\Program Files\LunaSA> vtl backup restore -source 2 -partition pm_backup


-target 1

7.

Enter the passwords when prompted.

8.

Confirm that the restore was successful by executing the following from the HSM client:

lunash:> partition showcontents -partition pm

9.

Enter your password when prompted.

10. Confirm that the restore operation was successful by executing the following command:

34

AWS CloudHSM Getting Started Guide


How to Stop Using an HSM

C:\Program Files\LunaSA> cmu li

How to Stop Using an HSM


AWS does not ordinarily de-provision an HSM appliance that contains key material. This protects you,
as well as AWS, from risks associated with accidentally destroying key material that is still in use.

Important
If you need to stop using an HSM appliance (such as when your subscription ends), back up the
contents of the HSM to another HSM that you control, or confirm that the keys stored within the
HSM are no longer needed.
Complete the following steps to stop using an HSM appliance.

To stop using an HSM appliance


1.

Delete all HSM partitions from the HSM appliance by executing the following, replacing
[HSM-partition-name] with the name of the partition that you want to delete (do not include the brackets
"[]"). If you are not sure of the partition name, use the partition list command.

partition delete -partition [HSM-partition-name]

Note
To delete an HSM partition, you must be logged into the HSM appliance command shell
(lunash) as admin, and you must be logged in to the onboard HSM as HSM Admin.
When a partition is deleted, the partition is cleared from the HSM and all contents are deleted. This
also implies that the partition is revoked from any clients that were registered to it. For more
information, go to Removing Partitions and partition delete command in the SafeNet Luna SA
documentation.
2.

Declassify the HSM appliance by first executing the following command to rotate all logs.

lunash:> syslog rotate

3.

Delete all files in the SCP directory.

lunash:> sysconf cleanup scp

35

AWS CloudHSM Getting Started Guide


Best Practices

4.

Delete all logs.

lunash:> syslog cleanup

5.

Contact AWS Support with a request to terminate service.

AWS will review the HSM. If the HSM appliance is in an uninitialized state, then AWS will de-provision it
and your subscription to the HSM will be terminated. If the HSM appliance still contains any HSM partitions,
AWS will contact you with a request to remove the partitions from the appliance.
AWS reserves the right to terminate service and reinitialize an HSM in the case of non-payment.

Best Practices
Use a high availability configuration. AWS recommends that you use two or more HSM appliances, in
separate Availability Zones, in a high availability configuration, to avoid data loss in the case that an
Availability Zone becomes unavailable.

For more information about best practices in and how to set up a high availability configuration, go to
Configuring High Availability and Load Balancing (p. 21).
Initializing an HSM irrevocably destroys the key material inside the HSM. Never initialize the HSM
unless you are certain that the keys have been backed up somewhere else or that the keys are no
longer required.
Keep your HSM administrator password secure and do not lose it. AWS does not have the ability to
recover your key material from an HSM for which you do not have the proper HSM administrator
credentials.
Do not apply software patches or updates to the appliance. Contact AWS Support if you need the
software updated.
Do not change the network configuration of the appliance.
Do not remove or change the syslog forwarding configuration that is provided on the appliance. You
may add additional destinations for syslog messages, as long as you do not change or remove the
ones that are already there.

Do not change or remove any SNMP configuration that is provided on the appliance. You may add
additional SNMP configuration as long as you do not disturb the configuration that is already present.
Do not change the NTP configuration that is provided on the appliance.

Troubleshooting
For frequently asked questions about AWS CloudHSM, see AWS CloudHSM FAQs.
Q: My HSM isn't working. What do I do?
Contact AWS Support. Your incident will be routed to the team that supports AWS CloudHSM.

Appendices
Topics

36

AWS CloudHSM Getting Started Guide


Appendices

Connecting Multiple Client Instances to AWS CloudHSM with One Certificate (p. 38)
Integrating Third-Party Applications with AWS CloudHSM (p. 40)
Building a Test Application (p. 41)
Building Your Own Applications (p. 43)

37

AWS CloudHSM Getting Started Guide


Connecting Multiple Client Instances to AWS CloudHSM
with One Certificate

Connecting Multiple Client Instances to AWS


CloudHSM with One Certificate
When you use multiple servers with AWS CloudHSM, normally each server generates a unique certificate
using that instance's IP address and registers this certificate with AWS CloudHSM; additional steps must
then be taken to allow this instance access to the HSM appliance. However, you can avoid the need to
create unique certificates per server by creating either an AMI with the HSM client configuration or an
Amazon S3 bucket. Either of these solutions can be used with Auto Scaling groups to allow client instances
to scale up and down. This allows you to have a scalable services layer that integrates with AWS
CloudHSM.
Topics
Creating an AMI with the HSM Client Configuration (p. 38)
Create an Amazon S3 Bucket and Roles (p. 39)

Creating an AMI with the HSM Client Configuration


Create an AMI with the client configuration, and then create multiple instances from the AMI. You can
use a name instead of an IP address when creating the certificate on the HSM client, and you can create
multiple instances from the same AMI without re-creating or changing the certificate.

Note
If you use a name instead of an IP address when creating the certificate on the HSM client, make
sure that the registered client name on the HSM appliance matches exactly.

To create an AMI with the client configuration and prepare the HSM client
1.

Execute the following commands on the HSM client, where ClientCertName is the name you have
chosen for the certificate on the HSM client.

C:\Program Files\LunaSA>vtl createCert -n ClientCertName


Private Key created and written to: C:\Program Files\LunaSA\cert\client\Cli
entCertNameKey.pem
Certificate created and written to: C:\Program Files\LunaSA\cert\client\Cli
entCertName.pem
C:\Program Files\LunaSA>pscp "%programfiles%\LunaSA\cert\client\ClientCert
Name.pem" manager@10.0.0.23:
manager@10.0.0.23's password:
ClientCertName.pem

2.

| 1 kB |

1.1 kB/s | ETA: 00:00:00 | 100%

Execute the following commands on the HSM appliance, where ClientName is the name of your
HSM client and ClientCertName is your certificate name.
[hsm6105.iad6] lunash:>c reg -c ClientName -h ClientCertName
'client register' successful.
Command Result : 0 (Success)
[hsm6105.iad6] lunash:>c l

38

AWS CloudHSM Getting Started Guide


Connecting Multiple Client Instances to AWS CloudHSM
with One Certificate

registered client 1: ClientName

3.

After completing the steps above, create an AMI that includes the client configuration, then create
one or more Amazon EC2 instances from the AMI. Each Amazon EC2 instance can connect to the
HSM appliance using the same certificate, and instances started from Auto Scaling groups can
establish a secure connection to AWS CloudHSM.
For more information about creating AMIs, go to Creating Your Own AMIs in the Amazon Elastic
Compute Cloud User Guide.
For more information about creating instances from AMIs, go to Launch Your Instance in the Amazon
Elastic Compute Cloud User Guide.

Create an Amazon S3 Bucket and Roles


If you prefer not to create an AMI, you can create an Amazon S3 bucket with the certificates and keys in
them, then create a role with an attached policy that allows read-only access to that bucket, and use the
role when launching the instance for your application (including with Auto Scaling). Then you can write
scripts in the instance to access the files from Amazon S3.

To create an Amazon S3 bucket and roles


1.
2.
3.
4.
5.
6.
7.

Create an Amazon S3 bucket. For more information, see Create a Bucket in the Amazon Simple
Storage Service Getting Started Guide.
Change permissions on the Amazon S3 bucket to reduce permissions to the minimum set of people
necessary.
Upload the certificates into the Amazon S3 bucket.
Create a role for your application. For more information, see Creating a Role in the Using IAM.
As part of creating the role, modify the role's policy to allow read-only access to the Amazon S3
bucket; for example, "Resource": ["arn:aws:S3:::bucket/*"].
Use the role when launching your application.
Write scripts on the application instance to download the certificate files from the Amazon S3 bucket.
This allows you to update the certificates from time to time, and also does not require you to figure
out how to secure your AMI to prevent credential leakage.

To learn more about using IAM roles with Amazon S3 buckets, see Using IAM roles to distribute non-AWS
credentials to your EC2 instances in the AWS Security blog or Using IAM Roles for EC2 Instances with
the SDK for Java in the AWS SDK for Java Developer Guide.

39

AWS CloudHSM Getting Started Guide


Integrating Third-Party Applications with AWS CloudHSM

Integrating Third-Party Applications with AWS


CloudHSM
This chapter describes how to use third-party applications with AWS CloudHSM.
Topics
Transparent Data Encryption with AWS CloudHSM (p. 40)
Volume Encryption for Amazon Elastic Block Store (p. 41)
Encryption with Amazon Simple Storage Service (S3) and SafeNet KeySecure (p. 41)
Setting Up SSL Termination on an Apache Web Server with Private Keys Stored in AWS
CloudHSM (p. 41)
If the application for which you are looking is not listed, contact AWS Support or see HSM Interoperability.

Transparent Data Encryption with AWS CloudHSM


Transparent Data Encryption (TDE) reduces the risk of confidential data theft by encrypting sensitive
data, such as credit card numbers, stored in application table columns or tablespaces (the containers for
all objects stored in a database).
The following topic describes how to configure an Oracle or Microsoft SQL Server database using TDE
while storing the master encryption key in AWS CloudHSM.

Oracle Database TDE with AWS CloudHSM


These instructions guide security administrators through how to integrate an Oracle database and your
LunaSA/PCI/HSM appliance, and also cover the necessary information to install, configure and integrate
an Oracle database with AWS CloudHSM.

To set up TDE for Oracle Database 11g


The following instructions are explained in detail in the Oracle Database 11g and LunaSA/PCI Integration
Guide.
1.
2.
3.

Set up your Luna SA/PCI/HSM appliances. For more information, see the instructions in Before You
Begin (p. 2).
Install Oracle Database 11g on the target machine. For more information and detailed instructions,
go to the Oracle Database Luna SA/PCI Integration Guide.
Integrate Oracle Database 11g R1 (11.1.0.6 or 11.1.0.7) or 11g R2 (11.2.0.1, 11.2.0.2, or 11.2.0.3)
with your Luna SA/PCI/your HSM appliances. For more information, go to the Oracle Database Luna
SA/PCI Integration Guide.

Microsoft SQL Server with AWS CloudHSM


The following topic describes how to use Microsoft SQL Server TDE and the Extensible Key Management
(EKM) Library with AWS CloudHSM.
For more information about the EKM library, go to http://technet.microsoft.com/en-us/library/bb895340.aspx

To set up TDE for Microsoft SQL Server and the EKM Library
The following instructions are explained in detail in the Microsoft SQL Server and LunaSA/PCI Integration
Guide.

40

AWS CloudHSM Getting Started Guide


Building a Test Application

1.
2.
3.

Set up your HSM appliance(s). Refer to the instructions in Before You Begin (p. 2).
Integrate Luna SA/PCI/HSM appliances with Microsoft SQL Server. For more information, go to the
Microsoft SQL Server Integration Guide.
Download and install the EKM libraries.

Volume Encryption for Amazon Elastic Block Store


For information about how to use volume encryption for Amazon Elastic Block Store (Amazon EBS) in
AWS (SafeNet ProtectV, SafeNet KeySecure and CloudHSM), go to the ProtectV Installation Guide
(AWS).

Encryption with Amazon Simple Storage Service (S3) and


SafeNet KeySecure
For information about how to use Amazon Simple Storage Service (Amazon S3) encryption with SafeNet
ProtectApp and SafeNet KeySecure, go to the SafeNet KMIP and Amazon S3 Integration Guide.

Setting Up SSL Termination on an Apache Web Server with


Private Keys Stored in AWS CloudHSM
The following topic describes how to set up SSL termination using Apache, with the private key stored in
the HSM. The SafeNet Luna HSM appliances integrate with the Apache HTTP server to provide significant
performance improvements by offloading cryptographic operations from the Apache HTTP Server to the
SafeNet Luna HSM appliances. In addition, the Luna HSM appliances provide extra security by protecting
and managing the server's high-value SSL private key within a FIPS 140-2 certified hardware security
module. For more information about the libraries that are required for the Apache integration, go to the
Apache HTTP Server Integration Guide. SafeNet's OpenSSL Toolkit may also be required for integrating
with Apache web server.

Building a Test Application


Building a Test Application Using C
The following procedure shows how to build a sample program that uses the SafeNet PKCS#11 library
to encrypt and decrypt a string, using the HSM to perform the cryptographic operations. The sample
source code is written in the C programming language.

To build a test application


1.
2.

Install the SafeNet client and certificates on your instance in your VPC, as described in the previous
sections.
Download the sample source code to your instance.

3.

On UNIX/Linux, do the following:

mkdir Sample
mv P11Sample.zip Sample
cd Sample/
unzip P11Sample.zip
more README.txt

41

AWS CloudHSM Getting Started Guide


Building a Test Application

4.

Follow the instructions in the README.txt file for installing make, gcc, setting the SfntLibPath
environment variable, building the sample application, and running it.

Building a Test Application Using Java


The following instructions show how to use Luna JSP, which consists of a single JCA/JCE service provider,
to build a sample Java-based application that uses SafeNet Luna products for secure cryptographic
operations.
The Luna JSP comes with several sample applications that show you how to use the Luna provider.
Install these sample applications with the SafeNet client software.
The sample applications include detailed comments. For more information, go to Luna JSP in the SafeNet
Luna SA documentation.

To compile the Java application

Execute the following command:

javac *.java

To run the Java application


1.

On UNIX/Linux, do the following:

cd Luna SA <install> /jsp/samples


java com.safenetinc.luna.sample.KeyStoreLunaDemo (or any other sample class
in that package)

Note
If you chose the default installation directory when installing the client software (p. 14), the
samples are located in
/usr/lunasa/jsp/samples/com/safenetinc/luna/sample/
2.

Create a workspace folder:

mkdir workspace

3.

Copy the sample code from the /usr/lunasa folder:

cp -R /usr/lunasa/jsp luna

4.

Change the directory to the samples folder:

42

AWS CloudHSM Getting Started Guide


Building Your Own Applications

cd luna/samples

5.

Update the HSM partition password in the Java sample code.

6.

Compile the sample code:

javac -classpath .:../lib/LunaProvider.jar ./com/safenetinc/luna/sample/*.java

7.

Add LunaProvider to the java.security file:

sudo vi /usr/java/jdk1.7.0_07/jre/lib/security/java.security
security.provider.10=com.safenetinc.luna.provider.LunaProvider

8.

Execute the following:

/usr/java/jdk1.7.0_07/bin/java -Djava.library.path=../lib/ -classpath


.:../lib/LunaProvider.jar:../lib/libLunaAPI.so com.safenetinc.luna.sample.Key
StoreLunaDemo

For more information, go to the following SafeNet Luna SA documentation topics:


Java Applications via Luna JSP
Linux Installation
Java

Building Your Own Applications


For more information about how to configure your applications to use one or more of the APIs provided
by the SafeNet client, go to Configured and Registered Client Using an HSM Partition and Integrating
Luna SA with Your Applications in the SafeNet Luna SA documentation.

43

AWS CloudHSM Getting Started Guide

Where to Get Additional Help


We recommend that you take advantage of the AWS Discussion Forums. These are community-based
forums for users to discuss technical questions related to AWS services. For the AWS CloudHSM forum,
go to https://forums.aws.amazon.com/forum.jspa?forumID=156.
You can also get help if you subscribe to AWS Premium Support, a one-on-one, fast-response support
channel (for more information, go to http://aws.amazon.com/premiumsupport).

44

AWS CloudHSM Getting Started Guide

Document History
The following table describes the important changes to the documentation in this release of AWS
CloudHSM.
Latest documentation update: November 05, 2013

Change

Description

Date Changed

Initial Release

First release of the AWS CloudHSM Getting Started


Guide.

2013-03-26

Update

Added support for US West (Oregon) and Asia Pacific


2013-11-05
(Sydney) regions; new sections on high availability and
load balancing; new sections on resources to deploy and
integrate with third-party applications; and instructions
on how to use a new AWS CloudFormation template to
set up your AWS CloudHSM environment.

45

Vous aimerez peut-être aussi