Command Execution Functions

This group of functions actually sends commands to and, receives responses from the TPM. The commands can be sent synchronously or asynchronously. There are two ways to send commands synchronously: via a sequence of three to five function calls; and via a single “does everything” call, the one-call. Support for asynchronous vs. asynchronous and one-call vs. a finer-grained multi-call approach arose from the desire to support as many application architectures as possible.

Tss2_Sys_ExecuteAsync is the most basic method of sending a command. It sends

the command using the TCTI transmit function and returns as quickly as possible. Here's an example of a call to this function:

rval = Tss2_Sys_ExecuteAsync( sysContext );

Tss2_Sys_ExecuteFinish is the companion function to ExecuteAsync. It calls the TCTI function to receive the response. It takes a command parameter, timeout, that tells it how long to wait for a response. Here's an example that waits 20 msec for a response from the TPM:

rval = Tss2_Sys_ExecuteFinish( sysContext, 20 );

Tss2_Sys_Execute is the synchronous method and is the equivalent of calling Tss2_Sys_ExecuteAsync followed by Tss2_Sys_ExecuteFinish with an infinite timeout. Here's an example:

rval = Tss2_Sys_Execute( sysContext );

The last function in the execution group, Tss2_Sys_XXXX, is the one-call or “do everything” function. This function assumes that authorizations aren't needed, a simple password authorization is being used, or that authorizations such as HMAC and policy have already been calculated. There is one of these commands for each Part 3 command.[1]

As an example, the one-call function for the Tpm2_StartAuthSession command is Tss2_Sys_StartAuthSession. When used with the associated Tss2_Sys_XXXX_Prepare call, the one-call interface can do any type of authorization. An interesting side effect of this is that the command parameters are marshalled twice: once during the Tss2_Sys_XXXX_Prepare call and once during the one-call function call. This was a design compromise because the one-call needed to be capable of being used as a standalone call and paired with the Tss2_Sys_XXXX_Prepare call. Here's an example of the one-call with no command or response authorizations:

rval = Tss2_Sys_GetTestResult( sysContext, 0, &outData, &testResult, 0 );

Note the function takes a pointer to a system context structure; a pointer to a

command authorization's array structure; two output parameters, outData and testResult; and a pointer to a response authorization structure. the parameters that are 0 are the command and response authorization array structures. for this very simple example, these aren't necessary, so NULL pointers are used. Use of these is explained in Chapter 13.

Command Completion Functions

This group of functions enables the command post-processing that is required. This includes response HMAC calculation and response parameter decryption if the session was configured as an encrypt session.

Tss2_Sys_GetRpBuffer gets a pointer to and the size of the response parameter byte stream. Knowing these two values enables the caller to calculate the response HMAC and compare it to the HMAC in the response authorization areas.

Tss2_Sys_GetRspAuths gets the response authorization areas. These are used

to check the response HMACs in order to validate that the response data hasn't been tampered with.

After validating the response data, if the response was sent using an encrypt session,

Tss2_Sys_GetEncryptParam and Tss2_Sys_SetEncryptParam can be used to decrypt the encrypted response parameter and insert the decrypted response parameter into the byte stream prior to unmarshalling the response parameters. These two functions are described in greater detail in Chapter 17 in the discussion of decrypt and encrypt sessions.

After the response parameter has been decrypted, the response byte stream can be unmarshalled. This is done by a call to Tss2_Sys_XXXX_Complete. Because each

command has different response parameters, there is one of these per Part 3 command. [2] An example of this call is as follows:

rval = Tss2_Sys_GetTestResult_Complete( sysContext, &outData, &testResult );

You've now seen all the SAPI calls. Some of these are specific to Part 3 commands, and some apply regardless of which Part 3 command is being executed.

  • [1] 4Part 3 does describe some hardware-triggered commands. These start with an underscore character and aren't included in the SAPI.
  • [2] Commands that have no response parameters don't have a corresponding Complete call.
< Prev   CONTENTS   Next >