[
{
"path": ".gitignore",
"content": "target \r\n"
},
{
"path": "LICENSE",
"content": "CC0 1.0 Universal\n\nStatement of Purpose\n\nThe laws of most jurisdictions throughout the world automatically confer\nexclusive Copyright and Related Rights (defined below) upon the creator and\nsubsequent owner(s) (each and all, an \"owner\") of an original work of\nauthorship and/or a database (each, a \"Work\").\n\nCertain owners wish to permanently relinquish those rights to a Work for the\npurpose of contributing to a commons of creative, cultural and scientific\nworks (\"Commons\") that the public can reliably and without fear of later\nclaims of infringement build upon, modify, incorporate in other works, reuse\nand redistribute as freely as possible in any form whatsoever and for any\npurposes, including without limitation commercial purposes. These owners may\ncontribute to the Commons to promote the ideal of a free culture and the\nfurther production of creative, cultural and scientific works, or to gain\nreputation or greater distribution for their Work in part through the use and\nefforts of others.\n\nFor these and/or other purposes and motivations, and without any expectation\nof additional consideration or compensation, the person associating CC0 with a\nWork (the \"Affirmer\"), to the extent that he or she is an owner of Copyright\nand Related Rights in the Work, voluntarily elects to apply CC0 to the Work\nand publicly distribute the Work under its terms, with knowledge of his or her\nCopyright and Related Rights in the Work and the meaning and intended legal\neffect of CC0 on those rights.\n\n1. Copyright and Related Rights. A Work made available under CC0 may be\nprotected by copyright and related or neighboring rights (\"Copyright and\nRelated Rights\"). Copyright and Related Rights include, but are not limited\nto, the following:\n\n i. the right to reproduce, adapt, distribute, perform, display, communicate,\n and translate a Work;\n\n ii. moral rights retained by the original author(s) and/or performer(s);\n\n iii. publicity and privacy rights pertaining to a person's image or likeness\n depicted in a Work;\n\n iv. rights protecting against unfair competition in regards to a Work,\n subject to the limitations in paragraph 4(a), below;\n\n v. rights protecting the extraction, dissemination, use and reuse of data in\n a Work;\n\n vi. database rights (such as those arising under Directive 96/9/EC of the\n European Parliament and of the Council of 11 March 1996 on the legal\n protection of databases, and under any national implementation thereof,\n including any amended or successor version of such directive); and\n\n vii. other similar, equivalent or corresponding rights throughout the world\n based on applicable law or treaty, and any national implementations thereof.\n\n2. Waiver. To the greatest extent permitted by, but not in contravention of,\napplicable law, Affirmer hereby overtly, fully, permanently, irrevocably and\nunconditionally waives, abandons, and surrenders all of Affirmer's Copyright\nand Related Rights and associated claims and causes of action, whether now\nknown or unknown (including existing as well as future claims and causes of\naction), in the Work (i) in all territories worldwide, (ii) for the maximum\nduration provided by applicable law or treaty (including future time\nextensions), (iii) in any current or future medium and for any number of\ncopies, and (iv) for any purpose whatsoever, including without limitation\ncommercial, advertising or promotional purposes (the \"Waiver\"). Affirmer makes\nthe Waiver for the benefit of each member of the public at large and to the\ndetriment of Affirmer's heirs and successors, fully intending that such Waiver\nshall not be subject to revocation, rescission, cancellation, termination, or\nany other legal or equitable action to disrupt the quiet enjoyment of the Work\nby the public as contemplated by Affirmer's express Statement of Purpose.\n\n3. Public License Fallback. Should any part of the Waiver for any reason be\njudged legally invalid or ineffective under applicable law, then the Waiver\nshall be preserved to the maximum extent permitted taking into account\nAffirmer's express Statement of Purpose. In addition, to the extent the Waiver\nis so judged Affirmer hereby grants to each affected person a royalty-free,\nnon transferable, non sublicensable, non exclusive, irrevocable and\nunconditional license to exercise Affirmer's Copyright and Related Rights in\nthe Work (i) in all territories worldwide, (ii) for the maximum duration\nprovided by applicable law or treaty (including future time extensions), (iii)\nin any current or future medium and for any number of copies, and (iv) for any\npurpose whatsoever, including without limitation commercial, advertising or\npromotional purposes (the \"License\"). The License shall be deemed effective as\nof the date CC0 was applied by Affirmer to the Work. Should any part of the\nLicense for any reason be judged legally invalid or ineffective under\napplicable law, such partial invalidity or ineffectiveness shall not\ninvalidate the remainder of the License, and in such case Affirmer hereby\naffirms that he or she will not (i) exercise any of his or her remaining\nCopyright and Related Rights in the Work or (ii) assert any associated claims\nand causes of action with respect to the Work, in either case contrary to\nAffirmer's express Statement of Purpose.\n\n4. Limitations and Disclaimers.\n\n a. No trademark or patent rights held by Affirmer are waived, abandoned,\n surrendered, licensed or otherwise affected by this document.\n\n b. Affirmer offers the Work as-is and makes no representations or warranties\n of any kind concerning the Work, express, implied, statutory or otherwise,\n including without limitation warranties of title, merchantability, fitness\n for a particular purpose, non infringement, or the absence of latent or\n other defects, accuracy, or the present or absence of errors, whether or not\n discoverable, all to the greatest extent permissible under applicable law.\n\n c. Affirmer disclaims responsibility for clearing rights of other persons\n that may apply to the Work or any use thereof, including without limitation\n any person's Copyright and Related Rights in the Work. Further, Affirmer\n disclaims responsibility for obtaining any necessary consents, permissions\n or other rights required for any use of the Work.\n\n d. Affirmer understands and acknowledges that Creative Commons is not a\n party to this document and has no duty or obligation with respect to this\n CC0 or use of the Work.\n\nFor more information, please see\n"
},
{
"path": "README.md",
"content": "hsm-guide\n=========\n\nTo view or edit the book source, go [here](https://github.com/snowch/hsm-guide/blob/master/book.md) (to edit, click on the *Edit* button)\n\nNote: diagrams with the 'uxf' extension have been created using [Umlet](http://www.umlet.com/)\n\n### Todo\n\n- Finish the book!! (please help!!)\n\n### License\n\n[Creative Commons](https://creativecommons.org/publicdomain/zero/1.0/)\n\n### Contributing\n\nPlease clone this repository and send me your pull requests, or just create an [Issue](https://github.com/snowch/hsm-guide/issues) with your suggestions.\n"
},
{
"path": "book.md",
"content": "HSM Guide\n=========\n\nAn introduction to HSMs.\n\n\n## Authors\n\n- Chris Snow\n- Colin Cook\n- Nick Bitounis\n- Juris Lacis\n- Zeeshan Ahmad\n- Other contributors ...\n\n## Book License\n\nCC0 1.0 Universal\n\n# Preface\n\n## About this book\n\nA primary role of a HSM is the secure management of digital keys. This book introduces digital key\nmanagement concepts and reinforces those concepts with exercises that the reader can perform on an open\nsource Thales HSM Simulator.\n\nThe reader should have a basic understanding of symmetric and asymmetric cryptography. Appendix A,\nIntroductory Books in Cryptography provides a list of introductory books in cryptography for those\nwishing to learn the basics or just wanting to refresh their knowledge in the field of cryptography.\n\nThis book is developed by the community - please send me your contributions.\n\n - The source of this book is available [here](https://github.com/snowch/hsm-guide/blob/master/book.md)\n - You can view the print version of the book [here](https://gitprint.com/snowch/hsm-guide/blob/master/book.md)\n\n## Audience\n\nUndergraduate and graduate students should find that this book supplements their studies in the theoretical\nconcepts of cryptography with practical applications.\n\nSoftware Engineers and Architects designing and building security solutions using the Thales brand of\nHSM will learn concepts and patterns of key management that can be applied to their designs\n\n## Book Organisation\n\nChapter 1, Introduction describes the role fulfilled by a HSM. The Thales series of HSM's are then\nintroduced with a short history of their evolution. Finally, an open source Thales Simulator project is\npresented, with hands on exercises for the reader to install the Simulator and then connect to it from Java,\nC#, and ruby clients.\n\nChapter 2, Theory covers the cryptography basics, different types of cryptographic functions and algorithms. \nThat chapter includes the basic information of encryption and message authentication functions used in cryptography.\nTODO finish about Chapter 2\n\nChapter 3, HSM Local Master Keys (LMKs) covers in detail the concept of the LMKs. The knowledge\ngained in this chapter is fundamental to your understanding of the Thales HSM. Almost all other chapters\ndepend on you understanding the material covered in this chapter. This chapter concludes with exercise\nwith the Thales Simulator to help instil the concepts of LMKs in the reader's mind.\n\nChapter 4, Key Concepts describes general key concepts that you need to know in addition to the material\ncovered in the previous chapter about LMKs. The knowledge in this chapter is of vital importance when\ninteracting with the Thales HSM. Exercises are provided with the Thales Simulator to put the concepts\nlearnt in this chapter into practise.\n\nChapter 5, Secure Key Exchange two sites that are secured with HSMs need to have a set of keys that are\nshared between the HSMs. This chapter describes how keys are created and shared. Exercises are given\nto setup two demo sites with the Thales Simulator and generate and share keys between the demo sites.\n\nChapter 6, Dynamic Key Exchange \n\nTODO describe other chapters\n\n# Introduction\n\n## Overview\n\nA primary role of a HSM is the secure management of digital keys. This document describes digital key\nmanagement concepts, and also describes some key management patterns for solving specific problems.\n\nOther acronyms for Hardware Security Modules include:\n\n- *HSM* : Hardware Security Module / Host Security Module\n- *TRSM* : Tamper Resistant Security Module\n- *SCD* : Secure Cryptographic Devices\n\nTODO: Why digital key management? Life without an HSM?\nThe primary need of HSM is to protect Digital keys from hackers who may have access to Servers/Sytems which stores Digital keys.\nThe conventional method of protecting Digital keys with passphrase has limitations, due to nature of passphrase we have to provide a passphrase for every iteration, which will break automation and passphrase is not secure enough due many reasons like weak md5 hashing algorithm and possibility of brute force attack.\n\n\nTODO: Thales Simulator project overview.\n\n## Thales HSM History and Versions\n\nTODO provide a brief history of Thales HSMs and an overview of current HSM versions.\n\n## Thales HSM interaction\n\nThere are two usage patterns for interacting with the HSM:\n\n\n \n\n\n### Console Commands\n\nConsole commands fall into the categories:\n\n- HSM Configuration\n- Fraud Detection\n- Diagnostic\n- LMK\n- HSM Authorization\n- Logging\n- Key Management\n- Payment System\n- Smartcard\n- Secure Host Communications\n\n### Host Commands\n\nHost commands fall into the categories:\n\n- Symmetric Key Management\n- PIN management\n- MAC and HMAC \n- Message Encryption \n- User Storage \n- Print Output Formatting\n- LMK Translation \n- Auditing \n- Card Verification Code/Value \n- EMV Chip Card \n- Racal Transaction Key Scheme (RTKS) \n- Derived Unique Key Per Transaction (DUKPT)(X9.24-1) \n- RSA Cryptosystem \n\n# Theory\n\nTODO introduction to this section\n\n## Bits, Bytes and Hex\n\nTODO write some information on bits, bytes and hex representation of data\n\n## Cryptographic functions\n\nCryptographic functions fall into two main classes called *encryption* and *message authentication functions*. \n\nEncryption functions are used to transmit data securely. Encryption functions are two way functions and have both encryption and decryption algorithms. The sender encrypts the message to be sent with the encryption algorithm and the cryptographic key. After receiving the encrypted data the recipient uses a decryption algorithm and cryptographic key to decrypt the encrypted data received:\n\n\n\nAuthentication functions are used to ensure that the message was not modified during transmission. The message authentication function result is not reversible. The sender calculates a check sum of the message and sends it together with plaintext or encrypted message. The sender, using the same message authentication algorithm can verify the check sum received together with the message. If the check sum is valid, the receiver can be sure that the message was not modified during transmission:\n\n\n\n### Encryption functions\n\nEncryption functions are divided into two classes, *symmetric* and *asymmetric*. \n\nSymmetric encryption algorithms uses the same key for both encryption of plaintext data and decryption of ciphertext. Usually, the decryption algorithm is completely reversed encryption algorithm. The symmetric encryption 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 be split into blocks of the required length before encryption, it has to be padded with additional bytes to meet the required length. \n\nSome of the most commonly used symmetric algorithms are: \n- Data Encryption Standard (DES / 3DES)\n- Advanced Encryption Standard (AES)\n- Blowfish\n- Twofish\n\n\n\nAsymmetric, also known as public-key algorithms use different keys (key pairs) for data encryption and decryption, these are called the private key and public key. Both the private and public keys are mathematically linked. The asymmetric encryption and decryption algorithms are also different. Before communication the receiver generates the pair of keys and keeps private key secret. The public key is distributed with other parties involved in data exchange. The public key used to encrypt data can't be used to decrypt it. Data can only be decrypted with the private key.\n\nSome of the most commonly used asymmetric algorithms are:\n- Rivest Shamir Adleman (RSA)\n- Diffie-Hellman\n- Digital Signature Algorithm (DSA)\n- ElGamal\n- Elliptic Curve Cipher (ECC)\n\n\n\nSymmetric algorithm are generally faster and more secure for a given length of key than an Asymmetric algorithm, hence it should be used for encrypting traffic between client and server and disk data. On the other hand, Asymmetric algorithm provides means of identifaction and provides proof to communication party and hence it's used for exchanging a secret key with untrusted party and also digitally sign the documents. In real world scenario, both are often used together. An asymmetric algorithm is used to confirm the identity of a communication party and to transmit secret keys that will result in a symmetric key and then later used for encryption of the actual data.\n\n### Message authentication functions\n\nAuthentication functions are divided into 2 classes, *hash* and *MAC*.\n\nHash functions are message authentication functions which produce a fixed length output sum (hash) of variable length input data. The hash functions do not use the encryption functions to produce hashes. Usually in cryptography, hash functions are applied on plain text messages before encryption, so that secrets are not used to produce a hash of the message. Attackers can generate the hashes free for modified messages, because of that no reason to use hash functions on encrypted messages or on plaintext messages without encryption of them.\n\nSome of the most commonly used hash functions:\n- MD5\n- SHA-1\n- SHA-2\n\n\n\nMAC functions also called keyed hash functions are cryptographic based message authentication functions to produce the short output check sum over the message used to ensure, that the message was not modified during transmission. In contrast to hash functions, MACs are generated using cryptographic algorithms and secret keys. The MAC can be securely applied to plain text messages without message encryption because it uses cryptographic keys to produce MAC.\n\nThe most commonly used MAC algorithms are defined in ISO-9797 standard.\n\nTODO - can we list some of the algorithms?\n\n\n\nTODO - brief paragraph to say when to use hash and when to use mac?\n\n## Padding\n\nTODO - Introduction to paddings\n\n### Symmetric block cipher paddings\n\nIn a case of symmetric block ciphers, padding is used to complete the message till the full block length. For example, if the message to be encrypted with DES algorithm has only 31 byte of data, it must be filled with additional 1 byte to be 32 bytes long, since DES algorithm needs 8 bytes of input plaintext data. \n\n#### PKCS#5 padding\n\nPKCS#5 padding is the most common type of padding applied to message during encryption. The padding must be removed from message after decryption to restore the original message content. PKCS#5 padding fills message with bytes with padding length as value. If message meets length requirements, additional full block of padding must be added to the end of message.\n\nThe example of PKCS#5 padding for incomplete message:\n\n\n\nThe example of PKCS#5 padding for complete 8 byte message:\n\n\n\nThe example of PKCS#5 padding on Java:\n\n```java\n/* \n * since different symmetric algorithms have different input data block sizes\n * the blockSize variable is passed to the methods\n */\n\npublic static byte[] pkcs5Pad(byte[] block, int blockSize) {\n\tint padLen = blockSize - block.length % blockSize;\n\tif (padLen == 0) {\n\t\tpadLen = blockSize;\n\t}\n\tint padVal = (byte)padLen;\n\tbyte[] paddedBlock = new byte[block.length + padLen];\n\tSystem.arraycopy(block, 0, paddedBlock, 0, block.length);\n\tfor (int k = 0; k < padLen; k++) {\n\t\tpaddedBlock[(block.length + k)] = (byte)padVal;\n\t}\n\treturn paddedBlock;\n}\n\npublic static byte[] pkcs5Unpad(byte[] paddedBlock) {\n\tint padLen = paddedBlock[(paddedBlock.length - 1)];\n\tint plainLen = paddedBlock.length - padLen;\n\tbyte[] plainBlock = new byte[plainLen];\n\tSystem.arraycopy(paddedBlock, 0, plainBlock, 0, plainLen);\n\treturn plainBLock;\n} \n```\n\n#### ISO-9797 Method 1 padding\n\nISO-9797 Method One padding is used for message MACing. This method adds zero bytes to the end of message until it meets the length requirements. It is not necessary to add an additional block of padding if a message meets length requirements. Method One padding can not be used for message encryption because it is impossible to differentiate padding bytes from the message content. \n\n\n\nThe example of ISO-9797 Method 1 padding on Java:\n\n```java\n/* \n * since different symmetric algorithms have different input data block sizes\n * the blockSize variable is passed to the methods\n */\n \npublic static byte[] iso9797Method1Pad (byte[] block, int blockSize) {\n\tint padLen = blockSize - block.length % blockSize;\n\tif (padLen == blockSize) {\n\t\tpadLen = 0;\n\t}\n\tbyte[] paddedBlock = new byte[block.length + padLen];\n\tSystem.arraycopy(block, 0, paddedBlock, 0, block.length);\n\treturn paddedBlock;\n}\n```\n\n#### ISO-9797 Method 2 padding\n\nISO-9797 Method Two padding is used for message padding for MAC calculation, but it can be used, also, for message encryption. The padding applied to the message adds one byte with value 0x80 (a singe bit with value 1) and, if necessary, adds zero bytes until the message meets length requirements. If that padding method is used for message MACing, it is not necessary to add additional block of padding if message is complete, but in a case of message encryption it must be.\n\nExample of ISO9797 Method 2 padding for incomplete message\n\n\n\nExample of ISO9797 Method 2 padding for complete message\n\n\n\nThe example of ISO-9797 Method 2 padding on Java:\n\n```java\n/* \n * since different symmetric algorithms have different input data block sizes\n * the blockSize variable is passed to the methods\n */\n \npublic static byte[] iso9797Method2Pad (byte[] block, int blockSize, boolean forMacing) {\n\tint padLen = blockSize - block.length % blockSize;\n\t// if padding is used for MACing, we do not need to add additional block\n\t// in a case of complete message length (multiple of blockSize)\n\tif (forMacing && padLen == blockSize) {\t\n\t\tpadLen = 0;\n\t}\n\tbyte[] paddedBlock = new byte[block.length + padLen];\n\tSystem.arraycopy(block, 0, paddedBlock, 0, block.length);\n\tif (padLen != 0) {\n\t\tpaddedBlock[block.length] = (byte)0x80;\n\t}\n\treturn paddedBlock;\n}\n\npublic static byte[] iso9797Method2Unpad (byte[] paddedMsg) {\n\tint padIdx = 0;\n\tfor (int i = paddedMsg.length - 1; i > 0; i--) {\n\t\tif (paddedMsg[i] == (byte)0x80) {\n\t\t\tpadIdx = i;\n\t\t}\n\t}\n\tbyte[] message = new byte[paddedMsg.length - padIdx];\n\tSystem.arraycopy(paddedMsg, 0, message, 0, message.length);\n\treturn message;\n}\n```\n\n### Asymmetric cipher paddings\n\nIn the most cases asymmetric cipher paddings are used to randomise the output. Usually, asymmetric paddings have fixed length and is placed in plaintext message in the predefined position.\n\n#### PKCS#1 v1.5 padding\n\nPKCS#1 v1.5 padding is used to randomise the ciphertext output during RSA encryption to avoid some types of attacks. The message length to be encrypted using RSA-PKCS#1 scheme must meet the condition ```mLen <= k - 11```, where ```mLen``` is plaintext message length and ```k``` is the public key length. The padding must be at least 11 bytes long and contain at least 8 non-zero random bytes. The scheme below shows the padding structure:\n\n\n\nWhen the ciphertext is decrypted, the padding structure must be validated. In a case of structure mismatch the error should be returned. The conditions of valid padding are:\n\n- 1st byte must be 0x00;\n- 2nd byte must be 0x02;\n- Encrypted message must have a byte with value 0x00 separating random byte octet from message;\n- Random byte octet must be at least 8 non-zero bytes long.\n\nThe example of PKCS#1 v1.5 padding on Java:\n\n```java\n/*\n * The example below adds PKCS#1 padding of length to make message the same \n * size as pubic key.\n */\n \npublic static byte[] pkcs1Pad (byte[] message, int keyLen) {\n\tjava.util.Random r = new java.util.Random();\n\tint padLen = keyLen - message.length - 3;\n\tbyte[] rand = new byte[padLen];\n\tbyte[] paddedMsg = new byte[message.length + padLen + 3];\n\tpaddedMsg[0] = (byte)0x00;\n\tpaddedMsg[1] = (byte)0x02;\n\tpaddedMsg[padLen + 2] = (byte)0x00;\n\tint n = 0;\n\tfor (int i = 0; i < padLen; i++) {\n\t\tn = r.nextInt(256);\n\t\tif (n == 0) {\n\t\t\ti--;\n\t\t\tcontinue;\n\t\t}\n\t\trand[i] = (byte)n;\n\t}\n\tSystem.arraycopy(rand, 0, paddedMsg, 2, rand.length);\n\tSystem.arraycopy(message, 0, paddedMsg, padLen + 3, message.length);\n\treturn paddedMsg;\n}\n\npublic static byte[] pkcs1Unpad (byte[] paddedMsg) \n\t\tthrows javax.crypto.BadPaddingException {\n\tint sepIdx = new String(paddedMsg).indexOf(\"\\0\", 1);\n\tif (paddedMsg[0] != (byte)0x00 || \n\t\t\tpaddedMsg[1] != (byte)0x02 || \n\t\t\tsepIdx == -1 || \n\t\t\tsepIdx < 10) {\n\t\tthrow new javax.crypto.BadPaddingException(\"Padding does not meet required conditions\");\n\t}\n\tbyte[] message = new byte[paddedMsg.length - sepIdx - 1];\n\tSystem.arraycopy(paddedMsg, sepIdx + 1, message, 0, message.length);\n\treturn message;\n}\n```\n\n#### PKCS#1 OAEP padding\n\nPKCS#1 OAEP (Optimal Asymmetric Encryption Padding) padding is used to randomise the ciphertext output during RSA encryption to avoid some types of attacks. The message length to be encrypted using RSA-OAEP scheme must meet the condition ```mLen <= k - 2hLen - 2```, where ```mLen``` is plaintext message length, ```k``` is a public key length, ```hLen``` is the length of hash function output. \n\nTODO - to finish.\n\n## Exercises\n\n### Asymmetric cipher paddings\n1) To verify the PKCS#1 v1.5 padding the following Java code can be used:\n\n```java\nimport java.security.KeyPair;\nimport java.security.KeyPairGenerator;\nimport java.security.PrivateKey;\nimport java.security.PublicKey;\nimport javax.crypto.Cipher;\n\npublic class RSAPaddingTest {\n\t\n\tprivate static String byte2hex(byte bs[]) {\n\t\t// refer to Appendix A for that method code\n\t}\n\t\n\t/*\n\t * Method generates the private and public RSA key pair\n\t */\n\n\tprivate static KeyPair generateKeyPair (int keyLen) throws Exception {\n\t\tKeyPairGenerator kpg = KeyPairGenerator.getInstance(\"RSA\");\n\t\tkpg.initialize(keyLen);\n\t\tKeyPair kp = kpg.genKeyPair();\n\t\treturn kp;\n\t}\n\t\n\t/*\n\t * Method encrypts passed message with RSA public key applying \n\t * PKCS1Padding to plaintext message\n\t */\n\t\n\tprivate static byte[] encrypt (String msg, PublicKey publicKey) throws Exception {\n\t\tCipher cipher = Cipher.getInstance(\"RSA/ECB/PKCS1Padding\");\n\t\tcipher.init(Cipher.ENCRYPT_MODE, publicKey);\n\t\tbyte[] ciphMsg = cipher.doFinal(msg.getBytes());\n\t\treturn ciphMsg;\n\t}\n\t\n\t/*\n\t * Method decrypts passed cipher text with RSA private key and do not remove\n\t * padding from plaintext message\n\t */\n\t\n\tprivate static byte[] decrypt (byte[] ciphMsg, PrivateKey privateKey) throws Exception {\n\t\tCipher cipher = Cipher.getInstance(\"RSA/ECB/NoPadding\");\n\t\tcipher.init(Cipher.DECRYPT_MODE, privateKey);\n\t\tbyte[] plainMsg = cipher.doFinal(ciphMsg);\n\t\treturn plainMsg;\n\t}\n\t\n\tpublic static void main (String[] args) {\n\t\tString msg = args[0];\n\t\tint keyLen = Integer.parseInt(args[1]);\n\t\ttry {\n\t\t\tKeyPair kp = generateKeyPair(keyLen);\n\t\t\tPublicKey publicKey = kp.getPublic();\n\t\t\tPrivateKey privateKey = kp.getPrivate();\n\t\t\tbyte[] ciphMsg = encrypt(msg, publicKey);\n\t\t\tbyte[] plainMsg = decrypt(ciphMsg, privateKey);\n\t\t\tSystem.out.println(byte2hex(plainMsg));\n\t\t} catch (Exception e) {\n\t\t\te.printStackTrace();\n\t\t}\n\t}\n}\n```\n\nThe code above can be compiled with command:\n\n```javac RSAPaddingTest.java```\n\nRun with command:\n\n```java RSAPaddingTest ```\n\nThe output will be as follows:\n\n```\n$ java JavaRSA 34234234234 512\n0002570D03777D36E4B335597EFCDB68FA076D6B7DFD210B727C9A088D351D52846185F9C03826B35062C1EFB3644C190BE6DDC2003334323334323334323334\n```\n\nThe output abve shows, that Java adds a random byte PKCS#1 padding to message making it the same length as a public key. In the example public key (modulo) is 512 bits long.\n\n- ```00``` - 1st byte is ```0x00```\n- ```02``` - 2nd byte is ```0x02```\n- ```570D03777D36E4B335597EFCDB68FA076D6B7DFD210B727C9A088D351D52846185F9C03826B35062C1EFB3644C190BE6DDC2``` - random bytes (50)\n- ```00``` - padding separator, ```0x00```;\n- ```3334323334323334323334``` - plaintext message\n\n# Introduction to the Thales Simulator\n\n## Thales Simulator Exercises\n\nThis section provides some exercises to get hands on experience using the Thales Simulator.\n\n### Setting up the Thales Simulator\n\nIn this exercise, you will download, install and run the Thales Simulator on a Windows machine. The purpose of this exercise is to get the Thales Simulator setup and ready for use in later chapters.\n\n#### Download and Install the Thales Simulator\n\n 1. Download ```ThalesSim.Setup.0.9.6.x86.zip``` from: [http://thalessim.codeplex.com/releases/view/88576](http://thalessim.codeplex.com/releases/view/88576)\n 2. Unzip the downloaded file and execute the file ```ThalesWinSimulatorSetup.msi```, accepting the default options.\n \n#### Starting the Thales Simulator\n\n 1. Navigate to the folder where you installed the Simulator (E.g. ```C:\\Program Files (x86)\\NTG\\Thales Simulator\\```)\n 2. Execute ThalesWinSimulator.exe (if your are running Windows 7, right click the file and select Run As Administrator)\n 3. Click the Start Simulator button: \n 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. \n\n\n#### Using the Simulator Console\n\nIn this section, we will connect to the HSM Console and run a basic command, Query Host (QH) to test connectivity to the HSM.\n\nFor a full list of console commands, you will need to refer to the *Console Reference Manual* which is available from Thales.\n\nNote: The Thales Simulator only implements a subset of the commands. A list of implemented console commands can be found [here](http://thalessim.codeplex.com/wikipage?title=list%20of%20supported%20console%20commands).\n\n##### Connecting with the Simulator Console\n\nIn this section, we ... TODO describe what we are doing here\n\n 1. Start the simulator as described in [Starting the Thales Simulator](./book.md#starting-the-thales-simulator)\n 2. Click The Console button \n 3. In the console window click *Connect to Console*.\n 4. Enter the *console* command ```QH``` followed by ENTER. \n 5. You should see something similar to this \n \nIn this exercise, we executed a console command ```QH``` against the simulator and observed the response that was displayed by the simulator.\n\n##### Connecting with a Python Client\n\nSee Appendix (TODO) to see instructions for:\n- installing python\n- running python code\n\n```python\nimport binascii\nimport socket\nimport sys\n\n# open a connection to the Thales Simulator\nsock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\nserver_address = ('localhost', 9998)\nsock.connect(server_address)\n\n# the command we need to send\ncommand = b'0006303030304e43'\n\n# convert the hex string to binary\ncommand = binascii.a2b_hex(command)\n\n# send a command\nsock.send(command)\n\n# receive the command response\nrecv_data = sock.recv(1024)\n\n# printout response\nsys.stdout.buffer.write(recv_data)\n\n# close the connection\nsock.close()\n```\n\nThe code simply opens a TCP connection to a Thales Simulator listening on ```localhost``` on port ```9998```. Next the python client converts the string ```0006303030304e43``` from its hexidecimal format to binary and sends it to the Thales Simulator. Finally the code receives the response and prints it to standard output.\n\nTo understand the meaning of the string ```0006303030304e43```, it can be broken down as follows (in reverse order):\n\n- ```4e43``` is the 2 byte command ```NC``` as hex\n- ```30303030``` adds a 4 byte header ```0000``` as hex\n- ```0006``` represents the length in hex of the command and header (i.e. the length of ```0000NC```)\n\nThe command should output a response similar to the following:\n\n```\n !0000ND007B44AC1DDEE2A94B0007-E000\n```\n\nThe response from HSM can be broken down as follows:\n\n- ```!``` actually is ```0021```, it is software header returned by HSM, actual response length\n- ```0000``` is HSM response header which is set the same as for received command\n- ```ND``` the response code. The response from HSM always is command code with incremented second letter\n- ```00``` error code, ```00``` means that no errors occurred during command processing\n- ```7B44AC1DDEE2A94B``` Local Master Key (see corresponding chapter) check value\n- ```0007-E000``` means the HSM firmware revision number\n\nEach command has its own response specification, see \"Host command reference manual\" for more details.\n\n# HSM Local Master Keys (LMKs)\n\nLocal Master Keys (LMKs) are a central concept for HSMs. This section describes LMKs in more detail.\n\n## LMK Overview\n\nLocal Master Keys are a sets of 40 DES keys. They are stored securely in the HSM making it very difficult for an attacker to gain access to them. LMKs are the only keys that are stored in the HSM.\n\nLMKs are not used for encrypting data, but are instead used to encrypt and decrypt other keys as these\nenter or leave the HSM. LMKs are used to ensure that even if the data traffic between the HSM and an\napplication is recorded, the clear values of any exchanged keys are not compromised.\n\nLMKs come in pairs and the Thales HSM contains several LMK pairs. Different LMK pairs are used to\nencrypt/decrypt different types of security keys. LMK pairs are identified by two numbers, for example\nLMK pair 04-05, LMK pair 14-15, etc. See the diagram below.\n\n\n\nEach LMK pair is assigned a code. LMK pair 04-05 is assigned code 00, while LMK pair 14-15 is assigned\ncode 02. The full list of HSM key pairs are listed in Table 2.1, “LMK Key Pairs”, below. Note that HSM\nkey pairs do not start at 00-01, instead the numbering starts at 04-05, and runs non-contiguously to 38-39.\n\n| Key Pair | Code |\n|-----------|-------|\n| 04-05 | 00 |\n| 06-07 | 01 |\n| 14-15 | 02 |\n| 16-17 | 03 |\n| 18-19 | 04 |\n| 20-21 | 05 |\n| 22-23 | 06 |\n| 24-25 | 07 |\n| 26-27 | 08 |\n| 28-26 | 09 |\n| 30-31 | 10 |\n| 32-33 | 11 |\n| 34-35 | 12 |\n| 36-37 | 13 |\n| 38-39 | 14 |\n\nEach 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 depends upon them.\n\n## LMK Variants\n\nBack when the HSM had only a handful of LMK pairs, more than the type of keys that had to be encrypted, a way had to be found to ensure that different key types can be used but also provide a way to identify parity errors with these key types. Variants are an easy way to pseudo-multiply your LMK pairs. (TODO validate this)\n\nKeys are encrypted under LMK pairs using either the clear value of the LMK or a variant of the LMK. An LMK variant is created by performing a XOR operation with a value on the LMK key. For example, variant 1 of an LMK is created by XORing the LMK with the value 000000000000000000000000000000A6. The Thales HSM supports 10 variants for each LMK pair, with variant 0 being the clear LMK itself. The full list of variant calculation functions can be seen in the Table below.\n\n\n\n| Variant number | Variant Calculation Function - XOR LMK with: |\n|---------|--------------------------------------------|\n| 0 | Not applicable - use clear value of LMK |\n| 1 | 000000000000000000000000000000A6 |\n| 2 | 0000000000000000000000000000005A |\n| 3 | 0000000000000000000000000000006A |\n| 4 | 000000000000000000000000000000DE |\n| 5 | 0000000000000000000000000000002B |\n| 6 | 00000000000000000000000000000050 |\n| 7 | 00000000000000000000000000000074 |\n| 8 | 0000000000000000000000000000009C |\n| 9 | 000000000000000000000000000000FA |\n\n## Exercises\n\nTODO - what exercises could be performed on the Simulator around LMK Concepts? Could we walk through the default keys with the HSM simulator and how to change those keys?\n\n# Key Concepts\n\n## Key Types\n\nEach different key supported by the Thales HSM has a unique code called the key type code. The key type is a three-digit number and is made up from the code of the LMK pair and the LMK variant. Therefore, keys encrypted under LMK pair 04-05 using a variant 1 will have a key type equal to “00” + “1” = 001. It is important to understand key types since several Thales commands expect key type codes as parameters. The full list of key types can be seen in the table below.\n\n| LMK Key Pair | LMK Code | Variant | Key Type Code | Key Type |\n|--------------|----------|---------|---------------|---------------|\n| 04-05 | 00 | 0 | 000 | ZMK |\n| 06-07 | 01 | 0 | 001 | ZPK |\n| 14-15 | 02 | 0 | 002 | PVK, TMK, TPK |\n| 14-15 | 02 | 4 | 402 | CVK, CSCK |\n| 16-17 | 03 | 0 | 003 | TAK |\n| 22-23 | 06 | 0 | 006 | WWK |\n| 26-27 | 08 | 0 | 008 | ZAK |\n| 28-29 | 09 | 0 | 009 | BDK1 |\n| 28-29 | 09 | 1 | 109 | MK-AC |\n| 28-29 | 09 | 2 | 209 | MK-SMI |\n| 28-29 | 09 | 3 | 309 | MK-SMC |\n| 28-29 | 09 | 4 | 409 | MK-DAC |\n| 28-29 | 09 | 5 | 509 | MK-DN |\n| 28-29 | 09 | 6 | 609 | BDK2 |\n| 28-29 | 09 | 7 | 709 | MK-CVC3 |\n| 28-29 | 09 | 8 | 809 | BDK3 |\n| 30-31 | 0A | 0 | 00A | ZEK |\n| 32-33 | 0B | 0 | 00B | DEK |\n| 32-33 | 0B | 3 | 30B | TEK |\n\nIn the latest payShield9000 and HSM8000 firmwares Thales has introduced second, PCI-HSM standard compliant, key type table with the changes around 002 key type - PVK, TMK, TPK. The changes moves TMK and TPK to different LMK pair and Variants leaving PVK the only key of 002 type:\n\n| LMK Key Pair | LMK Code | Variant | Key Type Code | Key Type |\n|--------------|----------|---------|---------------|---------------|\n| 14-15 | 02 | 0 | 002 | PVK |\n| 36-37 | 0D | 7 | 70D | TPK |\n| 36-37 | 0D | 8 | 80D | TMK |\n\n## Key Check Value\n\nThe check value of a key is derived by DES encrypting 16 zeroes (8 zero bytes) using that key. For example, the KCV for key 0123456789ABCDEF is D5D44FF720683D0D\n\nThe purpose of a KCV is to ensure that a key has been correctly transmitted between different parties and that they key is also configured correctly in systems. It is common practice to transmit the KCV of a key along with the key itself. Sometimes, the complete result of the DES encrypt operation is used, but typically only the first six digits are used (in the example, D5D44F).\n\n## Key Formats\n\nThe Thales HSM uses two major formats when processing security keys. These are Variant and ANSI.\n\nThe variant concept is similar to the one used to form LMK variants: a key is XORed with a value to form the key variant. Double-length keys are XORed with the value:\n\n```text\n00000000000000A6 000000000000005A\n```\n\nand triple-length keys are XORed with the value:\n\n```text\n00000000000000A6 000000000000005A 000000000000006A\n```\n\nTODO: how does the variant concept differ to the LMK variant concept?\n\nThe ANSI format is much simpler: a key is used as-is without performing any additional operations on it.\n\n## Key Scheme\n\nDepending on their length and key format, keys are designated by a key scheme that helps to quickly identify the nature of a key. Key schemes are the following:\n\n| Key Scheme | Description |\n|------------|-------------|\n| Z | Single-length ANSI keys |\n| U | Double-length variant keys |\n| T | Triple-length variant keys |\n| X | Double-length ANSI keys |\n| Y | Triple-length ANSI keys| \n\n## Exercises\n\nTODO - what exercises could be performed on the Simulator around LMK Concepts?\n\n# Secure Key Exchange\n\n## Overview\n\nTo securely exchange information between two users using the DES encryption scheme, it is vital to securely share a set of initial keys. This role is fulfilled by the Zone Master Keys. Unlike an LMK which does not leave the HSM, ZMKs are intended to be shared between sites to create secure Zones. The ZMK is distributed manually between the sites. The ZMK allow future (data encrypting) keys to be automatically shared between sites by encrypting those future keys with the ZMK. In that regard, they work very much like the LMKs with the important exception that they can be shared between users.\n\nZMKs have a key type code of 000 (they are encrypted under LMK pair 04-05 with a variant of 0).\n\nTODO diagram\n\nThe transfer of the ZMK between sites is performed manually. The ZMK is shared in parts (components) so that no one person will see the key.\n\nTODO diagram\n\nThe data encryption key is a Zone PIN Key (ZPK). The ZPK was historically used to encrypt PINs for transfer between sites (e.g. between Acquirer and Issuer).\n\nFor local storage (e.g. on the application server using the ZMK), the ZMK is encrypted under one of the LMK keys.\n\n## Example - Secure Key Exchange\n\nTwo parties want to exchange a ZMK. One party generates a random ZMK using three clear components which are the following:\n\n```text\n2CBF0D8FA4E66ECE 6B239E25B9BAD934\nB60825E3790D31CE 4A4AA74397461C13\n29BFE3C1D0C1E50B CD7038A42CFB160B\n```\n\nTODO: describe what is meant by clear components\n\nEach of these clear components are kept by a separate custodian that works for the first party and are delivered to different custodians of the second party. To create the complete ZMK, each custodian enters their component to the HSM which combines them to form the ZMK. Most typically, the clear components are simply XORed to form the ZMK. In the example, the ZMK value is:\n\n```text\nB308CBAD0D2ABA0B EC1901C20207D32C\n```\n\nWhen generating the ZMK, the first party also gives the KCV of the ZMK to the second party (for the example key the KCV is 6CE4CF). That way, the second party can verify the correct reception and data entry of the ZMK components.\n\nTODO: See “Exercise – Creating a ZMK” for hands on experience creating a ZMK.\n\n## Exercises\n\n### Creating a Zone Master Key (ZMK)\n\nIn this exercise, we create a Zone Master Key (ZMK) using console commands.\n\nThe ZMK is distributed manually as components. To create the ZMK, we first create three ZMK components.\n\n#### Generate the ZMK Components\n\nGenerate three ZMK components using the console command Generate Component (GC). Repeat the command three times as shown below:\n\n```text\nGC # User input\nKey length [1,2,3]: 2 # User input\nKey Type: 000 # User input\nKey Scheme: U # User input\nClear Component: 79CD 2380 9B4F C1C4 7F9E FB2A DF2A 674A\nEncrypted Component: U 1BA5 185A FCF1 5A1B 274B E1E0 03B4 7C2A\nKey check value: 7A5B C7\nGC # User input\nKey length [1,2,3]: 2 # User input\nKey Type: 000 # User input\nKey Scheme: U # User input\nClear Component: 0157 B3DF 6116 3402 372C 54FD 62F2 1C91\nEncrypted Component: U FCE4 7AF7 FFF8 9F40 2407 A35A F063 D3E1\nKey check value: 1E79 CB\nGC # User input\nKey length [1,2,3]: 2 # User input\nKey Type: 000 # User input\nKey Scheme: U # User input\nClear Component: 7AEA B5A4 1A9E 9B68 EF80 494C 0819 4ADA\nEncrypted Component: U EE8D 4F9E C8B2 ADF4 9CD2 F0D2 7F5C 95C5\nKey check value: 277A 5F\n```\n\n##### Description\n\nWe are generating a *Double-length* key, so we choose a Key Length of *2*. See [Key Schemes](#key-scheme) for a list of the key schemes.\n\nWe are generating *ZMK* keys, so we use the Key Type *000*. See [Key Types](#key-types) for a list of the key types.\n\nWe are generating a *Double-length variant key*, which has a Key Scheme of *U*. See [Key Schemes](#key-scheme) for a list of the key schemes.\n\nTODO: refer to a section that describes how to decide which scheme and type of key is most suitable for your particular encryption requirements? E.g. why have we chosen *Double-length variant key* and not *Single-length ANSI keys* for this example?\n\n#### Generate the ZMK from the components\n\nThis step uses the FK command to generate the ZMK from the three ZMK components previously generated:\n\nTODO: describe the various command options and how to choose which option values to use.\n\n```text\nFK # User input\nKey length [1,2,3]: 2 # User input\nKey Type: 000 # User input\nKey Scheme: U # User input\nComponent type [X,H,E,S]: E # User input\nEnter number of components (2-9): 3 # User input\nEnter component #1: 1BA5185AFCF15A1B274BE1E003B47C2A # User input from GC response: U 1BA5 185A FCF1 5A1B 274B E1E0 03B4 7C2A\nEnter component #2: FCE47AF7FFF89F402407A35AF063D3E1 # User input from GC response: U FCE4 7AF7 FFF8 9F40 2407 A35A F063 D3E1\nEnter component #3: EE8D4F9EC8B2ADF49CD2F0D27F5C95C5 # User input from GC response: U EE8D 4F9E C8B2 ADF4 9CD2 F0D2 7F5C 95C5\nEncrypted key: U 104C 4216 A751 FEEE FF55 698B 26C5 7789\nKey check value: BA0F C3\n```\n\nThe description of the Key length, Key Type and Key Scheme values are described in the Description for [Generate the ZMK Components](#generate-the-zmk-components).\n\nThe Component type is either:\n\n- X = XORed clear components. The universal way and the most commonly used, to exchange the keys between different parties.\n- H = Clear Half or Third Key (key split 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.\n- E = Components encrypted under LMK. HSM first decrypts the components and XORs decrypted components. Such components can be used only locally since 3rd parties do not have an access to component encryption LMK pair. This is the way to store keys in components in secure manner. \n- S = Components stored on smartcards. Can only be used to exchange keys between Thales HSMs.\n\n**Import the ZMK from the Components**\n\nThe ZMK is exchanged using secured methods and Split knowledge policy. Where three components that created above are sent to three nominated Security Officers of the other party. This is one of the most secure way to do it since no single person gains knowledge of the clear ZMK.\n\nIf you are at receiving end then you need to import ZMK into your HSM to decrypt the lower level key like ZPK in future.\n\n```text\nFK # User input\nKey length [1,2,3]: 2 # User input\nKey Type: 000 # User input\nKey Scheme: U # User input\nComponent type [X,H,E,S]: X # User input\nEnter number of components (2-9): 3 # User input\nEnter component #1: 79CD23809B4FC1C47F9EFB2ADF2A674A # User input from GC response: 79CD 2380 9B4F C1C4 7F9E FB2A DF2A 674A\nEnter component #2: 0157B3DF61163402372C54FD62F21C91 # User input from GC response: 0157 B3DF 6116 3402 372C 54FD 62F2 1C91\nEnter component #3: 7AEAB5A41A9E9B68EF80494C08194ADA # User input from GC response: 7AEA B5A4 1A9E 9B68 EF80 494C 0819 4ADA\nEncrypted key: U 104C 4216 A751 FEEE FF55 698B 26C5 7789\nKey check value: BA0F C3\n``` \n \n# Dynamic Key Exchange\n\n## Overview\n\nTODO: Why dynamic key exchange?\n\n## Zone PIN Key (ZPK)\n\nThe Zone PIN Key (ZPK) is a data encrypting key. It is used to encrypt the data that is transmitted in a security zone. For transfer between sites, the ZPK is encrypted under the ZMK. When stored locally (e.g. on the application server), the ZPK is encrypted using one of the LMK Keys.\n\nZPKs have a key type code of 001 (encrypted under LMK pair 06-07 with a variant of 0).\n\nTODO: See “Exercise – Creating a ZPK” for hands on experience creating a ZPK.\n\n### Example - Dynamic Key Exchange\n\nAssume that the ZMK presented in the previous example has been exchanged between two parties. One party, then, generates a random ZPK equal to:\n\n```text\nADD3B5C7B576D3AE 38B90B7C0EB67A7C, KCV = CB59C0\n```\n\nThe party then encrypts this ZPK under the ZMK to safely transmit this to the other party. The ZPK under the ZMK is:\n\n```text\nC9A62E96ADFB52A7 815BE8D7E730B24E, KCV = CB59C0\n```\n\n## Key Translation\n\nIn our previous example, the value C9A62E96ADFB52A7 815BE8D7E730B24E represents the randomly created ZPK encrypted under the previously created ZMK. But imagine that one of the parties that have exchanged this ZPK needs to transmit it to another party with which they share a different ZMK which we’ll call ZMK2 . To properly transmit the ZPK to the other zone that is secured with ZMK2, the ZPK has to be:\n\n- Decrypted under ZMK.\n- Encrypted under ZMK2.\n\nThis process is called key translation. Key translation does not happen with specific key types as the ZMK that was used in the previous example but is a more general process - for example it is possible to translate a key from encryption under the ZMK to encryption under an LMK.\n\nKey translation always takes place within the HSM to avoid exposing the clear value of the key being translated.\n\n## Translating a ZPK (between ZMK encryption and LMK encryption)\n\nThe HSM provides functionality to translate a ZPK between ZMK and LMK. This is used when a ZPK is received by Site B. In this case, Site A sends the ZPK encrypted with the ZMK to Site B. Site B translates the ZPK to LMK encryption.\n\nThe ZPK under LMK encryption is used for encrypting/decrypting the data sent between the sites.\n\nTODO: insert diagram\n\n### Exercises\n\n#### Creating a Zone PIN Key (ZPK)\n\nIn this exercise, we create a Zone PIN Key (ZPK) using console commands.\n\nWhen prompted for the ZMK, use the encrypted ZMK value from the section called “Creating a Zone Master Key (ZMK)”.\n\n```text\nKG\nKey length [1,2,3]: 2\nKey Type: 001\nKey Scheme (LMK): U\nKey Scheme (ZMK) [ENTER FOR NONE]: X\nEnter encrypted ZMK [ENTER FOR NONE]: U 104C 4216 A751 FEEE FF55 698B 26C5 7789\nEnter ZMK check value [ENTER TO SKIP CV TEST]:\nKey under LMK: U 8586 51EC 83AF CA66 8175 804F 5B7D CD6B\nKey encrypted for transmission: X BAA5 18AA D10D 28A2 D32A 5688 317F 44EB\nKey check value: 6543 F4\n```\n\n# PIN block creation (clear PIN blocks)\n\n# PIN block encryption and security zones. ZPKs and TPKs\n\n# PIN translation\n\n# MACing\n\n# CVV/CVV2/iCVV\n\n# Appendix A - Commonly used code in examples\n\n```java\nprivate static String byte2hex(byte bs[]) {\n\tint i;\n\tString s = new String();\n\tString hex_digits = \"0123456789ABCDEF\";\n\tbyte c;\n\tif (bs == null || bs.length == 0) {\n\t\treturn s;\n\t}\n\tfor (i = 0; i < bs.length; ++i) {\n\t\tc = bs[i];\n\t\ts += hex_digits.charAt((c >> 4) & 0xf);\n\t\ts += hex_digits.charAt(c & 0xf);\n\t}\n\treturn s;\n}\n```\n\n# Appendix B - Some other useful code pieces\n\n# Appendix C - Introductory Books in Cryptography\n- Introduction to Cryptography from GPGTools: https://gpgtools.tenderapp.com/kb/how-to/introduction-to-cryptography\n- Cryptography: An Introduction (3rd Edition) by Nigel Smart: https://www.cs.umd.edu/~waa/414-F11/IntroToCrypto.pdf\n- Cryptography just for beginners: http://www.tutorialspoint.com/cryptography/cryptography_tutorial.pdf\n\n# Appendix - Installing Python\n\nDownload and install the latest version of python from https://www.python.org/download/\n\n# Appendix - Connecting to the HSM using different languages\n\n##### Connecting with a Perl Client\n\nIn this exercise, we execute a host command against the Thales Simulator.\n\nIf you have perl installed, you can run the ```NC``` (Perform diagnostics) host command against the HSM as follows:\n\n```perl\n#!/usr/bin/env perl\nuse IO::Socket::INET; \nmy $sock = new IO::Socket::INET(PeerAddr=>\"localhost:9998\") or die; \n$sock->send(pack \"H*\",\"0006303030304e43\"); \n$sock->recv($data, 1024); print $data;\n```\n\nThe command should output a response similar to the following:\n\n```\n!0000ND007B44AC1DDEE2A94B0007-E000\n```\n\nThe response from HSM can be broken down as follows:\n\n- ```!``` actually is ```0021```, it is software header returned by HSM, actual response length\n- ```0000``` is HSM response header which is set the same as for received command\n- ```ND``` the response code. The response from HSM always is command code with incremented second letter\n- ```00``` error code, ```00``` means that no errors occurred during command processing\n- ```7B44AC1DDEE2A94B``` Local Master Key (see corresponding chapter) check value\n- ```0007-E000``` means the HSM firmware revision number\n\nEach command has its own response specification, see \"Host command reference manual\" for more details.\n\n##### Connecting with a Java Client\n\nIn this session, we connect to the HSM over TCP/IP using Java. When we connect using Java, we can send Host Commands to the HSM.\n\nIn the code example, below, we send the command Perform Diagnostics (NC), and print the response\nto System.out.\n\nFor a full treatment of Host Programming the Thales HSM, refer to the Thales documentation “Host\nProgrammer’s Manual”. For a full list of Host Commands, refer to the Thales documentation “Host\nCommand Reference Manual”\n\n```java\nimport java.io.BufferedOutputStream;\nimport java.io.InputStream;\nimport java.io.OutputStream;\nimport java.net.Socket;\nimport java.nio.ByteBuffer;\npublic class Main {\n\n public static void main(String[] args) throws Exception {\n\n Socket socket = new Socket(\"localhost\", 9998);\n\n String command = \"0006303030304e43\";\n \n // the following line converts the hex command string to a byte array\n byte[] bytes = ByteBuffer.allocate(8).putLong(Long.parseLong(command, 16)).array();\n\n OutputStream out = socket.getOutputStream();\n BufferedOutputStream bufferedOut = new BufferedOutputStream(out, 1024);\n bufferedOut.write(bytes);\n bufferedOut.flush();\n\n InputStream in = socket.getInputStream();\n int result;\n while ((result = in.read()) != -1) {\n System.out.print((char)result);\n }\n socket.close();\n }\n}\n```\nSee the description from [Connecting with a perl client](/book.md#connecting-with-a-perl-client) for the format of the command: ```0006303030304e43```.\n\n##### Connecting with a Unix client\n\nIf you have netcat (nc) installed, you can run a command by using echo convert a hex string to binary and send it to the Thales simulator using netcat.\n\nHere we send the Thales command ```NC``` which asks the Thales Simulator to Perform Diagnostics and return the result:\n\n```\n$ echo -ne '\\x00\\x06\\x30\\x30\\x30\\x30\\x4e\\x43' | nc localhost 9998\n!0000ND007B44AC1DDEE2A94B0007-E000\n```\n\nSee the description from [Connecting with a perl client](/book.md#connecting-with-a-perl-client) for the format of the command: ```0006303030304e43```.\n\n##### Connecting with a PL/SQL client\n\nIf you want to call HSM using PL/SQL you can use the UTL_TCP package as in example procedure below:\n\n```sql\nCREATE OR REPLACE PROCEDURE call_hsm IS \n\n\tv_to_hsm VARCHAR2(255);\n\tn_length NUMBER(2);\n\tv_from_hsm VARCHAR2(255);\n\trw_from_hsm RAW(100);\n\tc utl_tcp.connection;\n\tBEGIN\n\t\tc := utl_tcp.open_connection('192.168.229.1', '9998', NULL, NULL, NULL, NULL, NULL, NULL, 1); \n\t\tv_to_hsm := '0000' || 'NC';\n\t\tv_to_hsm := CHR(0) || CHR(LENGTH(v_to_hsm)) || v_to_hsm;\n\t\tv_from_hsm := utl_tcp.write_text(c, v_to_hsm);\n\t\tn_length := utl_tcp.available(c, 1); \n\t\tn_length := utl_tcp.read_raw(c, rw_from_hsm, 100);\n\t\tSELECT SUBSTR(CAST(rw_from_hsm AS VARCHAR2(255)), 5) \n\t\t\tINTO v_from_hsm \n\t\t\tFROM dual;\n\t\tv_from_hsm := utl_i18n.raw_to_char(v_from_hsm);\n\t\tdbms_output.put_line(v_from_hsm);\n\t\tutl_tcp.close_connection(c);\n\tEND;\n```\n"
},
{
"path": "console_command_use_case.uxf",
"content": "\r\n\r\n 10\r\n \r\n com.umlet.element.Actor\r\n \r\n 150\r\n 40\r\n 100\r\n 120\r\n \r\n HSM Operator\r\n \r\n \r\n \r\n com.umlet.element.custom.Systemborder\r\n \r\n 410\r\n 30\r\n 70\r\n 100\r\n \r\n HSM\r\nConsole\r\n \r\n \r\n \r\n com.umlet.element.Relation\r\n \r\n 200\r\n 30\r\n 230\r\n 70\r\n \r\n console commands>\r\n 210;50;30;50\r\n \r\n \r\n com.umlet.element.Relation\r\n \r\n 450\r\n 50\r\n 100\r\n 50\r\n \r\n \r\n 80;30;30;30\r\n \r\n \r\n com.umlet.element.custom.Systemborder\r\n \r\n 530\r\n 30\r\n 100\r\n 100\r\n \r\n HSM\r\n \r\n \r\n \r\n Text\r\n \r\n 250\r\n 170\r\n 270\r\n 90\r\n \r\n The HSM Operator interacts with the HSM by entering console commands into a console that is attached to the HSM.\r\nelementstyle=wordwrap\r\nfg=blue\r\n \r\n \r\n\r\n"
},
{
"path": "host_command_use_case.uxf",
"content": "\r\n\r\n 10\r\n \r\n com.umlet.element.custom.Systemborder\r\n \r\n 440\r\n 110\r\n 100\r\n 100\r\n \r\n HSM\r\n \r\n \r\n \r\n com.umlet.element.custom.Systemborder\r\n \r\n 60\r\n 110\r\n 100\r\n 100\r\n \r\n Client\r\nApplication\r\nCode\r\n \r\n \r\n \r\n com.umlet.element.Relation\r\n \r\n 130\r\n 110\r\n 330\r\n 70\r\n \r\n host commands>\r\n 310;50;30;50\r\n \r\n \r\n Text\r\n \r\n 170\r\n 240\r\n 260\r\n 90\r\n \r\n Client applications interact with the HSM using host commands that are sent to the HSM over a network connection using either TCP/IP or UDP/IP.\r\nelementstyle=wordwrap\r\nfg=blue\r\n \r\n \r\n\r\n"
}
]