S
P
E
C
I
F
I
C
A
T
I
O
N

MARS API Specification
Version 1
Revision 0
February 10, 2023
Contact: admin@trustedcomputinggroup.org
PUBLIC REVIEWWork in ProgressThis document is an intermediate draft
for comment only and is subject tochange without notice. Readers should
not design products based on thisdocument.

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW© TCG 2023

MARS API Specification

DISCLAIMERS, NOTICES, AND LICENSE TERMS
THIS SPECIFICATION IS PROVIDED “AS IS” WITH NO WARRANTIES WHATSOEVER, INCLUDINGANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY
PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL,
SPECIFICATION OR SAMPLE.
Without limitation, TCG disclaims all liability, including liability for infringement of any proprietary rights,
relating to use of information in this specification and to the implementation of this specification, and
TCG disclaims all liability for cost of procurement of substitute goods or services, lost profits, loss ofuse, loss of data or any incidental, consequential, direct, indirect, or special damages, whether undercontract, tort, warranty or otherwise, arising in any way out of use or reliance upon this specification or
any information herein.
This document is copyrighted by Trusted Computing Group (TCG), and no license, express or implied,
is granted herein other than as follows: You may not copy or reproduce the document or distribute it
to others without written permission from TCG, except that you may freely do so for the purposes of (a)examining or implementing TCG specifications or (b) developing, testing, or promoting information
technology standards and best practices, so long as you distribute the document with these disclaimers,
notices, and license terms.
Contact the Trusted Computing Group at www.trustedcomputinggroup.org for information on
specification licensing through membership agreements.
Any marks and brands contained herein are the property of their respective owners.

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 1© TCG 2023

MARS API Specification

ACKNOWLEDGEMENTS
The TCG would like to gratefully acknowledge the contributions of the following individuals andcompanies who volunteered their time and efforts for the development of this specification.
Joerg Borchert – Infineon
Tom Brostrom – Cyber Pack Ventures, Inc.
Eoin Carroll – Toyota Motor Corporation
Brian Dziki – USG
Mariza Marerro – USG
Vadim Sukhomlinov – Google LLC
Dick Wilkins – Phoenix Technologies, Inc.

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 2© TCG 2023

MARS API Specification

CONTENTSDISCLAIMERS, NOTICES, AND LICENSE TERMS ............................................................................ 1
ACKNOWLEDGEMENTS ..................................................................................................................... 2
CONTENTS .......................................................................................................................................... 3
TABLES ................................................................................................................................................ 5
Scope ............................................................................................................................................ 6
1.1 Key Words ............................................................................................................................. 6
1.2 Statement Type ..................................................................................................................... 6
Abbreviations, Acronyms and Terms Used ................................................................................... 7
Introduction.................................................................................................................................... 8
3.1 Serialized Architecture........................................................................................................... 8
3.2 Memory Mapped Architecture................................................................................................ 9
API............................................................................................................................................... 10
4.1 Response Codes ................................................................................................................. 10
4.2 Transport ............................................................................................................................. 10
4.3 Commands .......................................................................................................................... 10
4.3.1 Command Interface .................................................................................................... 10
4.3.2 Initialization ................................................................................................................. 11
4.3.2.1 Prototype ............................................................................................................... 11
4.3.2.2 Response Codes ................................................................................................... 11
4.3.3 Threading ................................................................................................................... 11
4.3.3.1 MARS_Lock .......................................................................................................... 12
4.3.3.2 MARS_Unlock ....................................................................................................... 12
4.4 Single Threading ................................................................................................................. 13
Header Files ................................................................................................................................ 14
5.1 mars/api.h ............................................................................................................................ 14
5.2 mars/mars.h......................................................................................................................... 14
5.2.1 Prelude ....................................................................................................................... 14
5.2.2 Property Tags ............................................................................................................. 14
5.2.3 Response Codes ........................................................................................................ 15
5.2.4 Management Commands ........................................................................................... 15
5.2.5 Sequence Primitives ................................................................................................... 15
5.2.6 Integrity Collection Commands ................................................................................... 15
5.2.7 Key Management Commands .................................................................................... 16
MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 3© TCG 2023

