{"id":23902953,"url":"https://github.com/mtumilowicz/cryptography-hsm-workshop","last_synced_at":"2026-02-25T22:04:39.437Z","repository":{"id":110875308,"uuid":"535136785","full_name":"mtumilowicz/cryptography-hsm-workshop","owner":"mtumilowicz","description":"Introduction into pkcs11 and integrations with hsm using softhsm.","archived":false,"fork":false,"pushed_at":"2022-09-27T19:37:04.000Z","size":164,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-15T14:14:11.939Z","etag":null,"topics":["cryptography","cryptography-concepts","cryptography-course","cryptography-tools","hardware-security-module","hsm","pkcs11","pkcs11-tool","pkcs11interop-implement","softhsm","workshop","workshop-materials"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtumilowicz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-10T22:47:37.000Z","updated_at":"2024-12-11T01:57:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"eda1807d-1e46-4be4-a9d0-68c2d00ed7cb","html_url":"https://github.com/mtumilowicz/cryptography-hsm-workshop","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mtumilowicz/cryptography-hsm-workshop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtumilowicz%2Fcryptography-hsm-workshop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtumilowicz%2Fcryptography-hsm-workshop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtumilowicz%2Fcryptography-hsm-workshop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtumilowicz%2Fcryptography-hsm-workshop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtumilowicz","download_url":"https://codeload.github.com/mtumilowicz/cryptography-hsm-workshop/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtumilowicz%2Fcryptography-hsm-workshop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29842897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T21:18:31.832Z","status":"ssl_error","status_checked_at":"2026-02-25T21:18:29.265Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","cryptography-concepts","cryptography-course","cryptography-tools","hardware-security-module","hsm","pkcs11","pkcs11-tool","pkcs11interop-implement","softhsm","workshop","workshop-materials"],"created_at":"2025-01-04T22:51:15.915Z","updated_at":"2026-02-25T22:04:39.422Z","avatar_url":"https://github.com/mtumilowicz.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://app.travis-ci.com/mtumilowicz/cryptography-hsm-workshop.svg?branch=master)](https://app.travis-ci.com/mtumilowicz/cryptography-hsm-workshop)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n# cryptography-hsm-workshop\n* references\n    * https://stackoverflow.com/questions/43114733/java-complains-on-loading-pkcs-dll-from-softhsm\n    * https://clydedcruz.medium.com/a-dive-into-softhsm-e4be3e70c7bc\n    * https://www.ibm.com/docs/en/linux-on-systems?topic=introduction-what-is-pkcs-11\n    * https://www.securew2.com/blog/what-is-pkcs11\n    * https://blog.devgenius.io/what-is-hardware-security-module-a-brief-explanation-6ac448f2cfa9\n    * https://clydedcruz.medium.com/a-dive-into-softhsm-e4be3e70c7bc\n    * https://medium.com/@gerritjvv/java-cryptography-api-and-keystorage-88bd350ec1b7\n    * https://medium.com/@mevan.karu/standard-api-for-connecting-hsms-with-client-applications-6296eb187d89\n    * http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html\n    * https://docs.oracle.com/en/java/javase/12/security/pkcs11-reference-guide1.html#GUID-6DA72F34-6C6A-4F7D-ADBA-5811576A9331\n    * https://thalesdocs.com/gphsm/ptk/5.9/docs/Content/PTK-C_Program/intro_PKCS11.htm\n    * https://medium.com/@mevan.karu/want-to-know-how-to-talk-to-a-hsm-at-code-level-69cb9ba7b392\n    * https://medium.com/@mevan.karu/secure-cryptographic-operations-with-hardware-security-modules-d54734834d7e\n    * http://javadoc.iaik.tugraz.at/pkcs11_wrapper/current/index.html\n    * https://www.opendnssec.org/softhsm/\n    * https://www.mankier.com/1/softhsm2-util\n    * [Explaining HSMs | Part 3 - Common Attacks](https://www.youtube.com/watch?v=aRjuUPYE-tk)\n    * https://medium.com/coinmonks/securing-keys-with-hsms-hardware-secure-module-d4015a9bdc5\n\n## preface\n* goals of this workshop\n    * understanding pkcs11\n    * introduction to hsm\n    * showing some basic attacks\n\n## pkcs11\n* PKCS = The Public-Key Cryptography Standards\n    * specified by OASIS Open which is a global nonprofit organization\n    * works on the development, convergence, and adoption of open standards for security, IoT, energy,\n    content technologies, emergency management, and other areas\n* specifies an API, called Cryptographic APIs (Cryptoki)\n    * defines the most commonly used cryptographic object types\n        * example: RSA keys, X.509 Certificates, DES/Triple DES keys, etc.\n        * and all the functions needed to use\n            * example: create/generate, modify, and delete those objects\n* PKCS #11 is not an implementation of a API, it is a specification for the implementation of the API\n    * OASIS Open provides only a set of ANSI C header files defining the interface exposed to client application\n    * HSM vendor is responsible for providing concrete implementation of the functionalities specified in PKCS #11\n        * which you need to install and configure according to manufacturer's instructions\n* applications can address cryptographic devices (tokens)\n    * example: smart cards, USB keys, and Hardware Security Modules (HSMs)\n    * and can perform cryptographic functions as implemented by these tokens\n        * example: create or delete cryptographic data like public-private key pairs\n* comes with a series of C header files \n    * (pkcs11.h, pkcs11f.h and pkcs11t.h)\n    * which different hardware providers provide implementations for\n    * Java has to provide a JCA wrapper for it via JNI (sun.security.pkcs11.SunPKCS11)\n        * some of famous wrappers:\n            * SunPKCS11\n                * doesn’t provide an object oriented mapping of data structures\n                * in contrast to most other providers, does not implement cryptographic algorithms itself\n            * IBM PKCS11\n                * isn’t an open source project\n            * IAIK PKCS11\n                * open sourced\n          * SunPKCS11 doesn’t provide an object oriented mapping of data structures and IBM wrapper isn’t an open source project\n* glossary\n    * token\n        * logical view of the underlying cryptographic device\n        * possesses a list of cryptographic functionalities supported by the device\n    * slot\n        * logical access point to the cryptographic device\n            * physical device interface\n            * example: smart card reader would represent a slot and the smart card would represent the token\n        * objects that resides within a given slot is not visible to other slots\n        * multiple slots may share the same token\n            * what application sees is there’s a token inside each slot\n                * example: if there is only one HSM then the token is same for all the slots\n                    * application gets the view of multiple independent tokens so HSM can be used by other\n                    applications from different slots concurrently.\n    * session\n        * logical connection between an application and a token\n        * all cryptographic operations provided in the HSM are used via an initiated session\n        * two types\n            * Read/Write\n            * Read-Only\n    * user\n        * is a person or an application who has access to the cryptographic device through a slot\n        * two users\n            * SO(Security Officer)\n                * has the authority to create a USER\n            * USER for each slot\n                * is responsible for using device for cryptographic operations\n            * there can be only one SO and USER for a given slot\n       * certain PKCS#11 operations, such as accessing private keys, require a login using PIN\n    * objects\n        * four classes\n            * data objects - defined by an application\n            * certificate objects - digital certificates such as X.509\n            * key objects - public, private or secret cryptographic keys\n                * digression\n                    * unextractable key on a secure token is represented by a Java Key object that does not\n                    contain the actual key material\n                        * Key object only contains a reference to the actual key\n            * vendor-defined objects\n        * further defined as either\n            * token object\n                * visible by any application which has sufficient access permission and is connected to that token\n                * important attribute: object remains on the token until a specific action is performed to remove it\n            * session object\n                * temporary and only remain in existence while the session is open\n                * only visible to the application that created them\n* debugging\n    * adding showInfo=true in the SunPKCS11 provider configuration file\n        * show debug info about Library, Slots, Token, and Mechanism\n    * restart the Java processes with one of the following options\n        * -Djava.security.debug=sunpkcs11\n            * general SunPKCS11 provider debugging info\n        * -Djava.security.debug=pkcs11keystore\n            * For PKCS#11 keystore specific debugging info\n* pkcs#11 configuration file\n    * example\n        ```\n        name = SoftHSM\n        library = C:/SoftHSM2/lib/softhsm2-x64.dll\n        slot = 875625480\n        attributes(generate, *, *) = {\n        CKA_TOKEN = true\n        }\n        attributes(generate, CKO_CERTIFICATE, *) = {\n        CKA_PRIVATE = false\n        }\n        attributes(generate, CKO_PUBLIC_KEY, *) = {\n        CKA_PRIVATE = false\n        }\n        ```\n    * library = pathname of PKCS#11 implementation\n    * name = name suffix of this provider instance\n    * description = description of this provider instance\n    * slot = slot id\n        * id of the slot that this provider instance is to be associated with\n    * slotListIndex = slot index\n        * slot index that this provider instance is to be associated with\n        * example: 0 indicates the first slot in the list\n        * at most one of slot or slotListIndex may be specified\n    * enabledMechanisms\n        * example\n            ```\n            enabledMechanisms = {\n                CKM_RSA_PKCS\n                CKM_RSA_PKCS_KEY_PAIR_GEN\n            }\n            ```\n        * not specified =\u003e mechanisms enabled are those that are supported\n          by both the SunPKCS11 provider and the PKCS#11 token\n    * attributes\n        * example\n            ```\n            attributes(operation, keytype, keyalgorithm) = {\n              name1 = value1\n              [...]\n            }\n            ```\n        * used to specify additional PKCS#11 that should be set when creating PKCS#11 key objects\n        * by default, the SunPKCS11 provider only specifies mandatory PKCS#11 attributes when creating objects\n            * example\n                * RSA public keys\n                    * key type and algorithm (CKA_CLASS and CKA_KEY_TYPE)\n                    * key values for RSA public keys (CKA_MODULUS and CKA_PUBLIC_EXPONENT)\n        * operation\n            * generate - for keys generated via a KeyPairGenerator or KeyGenerator\n            * import - for keys created via a KeyFactory or SecretKeyFactory\n            * * - for keys created using either a generate or a create operation\n        * keytype\n            * CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, and CKO_SECRET_KEY and * to match any type of key\n        * keyalgorithm\n            * one of the CKK_xxx constants from the PKCS#11 specification\n                * CKK_RSA, CKK_DSA, CKK_DH, CKK_AES, CKK_DES, CKK_DES3, CKK_RC4, CKK_BLOWFISH, CKK_GENERIC_SECRET, and CKK_EC\n            * or * to match keys of any algorithm\n            * attribute names and values\n                * name must be a CKA_xxx constant from the PKCS#11 specification\n                    * example: CKA_SENSITIVE\n                * value can be one of the following:\n                    * boolean value\n                    * integer\n                    * null = indicating that this attribute should not be specified when creating objects\n\n## hsm\n* a physical device that protect and manage digital keys and provides crypto-processing function\n    * example: generating the key, store the key, using the key for decrypt/encrypt operation, and discarding the key\n* trusted, hardened, tamper resistant, dedicated crypto processor designed to perform strengthened cryptographic\nhas a specially designed, well-tested hardware to perform cryptographic operations faster than a normal computer\nand security-focused OS to secure sensitive data from intruders\n* attaches directly to a server and is used to securely manage and perform operations on cryptographic keys\n    * plays a major role in the aspect of system’s security and it can become a single point of failure to the system\n        * most of the HSM vendors provide capability of using HSM clusters for high availability and load balancing\n* secret key will never leave HSM in unencrypted format\n    * main purpose: generate cryptographic keys and sign information without revealing private-key material\n    to the outside world\n* many different forms\n    * PCIe, where the HSM came in PCIe form to be embedded in server\n      * Example: Thales Luna PCIe HSM\n    * standalone appliance, where the HSM came in the form of standalone appliance\n      * Example: Utimaco Cryptoserver CP5\n    * USB, where the HSM came in the form of USB stick\n      * Example: YubiHSM 2\n* HSMs vs software cryptographic providers\n    * secured key management process\n        * HSMs are good at providing both logical and physical protection.\n        * HSMs keep sensitive materials such as private keys, symmetric keys within the HSM throughout their life cycle\n        without exposing them to outside\n        * all key operations are taking place inside the HSM =\u003e only authorized users can use the keys\n        * HSMs provide additional security by being tamper resistant\n            * device become inoperable in case of a tampering\n        * HSMs maintain a log containing all information on operations carried out using keys\n            * makes it easier to determine if any intrusions or misuse of keys have been taken place\n    * increase the throughput of the system\n        * software cryptographic providers utilize server resources\n            * causes performance degradation in the server\n        * HSMs are designed and optimized to carry out cryptographic operations\n            * increase in the overall performance of the system since\n                * server resources can be utilized for business logic processing\n                * HSMs are much faster at crypto processing than a normal CPU.\n    * strong key generation\n        * keys generated using software are inherently weaker than those generated using HSMs\n            * computer is a finite state machine =\u003e is not capable of generating truly random values\n            * HSMs are using a special physical processes to generate truly random keys\n    * meet current standards and regulations on cyber security\n        * FIPS 140-2\n            * an internationally recognized standard for hardware cryptographic devices\n            * four security levels\n                * almost every HSM in the market is standardized under those levels\n        * integrating HSMs to a system makes it easier to get compliance with current security regulations\n* use cases\n    * generation, storage and operation of private key of Certificate Authority (CA)\n    * generation, storage and operation of private key for https operation of an web server\n    * digitally sign a PDF file\n* to interact with the HSM, we need some kind of protocol\n    * common protocol: PKCS#1\n    * HSM Vendors will expose its function through this Cryptoki\n    * usually, HSM Vendors also have their own proprietary protocol and SDK for developer to use\n    * example\n        * application is using PKCS #11 supported HSM\n            * needs to generate an AES key using HSM and encrypt a sample of data using the generated key\n            * application authenticates itself as user ‘USER’ to the HSM and creates a secure communication passage\n            (session between token and application)\n            * application asks HSM to generate an AES key\n            * HSM returns the created AES key\n            * application sends set of data needs to be encrypted with the encryption key\n            * HSM sends back the ciphered data\n            * application closes the communication passage\n* layers involved in interacting with an HSM\n    ![alt text](img/hsm_layers.png)\n    ![alt text](img/pkcs11_communication.png)\n    * Java Cryptography Architecture (JCA) and Java Cryptography Extension (JCE)\n        * set of programming interfaces for performing cryptographic operations\n        * provider-based\n            * actual operation is performed in the configured provider which implements that interface\n        * tries to abstract the actual crypto implementation from the algorithm requested\n            * example\n                * using Cipher.getInstance(“AES”), and not have to hard code the actual implementation\n                    * different implementations can be swapped out depending on deployment requirements.\n        * heart of the JCA architecture: Provider abstract class\n            * specific provider will register different algorithm implementations\n            * each implementation implements a specific *SPI (service provider interface) abstract class\n                * example: KeyStoreSpi, KeyPairGenerationSpi, SignatureSpi\n    * Sun PKCS#11: bridge between the JCA, JCE APIs and the native PKCS#11 module\n        * native module: a shared-object library provided by the vendor of the HSM device\n            * .so file on Solaris and Linux\n            * or dynamic-link library (.dll on Windows)\n* multiple HSMs are handled by the PKCS #11 API\n    ![alt text](img/hsm_multiple_slots.png)\n    * PKCS #11 API is designed integrating load balancing techniques so that cryptographic operations are fairly\n    distributed over set of HSMs connected to the application\n\n## softhsm\n* potential problem with the use of the PKCS #11 interface is that it might limit the wide spread use of OpenDNSSEC,\nsince a potential user might not be willing to invest in a new hardware device\n* isn’t exactly an HSM per se, but a software implementation of a generic PKCS#11 device\n* you can use it to explore PKCS #11 without having a Hardware Security Module\n* commands\n  * softhsm2-util --show-slots\n  * softhsm2-util --init-token --slot 0 --label \"\u003ctoken name\u003e\"\n  * softhsm2-util --import key1.pem --token \"mytoken\" --label \"My key\" --id A1B2 --pin 123456\n\n## attacks\n* attack based on key wrapping\n    * key wrapping = encrypt one key with another key\n    * key used to encrypt other one (called wrapping key) needs: CKA_WRAP attribute\n    * key to be encrypted needs to be: CKA_EXTRACTABLE attribute\n    * for the attack\n        * you set CKA_DECRYPT for wrapping key\n        * you send back wrapped key to HSM to decrypt it\n* attack on key derivation (unextractable key)\n    * key derivation = extract key from key\n        * CKM_EXTRACT_KEY_FROM_KEY, is a mechanism which provides the capability\n          of creating one secret key from the bits of another secret key\n            * mechanism has a parameter, a CK_EXTRACT_PARAMS, which specifies which\n              bit of the original key should be used as the first bit of the newly-derived key\n    * for the attack\n        * start at the most-significant bit and extract 2 bytes\n        * HMAC a chosen message using the derived key\n        * with brute force uncover the short key by trying all possibilities against known message/HMAC pairs\n        * repeat with derived another short-key at a different offset\n        * this requires a couple of seconds with Luna G5\n* more: https://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.1.3442","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtumilowicz%2Fcryptography-hsm-workshop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtumilowicz%2Fcryptography-hsm-workshop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtumilowicz%2Fcryptography-hsm-workshop/lists"}