Skip to main content

Shepherd writeup
draft-ietf-rats-eat

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
   few individuals, with others being silent, or did it reach broad agreement?
While there was strong contribution of small group, there was broad consensus
to move with the current version of the draft.

2. Was there controversy about particular points, or were there decisions where
   the consensus was particularly rough?
Intial versions of the draft were too broad in scope, the resulting draft is
the content That reached broad consensus

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
   so, please summarize the areas of conflict in separate email messages to the
   responsible Area Director. (It should be in a separate email because this
   questionnaire is publicly available.)
No

4. For protocol documents, are there existing implementations of the contents of
   the document? Have a significant number of potential implementers indicated
   plans to implement? Are any existing implementations reported somewhere,
   either in the document itself (as [RFC 7942][3] recommends) or elsewhere
   (where)?
Known or planned implementations of EAT or a profile of EAT:
   EAT Libraries:
        - CBOR Formats - open source project
                o Rust:  https://github.com/carl-wallace/cbor_formats
        - EAT library - open source project
                o C: https://github.com/laurencelundblade/ctoken
        - A command line utility based on EAT library - open source project
                o C: https://github.com/laurencelundblade/xclaim
   EAT Profiles:
        - PSA
                o Golang: https://github.com/veraison/psatoken
                o
                C: https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/secure_fw/partitions/initial_attestation
                o
                Python: https://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/iat-verifier
        - CCA
                o Golang: https://github.com/veraison/ccatoken
                o
                C: https://git.trustedfirmware.org/TF-RMM/tf-rmm.git/tree/lib/attestation
        - FIDO FDO - open source project
                o
                Java: https://github.com/secure-device-onboard/pri-fidoiot/blob/master/protocol/src/main/java/org/fidoalliance/fdo/protocol/message/EatPayloadBase.java.
        - Global Platform - very early code of an EAT profile, may evolve into
        open source
                o
                 https://github.com/GlobalPlatform/TPS-API-Reference-Implementations.
        - Microsoft Azure Attestation - proprietary
                o
                https://github.com/CCC-Attestation/meetings/blob/main/materials/GregKostal_EAT_in_MAA.pdf

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
   IETF working groups or external organizations, and would it therefore benefit
   from their review? Have those reviews occurred? If yes, describe which
   reviews took place.
Yes, there is close relation to other drafts in RATS (e.g., UCCS and the RATS
Architecture), more importantly it leverages the work from (ACE/JOSE/COSE) as
it uses JWT and CWTs and generates extensions to those groups. There is also
alignment with the FIDO Alliance organization as they look to leverage the
claims defined in this draft.

6. Describe how the document meets any required formal expert review criteria,
   such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.
The draft has acquired early IANA assignment as well as expert review on the
Oauth/JWT and CWT. See answer to #21.

7. If the document contains a YANG module, has the final version of the module
   been checked with any of the [recommended validation tools][4] for syntax and
   formatting validation? If there are any resulting errors or warnings, what is
   the justification for not fixing them at this time? Does the YANG module
   comply with the Network Management Datastore Architecture (NMDA) as specified
   in [RFC 8342][5]?
No, YANG is not used or specified in this draft.

8. Describe reviews and automated checks performed to validate sections of the
   final version of the document written in a formal language, such as XML code,
   BNF rules, MIB definitions, CBOR's CDDL, etc.
We cloned and built the EAT github repository locally which is based on the
Thomson template (martinthomson/i-d-template: A template for IETF internet
draft git repositories (github.com)) and it built without errors, but with one
warning that identified a unused informative reference. There was one
informative reference to a draft that has since become an RFC that should be
updated. The eat draft relies on CDDL for normative statements. The CDDL is
verified correct using a make file that checks the CDDL against examples. The
same CDDL files are imported into the draft giving high confidence they are
syntactically correct.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
   document is needed, clearly written, complete, correctly designed, and ready
   to be handed off to the responsible Area Director?
