Desktop version

Home arrow Computer Science arrow A Practical Guide to TPM 2.0

Getting Started in Part 3: the Commands

If you're like most programmers, you'll start in Part 3. Seriously, who has time to read a lengthy specification? And after all, the goal is to just “Git 'er done,” right? That's typically the mindset of busy engineers, and it's actually a good approach, except that it will quickly bring you face to face with some of the harsh realities of the TPM 2.0 specification. In order to help you over some of the hurdles we've encountered when using the specification, here are a few things you need to know before you delve into Part 3.

The generic byte structure for all TPM 2.0 commands and responses is described in Part 1 in the section titled “Command/Response Structure.” The Separators table and Command Structure and Response Structure figures are particularly helpful. We recommend that you place a bookmark at these sections in the specification, because you'll be referring to them often.

To make this discussion a bit more practical, we describe in detail two types of commands—a command without authorizations (TPM2_Startup) and a command with authorizations (TPM2_Create)—and explain some of nuances of the command byte stream. We start with TPM2_Startup, because it's the first command that must be sent to the TPM and is one of the simplest TPM 2.0 commands.

If you look at the Part 3 section that describes the TPM2_Startup command, you see three sections:

“General Description”: Describes the command in text form, details some of the constraints on the inputs, and discusses error conditions.

“Command and Response”: A data schematic for the inputs to the command (Command) and the outputs from the command (Response). We discuss these tables in detail in a moment.

“Detailed Actions”: Contains code and a table of the error conditions that are returned by the command's code (not including the ones sent by the supporting code).

This three-part format is used for all commands. For the purposes of our current topic, we mainly look at the Command and Response tables. For the TPM2_Startup command, these tables are shown in Table 5-1 and Table 5-2.

Table 5-1. TPM2_Startup Command (Table 5 in Part 3 of the TPM 2.0 Specification)

The Type column shows the data type for each field of the command. These types are defined in Part 2 of the specification. The Name column is self-explanatory: it contains the name of the parameter to be passed to or from the TPM. This is also the name of the parameter in the Part 3 source code. The Description column describes the field along with any field-specific requirements. TPM2_Startup has two field-specific requirements: tag must be TPM_ST_NO_SESSIONS, and commandCode must be TPM_CC_Startup. The {NV} is a table decoration that means the command may update nonvolatile memory inside the TPM. (Table decorations are described in the Table Decorations section early in Part 3.)

The format of the first three fields—tag, commandSize, and commandCode—is the same for all commands. These fields form the command header.

Following are explanations of the command fields:

• tag: Indicates whether the command has sessions. Because the TPM2_Startup command can never take sessions, this tag must always be set to TPM_ST_NO_SESSIONS.

• commandSize: The size in bytes of the entire command stream sent to the TPM.

• commandCode: Indicates which command is being sent. This tells the TPM how to interpret the rest of the command data.

Now notice the line following the command code:

This line indicates that any fields following are in the parameter area. In this case, startupType is the only parameter in this area. In general, this area contains fields that configure any command-specific parameters for the command. The meaning of these lines and other table decorations are described in two sections of Part 3: “Table

Decorations” and “Handle and Parameter Demarcation.” You will want to refer to these two sections frequently when reading Part 3 of the spec.

Table 5-2. TPM2_Startup Response (Table 6 in Part 3 of the TPM 2.0 Specification)





Tag responseSize responseCode

see clause 6

Following are explanations of the response fields:

• tag: Indicates whether the response has sessions. Because this command never has sessions, tag is always TPM_ST_NO_SESSIONS.

• responseSize: The size in bytes of the entire response byte stream.

• responseCode: Indicates whether the command passed or failed.

TPM_RC_SUCCESS indicates passing. Other codes indicate failure.

Notice that TPM2_Startup has no return parameters.

Now we'll look at a much more complicated command, TPM2_Create. This command is used to create objects such as keys or data objects. Table 5-3 shows its Command table.

