ISO/IEC 11889-4:2015

Information technology - Trusted Platform Module Library - Part 4: Supporting Routines

ISO/IEC 11889-4:2015 contains C code that describes the algorithms and methods used by the command code in ISO/IEC 11889-3. The code in ISO/IEC 11889-4:2015 augments ISO/IEC 11889-2 and ISO/IEC 11889-3 to provide a complete description of a TPM, including the supporting framework for the code that performs the command actions. Any code in ISO/IEC 11889-4:2015 may be replaced by code that provides similar results when interfacing to the action code in ISO/IEC 11889-3. The behavior of code in this ISO/IEC 11889-4:2015 that is not included in an annex is normative, as observed at the interfaces with ISO/IEC 11889-3 code. Code in an annex is provided for completeness, that is, to allow a full implementation of ISO/IEC 11889 from the provided code. The code in ISO/IEC 11889-3 and this ISO/IEC 11889-4:2015 is written to define the behavior of a compliant TPM. In some cases (e.g., firmware update), it is not possible to provide a compliant implementation. In those cases, any implementation provided by the vendor that meets the general description of the function provided in ISO/IEC 11889-3 would be compliant. The code in ISO/IEC 11889-3 and this ISO/IEC 11889-4:2015 is not written to meet any particular level of conformance nor does ISO/IEC 11889 require that a TPM meet any particular level of conformance.

Technologies de l'information — Bibliothèque de module de plate-forme de confiance — Partie 4: Routines de support

General Information

• Status: Published
• Publication Date: 14-Dec-2015
• ICS: 35.030 - IT Security
• ICS: 35.040 - Information coding
• Technical Committee: ISO/IEC JTC 1 - Information technology
• Drafting Committee: ISO/IEC JTC 1 - Information technology
• Current Stage: 9093 - International Standard confirmed
• Start Date: 06-May-2021
• Completion Date: 30-Oct-2025

Relations

• Revises: ISO/IEC 11889-4:2009 - Information technology - Trusted Platform Module - Part 4: Commands
• Effective Date: 10-May-2014

Overview

ISO/IEC 11889-4:2015 - Information technology - Trusted Platform Module Library - Part 4: Supporting Routines - is a standards document that provides the C reference code and supporting framework used to define the behavior of a compliant Trusted Platform Module (TPM). It supplements ISO/IEC 11889-2 and ISO/IEC 11889-3 by describing algorithms, utility routines, header files and runtime scaffolding that the TPM command code relies on. The standard clarifies which code is normative at interfaces with the command implementations and includes annex material for a complete reference implementation.

Key technical topics and requirements

• Reference C code: Canonical routines and algorithms implemented in C that describe TPM supporting behavior; implementations may substitute alternative code that produces equivalent results.
• Normative vs. annex code: Behavior of code not in annex sections is normative at TPM/command interfaces; annex code is provided for completeness to enable full implementations.
• Automation and parsers: Configuration parser, structure (marshal/unmarshal) parsers, and command parser definitions to support command handling and portability.
• Header and type definitions: Standardized header files (e.g., BaseTypes.h, Global.h, Tpm.h) and core type/bit definitions used across TPM modules.
• Core runtime routines: Command dispatching, command execution (ExecuteCommand), session processing, handle parsing and authorization support.
• Subsystem utilities: Support for attestation, context management, policy, NV (non-volatile) storage, object management, PCR handling, sessions, time, and other TPM subsystems.
• Portability and implementation notes: Guidance on platform portability and vendor-specific implementations (e.g., firmware update paths) while preserving conformance at functional interfaces.
• No specific conformance level mandated: The standard defines behavior but does not require a particular conformance testing level.

Practical applications

• Building or porting TPM firmware and reference implementations using the provided C supporting routines.
• Implementing TPM command handlers and ensuring correct marshaling/unmarshaling, session and authorization handling.
• Creating interoperable TPM libraries for secure hardware root-of-trust features such as secure boot, attestation, key storage, and NV index management.
• Using the reference code for security reviews, implementation validation, and as a learning resource for TPM internals.

Who should use ISO/IEC 11889-4:2015

• TPM implementers and firmware engineers
• Device and platform manufacturers integrating hardware security modules
• Operating system and hypervisor developers providing TPM interfaces
• Security architects, auditors, and researchers analyzing TPM behavior
• Cryptographic library authors and test-suite developers

Related standards

• ISO/IEC 11889-2 - (Core structures/specifications referenced)
• ISO/IEC 11889-3 - (TPM command code; ISO/IEC 11889-4 provides supporting routines used by Part 3)

Keywords: ISO/IEC 11889-4:2015, Trusted Platform Module, TPM library, supporting routines, TPM C code, command dispatcher, TPM implementation, TPM firmware, NV storage, PCR, attestation.

