The Keys Service stores cryptographic keys, and allows callers to perform operations with those keys like encrypt, decrypt and sign. The service protects the keys by storing them in HSMs, and ensures that no operations against those keys export the keys to the device's memory.
In order to interact with an HSM, the Keys Service requires a PKCS#11 library for the HSM. There are two properties that must be configured in the
[aziot_keys] pkcs11_lib_path = "<path of the PKCS#11 library>" pkcs11_base_slot = "<PKCS#11 URI of a slot where dynamically generated keys will be stored>"
Any TPM 2.0 TPM can be accessed via the
tpm2-pkcs11library. See this page for details of how to install the library on your device.
Microchip devices like the ATECC608A can be accessed via the
cryptoauthliblibrary. See this page for details of how to install the library on your device.
(Not recommended for production) A software-simulated HSM can be accessed via the
softhsmlibrary. See this page for details of how to install the library on your device. This library stores all keys on the filesystem, so it is only useful for development and testing, not for production.
After you've configured the PKCS#11 library, you can test it with
p11tool. Since the library has been configured for the Keys Service's
aziotks Linux user, ensure that you always use that user when using
p11tool, etc. For example, prepend those commands with
sudo -u aziotks.
$PKCS11_LIB_PATH is the path of the PKCS#11 library that you set as the value of
aziot_keys.pkcs11_lib_path in the
To test with
pkcs11-tool --module "$PKCS11_LIB_PATH" .... For example,
pkcs11-tool --module "$PKCS11_LIB_PATH" -IOTwill show information about the token and all objects in it.
To test it with
p11tool --provider "$PKCS11_LIB_PATH" .... For example,
p11tool --provider="$PKCS11_LIB_PATH" --list-token-urlswill show the token URL for the token.
Another alternative for
p11toolis to create a
.modulefile so that you don't need to pass in
--providerfor every invocation:
sudo mkdir -p /etc/pkcs11/modules <<< "module: $PKCS11_LIB_PATH" sudo tee /etc/pkcs11/modules/tpm2-pkcs11.module
--provideris still useful to filter out tokens from other PKCS#11 libraries.
The pages above tell you how to modify the
/etc/aziot/config.toml with the details of the PKCS#11 library and the base slot.