Table 5-3. TPM2_Create Command (Table 19 in Part 3 of the TPM 2.0 Specification)

Following are explanations of the command fields:

• tag: In this case, TPM_ST_SESSIONS to indicate that the command must have sessions. Another indication is the @ sign in front of the parentHandle handle name; this means an authorization session is required with this handle. More on that later.

• commandSize: Size of the total byte stream including authorization data.

• commandCode: The command code for this command.

Note this separator. Now things get more interesting; this separator didn't exist the TPM2_Startup command:

This line indicates that the following fields are in the handle area, as described in the “Handle and Parameter Demarcation” section of Part 3. Handles are 32-bit references to various entities in the TPM. parentHandle is the only handle parameter for this command. Commands can take up to two handles in this area.

Notice the @ character in front of parentHandle. This is a table decoration; it means this handle requires that an associated authorization be included in the authorization section. This and other table decorations are described in the “Table Decorations” section early in Part 3.

Also notice the “Auth Index: 1” text in the description. This indicates the ordering of the authorization in the authorization section. In this case, the authorization for the parentHandle must be the first authorization in the authorization section. All commands that take authorizations can take up to three authorizations. When a command has an @ sign in front of one or more handles, the command requires an authorization for each such handle. In this case one authorization is required.

Notice the Auth Role: USER text. This is a further qualification on the authorization, which is described in the chapter on enhanced authorization. Auth roles are analogous to privilege levels in an operating system. They control who can get access to certain entities.

Handles behave differently from parameters in a command: handles aren't used in computing the cpHash, which is a hash of the input parameters. This hash is used in calculating HMACs and, in some cases, policy digests. The purpose of this separation is to allow a resource manager to virtualize the handles in order to swap objects in and out of the TPM, much like a virtual memory manager swaps memory contents between disk drives and memory. Later chapters describe HMACs, policy digests, and the resource manager in detail. For now, it's sufficient to understand that handles and parameters are separated into different fields in the byte stream in order to facilitate some key differences in functionality.

Now you see a line you're familiar with from the Startup command. Again, it indicates the start of the parameter area:

But in this case, because tag is equal to TPM_ST_SESSIONS, indicating that this command requires an authorization session, this separator also indicates where the authorization data is inserted into the command byte stream. This command's authorization area can have between one and three sessions, all of which are inserted here. We describe the authorization area in detail in chapter 13.

This command takes four parameters: insensitive, inPublic, outsideInfo, and creationPCR. Part 2 describes the data structure types for each of these.

Table 5-4 shows the TPM2_Create command's Response table.

Table 5-4. TPM2_Create Response (Table 20 in Part 3 of the TPM 2.0 Specification)

Following are explanations of the response fields:

• tag, responseSize, and responseCode are as described earlier, except that if the command passes, tag is TPM_RC_SESSIONS to indicate the presence of sessions in the response. There are three cases here:

• If the command has no sessions, the response will have no sessions. For this command, the tag is always set to TPM_ST_NO_SESSIONS.

• If the command has sessions and returns success, the response tag is TPM_ST_SESSIONS, indicating that the response, too, has sessions.

• If the command has sessions but fails, the response tag is TPM_ST_NO_SESSIONS. Failing commands never have sessions or response parameters in their response.

When the following line is present in a response schematic, it indicates the start of the response handle area. In this command, there are no response handles, so this line isn't present:

Now you see your old friend the parameter demarcation line:

Unlike for the command data, for the response, this is simply the dividing line for parameters; the authorization area isn't located here, but appears later in the byte stream. This command returns five response parameters: outPrivate, outPublic, creationData, creationHash, and creationTicketNotice.

The response authorization area is tacked on to the last line the in the schematic, after all the parameters. This means the response authorization area is the last area in the response byte stream.

Now that we've described the overall command and response structures, we'll discuss some commonly used data types.

< Prev   CONTENTS   Next >

Related topics