MARS API Specification

5.2.8 Attestation Commands ............................................................................................... 16
5.2.9 Command Codes........................................................................................................ 17
Bibliography ................................................................................................................................. 18

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 4© TCG 2023

MARS API Specification

TABLES
Table 1 – Additional Response Codes ................................................................................................ 10

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 5© TCG 2023

MARS API Specification

Scope
This document is the Measurement and Attestation RootS (MARS) Application Programmer Interface(API) Specification. It defines a C-language interface for host application code to utilize a MARS device.
Host application code means any software/firmware executing on a host including UEFI, boot loaders,
operating system, loadable libraries, and high-level applications. The intended audience for thisspecification includes software developers and designers implementing applications for MARS as
specified in (TCG, 2023).

1.1 Key Words
The key words “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD
NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” in this document form normative statements andare to be interpreted as described in RFC-2119, Key words for use in RFCs to Indicate Requirement
Levels.

1.2 Statement Type
Please note a very important distinction between different sections of text throughout this document.
There are two distinctive kinds of text: informative comment and normative statements. Because mostof the text in this specification will be of the kind normative statements, the authors have informallydefined it as the default and, as such, have specifically called out text which is of the kind informative
comment. They have done this by flagging the beginning and end of each informative comment andhighlighting its text in gray. This means that unless text is specifically marked as of the kind informative
comment, it can be considered a kind of normative statement.
EXAMPLE: Start of informative comment
This is the first paragraph of 1–n paragraphs containing text of the kind informative comment ...
This is the second paragraph of text of the kind informative comment ...
This is the nth paragraph of text of the kind informative comment ...
To understand the TCG specification the user must read the specification. (This use of MUST does not require
any action).
End of informative comment

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 6© TCG 2023

MARS API Specification

Abbreviations, Acronyms and Terms Used
API

Application Programmer Interface

host

A computing platform with an attached MARS device

MARS

Measurement and Attestation RootS

MMIO

Memory Mapped Input Output

TCG

Trusted Computing Group

UEFI

Unified Extensible Firmware Interface

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 7© TCG 2023

MARS API Specification

Introduction
The purpose of this API specification is to enable seamless usage of all available MARS commands
with minimal dependency on the choice of MARS architecture or how commands, parameters andresponses are formatted and delivered. The remainder of section 3 is informative.
Start of informative comment
MARS architectures are described here as serialized or memory mapped. This specification does notplace limits on the type of MARS architecture.

3.1 Serialized Architecture
Externally attached MARS devices (e.g., outside the host’s microcontroller die) are accessed via
serialization. In a serialized MARS architecture, each command to and response from the MARS
device is marshaled into individual blocks that are then transmitted. An API command that is designed
to take a potentially large parameter (such as MARS_SequenceUpdate()) may need to be
implemented to fragment the parameter to fit within message length limits, resulting in multiplecommands issued by the API to MARS. This action is transparent to the caller of the API.
The position of the API layer in the serialized logical architecture is shown in Figure 1.
HOST
APPLICATION

MARS

API

DISPATCHERSERIALIZATIONSERIALIZATIONCOMMAND

TRANSPORT

TRANSPORT

CRYPTO

Figure 1 – MARS Serialized Architecture

A description of each of the logical layers follows:••••

Application – software/firmware using the MARS API
API – the layer described by this specification
Serialization – marshals and unmarshalls commands, parameters and responses between thehost API and the MARS dispatcher
Transport – delivers serialized data between the host and MARSMARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 8© TCG 2023

MARS API Specification••

Command – implements the MARS commands as defined in the MARS Library Specification
Crypto – cryptographic services utilized by MARS Commands