Standards Content (Sample)

INTERNATIONAL ISO/IEC
STANDARD 11889-4
Second edition
2015-12-15
Information technology — Trusted
Platform Module Library —
Part 4:
Supporting Routines
Technologies de l’information — Bibliothèque de module
de plate-forme de confiance —
Partie 4: Routines de support
Reference number
©
ISO/IEC 2015
© ISO/IEC 2015, Published in Switzerland
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form
or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior
written permission. Permission can be requested from either ISO at the address below or ISO’s member body in the country of
the requester.
ISO copyright office
Ch. de Blandonnet 8 • CP 401
CH-1214 Vernier, Geneva, Switzerland
Tel. [phone]
Fax [phone]
[e-mail]
www.iso.org
ii © ISO/IEC 2015 – All rights reserved

CONTENTS
Foreword . xvii
Introduction . xviii
1 Scope . 1
2 Normative references . 2
3 Terms and definitions . 2
4 Symbols and abbreviated terms . 2
5 Automation . 2
5.1 Introduction . 2
5.2 Configuration Parser . 2
5.3 Structure Parser . 3
5.3.1 Introduction . 3
5.3.2 Unmarshaling Code Prototype . 3
5.3.3 Marshaling Code Function Prototypes . 5
5.4 Command Parser . 6
5.5 Portability . 6
6 Header Files . 7
6.1 Introduction . 7
6.2 BaseTypes.h . 7
6.3 bits.h . 8
6.4 bool.h . 9
6.5 Capabilities.h . 9
6.6 TPMB.h . 9
6.7 TpmError.h . 10
6.8 Global.h . 10
6.8.1 Description . 10
6.8.2 Includes. 11
6.8.3 Defines and Types . 11
6.8.4 Loaded Object Structures . 12
6.8.5 AUTH_DUP Types . 14
6.8.6 Active Session Context . 14
6.8.7 PCR . 16
6.8.8 Startup . 17
6.8.9 NV . 18
6.8.10 COMMIT_INDEX_MASK . 19
6.8.11 RAM Global Values . 19
6.8.12 Persistent Global Values . 21
6.8.13 Global Macro Definitions . 26
6.9 Private data . 26
6.10 Tpm.h . 31
6.11 swap.h . 31
6.12 InternalRoutines.h . 32
6.13 TpmBuildSwitches.h . 33
6.14 VendorString.h . 34
7 Main . 36
7.1 CommandDispatcher() . 36
7.2 ExecCommand.c . 36
7.2.1 Introduction . 36
7.2.2 Includes. 36
7.2.3 ExecuteCommand() . 36
© ISO/IEC 2015 – All rights reserved iii

7.3 ParseHandleBuffer() . 42
7.4 SessionProcess.c . 43
7.4.1 Introduction . 43
7.4.2 Includes and Data Definitions . 43
7.4.3 Authorization Support Functions . 43
7.4.4 Session Parsing Functions . 50
7.4.5 Response Session Processing . 68
8 Command Support Functions . 78
8.1 Introduction . 78
8.2 Attestation Command Support (Attest_spt.c) . 78
8.2.1 Includes. 78
8.2.2 Functions . 78
8.3 Context Management Command Support (Context_spt.c) . 81
8.3.1 Includes. 81
8.3.2 Functions . 81
8.4 Policy Command Support (Policy_spt.c) . 83
8.4.1 Includes. 83
8.4.2 Functions . 83
8.5 NV Command Support (NV_spt.c) . 85
8.5.1 Includes. 85
8.5.2 Functions . 86
8.6 Object Command Support (Object_spt.c) . 88
8.6.1 Includes. 88
8.6.2 Local Functions . 88
8.6.3 Public Functions . 93
9 Subsystem . 113
9.1 CommandAudit.c . 113
9.1.1 Introduction . 113
9.1.2 Includes. 113
9.1.3 Functions . 113
9.2 DA.c . 11 7
9.2.1 Introduction . 117
9.2.2 Includes and Data Definitions . 117
9.2.3 Functions . 117
9.3 Hierarchy.c . 120
9.3.1 Introduction . 120
9.3.2 Includes. 120
9.3.3 Functions . 120
9.4 NV.c . 12 4
9.4.1 Introduction . 124
9.4.2 Includes, Defines and Data Definitions . 124
9.4.3 NV Utility Functions . 124
9.4.4 NV Index and Persistent Object Access Functions . 126
9.4.5 RAM-based NV Index Data Access Functions . 130
9.4.6 Utility Functions . 132
9.4.7 NV Access Functions . 140
9.5 Object.c . 158
iv © ISO/IEC 2015 – All rights reserved

