SecurityPkg/Include/Library/Tpm2CommandLib.h

   1 /** @file
   2   This library is used by other modules to send TPM2 command.
   3
   4 Copyright (c) 2013 - 2021, Intel Corporation. All rights reserved. <BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _TPM2_COMMAND_LIB_H_
  10 #define _TPM2_COMMAND_LIB_H_
  11
  12 #include <IndustryStandard/Tpm20.h>
  13
  14 /**
  15   This command starts a hash or an Event sequence.
  16   If hashAlg is an implemented hash, then a hash sequence is started.
  17   If hashAlg is TPM_ALG_NULL, then an Event sequence is started.
  18
  19   @param[in]  HashAlg           The hash algorithm to use for the hash sequence
  20                                 An Event sequence starts if this is TPM_ALG_NULL.
  21   @param[out] SequenceHandle    A handle to reference the sequence
  22
  23   @retval EFI_SUCCESS      Operation completed successfully.
  24   @retval EFI_DEVICE_ERROR Unexpected device behavior.
  25 **/
  26 EFI_STATUS
  27 EFIAPI
  28 Tpm2HashSequenceStart (
  29   IN TPMI_ALG_HASH    HashAlg,
  30   OUT TPMI_DH_OBJECT  *SequenceHandle
  31   );
  32
  33 /**
  34   This command is used to add data to a hash or HMAC sequence.
  35   The amount of data in buffer may be any size up to the limits of the TPM.
  36   NOTE: In all TPM, a buffer size of 1,024 octets is allowed.
  37
  38   @param[in] SequenceHandle    Handle for the sequence object
  39   @param[in] Buffer            Data to be added to hash
  40
  41   @retval EFI_SUCCESS      Operation completed successfully.
  42   @retval EFI_DEVICE_ERROR Unexpected device behavior.
  43 **/
  44 EFI_STATUS
  45 EFIAPI
  46 Tpm2SequenceUpdate (
  47   IN TPMI_DH_OBJECT    SequenceHandle,
  48   IN TPM2B_MAX_BUFFER  *Buffer
  49   );
  50
  51 /**
  52   This command adds the last part of data, if any, to an Event sequence and returns the result in a digest list.
  53   If pcrHandle references a PCR and not TPM_RH_NULL, then the returned digest list is processed in
  54   the same manner as the digest list input parameter to TPM2_PCR_Extend() with the pcrHandle in each
  55   bank extended with the associated digest value.
  56
  57   @param[in]  PcrHandle         PCR to be extended with the Event data
  58   @param[in]  SequenceHandle    Authorization for the sequence
  59   @param[in]  Buffer            Data to be added to the Event
  60   @param[out] Results           List of digests computed for the PCR
  61
  62   @retval EFI_SUCCESS      Operation completed successfully.
  63   @retval EFI_DEVICE_ERROR Unexpected device behavior.
  64 **/
  65 EFI_STATUS
  66 EFIAPI
  67 Tpm2EventSequenceComplete (
  68   IN TPMI_DH_PCR          PcrHandle,
  69   IN TPMI_DH_OBJECT       SequenceHandle,
  70   IN TPM2B_MAX_BUFFER     *Buffer,
  71   OUT TPML_DIGEST_VALUES  *Results
  72   );
  73
  74 /**
  75   This command adds the last part of data, if any, to a hash/HMAC sequence and returns the result.
  76
  77   @param[in]  SequenceHandle    Authorization for the sequence
  78   @param[in]  Buffer            Data to be added to the hash/HMAC
  79   @param[out] Result            The returned HMAC or digest in a sized buffer
  80
  81   @retval EFI_SUCCESS      Operation completed successfully.
  82   @retval EFI_DEVICE_ERROR Unexpected device behavior.
  83 **/
  84 EFI_STATUS
  85 EFIAPI
  86 Tpm2SequenceComplete (
  87   IN TPMI_DH_OBJECT    SequenceHandle,
  88   IN TPM2B_MAX_BUFFER  *Buffer,
  89   OUT TPM2B_DIGEST     *Result
  90   );
  91
  92 /**
  93   Send Startup command to TPM2.
  94
  95   @param[in] StartupType           TPM_SU_CLEAR or TPM_SU_STATE
  96
  97   @retval EFI_SUCCESS      Operation completed successfully.
  98   @retval EFI_DEVICE_ERROR Unexpected device behavior.
  99 **/
 100 EFI_STATUS
 101 EFIAPI
 102 Tpm2Startup (
 103   IN      TPM_SU  StartupType
 104   );
 105
 106 /**
 107   Send Shutdown command to TPM2.
 108
 109   @param[in] ShutdownType           TPM_SU_CLEAR or TPM_SU_STATE.
 110
 111   @retval EFI_SUCCESS      Operation completed successfully.
 112   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 113 **/
 114 EFI_STATUS
 115 EFIAPI
 116 Tpm2Shutdown (
 117   IN      TPM_SU  ShutdownType
 118   );
 119
 120 /**
 121   This command causes the TPM to perform a test of its capabilities.
 122   If the fullTest is YES, the TPM will test all functions.
 123   If fullTest = NO, the TPM will only test those functions that have not previously been tested.
 124
 125   @param[in] FullTest    YES if full test to be performed
 126                          NO if only test of untested functions required
 127
 128   @retval EFI_SUCCESS      Operation completed successfully.
 129   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 130 **/
 131 EFI_STATUS
 132 EFIAPI
 133 Tpm2SelfTest (
 134   IN TPMI_YES_NO  FullTest
 135   );
 136
 137 /**
 138   This command allows setting of the authorization policy for the platform hierarchy (platformPolicy), the
 139   storage hierarchy (ownerPolicy), and and the endorsement hierarchy (endorsementPolicy).
 140
 141   @param[in]  AuthHandle            TPM_RH_ENDORSEMENT, TPM_RH_OWNER or TPM_RH_PLATFORM+{PP} parameters to be validated
 142   @param[in]  AuthSession           Auth Session context
 143   @param[in]  AuthPolicy            An authorization policy hash
 144   @param[in]  HashAlg               The hash algorithm to use for the policy
 145
 146   @retval EFI_SUCCESS      Operation completed successfully.
 147   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 148 **/
 149 EFI_STATUS
 150 EFIAPI
 151 Tpm2SetPrimaryPolicy (
 152   IN  TPMI_RH_HIERARCHY_AUTH  AuthHandle,
 153   IN  TPMS_AUTH_COMMAND       *AuthSession,
 154   IN  TPM2B_DIGEST            *AuthPolicy,
 155   IN  TPMI_ALG_HASH           HashAlg
 156   );
 157
 158 /**
 159   This command removes all TPM context associated with a specific Owner.
 160
 161   @param[in] AuthHandle        TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP}
 162   @param[in] AuthSession       Auth Session context
 163
 164   @retval EFI_SUCCESS      Operation completed successfully.
 165   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 166 **/
 167 EFI_STATUS
 168 EFIAPI
 169 Tpm2Clear (
 170   IN TPMI_RH_CLEAR      AuthHandle,
 171   IN TPMS_AUTH_COMMAND  *AuthSession OPTIONAL
 172   );
 173
 174 /**
 175   Disables and enables the execution of TPM2_Clear().
 176
 177   @param[in] AuthHandle        TPM_RH_LOCKOUT or TPM_RH_PLATFORM+{PP}
 178   @param[in] AuthSession       Auth Session context
 179   @param[in] Disable           YES if the disableOwnerClear flag is to be SET,
 180                                NO if the flag is to be CLEAR.
 181
 182   @retval EFI_SUCCESS      Operation completed successfully.
 183   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 184 **/
 185 EFI_STATUS
 186 EFIAPI
 187 Tpm2ClearControl (
 188   IN TPMI_RH_CLEAR      AuthHandle,
 189   IN TPMS_AUTH_COMMAND  *AuthSession  OPTIONAL,
 190   IN TPMI_YES_NO        Disable
 191   );
 192
 193 /**
 194   This command allows the authorization secret for a hierarchy or lockout to be changed using the current
 195   authorization value as the command authorization.
 196
 197   @param[in] AuthHandle        TPM_RH_LOCKOUT, TPM_RH_ENDORSEMENT, TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 198   @param[in] AuthSession       Auth Session context
 199   @param[in] NewAuth           New authorization secret
 200
 201   @retval EFI_SUCCESS      Operation completed successfully.
 202   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 203 **/
 204 EFI_STATUS
 205 EFIAPI
 206 Tpm2HierarchyChangeAuth (
 207   IN TPMI_RH_HIERARCHY_AUTH  AuthHandle,
 208   IN TPMS_AUTH_COMMAND       *AuthSession,
 209   IN TPM2B_AUTH              *NewAuth
 210   );
 211
 212 /**
 213   This replaces the current EPS with a value from the RNG and sets the Endorsement hierarchy controls to
 214   their default initialization values.
 215
 216   @param[in] AuthHandle        TPM_RH_PLATFORM+{PP}
 217   @param[in] AuthSession       Auth Session context
 218
 219   @retval EFI_SUCCESS      Operation completed successfully.
 220   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 221 **/
 222 EFI_STATUS
 223 EFIAPI
 224 Tpm2ChangeEPS (
 225   IN TPMI_RH_PLATFORM   AuthHandle,
 226   IN TPMS_AUTH_COMMAND  *AuthSession
 227   );
 228
 229 /**
 230   This replaces the current PPS with a value from the RNG and sets platformPolicy to the default
 231   initialization value (the Empty Buffer).
 232
 233   @param[in] AuthHandle        TPM_RH_PLATFORM+{PP}
 234   @param[in] AuthSession       Auth Session context
 235
 236   @retval EFI_SUCCESS      Operation completed successfully.
 237   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 238 **/
 239 EFI_STATUS
 240 EFIAPI
 241 Tpm2ChangePPS (
 242   IN TPMI_RH_PLATFORM   AuthHandle,
 243   IN TPMS_AUTH_COMMAND  *AuthSession
 244   );
 245
 246 /**
 247   This command enables and disables use of a hierarchy.
 248
 249   @param[in] AuthHandle        TPM_RH_ENDORSEMENT, TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}
 250   @param[in] AuthSession       Auth Session context
 251   @param[in] Hierarchy         Hierarchy of the enable being modified
 252   @param[in] State             YES if the enable should be SET,
 253                                NO if the enable should be CLEAR
 254
 255   @retval EFI_SUCCESS      Operation completed successfully.
 256   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 257 **/
 258 EFI_STATUS
 259 EFIAPI
 260 Tpm2HierarchyControl (
 261   IN TPMI_RH_HIERARCHY  AuthHandle,
 262   IN TPMS_AUTH_COMMAND  *AuthSession,
 263   IN TPMI_RH_HIERARCHY  Hierarchy,
 264   IN TPMI_YES_NO        State
 265   );
 266
 267 /**
 268   This command cancels the effect of a TPM lockout due to a number of successive authorization failures.
 269   If this command is properly authorized, the lockout counter is set to zero.
 270
 271   @param[in]  LockHandle            LockHandle
 272   @param[in]  AuthSession           Auth Session context
 273
 274   @retval EFI_SUCCESS      Operation completed successfully.
 275   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 276 **/
 277 EFI_STATUS
 278 EFIAPI
 279 Tpm2DictionaryAttackLockReset (
 280   IN  TPMI_RH_LOCKOUT    LockHandle,
 281   IN  TPMS_AUTH_COMMAND  *AuthSession
 282   );
 283
 284 /**
 285   This command cancels the effect of a TPM lockout due to a number of successive authorization failures.
 286   If this command is properly authorized, the lockout counter is set to zero.
 287
 288   @param[in]  LockHandle            LockHandle
 289   @param[in]  AuthSession           Auth Session context
 290   @param[in]  NewMaxTries           Count of authorization failures before the lockout is imposed
 291   @param[in]  NewRecoveryTime       Time in seconds before the authorization failure count is automatically decremented
 292   @param[in]  LockoutRecovery       Time in seconds after a lockoutAuth failure before use of lockoutAuth is allowed
 293
 294   @retval EFI_SUCCESS      Operation completed successfully.
 295   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 296 **/
 297 EFI_STATUS
 298 EFIAPI
 299 Tpm2DictionaryAttackParameters (
 300   IN  TPMI_RH_LOCKOUT    LockHandle,
 301   IN  TPMS_AUTH_COMMAND  *AuthSession,
 302   IN  UINT32             NewMaxTries,
 303   IN  UINT32             NewRecoveryTime,
 304   IN  UINT32             LockoutRecovery
 305   );
 306
 307 /**
 308   This command is used to read the public area and Name of an NV Index.
 309
 310   @param[in]  NvIndex            The NV Index.
 311   @param[out] NvPublic           The public area of the index.
 312   @param[out] NvName             The Name of the nvIndex.
 313
 314   @retval EFI_SUCCESS            Operation completed successfully.
 315   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 316 **/
 317 EFI_STATUS
 318 EFIAPI
 319 Tpm2NvReadPublic (
 320   IN      TPMI_RH_NV_INDEX  NvIndex,
 321   OUT     TPM2B_NV_PUBLIC   *NvPublic,
 322   OUT     TPM2B_NAME        *NvName
 323   );
 324
 325 /**
 326   This command defines the attributes of an NV Index and causes the TPM to
 327   reserve space to hold the data associated with the index.
 328   If a definition already exists at the index, the TPM will return TPM_RC_NV_DEFINED.
 329
 330   @param[in]  AuthHandle         TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}.
 331   @param[in]  AuthSession        Auth Session context
 332   @param[in]  Auth               The authorization data.
 333   @param[in]  NvPublic           The public area of the index.
 334
 335   @retval EFI_SUCCESS            Operation completed successfully.
 336   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 337   @retval EFI_ALREADY_STARTED    The command was returned successfully, but NvIndex is already defined.
 338 **/
 339 EFI_STATUS
 340 EFIAPI
 341 Tpm2NvDefineSpace (
 342   IN      TPMI_RH_PROVISION  AuthHandle,
 343   IN      TPMS_AUTH_COMMAND  *AuthSession  OPTIONAL,
 344   IN      TPM2B_AUTH         *Auth,
 345   IN      TPM2B_NV_PUBLIC    *NvPublic
 346   );
 347
 348 /**
 349   This command removes an index from the TPM.
 350
 351   @param[in]  AuthHandle         TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}.
 352   @param[in]  NvIndex            The NV Index.
 353   @param[in]  AuthSession        Auth Session context
 354
 355   @retval EFI_SUCCESS            Operation completed successfully.
 356   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 357   @retval EFI_NOT_FOUND          The command was returned successfully, but NvIndex is not found.
 358 **/
 359 EFI_STATUS
 360 EFIAPI
 361 Tpm2NvUndefineSpace (
 362   IN      TPMI_RH_PROVISION  AuthHandle,
 363   IN      TPMI_RH_NV_INDEX   NvIndex,
 364   IN      TPMS_AUTH_COMMAND  *AuthSession OPTIONAL
 365   );
 366
 367 /**
 368   This command reads a value from an area in NV memory previously defined by TPM2_NV_DefineSpace().
 369
 370   @param[in]     AuthHandle         the handle indicating the source of the authorization value.
 371   @param[in]     NvIndex            The index to be read.
 372   @param[in]     AuthSession        Auth Session context
 373   @param[in]     Size               Number of bytes to read.
 374   @param[in]     Offset             Byte offset into the area.
 375   @param[in,out] OutData            The data read.
 376
 377   @retval EFI_SUCCESS            Operation completed successfully.
 378   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 379   @retval EFI_NOT_FOUND          The command was returned successfully, but NvIndex is not found.
 380 **/
 381 EFI_STATUS
 382 EFIAPI
 383 Tpm2NvRead (
 384   IN      TPMI_RH_NV_AUTH    AuthHandle,
 385   IN      TPMI_RH_NV_INDEX   NvIndex,
 386   IN      TPMS_AUTH_COMMAND  *AuthSession  OPTIONAL,
 387   IN      UINT16             Size,
 388   IN      UINT16             Offset,
 389   IN OUT  TPM2B_MAX_BUFFER   *OutData
 390   );
 391
 392 /**
 393   This command writes a value to an area in NV memory that was previously defined by TPM2_NV_DefineSpace().
 394
 395   @param[in]  AuthHandle         the handle indicating the source of the authorization value.
 396   @param[in]  NvIndex            The NV Index of the area to write.
 397   @param[in]  AuthSession        Auth Session context
 398   @param[in]  InData             The data to write.
 399   @param[in]  Offset             The offset into the NV Area.
 400
 401   @retval EFI_SUCCESS            Operation completed successfully.
 402   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 403   @retval EFI_NOT_FOUND          The command was returned successfully, but NvIndex is not found.
 404 **/
 405 EFI_STATUS
 406 EFIAPI
 407 Tpm2NvWrite (
 408   IN      TPMI_RH_NV_AUTH    AuthHandle,
 409   IN      TPMI_RH_NV_INDEX   NvIndex,
 410   IN      TPMS_AUTH_COMMAND  *AuthSession  OPTIONAL,
 411   IN      TPM2B_MAX_BUFFER   *InData,
 412   IN      UINT16             Offset
 413   );
 414
 415 /**
 416   This command may be used to prevent further reads of the Index until the next TPM2_Startup (TPM_SU_CLEAR).
 417
 418   @param[in]  AuthHandle         the handle indicating the source of the authorization value.
 419   @param[in]  NvIndex            The NV Index of the area to lock.
 420   @param[in]  AuthSession        Auth Session context
 421
 422   @retval EFI_SUCCESS            Operation completed successfully.
 423   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 424   @retval EFI_NOT_FOUND          The command was returned successfully, but NvIndex is not found.
 425 **/
 426 EFI_STATUS
 427 EFIAPI
 428 Tpm2NvReadLock (
 429   IN      TPMI_RH_NV_AUTH    AuthHandle,
 430   IN      TPMI_RH_NV_INDEX   NvIndex,
 431   IN      TPMS_AUTH_COMMAND  *AuthSession OPTIONAL
 432   );
 433
 434 /**
 435   This command may be used to inhibit further writes of the Index.
 436
 437   @param[in]  AuthHandle         the handle indicating the source of the authorization value.
 438   @param[in]  NvIndex            The NV Index of the area to lock.
 439   @param[in]  AuthSession        Auth Session context
 440
 441   @retval EFI_SUCCESS            Operation completed successfully.
 442   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 443   @retval EFI_NOT_FOUND          The command was returned successfully, but NvIndex is not found.
 444 **/
 445 EFI_STATUS
 446 EFIAPI
 447 Tpm2NvWriteLock (
 448   IN      TPMI_RH_NV_AUTH    AuthHandle,
 449   IN      TPMI_RH_NV_INDEX   NvIndex,
 450   IN      TPMS_AUTH_COMMAND  *AuthSession OPTIONAL
 451   );
 452
 453 /**
 454   The command will SET TPMA_NV_WRITELOCKED for all indexes that have their TPMA_NV_GLOBALLOCK attribute SET.
 455
 456   @param[in]  AuthHandle         TPM_RH_OWNER or TPM_RH_PLATFORM+{PP}.
 457   @param[in]  AuthSession        Auth Session context
 458
 459   @retval EFI_SUCCESS            Operation completed successfully.
 460   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 461   @retval EFI_NOT_FOUND          The command was returned successfully, but NvIndex is not found.
 462 **/
 463 EFI_STATUS
 464 EFIAPI
 465 Tpm2NvGlobalWriteLock (
 466   IN      TPMI_RH_PROVISION  AuthHandle,
 467   IN      TPMS_AUTH_COMMAND  *AuthSession OPTIONAL
 468   );
 469
 470 /**
 471   This command is used to cause an update to the indicated PCR.
 472   The digests parameter contains one or more tagged digest value identified by an algorithm ID.
 473   For each digest, the PCR associated with pcrHandle is Extended into the bank identified by the tag (hashAlg).
 474
 475   @param[in] PcrHandle   Handle of the PCR
 476   @param[in] Digests     List of tagged digest values to be extended
 477
 478   @retval EFI_SUCCESS      Operation completed successfully.
 479   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 480 **/
 481 EFI_STATUS
 482 EFIAPI
 483 Tpm2PcrExtend (
 484   IN      TPMI_DH_PCR         PcrHandle,
 485   IN      TPML_DIGEST_VALUES  *Digests
 486   );
 487
 488 /**
 489   This command is used to cause an update to the indicated PCR.
 490   The data in eventData is hashed using the hash algorithm associated with each bank in which the
 491   indicated PCR has been allocated. After the data is hashed, the digests list is returned. If the pcrHandle
 492   references an implemented PCR and not TPM_ALG_NULL, digests list is processed as in
 493   TPM2_PCR_Extend().
 494   A TPM shall support an Event.size of zero through 1,024 inclusive.
 495
 496   @param[in]  PcrHandle   Handle of the PCR
 497   @param[in]  EventData   Event data in sized buffer
 498   @param[out] Digests     List of digest
 499
 500   @retval EFI_SUCCESS      Operation completed successfully.
 501   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 502 **/
 503 EFI_STATUS
 504 EFIAPI
 505 Tpm2PcrEvent (
 506   IN      TPMI_DH_PCR         PcrHandle,
 507   IN      TPM2B_EVENT         *EventData,
 508   OUT     TPML_DIGEST_VALUES  *Digests
 509   );
 510
 511 /**
 512   This command returns the values of all PCR specified in pcrSelect.
 513
 514   @param[in]  PcrSelectionIn     The selection of PCR to read.
 515   @param[out] PcrUpdateCounter   The current value of the PCR update counter.
 516   @param[out] PcrSelectionOut    The PCR in the returned list.
 517   @param[out] PcrValues          The contents of the PCR indicated in pcrSelect.
 518
 519   @retval EFI_SUCCESS            Operation completed successfully.
 520   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 521 **/
 522 EFI_STATUS
 523 EFIAPI
 524 Tpm2PcrRead (
 525   IN   TPML_PCR_SELECTION  *PcrSelectionIn,
 526   OUT  UINT32              *PcrUpdateCounter,
 527   OUT  TPML_PCR_SELECTION  *PcrSelectionOut,
 528   OUT  TPML_DIGEST         *PcrValues
 529   );
 530
 531 /**
 532   This command is used to set the desired PCR allocation of PCR and algorithms.
 533
 534   @param[in]  AuthHandle         TPM_RH_PLATFORM+{PP}
 535   @param[in]  AuthSession        Auth Session context
 536   @param[in]  PcrAllocation      The requested allocation
 537   @param[out] AllocationSuccess  YES if the allocation succeeded
 538   @param[out] MaxPCR             maximum number of PCR that may be in a bank
 539   @param[out] SizeNeeded         number of octets required to satisfy the request
 540   @param[out] SizeAvailable      Number of octets available. Computed before the allocation
 541
 542   @retval EFI_SUCCESS            Operation completed successfully.
 543   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 544 **/
 545 EFI_STATUS
 546 EFIAPI
 547 Tpm2PcrAllocate (
 548   IN  TPMI_RH_PLATFORM    AuthHandle,
 549   IN  TPMS_AUTH_COMMAND   *AuthSession,
 550   IN  TPML_PCR_SELECTION  *PcrAllocation,
 551   OUT TPMI_YES_NO         *AllocationSuccess,
 552   OUT UINT32              *MaxPCR,
 553   OUT UINT32              *SizeNeeded,
 554   OUT UINT32              *SizeAvailable
 555   );
 556
 557 /**
 558   Alloc PCR data.
 559
 560   @param[in]  PlatformAuth      platform auth value. NULL means no platform auth change.
 561   @param[in]  SupportedPCRBanks Supported PCR banks
 562   @param[in]  PCRBanks          PCR banks
 563
 564   @retval EFI_SUCCESS Operation completed successfully.
 565 **/
 566 EFI_STATUS
 567 EFIAPI
 568 Tpm2PcrAllocateBanks (
 569   IN TPM2B_AUTH  *PlatformAuth   OPTIONAL,
 570   IN UINT32      SupportedPCRBanks,
 571   IN UINT32      PCRBanks
 572   );
 573
 574 /**
 575   This command returns various information regarding the TPM and its current state.
 576
 577   The capability parameter determines the category of data returned. The property parameter
 578   selects the first value of the selected category to be returned. If there is no property
 579   that corresponds to the value of property, the next higher value is returned, if it exists.
 580   The moreData parameter will have a value of YES if there are more values of the requested
 581   type that were not returned.
 582   If no next capability exists, the TPM will return a zero-length list and moreData will have
 583   a value of NO.
 584
 585   NOTE:
 586   To simplify this function, leave returned CapabilityData for caller to unpack since there are
 587   many capability categories and only few categories will be used in firmware. It means the caller
 588   need swap the byte order for the fields in CapabilityData.
 589
 590   @param[in]  Capability         Group selection; determines the format of the response.
 591   @param[in]  Property           Further definition of information.
 592   @param[in]  PropertyCount      Number of properties of the indicated type to return.
 593   @param[out] MoreData           Flag to indicate if there are more values of this type.
 594   @param[out] CapabilityData     The capability data.
 595
 596   @retval EFI_SUCCESS            Operation completed successfully.
 597   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 598 **/
 599 EFI_STATUS
 600 EFIAPI
 601 Tpm2GetCapability (
 602   IN      TPM_CAP               Capability,
 603   IN      UINT32                Property,
 604   IN      UINT32                PropertyCount,
 605   OUT     TPMI_YES_NO           *MoreData,
 606   OUT     TPMS_CAPABILITY_DATA  *CapabilityData
 607   );
 608
 609 /**
 610   This command returns the information of TPM Family.
 611
 612   This function parse the value got from TPM2_GetCapability and return the Family.
 613
 614   @param[out] Family             The Family of TPM. (a 4-octet character string)
 615
 616   @retval EFI_SUCCESS            Operation completed successfully.
 617   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 618 **/
 619 EFI_STATUS
 620 EFIAPI
 621 Tpm2GetCapabilityFamily (
 622   OUT     CHAR8  *Family
 623   );
 624
 625 /**
 626   This command returns the information of TPM manufacture ID.
 627
 628   This function parse the value got from TPM2_GetCapability and return the TPM manufacture ID.
 629
 630   @param[out] ManufactureId      The manufacture ID of TPM.
 631
 632   @retval EFI_SUCCESS            Operation completed successfully.
 633   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 634 **/
 635 EFI_STATUS
 636 EFIAPI
 637 Tpm2GetCapabilityManufactureID (
 638   OUT     UINT32  *ManufactureId
 639   );
 640
 641 /**
 642   This command returns the information of TPM FirmwareVersion.
 643
 644   This function parse the value got from TPM2_GetCapability and return the TPM FirmwareVersion.
 645
 646   @param[out] FirmwareVersion1   The FirmwareVersion1.
 647   @param[out] FirmwareVersion2   The FirmwareVersion2.
 648
 649   @retval EFI_SUCCESS            Operation completed successfully.
 650   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 651 **/
 652 EFI_STATUS
 653 EFIAPI
 654 Tpm2GetCapabilityFirmwareVersion (
 655   OUT     UINT32  *FirmwareVersion1,
 656   OUT     UINT32  *FirmwareVersion2
 657   );
 658
 659 /**
 660   This command returns the information of the maximum value for commandSize and responseSize in a command.
 661
 662   This function parse the value got from TPM2_GetCapability and return the max command size and response size
 663
 664   @param[out] MaxCommandSize     The maximum value for commandSize in a command.
 665   @param[out] MaxResponseSize    The maximum value for responseSize in a command.
 666
 667   @retval EFI_SUCCESS            Operation completed successfully.
 668   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 669 **/
 670 EFI_STATUS
 671 EFIAPI
 672 Tpm2GetCapabilityMaxCommandResponseSize (
 673   OUT UINT32  *MaxCommandSize,
 674   OUT UINT32  *MaxResponseSize
 675   );
 676
 677 /**
 678   This command returns Returns a list of TPMS_ALG_PROPERTIES. Each entry is an
 679   algorithm ID and a set of properties of the algorithm.
 680
 681   This function parse the value got from TPM2_GetCapability and return the list.
 682
 683   @param[out] AlgList      List of algorithm.
 684
 685   @retval EFI_SUCCESS            Operation completed successfully.
 686   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 687 **/
 688 EFI_STATUS
 689 EFIAPI
 690 Tpm2GetCapabilitySupportedAlg (
 691   OUT TPML_ALG_PROPERTY  *AlgList
 692   );
 693
 694 /**
 695   This command returns the information of TPM LockoutCounter.
 696
 697   This function parse the value got from TPM2_GetCapability and return the LockoutCounter.
 698
 699   @param[out] LockoutCounter     The LockoutCounter of TPM.
 700
 701   @retval EFI_SUCCESS            Operation completed successfully.
 702   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 703 **/
 704 EFI_STATUS
 705 EFIAPI
 706 Tpm2GetCapabilityLockoutCounter (
 707   OUT     UINT32  *LockoutCounter
 708   );
 709
 710 /**
 711   This command returns the information of TPM LockoutInterval.
 712
 713   This function parse the value got from TPM2_GetCapability and return the LockoutInterval.
 714
 715   @param[out] LockoutInterval    The LockoutInterval of TPM.
 716
 717   @retval EFI_SUCCESS            Operation completed successfully.
 718   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 719 **/
 720 EFI_STATUS
 721 EFIAPI
 722 Tpm2GetCapabilityLockoutInterval (
 723   OUT     UINT32  *LockoutInterval
 724   );
 725
 726 /**
 727   This command returns the information of TPM InputBufferSize.
 728
 729   This function parse the value got from TPM2_GetCapability and return the InputBufferSize.
 730
 731   @param[out] InputBufferSize    The InputBufferSize of TPM.
 732                                  the maximum size of a parameter (typically, a TPM2B_MAX_BUFFER)
 733
 734   @retval EFI_SUCCESS            Operation completed successfully.
 735   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 736 **/
 737 EFI_STATUS
 738 EFIAPI
 739 Tpm2GetCapabilityInputBufferSize (
 740   OUT     UINT32  *InputBufferSize
 741   );
 742
 743 /**
 744   This command returns the information of TPM PCRs.
 745
 746   This function parse the value got from TPM2_GetCapability and return the PcrSelection.
 747
 748   @param[out] Pcrs    The Pcr Selection
 749
 750   @retval EFI_SUCCESS            Operation completed successfully.
 751   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 752 **/
 753 EFI_STATUS
 754 EFIAPI
 755 Tpm2GetCapabilityPcrs (
 756   OUT TPML_PCR_SELECTION  *Pcrs
 757   );
 758
 759 /**
 760   This function will query the TPM to determine which hashing algorithms
 761   are supported and which PCR banks are currently active.
 762
 763   @param[out]  TpmHashAlgorithmBitmap A bitmask containing the algorithms supported by the TPM.
 764   @param[out]  ActivePcrBanks         A bitmask containing the PCRs currently allocated.
 765
 766   @retval     EFI_SUCCESS   TPM was successfully queried and return values can be trusted.
 767   @retval     Others        An error occurred, likely in communication with the TPM.
 768
 769 **/
 770 EFI_STATUS
 771 EFIAPI
 772 Tpm2GetCapabilitySupportedAndActivePcrs (
 773   OUT UINT32  *TpmHashAlgorithmBitmap,
 774   OUT UINT32  *ActivePcrBanks
 775   );
 776
 777 /**
 778   This command returns the information of TPM AlgorithmSet.
 779
 780   This function parse the value got from TPM2_GetCapability and return the AlgorithmSet.
 781
 782   @param[out] AlgorithmSet    The AlgorithmSet of TPM.
 783
 784   @retval EFI_SUCCESS            Operation completed successfully.
 785   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 786 **/
 787 EFI_STATUS
 788 EFIAPI
 789 Tpm2GetCapabilityAlgorithmSet (
 790   OUT     UINT32  *AlgorithmSet
 791   );
 792
 793 /**
 794   This function will query if the command is supported.
 795
 796   @param[In]  Command         TPM_CC command starts from TPM_CC_FIRST.
 797   @param[out] IsCmdImpl       The command is supported or not.
 798
 799   @retval EFI_SUCCESS            Operation completed successfully.
 800   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 801 **/
 802 EFI_STATUS
 803 EFIAPI
 804 Tpm2GetCapabilityIsCommandImplemented (
 805   IN      TPM_CC   Command,
 806   OUT     BOOLEAN  *IsCmdImpl
 807   );
 808
 809 /**
 810   This command is used to check to see if specific combinations of algorithm parameters are supported.
 811
 812   @param[in]  Parameters              Algorithm parameters to be validated
 813
 814   @retval EFI_SUCCESS      Operation completed successfully.
 815   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 816 **/
 817 EFI_STATUS
 818 EFIAPI
 819 Tpm2TestParms (
 820   IN  TPMT_PUBLIC_PARMS  *Parameters
 821   );
 822
 823 /**
 824   This command allows the platform to change the set of algorithms that are used by the TPM.
 825   The algorithmSet setting is a vendor-dependent value.
 826
 827   @param[in]  AuthHandle              TPM_RH_PLATFORM
 828   @param[in]  AuthSession             Auth Session context
 829   @param[in]  AlgorithmSet            A TPM vendor-dependent value indicating the
 830                                       algorithm set selection
 831
 832   @retval EFI_SUCCESS      Operation completed successfully.
 833   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 834 **/
 835 EFI_STATUS
 836 EFIAPI
 837 Tpm2SetAlgorithmSet (
 838   IN  TPMI_RH_PLATFORM   AuthHandle,
 839   IN  TPMS_AUTH_COMMAND  *AuthSession,
 840   IN  UINT32             AlgorithmSet
 841   );
 842
 843 /**
 844   This command is used to start an authorization session using alternative methods of
 845   establishing the session key (sessionKey) that is used for authorization and encrypting value.
 846
 847   @param[in]  TpmKey             Handle of a loaded decrypt key used to encrypt salt.
 848   @param[in]  Bind               Entity providing the authValue.
 849   @param[in]  NonceCaller        Initial nonceCaller, sets nonce size for the session.
 850   @param[in]  Salt               Value encrypted according to the type of tpmKey.
 851   @param[in]  SessionType        Indicates the type of the session.
 852   @param[in]  Symmetric          The algorithm and key size for parameter encryption.
 853   @param[in]  AuthHash           Hash algorithm to use for the session.
 854   @param[out] SessionHandle      Handle for the newly created session.
 855   @param[out] NonceTPM           The initial nonce from the TPM, used in the computation of the sessionKey.
 856
 857   @retval EFI_SUCCESS            Operation completed successfully.
 858   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 859 **/
 860 EFI_STATUS
 861 EFIAPI
 862 Tpm2StartAuthSession (
 863   IN      TPMI_DH_OBJECT          TpmKey,
 864   IN      TPMI_DH_ENTITY          Bind,
 865   IN      TPM2B_NONCE             *NonceCaller,
 866   IN      TPM2B_ENCRYPTED_SECRET  *Salt,
 867   IN      TPM_SE                  SessionType,
 868   IN      TPMT_SYM_DEF            *Symmetric,
 869   IN      TPMI_ALG_HASH           AuthHash,
 870   OUT  TPMI_SH_AUTH_SESSION       *SessionHandle,
 871   OUT  TPM2B_NONCE                *NonceTPM
 872   );
 873
 874 /**
 875   This command causes all context associated with a loaded object or session to be removed from TPM memory.
 876
 877   @param[in]  FlushHandle        The handle of the item to flush.
 878
 879   @retval EFI_SUCCESS            Operation completed successfully.
 880   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 881 **/
 882 EFI_STATUS
 883 EFIAPI
 884 Tpm2FlushContext (
 885   IN      TPMI_DH_CONTEXT  FlushHandle
 886   );
 887
 888 /**
 889   This command includes a secret-based authorization to a policy.
 890   The caller proves knowledge of the secret value using an authorization
 891   session using the authValue associated with authHandle.
 892
 893   @param[in]  AuthHandle         Handle for an entity providing the authorization
 894   @param[in]  PolicySession      Handle for the policy session being extended.
 895   @param[in]  AuthSession        Auth Session context
 896   @param[in]  NonceTPM           The policy nonce for the session.
 897   @param[in]  CpHashA            Digest of the command parameters to which this authorization is limited.
 898   @param[in]  PolicyRef          A reference to a policy relating to the authorization.
 899   @param[in]  Expiration         Time when authorization will expire, measured in seconds from the time that nonceTPM was generated.
 900   @param[out] Timeout            Time value used to indicate to the TPM when the ticket expires.
 901   @param[out] PolicyTicket       A ticket that includes a value indicating when the authorization expires.
 902
 903   @retval EFI_SUCCESS            Operation completed successfully.
 904   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 905 **/
 906 EFI_STATUS
 907 EFIAPI
 908 Tpm2PolicySecret (
 909   IN      TPMI_DH_ENTITY     AuthHandle,
 910   IN      TPMI_SH_POLICY     PolicySession,
 911   IN      TPMS_AUTH_COMMAND  *AuthSession  OPTIONAL,
 912   IN      TPM2B_NONCE        *NonceTPM,
 913   IN      TPM2B_DIGEST       *CpHashA,
 914   IN      TPM2B_NONCE        *PolicyRef,
 915   IN      INT32              Expiration,
 916   OUT     TPM2B_TIMEOUT      *Timeout,
 917   OUT     TPMT_TK_AUTH       *PolicyTicket
 918   );
 919
 920 /**
 921   This command allows options in authorizations without requiring that the TPM evaluate all of the options.
 922   If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that
 923   satisfies the policy. This command will indicate that one of the required sets of conditions has been
 924   satisfied.
 925
 926   @param[in] PolicySession      Handle for the policy session being extended.
 927   @param[in] HashList           the list of hashes to check for a match.
 928
 929   @retval EFI_SUCCESS            Operation completed successfully.
 930   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 931 **/
 932 EFI_STATUS
 933 EFIAPI
 934 Tpm2PolicyOR (
 935   IN TPMI_SH_POLICY  PolicySession,
 936   IN TPML_DIGEST     *HashList
 937   );
 938
 939 /**
 940   This command indicates that the authorization will be limited to a specific command code.
 941
 942   @param[in]  PolicySession      Handle for the policy session being extended.
 943   @param[in]  Code               The allowed commandCode.
 944
 945   @retval EFI_SUCCESS            Operation completed successfully.
 946   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 947 **/
 948 EFI_STATUS
 949 EFIAPI
 950 Tpm2PolicyCommandCode (
 951   IN      TPMI_SH_POLICY  PolicySession,
 952   IN      TPM_CC          Code
 953   );
 954
 955 /**
 956   This command returns the current policyDigest of the session. This command allows the TPM
 957   to be used to perform the actions required to precompute the authPolicy for an object.
 958
 959   @param[in]  PolicySession      Handle for the policy session.
 960   @param[out] PolicyHash         the current value of the policyHash of policySession.
 961
 962   @retval EFI_SUCCESS            Operation completed successfully.
 963   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 964 **/
 965 EFI_STATUS
 966 EFIAPI
 967 Tpm2PolicyGetDigest (
 968   IN      TPMI_SH_POLICY  PolicySession,
 969   OUT  TPM2B_DIGEST       *PolicyHash
 970   );
 971
 972 /**
 973   This command allows access to the public area of a loaded object.
 974
 975   @param[in]  ObjectHandle            TPM handle of an object
 976   @param[out] OutPublic               Structure containing the public area of an object
 977   @param[out] Name                    Name of the object
 978   @param[out] QualifiedName           The Qualified Name of the object
 979
 980   @retval EFI_SUCCESS      Operation completed successfully.
 981   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 982 **/
 983 EFI_STATUS
 984 EFIAPI
 985 Tpm2ReadPublic (
 986   IN  TPMI_DH_OBJECT  ObjectHandle,
 987   OUT TPM2B_PUBLIC    *OutPublic,
 988   OUT TPM2B_NAME      *Name,
 989   OUT TPM2B_NAME      *QualifiedName
 990   );
 991
 992 //
 993 // Help function
 994 //
 995
 996 /**
 997   Copy AuthSessionIn to TPM2 command buffer.
 998
 999   @param [in]  AuthSessionIn   Input AuthSession data
1000   @param [out] AuthSessionOut  Output AuthSession data in TPM2 command buffer
1001
1002   @return AuthSession size
1003 **/
1004 UINT32
1005 EFIAPI
1006 CopyAuthSessionCommand (
1007   IN      TPMS_AUTH_COMMAND  *AuthSessionIn  OPTIONAL,
1008   OUT     UINT8              *AuthSessionOut
1009   );
1010
1011 /**
1012   Copy AuthSessionIn from TPM2 response buffer.
1013
1014   @param [in]  AuthSessionIn   Input AuthSession data in TPM2 response buffer
1015   @param [out] AuthSessionOut  Output AuthSession data
1016
1017   @return AuthSession size
1018 **/
1019 UINT32
1020 EFIAPI
1021 CopyAuthSessionResponse (
1022   IN      UINT8               *AuthSessionIn,
1023   OUT     TPMS_AUTH_RESPONSE  *AuthSessionOut OPTIONAL
1024   );
1025
1026 /**
1027   Return size of digest.
1028
1029   @param[in] HashAlgo  Hash algorithm
1030
1031   @return size of digest
1032 **/
1033 UINT16
1034 EFIAPI
1035 GetHashSizeFromAlgo (
1036   IN TPMI_ALG_HASH  HashAlgo
1037   );
1038
1039 /**
1040   Get hash mask from algorithm.
1041
1042   @param[in] HashAlgo   Hash algorithm
1043
1044   @return Hash mask
1045 **/
1046 UINT32
1047 EFIAPI
1048 GetHashMaskFromAlgo (
1049   IN TPMI_ALG_HASH  HashAlgo
1050   );
1051
1052 /**
1053   Return if hash alg is supported in HashAlgorithmMask.
1054
1055   @param HashAlg            Hash algorithm to be checked.
1056   @param HashAlgorithmMask  Bitfield of allowed hash algorithms.
1057
1058   @retval TRUE  Hash algorithm is supported.
1059   @retval FALSE Hash algorithm is not supported.
1060 **/
1061 BOOLEAN
1062 EFIAPI
1063 IsHashAlgSupportedInHashAlgorithmMask (
1064   IN TPMI_ALG_HASH  HashAlg,
1065   IN UINT32         HashAlgorithmMask
1066   );
1067
1068 /**
1069   Copy TPML_DIGEST_VALUES into a buffer
1070
1071   @param[in,out] Buffer             Buffer to hold copied TPML_DIGEST_VALUES compact binary.
1072   @param[in]     DigestList         TPML_DIGEST_VALUES to be copied.
1073   @param[in]     HashAlgorithmMask  HASH bits corresponding to the desired digests to copy.
1074
1075   @return The end of buffer to hold TPML_DIGEST_VALUES.
1076 **/
1077 VOID *
1078 EFIAPI
1079 CopyDigestListToBuffer (
1080   IN OUT VOID            *Buffer,
1081   IN TPML_DIGEST_VALUES  *DigestList,
1082   IN UINT32              HashAlgorithmMask
1083   );
1084
1085 /**
1086   Get TPML_DIGEST_VALUES data size.
1087
1088   @param[in]     DigestList    TPML_DIGEST_VALUES data.
1089
1090   @return TPML_DIGEST_VALUES data size.
1091 **/
1092 UINT32
1093 EFIAPI
1094 GetDigestListSize (
1095   IN TPML_DIGEST_VALUES  *DigestList
1096   );
1097
1098 /**
1099   This function get digest from digest list.
1100
1101   @param[in]  HashAlg       Digest algorithm
1102   @param[in]  DigestList    Digest list
1103   @param[out] Digest        Digest
1104
1105   @retval EFI_SUCCESS       Digest is found and returned.
1106   @retval EFI_NOT_FOUND     Digest is not found.
1107 **/
1108 EFI_STATUS
1109 EFIAPI
1110 GetDigestFromDigestList (
1111   IN TPMI_ALG_HASH       HashAlg,
1112   IN TPML_DIGEST_VALUES  *DigestList,
1113   OUT VOID               *Digest
1114   );
1115
1116 /**
1117    This function will query the TPM to determine which hashing algorithms and
1118    get the digests of all active and supported PCR banks of a specific PCR register.
1119
1120    @param[in]     PcrHandle     The index of the PCR register to be read.
1121    @param[out]    HashList      List of digests from PCR register being read.
1122
1123    @retval EFI_SUCCESS           The Pcr was read successfully.
1124    @retval EFI_DEVICE_ERROR      The command was unsuccessful.
1125 **/
1126 EFI_STATUS
1127 EFIAPI
1128 Tpm2PcrReadForActiveBank (
1129   IN      TPMI_DH_PCR  PcrHandle,
1130   OUT     TPML_DIGEST  *HashList
1131   );
1132
1133 #endif