3.2 Memory Mapped ArchitectureInternally attached MARS devices (e.g., within the host’s microcontroller die) are accessed using thehost’s MMIO functionality. An MMIO-based MARS architecture can be depicted as shown in Figure
2. Since it may not be necessary to serialize commands into blocks, as with the MARS serializedarchitecture, large parameters could be streamed to MARS via direct register writes.
HOST
APPLICATION

MARS

API

COMMAND

MMIO

MMIO

CRYPTO

Figure 2 – MARS Memory Mapped Architecture
A description of each of the logical layers follows:
•
•
•
•
•

Application – software/firmware using the MARS API
API – the layer described by this specification
MMIO – a memory mapped input/output device controller for an internally attached MARS
deviceCommand – implements the MARS commands as defined in the MARS Library Specification
Crypto – cryptographic services utilized by MARS Commands

End of informative comment

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 9© TCG 2023

MARS API Specification

API
4.1 Response Codes
When MARS API commands (see section 4.3) succeed, they SHALL return a response code of
MARS_RC_SUCCESS along with their specified results. When a requested MARS API commandcannot perform its function, then it SHALL return a single response code from the table of Response
Code Constants (TCG, 2023) other than MARS_RC_SUCCESS. This API SHALL return
MARS_RC_COMMAND for commands that are not supported. Additionally, the API SHALL return a
response code of MARS_RC_LOCK in the event of locking errors (see Table 1 and section 4.3.3).
Table 1 – Additional Response Codes
Name
MARS_RC_LOCK

Value
3

Description
not locked or calling thread already locked

4.2 Transport
Start of informative comment
The MARS API assumes that the transport mechanism used by the API in the MARS SerializedArchitecture has been properly initialized prior to use of any other MARS API functions. Refer todocumentation from the provider of the MARS API for more detail.
End of informative comment

4.3 Commands
A MARS API MUST implement all the functions described in this section.
4.3.1 Command Interface
To make usage of MARS commands as seamless as possible, the API MUST implement all the MARS
Command Interface definitions specified in (TCG, 2023). Thus, the dispatcher can be viewed as a proxy
for the host API.
Start of informative comment
In this API, MARS_RegRead() uses the serialization and transport layers to convey the command code
MARS_CC_RegRead (from section 5.2.9) and its parameter regIndex to the MARS dispatcher. The
MARS dispatcher then invokes its MARS_RegRead() that retrieves the contents of the specified
register. The dispatcher then serializes and transports the response code MARS_RC_SUCCESS(assuming the register index was valid) and the copied register back to the host API where they are
returned to the calling application.
End of informative comment
MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 10© TCG 2023

MARS API Specification

4.3.2 Initialization
MARS_ApiInit() is responsible for setting the initial context needed by the MARS API, such as its mutex
and constants retrieved from the MARS device. MARS_ApiInit() is designed to be used once after
transport initialization (see section 4.2) and before other MARS API functions are called. If not used inthis manner, the MARS API functions SHALL return MARS_RC_IO.
4.3.2.1 Prototype
MARS_RC MARS_ApiInit ();4.3.2.2 Response Codes• MARS_RC_SUCCESS – API initialized successfully• MARS_RC_IO – error during initialization
4.3.3 Threading
MARS maintains context for only a single series of commands (a session). There is no mechanism tosave and restore context.
MARS_Lock() implicitly uses and records an implementation-specific thread or context identifier torestrict subsequent MARS API commands to being issued by the thread/context with the same
identifier. Other MARS API commands MUST check that the identifier is the same as recorded by thelast MARS_Lock(). If not, the commands SHALL return MARS_RC_LOCK.
MARS_Unlock() clears the recorded identifier.