9.5.1 Introduction . 158
9.5.2 Includes and Data Definitions . 158
9.5.3 Functions . 158
9.6 PCR.c . 174
9.6.1 Introduction . 174
9.6.2 Includes, Defines, and Data Definitions . 174
9.6.3 Functions . 174
9.7 PP.c . 19 6
9.7.1 Introduction . 196
9.7.2 Includes. 196
9.7.3 Functions . 196
9.8 Session.c . 199
9.8.1 Introduction . 199
9.8.2 Includes, Defines, and Local Variables . 200
9.8.3 File Scope Function -- ContextIdSetOldest() . 200
9.8.4 Startup Function -- SessionStartup() . 201
9.8.5 Access Functions . 202
9.8.6 Utility Functions . 204
9.9 Time.c . 216
9.9.1 Introduction . 216
9.9.2 Includes. 216
9.9.3 Functions . 216
10 Support . 221
10.1 AlgorithmCap.c . 221
10.1.1 Description . 221
10.1.2 Includes and Defines . 221
10.1.3 AlgorithmCapGetImplemented() . 222
10.2 Bits.c . 224
10.2.1 Introduction . 224
10.2.2 Includes. 224
10.2.3 Functions . 224
10.3 CommandAttributeData.c . 225
10.4 CommandCodeAttributes.c . 231
10.4.1 Introduction . 231
10.4.2 Includes and Defines . 231
10.4.3 Command Attribute Functions . 231
10.5 DRTM.c . 236
10.5.1 Description . 236
10.5.2 Includes. 236
10.5.3 Functions . 236
10.6 Entity.c . 237
10.6.1 Description . 237
10.6.2 Includes. 237
10.6.3 Functions . 237
10.7 Global.c . 243
10.7.1 Description . 243
10.7.2 Includes and Defines . 244
10.7.3 Global Data Values . 244
© ISO/IEC 2015 – All rights reserved v

10.7.4 Private Values . 244
10.8 Handle.c . 246
10.8.1 Description . 246
10.8.2 Includes. 246
10.8.3 Functions . 246
10.9 Locality.c . 24 8
10.9.1 Includes. 248
10.9.2 LocalityGetAttributes() . 248
10.10 Manufacture.c . 248
10.10.1 Description . 248
10.10.2 Includes and Data Definitions . 248
10.10.3 Functions . 249
10.11 Marshal.c . 251
10.11.1 Introduction . 251
10.11.2 Unmarshal and Marshal a Value . 251
10.11.3 Unmarshal and Marshal a Union . 252
10.11.4 Unmarshal and Marshal a Structure . 254
10.11.5 Unmarshal and Marshal an Array . 256
10. 11.6 TPM2B Handling . 258
10.12 MemoryLib.c . 259
10.12.1 Description . 259
10.12.2 Includes and Data Definitions . 259
10.12.3 Functions on BYTE Arrays . 259
10.13 Power.c . 26 4
10.13.1 Description . 264
10.13.2 Includes and Data Definitions . 264
10.13.3 Functions . 264
10.14 PropertyCap.c . 265
10.14.1 Description . 265
10.14.2 Includes. 265
10.14.3 Functions . 265
10.15 TpmFail.c . 273
10.15.1 Includes, Defines, and Types . 273
10.15.2 Typedefs . 273
10.15.3 Local Functions . 274
10.15.4 Public Functions . 275
10.15.5 TpmFailu reMode . 275
11 Cryptographic Functions . 279
11.1 Introduction . 279
11.2 CryptUtil.c . 279
11.2.1 Introduction . 279
11.2.2 Includes. 279
11.2.3 TranslateCryptErrors() . 279
11.2.4 Random Number Generation Functions . 280
11.2.5 Hash/HMAC Functions . 281
11.2.6 RSA Functions . 294
11.2.7 ECC Functions . 302
11.2.8 Symmetric Functions . 312
11.2.9 Initialization and shut down . 316
vi © ISO/IEC 2015 – All rights reserved

