1of22

HSMGuideAn introduction to HSMs.

AuthorsChris SnowColin CookNick BitounisJuris LacisZeeshan AhmadOther contributors ...

BookLicenseCC0 1.0 Universal

PrefaceAboutthisbookA primary role of a HSM is the secure management of digital keys. This book introduces digital keymanagement concepts and reinforces those concepts with exercises that the reader can perform on an opensource Thales HSM Simulator.

The reader should have a basic understanding of symmetric and asymmetric cryptography. Appendix A,Introductory Books in Cryptography provides a list of introductory books in cryptography for those wishing tolearn the basics or just wanting to refresh their knowledge in the field of cryptography.

This book is developed by the community - please send me your contributions.

The source of this book is available here(https://github.com/snowch/hsm-guide/blob/master/book.md)You can view the print version of the book here(https://gitprint.com/snowch/hsm-guide/blob/master/book.md)

AudienceUndergraduate and graduate students should find that this book supplements their studies in the theoreticalconcepts of cryptography with practical applications.

Software Engineers and Architects designing and building security solutions using the Thales brand of HSMwill learn concepts and patterns of key management that can be applied to their designs

BookOrganisationChapter 1, Introduction describes the role fulfilled by a HSM. The Thales series of HSM's are then introduced

2of22

with a short history of their evolution. Finally, an open source Thales Simulator project is presented, withhands on exercises for the reader to install the Simulator and then connect to it from Java, C#, and rubyclients.

Chapter 2, Theory covers the cryptography basics, different types of cryptographic functions and algorithms.That chapter includes the basic information of encryption and message authentication functions used incryptography. TODO finish about Chapter 2

Chapter 3, HSM Local Master Keys (LMKs) covers in detail the concept of the LMKs. The knowledge gained inthis chapter is fundamental to your understanding of the Thales HSM. Almost all other chapters depend onyou understanding the material covered in this chapter. This chapter concludes with exercise with the ThalesSimulator to help instill the concepts of LMKs.

Chapter 4, Key Concepts describes general key concepts that you need to know in addition to the materialcovered in the previous chapter about LMKs. The knowledge in this chapter is of vital importance wheninteracting with the Thales HSM. Exercises are provided with the Thales Simulator to put the concepts learntin this chapter into practise.

Chapter 5, Secure Key Exchange two sites that are secured with HSMs need to have a set of keys that areshared between the HSMs. This chapter describes how keys are created and shared. Exercises are given tosetup two demo sites with the Thales Simulator and generate and share keys between the demo sites.

Chapter 6, Dynamic Key Exchange

TODO describe other chapters

IntroductionOverviewA primary role of a HSM is the secure management of digital keys. This document describes digital keymanagement concepts, and also describes some key management patterns for solving specific problems.

Other acronyms for Hardware Security Modules include:

HSM : Hardware Security Module / Host Security ModuleTRSM : Tamper Resistant Security ModuleSCD : Secure Cryptographic Devices

TODO: Why digital key management? Life without a HSM? TODO: Thales Simulator project overview.

ThalesHSMHistoryandVersionsTODO provide a brief history of THales HSMs and an overview of current HSM versions.

ThalesHSMinteractionThere are two usage patterns for interacting with the HSM:

ConsoleCommands

3of22

Console commands fall into the categories:

HSM diagnosticsCreating KeysTODO what else?

HostCommandsHost commands fall into the categories:

TODO

TheoryTODO introduction to this section

Bits,BytesandHexTODO write some information on bits, bytes and hex representation of data

CryptographicfunctionsCryptographic functions fall into two main classes called encryption and message authentication functions.

Encryption functions are used to transmit data securely. Encryption functions are two way functions and haveboth encryption and decryption algorithms. The sender encrypts the message to be sent with the encryptionalgorithm and the cryptographic key. After receiving the encrypted data the recipient uses a decryptionalgorithm and cryptographic key to decrypt the encrypted data received:

Authentication functions are used to ensure that the message was not modified during transmission. Themessage authentication function result is not reversable. The sender calculates a check sum of the messageand sends it together with plaintext or encrypted message. The sender, using the same messageauthentication algorithm can verify the check summ received together with the message. If the check sum isvalid, the receiver can be sure that the message was not modified during transmission:

EncryptionfunctionsEncryption functions are divided into two classes, symmetric and asymmetric.

Symmetic encryption algorithms uses the same key for both encryption of plaintext data and decryption ofciphertext. Usually, the decryption algorithm is completely reversed encryption algorithm. The symmetricencryption can use stream ciphers or block ciphers. This document covers only block cipher encryption.Block cipher algorithms operate with fixed length blocks of bits on input, if the plain text message can not besplit into blocks of the required length before encryption, it has to be padded with additional bytes to meet therequired length.

Some of the most commonly used symmetric algorithms are:

Data Encryption Standard (DES / 3DES)

4of22

Advanced Encryption Standard (AES)BlowfishTwofish

Asymmetric, also known as public-key algorithms use different keys (key pairs) for data encryption anddecryption, these are called the private key and public key. Both the private and public keys are mathematicalylinked. The asymmetric encryption and decryption algorithms are also different. Before communication thereceiver generates the pair of keys and keeps private key secret. The public key is distributed with other partiesinvolved in data exchange. The public key used to encrypt data can't be used to decrypt it. Data can only bedecrypted with the private key.

Some of the most commonly used asymmetric algorithms are:

Rivest Shamir Adleman (RSA)Diffie-HellmanDigital Signature Algorithm (DSA)ElGamalElyptic Curve Cipher (ECC)

TODO - brief paragraph to say when to use symmetric and when to use assymetric?

MessageauthenticationfunctionsAuthentication functions are divided into 2 classes, hash and MAC.

Hash functions are message authentication functions wich produce a fixed length output sum (hash) ofvariable length input data. The hash functions do not use the encryption functions to produce hashes. Usuallyin cryptography, hash functions are applied on plain text messages before encryption, so that secrets are notused to produce a hash of the message. Atacker can generate the hashes free for modified messages, becauseof that no reason to use hash functions on encrypted messages or on plaintext messages without encryptionof them.

Some of the most commonly used hash functions:

MD5SHA-1SHA-2

MAC functions also called keyed hash functions are cryptographic based message authentication functions toproduce the short output check sum over the message used to ensure, that the message was not modifiedduring transmission. In contrast to hash functions, MACs are generated using cryptographic algorithms andsecret keys. The MAC can be securely applied to plain text messages without message encryption because ituses cryptographic keys to produce MAC.

The most commonly used MAC algorithms are defined in ISO-9797 standard.

TODO - can we list some of the algorithms?

TODO - brief paragraph to say when to use hash and when to use mac?

5of22

PaddingTODO - Introduction to paddings

SymmetricblockcipherpaddingsIn a case of symmetric block ciphers, padding is used to complete the message till the full block length. Forexample, if the message to be encrypted with DES algorithm has only 31 byte of data, it must be filled withadditional 1 byte to be 32 bytes long, since DES algorithm needs 8 bytes of input plaintext data.

PKCS#5paddingPKCS#5 padding is the most common type of padding applied to message during encryption. The paddingmust be removed from message after decryption to restore the original message content. PKCS#5 padding fillsmessage with bytes with padding length as value. If message meets length requirements, additional full blockof padding must be added to the end of message.

The example of PKCS#5 padding for incomplete message:

The example of PKCS#5 padding for complete 8 byte message:

The example of PKCS#5 padding on Java:

ISO-9797Method1paddingISO-9797 Method One padding is used for message MACing. This method adds zero bytes to the end ofmessage until it meets the length requirements. It is not necessery to add an additional block of padding if a

/**sincedifferentsymmetricalgoritmshavedifferentinputdatablocksizes

*theblockSizevariableispassedtothemethods*/

publicpublic staticstatic bytebyte [][] pkcs5Padpkcs5Pad (( bytebyte [][] block,, intint bloclSize)) {{intint padLen== blockSize-- block.. length%% blockSize;;ifif (( padLen==== 0)) {{padLen== blockSize;;}}intint padVal== (( bytebyte )) padLen;;bytebyte [][] paddedBlock== newnew bytebyte [[ block.. length++ padLen];];System.. arraycopy(( block,, 0,, paddedBlock,, 0,, block.. length););forfor (( intint k== 0;; k

6of22

message meets length requirements. Method One padding can not be used for message encryption because itis impossible to differentiate padding bytes from the message content.

The example of ISO-9797 Method 1 padding on Java:

ISO-9797Method2paddingISO-9797 Method Two padding is used for message padding for MAC calculation, but it can be used, also, formessage encryption. The padding applied to the message adds one byte vith value 0x80 (a singe bit with value1) and, if necessery, adds zero bytes until the message meets length requirements. If that padding method isused for message MACing, it is not necessery to add additional block of padding if message is complete, but ina case of message encryption it must be.

Example of ISO9797 Method 2 padding for incomplete message

Example of ISO9797 Method 2 padding for complete message

The example of ISO-9797 Method 2 padding on Java:

/**sincedifferentsymmetricalgoritmshavedifferentinputdatablocksizes*theblockSizevariableispassedtothemethods

*/

publicpublic staticstatic bytebyte [][] iso9797Method1Padiso9797Method1Pad (( bytebyte [][] block,, intint blockSize)) {{intint padLen== blockSize-- block.. length%% blockSize;;ifif (( padLen==== blockSize)) {{padLen== 0;;}}bytebyte [][] paddedBlock== newnew bytebyte [[ block.. length++ padLen];];System.. arraycopy(( block,, 0,, paddedBlock,, 0,, block.. length););returnreturn paddedBlock;;}}

/**sincedifferentsymmetricalgoritmshavedifferentinputdatablocksizes*theblockSizevariableispassedtothemethods

*/

publicpublic staticstatic bytebyte [][] iso9797Method2Padiso9797Method2Pad (( bytebyte [][] block,, intint blockSize,, booleanboolean forMacing)) {{intint padLen== blockSize-- block.. length%% blockSize;;//ifpaddingisusedforMACing,wedonotneedtoaddadditionalblock//inacaseofcompletemessagelength(multipleofblockSize)ifif (( forMacing&&&& padLen==== blockSize)) {{ padLen== 0;;}}bytebyte [][] paddedBlock== newnew bytebyte [[ block.. length++ padLen];];System.. arraycopy(( block,, 0,, paddedBlock,, 0,, block.. length););paddedBlock[[ block.. length]] == (( bytebyte )) 0x80;;returnreturn paddedBlock;;}}

publicpublic staticstatic bytebyte [][] iso9797Method2Unpadiso9797Method2Unpad (( bytebyte [][] paddedMsg)) {{

7of22

AsymmetriccipherpaddingsIn the most cases asymmetric cipher paddings are used to randomise the output. Usualy, asymmetricpaddings have fixed length and is placed in plaintext message in the predefined position.

PKCS#1v1.5paddingPKCS#1 v1.5 padding is used to randomise the ciphertext output dirung RSA encryption to avoid some types ofattacks. The message length to be encrypted using RSA-PKCS#1 scheme must meet the condition mLen> 0;; i--)--) {{ifif (( paddedMsg[[ i]] ==== (( bytebyte )) 0x80)) {{padIdx== i;;}}}}bytebyte [][] message== newnew bytebyte [[ paddedMsg.. length-- padIdx];];System.. arraycopy(( paddedMsg,, 0,, message,, 0,, message.. length););returnreturn message;;}}

/**TheexamplebelowaddsPKCS#1paddingoflengthtomakemessagethesame

*sizeaspubickey.*/

publicpublic staticstatic bytebyte [][] pkcs1Padpkcs1Pad (( bytebyte [][] message,, intint keyLen)) {{java.. util.. Randomr== newnew java.. util.. Random();();intint padLen== keyLen-- message.. length-- 3;;bytebyte [][] rand== newnew bytebyte [[ padLen];];bytebyte [][] paddedMsg== newnew bytebyte [[ message.. length++ padLen++ 3];];paddedMsg[[ 0]] == (( bytebyte )) 0x00;;paddedMsg[[ 1]] == (( bytebyte )) 0x02;;paddedMsg[[ padLen++ 2]] == (( bytebyte )) 0x00;;intint n== 0;;forfor (( intint i== 0;; i

8of22

PKCS#1OAEPpaddingPKCS#1 OAEP (Optimal Asymmetric Encryption Padding) padding is used to randomise the ciphertext outputdirung RSA encryption to avoid some types of attacks. The message length to be encrypted using RSA-OAEPscheme must meet the condition mLen

9of22

The code above can be compiled with command:

javacRSAPaddingTest.java

Run with command:

javaRSAPaddingTest

The output will be as follows:

The output abowe shows, that Java adds a random byte PKCS#1 padding to message making it the same lengthas a public key. In the example public key (modulo) is 512 bits long.

00 - 1st byte is 0x0002 - 2nd byte is 0x02570D03777D36E4B335597EFCDB68FA076D6B7DFD210B727C9A088D351D52846185F9C03826B35062C1EFB3644C190BE6DDC2- random bytes (50)

*PKCS1Paddingtoplaintextmessage*/

privateprivate staticstatic bytebyte [][] encryptencrypt (( Stringmsg,, PublicKeypublicKey)) throwsthrows Exception{{Ciphercipher== Cipher.. getInstance(( "RSA/ECB/PKCS1Padding"););cipher.. init(( Cipher.. ENCRYPT_MODE,, publicKey););bytebyte [][] ciphMsg== cipher.. doFinal(( msg.. getBytes());());returnreturn ciphMsg;;}}

/**MethoddecryptspassedciphertextwithRSAprivatekeyanddonotremove*paddingfromplaintextmessage*/

privateprivate staticstatic bytebyte [][] decryptdecrypt (( bytebyte [][] ciphMsg,, PrivateKeyprivateKey)) throwsthrows Exception{{Ciphercipher== Cipher.. getInstance(( "RSA/ECB/NoPadding"););cipher.. init(( Cipher.. DECRYPT_MODE,, privateKey););bytebyte [][] plainMsg== cipher.. doFinal(( ciphMsg););returnreturn plainMsg;;}}

publicpublic staticstatic voidvoid mainmain (( String[][] args)) {{Stringmsg== args[[ 0];];intint keyLen== Integer.. parseInt(( args[[ 1]);]);trytry {{KeyPairkp== generateKeyPair(( keyLen););PublicKeypublicKey== kp.. getPublic();();PrivateKeyprivateKey== kp.. getPrivate();();bytebyte [][] ciphMsg== encrypt(( msg,, publicKey););bytebyte [][] plainMsg== decrypt(( ciphMsg,, privateKey););System.. out.. println(( byte2hex(( plainMsg));));}} catchcatch (( Exceptione)) {{e.. printStackTrace();();}}}}}}

$javaJavaRSA342342342345120002570D03777D36E4B335597EFCDB68FA076D6B7DFD210B727C9A088D351D52846185F9C03826B35062C1EFB3644C190BE6DDC2003334323334323334323334

10of22

00 - padding separator, 0x00;3334323334323334323334 - plaintext message

IntroductiontotheThalesSimulatorThalesSimulatorExercisesThis section provides some exercises to get hands on experience using the Thales Simulator.

SettinguptheThalesSimulatorIn this exercise, you will download, install and run the Thales Simulator on a Windows machine. The purposeof this exercise is to get the Thales Simulator setup and ready for use in later chapters.

DownloadandInstalltheThalesSimulator1. Download ThalesSim.Setup.0.9.6.x86.zip from: http://thalessim.codeplex.com/releases/view/88576

(http://thalessim.codeplex.com/releases/view/88576)2. Unzip the downloaded file and execute the file ThalesWinSimulatorSetup.msi, accepting the default

options.

StartingtheThalesSimulator1. Navigate to the folder where you installed the Simulator (E.g. C:\ProgramFiles(x86)\NTG\Thales

Simulator\)2. Execute ThalesWinSimulator.exe (if your are running Windows 7, right click the file and select Run As

Administrator)3. Click the Start Simulator button: 4. In the Application Events window, the simulator will inform you that it could not find a file containing

the LMK keys so it will create a new set of keys for you. The Simulator will always create the same keys.

UsingtheSimulatorConsoleIn this section, we will connect to the HSM Console and run a basic command, Query Host (QH) to testconnectivity to the HSM.

For a full list of console commands, you will need to refer to the Console Reference Manual which is availablefrom Thales.

Note: The Thales Simulator only implements a subset of the commands. A list of implemented consolecommands can be found here(http://thalessim.codeplex.com/wikipage?title=list%20of%20supported%20console%20commands).

ConnectingwiththeSimulatorConsole

In this section, we ... TODO describe what we are doing here

1. Start the simulator as described in Starting the Thales Simulator(./book.md#starting-the-thales-simulator)2. Click The Console button 3. In the console window click Connect to Console.4. Enter the console command QH followed by ENTER.

11of22

5. You should see something similar to this

In this exercise, we executed a console command QH against the simulator and observed the response that wasdisplayed by the simulator.

ConnectingwithaPythonClient

See Appendix (TODO) to see instructions for:

installing pythonrunning python code

The code simply opens a TCP connection to a Thales Simulator listening on localhost on port 9998. Next thepython client converts the string 0006303030304e43 from its hexidecimal format to binary and sends it to theThales Simulator. Finally the code receives the response and prints it to standard output.

To understand the meaning of the string 0006303030304e43, it can be broken down as follows (in reverseorder):

4e43 is the 2 byte command NC as hex30303030 adds a 4 byte header 0000 as hex0006 represents the length in hex of the comamnd and header (i.e. the length of 0000NC)

The command should output a response similar to the following:

The response from HSM can be broken down as follows:

! actualy is 0021, it is software header returned by HSM, actual response length0000 is HSM response header which is set the same as for received command

importimport binasciiimportimport socketimportimport sys

#openaconnectiontotheThalesSimulatorsock== socket.. socket(socket.. AF_INET,socket.. SOCK_STREAM)server_address== ('localhost',9998)sock.. connect(server_address)

#thecommandweneedtosendcommand== b'0006303030304e43'

#convertthehexstringtobinarycommand== binascii.. a2b_hex(command)

#sendacommandsock.. send(command)

#receivethecommandresponserecv_data== sock.. recv(1024)

#printoutresponsesys.. stdout.. buffer.. write(recv_data)

#closetheconnectionsock.. close()

!! 0000ND007B44AC1DDEE2A94B0007-- E000

12of22

ND the response code. The response from HSM always is command code with incremented second letter00 error code, 00 means that no errors occured during command processing7B44AC1DDEE2A94B Local Master Key (see corresponding chapter) check value0007-E000 means the HSM firmware revision number

Each command has its own response specification, see "Host command reference manual" for more details.

HSMLocalMasterKeys(LMKs)Local Master Keys (LMKs) are a central concept for HSMs. This section describes LMKs in more detail.

LMKOverviewLocal Master Keys are a sets of 40 DES keys. They are stored securely in the HSM making it very difficult for anattacker to gain access to them. LMKs are the only keys that are stored in the HSM.

LMKs are not used for encrypting data, but are instead used to encrypt and decrypt other keys as these enter orleave the HSM. LMKs are used to ensure that even if the data traffic between the HSM and an application isrecorded, the clear values of any exchanged keys are not compromised.

LMKs come in pairs and the Thales HSM contains several LMK pairs. Different LMK pairs are used toencrypt/decrypt different types of security keys. LMK pairs are identified by two numbers, for example LMKpair 04-05, LMK pair 14-15, etc. See the diagram below.

Each LMK pair is assigned a code. LMK pair 04-05 is assigned code 00, while LMK pair 14-15 is assigned code02. The full list of HSM key pairs are listed in Table 2.1, LMK Key Pairs, below. Note that HSM key pairs donot start at 00-01, instead the numbering starts at 04-05, and runs non-contiguously to 38-39.

Key Pair Code

04-05 00

06-07 01

14-15 02

16-17 03

18-19 04

20-21 05

22-23 06

24-25 07

26-27 08

28-26 09

30-31 10

13of22

32-33 11

34-35 12

36-37 13

38-39 14

Key Pair Code

Each HSM has a unique set of LMK pairs that can be either randomly generated or loaded from smart cards.HSM users jealously guard the LMKs because the integrity of the key management security scheme dependsupon them.

LMKVariantsBack when the HSM had only a handful of LMK pairs, more than the type of keys that had to be encrypted, away had to be found to ensure that different key types can be used but also provide a way to identify parityerrors with these key types. Variants are an easy way to pseudo-multiply your LMK pairs. (TODO validate this)

Keys are encrypted under LMK pairs using either the clear value of the LMK or a variant of the LMK. An LMKvariant is created by performing a XOR operation with a value on the LMK key. For example, variant 1 of anLMK is created by XORing the LMK with the value 000000000000000000000000000000A6. The Thales HSMsupports 10 variants for each LMK pair, with variant 0 being the clear LMK itself. The full list of variantcalculation functions can be seen in the Table below.

Variant number Variant Calculation Function - XOR LMK with:

0 Not applicable - use clear value of LMK

1 000000000000000000000000000000A6

2 0000000000000000000000000000005A

3 0000000000000000000000000000006A

4 000000000000000000000000000000DE

5 0000000000000000000000000000002B

6 00000000000000000000000000000050

7 00000000000000000000000000000074

8 0000000000000000000000000000009C

9 000000000000000000000000000000FA

ExercisesTODO - what exercises could be performed on the Simulator around LMK Concepts? Could we walk throughthe default keys with the HSM simulator and how to change those keys?

14of22

KeyConceptsKeyTypesEach different key supported by the Thales HSM has a unique code called the key type code. The key type is athree-digit number and is made up from the code of the LMK pair and the LMK variant. Therefore, keysencrypted under LMK pair 04-05 using a variant 1 will have a key type equal to 00 + 1 = 001. It is importantto understand key types since several Thales commands expect key type codes as parameters. The full list ofkey types can be seen in the table below.

LMK Key Pair LMK Code Variant Key Type Code Key Type

04-05 00 0 000 ZMK

06-07 01 0 001 ZPK

14-15 02 0 002 PVK, TMK, TPK

14-15 02 4 402 CVK, CSCK

16-17 03 0 003 TAK

22-23 06 0 006 WWK

26-27 08 0 008 ZAK

28-29 09 0 009 BDK1

28-29 09 1 109 MK-AC

28-29 09 2 209 MK-SMI

28-29 09 3 309 MK-SMC

28-29 09 4 409 MK-DAC

28-29 09 5 509 MK-DN

28-29 09 6 609 BDK2

28-29 09 7 709 MK-CVC3

28-29 09 8 809 BDK3

30-31 0A 0 00A ZEK

32-33 0B 0 00B DEK

32-33 0B 3 30B TEK

In the latest payShield9000 and HSM8000 firmwares Thales has introduced second, PCI-HSM standardcompliant, key type table with the changes around 002 key type - PVK, TMK, TPK. The changes moves TMKand TPK to different LMK pair and Variants leaving PVK the only key of 002 type:

LMK Key Pair LMK Code Variant Key Type Code Key Type

15of22

14-15 02 0 002 PVK

36-37 0D 7 70D TPK

36-37 0D 8 80D TMK

LMK Key Pair LMK Code Variant Key Type Code Key Type

KeyCheckValueThe check value of a key is derived by DES encrypting 16 zeroes (8 zero bytes) using that key. For example, theKCV for key 0123456789ABCDEF is D5D44FF720683D0D

The purpose of a KCV is to ensure that a key has been correctly transmitted between different parties and thatthey key is also configured correctly in systems. It is common practice to transmit the KCV of a key along withthe key itself. Sometimes, the complete result of the DES encrypt operation is used, but typically only the firstsix digits are used (in the example, D5D44F).

KeyFormatsThe Thales HSM uses two major formats when processing security keys. These are Variant and ANSI.

The variant concept is similar to the one used to form LMK variants: a key is XORed with a value to form thekey variant. Double-length keys are XORed with the value:

and triple-length keys are XORed with the value:

TODO: how does the variant concept differ to the LMK variant concept?

The ANSI format is much simpler: a key is used as-is without performing any additional operations on it.

KeySchemeDepending on their length and key format, keys are designated by a key scheme that helps to quickly identifythe nature of a key. Key schemes are the following:

Key Scheme Description

Z Single-length ANSI keys

U Double-length variant keys

T Triple-length variant keys

X Double-length ANSI keys

Y Triple-length ANSI keys

00000000000000A6000000000000005A

00000000000000A6000000000000005A000000000000006A

16of22

ExercisesTODO - what exercises could be performed on the Simulator around LMK Concepts?

SecureKeyExchangeOverviewTo securely exchange information between two users using the DES encryption scheme, it is vital to securelyshare a set of initial keys. This role is fulfilled by the Zone Master Keys. Unlike an LMK which does not leavethe HSM, ZMKs are intended to be shared between sites to create secure Zones. The ZMK is distributedmanually between the sites. The ZMK allow future (data encrypting) keys to be automatically shared betweensites by encrypting those future keys with the ZMK. In that regard, they work very much like the LMKs withthe important exception that they can be shared between users.

ZMKs have a key type code of 000 (they are encrypted under LMK pair 04-05 with a variant of 0).

TODO diagram

The transfer of the ZMK between sites is performed manually. The ZMK is shared in parts (components) sothat no one person will see the key.

TODO diagram

The data encryption key is a Zone PIN Key (ZPK). The ZPK was historically used to encrypt PINs for transferbetween sites (e.g. between Acquirer and Issuer).

For local storage (e.g. on the application server using the ZMK), the ZMK is encrypted under one of the LMKkeys.

Example-SecureKeyExchangeTwo parties want to exchange a ZMK. One party generates a random ZMK using three clear components whichare the following:

TODO: describe what is meant by clear components

Each of these clear components are kept by a separate custodian that works for the first party and aredelivered to different custodians of the second party. To create the complete ZMK, each custodian enters theircomponent to the HSM which combines them to form the ZMK. Most typically, the clear components aresimply XORed to form the ZMK. In the example, the ZMK value is:

When generating the ZMK, the first party also gives the KCV of the ZMK to the second party (for the examplekey the KCV is 6CE4CF). That way, the second party can verify the correct reception and data entry of the ZMKcomponents.

TODO: See Exercise Creating a ZMK for hands on experience creating a ZMK.

2CBF0D8FA4E66ECE6B239E25B9BAD934B60825E3790D31CE4A4AA74397461C1329BFE3C1D0C1E50BCD7038A42CFB160B

B308CBAD0D2ABA0BEC1901C20207D32C

17of22

ExercisesCreatingaZoneMasterKey(ZMK)In this exercise, we create a Zone Master Key (ZMK) using console commands.

The ZMK is distributed manually as components. To create the ZMK, we first create three ZMK components.

GeneratetheZMKComponentsGenerate three ZMK components using the console command Generate Component (GC). Repeat thecommand three times as shown below:

Description

We are generating a Double-length key, so we choose a Key Length of 2. See Key Schemes for a list of the keyschemes.

We are generating ZMK keys, so we use the Key Type 000. See Key Types for a list of the key types.

We are generating a Double-length variant key, which has a Key Scheme of U. See Key Schemes for a list of thekey schemes.

TODO: refer to a section that describes how to decide which scheme and type of key is most suitable for yourparticular encryption requirements? E.g. why have we chosen Double-length variant key and not Single-lengthANSI keys for this example?

GeneratetheZMKfromthecomponentsThis step uses the FK command to generate the ZMK from the three ZMK components previously generated:

TODO: describe the various command options and how to choose which option values to use.

GC#UserinputKeylength[1,2,3]:2#UserinputKeyType:000#UserinputKeyScheme:U#UserinputClearComponent:79CD23809B4FC1C47F9EFB2ADF2A674AEncryptedComponent:U1BA5185AFCF15A1B274BE1E003B47C2AKeycheckvalue:7A5BC7GC#UserinputKeylength[1,2,3]:2#UserinputKeyType:000#UserinputKeyScheme:U#UserinputClearComponent:0157B3DF61163402372C54FD62F21C91EncryptedComponent:UFCE47AF7FFF89F402407A35AF063D3E1Keycheckvalue:1E79CBGC#UserinputKeylength[1,2,3]:2#UserinputKeyType:000#UserinputKeyScheme:U#UserinputClearComponent:7AEAB5A41A9E9B68EF80494C08194ADAEncryptedComponent:UEE8D4F9EC8B2ADF49CD2F0D27F5C95C5Keycheckvalue:277A5F

FK#UserinputKeylength[1,2,3]:2#UserinputKeyType:000#UserinputKeyScheme:U#Userinput

18of22

The description of the Key length, Key Type and Key Scheme values are described in the Description forGenerate the ZMK Components.

The Component type is either:

X = XORed clear components. The useversal way and the most commonly used, to exchange the keysbetween different parties.H = Clear Half or Third Key (key splitted into 2 or 3 blocks, each block is entered as separate component).Like XORed clear components, this is applied way to exchange keys between any parties.E = Components encrypted under LMK. HSM forst decrypts the components and XORs decryptedcomponents. Such components can be used only localy since 3rd parties do not have an access tocomponent encryption LMK pair. This is the way to store keys in components in secure manner.S = Components stored on smartcards. Can only be used to exchange keys between Thales HSMs.

DynamicKeyExchangeOverviewTODO: Why dynamic key exchange?

ZonePINKey(ZPK)The Zone PIN Key (ZPK) is a data encrypting key. It is used to encrypt the data that is transmitted in a securityzone. For transfer between sites, the ZPK is encrypted under the ZMK. When stored locally (e.g. on theapplication server), the ZPK is encrypted using one of the LMK Keys.

ZPKs have a key type code of 001 (encrypted under LMK pair 06-07 with a variant of 0).

TODO: See Exercise Creating a ZPK for hands on experience creating a ZPK.

Example-DynamicKeyExchangeAssume that the ZMK presented in the previous example has been exchanged between two parties. One party,then, generates a random ZPK equal to:

The party then encrypts this ZPK under the ZMK to safely transmit this to the other party. The ZPK under theZMK is:

Componenttype[X,H,E,S]:X#UserinputEnternumberofcomponents(2-9):3#UserinputEntercomponent#1:1BA5185AFCF15A1B274BE1E003B47C2A#UserinputfromGCresponse:U1BA5185AFCF15A1B274BE1E003B47C2AEntercomponent#2:FCE47AF7FFF89F402407A35AF063D3E1#UserinputfromGCresponse:UFCE47AF7FFF89F402407A35AF063D3E1Entercomponent#3:EE8D4F9EC8B2ADF49CD2F0D27F5C95C5#UserinputfromGCresponse:UEE8D4F9EC8B2ADF49CD2F0D27F5C95C5Encryptedkey:U104C4216A751FEEEFF55698B26C57789Keycheckvalue:BA0FC3

ADD3B5C7B576D3AE38B90B7C0EB67A7C,KCV=CB59C0

C9A62E96ADFB52A7815BE8D7E730B24E,KCV=CB59C0

19of22

KeyTranslationIn our previous example, the value C9A62E96ADFB52A7 815BE8D7E730B24E represents the randomly createdZPK encrypted under the previously created ZMK. But imagine that one of the parties that have exchanged thisZPK needs to transmit it to another party with which they share a different ZMK which well call ZMK2 . Toproperly transmit the ZPK to the other zone that is secured with ZMK2, the ZPK has to be:

Decrypted under ZMK.Encrypted under ZMK2.

This process is called key translation. Key translation does not happen with specific key types as the ZMK thatwas used in the previous example but is a more general process - for example it is possible to translate a keyfrom encryption under the ZMK to encryption under an LMK.

Key translation always takes place within the HSM to avoid exposing the clear value of the key beingtranslated.

TranslatingaZPK(betweenZMKencryptionandLMKencryption)The HSM provides functionality to translate a ZPK between ZMK and LMK. This is used when a ZPK is receivedby Site B. In this case, Site A sends the ZPK encrypted with the ZMK to Site B. Site B translates the ZPK to LMKencryption.

The ZPK under LMK encryption is used for encrypting/decrypting the data sent between the sites.

TODO: insert diagram

ExercisesCreatingaZonePINKey(ZPK)In this exercise, we create a Zone PIN Key (ZPK) using console commands.

When prompted for the ZMK, use the encrypted ZMK value from the section called Creating a Zone MasterKey (ZMK).

PINblockcreation(clearPINblocks)

PINblockencryptionandsecurityzones.ZPKsandTPKs

KGKeylength[1,2,3]:2KeyType:001KeyScheme(LMK):UKeyScheme(ZMK)[ENTERFORNONE]:XEnterencryptedZMK[ENTERFORNONE]:U104C4216A751FEEEFF55698B26C57789EnterZMKcheckvalue[ENTERTOSKIPCVTEST]:KeyunderLMK:U858651EC83AFCA668175804F5B7DCD6BKeyencryptedfortransmission:XBAA518AAD10D28A2D32A5688317F44EBKeycheckvalue:6543F4

20of22

PINtranslation

MACing

CVV/CVV2/iCVV

AppendixA-Commonlyusedcodeinexamples

AppendixB-Someotherusefullcodepeaces

AppendixC-IntroductoryBooksinCryptography

Appendix-InstallingPythonDownload and install the latest version of python from https://www.python.org/download/(https://www.python.org/download/)

Appendix-ConnectingtotheHSMusingdifferentlanguagesConnectingwithaPerlClient

In this exercise, we execute a host command against the Thales Simulator.

If you have perl installed, you can run the NC (Perform diagnostics) host command against the HSM as follows:

privateprivate staticstatic Stringbyte2hexbyte2hex (( bytebyte bs[])[]) {{intint i;;Strings== newnew String();();Stringhex_digits== "0123456789ABCDEF";;bytebyte c;;ifif (( bs==== nullnull |||| bs.. length==== 0)) {{returnreturn s;;}}forfor (( i== 0;; i>>> 4)) && 0xf););s+=+= hex_digits.. charAt(( c&& 0xf););}}returnreturn s;;}}

21of22

The command should output a response similar to the following:

The response from HSM can be broken down as follows:

! actualy is 0021, it is software header returned by HSM, actual response length0000 is HSM response header which is set the same as for received commandND the response code. The response from HSM always is command code with incremented second letter00 error code, 00 means that no errors occured during command processing7B44AC1DDEE2A94B Local Master Key (see corresponding chapter) check value0007-E000 means the HSM firmware revision number

Each command has its own response specification, see "Host command reference manual" for more details.

ConnectingwithaJavaClient

In this session, we connect to the HSM over TCP/IP using Java. When we connect using Java, we can sendHost Commands to the HSM.

In the code example, below, we send the command Perform Diagnostics (NC), and print the response toSystem.out.

For a full treatment of Host Programming the Thales HSM, refer to the Thales documentation HostProgrammers Manual. For a full list of Host Commands, refer to the Thales documentation Host CommandReference Manual

#!/usr/bin/envperluseuse IO::Socket::INET;mymy $sock== newnew IO::Socket::INET(PeerAddr=>=> "localhost:9998")oror die;$sock->-> send(pack"H*","0006303030304e43");$sock->-> recv($data,1024);printprint $data;

!! 0000ND007B44AC1DDEE2A94B0007-- E000

importimport java.io.BufferedOutputStream;;importimport java.io.InputStream;;importimport java.io.OutputStream;;importimport java.net.Socket;;importimport java.nio.ByteBuffer;;publicpublic classclass MainMain {{

publicpublic staticstatic voidvoid mainmain (( String[][] args)) throwsthrows Exception{{

Socketsocket== newnew Socket(( "localhost",, 9998););

Stringcommand== "0006303030304e43";;

//thefollowinglineconvertsthehexcommandstringtoabytearraybytebyte [][] bytes== ByteBuffer.. allocate(( 8).). putLong(( Long.. parseLong(( command,, 16)).)). array();();

OutputStreamout== socket.. getOutputStream();();BufferedOutputStreambufferedOut== newnew BufferedOutputStream(( out,, 1024););bufferedOut.. write(( bytes););bufferedOut.. flush();();

InputStreamin== socket.. getInputStream();();intint result;;whilewhile (((( result== in.. read())()) !=!= -- 1)) {{System.. out.. print(((( charchar )) result););

22of22

See the description from Connecting with a perl client(/book.md#connecting-with-a-perl-client)for the format of thecommand: 0006303030304e43.

ConnectingwithaUnixclient

If you have netcat (nc) installed, you can run a command by using echo convert a hex string to binary and sendit to the Thales simulator using netcat.

Here we send the Thales command NC which asks the Thales Simulator to Perform Diagnostics and return theresult:

See the description from Connecting with a perl client(/book.md#connecting-with-a-perl-client)for the format of thecommand: 0006303030304e43.

ConnectingwithaPL/SQLclient

If you want to call HSM using PL/SQL you can use the UTL_TCP package as in example procedure below:

}}socket.. close();();}}}}

$echo-- ne'\x00\x06\x30\x30\x30\x30\x4e\x43'|| nclocalhost9998!! 0000ND007B44AC1DDEE2A94B0007-- E000

CREATECREATE OROR REPLACEREPLACE PROCEDUREPROCEDURE call_hsmISIS

v_to_hsmVARCHAR2(255);n_lengthNUMBER(2);v_from_hsmVARCHAR2(255);rw_from_hsmRAW(100);cc utl_tcp.connectionconnection ;BEGINBEGINcc :== utl_tcp.open_connection('192.168.229.1','9998',NULLNULL ,NULLNULL ,NULLNULL ,NULLNULL ,NULLNULL ,NUNULLLL ,1);v_to_hsm:== '0000'|||| 'NC';v_to_hsm:== CHR(0)|||| CHR(LENGTHLENGTH (v_to_hsm))|||| v_to_hsm;v_from_hsm:== utl_tcp.write_text(cc ,v_to_hsm);n_length:== utl_tcp.available(cc ,1);n_length:== utl_tcp.read_raw(cc ,rw_from_hsm,100);SELECTSELECT SUBSTR(CASTCAST (rw_from_hsmASAS VARCHAR2(255)),5)INTOINTO v_from_hsmFROMFROM dual;v_from_hsm:== utl_i18n.raw_to_char(v_from_hsm);dbms_output.put_line(v_from_hsm);utl_tcp.close_connection(cc );ENDEND ;