Start of informative comment
To help maintain a desired MARS context, an operating system could be used to prevent interleavingof multiple sessions amongst processes (e.g., via exclusive device access).
A critical series of MARS commands is a series that is intolerant of unexpected changes in MARS’
state. Consequently, a thread depending on MARS state that could be altered by another thread’s
execution should call MARS_Lock() once at the series’ beginning, and MARS_Unlock() at the series’
end. For example, suppose that thread A is used to quote PCR 0 and thread B is used to extend PCR
0. It is incorrect for thread A to:
MARS_Lock();
MARS_Quote(1, …);
MARS_Unlock();
MARS_Lock();
MARS_RegRead(0, …);
MARS_Unlock();

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 11© TCG 2023

MARS API Specification

since thread B could update PCR 0 before thread A can read what it quoted. The correct, and simpler,
implementation of thread A is:
MARS_Lock();
MARS_Quote(1, …);
MARS_RegRead(0, …);
MARS_Unlock();
Another example of a critical series is use of MARS Sequence Primitives. MARS does not have amechanism for saving and restoring Sequence context, so those primitives must be used within asingle MARS_Lock() and MARS_Unlock() pair, as in:
MARS_Lock();
MARS_SequenceHash();MARS_SequenceUpdate(…);…
MARS_SequenceUpdate(…);
MARS_SequenceComplete(…);
MARS_Unlock();
End of informative comment
4.3.3.1 MARS_Lock
MARS_Lock() prepares MARS for exclusive access to support a series of non-interleaved commands.
If already locked by another thread, this function SHALL block until that other thread calls
MARS_Unlock().
4.3.3.1.1 Prototype
MARS_RC MARS_Lock ();4.3.3.1.2 Response Codes• MARS_RC_SUCCESS – exclusive access acquired• MARS_RC_LOCK – calling thread already locked
4.3.3.2 MARS_Unlock
MARS_Unlock() SHALL render inaccessible all data (e.g., plaintext, keys) provided by or for code
accessing the MARS, and relinquish control of the MARS after a previous MARS_Lock().
4.3.3.2.1 Prototype
MARS_RC MARS_Unlock ();4.3.3.2.2 Response Codes• MARS_RC_SUCCESS – exclusive access relinquished• MARS_RC_LOCK – not locked
MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 12© TCG 2023

MARS API Specification

4.4 Single Threading
In non-threaded environments, simplified implementations of MARS_Lock() and MARS_Unlock() may
be implemented. As an example, refer to the informative code snippet below.
Start of informative comment
static bool locked = false;
MARS_RC MARS_Lock(){ return locked ? MARS_RC_LOCK : (locked = true , MARS_RC_SUCCESS); }MARS_RC MARS_Unlock(){ return locked ? locked = false , MARS_RC_SUCCESS : MARS_RC_LOCK; }End of informative comment

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 13© TCG 2023

MARS API Specification

Header Files
5.1 mars/api.h#pragma once#include "mars.h"#define MARS_RC_LOCK

3// not locked or calling thread already locked

MARS_RC MARS_ApiInit ();MARS_RC MARS_Lock ();MARS_RC MARS_Unlock ();5.2 mars/mars.h
5.2.1 Prelude#pragma once#include <stdint.h> // for uint32_t, etc.
#include <stdlib.h> // for size_t#include <stdbool.h> // for bool, true, false
5.2.2 Property Tags
#define MARS_PT_PCR 1// uint16_t number of consecutive PCRs
implemented on this MARS
#define MARS_PT_TSR 2// uint16_t number of consecutive TSRs
implemented on this MARS
#define MARS_PT_LEN_DIGEST 3 // uint16_t size of a digest that can beprocessed or produced#define MARS_PT_LEN_SIGN 4// uint16_t size of signature produced by
CryptSign()#define MARS_PT_LEN_KSYM 5// uint16_t size of symmetric key producedby CryptSkdf()#define MARS_PT_LEN_KPUB 6// uint16_t size of asymmetric key returned
by MARS_PublicRead()#define MARS_PT_LEN_KPRV 7// uint16_t size of private asymmetric key
produced by CryptAkdf()#define MARS_PT_ALG_HASH 8// uint16_t TCG-registered algorithm forhashing by CryptHash()#define MARS_PT_ALG_SIGN 9// uint16_t TCG-registered algorithm forsigning by CryptSign()#define MARS_PT_ALG_SKDF 10// uint16_t TCG-registered algorithm forsymmetric key derivation by CryptSkdf()#define MARS_PT_ALG_AKDF 11// uint16_t TCG-registered algorithm forasymmetric key derivation by CryptAkdf()

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 14© TCG 2023

