Documentation for TPM scenario

[Banchio]

Ciao, with regards to the following statement:

Using a configuration file, we can enroll with a private key resident on a hardware module, such as a hardware security module (HSM) or a Trusted Platform Module 2.0 (TPM) device. Refer to the documentation for more details.

How do I find the documentation? I would like to test EST server with a virtual TPM like described in https://docs.microsoft.com/en-us/azure/iot-edge/how-to-auto-provision-simulated-device-linux?view=iotedge-2018-06 Thanks!

[paulgriffiths]

Hi @Banchio - having built the EST client, the documentation can be accessed with:

estclient help -common

for general information on using the configuration file, and:

estclient sampleconfig -tpm

will output a sample configuration file for use with TPM signing keys.

The relevant part of the sample configuration file for the TPM-specific options is:

{
    "private_key": {
        "tpm": {
            "device": "/dev/tpmrm0",
            "persistent_handle": 2164391936,
            "storage_handle": 2164260865,
            "ek_handle": 2164326401,
            "key_password": "xyzzy",
            "storage_password": "opensesame",
            "ek_password": "abracadabra",
            "ek_certs": "/path/to/ek/certs/chain.pem",
            "public_area": "signing_key.pub",
            "private_area": "signing_key.priv"
        }
    }
}

Note that the EST client won't actually create a signing key on the TPM for you, so it assumes you've already done that and that you have a suitable signing key already available for use.

You don't need to complete all the fields in the TPM section of the configuration file - which fields you complete depends on how your TPM signing key is available:

1. You always need to complete the "device" field on Linux (it's "/dev/tpm0" in the page you linked, for example);
2. If your signing key is permanently resident on the TPM, you also need to complete:
   • "persistent_handle", which must contain the persistent TPM handle for your signing key; and
   • optionally, "key_password" if your signing key is protected on the TPM by a password
3. If your signing key has been saved off-TPM, then the EST client can load it for you (and automatically unload it again once you're done) provided that the associated storage key is permanently resident on the TPM. In this case, you also need to complete:
   • "storage_handle", which must contain the persistent TPM handle for your storage key;
   • "public_area" and "private_area", which must contain the paths to the public and private area blobs of your signing key that you previously saved; and
   • optionally, "key_password" and/or "storage_password" if your signing key and/or storage key are protected on the TPM by a password

The fields beginning with "ek_ are only used for our non-standard TPM privacy-preserving enrollment protocol, so you probably don't need them for your purpose.

Let me know if you have further questions or encounter problems!

[Banchio]

Thank you so much for the detailed explanation, will try in the coming weeks this scenario and update this issue in case of issue. Closing it for now, thanks again!