I have reviewed the document and believe it is ready for Area Directory review.
The EAT I-D is a set of claims that are intended for use within a CWT or JWT
web token. There aren’t any mandatory to use claims as their use is prescribed
according to a profile that may be user, application, or vendor specific. The
intent of the draft is to define claim syntax and semantics such that if a
claim is asserted by one entity, a receiving entity will be able to process the
claim by reading the EAT draft. The RATS Architecture RFC 9334: Remote
ATtestation procedureS (RATS) Architecture (ietf.org) defines several
attestation conceptual messages. Claims contained in the EAT draft could be
used by some or all the conceptual messages. There may be claims defined in EAT
that are better suited to one type of conceptual message over another, but it
was not a goal of the draft to stereo type the claims to conceptual messages.
There were several discussions on the email list and in face-to-face meetings
to clarify these objectives. Some of the proposed claims were less well defined
or thought to be unnecessary and were removed from the final draft. Other
claims were thought to be highly useful, such that the working group sought and
obtained early allocation from IANA registries. The FIDO Alliance has
incorporated some of the early allocation claims into at least one of their
specifications.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?
This draft received reviews from SECDir and IoTdir representatives. One issue
raised was an interoperability concern. If a profile is required to direct
which claims are used and, in some cases, how they are to be applied, wouldn’t
that suggest that the profile is point at which interoperability is guaranteed.
The working group resolved this issue by observing that all web tokens require
similar qualification. As a building block specification, it is anticipated
that other standards groups will write specifications that define meaningful
profiles, but it is also possible that vendor-specific profiles could be
defined as well. There is a public vendor specific profile here:
draft-tschofenig-rats-psa-token-10 - Arm's Platform Security Architecture (PSA)
Attestation Token (ietf.org). Another concern raised had to do with the way
certain claims were described, and whether the description was semantically
clear and sufficient to avoid downstream security issues. The authors addressed
these concerns by rewriting the section or by removing the claim altogether
(possibly to be reintroduced in a future draft). Some of the feedback observed
that EAT refers to attestation ‘protocols’ where that may be too specific as
the RATS Architecture refers to them as ‘conveyance’ mechanisms. The EAT draft
does not intend to define a protocol per se but does anticipate being used to
define a conceptual message type that is included as a payload in a protocol
that supports attestation. Still other review feedback included concerns about
possible semantic differences that could occur given different conceptual
message contexts. A claim asserted as Evidence could have different meaning if
asserted as Attestation Results, for example. The working group resolved these
concerns by revising EAT normative that seemed to prescribe a meaning assuming
a particular conceptual message type but didn’t clearly articulate the
assumption as part of the description.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?
Request is for “Proposed Standard”, the datatracker and draft reflect the
intent.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.
Yes, we did a query to the RATs mail list as well as a unicast request to the
draft authors and no IPR disclosures were submitted or known to the
participants.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.
Yes.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)
The EAT draft appears to follow the I-D style guidelines and uses the
convention that “this document” should be replaced with “this RFC” when an RFC
status is granted. It makes use of acronyms by defining the expanded name and
including a parenthetical abbreviation. The draft appears to make proper use of
RFC2119 for normative statements. The draft appears to follow guidelines in
NISTIR8366. There doesn’t appear to be stale text.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].
The RATS chairs identified two informative references [IEEE.802-2001] and
[OUI.Guide] that possibly should be normative. The chairs notified the authors
to determine if this is appropriate.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?
All normative references are freely available.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.
There are 4 normative references to non-standards track RFCs: 
RFC2119RFC8126, RFC8174, RFC8792 and two references to I-Ds:
https://datatracker.ietf.org/doc/html/draft-ietf-suit-manifest-21 and
https://datatracker.ietf.org/doc/html/draft-ietf-sacm-coswid-22.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?
The two cited I-Ds are progressing toward RFC status. This I-D should update
these references  when they become RFCs. RFC9052 and RFC8949 make normative
reference to RFC2119 and RFC8174. Possibly, these should be added to the
downref exceptions registry Downref registry (ietf.org)? The I-D authors
believe RFC8126 and RFC8792 do not need to be normative references. They plan
to make this change in v20 of the EAT draft.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.
No

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).
The IANA considerations section identifies the code points that have been
previously assigned based on a pre-allocation request and the remaining code
points are clearly described as requiring IANA allocation.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.
There are several IANA registries that are impacted by this I-D. Michael Jones
would be the appropriate designated expert.

The set of IANA registries affected are copied from the EAT draft as follows:

10.2. CWT and JWT Claims Registered by This Document
This specification adds the following values to the "JSON Web Token Claims"
registry established by [RFC7519] and the "CBOR Web Token Claims Registry"
established by [RFC8392]. Each entry below is an addition to both registries.¶
The "Claim Description", "Change Controller" and "Specification Documents" are
common and equivalent for the JWT and CWT registries. The "Claim Key" and
"Claim Value Types(s)" are for the CWT registry only. The "Claim Name" is as
defined for the CWT registry, not the JWT registry. The "JWT Claim Name" is
equivalent to the "Claim Name" in the JWT registry.

IANA is requested to register the following claims.

RFC Editor: Please make the following adjustments and remove this paragraph.
Replace "this document" with this RFC number. In the following, the claims with
"Claim Key: TBD" need to be assigned a value in the Specification Required
Range, preferrably starting around 267. Those below already with a Claim Key
number were given early assignment. No change is requested for them except for
Claim Key 262. Claim 262 should be renamed from "secboot" to "oemboot" in the
JWT registry and it's description changed in both the CWT and JWT registries.

