SecurityPkg/Include/Library/Tpm2CommandLib.h

   1 /** @file
   2   This library is used by other modules to send TPM2 command.
   3
   4 Copyright (c) 2013 - 2018, 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 command is used to check to see if specific combinations of algorithm parameters are supported.
 795
 796   @param[in]  Parameters              Algorithm parameters to be validated
 797
 798   @retval EFI_SUCCESS      Operation completed successfully.
 799   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 800 **/
 801 EFI_STATUS
 802 EFIAPI
 803 Tpm2TestParms (
 804   IN  TPMT_PUBLIC_PARMS           *Parameters
 805   );
 806
 807 /**
 808   This command allows the platform to change the set of algorithms that are used by the TPM.
 809   The algorithmSet setting is a vendor-dependent value.
 810
 811   @param[in]  AuthHandle              TPM_RH_PLATFORM
 812   @param[in]  AuthSession             Auth Session context
 813   @param[in]  AlgorithmSet            A TPM vendor-dependent value indicating the
 814                                       algorithm set selection
 815
 816   @retval EFI_SUCCESS      Operation completed successfully.
 817   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 818 **/
 819 EFI_STATUS
 820 EFIAPI
 821 Tpm2SetAlgorithmSet (
 822   IN  TPMI_RH_PLATFORM          AuthHandle,
 823   IN  TPMS_AUTH_COMMAND         *AuthSession,
 824   IN  UINT32                    AlgorithmSet
 825   );
 826
 827 /**
 828   This command is used to start an authorization session using alternative methods of
 829   establishing the session key (sessionKey) that is used for authorization and encrypting value.
 830
 831   @param[in]  TpmKey             Handle of a loaded decrypt key used to encrypt salt.
 832   @param[in]  Bind               Entity providing the authValue.
 833   @param[in]  NonceCaller        Initial nonceCaller, sets nonce size for the session.
 834   @param[in]  Salt               Value encrypted according to the type of tpmKey.
 835   @param[in]  SessionType        Indicates the type of the session.
 836   @param[in]  Symmetric          The algorithm and key size for parameter encryption.
 837   @param[in]  AuthHash           Hash algorithm to use for the session.
 838   @param[out] SessionHandle      Handle for the newly created session.
 839   @param[out] NonceTPM           The initial nonce from the TPM, used in the computation of the sessionKey.
 840
 841   @retval EFI_SUCCESS            Operation completed successfully.
 842   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 843 **/
 844 EFI_STATUS
 845 EFIAPI
 846 Tpm2StartAuthSession (
 847   IN      TPMI_DH_OBJECT            TpmKey,
 848   IN      TPMI_DH_ENTITY            Bind,
 849   IN      TPM2B_NONCE               *NonceCaller,
 850   IN      TPM2B_ENCRYPTED_SECRET    *Salt,
 851   IN      TPM_SE                    SessionType,
 852   IN      TPMT_SYM_DEF              *Symmetric,
 853   IN      TPMI_ALG_HASH             AuthHash,
 854      OUT  TPMI_SH_AUTH_SESSION      *SessionHandle,
 855      OUT  TPM2B_NONCE               *NonceTPM
 856   );
 857
 858 /**
 859   This command causes all context associated with a loaded object or session to be removed from TPM memory.
 860
 861   @param[in]  FlushHandle        The handle of the item to flush.
 862
 863   @retval EFI_SUCCESS            Operation completed successfully.
 864   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 865 **/
 866 EFI_STATUS
 867 EFIAPI
 868 Tpm2FlushContext (
 869   IN      TPMI_DH_CONTEXT           FlushHandle
 870   );
 871
 872 /**
 873   This command includes a secret-based authorization to a policy.
 874   The caller proves knowledge of the secret value using an authorization
 875   session using the authValue associated with authHandle.
 876
 877   @param[in]  AuthHandle         Handle for an entity providing the authorization
 878   @param[in]  PolicySession      Handle for the policy session being extended.
 879   @param[in]  AuthSession        Auth Session context
 880   @param[in]  NonceTPM           The policy nonce for the session.
 881   @param[in]  CpHashA            Digest of the command parameters to which this authorization is limited.
 882   @param[in]  PolicyRef          A reference to a policy relating to the authorization.
 883   @param[in]  Expiration         Time when authorization will expire, measured in seconds from the time that nonceTPM was generated.
 884   @param[out] Timeout            Time value used to indicate to the TPM when the ticket expires.
 885   @param[out] PolicyTicket       A ticket that includes a value indicating when the authorization expires.
 886
 887   @retval EFI_SUCCESS            Operation completed successfully.
 888   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 889 **/
 890 EFI_STATUS
 891 EFIAPI
 892 Tpm2PolicySecret (
 893   IN      TPMI_DH_ENTITY            AuthHandle,
 894   IN      TPMI_SH_POLICY            PolicySession,
 895   IN      TPMS_AUTH_COMMAND         *AuthSession, OPTIONAL
 896   IN      TPM2B_NONCE               *NonceTPM,
 897   IN      TPM2B_DIGEST              *CpHashA,
 898   IN      TPM2B_NONCE               *PolicyRef,
 899   IN      INT32                     Expiration,
 900   OUT     TPM2B_TIMEOUT             *Timeout,
 901   OUT     TPMT_TK_AUTH              *PolicyTicket
 902   );
 903
 904 /**
 905   This command allows options in authorizations without requiring that the TPM evaluate all of the options.
 906   If a policy may be satisfied by different sets of conditions, the TPM need only evaluate one set that
 907   satisfies the policy. This command will indicate that one of the required sets of conditions has been
 908   satisfied.
 909
 910   @param[in] PolicySession      Handle for the policy session being extended.
 911   @param[in] HashList           the list of hashes to check for a match.
 912
 913   @retval EFI_SUCCESS            Operation completed successfully.
 914   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 915 **/
 916 EFI_STATUS
 917 EFIAPI
 918 Tpm2PolicyOR (
 919   IN TPMI_SH_POLICY           PolicySession,
 920   IN TPML_DIGEST              *HashList
 921   );
 922
 923 /**
 924   This command indicates that the authorization will be limited to a specific command code.
 925
 926   @param[in]  PolicySession      Handle for the policy session being extended.
 927   @param[in]  Code               The allowed commandCode.
 928
 929   @retval EFI_SUCCESS            Operation completed successfully.
 930   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 931 **/
 932 EFI_STATUS
 933 EFIAPI
 934 Tpm2PolicyCommandCode (
 935   IN      TPMI_SH_POLICY            PolicySession,
 936   IN      TPM_CC                    Code
 937   );
 938
 939 /**
 940   This command returns the current policyDigest of the session. This command allows the TPM
 941   to be used to perform the actions required to precompute the authPolicy for an object.
 942
 943   @param[in]  PolicySession      Handle for the policy session.
 944   @param[out] PolicyHash         the current value of the policyHash of policySession.
 945
 946   @retval EFI_SUCCESS            Operation completed successfully.
 947   @retval EFI_DEVICE_ERROR       The command was unsuccessful.
 948 **/
 949 EFI_STATUS
 950 EFIAPI
 951 Tpm2PolicyGetDigest (
 952   IN      TPMI_SH_POLICY            PolicySession,
 953      OUT  TPM2B_DIGEST              *PolicyHash
 954   );
 955
 956 /**
 957   This command allows access to the public area of a loaded object.
 958
 959   @param[in]  ObjectHandle            TPM handle of an object
 960   @param[out] OutPublic               Structure containing the public area of an object
 961   @param[out] Name                    Name of the object
 962   @param[out] QualifiedName           The Qualified Name of the object
 963
 964   @retval EFI_SUCCESS      Operation completed successfully.
 965   @retval EFI_DEVICE_ERROR Unexpected device behavior.
 966 **/
 967 EFI_STATUS
 968 EFIAPI
 969 Tpm2ReadPublic (
 970   IN  TPMI_DH_OBJECT            ObjectHandle,
 971   OUT TPM2B_PUBLIC              *OutPublic,
 972   OUT TPM2B_NAME                *Name,
 973   OUT TPM2B_NAME                *QualifiedName
 974   );
 975
 976 //
 977 // Help function
 978 //
 979
 980 /**
 981   Copy AuthSessionIn to TPM2 command buffer.
 982
 983   @param [in]  AuthSessionIn   Input AuthSession data
 984   @param [out] AuthSessionOut  Output AuthSession data in TPM2 command buffer
 985
 986   @return AuthSession size
 987 **/
 988 UINT32
 989 EFIAPI
 990 CopyAuthSessionCommand (
 991   IN      TPMS_AUTH_COMMAND         *AuthSessionIn, OPTIONAL
 992   OUT     UINT8                     *AuthSessionOut
 993   );
 994
 995 /**
 996   Copy AuthSessionIn from TPM2 response buffer.
 997
 998   @param [in]  AuthSessionIn   Input AuthSession data in TPM2 response buffer
 999   @param [out] AuthSessionOut  Output AuthSession data
1000
1001   @return AuthSession size
1002 **/
1003 UINT32
1004 EFIAPI
1005 CopyAuthSessionResponse (
1006   IN      UINT8                      *AuthSessionIn,
1007   OUT     TPMS_AUTH_RESPONSE         *AuthSessionOut OPTIONAL
1008   );
1009
1010 /**
1011   Return size of digest.
1012
1013   @param[in] HashAlgo  Hash algorithm
1014
1015   @return size of digest
1016 **/
1017 UINT16
1018 EFIAPI
1019 GetHashSizeFromAlgo (
1020   IN TPMI_ALG_HASH    HashAlgo
1021   );
1022
1023 /**
1024   Get hash mask from algorithm.
1025
1026   @param[in] HashAlgo   Hash algorithm
1027
1028   @return Hash mask
1029 **/
1030 UINT32
1031 EFIAPI
1032 GetHashMaskFromAlgo (
1033   IN TPMI_ALG_HASH     HashAlgo
1034   );
1035
1036 /**
1037   Return if hash alg is supported in HashAlgorithmMask.
1038
1039   @param HashAlg            Hash algorithm to be checked.
1040   @param HashAlgorithmMask  Bitfield of allowed hash algorithms.
1041
1042   @retval TRUE  Hash algorithm is supported.
1043   @retval FALSE Hash algorithm is not supported.
1044 **/
1045 BOOLEAN
1046 EFIAPI
1047 IsHashAlgSupportedInHashAlgorithmMask(
1048   IN TPMI_ALG_HASH  HashAlg,
1049   IN UINT32         HashAlgorithmMask
1050   );
1051
1052 /**
1053   Copy TPML_DIGEST_VALUES into a buffer
1054
1055   @param[in,out] Buffer             Buffer to hold copied TPML_DIGEST_VALUES compact binary.
1056   @param[in]     DigestList         TPML_DIGEST_VALUES to be copied.
1057   @param[in]     HashAlgorithmMask  HASH bits corresponding to the desired digests to copy.
1058
1059   @return The end of buffer to hold TPML_DIGEST_VALUES.
1060 **/
1061 VOID *
1062 EFIAPI
1063 CopyDigestListToBuffer(
1064   IN OUT VOID                       *Buffer,
1065   IN TPML_DIGEST_VALUES             *DigestList,
1066   IN UINT32                         HashAlgorithmMask
1067   );
1068
1069 /**
1070   Get TPML_DIGEST_VALUES data size.
1071
1072   @param[in]     DigestList    TPML_DIGEST_VALUES data.
1073
1074   @return TPML_DIGEST_VALUES data size.
1075 **/
1076 UINT32
1077 EFIAPI
1078 GetDigestListSize(
1079   IN TPML_DIGEST_VALUES             *DigestList
1080   );
1081
1082 /**
1083   This function get digest from digest list.
1084
1085   @param[in]  HashAlg       Digest algorithm
1086   @param[in]  DigestList    Digest list
1087   @param[out] Digest        Digest
1088
1089   @retval EFI_SUCCESS       Digest is found and returned.
1090   @retval EFI_NOT_FOUND     Digest is not found.
1091 **/
1092 EFI_STATUS
1093 EFIAPI
1094 GetDigestFromDigestList(
1095   IN TPMI_ALG_HASH      HashAlg,
1096   IN TPML_DIGEST_VALUES *DigestList,
1097   OUT VOID              *Digest
1098   );
1099
1100 #endif