Diff: rfc9597.original.xml

	rfc9597.original.xml	rfc9597.xml
	<?xml version='1.0' encoding='utf-8'?>	<?xml version='1.0' encoding='utf-8'?>


	<!DOCTYPE rfc [	<!DOCTYPE rfc [
	<!ENTITY nbsp " ">	<!ENTITY nbsp " ">
	<!ENTITY zwsp "">	<!ENTITY zwsp "">
	<!ENTITY nbhy "‑">	<!ENTITY nbhy "‑">
	<!ENTITY wj "⁠">	<!ENTITY wj "⁠">
	]>	]>

	<!-- name="GENERATOR" content="github.com/mmarkdown/mmark Mmark Markdown Process
	or - mmark.miek.nl" -->	<rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" ipr="trust200902" do
	<rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" ipr="trust200902" do	cName="draft-ietf-cose-cwt-claims-in-headers-10" number="9597" updates="" obsole
	cName="draft-ietf-cose-cwt-claims-in-headers-10" submissionType="IETF" category=	tes="" submissionType="IETF" consensus="true" category="std" xml:lang="en" tocIn
	"std" xml:lang="en" indexInclude="true">	clude="true" symRefs="true" sortRefs="true">

	<front>	<front>

	<title>CBOR Web Token (CWT) Claims in COSE Headers</title><seriesInfo value="dra	<title abbrev="CWT Claims in COSE Headers">CBOR Web Token (CWT) Claims in COSE
	ft-ietf-cose-cwt-claims-in-headers-10" status="standard" name="Internet-Draft"/>	Headers</title>
	<author initials="T." surname="Looker" fullname="Tobias Looker"><organization>Ma	<seriesInfo name="RFC" value="9597"/>
	ttr</organization><address><postal><street/>	<author initials="T." surname="Looker" fullname="Tobias Looker">
	</postal><email>tobias.looker@mattr.global</email>	<organization>Mattr</organization>
	</address></author><author initials="M." surname="Jones" fullname="Michael B. Jo	<address>
	nes"><organization>Self-Issued Consulting</organization><address><postal><street	<email>tobias.looker@mattr.global</email>
	/>	</address>
	</postal><email>michael_b_jones@hotmail.com</email>	</author>
	<uri>https://self-issued.info/</uri>	<author initials="M.B." surname="Jones" fullname="Michael B. Jones">
	</address></author><date/>	<organization>Self-Issued Consulting</organization><address>
	<area>Internet</area>	<email>michael_b_jones@hotmail.com</email>
	<workgroup>COSE</workgroup>	<uri>https://self-issued.info/</uri>
		</address>
		</author>
		<date year="2024" month="June"/>

		<area>SEC</area>
		<workgroup>cose</workgroup>

	<keyword>COSE</keyword>	<keyword>COSE</keyword>
	<keyword>JOSE</keyword>	<keyword>JOSE</keyword>

	<abstract>	<abstract>

	<t>This document describes how to include CBOR Web Token (CWT) claims in the hea der parameters of any COSE structure. This functionality helps to facilitate app lications that wish to make use of CBOR Web Token (CWT) claims in encrypted COSE structures and/or COSE structures featuring detached signatures, while having s ome of those claims be available before decryption and/or without inspecting the detached payload.	<t>This document describes how to include CBOR Web Token (CWT) claims in the hea der parameters of any CBOR Object Signing and Encryption (COSE) structure. This functionality helps to facilitate applications that wish to make use of CWT clai ms in encrypted COSE structures and/or COSE structures featuring detached signat ures, while having some of those claims be available before decryption and/or wi thout inspecting the detached payload.
	Another use case is using CWT claims with payloads that are not CWT Claims Sets, including payloads that are not CBOR at all.</t>	Another use case is using CWT claims with payloads that are not CWT Claims Sets, including payloads that are not CBOR at all.</t>
	</abstract>	</abstract>


	<note title="Discussion Venues" removeInRFC="true">
	<t>Source for this draft and an issue tracker can be found at
	<eref target="https://github.com/tplooker/draft-ietf-cose-cwt-claims-in-head
	ers"/>.</t>
	</note>
	</front>	</front>


	<middle>	<middle>

	<section anchor="introduction"><name>Introduction</name>	<section anchor="introduction"><name>Introduction</name>

	<t>In some applications of COSE, it is useful to have a standard representation of CWT claims <xref target="RFC8392"/> available in the header parameters. These include encrypted COSE structures, which may or may not be an encrypted CWT and /or those featuring a detached signature.	<t>In some applications of COSE, it is useful to have a standard representation of CWT claims <xref target="RFC8392"/> available in the header parameters. These include encrypted COSE structures, which may or may not be an encrypted CWT, an d/or those featuring a detached signature.
	Another use case is using CWT claims with payloads that are not CWT Claims Sets, including payloads that are not CBOR at all.	Another use case is using CWT claims with payloads that are not CWT Claims Sets, including payloads that are not CBOR at all.
	For instance, an application might want to include an "iss" (issuer) claim in a COSE_Sign1 structure	For instance, an application might want to include an "iss" (issuer) claim in a COSE_Sign1 structure
	when the payload being signed is a non-CBOR data structure, such as a bitmap ima ge, and the issuer value is used for key discovery.</t>	when the payload being signed is a non-CBOR data structure, such as a bitmap ima ge, and the issuer value is used for key discovery.</t>

	<t>Section 5.3 of JSON Web Token (JWT) <xref target="RFC7519"/> defined a simila
	r mechanism for expressing selected JWT based claims as JOSE header parameters.	<t><xref target="RFC7519" sectionFormat="of" section="5.3"/>, "JSON Web Token (J
	This JWT feature was motivated by the desire to have certain claims, such as th	WT)", defined a similar mechanism for expressing selected JWT-based claims as JS
	e Issuer value, be visible to software processing the JWT, even though the JWT i	ON Object Signing and Encryption (JOSE) header parameters. This JWT feature was
	s encrypted. No corresponding feature was standardized for CWTs, which was an o	motivated by the desire to have certain claims, such as the Issuer value, be vi
	mission that this specification corrects.</t>	sible to software processing the JWT, even though the JWT is encrypted. No corr
		esponding feature was standardized for CWTs, which was an omission that this spe
		cification corrects.</t>
	<t>Directly including CWT claim values as COSE header parameter values would not work, since there are conflicts between the numeric header parameter assignment s and the numeric CWT claim assignments. Instead, this specification defines a single header parameter registered in the IANA "COSE Header Parameters" registry that creates a location to store CWT claims in a COSE header parameter.</t>	<t>Directly including CWT claim values as COSE header parameter values would not work, since there are conflicts between the numeric header parameter assignment s and the numeric CWT claim assignments. Instead, this specification defines a single header parameter registered in the IANA "COSE Header Parameters" registry that creates a location to store CWT claims in a COSE header parameter.</t>
	<t>This specification does not define how to use CWT claims and their	<t>This specification does not define how to use CWT claims and their
	semantics for particular applications, whether they are in the COSE	semantics for particular applications, whether they are in the COSE
	payload or the CWT Claims header parameter, or both.	payload or the CWT Claims header parameter, or both.
	Therefore, understanding how to process the CWT Claims header	Therefore, understanding how to process the CWT Claims header
	parameter requires unambiguously knowing the intended interpretation.	parameter requires unambiguously knowing the intended interpretation.

	The necessary information about this MAY come from other header parameters.	The necessary information about this <bcp14>MAY</bcp14> come from other header p arameters.
	Unless there already is a natural way of providing this information at	Unless there already is a natural way of providing this information at
	an appropriate level of integrity protection and authentication, a	an appropriate level of integrity protection and authentication, a

	RECOMMENDED way to include this information in the COSE structure is	<bcp14>RECOMMENDED</bcp14> way to include this information in the COSE structure
	use of the <tt>typ</tt> (type) Header Parameter	is
	<xref target="I-D.ietf-cose-typ-header-parameter"/>.	use of the "typ" (type) Header Parameter
	Other methods for determining the intended interpretation MAY also be used.	<xref target="RFC9596"/>.
	Recipients of the CWT Claims header parameter MUST NOT use the	Other methods for determining the intended interpretation <bcp14>MAY</bcp14> als
		o be used.
		Recipients of the CWT Claims header parameter <bcp14>MUST NOT</bcp14> use the
	information in the CWT Claims header parameter beyond the integrity	information in the CWT Claims header parameter beyond the integrity
	protection or authentication afforded to the CWT Claims header and the	protection or authentication afforded to the CWT Claims header and the
	information used to derive its intended interpretation.</t>	information used to derive its intended interpretation.</t>

	<section anchor="requirements-terminology"><name>Requirements Terminology</name>	<section anchor="requirements-terminology"><name>Requirements Terminology</name>

	<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",	<t>
	"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this d	The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
	ocument are to be interpreted as described in BCP 14 <xref target="RFC2119"/> <x	"<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>
	ref target="RFC8174"/> when, and only when, they appear in all capitals, as show	",
	n here.</t>	"<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
		"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
		"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
		be
		interpreted as described in BCP 14 <xref target="RFC2119"/> <xref
		target="RFC8174"/> when, and only when, they appear in all capitals, as
		shown here.
		</t>
	</section>	</section>
	</section>	</section>

	<section anchor="representation"><name>Representation</name>	<section anchor="representation"><name>Representation</name>
	<t>This document defines the following COSE header parameter:</t>	<t>This document defines the following COSE header parameter:</t>

	<table>
		<table anchor="iana-tab">
	<thead>	<thead>
	<tr>	<tr>
	<th>Name</th>	<th>Name</th>
	<th>Label</th>	<th>Label</th>
	<th>Value Type</th>	<th>Value Type</th>
	<th>Value Registry</th>	<th>Value Registry</th>
	<th>Description</th>	<th>Description</th>

		<th>Reference</th>
	</tr>	</tr>
	</thead>	</thead>

	<tbody>	<tbody>
	<tr>	<tr>
	<td>CWT Claims</td>	<td>CWT Claims</td>

	<td>TBD (requested assignment 15)</td>	<td>15</td>
	<td>map</td>	<td>map</td>

	<td><xref target="IANA.COSE"/></td>	<td><t>map keys in <xref target="CWT.Claims"/></t></td>
	<td>Location for CWT Claims in COSE Header Parameters</td>	<td>Location for CWT Claims in COSE Header Parameters</td>

		<td><xref target="representation"/> of RFC 9597</td>
	</tr>	</tr>
	</tbody>	</tbody>
	</table><t>The following is a non-normative description for the value type of th e CWT claim header parameter using CDDL <xref target="RFC8610"/>.</t>	</table><t>The following is a non-normative description for the value type of th e CWT claim header parameter using CDDL <xref target="RFC8610"/>.</t>


	<artwork><![CDATA[CWT-Claims = {	<sourcecode type="cddl">
		<![CDATA[CWT-Claims = {
	* Claim-Label => any	* Claim-Label => any
	}	}

	Claim-Label = int / text	Claim-Label = int / text
	]]>	]]>

	</artwork>	</sourcecode>
	<t>In cases where CWT claims are present both in the payload and the header of a	<t>In cases where CWT claims are present both in the payload and the header of a
	CWT, an application receiving such a structure MUST verify that their values ar	CWT, an application receiving such a structure <bcp14>MUST</bcp14> verify that
	e identical, unless the application defines other specific processing rules for	their values are identical, unless the application defines other specific proces
	these claims.</t>	sing rules for these claims.</t>
	<t>It is RECOMMENDED that the CWT Claims header parameter is used only in a prot	<t>It is <bcp14>RECOMMENDED</bcp14> that the CWT Claims header parameter only be
	ected header to avoid the contents being malleable. The header parameter MUST on	used in a protected header to avoid the contents being malleable. The header pa
	ly occur once in either the protected or unprotected header of a COSE structure.	rameter <bcp14>MUST</bcp14> only occur once in either the protected or unprotect
	</t>	ed header of a COSE structure.</t>
	<t>The CWT Claims header parameter MAY be used in any COSE object using header p	<t>The CWT Claims header parameter <bcp14>MAY</bcp14> be used in any COSE object
	arameters, such as COSE_Sign objects. Its use is not restricted to CWTs.</t>	using header parameters, such as COSE_Sign objects. Its use is not restricted
		to CWTs.</t>
	</section>	</section>

	<section anchor="privacy-considerations"><name>Privacy Considerations</name>	<section anchor="privacy-considerations"><name>Privacy Considerations</name>
	<t>Some of the registered CWT claims may contain privacy-sensitive information. Since CWT claims in COSE headers are not encrypted, when privacy-sensitive infor mation is present in these claims, applications and protocols using them should ensure that these COSE objects are only made visible to parties for which it is appropriate for them to have access to this sensitive information.</t>	<t>Some of the registered CWT claims may contain privacy-sensitive information. Since CWT claims in COSE headers are not encrypted, when privacy-sensitive infor mation is present in these claims, applications and protocols using them should ensure that these COSE objects are only made visible to parties for which it is appropriate for them to have access to this sensitive information.</t>
	</section>	</section>

	<section anchor="security-considerations"><name>Security Considerations</name>	<section anchor="security-considerations"><name>Security Considerations</name>

	<t>Implementers should also review the security considerations for CWT, which ar e documented in Section 8 of <xref target="RFC8392"/>.</t>	<t>Implementers should also review the security considerations for CWT, which ar e documented in <xref target="RFC8392" sectionFormat="of" section="8"/>.</t>
	<t>As described in <xref target="RFC9052"/>, if the COSE payload is transported separately ("detached content"), then it is the responsibility of the applicatio n to ensure that it will be transported without changes.</t>	<t>As described in <xref target="RFC9052"/>, if the COSE payload is transported separately ("detached content"), then it is the responsibility of the applicatio n to ensure that it will be transported without changes.</t>

	<t>The reason for applications to verify that CWT claims that are present both i
	n the payload and the header of a CWT are identical, unless it defines other spe	<t>The reason for applications to verify that CWT claims present in both the pay
	cific processing rules for these claims, is to eliminate potential confusion tha	load and the header of a CWT are identical, unless they define other specific pr
	t might arise by having different values for the same claim, which could result	ocessing rules for these claims, is to eliminate potential confusion that might
	in inconsistent processing of such claims.</t>	arise by having different values for the same claim, which could result in incon
	<t>Processing information in claims prior to validating that their integrity is	sistent processing of such claims.</t>
	cryptographically secured can pose security risks.	<t>Processing information in claims prior to validating that their integrity is
		cryptographically secure can pose security risks.
	This is true whether the claims are in the payload or a header parameter.	This is true whether the claims are in the payload or a header parameter.
	Implementers must ensure that any tentative decisions made based on previously u nverified information are confirmed once the cryptographic processing has been c ompleted.	Implementers must ensure that any tentative decisions made based on previously u nverified information are confirmed once the cryptographic processing has been c ompleted.
	This includes any information that was used to derive the intended	This includes any information that was used to derive the intended
	interpretation of the CWT claims parameter.</t>	interpretation of the CWT claims parameter.</t>
	</section>	</section>

	<section anchor="iana-considerations"><name>IANA Considerations</name>	<section anchor="iana-considerations"><name>IANA Considerations</name>

	<t>IANA is requested to register the new COSE header parameter "CWT Claims" in t	<t>IANA has registered the new COSE header parameter "CWT Claims" defined in
	he table in <xref target="representation"/> in the "COSE Header Parameters" regi	<xref target="iana-tab"/> in the "COSE Header Parameters" registry <xref target=
	stry <xref target="IANA.COSE"/>.</t>	"COSE.HeaderParameters"/>.</t>
	</section>	</section>

	</middle>	</middle>

	<back>	<back>

	<references><name>References</name>	<references>
	<references><name>Normative References</name>	<name>References</name>
	<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-cos	<references>
	e-typ-header-parameter.xml"/>	<name>Normative References</name>
	<reference anchor="IANA.COSE" target="https://www.iana.org/assignments/cose/cose
	.xhtml#header-parameters">	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9596.xml"
		/>
		<reference anchor="COSE.HeaderParameters" target="https://www.iana.org/assignmen
		ts/cose/">
	<front>	<front>
	<title>COSE Header Parameters</title>	<title>COSE Header Parameters</title>
	<author>	<author>
	<organization>IANA</organization>	<organization>IANA</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


		<reference anchor="CWT.Claims" target="https://www.iana.org/assignments/cwt/">
		<front>
		<title>CBOR Web Token (CWT) Claims</title>
		<author>
		<organization>IANA</organization>
		</author>
		</front>
		</reference>

	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml" />	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml" />
	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml" />	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml" />
	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8392.xml" />	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8392.xml" />
	</references>	</references>
	<references><name>Informative References</name>	<references><name>Informative References</name>
	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml" />	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7519.xml" />
	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8610.xml" />	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8610.xml" />
	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9052.xml" />	<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9052.xml" />
	</references>	</references>
	</references>	</references>


	<section anchor="Acknowledgements"><name>Acknowledgements</name>	<section anchor="Acknowledgements" numbered="false"><name>Acknowledgements</name >
	<t>We would like to thank	<t>We would like to thank

	Daisuke Ajitomi,	<contact fullname="Daisuke Ajitomi"/>,
	Claudio Allocchio,	<contact fullname="Claudio Allocchio"/>,
	Carsten Bormann,	<contact fullname="Carsten Bormann"/>,
	Laurence Lundblade,	<contact fullname="Laurence Lundblade"/>,
	Ivaylo Petrov,	<contact fullname="Ivaylo Petrov"/>,
	Ines Robles,	<contact fullname="Ines Robles"/>,
	Orie Steele,	<contact fullname="Orie Steele"/>,
	Hannes Tschofenig,	<contact fullname="Hannes Tschofenig"/>,
	Paul Wouters,	<contact fullname="Paul Wouters"/>,
	and	and

	Peter Yee	<contact fullname="Peter Yee"/>
	for their valuable contributions to this specification.</t>	for their valuable contributions to this specification.</t>
	</section>	</section>


	<section anchor="document-history"><name>Document History</name>
	<t>-09</t>

	<ul spacing="compact">
	<li>Described use cases where CWT claims can't be put in the payload in response
	to Hannes Tschofenig's IotDir review.</li>
	<li>Said that profiles specify the semantics of the CWT claims in response to Ca
	rsten Bormann's feedback.</li>
	</ul>
	<t>-08</t>

	<ul spacing="compact">
	<li>Added Security Consideration about profiles and processing CWT claims.</li>
	</ul>
	<t>-07</t>

	<ul spacing="compact">
	<li>Added Privacy Consideration about unencrypted claims in header parameters.</
	li>
	<li>Added Security Consideration about detached content.</li>
	<li>Added Security Consideration about claims that are present both in the paylo
	ad and the header of a CWT.</li>
	<li>Changed requested IANA COSE Header Parameter assignment number from 13 to 15
	due to subsequent assignments of 13 and 14.</li>
	<li>Acknowledged last call reviewers.</li>
	</ul>
	<t>-06</t>

	<ul spacing="compact">
	<li>Changed requested IANA COSE Header Parameter assignment number from 11 to 13
	due to Countersignature being allocated 11.</li>
	<li>Reference correct registry IANA COSE Header Parameters.</li>
	</ul>
	<t>-05</t>

	<ul spacing="compact">
	<li>Added Acknowledgements section.</li>
	<li>Addressed WGLC feedback. Specifically...</li>
	<li>Added statement about being able to use the header parameter in any COSE obj
	ect.</li>
	<li>Moved statment about verifing that claim values present in both the header a
	nd payload are identical from the Security Considerations to the body of the spe
	cification.</li>
	</ul>
	<t>-04</t>

	<ul spacing="compact">
	<li>Update author affiliation.</li>
	<li>Add standard reference to RFC terminology.</li>
	<li>Added reference to security considerations from RFC8392.</li>
	</ul>
	<t>-03</t>

	<ul spacing="compact">
	<li>Added recommendation around header treatment in protected vs unprotected.</l
	i>
	</ul>
	<t>-02</t>

	<ul spacing="compact">
	<li>Added CDDL description for CWT claim value.</li>
	</ul>
	<t>-01</t>

	<ul spacing="compact">
	<li>Changed example from Key ID to Issuer.</li>
	</ul>
	<t>-00</t>

	<ul spacing="compact">
	<li>Created draft-ietf-cose-cwt-claims-in-headers-00 from draft-looker-cose-cwt-
	claims-in-headers-00 following working group adoption.</li>
	</ul>
	</section>

	</back>	</back>

	</rfc>	</rfc>

End of changes. 27 change blocks.
	163 lines changed or deleted	118 lines changed or added
This html diff was produced by rfcdiff 1.48.