11.2.10 Algorithm-Independent Functions . 317
11.2.11 Math functions . 339
11.2.12 Capability Support . 341
11.3 Ticket.c . 34 3
11.3.1 Introduction . 343
11.3.2 Includes. 343
11.3.3 Functions . 343
11.4 CryptSelfTest.c . 346
11.4.1 Introduction . 346
11.4.2 Functions . 347
Annex A (informative) Implementation Dependent . 351
A.1 Introduction . 351
A.2 Implementation.h . 351
Annex B (informative) Cryptographic Library Interface . 365
B.1 Introduction . 365
B.2 Integer Format . 365
B.3 CryptoEngine.h . 365
B.3.1. Introduction . 365
B.3.2. General Purpose Macros. 366
B.3.3. Self-test . 366
B.3.4. Hash-related Structures . 366
B.3.5. Asymmetric Structures and Values . 368
B.3.6. ECC-related Structures . 368
B.3.7. RSA-related Structures . 368
B.4 OsslCryptoEngine.h . 370
B.4.1. Introduction . 370
B.4.2. Defines . 370
B.5 MathFunctions.c . 371
B.5.1. Introduction . 371
B.5.2. Externally Accessible Functions . 371
B.6 CpriCryptP ri.c . 381
B.6.1. Introduction . 381
B.6.2. Includes and Locals . 381
B.6.3. Functions . 381
B.7 CpriRNG.c . 383
B.7.1. Introduction . 383
B.7.2. Defines . 383
B.7.3. Includes and Values. 383
B.7.4. Functions . 383
B.8 CpriHash.c . 386
B.8.1. Description . 386
B.8.2. Includes, Defines, and Types . 386
B.8.3. Static Functions . 386
B.8.4. Hash Functions . 388
B.8.5. HMAC Functions . 395
B.8.6. Mask and Key Generation Functions . 397
B.9 CpriHashData.c . 402
B.10 CpriMisc.c . 403
© ISO/IEC 2015 – All rights reserved vii

B.10.1. Includes. 403
B.10.2. Functions . 403
B.11 CpriSym.c . 405
B.11.1. Introduction . 405
B.11.2. Includes, Defines, and Typedefs . 405
B.11.3. Utility Functions . 406
B.11.4. Symmetric Encryption . 407
B.12 RSA Files . 412
B.12.1. CpriRSA.c . 412
B.12.2. Alternative RSA Key Generation . 436
B.13 Elliptic Curve Files . 467
B.13.1. CpriDataEcc.h . 467
B.13.2. CpriDataEcc.c . 468
B.13.3. CpriECC.c . 471
Annex C (informative) Simulation Environment . 509
C.1 Introduction . 509
C.2 Cancel.c . 509
C.2.1. Introduction . 509
C.2.2. Includes, Typedefs, Structures, and Defines . 509
C.2.3. Functions . 509
C.3 Clock.c . 511
C.3.1. Introduction . 511
C.3.2. Includes and Data Definitions . 511
C.3.3. Functions . 511
C.4 Entropy.c . 513
C.4.1. Includes and Defines . 513
C.4.2. Local values . 513
C.4.3. _plat__Get E n t r opy ( ). 513
C.5 LocalityPlat.c . 515
C.5.1. Includes. 515
C.5.2. Functions . 515
C.6 NVMem.c . 516
C.6.1. Introduction . 516
C.6.2. Includes. 516
C.6.3. Functions . 516
C.7 PowerPlat.c . 521
C.7.1. Includes. 521
C.7.2. Functions . 521
C.8 Platform.h . 523
C.8.1. Includes and Defines . 523
C.8.2. Power Functions . 523
C.8.3. Physical Presence Functions . 523
C.8.4. Command Canceling Functions . 524
C.8.5. NV memory functions . 525
C.8.6. Locality Functions . 527
C.8.7. Clock Constants and Functions . 527
C.8.8. Entropy Function _plat__GetEn tr opy() . 529
viii © ISO/IEC 2015 – All rights reserved

C.9 PlatformData.h . 530
C.10 PlatformData.c . 531
C.10.1. Description . 531
C.10.2. Incl udes. 531
C.11 PPPlat.c . 532
C.11.1. Description . 532
C.11.2. Incl udes. 532
C.11.3. Functions . 532
C.12 Unique.c . 534
C.12.1. Introduction . 534
C.12.2. Incl udes. 534
C.12.3. _plat__GetUnique() . 534
Annex D (informative) Remote Procedure Interface . 535
D.1 Introduction . 535
D.2 TpmTcpProtocol.h . 536
D.2.1. Introduction . 536
D.2.2. Defines . 536
D.2.3. Typedefs . 536
D.3 TcpServer.c . 538
D.3.1. Description . 538
D.3.2. Includes, Locals, Defines and Function Prototypes . 538
D.3.3. Functions . 538
D.4 TPMCmdp.c . 548
D.4.1. Description . 548
D.4.2. Includes and Data Definitions . 548
D.4.3. Functions . 548
D.5 TPMCmds.c . 554
D.5.1. Description . 554
D.5.2. Includes, Defines, Data Definitions, and Function Prototypes . 554
D.5.3. Functions . 554
Bibliography . 556
© ISO/IEC 2015 – All rights reserved ix

Tables
Table 1 . 43
Table 2 . 44
Table 3 . 46
Table 4 . 46
Table 5 . 47
Table 6 . 49
Table 7 . 52
Table 8 . 54
Table 9 . 55
Table 10 . 58
Table 11 . 61
Table 12 . 62
Table 13 . 64
Table 14 . 64
Table 15 . 67
Table 16 . 78
Table 17 . 80
Table 18 . 86
Table 19 .
...