AWS CloudHSM for Dummies

Amazon is surely not great in documenting stuffs.

Probably, it happens when you deploy codes faster than you can type a sentence.

I was helping a bunch of developers with CloudHSM related issues. I am the go-to guy when it is about cryptography. I worked with HSM before. So just thought “Yaa, I can help these poor guys with cloudHSM”, and started reading the AWS documentations. Finally I found, I was in a complete soup. There is almost no material other than the official AWS user guide. Which is good and but not enough. It skips many basic concepts and made it hard to understand. Moreover, when you are looking for technical workarounds, it is just an ocean of random stuffs. Unfortunately there is practically nothing else about it in Internet, nothing that can appear in the first page of google search. The user guide documentation covers a lot about the features, deployment, compliance and pricing of CloudHSM. Unfortunately, there is not much words on how you would work with that. So, it took 3 sleepless nights for me to understand the basics and to connect the dots and to figure out what is happening behind the scene.

So this blog is not a replacement of AWS user guide (not unless amazon pays me for that). But this is for setting a background on how to use that user documents located at https://docs.aws.amazon.com/cloudhsm/latest/userguide/introduction.html

This document is not a handbook, or cheatsheet or reference guide. It contains lot of information buried within the texts. This is more for building concepts, and probably not for finding readymade solution to your issues.

Introduction to Basic

First thing first, Explanation to few jargons. let us talk in common terms…

HSM

you know the full form of this abbreviation. It is a hardware device that stores your cryptographic keys (symmetric and asymmetric) and performs all the cryptographic operation within itself. In other words, it contains all the keys, and never let you get to see the keys (unless you ruthlessly want them by bypassing several layers of restriction). If you get to open a lock, you will not get the key. Instead, send the lock to the HSM and it will open it for you. If you want to encrypt, decrypt, sign etc., you send the files in HSM, it will do all the necessary operations and send you back your required data. How will HSM know which key you are looking for to perform a particular operation? Well, every key has a unique Object ID, along with some attributes, labels, properties, fags etc. You can access your keys by ID or any other attributes.

HSMs normally perform two types of functions:

• Storage the cryptographic objects (asymmetric keys, symmetric keys and X509 certificates etc)
• Performing cryptographic operations (Asymmetric key pair generation, symmetric key generation, hashing, encryption/decryption and signing etc)

HSM used to be a dedicated hardware device connected to a computers. There are many applications around us (including all the point of sale machines, ATMs, bank servers) that use hardware security module. Later we got soft HSM (sounds funny, though) and cloud-based HSMs. HSM is still a dedicated hardware device looks like a server blade or sillicon-chip. Sometimes we can see them, sometime they are hidden in cloud. AWS, Azure, GoogleCloud are providing HSM as a IAAS. Those are also single-tenant dedicated hardware modules attached with the specific machine (we call it a cluster). That is why HSM is very costly even in cloud.

There are few terminologies related to HSM.

Slots

Slots are the logical partitions in the cryptographic device. In case of HSMs, there could be hundreds or more slots are available. That is how a HSM can be used by multiple teams like dev, non-prod, prod etc. In dedicated physical HSM, there is a slot for inserting a smart card. Smart card contains cryptographic information and credentials to access HSM. That is why we still call it a slot.

Token

Token is a device where application stores the cryptographic objects and also perform cryptographic operations. In the case of smart cards, you can think of slot as a smart card reader while the smart card inserted inside the reader is the token. In case of HSMs, you cannot visualize the slot and token relationship just like you did in case of reader and the smart card. when a slot is initialized in HSM then the token is present in the slot.

Session

Once a token is present in the slot then the application opens a session (logical connection) with the token. Once the session is in place, the application can perform different cryptographic operations with the token e.g. application can use the session object to generate asymmetric key pair, produce signature with the private key present inside the token and so on. When the application is done with the cryptographic operations, it can close the session with the token.

Object

Anything that is stored in a HSM. It includes all the keys , certificates, piece of senstive information etc.

Mechanism

