This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The value to use with the parameter for each of the structures can be found in <xreftarget="CBOR-Tags"/>.
</t>
<t>
When a COSE object is carried in a CoAP message, the CoAP content type parameter can be used to identify the message content.
When a COSE object is carried as a CoAP payload, the CoAP content type parameter can be used to identify the message content.
The CoAP content types can be found in <xreftarget="CoAP_content_type"/>.
The CBOR Tag for the message structure is not required as each security message is uniquely identified.
</t>
@@ -478,7 +478,8 @@ tag=10
The structure of COSE has been designed to have two buckets of information that are not considered to be part of the payload itself, but are used for holding information about content, algorithms, keys, or evaluation hints for the processing of the layer.
These two buckets are available for use in all of the structures except for keys.
While these buckets can be present, they may not all be usable in all instances.
For example, while the protected bucket is defined as part of recipient structures, most of the algorithms that are used for recipients do not provide for authenticated data and thus the bucket should not be used.
For example, while the protected bucket is defined as part of the recipient structure, some of the algorithms used for recipient structures do not provide for authenticated data.
If this is the case, the protected bucket should be left empty.
</t>
<t>
@@ -610,8 +611,9 @@ header_map = {
</t>
<thangText='kid'>
This parameter one of the ways that can be used to find the key to be used.
The value of this parameter is matched against the 'kid' member in a COSE_Key structure.
This parameter identifies one piece of data that can be used as input to find the needed cryptographic key.
The value of this parameter can be matched against the 'kid' member in a COSE_Key structure.
Other methods of key distribution can define an equivalent field to be matched.
Applications MUST NOT assume that 'kid' values are unique.
There may be more than one key with the same 'kid' value, it may be required that all of the keys need to be checked to find the correct one.
The internal structure of 'kid' values is not defined and cannot be relied on by applications.
@@ -653,7 +655,7 @@ header_map = {
For signatures and recipient structures, this would be the time that the signature or recipient key object was created.
For content structures, this would be the time that the content structure was created.
The unsigned integer value is the number of seconds, excluding leap seconds, after midnight UTC, January 1, 1970.
The field is primarily intended to be to be used for countersignatures, however it can additionally be used for replay detection as well.
The field is primarily intended to be to be used for counter signatures, however it can additionally be used for replay detection as well.
There are provisions for parameters about the content and parameters about the signature to be carried along with the signature itself.
These parameters may be authenticated by the signature, or just present.
An example of a parameter about the content is the content type.
Examples of parameters about the signature would be the algorithm and key used to create the signature, when the signature was created, and a counter-signature.
Examples of parameters about the signature would be the algorithm and key used to create the signature, when the signature was created, and counter signatures.
</t>
<t>
@@ -841,6 +843,11 @@ COSE_Signature = [
COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7
]]></artwork></figure>
<t>
The CBOR object that carries the body, the signature and the information about the body and signature is called the COSE_Sign1 structure.
Examples of COSE Single signature messages can be found in <xreftarget="Sign1_Examples"/>.
</t>
<t>
The COSE_Sign1 structure is a CBOR array.
The fields of the array in order are:
@@ -893,7 +900,7 @@ COSE_Sign1 = [
The primary reason for supporting this can be seen by looking at the CoAP message structure <xreftarget="RFC7252"/> where the facility exists for options to be carried before the payload.
An example of data that can be placed in this location would be CoAP options for transaction ids and nonces to check for replay protection.
If the data is in the options section, then it is available for routers to help in performing the replay detection and prevention.
However, it may also be desired to protect these values so that if they cannot be modified in transit it can be detected.
However, it may also be desired to protect these values so that if they are be modified in transit it can be detected.
This is the purpose of the externally supplied data field.
</t>
@@ -948,6 +955,7 @@ COSE_Sign1 = [
<t>
The protected attributes from the application encoded in a bstr type.
If this field is not supplied, it defaults to a zero length binary string.
(See <xreftarget="Extern_AAD"/> for application guidance on constructing this field.)
</t>
<t>
@@ -981,15 +989,15 @@ Sig_structure = [
</t>
<t>
Create the value ToBeSigned by encoding the Sig_structure to a byte string.
Create the value ToBeSigned by encoding the Sig_structure to a byte string using the encoding described in <xreftarget="CBOR-Canonical"/>.
</t>
<t>
Call the signature creation algorithm passing in K (the key to sign with), alg (the algorithm to sign with) and ToBeSigned (the value to sign).
</t>
<t>
Place the resulting signature value in the 'signature' field of the map.
Place the resulting signature value in the 'signature' field of the array.
</t>
</list>
</t>
@@ -1003,7 +1011,7 @@ Sig_structure = [
</t>
<t>
Create the value ToBeSigned by encoding the Sig_structure to a byte string.
Create the value ToBeSigned by encoding the Sig_structure to a byte string using the encoding described in <xreftarget="CBOR-Canonical"/>..
</t>
<t>
@@ -1036,13 +1044,13 @@ Sig_structure = [
<t>
The creation and validation of counter signatures over the different items relies on the fact that the structure of the objects have the same structure.
The elements are a set of protected attributes, a set of unprotected attributes and a body in that order.
This means that the Sig_structure can be used for in a uniform manner to get the byte stream for processing a signature.
This means that the Sig_structure can be used in a uniform manner to get the byte stream for processing a signature.
If the counter signature is going to be computed over a COSE_Enveloped structure, the body_protected and payload items can be mapped into the Sig_structure in the same manner as from the COSE_Sign structure.
</t>
<t>
It should be noted that only a signature algorithm with appendix (see <xreftarget="SigAlgs"/>) can be used for counter signatures.
This is because the body should be able to be processed without having to evaluate the countersignature, and this is not possible for signature schemes with message recovery.
This is because the body should be able to be processed without having to evaluate the counter signature, and this is not possible for signature schemes with message recovery.
</t>
</section>
</section>
@@ -1072,7 +1080,7 @@ Sig_structure = [
This is different from the approach used by both <xreftarget="RFC5652"/> and <xreftarget="RFC7516"/> where different structures are used for the content layer and for the recipient layer.
Two structures are defined: COSE_Enveloped to hold the encrypted content, and COSE_recipient to hold the encrypted keys for recipients.
Examples of encrypted messages can be found in <xreftarget="EncryptedExamples"/>.
Examples of encrypted messages can be found in <xreftarget="EnvelopedExamples"/>.
</t>
<t>
@@ -1201,7 +1209,7 @@ COSE_recipient = [
<t>
The structure defined to hold an encrypted message is COSE_Encrypted.
Examples of encrypted messages can be found in <xreftarget="EncryptedExamples"/>.
Examples of encrypted messages can be found in <xreftarget="EnvelopedExamples"/>.
</t>
<t>
@@ -1250,17 +1258,12 @@ COSE_Encrypted = [
<t>
The encryption algorithm for AEAD algorithms is fairly simple.
</t>
The first step is to create a consistent byte stream for the authenticated data structure.
For this purpose we use a CBOR array, the fields of the array in order are:
<t>
<liststyle="numbers">
<t>
Create a CBOR array (Enc_structure) to encode the authenticated data.
</t>
<t>
Place a context string in the form of a tstr in the first location to identify the data and location being encoded.
The strings defined are:
A text string identifying the context of the authenticated data structure. The context string is:
<liststyle="hanging">
<thangText='"Encrypted"'> for the content encryption of an encrypted data structure.</t>
<thangText='"Enveloped"'> for the first level of an enveloped data structure (i.e. for content encryption).</t>
@@ -1269,19 +1272,41 @@ COSE_Encrypted = [
<thangText='"Rec_Recipient"'>for a recipient encoding to be placed in a recipient structure.</t>
</list>
</t>
<t>
Copy the protected header field from the message to be sent to the second location in the Enc_structure.
The protected attributes from the body structure encoded in a bstr type. If there are no protected attributes, a bstr of length zero is used.
</t>
<t>
If the application has supplied external additional authenticated data to be included in the computation, then it is placed in the third location ('external_aad' field) of the Enc_structure.
If no data was supplied, then a zero length binary value is used.
The protected attributes from the application encoded in a bstr type. If this field is not supplied, it defaults to a zero length bstr.
(See <xreftarget="Extern_AAD"/> for application guidance on constructing this field.)
</t>
</list>
</t>
<t>
The CDDL fragment which describes the above text is:
<sectionanchor="encryption-algorithm-for-ae-algorithms"title="Encryption algorithm for AE algorithms">
<t>
How to encrypt a message:
<liststyle="numbers">
<t>
Verify that the 'protected' field is absent.
@@ -1372,6 +1422,42 @@ Enc_structure = [
</list>
</t>
<t>
How to decrypt a message:
<liststyle="numbers">
<t>
Verify that the 'protected' field is absent.
</t>
<t>
Verify that there was no external additional authenticated data supplied for this operation.
</t>
<t>
Determine the decryption key.
This step is dependent on the class of recipient algorithm being used.
For:
<liststyle="hanging">
<thangText="No Recipients:">
The key to be used is determined by the algorithm and key at the current level.
</t>
<thangText="Direct and Direct Key Agreement:">
The key is determined by the key and algorithm in the recipient structure.
The encryption algorithm and size of the key to be used are inputs into the KDF used for the recipient.
(For direct, the KDF can be thought of as the identity operation.)
</t>
<thangText="Other:">
The key is determined by decoding and decrypting the recipient structure.
</t>
</list>
</t>
<t>
Call the decryption algorithm with K (the decryption key to use), C (the cipher text) and AAD.
</t>
</list>
</t>
</section>
</section>
@@ -1473,6 +1559,7 @@ COSE_Mac = [
<t>
The MAC message uses the COSE_Mac0 structure defined in this section for carrying the body.
Examples of MAC messages with an implicit key can be found in <xreftarget="Mac0Examples"/>.
</t>
<t>
@@ -1514,7 +1601,7 @@ COSE_Mac0 = [
</section>
<sectiontitle="How to compute a MAC">
<sectiontitle="How to compute and verify a MAC">
<t>
In order to get a consistent encoding of the data to be authenticated, the MAC_structure is used to have a canonical form.
The MAC_structure is a CBOR array.
@@ -1559,15 +1646,19 @@ MAC_structure = [
<liststyle="numbers">
<t>
Create a MAC_structure and fill in the fields.
Create a MAC_structure and populate it with the appropriate fields.
</t>
<t>
Encode the MAC_structure using a canonical CBOR encoder. The resulting bytes are the value to compute the MAC on.
Encode the MAC_structure to a byte stream using the encoding described in <xreftarget="CBOR-Canonical"/>.
</t>
<t>
Compute the MAC and place the result in the 'tag' field of the COSE_Mac structure.
Call the MAC creation algorithm passing in K (the key to use), alg (the algorithm to MAC with) and ToBeMaced (the value to compute the MAC on).
</t>
<t>
Place the resulting MAC in the 'tag' field of the COSE_Mac structure.
</t>
<t>
@@ -1576,6 +1667,31 @@ MAC_structure = [
</list>
</t>
<t>
How to verify a MAC are:
<liststyle="numbers">
<t>
Create a MAC_structure object and populate it with the appropriate fields.
</t>
<t>
Encode the MAC_structure to a byte stream using the encoding described in <xreftarget="CBOR-Canonical"/>.
</t>
<t>
Obtain the cryptographic key from one of the recipients of the message.
</t>
<t>
Call the MAC creation algorithm passing in K (the key to use), alg (the algorithm to MAC with) and ToBeMaced (the value to compute the MAC on).
</t>
<t>
Compare the MAC value to the 'tag' field of the COSE_Mac structure.
</t>
</list>
</t>
</section>
</section>
@@ -3281,7 +3397,7 @@ COSE_KDF_Context = [
<liststyle="symbols">
<t>
Applications need to determine the set of messages defined in this document that it will be using.
Applications need to determine the set of messages defined in this document that they will be using.
The set of messages corresponds fairly directly to the set of security services that are needed and to the security levels needed.
</t>
@@ -3293,7 +3409,7 @@ COSE_KDF_Context = [
</t>
<t>
When applications use externally defined authenticated data, they need to define how that data is to be defined.
When applications use externally defined authenticated data, they need to define how that data is encoded.
This document assumes that the data will be provided as a byte stream.
More information can be found in <xreftarget="Extern_AAD"/>.
</t>
@@ -3859,15 +3975,15 @@ COSE_KDF_Context = [
<t>
There are a number of security considerations that need to be taken into account by implementers of this specification.
The security considerations that are specific to an individual algorithm are placed next to the description of the algorithm.
While some considerations have been highlighted here, additional considerations may be found in the documents referred to that have full details of the algorithm.
While some considerations have been highlighted here, additional considerations may be found in the documents listed in the references.
</t>
<t>
Implementations need to protect the private key for any individuals.
There are some cases in this document that need to be highlighted on this issue.
<liststyle="symbols">
<t>
Using a the same key for two different algorithms can leak information about the key.
Using the same key for two different algorithms can leak information about the key.
It is therefore recommended that keys be restricted to a single algorithm.
</t>
<t>
@@ -3904,12 +4020,12 @@ COSE_KDF_Context = [
<t>
Before using a key for transmission, or before acting on information recieved, a trust decision on a key needs to be made.
Is the data or action something that the entity associated with the key has a right to see or a right to request.
A number of factors are assoicated with this trust decision.
A number of factors are associated with this trust decision.
Some of the ones that are highlighted here are:
<liststyle="symbols">
<t>What are the permissions assoicated with the key owner?</t>
<t>What are the permissions associated with the key owner?</t>
<t>Is the cryptographic algorithm acceptable in the current context?</t>
<t>Have the restrictions associated with the key, such as algorithm or freshness, been checked are are correct?</t>
<t>Have the restrictions associated with the key, such as algorithm or freshness, been checked and are correct?</t>
<t>Is the request something that is reasonable given the current state of the application?</t>
<t>Have any security considerations that are part of the message been enforced? (As specified by the application or crit parameter.)</t>
</list>
@@ -4119,25 +4235,6 @@ COSE_KDF_Context = [
<sectiontitle="Making Mandatory Items Optional">
<t>
There has been a minority of the working group who have expressed a strong desire to relax the rule that the algorithm identifier be required to appear in each level of a COSE mesage.
There are two basic reasons that have been advanced to support this position.
First, the resulting message will be smaller if the algorithm identifier is omitted from the most common messages in a CoAP environment.
Second, there is a potential bug that will arise if full checking is not done correctly between the different places that an algorithm identifier could be placed.
(The message itself, an application statement, the key structure that the sender possesses and the key structure the recipient possesses.)
</t>
<t>
This appendix lays out how such a change can be made and the details that an application needs to specify in order to use this option.
Two different sets of details are specified: Those needed to omit an algorithm identifier and those needed to use a variant on the counter signature attribute which contains no attributes about itself.
</t>
<sectiontitle="Algorithm Identification">
<t>
</t>
</section>
<sectiontitle="Countersignature Without Headers">
</section>
</section>
<sectionanchor="three-layer"title="Three Levels of Recipient Information">