Luna Key Management Utility (KMU)

This project provides a tool to generate and manage cryptographic keys using Luna General Purpose HSMs, and more specifically Luna Network HSMs.

Introduction

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 Shell (Lush)
  • The Luna client management tool (LunaCM)
• 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.

Requirements

• Base OS:
  • Windows-10 or later.
  • Windows Server 2019 or later.
• Redistribuable package:
  • 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).
• 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.

Build

• 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').
• 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.

Run

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

Test

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.

Contributing

If you are interested in contributing to this project, please read the Contributing guide.

License

This software is provided under a permissive license.