Mechanism In HSM terminology, collection of cryptographic algorithms are called mechanisms e.g. RSA, AES with SHA256, RSA with PSS padding etc. are referred as mechanisms.

User

Cryptographic devices contains private and public objects. In order to access the private objects, users must be authenticated from the device. One of the operation that requires authentication is the access of private key in order to produce a signature.

PKCS#11

There are so many HSM manufacturers in the market. Every different devices has a different set of commands to operate. How can have a common language to speak to all of them? So, we got PKCS (Public Key Cryptography Standard), which is a standard API specification by which we can interact with HSM or any other cryptographic devices. Majority of the HSM vendors implement this API model in their products. Applications that need to access the cryptographic devices can use the PKCS#11 interface and these applications do not need to change the application code once the underlying cryptographic device changes. The API model is distributed as multiple C header files which are part of the standard PKCS#11 specification. Cryptographic device vendors implement these C header files and distributed as DLL (Windows) or SO (Linux) files. Applications can then load these DLL or SO files in their applications in order to access the cryptographic devices. A number of wrappers are also written on top of DLL or SO files in different languages e.g. Java and C# etc.

Cryptoki

Cryptographic Token Interface (Cryptoki) is a library (DLL or SO file) that is provided by the cryptographic device vendors. It contains an implementation of the PKCS#11 C header files. Every cryptographic device vendor provides its own PKCS#11 complaint library. Applications has to load this library in order to access the cryptographic device.

Getting to work with AWS CloudHSM

Now, if you are using HSM from Amazon AWS, you need to know this. Probably Everybody knows, but just in case you are naive to AWS like me,

EC2

EC2 is the linux (or Windows) machine created at AWS cloud, from where we can (and we must) connect to HSM. There are lot more to speak about AWS, and EC2. For now, let us understand

Cloud is not a cloud, it is just someone else’s computer

I am deliberately omitting many technical stuffs, and we will discuss them in another blog. You can SSH to EC2 and invoke a bash shell (that means, you can connect to this machine from a ssh tool like putty, termius etc. or from your beautiful black terminal/command prompt and work with the machine by writing boring commands)

VPC

Your very own cloud inside another cloud. It is like creating your own local network within your devices in AWS. The following picture from AWS documentation might help you understanding, how VPC is important for HSM.

| appliance, but does not have access to your keys B: You control and manage your own keys C: Application performance improves (due to close proximity with AWS workloads) D: Secure key storage in tamper-resistant hardware available in multiple Availability Zones (AZs) E: Your HSMs are in your Virtual Private Cloud (VPC) and isolated from other AWS networks. | | — — | — — |

Picture: https://aws.amazon.com

Cluster

A collection of many HSMs, all in sync to ensure your keys are stored in multiple locations. If for some reason, the key is lost hardware failure, you will be in a complete soup. You can think, cluster is a one single logical HSM which is actually a collection of multiple physical HSMs. If you are fine with losing your keys and never to get them back, you can have one HSM in a cluster. Otherwise, you can keep multiple (maximum of 128) HSMs running in a cluster to ensure it is failsafe. In AWS, you cannot directly talk to HSM by an IP address (called Elastic Network Interface or ENI), you have to talk to the cluster. The cluster will then talk to all the HSMs in it and synchronize them. That is why, even if you have one HSM, you have to create a cluster. More Info

CloudHSM AWS provides a dedicated hardware assigned to you when you create a HSM. It is not Virtual. It is a real silicon chip in the cloud. You have AWS console and AWS CLI administering, creating, deleting, setting hardware parameters etc. in the cluster and the HSMs,.

You have a CloudHSM Client service by which you can connect to the HSM (actually to the cluster). You can configure your HSM by Configure Tool.

There are two command line utilities provided by Amazon, that will help you speaking to your HSM. These tools are,

• cloudhsm_mgmt_util
• key_mgmt_util

Now the question is, how an application can talk to HSM? There are multiple libraries supported by AWS to do so. These libraries are,

• PKCS #11 Library
• OpenSSL Dynamic Engine
• Java Library
• KSP and CNG Providers