MARS API Specification

5.2.3 Response Codes
typedef uint16_t MARS_RC;#define MARS_RC_SUCCESS 0// Command executed as expected#define MARS_RC_IO
1// Input / Output or parsing error#define MARS_RC_FAILURE 2// self-testing placed MARS in failure modeor MARS is otherwise inaccessible// reserved
3#define MARS_RC_BUFFER
4// Invalid buffer pointer (null or
misaligned) or length#define MARS_RC_COMMAND 5// Command not supported#define MARS_RC_VALUE
6// Value out of range or incorrect forcontext#define MARS_RC_REG
7// Invalid register index specified#define MARS_RC_SEQ
8// Not preceded by Sequence start command
5.2.4 Management Commands
MARS_RC MARS_SelfTest (bool fullTest);
MARS_RC MARS_CapabilityGet (uint16_t pt,
void * cap,
uint16_t caplen);
5.2.5 Sequence Primitives
MARS_RC MARS_SequenceHash ();MARS_RC MARS_SequenceUpdate(const void * in,size_t inSize,void * out,
size_t * outlen);
MARS_RC MARS_SequenceComplete(
void * out,
size_t * outlen);
5.2.6 Integrity Collection Commands
MARS_RC MARS_PcrExtend (uint16_t pcrIndex,
const void * dig);
MARS_RC MARS_RegRead (MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 15© TCG 2023

MARS API Specification

uint16_t regIndex,
void * dig);
5.2.7 Key Management Commands
MARS_RC MARS_Derive (uint32_t regSelect,const void * ctx,
uint16_t ctxlen,
void * out);
MARS_RC MARS_DpDerive (uint32_t regSelect,const void * ctx,
uint16_t ctxlen);
MARS_RC MARS_PublicRead (bool restricted,
const void * ctx,
uint16_t ctxlen,
void * pub);
5.2.8 Attestation Commands
MARS_RC MARS_Quote (uint32_t regSelect,const void * nonce,
uint16_t nlen,
const void * ctx,
uint16_t ctxlen,
void * sig);
MARS_RC MARS_Sign (const void * ctx,
uint16_t ctxlen,
const void * dig,void * sig);
MARS_RC MARS_SignatureVerify (bool restricted,
const void * ctx,
uint16_t ctxlen,
const void * dig,
const void * sig,bool * result);

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 16© TCG 2023

MARS API Specification

5.2.9 Command Codes#define MARS_CC_SelfTest#define MARS_CC_CapabilityGet#define MARS_CC_SequenceHash#define MARS_CC_SequenceUpdate#define MARS_CC_SequenceComplete#define MARS_CC_PcrExtend#define MARS_CC_RegRead#define MARS_CC_Derive#define MARS_CC_DpDerive#define MARS_CC_PublicRead#define MARS_CC_Quote#define MARS_CC_Sign#define MARS_CC_SignatureVerify#define MARS_CC_LAST

0
1
2
3
4
5
6
7
8
9
10
11
12
12

MARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 17© TCG 2023

MARS API Specification

Bibliography
TCG. (2023, Jan 2). MARS Library Specification, v1r14. Retrieved fromhttps://trustedcomputinggroup.org/resource/mars-library-specification/
Trusted Computing Group. (n.d.). MARS Repository. Retrieved fromhttps://github.com/TrustedComputingGroup/MARSMARS API Specification | Version 1 | Revision 0 | 2/10/2023 | PUBLIC REVIEW

Page 18© TCG 2023