Command Preparation Functions
As explained in Chapters 13 and 17, HMAC calculation, command parameter encryption, and response parameter decryption often require preand post-command processing.
The command preparation functions provide the pre-command execution functions that are needed before actually sending the command to the TPM.
In order to calculate the command HMAC and encrypt command parameters, the command parameters must be marshalled. This could be done with special application code, but because the SAPI already contains this functionality, the API designers decided to make this functionality available to the application. This is the purpose of the Tss2_Sys_XXXX_Prepare functions. Because the command parameters are unique for each Part 3 command, there is one of these functions for each TPM command that needs it. The “XXXX” is replaced by the command name; for instance, the Tss2_Sys_XXXX_Prepare function for TPM2_StartAuthSession is Tss2_Sys_StartAuthSession_Prepare. Following is a call to the prepare code for TPM2_GetTestResult:
rval = Tss2_Sys_GetTestResult_Prepare( sysContext );
■ Note the only parameter to this function is a pointer to the system context, because
TPM2_GetTestResult has no input parameters.
After the Tss2_Sys_XXXX_Prepare call, the data has been marshalled. To get the marshalled command parameter byte stream, the Tss2_Sys_GetCpParam function is called. This returns the start of the cpBuffer, the marshalled command parameter byte stream, and the length of the cpBuffer. How this is used is described further in Chapters 13 and 17.
Another function that is needed to calculate the command HMAC is Tss2_Sys_GetCommandCode. This function returns the command code bytes in CPU endian order. This function is also used in command post-processing.
The Tss2_Sys_GetDecryptParam and Tss2_Sys_SetDecryptParam functions are used for decrypt sessions, which you learn about in Chapter 17. For now, the Tss2_Sys_GetDecryptParam function returns a pointer to the start of the parameter to be encrypted and the size of the parameter. These two returned values are used by the application when it calls Tss2_Sys_SetDecryptParam to set the encrypted value into the command byte stream.
The Tss2_Sys_SetCmdAuths function is used to set the command authorization areas (also called sessions) in the command byte stream. This is explained in detail in Chapter 13, when sessions and authorizations are discussed.