{"id":26397295,"url":"https://github.com/thalesgroup/luna-kmu","last_synced_at":"2025-03-17T12:17:19.917Z","repository":{"id":251004382,"uuid":"826978039","full_name":"ThalesGroup/luna-kmu","owner":"ThalesGroup","description":"A tool to generate and manage cryptographic keys using a Luna HSM","archived":false,"fork":false,"pushed_at":"2025-03-14T19:41:12.000Z","size":337,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-14T20:34:38.682Z","etag":null,"topics":["cryptographic-software","cryptography-utilities","hsm","luna","thales"],"latest_commit_sha":null,"homepage":"https://thalesdocs.com/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThalesGroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-10T19:06:04.000Z","updated_at":"2025-03-14T19:41:15.000Z","dependencies_parsed_at":"2025-02-05T16:31:07.440Z","dependency_job_id":"b0d25e4f-7801-48fe-a33c-19d630951169","html_url":"https://github.com/ThalesGroup/luna-kmu","commit_stats":null,"previous_names":["thalesgroup/luna-kmu"],"tags_count":0,"template":false,"template_full_name":"ThalesGroup/template-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Fluna-kmu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Fluna-kmu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Fluna-kmu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThalesGroup%2Fluna-kmu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThalesGroup","download_url":"https://codeload.github.com/ThalesGroup/luna-kmu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244031135,"owners_count":20386534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cryptographic-software","cryptography-utilities","hsm","luna","thales"],"created_at":"2025-03-17T12:17:19.275Z","updated_at":"2025-03-17T12:17:19.905Z","avatar_url":"https://github.com/ThalesGroup.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\r\n# Luna Key Management Utility (KMU)\r\n\r\nThis project provides a tool to generate and manage cryptographic keys using [Luna General Purpose HSMs](https://cpl.thalesgroup.com/encryption/hardware-security-modules/general-purpose-hsms), and more specifically [Luna Network HSMs](https://cpl.thalesgroup.com/encryption/hardware-security-modules/network-hsms). \r\n\r\n## Introduction\r\nKMU is based on the [PKCS#11 specification](https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html), with some [Luna specific extensions](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/sdk/pkcs11/pkcs11_standard.htm).\r\n\r\nIt has been tested with both Luna Network HSMs and the [Luna Cloud HSM service](https://cpl.thalesgroup.com/encryption/data-protection-on-demand/services/luna-cloud-hsm).\r\n\r\nThe purpose of KMU is to offer handful key management functions to import/export/derive cryptographic keys using transport keys (or \"wrap keys\", which can be private or secret keys) to address typical IOT and automotive use cases.\r\n\r\nKMU allows to:\r\n-\tCreate data objects.\r\n-\tList objects in partitions.\r\n-\tDisplay and modify object attributes.\r\n-\tCreate keys (including DES, AES, RSA, DSA, DH, ECDSA, EdDSA, Montgomery, SM2, SM4 or generic ones).\r\n- \tCreate AES or DES keys as multiple clear key compoments and KCV (XOR method)\r\n-\tExport and wrap private/secret keys (currently limited to RSA OAEP, AES variant wrap algorithms) in a file.\r\n-\tExport public keys in a binary file or a text file encoded using ASN1 DER and PKCS#8.\r\n-\tImport wrapped private/secret keys from a file (currently limited to RSA OAEP, AES variant wrap algorithms).\r\n-   Import wrapped AES keys from a file encoded in TR31 format(partial support with AES key only as ZMK).\r\n- \tImport DES or AES keys as multiple clear key compoments and KCV (XOR method)\r\n-\tImport public keys from a binary file or a text text file encoded using ASN1 DER, PKCS#8.\r\n-\tEncrypt/decrypt from/to a file (currently limited to RSA OAEP and AES encryption algorithms).\r\n-\tDerive key (currently limited to SHAxxx derivation mechanisms and proprietary Thales Luna key derivation functions such as CKM_NIST_PRF_KDF).\r\n-\tGenerate a digest for symetric keys.\r\n-\tConvert a file format to other file formats.\r\n-\tCompute KCV on a symetric key (currently limited to 3 KCV methods: PCI DSS, PKCS#11 and Global Platform).\r\n\r\nThese operations require to create partitions, register clients, initialize user roles... These tasks can be performed using:\r\n- The [Luna Universal Client](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/Utilities/Preface.htm), and esp.\r\n  - The [Luna Shell (Lush)](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/lunash/Preface.htm)\r\n  - The [Luna client management tool (LunaCM)](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/lunacm/Preface.htm)\r\n- The [Luna REST API](https://thalesdocs.com/gphsm/luna/7/docs/network/Content/REST_API/REST_API_References.htm)\r\n\r\nKMU supports the Luna HSM \"Crypto User\" role, with both password and PED authentication (if the CKF_PROTECTED_AUTHENTICATION_PATH \"TokenInfo\" flag is set to 1).\r\n\r\nKMU is available as a console and might be scriptable from a command line. The console supports auto completion for command and parameters.\r\n\r\n## Requirements\r\n- Base OS:\r\n  - Windows-10 or later.\r\n  - Windows Server 2019 or later.\r\n- Redistribuable package:\r\n  - 2015 -2022 (refer to https://learn.microsoft.com/fr-fr/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022).\r\n- Thales Luna Universal Client:\r\n  - 10.5.x or later.\r\n- Environment variable “ChrystokiConfigurationPath” must refer to the folder that contains the Luna Universal Client PKCS#11 library ('cryptoki.dll').\r\n  - This environment variable is set when you install luna client.\r\n  - KMU searches for a \"cryptoki.dll\" in the path pointed at by this environment variable.\r\n  - If this environment variable is already pointing at a PKCS#11 DLL, KMU will use this library.\r\n\r\n## Build\r\n- Requirements:\r\n  - Base OS:\r\n    - Windows-10 or later.\r\n    - Windows Server 2019 or later.\r\n  - Development environment:\r\n    - Visual Studio 2015 or later with a C/C++ build chain.\r\n    - Thales Luna Universal Client:\r\n      - 10.5.x or later.\r\n    - Environment variable “ChrystokiConfigurationPath” must refer to the folder that contains the Luna Universal Client PKCS#11 library ('cryptoki.dll').\r\n- Using Visual Studio:\r\n  - Open the \"kmu.sln\" solution file.\r\n  - Select the \"release\" configuration and build the solution.\r\n- Once built, \"kmu.exe\" can be used immediately.\r\n\r\nNote:\r\n- A precompiled version is provided for Windows x64 platforms in the \"x64/release\" directory. \r\n\r\n## Run\r\nRefer to the usage documentation provided by the tool (running it without any parameter or using help command).\r\n\r\n```\r\nhelp                            Display this help\r\nlistslot                        This command lists all PKCS#11 slot\r\nlogin                           Login to selected slot\r\nlogout                          Logout the current slot\r\nlist                            This command lists all the keys in the selected slot\r\ngeneratekey                     This command generates a symmetric or asymmetric key\r\ncreatedo                        This command creates a data object\r\ngetattribute                    This command displays object attributes\r\nsetattribute                    This command set attributes to an object\r\nexport                          This command exports a key to a file\r\nimport                          This command imports a key from a file\r\nencrypt                         This command encrypts a file\r\ndecrypt                         This command decrypts a file\r\nderive                          This command derives a key\r\nconvert                         This command converts a file to a different format\r\ndelete                          This command deletes an object\r\ndigestkey                       This command return a message digest of secret key\r\ncomputekcv                      This command calculate the KCV of a symetric key\r\nexit                            Exit console\r\n```\r\n\r\nAll command parameters are optional. \r\n\r\nTo display help for a specific command, use: \r\n\r\n```\r\n\"command\" help\r\n```\r\n\r\nTwo argument formats are supported for each command:\r\n- Command -arg1 value1 -arg2 -value2\r\n- Command -arg=value1 -arg2=value2\r\n\r\nTypical examples:\r\n| Command | -argument=value or -argument value |\r\n| ------- | ---------------------------------- | \r\n| List all objects in a PKCS#11 | slot list -slot=0 -password=00000000 |\r\n| List all objects in a PKCS#11 as crypto user | slot list -slot=0 -password=00000000 - cu=true|\r\n| Generate a AES key | generatekey -slot=0 -password=00000000 -keytype=aes -keysize 32 -label=key-aes-256 -extractable=1 -modifiable=true -wrap=0 -encrypt false -token=true -private=true -sensitive=true |\r\n| Generate a RSA key | generatekey -slot=0 -password=00000000 -keytype=rsa -keysize 4096 -labelpublic=key-rsa-public -labelprivate=key-rsa-private -publicexponent=65537 -extractable=1 -modifiable=true -mech=prime |\r\n| Generate a ECDSA key | generatekey -slot=0 -password=00000000 -keytype=ecdsa -labelpublic=key-ecdsa-public -labelprivate=key-ecdsa-private -curve=secp256r1  |\r\n| Generate a EDDSA key | generatekey -slot=0 -password=00000000 -keytype=eddsa -labelpublic=key-eddsa-public -labelprivate=key-eddsa-private -curve=ed25519 |\r\n| Generate a SM2 key | generatekey -slot=0 -password=00000000 -keytype=sm2 -labelpublic=key-sm2-public -labelprivate=key-sm2-private -curve=sm2 |\r\n| Export a private RSA key with a symetric AES wrap key (1) | export -slot=0 -password=00000000 -handle=377 -outputfile=private_rsa.bin -format=bin -key=426 -algo=aes_cbc_pad |\r\n| Export a private RSA key with a symetric AES wrap key (2) | export -slot=0 -password=00000000 -handle=377 -outputfile=private_rsa.txt -format=text -key=426 -algo=aes_cbc_pad |\r\n| Export a AES key with a asymetric public RSA wrap key | export -slot=0 -password=00000000 -handle=535 -outputfile=secret_aes.bin -format=bin -key=602 -algo=rsa_oaep_sha256 |\r\n| Export a public key | export -slot=0 -password=00000000 -handle=717 -outputfile=public_ecdsa_sect571k1.pem -format=PKCS8 |\r\n| Import a private RSA key with a symetric AES wrap key | import -slot=0 -password=00000000 -keyclass=private -keytype=rsa -inputfile=private_rsa.bin -format=bin -key=426 -algo=aes_cbc_pad -label=importrsakey -modifiable=false -extractable=false |\r\n| Import a AES key with a asymetric private RSA wrap key | import -slot=0 -password=00000000 -keyclass=secret -keytype=aes -inputfile=secret_aes.bin -format=bin -key=603 -algo=rsa_oaep_sha256 -label=importaeskey -modifiable=true -extractable=true |\r\n| Import a public key | import -slot=0 -password=00000000 -keyclass=public -keytype=ecdsa -inputfile=public_ecdsa_sect571k1.pem -format=PKCS8 -label=imported-ecdsa-sect571k1 -modifiable=true -extractable=true |\r\n| Derive a key from a master key using SHA derivation | derive -slot=0 -password=00000000 -key=751 -keytype=aes -keysize=32 -mech=sha256 -label=derived-key-sha256 -extractable=true |\r\n| Derive a key from a master key using luna KDF method with SCP03 | derive -slot=0 -password=00000000 -key=426 -keytype=aes -keysize=32 -mech=luna-nist-kdf  |-label=derived-key-kdf-scp03 -extractable=true -kdf-type=aes-cmac -kdf-scheme=scp03 -kdf-counter=9 -kdf-label=0102 -kdf-context=FFFF |\r\n| Generate a AES key with 3 compoments and follow prompt| generatekey -slot=0 -password=00000000 -keytype=aes -keysize=32 -clearcomponents=3 -label=zmk-key-aes-256 |\r\n| Import a AES key with 3 compoments and follow prompt | import -slot=0 -password=00000000 -keytype=aes -keysize=32 -clearcomponents=3 -label=zmk-key-aes-256 |\r\n\r\n## Test\r\n\r\nThe folder test contains some templates of keys that can be imported into a HSM (using a preconfigued HSM slot) and a file \"list-command.txt\" that contains a list of test command.\r\n\r\nThe best approach is to generate/derive different kinds of keys (AES, RSA, ECDSA...) on the HSM using the \"generatekey\" command.\r\n\r\nThen keys can be exported and imported to/from different parties. \r\n\r\nOnce a key has been generated, its PKCS#11 attributes can be shown using the \"getattribute\" command. \r\n\r\nThe PKCS#11 attributes may be updated using the \"setattribute\" command.\r\n\r\n## Contributing\r\n\r\nIf you are interested in contributing to this project, please read the [Contributing guide](CONTRIBUTING.md).\r\n\r\n## License\r\n\r\nThis software is provided under a [permissive license](LICENSE).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthalesgroup%2Fluna-kmu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthalesgroup%2Fluna-kmu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthalesgroup%2Fluna-kmu/lists"}