• Claim Name: Nonce¶
• Claim Description: Nonce¶
• JWT Claim Name: "eat_nonce"¶
• Claim Key: 10¶
• Claim Value Type(s): byte string¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: UEID¶
• Claim Description: The Universal Entity ID¶
• JWT Claim Name: "ueid"¶
• CWT Claim Key: 256¶
• Claim Value Type(s): byte string¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: SUEIDs¶
• Claim Description: Semi-permanent UEIDs¶
• JWT Claim Name: "sueids"¶
• CWT Claim Key: 257¶
• Claim Value Type(s): map¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Hardware OEMID¶
• Claim Description: Hardware OEM ID¶
• JWT Claim Name: "oemid"¶
• Claim Key: 258¶
• Claim Value Type(s): byte string or integer¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Hardware Model¶
• Claim Description: Model identifier for hardware¶
• JWT Claim Name: "hwmodel"¶
• Claim Key: 259¶
• Claim Value Type(s): byte string¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Hardware Version¶
• Claim Description: Hardware Version Identifier¶
• JWT Claim Name: "hwversion"¶
• Claim Key: TBD 260¶
• Claim Value Type(s): array¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: OEM Authortised Boot¶
• Claim Description: Indicate whether the software booted was OEM authorized¶
• JWT Claim Name: "oemboot"¶
• Claim Key: 262¶
• Claim Value Type(s): Boolean¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Debug Status¶
• Claim Description: Indicate status of debug facilities¶
• JWT Claim Name: "dbgstat"¶
• Claim Key: 263¶
• Claim Value Type(s): integer or string¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Location¶
• Claim Description: The geographic location¶
• JWT Claim Name: "location"¶
• Claim Key: 264¶
• Claim Value Type(s): map¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: EAT Profile¶
• Claim Description: Indicates the EAT profile followed¶
• JWT Claim Name: "eat_profile"¶
• Claim Key: 265¶
• Claim Value Type(s): URI or OID¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Submodules Section¶
• Claim Description: The section containing submodules¶
• JWT Claim Name: "submods"¶
• Claim Key: 266¶
• Claim Value Type(s): map¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Uptime¶
• Claim Description: Uptime¶
• JWT Claim Name: "uptime"¶
• Claim Key: TBD¶
• Claim Value Type(s): unsigned integer¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Boot Count¶
• Claim Description: The number times the entity or submodule has been booted¶
• JWT Claim Name: "bootcount"¶
• Claim Key: TBD¶
• Claim Value Type(s): uint¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Boot Seed¶
• Claim Description: Identifies a boot cycle¶
• JWT Claim Name: "bootseed"¶
• Claim Key: TBD¶
• Claim Value Type(s): bytes¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: DLOAs¶
• Claim Description: Certifications received as Digital Letters of Approval¶
• JWT Claim Name: "dloas"¶
• Claim Key: TBD¶
• Claim Value Type(s): array¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Software Name¶
• Claim Description: The name of the software running in the entity¶
• JWT Claim Name: "swname"¶
• Claim Key: TBD¶
• Claim Value Type(s): map¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Software Version¶
• Claim Description: The version of software running in the entity¶
• JWT Claim Name: "swversion"¶
• Claim Key: TBD¶
• Claim Value Type(s): map¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Software Manifests¶
• Claim Description: Manifests describing the software installed on the entity¶
• JWT Claim Name: "manifests"¶
• Claim Key: TBD¶
• Claim Value Type(s): array¶
• Change Controller: IESG¶
• Specification Document(s): this document¶
• Claim Name: Measurements¶
• Claim Description: Measurements of the software, memory configuration and
such on the entity¶ • JWT Claim Name: "measurements"¶ • Claim Key: TBD¶ • Claim
Value Type(s): array¶ • Change Controller: IESG¶ • Specification
Document(s): this document¶ • Claim Name: Software Measurement Results¶ • Claim
Description: The results of comparing software measurements to reference
values¶ • JWT Claim Name: "measres"¶ • Claim Key: TBD¶ • Claim Value Type(s):
array¶ • Change Controller: IESG¶ • Specification Document(s): this document¶ •
Claim Name: Intended Use¶ • Claim Description: Indicates intended use of the
EAT¶ • JWT Claim Name: "intuse"¶ • Claim Key: TBD¶ • Claim Value Type(s):
integer or string¶ • Change Controller: IESG¶ • Specification Document(s): this
document¶ 10.3. UEID URN Registered by this Document IANA is requested to
register the following new subtypes in the "DEV URN Subtypes" registry under
"Device Identification". See [RFC9039].¶ Table 3 Subtype Description Reference
ueid Universal Entity Identifier This document sueid Semi-permanent Universal
Entity Identifier This document 10.4. CBOR Tag for Detached EAT Bundle
Registered by this Document In the registry [IANA.cbor-tags], IANA is requested
to allocate the following tag from the FCFS space, with the present document as
the specification reference.¶ Table 4 Tag Data Items Semantics TBD602 array
Detached EAT Bundle Section 5 10.5. Media Types Registered by this Document It
is requested that the CoAP Content-Format for SPDX and CycloneDX be been
registered in the "CoAP Content-Formats" subregistry within the "Constrained
RESTful Environments (CoRE) Parameters" registry [IANA.core-parameters]:¶ •
Media Type: application/spdx+json¶ • Encoding: binary¶ • ID: TBD¶ •
Reference: [SPDX]¶ • Media Type: vendor/vnd.cyclonedx+xml¶ • Encoding: binary¶
• ID: TBD¶ • Reference: [CycloneDX]¶ • Media Type: vendor/vnd.cyclonedx+json¶ •
Encoding: binary¶ • ID: TBD¶ • Reference: [CycloneDX]

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]:
https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/
Back