src/security/tpm/tss/tcg-2.0/tss_structures.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2
   3 #ifndef TCG2_TSS_STRUCTURES_H_
   4 #define TCG2_TSS_STRUCTURES_H_
   5
   6 /*
   7  * This file includes a subset of definitions of TPM protocol version 2.x
   8  * constants and structures needed for functions used in coreboot.
   9  */
  10 #include <types.h>
  11 #include <security/tpm/tss_errors.h>
  12
  13 /* This should be plenty for what firmware needs. */
  14 #define TPM_BUFFER_SIZE 256
  15
  16 /* Some TPM2 return codes used in this library. */
  17 #define TPM2_RC_SUCCESS    0
  18 #define TPM2_RC_NV_DEFINED 0x14c
  19
  20 #define HASH_COUNT 2 /* SHA-1 and SHA-256 are supported */
  21
  22 /* Basic TPM2 types. */
  23 typedef uint16_t TPM_SU;
  24 typedef uint16_t TPM_ALG_ID;
  25 typedef uint32_t TPM_HANDLE;
  26 typedef uint32_t TPM_RC;
  27 typedef uint8_t TPMI_YES_NO;
  28 typedef TPM_ALG_ID TPMI_ALG_HASH;
  29 typedef TPM_HANDLE TPMI_DH_PCR;
  30 typedef TPM_HANDLE TPMI_RH_NV_INDEX;
  31 typedef TPM_HANDLE TPMI_RH_ENABLES;
  32 typedef TPM_HANDLE TPMI_SH_AUTH_SESSION;
  33 typedef TPM_HANDLE TPM_RH;
  34
  35 /* Some hardcoded algorithm values. */
  36 /* Table 7 - TPM_ALG_ID Constants */
  37 #define TPM_ALG_ERROR   ((TPM_ALG_ID)0x0000)
  38 #define TPM_ALG_HMAC    ((TPM_ALG_ID)0x0005)
  39 #define TPM_ALG_NULL    ((TPM_ALG_ID)0x0010)
  40 #define TPM_ALG_SHA1    ((TPM_ALG_ID)0x0004)
  41 #define TPM_ALG_SHA256  ((TPM_ALG_ID)0x000b)
  42 #define TPM_ALG_SHA384  ((TPM_ALG_ID)0x000C)
  43 #define TPM_ALG_SHA512  ((TPM_ALG_ID)0x000D)
  44 #define TPM_ALG_SM3_256 ((TPM_ALG_ID)0x0012)
  45
  46 /* Annex A Algorithm Constants */
  47
  48 /* Table 205 - Defines for SHA1 Hash Values */
  49 #define SHA1_DIGEST_SIZE    20
  50 /* Table 206 - Defines for SHA256 Hash Values */
  51 #define SHA256_DIGEST_SIZE  32
  52 /* Table 207 - Defines for SHA384 Hash Values */
  53 #define SHA384_DIGEST_SIZE  48
  54 /* Table 208 - Defines for SHA512 Hash Values */
  55 #define SHA512_DIGEST_SIZE  64
  56 /* Table 209 - Defines for SM3_256 Hash Values */
  57 #define SM3_256_DIGEST_SIZE 32
  58
  59 /* Some hardcoded hierarchies. */
  60 #define TPM_RH_NULL         0x40000007
  61 #define TPM_RS_PW           0x40000009
  62 #define TPM_RH_PLATFORM     0x4000000C
  63
  64 typedef uint32_t TPM_CC;
  65
  66 typedef struct {
  67         uint16_t      size;
  68         uint8_t       *buffer;
  69 } TPM2B;
  70
  71 /* Relevant TPM Command's structures. */
  72 /* Common command/response header. */
  73 struct tpm_header {
  74         uint16_t tpm_tag;
  75         uint32_t tpm_size;
  76         TPM_CC tpm_code;
  77 } __packed;
  78
  79 /* TPM command codes. */
  80 #define TPM2_Hierarchy_Control ((TPM_CC)0x00000121)
  81 #define TPM2_Clear             ((TPM_CC)0x00000126)
  82 #define TPM2_ClearControl      ((TPM_CC)0x00000127)
  83 #define TPM2_NV_DefineSpace    ((TPM_CC)0x0000012A)
  84 #define TPM2_NV_SetBits        ((TPM_CC)0x00000135)
  85 #define TPM2_NV_Write          ((TPM_CC)0x00000137)
  86 #define TPM2_NV_WriteLock      ((TPM_CC)0x00000138)
  87 #define TPM2_SelfTest          ((TPM_CC)0x00000143)
  88 #define TPM2_Startup           ((TPM_CC)0x00000144)
  89 #define TPM2_Shutdown          ((TPM_CC)0x00000145)
  90 #define TPM2_NV_Read           ((TPM_CC)0x0000014E)
  91 #define TPM2_GetCapability     ((TPM_CC)0x0000017A)
  92 #define TPM2_PCR_Extend        ((TPM_CC)0x00000182)
  93 /* TPM2 specifies vendor commands need to have this bit set. Vendor command
  94    space is defined by the lower 16 bits. */
  95 #define TPM_CC_VENDOR_BIT_MASK 0x20000000
  96
  97 /* Table 15 - TPM_RC Constants (Actions) */
  98 #define RC_FMT1                (TPM_RC)(0x080)
  99 #define TPM_RC_HASH            (TPM_RC)(RC_FMT1 + 0x003)
 100 #define TPM_RC_P               (TPM_RC)(0x040)
 101 #define TPM_RC_N_MASK          (TPM_RC)(0xF00)
 102
 103 /* Startup values. */
 104 #define TPM_SU_CLEAR 0
 105 #define TPM_SU_STATE 1
 106
 107 #define TPM_HT_PCR             0x00
 108 #define TPM_HT_NV_INDEX        0x01
 109 #define TPM_HT_HMAC_SESSION    0x02
 110 #define TPM_HT_POLICY_SESSION  0x03
 111
 112 #define HR_SHIFT               24
 113 #define HR_PCR                (TPM_HT_PCR <<  HR_SHIFT)
 114 #define HR_HMAC_SESSION       (TPM_HT_HMAC_SESSION <<  HR_SHIFT)
 115 #define HR_POLICY_SESSION     (TPM_HT_POLICY_SESSION <<  HR_SHIFT)
 116 #define HR_TRANSIENT          (TPM_HT_TRANSIENT <<  HR_SHIFT)
 117 #define HR_PERSISTENT         (TPM_HT_PERSISTENT <<  HR_SHIFT)
 118 #define HR_NV_INDEX           (TPM_HT_NV_INDEX <<  HR_SHIFT)
 119 #define HR_PERMANENT          (TPM_HT_PERMANENT <<  HR_SHIFT)
 120 #define PCR_FIRST             (HR_PCR + 0)
 121 #define PCR_LAST              (PCR_FIRST + IMPLEMENTATION_PCR-1)
 122 #define HMAC_SESSION_FIRST    (HR_HMAC_SESSION + 0)
 123 #define HMAC_SESSION_LAST     (HMAC_SESSION_FIRST+MAX_ACTIVE_SESSIONS-1)
 124 #define LOADED_SESSION_FIRST  HMAC_SESSION_FIRST
 125 #define LOADED_SESSION_LAST   HMAC_SESSION_LAST
 126 #define POLICY_SESSION_FIRST  (HR_POLICY_SESSION + 0)
 127 #define POLICY_SESSION_LAST   (POLICY_SESSION_FIRST + MAX_ACTIVE_SESSIONS-1)
 128 #define TRANSIENT_FIRST       (HR_TRANSIENT + 0)
 129 #define ACTIVE_SESSION_FIRST  POLICY_SESSION_FIRST
 130 #define ACTIVE_SESSION_LAST   POLICY_SESSION_LAST
 131 #define TRANSIENT_LAST        (TRANSIENT_FIRST+MAX_LOADED_OBJECTS-1)
 132 #define PERSISTENT_FIRST      (HR_PERSISTENT + 0)
 133 #define PERSISTENT_LAST       (PERSISTENT_FIRST + 0x00FFFFFF)
 134 #define PLATFORM_PERSISTENT   (PERSISTENT_FIRST + 0x00800000)
 135 #define NV_INDEX_FIRST        (HR_NV_INDEX + 0)
 136 #define NV_INDEX_LAST         (NV_INDEX_FIRST + 0x00FFFFFF)
 137 #define PERMANENT_FIRST       TPM_RH_FIRST
 138 #define PERMANENT_LAST        TPM_RH_LAST
 139
 140 /* Tpm2 command tags. */
 141 #define TPM_ST_NO_SESSIONS 0x8001
 142 #define TPM_ST_SESSIONS    0x8002
 143
 144 /* Values copied from tpm2/tpm_types.h */
 145 #define RC_VER1                                         0x100
 146 #define TPM_RC_INITIALIZE         ((TPM_RC)(RC_VER1 + 0x000))
 147 #define TPM_RC_NV_RANGE           ((TPM_RC)(RC_VER1 + 0x046))
 148 #define TPM_RC_NV_UNINITIALIZED   ((TPM_RC)(RC_VER1 + 0x04A))
 149
 150 /*
 151  * Cr50 returns this code when an attempt is made to read an NV location which
 152  * has not yet been defined. This is an aggregation of various return code
 153  * extensions which may or may not match if a different TPM2 device is
 154  * used.
 155  */
 156 #define TPM_RC_CR50_NV_UNDEFINED  0x28b
 157
 158 /* TPM command structures. */
 159
 160 struct tpm2_startup {
 161         TPM_SU  startup_type;
 162 };
 163
 164 struct tpm2_shutdown {
 165         TPM_SU  shutdown_type;
 166 };
 167
 168 /* Various TPM capability types to use when querying the device. */
 169 /* Table 21 - TPM_CAP Constants */
 170 typedef uint32_t TPM_CAP;
 171 #define TPM_CAP_PCRS             ((TPM_CAP)0x00000005)
 172 #define TPM_CAP_TPM_PROPERTIES   ((TPM_CAP)0x00000006)
 173
 174 typedef TPM_HANDLE TPMI_RH_NV_AUTH;
 175 typedef TPM_HANDLE TPMI_RH_NV_INDEX;
 176
 177 /* TPM Property capability constants. */
 178 typedef uint32_t TPM_PT;
 179 #define PT_GROUP                                   0x00000100
 180 #define PT_FIXED                               (PT_GROUP * 1)
 181 #define TPM_PT_FAMILY_INDICATOR      ((TPM_PT)(PT_FIXED + 0))
 182 #define TPM_PT_MANUFACTURER          ((TPM_PT)(PT_FIXED + 5))
 183 #define TPM_PT_FIRMWARE_VERSION_1   ((TPM_PT)(PT_FIXED + 11))
 184 #define TPM_PT_FIRMWARE_VERSION_2   ((TPM_PT)(PT_FIXED + 12))
 185 #define PT_VAR                                 (PT_GROUP * 2)
 186 #define TPM_PT_PERMANENT               ((TPM_PT)(PT_VAR + 0))
 187
 188 /* Structures of payloads of various TPM2 commands. */
 189 struct tpm2_get_capability {
 190         TPM_CAP capability;
 191         uint32_t property;
 192         uint32_t propertyCount;
 193 };
 194
 195 /* get_capability response when PT_PERMANENT is requested. */
 196 typedef struct {
 197         uint32_t ownerAuthSet       : 1;
 198         uint32_t endorsementAuthSet : 1;
 199         uint32_t lockoutAuthSet     : 1;
 200         uint32_t reserved3_7        : 5;
 201         uint32_t disableClear       : 1;
 202         uint32_t inLockout          : 1;
 203         uint32_t tpmGeneratedEPS    : 1;
 204         uint32_t reserved11_31      : 21;
 205 } TPMA_PERMANENT;
 206
 207 typedef struct {
 208         uint32_t TPMA_NV_PPWRITE        : 1;
 209         uint32_t TPMA_NV_OWNERWRITE     : 1;
 210         uint32_t TPMA_NV_AUTHWRITE      : 1;
 211         uint32_t TPMA_NV_POLICYWRITE    : 1;
 212         uint32_t TPMA_NV_COUNTER        : 1;
 213         uint32_t TPMA_NV_BITS           : 1;
 214         uint32_t TPMA_NV_EXTEND         : 1;
 215         uint32_t reserved7_9            : 3;
 216         uint32_t TPMA_NV_POLICY_DELETE  : 1;
 217         uint32_t TPMA_NV_WRITELOCKED    : 1;
 218         uint32_t TPMA_NV_WRITEALL       : 1;
 219         uint32_t TPMA_NV_WRITEDEFINE    : 1;
 220         uint32_t TPMA_NV_WRITE_STCLEAR  : 1;
 221         uint32_t TPMA_NV_GLOBALLOCK     : 1;
 222         uint32_t TPMA_NV_PPREAD         : 1;
 223         uint32_t TPMA_NV_OWNERREAD      : 1;
 224         uint32_t TPMA_NV_AUTHREAD       : 1;
 225         uint32_t TPMA_NV_POLICYREAD     : 1;
 226         uint32_t reserved20_24          : 5;
 227         uint32_t TPMA_NV_NO_DA          : 1;
 228         uint32_t TPMA_NV_ORDERLY        : 1;
 229         uint32_t TPMA_NV_CLEAR_STCLEAR  : 1;
 230         uint32_t TPMA_NV_READLOCKED     : 1;
 231         uint32_t TPMA_NV_WRITTEN        : 1;
 232         uint32_t TPMA_NV_PLATFORMCREATE : 1;
 233         uint32_t TPMA_NV_READ_STCLEAR   : 1;
 234 } TPMA_NV;
 235
 236 typedef union {
 237         struct {
 238                 uint16_t  size;
 239                 const uint8_t   *buffer;
 240         } t;
 241         TPM2B b;
 242 } TPM2B_DIGEST;
 243
 244 typedef TPM2B_DIGEST TPM2B_AUTH;
 245 typedef TPM2B_DIGEST TPM2B_NONCE;
 246
 247 typedef struct {
 248         TPM_PT  property;
 249         uint32_t  value;
 250 } TPMS_TAGGED_PROPERTY;
 251
 252 #define MAX_CAP_DATA (TPM_BUFFER_SIZE - sizeof(struct tpm_header) - \
 253                       sizeof(TPMI_YES_NO) - sizeof(TPM_CAP) - sizeof(uint32_t))
 254 #define MAX_TPM_PROPERTIES  (MAX_CAP_DATA/sizeof(TPMS_TAGGED_PROPERTY))
 255
 256 #define IMPLEMENTATION_PCR            24
 257 #define PLATFORM_PCR                  24
 258
 259 #define PCR_SELECT_MIN                (ALIGN_UP(PLATFORM_PCR, 8)/8)
 260 #define PCR_SELECT_MAX                (ALIGN_UP(IMPLEMENTATION_PCR, 8)/8)
 261
 262 /* Somewhat arbitrary, leave enough room for command wrappers. */
 263 #define MAX_NV_BUFFER_SIZE (TPM_BUFFER_SIZE - sizeof(struct tpm_header) - 50)
 264
 265 /* Table 81 - TPMS_PCR_SELECTION Structure */
 266 typedef struct {
 267         TPMI_ALG_HASH   hash;
 268         uint8_t         sizeofSelect;
 269         uint8_t         pcrSelect[PCR_SELECT_MAX];
 270 } __packed TPMS_PCR_SELECTION;
 271
 272 /* Table 98 - TPML_PCR_SELECTION Structure */
 273 typedef struct {
 274         uint32_t           count;
 275         TPMS_PCR_SELECTION pcrSelections[HASH_COUNT];
 276 } __packed TPML_PCR_SELECTION;
 277
 278 /* Table 100 - TPML_TAGGED_TPM_PROPERTY Structure */
 279 typedef struct {
 280         uint32_t              count;
 281         TPMS_TAGGED_PROPERTY  tpmProperty[MAX_TPM_PROPERTIES];
 282 } TPML_TAGGED_TPM_PROPERTY;
 283
 284 typedef union {
 285         TPML_TAGGED_TPM_PROPERTY  tpmProperties;
 286         TPML_PCR_SELECTION        assignedPCR;
 287 } TPMU_CAPABILITIES;
 288
 289 typedef struct {
 290         TPM_CAP            capability;
 291         TPMU_CAPABILITIES  data;
 292 } TPMS_CAPABILITY_DATA;
 293
 294 struct get_cap_response {
 295         TPMI_YES_NO more_data;
 296         TPMS_CAPABILITY_DATA cd;
 297 };
 298
 299 typedef struct {
 300         TPMI_RH_NV_INDEX  nvIndex;
 301         TPMI_ALG_HASH     nameAlg;
 302         TPMA_NV           attributes;
 303         TPM2B_DIGEST      authPolicy;
 304         uint16_t          dataSize;
 305 } TPMS_NV_PUBLIC;
 306
 307 typedef union {
 308         struct {
 309                 uint16_t        size;
 310                 TPMS_NV_PUBLIC  nvPublic;
 311         } t;
 312         TPM2B b;
 313 } TPM2B_NV_PUBLIC;
 314
 315 typedef union {
 316         struct {
 317                 uint16_t  size;
 318                 const uint8_t   *buffer;
 319         } t;
 320         TPM2B b;
 321 } TPM2B_MAX_NV_BUFFER;
 322
 323 /* Table 66 - TPMU_HA Union */
 324 typedef union {
 325         uint8_t sha1[SHA1_DIGEST_SIZE];
 326         uint8_t sha256[SHA256_DIGEST_SIZE];
 327         uint8_t sm3_256[SM3_256_DIGEST_SIZE];
 328         uint8_t sha384[SHA384_DIGEST_SIZE];
 329         uint8_t sha512[SHA512_DIGEST_SIZE];
 330 } TPMU_HA;
 331
 332 typedef struct {
 333         TPMI_ALG_HASH  hashAlg;
 334         TPMU_HA        digest;
 335 } TPMT_HA;
 336
 337 /* Table 96 -- TPML_DIGEST_VALUES Structure <I/O> */
 338 typedef struct {
 339         uint32_t   count;
 340         TPMT_HA digests[HASH_COUNT];
 341 } TPML_DIGEST_VALUES;
 342
 343 struct nv_read_response {
 344         uint32_t params_size;
 345         TPM2B_MAX_NV_BUFFER buffer;
 346 };
 347
 348 struct vendor_command_response {
 349         uint16_t vc_subcommand;
 350         union {
 351                 uint8_t num_restored_headers;
 352                 uint8_t recovery_button_state;
 353                 uint8_t tpm_mode;
 354                 uint8_t boot_mode;
 355                 /*
 356                  * bits 63..8 : reserved
 357                  * bits 7..0 : factory config
 358                  */
 359                 uint64_t factory_config;
 360         };
 361 };
 362
 363 struct tpm2_session_attrs {
 364         uint8_t continueSession : 1;
 365         uint8_t auditExclusive  : 1;
 366         uint8_t auditReset      : 1;
 367         uint8_t reserved3_4     : 2;
 368         uint8_t decrypt         : 1;
 369         uint8_t encrypt         : 1;
 370         uint8_t audit           : 1;
 371 };
 372
 373 /*
 374  * TPM session header for commands requiring session information. Also
 375  * included in the responses to those commands.
 376  */
 377 struct tpm2_session_header {
 378         uint32_t session_handle;
 379         uint16_t nonce_size;
 380         uint8_t *nonce;
 381         union {
 382                 struct tpm2_session_attrs session_attr_bits;
 383                 uint8_t session_attrs;
 384         }  __packed;
 385         uint16_t auth_size;
 386         uint8_t *auth;
 387 };
 388
 389 struct tpm2_response {
 390         struct tpm_header hdr;
 391         union {
 392                 struct get_cap_response gc;
 393                 struct nv_read_response nvr;
 394                 struct tpm2_session_header def_space;
 395                 struct vendor_command_response vcr;
 396         };
 397 };
 398
 399 struct tpm2_nv_define_space_cmd {
 400         TPM2B_AUTH auth;
 401         TPMS_NV_PUBLIC publicInfo;
 402 };
 403
 404 struct tpm2_nv_write_cmd {
 405         TPMI_RH_NV_INDEX nvIndex;
 406         TPM2B_MAX_NV_BUFFER data;
 407         uint16_t offset;
 408 };
 409
 410 struct tpm2_nv_setbits_cmd {
 411         TPMI_RH_NV_INDEX nvIndex;
 412         uint64_t bits;
 413 };
 414
 415 struct tpm2_self_test {
 416         TPMI_YES_NO yes_no;
 417 };
 418
 419 struct tpm2_nv_read_cmd {
 420         TPMI_RH_NV_INDEX nvIndex;
 421         uint16_t size;
 422         uint16_t offset;
 423 };
 424
 425 struct tpm2_nv_write_lock_cmd {
 426         TPMI_RH_NV_INDEX nvIndex;
 427 };
 428
 429 struct tpm2_pcr_extend_cmd {
 430         TPMI_DH_PCR pcrHandle;
 431         TPML_DIGEST_VALUES digests;
 432 };
 433
 434 struct tpm2_clear_control_cmd {
 435         TPMI_YES_NO disable;
 436 };
 437
 438 struct tpm2_hierarchy_control_cmd {
 439         TPMI_RH_ENABLES enable;
 440         TPMI_YES_NO state;
 441 };
 442
 443 #endif // TCG2_TSS_STRUCTURES_H_