Further Information
clairet This space contains documentation on CM and the DDKG, as well as details necessary to understand how they communicate with each other and KeyScaler.
Contents
Credential Manager Assets
This page contains sources of information related to how assets are created, delivered and processed.
The asset receiver is a fairly simple process that runs as a daemon. It periodically checks for any new assets and then receives them when they become available. Initially it will support certificates but it may be enhanced moving forward to receive config, executables or even scripts.
The Process
Periodically (configurable) the Credential Manager process will perform an auth to the SAC. The SAC will return a list (that may be empty) of assets that need to be processed. For each asset in the list an action will be taken. Currently the process has support for certificates so any other type of asset will be ignored (but reported in the log). Each certificate will be delivered encrypted (the private key part will be encrypted), the receiver will decrypt the certificate and then store it on the device at the location specified (received from the SAC). Upon successful storage of the certificate to the file system of the device the receipt will be acknowledged to the SAC. Failure to process the certificate will also be reported back to the SAC so that it may be communicated to the user.
Assets JSON structure
The list of assets received from the SAC will be in the form of a JSON block. The JSON will have the following structure:
"assets":[{"assetId":"someid","assetType":"certificate","filePath":"/some/path/cert.txt","storeEncrypted":"false","certificate":"BEGIN certdata END","privateKey":"encrypted privatekey"}]
The option to store the certificate in the encrypted state (that it is delivered) exists but has little practical value at this time.
Configuration
The only configuration required by the Credential Manager are the credentials for communication with the SAC, the sleep period (how often to check for new assets) and the logging to use. This configuration is read from a config file when the process starts.
Secure Storage
File based storage (secure soft storage)
The Secure Soft Storage mechanism is used to encrypt private keys and certificates held on the host device using keys held by KeyScaler. These keys can only be accessed by the device that was the originator of the request which created them.
Encryption Algorithm
Data is encrypted using an AES 256 symmetric key and IV generated and delivered securely by KeyScaler.
Storage format
The encrypted data is held in a JSON object along with the key ID and asset ID.
{
"key-id": <the challenge key ID>,
"asset-id": <The identifier of the asset that created the data>,
"ciphertext": <The encrypted data base64 encoded>
}
Storage location
The JSON object is then stored as a file in the location on the filesystem as defined in the certificate policy.
Message flow
TODO: Define the message flow in Mermaid or plantUML
Decryption request
For decryption the challenge key ID and asset ID is required to request the key and IV from the KeyScaler, these are found in the JSON object stored in the filesystem.
{
"userId": <The authorization identifier>,
"deviceKey": <An authorization challenge devicekey>,
"keyId": <The challenge key ID stored in the secure soft storage JSON object>,
"appHash": <The hash of the application that is sending the request>,
"assetId": <The asset ID stored in the secure soft storage JSON object>
}
This request is sent by the decrypting application to https://<sac-host>/key/app
TPM based storage
Credential Manager TPM Integration Design
The Credential Manager will use tpm2-tss to provide the interface between CM and a TPM on the host device (where available and configured).
Device TPM Detection
An attempt to provision a TPM using tss2-tpm will allow CM to detect if a TPM is present on the device. If the device does not have a TPM it will fallback to using Secure Soft Storage, if there is a TPM then the provision request will return SUCCESS or DEVICE_ALREADY_PROVISIONED.
Functionality
- The private key shall continue to be created using OpenSSL (if generated on the device) or delivered encrypted from KeyScaler (if generated by the KeyScaler).
- CSRs shall also continue to be generated by OpenSSL.
- The CM shall use a TPM to encrypt the existing JSON encryption blocks that contains either a private key or certificate. This is achieved by sealing a randomly generated encryption key which is stored in the TPM and bound to the host machine, used to encrypt and decrypt the key / certificate.
- This ensures that only the host machine that sealed the data can unseal it.
- A unique encryption key shall be generated for each private key / certificate encrypted on the device.
- When rotating an existing encrypted certificate it will retain the encryption key for that certificate to ensure old copies of the certificate can continue to be decrypted by the host.
- TPM is only used to bind a private key or certificate to the host if the policy has the ‘store encrypted’ option checked.
Credential Manager TPM support
The Credential Manager uses a device TPM, when available, to securely store a private key / certificate on the host device. The TPM seals the key / certificate to the host by utilising the SRK held within the TPM during encryption and decryption. The TPM on the host device must support the TPM 2.0 standard.
FAPI configuration
The FAPI configuration and associated profiles are installed in /usr/local/deviceauthority/conf/. These files allow device specific configuration changes based on the capabilities of the TPM. E.g., we can select whether to use an ECC or an RSA profile, configure which algorithms it can use, etc.
Changes to this area may require developer support – default files provided should work for most customers.
Additional dependencies for TPM support build
Credential Manager TPM support is enabled by the TSS2-TPM libraries – GitHub – tpm2-software/tpm2-tss: OSS implementation of the TCG TPM2 Software Stack (TSS2) .
- libtss2-fapi.so.1.0.0
- libtss2-mu.so.0.0.1
- libtss2-sys.so.1.0.1
- libtss2-esys.so.0.0.1
- libtss2-tctildr.so.0.0.0
- libtss2-tcti-device.so.0.0.0
- libjson-c.so.5.2.0
- libuuid.so.1.3.0
These library files are copied to /usr/local/deviceauthority/lib/ – this path is included in LD_LIBRARY_PATH by the startCredentialManager.sh script.
Note that openSSL v3.0 is required for Credential Manager builds that support TPM.
Storage format
Like secure-soft-storage, TPM based storage generates a key file at a path defined within the KeyScaler certificate issuing policy. If Store Private Key Encrypted On Device is enabled in the policy the private key (if generated on device) and the certificate are stored in a JSON encryption block:
{"ciphertext": "<ciphertext generated by the TPM>", "iv": "<Nonce value generated by the TPM>"}
This contains the ciphertext generated from the private key or certificate and the IV value used to initialise the encryption algorithm. The IV is required to decrypt the ciphertext. The IV is a nonce value generated by the TPM GetRandom value.
The public data associated with the ciphertext encryption key is stored in the keystore at /usr/local/var/lib/tpm2-tss/system/keystore/<tpm policy>/HS/SRK/<certificate path>/. The certificate path is integrated into the keystore path to allow for identification of the encryption key metadata required to decrypt a ciphertext.
Decryption
The libda library is pre-loaded by an application to allow it to intercept OpenSSL calls to read the key / certificate files generated on the device by the KeyScaler certificate issuing policy. libda uses the file path given in the certificate policy to lookup the public data required for the TPM to decrypt the ciphertext contained in the cipher block.
Unlike secure-soft-storage there is no communication between KeyScaler and the application utilising libda, so the application hash is not required for this process.
Non TPM devices
If a device has a TPM it will always attempt to use it. If the TPM fails to be initialised it will fail to generate encrypted key pairs. There is no mechanism to disable TPM usage if the credential manager has support for it built-in as this would weaken CM security. However, if a customer does not want to use the TPM we recommend the use of a CM build without TPM support built-in. This reduces the size and ensures that a device will always use secure soft storage.
If a device does not have a TPM but is running a TPM capable CM it will detect there is no hardware TPM and automatically use secure soft storage.
There are no configuration options available for TPM in the credential manager.
Debugging
Enable TPM logging
To enable TPM logging the following command should be defined when launching credential_manager:
TSS2_LOG=all+DEBUG
Check Credential Manager build TPM support
To check the Credential Manager you’re using has TPM support you can run credential_manager --verbose which will report a Debug log message that states MQTT support: false, TPM support: true where MQTT not supported and TPM is supported.