This project provides a tool to generate and manage cryptographic keys using Luna General Purpose HSMs, and more specifically Luna Network HSMs.
KMU is based on the PKCS#11 specification, with some Luna specific extensions.
It has been tested with both Luna Network HSMs and the Luna Cloud HSM service.
The 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.
KMU allows to:
- Create data objects.
- List objects in partitions.
- Display and modify object attributes.
- Create keys (including DES, AES, RSA, DSA, DH, ECDSA, EdDSA, Montgomery, SM2, SM4 or generic ones).
- Export and wrap private/secret keys (currently limited to RSA OAEP, AES variant wrap algorithms) in a file.
- Export public keys in a binary file or a text file encoded using ASN1 DER and PKCS#8.
- Import wrapped private/secret keys from a file (currently limited to RSA OAEP, AES variant wrap algorithms).
- Import public keys from a binary file or a text text file encoded using ASN1 DER, PKCS#8 and TR31 (partial support with AES key only).
- Encrypt/decrypt from/to a file (currently limited to RSA OAEP and AES encryption algorithms).
- Derive key (currently limited to SHAxxx derivation mechanisms and proprietary Thales Luna key derivation functions such as CKM_NIST_PRF_KDF).
- Generate a digest for symetric keys.
- Convert a file format to other file formats.
- Compute KCV on a symetric key (currently limited to 3 KCV methods: PCI DSS, PKCS#11 and Global Platform).
These operations require to create partitions, register clients, initialize user roles... These tasks can be performed using:
- The Luna Universal Client, and esp.
- The Luna REST API
KMU 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).
KMU is available as a console and might be scriptable from a command line. The console supports auto completion for command and parameters.
- Base OS:
- Windows-10 or later.
- Windows Server 2019 or later.
- Redistribuable package:
- Thales Luna Universal Client:
- 10.5.x or later.
- Environment variable “ChrystokiConfigurationPath” must refer to the folder that contains the Luna Universal Client PKCS#11 library ('cryptoki.dll').
- This environment variable is set when you install luna client.
- KMU searches for a "cryptoki.dll" in the path pointed at by this environment variable.
- If this environment variable is already pointing at a PKCS#11 DLL, KMU will use this library.
- Requirements:
- Base OS:
- Windows-10 or later.
- Windows Server 2019 or later.
- Development environment:
- Visual Studio 2015 or later with a C/C++ build chain.
- Thales Luna Universal Client:
- 10.5.x or later.
- Environment variable “ChrystokiConfigurationPath” must refer to the folder that contains the Luna Universal Client PKCS#11 library ('cryptoki.dll').
- Base OS:
- Using Visual Studio:
- Open the "kmu.sln" solution file.
- Select the "release" configuration and build the solution.
- Once built, "kmu.exe" can be used immediately.
Note:
- A precompiled version is provided for Windows x64 platforms in the "x64/release" directory.
Refer to the usage documentation provided by the tool (running it without any parameter or using help command).
help Display this help
listslot This command lists all PKCS#11 slot
login Login to selected slot
logout Logout the current slot
list This command lists all the keys in the selected slot
generatekey This command generates a symmetric or asymmetric key
createdo This command creates a data object
getattribute This command displays object attributes
setattribute This command set attributes to an object
export This command exports a key to a file
import This command imports a key from a file
encrypt This command encrypts a file
decrypt This command decrypts a file
derive This command derives a key
convert This command converts a file to a different format
delete This command deletes an object
digestkey This command return a message digest of secret key
computekcv This command calculate the KCV of a symetric key
exit Exit console
All command parameters are optional.
To display help for a specific command, use:
"command" help
Two argument formats are supported for each command:
- Command -arg1 value1 -arg2 -value2
- Command -arg=value1 -arg2=value2
Typical examples:
| Command | -argument=value or -argument value |
|---|---|
| List all objects in a PKCS#11 slot | list -slot=0 -password=00000000 |
| 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 |
| 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 |
| Generate a ECDSA key | generatekey -slot=0 -password=00000000 -keytype=ecdsa -labelpublic=key-ecdsa-public -labelprivate=key-ecdsa-private -curve=secp256r1 |
| Generate a EDDSA key | generatekey -slot=0 -password=00000000 -keytype=eddsa -labelpublic=key-eddsa-public -labelprivate=key-eddsa-private -curve=ed25519 |
| Generate a SM2 key | generatekey -slot=0 -password=00000000 -keytype=sm2 -labelpublic=key-sm2-public -labelprivate=key-sm2-private -curve=sm2 |
| 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 |
| 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 |
| 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 |
| Export a public key | export -slot=0 -password=00000000 -handle=717 -outputfile=public_ecdsa_sect571k1.pem -format=PKCS8 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
The 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.
The best approach is to generate/derive different kinds of keys (AES, RSA, ECDSA...) on the HSM using the "generatekey" command.
Then keys can be exported and imported to/from different parties.
Once a key has been generated, its PKCS#11 attributes can be shown using the "getattribute" command.
The PKCS#11 attributes may be updated using the "setattribute" command.
If you are interested in contributing to this project, please read the Contributing guide.
This software is provided under a permissive license.