Trusted Execution Environment Provisioning (TEEP) ProtocolArm Ltd.AbsamTirol6067Austriahannes.tschofenig@arm.comBroadcom350 Ellis StMountain ViewCA94043USAmingliang.pei@broadcom.comIntelUSdavid.m.wheeler@intel.comMicrosoftUSdthaler@microsoft.comAISTJPakira.tsukamoto@aist.go.jp
Security
TEEPTrusted Execution EnvironmentThis document specifies a protocol that installs, updates, and deletes
Trusted Applications (TAs) in a device with a Trusted Execution
Environment (TEE). This specification defines an interoperable
protocol for managing the lifecycle of TAs.The protocol name is pronounced teepee. This conjures an image of a
wedge-shaped protective covering for one’s belongings, which sort of
matches the intent of this protocol.The Trusted Execution Environment (TEE) concept has been designed to
separate a regular operating system, also referred as a Rich Execution
Environment (REE), from security-sensitive applications. In an TEE
ecosystem, device vendors may use different operating systems in the
REE and may use different types of TEEs. When application providers or
device administrators use Trusted Application Managers (TAMs) to
install, update, and delete Trusted Applications (TAs) on a wide range
of devices with potentially different TEEs then an interoperability
need arises.This document specifies the protocol for communicating between a TAM
and a TEEP Agent, involving a TEEP Broker.The Trusted Execution Environment Provisioning (TEEP) architecture
document has set to provide a design
guidance for such an interoperable protocol and introduces the
necessary terminology. Note that the term Trusted Application may
include more than code; it may also include configuration data and
keys needed by the TA to operate correctly.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”,
“MAY”, and “OPTIONAL” in this document are to be interpreted as
described in BCP 14 when, and only when, they
appear in all capitals, as shown here.This specification re-uses the terminology defined in .The TEEP protocol consists of a couple of messages exchanged between a TAM
and a TEEP Agent via a TEEP Broker.
The messages are encoded in CBOR and designed to provide end-to-end security.
TEEP protocol messages are signed by the endpoints, i.e., the TAM and the
TEEP Agent, but trusted
applications may as well be encrypted and signed by the service provider.
The TEEP protocol not only re-use
CBOR but also the respective security wrapper, namely COSE . Furthermore,
for attestation the Entity Attestation Token (EAT) and for software updates the SUIT
manifest format are re-used.This specification defines six messages.A TAM queries a device’s current state with a QueryRequest message.
A TEEP Agent will, after authenticating and authorizing the request, report
attestation information, list all TAs, and provide information about supported
algorithms and extensions in a QueryResponse message. An error message is
returned if the request
could not be processed. A TAM will process the QueryResponse message and
determine
whether subsequent message exchanges to install, update, or delete trusted
applications
shall be initiated.With the TrustedAppInstall message a TAM can instruct a TEEP Agent to install
a TA.
The TEEP Agent will process the message, determine whether the TAM is authorized
and whether the
TA has been signed by an authorized SP. In addition to the binary, the TAM
may also provide
personalization data. If the TrustedAppInstall message was processed successfully
then a
Success message is returned to the TAM, an Error message otherwise.With the TrustedAppDelete message a TAM can instruct a TEEP Agent to delete
one or multiple TA(s).
A Success message is returned when the operation has been completed successfully,
and an Error message
otherwise.TEEP messages are protected by the COSE_Sign1 structure.
The TEEP protocol messages are described in CDDL format below.To create a TEEP message, the following steps are performed.Create a TEEP message according to the description below and populate
it with the respective content.Create a COSE Header containing the desired set of Header
Parameters. The COSE Header MUST be valid per the specification.Create a COSE_Sign1 object
using the TEEP message as the COSE_Sign1 Payload; all
steps specified in for creating a
COSE_Sign1 object MUST be followed.Prepend the COSE object with the
TEEP CBOR tag to indicate that the CBOR-encoded message is indeed a
TEEP message.When validating a TEEP message, the following steps are performed. If any
of
the listed steps fail, then the TEEP message MUST be rejected.Verify that the received message is a valid CBOR object.Remove the TEEP message CBOR tag and verify
that one of the COSE CBOR tags follows it.Verify that the message contains a COSE_Sign1 structure.Verify that the resulting COSE Header includes only parameters
and values whose syntax and semantics are both understood and
supported or that are specified as being ignored when not
understood.Follow the steps specified in Section 4 of (“Signing Objects”) for
validating a COSE_Sign1 object. The COSE_Sign1 payload is the content
of the TEEP message.Verify that the TEEP message is a valid CBOR map and verify the fields of
the
TEEP message according to this specification.A QueryRequest message is used by the TAM to learn
information from the TEEP Agent. The TAM can learn
the features supported by the TEEP Agent, including
ciphersuites, and protocol versions. Additionally,
the TAM can selectively request data items from the
TEEP Agent via the request parameter. Currently,
the following features are supported:Request for attestation information,Listing supported extensions,Querying installed software (trusted apps), andListing supporting SUIT commands.Like other TEEP messages, the QueryRequest message is
signed, and the relevant CDDL snippet is shown below.
The complete CDDL structure is shown in .The message has the following fields:
The value of (1) corresponds to a QueryRequest message sent from the TAM to
the TEEP Agent.
The value in the token parameter is used to match responses to requests. This is
particualrly useful when a TAM issues multiple concurrent requests to a TEEP Agent.
The request parameter indicates what information the TAM requests from the TEEP
Agent in form of a bitmap. Each value in the bitmap corresponds to an
IANA registered information element. This
specification defines the following initial set of information elements:
With this value the TAM requests the TEEP Agent to return an entity attestation
token (EAT) in the response. If the TAM requests an attestation token to be
returned by the TEEP Agent then it MUST also include the nonce in the message.
The nonce is subsequently placed into the EAT token for replay protection.
With this value the TAM queries the TEEP Agent for all installed TAs.
With this value the TAM queries the TEEP Agent for supported capabilities
and extensions, which allows a TAM to discover the capabilities of a TEEP
Agent implementation.
With this value the TAM queries the TEEP Agent for supported commands offered
by the SUIT manifest implementation.
Further values may be added in the future via IANA registration.
The cipher-suites parameter lists the ciphersuite(s) supported by the TAM. Details
about the ciphersuite encoding can be found in .
The none field is an optional parameter used for ensuring the refreshness of the Entity
Attestation Token (EAT) returned with a QueryResponse message. When a nonce is
provided in the QueryRequest and an EAT is returned with the QueryResponse message
then the nonce contained in this request MUST be copied into the nonce claim found
in the EAT token.
The version field parameter the version(s) supported by the TAM. For this version
of the specification this field can be omitted.
The ocsp_data parameter contains a list of OCSP stapling data
respectively for the TAM certificate and each of the CA certificates
up to the root certificate. The TAM provides OCSP data so that the
TEEP Agent can validate the status of the TAM certificate chain
without making its own external OCSP service call. OCSP data MUST be
conveyed as a DER-encoded OCSP response (using the ASN.1 type
OCSPResponse defined in ). The use of OCSP is optional to
implement for both the TAM and the TEEP Agent. A TAM can query the
TEEP Agent for the support of this functionality via the capability
discovery exchange, as described above.The QueryResponse message is the successful response by the TEEP Agent after
receiving a QueryRequest message.Like other TEEP messages, the QueryResponse message is
signed, and the relevant CDDL snippet is shown below.
The complete CDDL structure is shown in .The message has the following fields:
The value of (2) corresponds to a QueryResponse message sent from the TEEP Agent
to the TAM.
The value in the token parameter is used to match responses to requests. The
value MUST correspond to the value received with the QueryRequest message.
The selected-cipher-suite parameter indicates the selected ciphersuite. Details
about the ciphersuite encoding can be found in .
The selected-version parameter indicates the protocol version selected by the
TEEP Agent.
The eat parameter contains an Entity Attestation Token following the encoding
defined in .
The ta-list parameter enumerates the trusted applications installed on the device
in form of TA_ID byte strings.
The ext-list parameter lists the supported extensions. This document does not
define any extensions.The TrustedAppInstall message is used by the TAM to install software (trusted apps)
via the TEEP Agent.Like other TEEP messages, the TrustedAppInstall message is
signed, and the relevant CDDL snippet is shown below.
The complete CDDL structure is shown in .The TrustedAppInstall message has the following fields:
The value of (3) corresponds to a TrustedAppInstall message sent from the TAM to
the TEEP Agent. In case of successful processing, an Success
message is returned by the TEEP Agent. In case of an error, an Error message
is returned. Note that the TrustedAppInstall message
is used for initial TA installation but also for TA updates.
The value in the token field is used to match responses to requests.
The manifest-list field is used to convey one or multiple SUIT manifests.
A manifest is
a bundle of metadata about the trusted app, where to
find the code, the devices to which it applies, and cryptographic
information protecting the manifest. The manifest may also convey personalization
data. TA binaries and personalization data is typically signed and encrypted
by the SP. Other combinations are, however, possible as well. For example,
it is also possible for the TAM to sign and encrypt the personalization data
and to let the SP sign and/or encrypt the TA binary.The TrustedAppDelete message is used by the TAM to remove
software (trust apps) from the device.Like other TEEP messages, the TrustedAppDelete message is
signed, and the relevant CDDL snippet is shown below.
The complete CDDL structure is shown in .The TrustedAppDelete message has the following fields:
The value of (4) corresponds to a TrustedAppDelete message sent from the TAM to the
TEEP Agent. In case of successful processing, an Success
message is returned by the TEEP Agent. In case of an error, an Error message
is returned.
The value in the token parameter is used to match responses to requests.
The ta-list parameter enumerates the TAs to be deleted.The TEEP protocol defines two implicit success messages and this explicit
Success message for the cases where the TEEP Agent cannot return another reply,
such as for the TrustedAppInstall and the TrustedAppDelete messages.Like other TEEP messages, the Success message is
signed, and the relevant CDDL snippet is shown below.
The complete CDDL structure is shown in .The Success message has the following fields:
The value of (5) corresponds to corresponds to a Success message sent from the TEEP Agent to the
TAM.
The value in the token parameter is used to match responses to requests.
The msg parameter contains optional diagnostics information encoded in
UTF-8 returned by the TEEP Agent.The Error message is used by the TEEP Agent to return an error.Like other TEEP messages, the Error message is
signed, and the relevant CDDL snippet is shown below.
The complete CDDL structure is shown in .The Error message has the following fields:
The value of (6) corresponds to an Error message sent from the TEEP Agent to the TAM.
The value in the token parameter is used to match responses to requests.
The err-code parameter is populated with values listed in a registry (with the
initial set of error codes listed below). Only selected messages are applicable
to each message.
The err-msg parameter is a human-readable diagnostic text that MUST be encoded
using UTF-8 using Net-Unicode form .
The cipher-suites parameter lists the ciphersuite(s) supported by the TEEP Agent.
This field is optional but MUST be returned with the ERR_UNSUPPORTED_CRYPTO_ALG
error message.
The version parameter enumerates the protocol version(s) supported by the TEEP
Agent. This otherwise optional parameter MUST be returned with the ERR_UNSUPPORTED_MSG_VERSION
error message.This specification defines the following initial error messages:
The TEEP Agent sends this error message when
a request contains incorrect fields or fields that are inconsistent with
other fields.
The TEEP Agent sends this error message when
it recognizes an unsupported extension or unsupported message.
The TEEP Agent sends this error message when
it fails to verify the signature of the message.
The TEEP Agent receives a message but does not
support the indicated version.
The TEEP Agent receives a request message
encoded with an unsupported cryptographic algorithm.
The TEEP Agent returns this error
when processing of a certificate failed. For diagnosis purposes it is
RECOMMMENDED to include information about the failing certificate
in the error message.
The TEEP Agent returns this error
when a certificate was of an unsupported type.
The TEEP Agent returns this error
when a certificate was revoked by its signer.
The TEEP Agent returns this error
when a certificate has expired or is not currently
valid.
The TEEP Agent returns this error when a miscellaneous
internal error occurred while processing the request.
This error is reported when a device
resource isn’t available anymore, such as storage space is full.
This error will occur when the target TA does not
exist. This error may happen when the TAM has stale information and
tries to delete a TA that has already been deleted.
While installing a TA, a TEE will return
this error if the TA has already been installed.
The TEEP Agent returns this error when
it does not recognize the format of the TA binary.
The TEEP Agent returns this error when
it fails to decrypt the TA binary.
The TEEP Agent returns this error when
it fails to decompress the TA binary.
The TEEP Agent returns this error when
manifest processing failures occur that are less specific than
ERR_TA_UNKNOWN_FORMAT, ERR_TA_UNKNOWN_FORMAT, and ERR_TA_DECOMPRESSION_FAILED.
The TEEP Agent returns this error when
it fails to process the provided personalization data.Additional error code can be registered with IANA.In COSE, arrays and maps use strings, negative integers, and unsigned
integers as their keys. Integers are used for compactness of
encoding. Since the word “key” is mainly used in its other meaning, as a
cryptographic key, this specification uses the term “label” for this usage
as a map key.This specification uses the following mapping:NameLabelcipher-suites1nonce2version3ocsp-data4selected-cipher-suite5selected-version6eat7ta-list8ext-list9manifest-list10msg11err-msg12A ciphersuite consists of an AEAD algorithm, a HMAC algorithm, and a signature
algorithm.
Each ciphersuite is identified with an integer value, which corresponds to
an IANA registered
ciphersuite. This document specifies two ciphersuites.ValueCiphersuite1AES-CCM-16-64-128, HMAC 256/256, X25519, EdDSA2AES-CCM-16-64-128, HMAC 256/256, P-256, ES256This section summarizes the security considerations discussed in this
specification:
TEEP protocol messages exchanged between the TAM and the TEEP Agent
are protected using COSE. This specification relies on the
cryptographic algorithms provided by COSE. Public key based
authentication is used to by the TEEP Agent to authenticate the TAM
and vice versa.
A TAM may rely on the attestation information provided by the TEEP
Agent and the Entity Attestation Token is re-used to convey this
information. To sign the Entity Attestation Token it is necessary
for the device to possess a public key (usually in the form of a
certificate) along with the corresponding private key. Depending on
the properties of the attestation mechanism it is possible to
uniquely identify a device based on information in the attestation
information or in the certificate used to sign the attestation
token. This uniqueness may raise privacy concerns. To lower the
privacy implications the TEEP Agent MUST present its attestation
information only to an authenticated and authorized TAM.
TA binaries are provided by the SP. It is the responsibility of the
TAM to relay only verified TAs from authorized SPs. Delivery of
that TA to the TEEP Agent is then the responsibility of the TAM and
the TEEP Broker, using the security mechanisms provided by the TEEP
protocol. To protect the TA binary the SUIT manifest is re-used and
it offers a varity of security features, including digitial
signatures and symmetric encryption.
An SP or a TAM can supply personalization data along with a TA.
This data is also protected by a SUIT manifest.
The personalization data may be opaque to the TAM.
The TEEP protocol relies on the TEEP Broker to relay messages
between the TAM and the TEEP Agent. When the TEEP Broker is
compromised it can drop messages, delay the delivery of messages,
and replay messages but it cannot modify those messages. (A replay
would be, however, detected by the TEEP Agent.) A compromised TEEP
Broker could reorder messages in an attempt to install an old
version of a TA. Information in the manifest ensures that the TEEP
Agents are protected against such downgrading attacks based on
features offered by the manifest itself.
The QueryRequest message from a TAM to the TEEP Agent may include
OCSP stapling data for the TAM’s signer certificate and for
intermediate CA certificates up to the root certificate so that the
TEEP Agent can verify the certificate’s revocation status. A
certificate revocation status check on a TA signer certificate is
OPTIONAL by a TEEP Agent. A TAM is responsible for vetting a TA and
before distributing them to TEEP Agents. TEEP Agents will trust a TA
signer certificate’s validation status done by a TAM.
The CA issuing certificates to a TAM or an SP may get compromised.
A compromised intermediate CA certificates can be detected by a TEEP
Agent by using OCSP information, assuming the revocation information
is available. Additionally, it is RECOMMENDED to provide a way to
update the trust anchor store used by the device, for example using
a firmware update mechanism. If the CA issuing certificates to
devices gets compromised then these devices might be rejected by a
TAM, if revocation is available to the TAM.
The TEEP Agent SHOULD use OCSP information to verify the validity of
the TAM-provided certificate (as well as the validity of
intermediate CA certificates). The integrity and the accuracy of the
clock within the TEE determines the ability to determine an expired
or revoked certificate since OCSP stapling includes signature
generation time, certificate validity dates are compared to the
current time.IANA is requested to assign a media type for
application/teep+cbor.
application
teep+cbor
none
none
Same as encoding considerations of
application/cbor
See Security Considerations Section of this document.
Same as interoperability
considerations of application/cbor as specified in
This document.
TEEP protocol implementations
N/A
N/A
N/A
N/A
N/A
teep@ietf.org
COMMON
none
See the “Authors’ Addresses” section of this document
IETFIANA is also requested to create a new registry for the error codes defined
in .Registration requests are evaluated after a
three-week review period on the teep-reg-review@ietf.org mailing list,
on the advice of one or more Designated Experts . However,
to allow for the allocation of values prior to publication, the
Designated Experts may approve registration once they are satisfied
that such a specification will be published.Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., “Request to register an error code: example”).
Registration requests that are undetermined for a period longer than
21 days can be brought to the IESG’s attention (using the
iesg@ietf.org mailing list) for resolution.Criteria that should be applied by the Designated Experts includes
determining whether the proposed registration duplicates existing
functionality, whether it is likely to be of general applicability or
whether it is useful only for a single extension, and whether the
registration description is clear.IANA must only accept registry updates from the Designated Experts
and should direct all requests for registration to the review mailing
list.IANA is also requested to create a new registry for ciphersuites, as defined
in .IANA is requested to register a CBOR tag in the “CBOR Tags” registry
for use with TEEP messages.The registry contents is:CBOR Tag: TBD1Data Item: TEEP MessageSemantics: TEEP Message, as defined in [[TBD: This RFC]]Reference: [[TBD: This RFC]]Point of Contact: TEEP working group (teep@ietf.org)CBOR Object Signing and Encryption (COSE)Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need for the ability to have basic security services defined for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR.UTF-8, a transformation format of ISO 10646ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8, the object of this memo. UTF-8 has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo obsoletes and replaces RFC 2279.Unicode Format for Network InterchangeThe Internet today is in need of a standardized form for the transmission of internationalized "text" information, paralleling the specifications for the use of ASCII that date from the early days of the ARPANET. This document specifies that format, using UTF-8 with normalization and specific line-ending sequences. [STANDARDS-TRACK]Concise Binary Object Representation (CBOR)The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack.The Entity Attestation Token (EAT)An Entity Attestation Token (EAT) provides a signed (attested) set of claims that describe state and characteristics of an entity, typically a device like a phone or an IoT device. These claims are used by a relying party to determine how much it wishes to trust the entity. An EAT is either a CWT or JWT with some attestation-oriented claims. To a large degree, all this document does is extend CWT and JWT. Contributing TBDA Concise Binary Object Representation (CBOR)-based Serialization Format for the Software Updates for Internet of Things (SUIT) ManifestThis specification describes the format of a manifest. A manifest is a bundle of metadata about the firmware for an IoT device, where to find the firmware, the devices to which it applies, and cryptographic information protecting the manifest. Firmware updates and trusted boot both tend to use sequences of common operations, so the manifest encodes those sequences of operations, rather than declaring the metadata.X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSPThis document specifies a protocol useful in determining the current status of a digital certificate without requiring CRLs. [STANDARDS-TRACK]Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.Trusted Execution Environment Provisioning (TEEP) ArchitectureA Trusted Execution Environment (TEE) is an environment that enforces that any code within that environment cannot be tampered with, and that any data used by such code cannot be read or tampered with by any code outside that environment. This architecture document motivates the design and standardization of a protocol for managing the lifecycle of trusted applications running inside such a TEE.Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data StructuresThis document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON.Guidelines for Writing an IANA Considerations Section in RFCsMany protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA).To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry.This is the third edition of this document; it obsoletes RFC 5226.We would like to thank Brian Witten (Symantec), Tyler Kim (Solacia), Nick Cook (Arm), and Minho Yoo (IoTrust) for their contributions
to the Open Trust Protocol (OTrP), which influenced the design of this specification.We would like to thank Eve Schooler for the suggestion of the protocol name.We would like to thank Kohei Isobe (TRASIO/SECOM),
Kuniyasu Suzaki (TRASIO/AIST), Tsukasa Oi (TRASIO), and Yuichi Takita (SECOM)
for their valuable implementation feedback.We would also like to thank Carsten Bormann and Henk Birkholz for their help with the CDDL.