Month: May 2017

Whenever working with Trusted Platform Modules (TPM) one stumbles over the responses and especially the error codes that are returned by the TPM and the software stack used to talk to the TPM. TPM error codes are not always straight forward, but encode more information, for instance, which parameter caused the error.

To make it easier to look up the TPM error codes, I wrote the  TPM Return Code Decoder app. In addition to the error code lookup, the app also provides a library of TPM command descriptions. On the left side menu, the input field  icon opens the Return Code Decoder page. When a TPM error code is entered, the description will be filled with the TPM 1.2 and TPM 2.0 description of the error. If the error code is incorrect for either TPM 1.2 or TPM 2.0, the description field will say that it’s not a valid error code.

The search icon in the menu will open the command code lookup page. Here, a short description of the TPM command will show up in the description field.

The numeric command codes between TPM 1.2 and TPM 2.0 do not overlap, so the lookup of command codes produces either a description for the TPM 1.2 command, or the TPM 2.0 command. Alternatively to entering the numerical command code, a user can select a command from the list of commands, which are sorted alphabetically.

For both, error code and command code lookup, the input field will accept either a decimal entry or a hexadecimal entry. The latter has to be preceded by “0x” to indicate the hexadecimal number. For instance the decimal error code 257 would have to be input as “0x101” in hexadecimal.

The command code lookup page takes the description from the published TPM specifications. It does not contain the full text of the specification, but often only the first paragraph for the respective commands. For a full description of the commands, the full specifications should be consulted. They can be obtained at the TCG website:

• TPM 1.2 Specification
• TPM 2.0 Specification

I hope that this app can help you look up the description for a command or error code for a TPM that you use or write software for.

Source code for the app can be found on GitHub.

This blog post will introduce the basic functionality of the TPM PCR Calculator app, which can be found in the Windows Store.

During the boot of a PC with measured boot enabled, firmware and early phases of the operating system protocol software and configuration data into a measurement log and “checksums” of these log entries into the Platform Configuration Registers (PCR) of a Trusted Platform Module (TPM). The checksums are recorded as hashes, which have been computed using secure hashing algorithms (SHA).

I work a lot with these measured boot logs, or TCG logs, generated as results of UEFI firmware or Windows boot loader. To validate the entries in these log file, I have to calculate hashes and PCR values from hand. This becomes tedious. That’s why I wrote the TPM PCR Calculator app.

The menu (column of icons) on the left navigates to different functionality of this app. The first icon, which looks like the search icon, opens the PCR calculator page. I’ll get back to that later. The first calculator icon opens the hash calculator page.

A hashing algorithm computes the cryptographic hash, or digest, from whatever data is presented to it. To allow users to either input text or a text representation of a byte array, the user can toggle a checkbox labeled “Input is raw bytes.” If the checkbox is clear, the text in the input box  is treated as plain text. If the checkbox is selected, the input is treated as hexadecimal text representation of a byte array. A value of zero of size four bytes would look like this: “00000000” (without the quotes). The “compute hash” button starts the computation of the hashes. The app currently supports the secure hash algorithms (SHA) SHA1 and, from the SHA2 class, SHA2-256, SHA2-384, and SHA2-512. If the checkbox is selected to interpret the input as bytes, but the input cannot be converted into a byte array, an error message is printed into the SHA1 output box.

The lower calculator icon opens the hash calculator with HMAC key page. This hash calculation uses an additional key to compute the hash of input data.

This page work essentially the same as the hash calculator page, except that the HMAC key has to be provided as well. The input format for the HMAC key is always assumed to be “raw bytes”, so the checkbox only controls the input parsing of the input data field.

Now let’s come back to the PCR calculator page: Platform Configuration Registers (PCR) can be manipulated using a one-way (or trap-door) function. This function – “Extend” in TPM terminology – performs two steps: first, it concatenates the input data to the current value of the register. Then a hash is computed of the concatenated value. The result is then stored as current value.  The PCR calculation page will show these steps as explanation of the Extend function.

A PCR is usually associated with a hashing algorithm. TPM version 1.2 devices only support the SHA1 algorithm with PCRs, whereas TPM version 2.0 devices can support multiple PCR with different hashing algorithms. I’ll write a different post that goes into the details of what exactly a PCR is at another time.

In summary, if you have the need to compute hashes or PCR values, this app might be for you.

Source code for the app can be found on GitHub.