draft-ietf-cose-msg-06.txt   draft-ietf-cose-msg-07.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Intended status: Informational October 17, 2015 Intended status: Informational November 3, 2015
Expires: April 19, 2016 Expires: May 6, 2016
CBOR Encoded Message Syntax CBOR Encoded Message Syntax
draft-ietf-cose-msg-06 draft-ietf-cose-msg-07
Abstract Abstract
Concise Binary Object Representation (CBOR) is data format designed Concise Binary Object Representation (CBOR) is data format designed
for small code size and small message size. There is a need for the for small code size and small message size. There is a need for the
ability to have the basic security services defined for this data ability to have the basic security services defined for this data
format. This document specifies how to do signatures, message format. This document specifies procesing for signatures, message
authentication codes and encryption using this data format. authentication codes, and encryption using CBOR. This document also
specifies a represention for cryptographic keys using CBOR.
Contributing to this document Contributing to this document
The source for this draft is being maintained in GitHub. Suggested The source for this draft is being maintained in GitHub. Suggested
changes should be submitted as pull requests at <https://github.com/ changes should be submitted as pull requests at <https://github.com/
cose-wg/cose-spec>. Instructions are on that page as well. cose-wg/cose-spec>. Instructions are on that page as well.
Editorial changes can be managed in GitHub, but any substantial Editorial changes can be managed in GitHub, but any substantial
issues need to be discussed on the COSE mailing list. issues need to be discussed on the COSE mailing list.
Status of This Memo Status of This Memo
skipping to change at page 1, line 42 skipping to change at page 1, line 43
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 19, 2016. This Internet-Draft will expire on May 6, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 44 skipping to change at page 2, line 44
5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 20 5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 20
5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 20 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 20
5.4. Encryption algorithm for AE algorithms . . . . . . . . . 21 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 21
6. MAC objects . . . . . . . . . . . . . . . . . . . . . . . . . 22 6. MAC objects . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.1. How to compute a MAC . . . . . . . . . . . . . . . . . . 23 6.1. How to compute a MAC . . . . . . . . . . . . . . . . . . 23
7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 24 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 24
7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 24 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 24
8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 27 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 27
8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 28 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.1.1. Security Considerations . . . . . . . . . . . . . . . 29 8.1.1. Security Considerations . . . . . . . . . . . . . . . 29
9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 30 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 29
9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 30 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 30
9.1.1. Security Considerations . . . . . . . . . . . . . . . 31 9.1.1. Security Considerations . . . . . . . . . . . . . . . 31
9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 32 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 31
9.2.1. Security Considerations . . . . . . . . . . . . . . . 32 9.2.1. Security Considerations . . . . . . . . . . . . . . . 32
10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 33 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 32
10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 33 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 33
10.1.1. Security Considerations . . . . . . . . . . . . . . 34 10.1.1. Security Considerations . . . . . . . . . . . . . . 34
10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 34 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 34
10.2.1. Security Considerations . . . . . . . . . . . . . . 37 10.2.1. Security Considerations . . . . . . . . . . . . . . 37
10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 37 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 37
10.3.1. Security Considerations . . . . . . . . . . . . . . 38 10.3.1. Security Considerations . . . . . . . . . . . . . . 38
11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 38 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 38
11.1. HMAC-based Extract-and-Expand Key Derivation Function 11.1. HMAC-based Extract-and-Expand Key Derivation Function
(HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 39 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 39
11.2. Context Information Structure . . . . . . . . . . . . . 40 11.2. Context Information Structure . . . . . . . . . . . . . 40
skipping to change at page 3, line 43 skipping to change at page 3, line 43
15.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 60 15.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 60
15.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 60 15.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 60
15.8. Media Type Registrations . . . . . . . . . . . . . . . . 61 15.8. Media Type Registrations . . . . . . . . . . . . . . . . 61
15.8.1. COSE Security Message . . . . . . . . . . . . . . . 61 15.8.1. COSE Security Message . . . . . . . . . . . . . . . 61
15.8.2. COSE Key media type . . . . . . . . . . . . . . . . 63 15.8.2. COSE Key media type . . . . . . . . . . . . . . . . 63
15.9. CoAP Content Format Registrations . . . . . . . . . . . 65 15.9. CoAP Content Format Registrations . . . . . . . . . . . 65
16. Security Considerations . . . . . . . . . . . . . . . . . . . 65 16. Security Considerations . . . . . . . . . . . . . . . . . . . 65
17. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 66
17.1. Normative References . . . . . . . . . . . . . . . . . . 66 17.1. Normative References . . . . . . . . . . . . . . . . . . 66
17.2. Informative References . . . . . . . . . . . . . . . . . 66 17.2. Informative References . . . . . . . . . . . . . . . . . 66
Appendix A. CDDL Grammar . . . . . . . . . . . . . . . . . . . . 68 Appendix A. CDDL Grammar . . . . . . . . . . . . . . . . . . . . 69
Appendix B. Three Levels of Recipient Information . . . . . . . 69 Appendix B. Three Levels of Recipient Information . . . . . . . 69
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 70 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 71
C.1. Examples of MAC messages . . . . . . . . . . . . . . . . 71 C.1. Examples of MAC messages . . . . . . . . . . . . . . . . 72
C.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 71 C.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 72
C.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 72 C.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 73
C.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 73 C.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 74
C.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 74 C.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 75
C.2. Examples of Encrypted Messages . . . . . . . . . . . . . 75 C.2. Examples of Encrypted Messages . . . . . . . . . . . . . 76
C.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 75 C.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 76
C.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 76 C.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 77
C.3. Examples of Signed Message . . . . . . . . . . . . . . . 77 C.3. Examples of Signed Message . . . . . . . . . . . . . . . 78
C.3.1. Single Signature . . . . . . . . . . . . . . . . . . 77 C.3.1. Single Signature . . . . . . . . . . . . . . . . . . 78
C.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 78 C.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 79
C.4. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 78 C.4. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 79
C.4.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 78 C.4.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 79
C.4.2. Private Keys . . . . . . . . . . . . . . . . . . . . 81 C.4.2. Private Keys . . . . . . . . . . . . . . . . . . . . 82
Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 82 Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 83
D.1. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 82 D.1. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 83
D.2. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 83 D.2. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 84
D.3. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 83 D.3. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 84
D.4. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 83 D.4. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 84
D.5. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 83 D.5. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 84
D.6. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 84 D.6. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 85
D.7. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 84 D.7. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 85
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 85 D.8. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 85
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 86
1. Introduction 1. Introduction
There has been an increased focus on the small, constrained devices There has been an increased focus on the small, constrained devices
that make up the Internet of Things (IOT). One of the standards that that make up the Internet of Things (IOT). One of the standards that
has come out of this process is the Concise Binary Object has come out of this process is the Concise Binary Object
Representation (CBOR). CBOR extended the data model of the Representation (CBOR). CBOR extended the data model of the
JavaScript Object Notation (JSON) by allowing for binary data among JavaScript Object Notation (JSON) by allowing for binary data among
other changes. CBOR is being adopted by several of the IETF working other changes. CBOR is being adopted by several of the IETF working
groups dealing with the IOT world as their encoding of data groups dealing with the IOT world as their encoding of data
structures. CBOR was designed specifically to be both small in terms structures. CBOR was designed specifically to be both small in terms
of messages transport and implementation size as well having a schema of messages transport and implementation size as well having a schema
free decoder. A need exists to provide basic message security free decoder. A need exists to provide basic message security
services for IOT and using CBOR as the message encoding format makes services for IOT and using CBOR as the message encoding format makes
sense. sense.
The JOSE working group produced a set of documents The JOSE working group produced a set of documents
[RFC7515][RFC7516][RFC7517][RFC7518] that defined how to perform [RFC7515][RFC7516][RFC7517][RFC7518] using JSON [RFC7159] that
encryption, signatures and message authentication (MAC) operations specified how to process encryption, signatures and message
for JSON documents and then to encode the results using the JSON authentication (MAC) operations, and how to encode keys using JSON.
format [RFC7159]. This document does the same work for use with the This document does the same work for use with the CBOR [RFC7049]
CBOR [RFC7049] document format. While there is a strong attempt to document format. While there is a strong attempt to keep the flavor
keep the flavor of the original JOSE documents, two considerations of the original JOSE documents, two considerations are taken into
are taken into account: account:
o CBOR has capabilities that are not present in JSON and should be o CBOR has capabilities that are not present in JSON and should be
used. One example of this is the fact that CBOR has a method of used. One example of this is the fact that CBOR has a method of
encoding binary directly without first converting it into a base64 encoding binary directly without first converting it into a base64
encoded string. encoded string.
o COSE is not a direct copy of the JOSE specification. In the o COSE is not a direct copy of the JOSE specification. In the
process of creating COSE, decisions that were made for JOSE were process of creating COSE, decisions that were made for JOSE were
re-examined. In many cases different results were decided on as re-examined. In many cases different results were decided on as
the criteria were not always the same as for JOSE. the criteria were not always the same as for JOSE.
skipping to change at page 5, line 25 skipping to change at page 5, line 25
o Signed messages separate the concept of protected and unprotected o Signed messages separate the concept of protected and unprotected
parameters that are for the content and the signature. parameters that are for the content and the signature.
o Recipient processing has been made more uniform. A recipient o Recipient processing has been made more uniform. A recipient
structure is required for all recipients rather than only for structure is required for all recipients rather than only for
some. some.
o MAC messages are separated from signed messages. o MAC messages are separated from signed messages.
o MAC messages have the ability to do use all recipient algorithms o MAC messages have the ability to use all recipient algorithms on
on the MAC authentication key. the MAC authentication key.
o Use binary encodings for binary data rather than base64url o Use binary encodings for binary data rather than base64url
encodings. encodings.
o Combine the authentication tag for encryption algorithms with the o Combine the authentication tag for encryption algorithms with the
ciphertext. ciphertext.
o Remove the flattened mode of encoding. Forcing the use of an o Remove the flattened mode of encoding. Forcing the use of an
array of recipients at all times forces the message size to be two array of recipients at all times forces the message size to be two
bytes larger, but one gets a corresponding decrease in the bytes larger, but one gets a corresponding decrease in the
skipping to change at page 6, line 19 skipping to change at page 6, line 19
There is a version of a CBOR grammar in the CBOR Data Definition There is a version of a CBOR grammar in the CBOR Data Definition
Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. An Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. An
informational version of the CBOR grammar that reflects what is in informational version of the CBOR grammar that reflects what is in
the prose can be found in Appendix A. CDDL has not been fixed, so the prose can be found in Appendix A. CDDL has not been fixed, so
this grammar may will only work with the version of CDDL at the time this grammar may will only work with the version of CDDL at the time
of publishing. of publishing.
The document was developed by first working on the grammar and then The document was developed by first working on the grammar and then
developing the prose to go with it. An artifact of this is that the developing the prose to go with it. An artifact of this is that the
prose was written using the primitive type strings defined by early prose was written using the primitive type strings defined by early
versions CDDL. In this specification the following primitive types versions CDDL. In this specification, the following primitive types
are used: are used:
bstr - byte string (major type 2). bstr - byte string (major type 2).
int - an unsigned integer or a negative integer. int - an unsigned integer or a negative integer.
nil - a null value (major type 7, value 22). nil - a null value (major type 7, value 22).
nint - a negative integer (major type 1). nint - a negative integer (major type 1).
tstr - a UTF-8 text string (major type 3). tstr - a UTF-8 text string (major type 3).
uint - an unsigned integer (major type 0). uint - an unsigned integer (major type 0).
bool - a boolean value (true: major type 7, value 21, false: major
type 7, value 20).
Text from here to start of next section to be removed Text from here to start of next section to be removed
NOTE: For the purposes of review, we are currently interlacing the NOTE: For the purposes of review, we are currently interlacing the
CDDL grammar into the text of document. This is being done for CDDL grammar into the text of document. This is being done for
simplicity of comparison of the grammar against the prose. The simplicity of comparison of the grammar against the prose. The
grammar will be removed to an appendix during WGLC. grammar will be removed to an appendix during WGLC.
start = COSE_Untagged_Message / COSE_Tagged_Message / start = COSE_Untagged_Message / COSE_Tagged_Message /
COSE_Key / COSE_KeySet COSE_Key / COSE_KeySet / Internal_Types
1.4. CBOR Related Terminology 1.4. CBOR Related Terminology
In JSON, maps are called objects and only have one kind of map key: a In JSON, maps are called objects and only have one kind of map key: a
string. In COSE, we use both strings and integers (both negative and string. In COSE, we use both strings and integers (both negative and
non-negative integers) as map keys, as well as data items to identify non-negative integers) as map keys. The integers are used for
specific choices. The integers (both positive and negative) are used compactness of encoding and easy comparison. (Generally, in this
for compactness of encoding and easy comparison. (Generally, in this
document the value zero is going to be reserved and not used.) Since document the value zero is going to be reserved and not used.) Since
the work "key" is mainly used in its other meaning, as a the work "key" is mainly used in its other meaning, as a
cryptographic key, we use the term "label" for this usage of either cryptographic key, we use the term "label" for this usage as a map
an integer or a string to identify map keys and choose data items. keys.
Text from here to start of next section to be removed Text from here to start of next section to be removed
label = int / tstr label = int / tstr
values = any values = any
1.5. Document Terminology 1.5. Document Terminology
In this document we use the following terminology: [CREF2] In this document we use the following terminology: [CREF2]
skipping to change at page 8, line 7 skipping to change at page 8, line 9
need to specify some type of discovery method of algorithm need to specify some type of discovery method of algorithm
capabilities. The discovery method may be as simple as requiring capabilities. The discovery method may be as simple as requiring
preconfiguration of the set of algorithms to providing a discovery preconfiguration of the set of algorithms to providing a discovery
method built into the protocol. S/MIME provided a number of method built into the protocol. S/MIME provided a number of
different ways to approach the problem: different ways to approach the problem:
o Advertising in the message (S/MIME capabilities) [RFC5751]. o Advertising in the message (S/MIME capabilities) [RFC5751].
o Advertising in the certificate (capabilities extension) [RFC4262] o Advertising in the certificate (capabilities extension) [RFC4262]
o Minimum requirements for the S/MIME which have been updated over o Minimum requirements for the S/MIME, which have been updated over
time [RFC2633][RFC5751] time [RFC2633][RFC5751]
2. Basic COSE Structure 2. Basic COSE Structure
The COSE Message structure is designed so that there can be a large The COSE Message structure is designed so that there can be a large
amount of common code when parsing and processing the different amount of common code when parsing and processing the different
security messages. All of the message structures are built on a CBOR security messages. All of the message structures are built on a CBOR
array type. The first three elements of the array contains the same array type. The first three elements of the array contains the same
basic information. The first element is a set of protected header basic information. The first element is a set of protected header
information. The second element is a set of unprotected header information. The second element is a set of unprotected header
skipping to change at page 9, line 43 skipping to change at page 9, line 45
unless the re-encoded byte string is identical to the decoded byte unless the re-encoded byte string is identical to the decoded byte
string.) This finesses the problem of all parties needing to be string.) This finesses the problem of all parties needing to be
able to do a common canonical encoding. able to do a common canonical encoding.
unprotected: Contains parameters about the current layer that are unprotected: Contains parameters about the current layer that are
not cryptographically protected. not cryptographically protected.
Only parameters that deal with the current layer are to be placed at Only parameters that deal with the current layer are to be placed at
that layer. As an example of this, the parameter 'content type' that layer. As an example of this, the parameter 'content type'
describes the content of the message being carried in the message. describes the content of the message being carried in the message.
As such this parameter is placed only in the content layer and is not As such, this parameter is placed only in the content layer and is
placed in the recipient or signature layers. In principle, one not placed in the recipient or signature layers. In principle, one
should be able to process any given layer without reference to any should be able to process any given layer without reference to any
other layer. (The only data that should need to cross layers is the other layer. (The only data that should need to cross layers is the
cryptographic key.) cryptographic key.)
The buckets are present in all of the security objects defined in The buckets are present in all of the security objects defined in
this document. The fields in order are the 'protected' bucket (as a this document. The fields in order are the 'protected' bucket (as a
CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map'
type). The presence of both buckets is required. The parameters type). The presence of both buckets is required. The parameters
that go into the buckets come from the IANA "COSE Header Parameters" that go into the buckets come from the IANA "COSE Header Parameters"
(Section 15.2). Some common parameters are defined in the next (Section 15.2). Some common parameters are defined in the next
section, but a number of parameters are defined throughout this section, but a number of parameters are defined throughout this
document. document.
Text from here to start of next section to be removed [CREF4] Text from here to start of next section to be removed [CREF4]
skipping to change at page 11, line 26 skipping to change at page 11, line 28
parameter if the content structure is potentially ambiguous. parameter if the content structure is potentially ambiguous.
kid This parameter one of the ways that can be used to find the key 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 to be used. The value of this parameter is matched against the
'kid' member in a COSE_Key structure. Applications MUST NOT 'kid' member in a COSE_Key structure. Applications MUST NOT
assume that 'kid' values are unique. There may be more than one 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 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 keys need to be checked to find the correct one. The internal
structure of 'kid' values is not defined and generally cannot be structure of 'kid' values is not defined and generally cannot be
relied on by applications. Key identifier values are hints about relied on by applications. Key identifier values are hints about
which key to use, they are not directly a security critical field, which key to use. They are not directly a security critical
for this reason they can be placed in the unprotected headers field. For this reason, they can be placed in the unprotected
bucket. headers bucket.
nonce This parameter holds either a nonce or Initialization Vector nonce This parameter holds either a nonce or Initialization Vector
value. The value can be used either as a counter value for a value. The value can be used either as a counter value for a
protocol or as an IV for an algorithm. protocol or as an IV for an algorithm.
counter signature This parameter holds a counter signature value. counter signature This parameter holds a counter signature value.
Counter signatures provide a method of having a second party sign Counter signatures provide a method of having a second party sign
some data, the counter signature can occur as an unprotected some data. The counter signature can occur as an unprotected
attribute in any of the following structures: COSE_Sign, attribute in any of the following structures: COSE_Sign,
COSE_signature, COSE_enveloped, COSE_recipient, COSE_signature, COSE_enveloped, COSE_recipient,
COSE_encryptedData, COSE_mac. These structures all have the same COSE_encryptedData, COSE_mac. These structures all have the same
basic structure so that a consistent calculation of the counter basic structure so that a consistent calculation of the counter
signature can be computed. Details on computing counter signature can be computed. Details on computing counter
signatures are found in Section 4.3. signatures are found in Section 4.3.
creation time This parameter provides the time the content was creation time This parameter provides the time the content was
created. For signatures and recipient structures, this would be created. For signatures and recipient structures, this would be
the time that the signature or recipient key object was created. the time that the signature or recipient key object was created.
skipping to change at page 15, line 12 skipping to change at page 15, line 12
signature : bstr signature : bstr
] ]
4.1. Externally Supplied Data 4.1. Externally Supplied Data
One of the features that we supply in the COSE document is the One of the features that we supply in the COSE document is the
ability for applications to provide additional data to be ability for applications to provide additional data to be
authenticated as part of the security, but that is not carried as authenticated as part of the security, but that is not carried as
part of the COSE object. The primary reason for supporting this can part of the COSE object. The primary reason for supporting this can
be seen by looking at the CoAP message structure [RFC7252] where the be seen by looking at the CoAP message structure [RFC7252] where the
facility exists for options to be carried before the payload. An facility exists for options to be carried before the payload.
example of data that can be placed in this location would be [CREF6] An example of data that can be placed in this location would
transaction ids and nonces to check for replay protection. If the be transaction ids and nonces to check for replay protection. If the
data is in the options section, then it is available for routers to data is in the options section, then it is available for routers to
help in performing the replay detection and prevention. However, it help in performing the replay detection and prevention. However, it
may also be desired to protect these values so that they cannot be may also be desired to protect these values so that they cannot be
modified in transit. This is the purpose of the externally supplied modified in transit. This is the purpose of the externally supplied
data field. data field.
This document describes the process for using a byte array of This document describes the process for using a byte array of
externally supplied authenticated data, however the method of externally supplied authenticated data, however the method of
constructing the byte array is a function of the application. constructing the byte array is a function of the application.
Applications which use this feature need to define how the externally Applications that use this feature need to define how the externally
supplied authenticated data is to be constructed. Such a supplied authenticated data is to be constructed. Such a
construction needs to take into account the following issues: construction needs to take into account the following issues:
o If multiple items are included, care needs to be taken that data o If multiple items are included, care needs to be taken that data
cannot bleed between the items. This is usually addressed by cannot bleed between the items. This is usually addressed by
making fields fixed width and/or encoding the length of the field. making fields fixed width and/or encoding the length of the field.
Using options from CoAP as an example, these fields use a TLV Using options from CoAP as an example, these fields use a TLV
structure so they can be concatenated without any problems. structure so they can be concatenated without any problems.
o If multiple items are included, a defined order for the items o If multiple items are included, a defined order for the items
needs to be defined. Using options from CoAP as an example, an needs to be defined. Using options from CoAP as an example, an
application could state that the fields are to be ordered by the application could state that the fields are to be ordered by the
option number. option number.
4.2. Signing and Verification Process 4.2. Signing and Verification Process
In order to create a signature, a consistent byte stream is needed in In order to create a signature, a consistent byte stream is needed in
order to process. This document uses a CBOR array to construct the order to process. This algorithm takes in the body information
byte stream to be processed. The fields of the array in order are: (COSE_Sign), the signer information (COSE_Signer), and the
application data (External). This document uses a CBOR array to
construct the byte stream to be processed. The fields of the array
in order are:
1. The body protected attributes. This is a bstr type containing 1. The protected attributes from the body structure encoded in a
the protected attributes of the body. bstr type.
2. The signature protected attributes. This is a bstr type 2. The protected attributes from the signer structure encoded in a
containing the protected attributes of the signature. bstr type.
3. The external protected attributes. This is a bstr type 3. The protected attributes from the application encoded in a bstr
containing the protected attributes external to the type. If this field is not supplied, it defaults to a zero
COSE_Signature structure. length binary string.
4. The payload to be signed. The payload is encoded in a bstr. The 4. The payload to be signed encoded in a bstr type. The payload is
payload is placed here independent of how it is transported. placed here independent of how it is transported.
How to compute a signature: How to compute a signature:
1. Create a CBOR array and populate it with the appropriate fields. 1. Create a CBOR array and populate it with the appropriate fields.
For body_protected and sign_protected, if the fields are not For body_protected and sign_protected, if the fields are not
present in their corresponding maps, a bstr of length zero is present in their corresponding maps, a bstr of length zero is
used. used.
2. If the application has supplied external additional authenticated 2. If the application has supplied external additional authenticated
data to be included in the computation, then it is placed in the data to be included in the computation, then it is placed in the
skipping to change at page 18, line 7 skipping to change at page 18, line 7
in the same manner as from the COSE_Sign structure. in the same manner as from the COSE_Sign structure.
While one can create a counter signature for a COSE_Sign structure, While one can create a counter signature for a COSE_Sign structure,
there is not much of a point to doing so. It is equivalent to create there is not much of a point to doing so. It is equivalent to create
a new COSE_signature structure and placing it in the signatures a new COSE_signature structure and placing it in the signatures
array. It is strongly suggested that it not be done, but it is not array. It is strongly suggested that it not be done, but it is not
banned. banned.
5. Encryption objects 5. Encryption objects
COSE supports two different encryption structures. OOSE_enveloped is COSE supports two different encryption structures. COSE_enveloped is
used when the key needs to be explicitly identified. This structure used when the key needs to be explicitly identified. This structure
supports the use of recipient structures to allow for random content supports the use of recipient structures to allow for random content
encryption keys to be used. COSE_encrypted is used when a recipient encryption keys to be used. COSE_encrypted is used when a recipient
structure is not needed because the key to be used is known structure is not needed because the key to be used is known
implicitly. implicitly.
5.1. Enveloped COSE structure 5.1. Enveloped COSE structure
The enveloped structure allows for one or more recipients of a The enveloped structure allows for one or more recipients of a
message. There are provisions for parameters about the content and message. There are provisions for parameters about the content and
parameters about the recipient information to be carried in the parameters about the recipient information to be carried in the
message. The parameters associated with the content can be message. The parameters associated with the content can be
authenticated by the content encryption algorithm. The parameters authenticated by the content encryption algorithm. The parameters
associated with the recipient can be authenticated by the recipient associated with the recipient can be authenticated by the recipient
algorithm (when the algorithm supports it). Examples of parameters algorithm (when the algorithm supports it). Examples of parameters
about the content are the type of the content, when the content was about the content are the type of the content, when the content was
created, and the content encryption algorithm. Examples of created, and the content encryption algorithm. Examples of
parameters about the recipient are the recipient's key identifier, parameters about the recipient are the recipient's key identifier,
the recipient encryption algorithm. the recipient encryption algorithm.
In COSE, the same techniques and structures for encrypting both the In COSE, the same techniques and structures are used for encrypting
plain text and the keys used to protect the text. This is different both the plain text and the keys used to protect the text. This is
from the approach used by both [RFC5652] and [RFC7516] where different from the approach used by both [RFC5652] and [RFC7516]
different structures are used for the content layer and for the where different structures are used for the content layer and for the
recipient layer. recipient layer.
The COSE_encrypt structure is a CBOR array. The fields of the array The COSE_encrypt structure is a CBOR array. The fields of the array
in order are: in order are:
protected is described in Section 3. protected is described in Section 3.
unprotected is described in Section 3. unprotected is described in Section 3.
ciphertext contains the encrypted plain text encoded as a bstr. If ciphertext contains the encrypted plain text encoded as a bstr. If
skipping to change at page 19, line 10 skipping to change at page 19, line 10
COSE_recipient. COSE_recipient.
The COSE_recipient structure is a CBOR array. The fields of the The COSE_recipient structure is a CBOR array. The fields of the
array in order are: array in order are:
protected is described in Section 3. protected is described in Section 3.
unprotected is described in Section 3. unprotected is described in Section 3.
ciphertext contains the encrypted key encoded as a bstr. If there ciphertext contains the encrypted key encoded as a bstr. If there
is not an encrypted key, then this field is encoded as a nil type. is not an encrypted key, then this field is encoded as a nil
value.
recipients contains an array of recipient information structures. recipients contains an array of recipient information structures.
The type for the recipient information structure is a The type for the recipient information structure is a
COSE_recipient. If there are no recipient information structures, COSE_recipient. If there are no recipient information structures,
this element is absent. this element is absent.
Text from here to start of next section to be removed Text from here to start of next section to be removed
COSE_Enveloped_Tagged = #6.998(COSE_enveloped) ; Replace 998 with TBD32 COSE_Enveloped_Tagged = #6.998(COSE_enveloped) ; Replace 998 with TBD32
skipping to change at page 19, line 43 skipping to change at page 19, line 44
? recipients: [+COSE_recipient] ? recipients: [+COSE_recipient]
] ]
5.1.1. Recipient Algorithm Classes 5.1.1. Recipient Algorithm Classes
A typical encrypted message consists of an encrypted content and an A typical encrypted message consists of an encrypted content and an
encrypted CEK for one or more recipients. The content-encryption key encrypted CEK for one or more recipients. The content-encryption key
is encrypted for each recipient, using a key specific to that is encrypted for each recipient, using a key specific to that
recipient. The details of this encryption depends on which class the recipient. The details of this encryption depends on which class the
recipient algorithm falls into. Specific details on each of the recipient algorithm falls into. Specific details on each of the
classes can be found in Section 12. A short summary of the six classes can be found in Section 12. A short summary of the five
recipient algorithm classes is: recipient algorithm classes is:
none: The CEK is the same as the identified previously distributed none: The CEK is the same as the identified previously distributed
symmetric key or derived from a previously distributed secret. symmetric key or derived from a previously distributed secret.
symmetric key-encryption keys: The CEK is encrypted using a symmetric key-encryption keys: The CEK is encrypted using a
previously distributed symmetric key-encryption key. previously distributed symmetric key-encryption key.
key agreement: the recipient's public key and a sender's private key key agreement: the recipient's public key and a sender's private key
are used to generate a pairwise secret, a KDF is applied to derive are used to generate a pairwise secret, a KDF is applied to derive
a key, and then the CEK is either the derived key or encrypted by a key, and then the CEK is either the derived key or encrypted by
the derived key. the derived key.
key transport: the CEK is encrypted in the recipient's public key key transport: the CEK is encrypted with the recipient's public key
passwords: the CEK is encrypted in a key-encryption key that is passwords: the CEK is encrypted in a key-encryption key that is
derived from a password. derived from a password.
5.2. Encrypted COSE structure 5.2. Encrypted COSE structure
The encrypted structure does not have the ability to specify The encrypted structure does not have the ability to specify
recipients of the message. The structure assumes that the recipient recipients of the message. The structure assumes that the recipient
of the object will already know the identity of the key to be used in of the object will already know the identity of the key to be used in
order to decrypt the message. If a key needs to be identified to the order to decrypt the message. If a key needs to be identified to the
skipping to change at page 22, line 36 skipping to change at page 22, line 36
In this section we describe the structure and methods to be used when In this section we describe the structure and methods to be used when
doing MAC authentication in COSE. This document allows for the use doing MAC authentication in COSE. This document allows for the use
of all of the same classes of recipient algorithms as are allowed for of all of the same classes of recipient algorithms as are allowed for
encryption. encryption.
When using MAC operations, there are two modes in which it can be When using MAC operations, there are two modes in which it can be
used. The first is just a check that the content has not been used. The first is just a check that the content has not been
changed since the MAC was computed. Any class of recipient algorithm changed since the MAC was computed. Any class of recipient algorithm
can be used for this purpose. The second mode is to both check that can be used for this purpose. The second mode is to both check that
the content has not been changed since the MAC was computed, and to the content has not been changed since the MAC was computed, and to
use recipient algorithm to verify who sent it. The classes of use the recipient algorithm to verify who sent it. The classes of
recipient algorithms that support this are those that use a pre- recipient algorithms that support this are those that use a pre-
shared secret or do static-static key agreement (without the key wrap shared secret or do static-static key agreement (without the key wrap
step). In both of these cases the entity MACing the message can be step). In both of these cases, the entity MACing the message can be
validated by a key binding. (The binding of identity assumes that validated by a key binding. (The binding of identity assumes that
there are only two parties involved and you did not send the message there are only two parties involved and you did not send the message
yourself.) yourself.)
The COSE_Mac structure is a CBOR array. The fields of the array in The COSE_Mac structure is a CBOR array. The fields of the array in
order are: order are:
protected is described in Section 3. protected is described in Section 3.
unprotected is described in Section 3. unprotected is described in Section 3.
skipping to change at page 24, line 26 skipping to change at page 24, line 26
the IANA registry 'COSE Key Type Parameters' (Section 15.6). the IANA registry 'COSE Key Type Parameters' (Section 15.6).
A COSE Key Set uses a CBOR array object as its underlying type. The A COSE Key Set uses a CBOR array object as its underlying type. The
values of the array elements are COSE Keys. A Key Set MUST have at values of the array elements are COSE Keys. A Key Set MUST have at
least one element in the array. least one element in the array.
The element "kty" is a required element in a COSE_Key map. The element "kty" is a required element in a COSE_Key map.
Text from here to start of next section to be removed Text from here to start of next section to be removed
The CDDL grammar describing a COSE_Key and COSE_KeySet is: [CREF6] The CDDL grammar describing a COSE_Key and COSE_KeySet is: [CREF7]
COSE_Key = { COSE_Key = {
key_kty => tstr / int, key_kty => tstr / int,
? key_ops => [+ (tstr / int) ], ? key_ops => [+ (tstr / int) ],
? key_alg => tstr / int, ? key_alg => tstr / int,
? key_kid => bstr, ? key_kid => bstr,
* label => values * label => values
} }
COSE_KeySet = [+COSE_Key] COSE_KeySet = [+COSE_Key]
skipping to change at page 27, line 5 skipping to change at page 26, line 41
| agree | | | | agree | | |
+---------+-------+-------------------------------------------------+ +---------+-------+-------------------------------------------------+
Table 3: Key Operation Values Table 3: Key Operation Values
Text from here to start of next section to be removed Text from here to start of next section to be removed
The following provides a CDDL fragment which duplicates the The following provides a CDDL fragment which duplicates the
assignment labels from Table 2 and Table 3. assignment labels from Table 2 and Table 3.
;key_labels ;key_labels
key_kty=1 key_kty=1
key_kid=2 key_kid=2
key_alg=3 key_alg=3
key_ops=4 key_ops=4
;key_ops values ;key_ops values
key_ops_sign=1 key_ops_values = (key_ops_sign:1, key_ops_verify:2, key_ops_encrypt:3,
key_ops_verify=2 key_ops_decrypt:4, key_ops_wrap:5, key_ops_unwrap:6,
key_ops_encrypt=3 key_ops_agree:7)
key_ops_decrypt=4
key_ops_wrap=5
key_ops_unwrap=6
key_ops_agree=7
8. Signature Algorithms 8. Signature Algorithms
There are two basic signature algorithm structures that can be used. There are two basic signature algorithm structures that can be used.
The first is the common signature with appendix. In this structure, The first is the common signature with appendix. In this structure,
the message content is processed and a signature is produced, the the message content is processed and a signature is produced, the
signature is called the appendix. This is the message structure used signature is called the appendix. This is the message structure used
by our common algorithms such as ECDSA and RSASSA-PSS. (In fact the by our common algorithms such as ECDSA and RSASSA-PSS. (In fact the
SSA in RSASSA-PSS stands for Signature Scheme with Appendix.) The SSA in RSASSA-PSS stands for Signature Scheme with Appendix.) The
basic structure becomes: basic structure becomes:
signature = Sign(message content, key) signature = Sign(message content, key)
valid = Verification(message content, key, signature) valid = Verification(message content, key, signature)
The second is a signature with message recovery. (An example of such The second is a signature with message recovery. (An example of such
an algorithm is [PVSig].) In this structure, the message content is an algorithm is [PVSig].) In this structure, the message content is
processed, but part of is included in the signature. Moving bytes of processed, but part of it is included in the signature. Moving bytes
the message content into the signature allows for an effectively of the message content into the signature allows for an effectively
smaller signature, the signature size is still potentially large, but smaller signature, the signature size is still potentially large, but
the message content is shrunk. This has implications for systems the message content is shrunk. This has implications for systems
implementing these algorithms and for applications that use them. implementing these algorithms and for applications that use them.
The first is that the message content is not fully available until The first is that the message content is not fully available until
after a signature has been validated. Until that point the part of after a signature has been validated. Until that point the part of
the message contained inside of the signature is unrecoverable. The the message contained inside of the signature is unrecoverable. The
second is that the security analysis of the strength of the signature second is that the security analysis of the strength of the signature
is very much based on the structure of the message content. Messages is very much based on the structure of the message content. Messages
which are highly predictable require additional randomness to be which are highly predictable require additional randomness to be
supplied as part of the signature process, in the worst case it supplied as part of the signature process. In the worst case, it
becomes the same as doing a signature with appendix. Thirdly, in the becomes the same as doing a signature with appendix. Thirdly, in the
event that multiple signatures are applied to a message, all of the event that multiple signatures are applied to a message, all of the
signature algorithms are going to be required to consume the same signature algorithms are going to be required to consume the same
number of bytes of message content. number of bytes of message content.
signature, message sent = Sign(message content, key) signature, message sent = Sign(message content, key)
valid, message content = Verification(message sent, key, signature) valid, message content = Verification(message sent, key, signature)
At this time, only signatures with appendixes are defined for use At this time, only signatures with appendixes are defined for use
skipping to change at page 28, line 23 skipping to change at page 28, line 11
a signature with message recovery algorithm due to the effective size a signature with message recovery algorithm due to the effective size
reduction that is possible. Implementations will need to keep this reduction that is possible. Implementations will need to keep this
in mind for later possible integration. in mind for later possible integration.
8.1. ECDSA 8.1. ECDSA
ECDSA [DSS] defines a signature algorithm using ECC. ECDSA [DSS] defines a signature algorithm using ECC.
The ECDSA signature algorithm is parameterized with a hash function The ECDSA signature algorithm is parameterized with a hash function
(h). In the event that the length of the hash function output is (h). In the event that the length of the hash function output is
greater than group of the key, the left most bytes of the hash output greater than the group of the key, the left-most bytes of the hash
are used. output are used.
The algorithms defined in this document can be found in Table 4. The algorithms defined in this document can be found in Table 4.
+-------+-------+---------+------------------+ +-------+-------+---------+------------------+
| name | value | hash | description | | name | value | hash | description |
+-------+-------+---------+------------------+ +-------+-------+---------+------------------+
| ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 | | ES256 | -7 | SHA-256 | ECDSA w/ SHA-256 |
| | | | | | | | | |
| ES384 | -8 | SHA-384 | ECDSA w/ SHA-384 | | ES384 | -8 | SHA-384 | ECDSA w/ SHA-384 |
| | | | | | | | | |
skipping to change at page 29, line 27 skipping to change at page 29, line 12
Signature = I2OSP(R, n) | I2OSP(S, n) Signature = I2OSP(R, n) | I2OSP(S, n)
where n = ceiling(key_length / 8) where n = ceiling(key_length / 8)
8.1.1. Security Considerations 8.1.1. Security Considerations
The security strength of the signature is no greater than the minimum The security strength of the signature is no greater than the minimum
of the security strength associated with the bit length of the key of the security strength associated with the bit length of the key
and the security strength of the hash function. and the security strength of the hash function.
System which have poor random number generation can leak their keys System which have poor random number generation can leak their keys
by signing two different messages with the same value of 'k'. by signing two different messages with the same value 'k' (the per-
[RFC6979] provides a method to deal with this problem by making 'k' message random value). [RFC6979] provides a method to deal with this
be deterministic based on the message content rather than randomly problem by making 'k' be deterministic based on the message content
generated. Applications which specify ECDSA should evaluate the rather than randomly generated. Applications that specify ECDSA
ability to get good random number generation and require this when it should evaluate the ability to get good random number generation and
is not possible. Note: Use of this technique a good idea even when require this when it is not possible. Note: Use of this technique a
good random number generation exists. Doing so both reduces the good idea even when good random number generation exists. Doing so
possibility of having the same value of 'k' in two signature both reduces the possibility of having the same value of 'k' in two
operations, but allows for reproducible signature values which helps signature operations, but allows for reproducible signature values
testing. which helps testing.
There are two substitution that can theoretically be mounted against There are two substitution attacks that can theoretically be mounted
the ECDSA signature algorithm. against the ECDSA signature algorithm.
o Changing the curve used to validate the signature: If one changes o Changing the curve used to validate the signature: If one changes
the curve used to validate the signature, then potentially one the curve used to validate the signature, then potentially one
could have a two messages with the same signature each computed could have a two messages with the same signature each computed
under a different curve. The only requirement on the new curve is under a different curve. The only requirement on the new curve is
that its order be the same as the old one and it be acceptable to that its order be the same as the old one and it be acceptable to
the client. An example would be to change from using the curve the client. An example would be to change from using the curve
secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit secp256r1 (aka P-256) to using secp256k1. (Both are 256 bit
curves.) We current do not have any way to deal with this version curves.) We current do not have any way to deal with this version
of the attack except to restrict the overall set of curves that of the attack except to restrict the overall set of curves that
skipping to change at page 30, line 20 skipping to change at page 30, line 4
collide with a SHA-256 bit hash value.) This attack can be collide with a SHA-256 bit hash value.) This attack can be
mitigated by including the signature algorithm identifier in the mitigated by including the signature algorithm identifier in the
data to be signed. data to be signed.
9. Message Authentication (MAC) Algorithms 9. Message Authentication (MAC) Algorithms
Message Authentication Codes (MACs) provide data authentication and Message Authentication Codes (MACs) provide data authentication and
integrity protection. They provide either no or very limited data integrity protection. They provide either no or very limited data
origination. (One cannot, for example, be used to prove the identity origination. (One cannot, for example, be used to prove the identity
of the sender to a third party.) of the sender to a third party.)
MACs use the same basic structure as signature with appendix
MACs are designed in the same basic structure as signature with algorithms. The message content is processed and an authentication
appendix algorithms. The message content is processed and an code is produced. The authentication code is frequently called a
authentication code is produced, the authentication code is tag. The basic structure becomes:
frequently called a tag. The basic structure becomes:
tag = MAC_Create(message content, key) tag = MAC_Create(message content, key)
valid = MAC_Verify(message content, key, tag) valid = MAC_Verify(message content, key, tag)
MAC algorithms can be based on either a block cipher algorithm (i.e. MAC algorithms can be based on either a block cipher algorithm (i.e.
AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a
MAC algorithm for each of these two constructions. MAC algorithm for each of these two constructions.
9.1. Hash-based Message Authentication Codes (HMAC) 9.1. Hash-based Message Authentication Codes (HMAC)
skipping to change at page 31, line 4 skipping to change at page 30, line 34
security of hash algorithms such as MD5 has decreased over time, the security of hash algorithms such as MD5 has decreased over time, the
security of HMAC combined with MD5 has not yet been shown to be security of HMAC combined with MD5 has not yet been shown to be
compromised [RFC6151]. compromised [RFC6151].
The HMAC algorithm is parameterized by an inner and outer padding, a The HMAC algorithm is parameterized by an inner and outer padding, a
hash function (h) and an authentication tag value length. For this hash function (h) and an authentication tag value length. For this
specification, the inner and outer padding are fixed to the values specification, the inner and outer padding are fixed to the values
set in [RFC2104]. The length of the authentication tag corresponds set in [RFC2104]. The length of the authentication tag corresponds
to the difficulty of producing a forgery. For use in constrained to the difficulty of producing a forgery. For use in constrained
environments, we define a set of HMAC algorithms that are truncated. environments, we define a set of HMAC algorithms that are truncated.
There are currently no known issues when truncating, however the There are currently no known issues when truncating, however the
security strength of the message tag is correspondingly reduced in security strength of the message tag is correspondingly reduced in
strength. When truncating, the left most tag length bits are kept strength. When truncating, the left-most tag length bits are kept
and transmitted. and transmitted.
The algorithm defined in this document can be found in Table 5. The algorithm defined in this document can be found in Table 5.
+-----------+-------+---------+--------+----------------------------+ +-----------+-------+---------+--------+----------------------------+
| name | value | Hash | Length | description | | name | value | Hash | Length | description |
+-----------+-------+---------+--------+----------------------------+ +-----------+-------+---------+--------+----------------------------+
| HMAC | * | SHA-256 | 64 | HMAC w/ SHA-256 truncated | | HMAC | * | SHA-256 | 64 | HMAC w/ SHA-256 truncated |
| 256/64 | | | | to 64 bits | | 256/64 | | | | to 64 bits |
| | | | | | | | | | | |
skipping to change at page 31, line 31 skipping to change at page 31, line 24
| HMAC | 5 | SHA-384 | 384 | HMAC w/ SHA-384 | | HMAC | 5 | SHA-384 | 384 | HMAC w/ SHA-384 |
| 384/384 | | | | | | 384/384 | | | | |
| | | | | | | | | | | |
| HMAC | 6 | SHA-512 | 512 | HMAC w/ SHA-512 | | HMAC | 6 | SHA-512 | 512 | HMAC w/ SHA-512 |
| 512/512 | | | | | | 512/512 | | | | |
+-----------+-------+---------+--------+----------------------------+ +-----------+-------+---------+--------+----------------------------+
Table 5: HMAC Algorithm Values Table 5: HMAC Algorithm Values
Some recipient algorithms carry the key while others derive a key Some recipient algorithms carry the key while others derive a key
from secret data. For those algorithms which carry the key (i.e. from secret data. For those algorithms that carry the key (i.e.
RSA-OAEP and AES-KeyWrap), the size of the HMAC key SHOULD be the RSA-OAEP and AES-KeyWrap), the size of the HMAC key SHOULD be the
same size as the underlying hash function. For those algorithms same size as the underlying hash function. For those algorithms that
which derive the key, the derived key MUST be the same size as the derive the key, the derived key MUST be the same size as the
underlying hash function. underlying hash function.
If the key obtained from a key structure, the key type MUST be If the key is obtained from a key structure, the key type MUST be
'Symmetric'. Implementations creating and validating MAC values MUST 'Symmetric'. Implementations creating and validating MAC values MUST
validate that the key type, key length and algorithm are correct and validate that the key type, key length, and algorithm are correct and
appropriate for the entities involved. appropriate for the entities involved.
9.1.1. Security Considerations 9.1.1. Security Considerations
HMAC has proved to be resistant even when used with weakening hash HMAC has proved to be resistant to attack even when used with
algorithms. The current best method appears to be a brute force weakening hash algorithms. The current best method appears to be a
attack on the key. This means that key size is going to be directly brute force attack on the key. This means that key size is going to
related to the security of an HMAC operation. be directly related to the security of an HMAC operation.
9.2. AES Message Authentication Code (AES-CBC-MAC) 9.2. AES Message Authentication Code (AES-CBC-MAC)
AES-CBC-MAC is defined in [MAC]. AES-CBC-MAC is defined in [MAC].
AES-CBC-MAC is parameterized by the key length, the authentication AES-CBC-MAC is parameterized by the key length, the authentication
tag length and the IV used. For all of these algorithms, the IV is tag length and the IV used. For all of these algorithms, the IV is
fixed to all zeros. We provide an array of algorithms for various fixed to all zeros. We provide an array of algorithms for various
key lengths and tag lengths. The algorithms defined in this document key lengths and tag lengths. The algorithms defined in this document
are found in Table 6. are found in Table 6.
skipping to change at page 33, line 18 skipping to change at page 33, line 8
10. Content Encryption Algorithms 10. Content Encryption Algorithms
Content Encryption Algorithms provide data confidentiality for Content Encryption Algorithms provide data confidentiality for
potentially large blocks of data using a symmetric key. They provide potentially large blocks of data using a symmetric key. They provide
either no or very limited data origination. (One cannot, for either no or very limited data origination. (One cannot, for
example, be used to prove the identity of the sender to a third example, be used to prove the identity of the sender to a third
party.) The ability to provide data origination is linked to how the party.) The ability to provide data origination is linked to how the
symmetric key is obtained. symmetric key is obtained.
We restrict the set of legal content encryption algorithms to those We restrict the set of legal content encryption algorithms to those
which support authentication both of the content and additional data. that support authentication both of the content and additional data.
The encryption process will generate some type of authentication The encryption process will generate some type of authentication
value, but that value may be either explicit or implicit in terms of value, but that value may be either explicit or implicit in terms of
the algorithm definition. For simplicity sake, the authentication the algorithm definition. For simplicity sake, the authentication
code will normally be defined as being appended to the cipher text code will normally be defined as being appended to the cipher text
stream. The basic structure becomes: stream. The basic structure becomes:
ciphertext = Encrypt(message content, key, additional data) ciphertext = Encrypt(message content, key, additional data)
valid, message content = Decrypt(cipher text, key, additional data) valid, message content = Decrypt(cipher text, key, additional data)
skipping to change at page 33, line 43 skipping to change at page 33, line 33
10.1. AES GCM 10.1. AES GCM
The GCM mode is a generic authenticated encryption block cipher mode The GCM mode is a generic authenticated encryption block cipher mode
defined in [AES-GCM]. The GCM mode is combined with the AES block defined in [AES-GCM]. The GCM mode is combined with the AES block
encryption algorithm to define an AEAD cipher. encryption algorithm to define an AEAD cipher.
The GCM mode is parameterized with by the size of the authentication The GCM mode is parameterized with by the size of the authentication
tag. The size of the authentication tag is limited to a small set of tag. The size of the authentication tag is limited to a small set of
values. For this document however, the size of the authentication values. For this document however, the size of the authentication
tag is fixed at 128-bits. tag is fixed at 128 bits.
The set of algorithms defined in this document are in Table 7. The set of algorithms defined in this document are in Table 7.
+---------+-------+-----------------------------+ +---------+-------+-----------------------------+
| name | value | description | | name | value | description |
+---------+-------+-----------------------------+ +---------+-------+-----------------------------+
| A128GCM | 1 | AES-GCM mode w/ 128-bit key | | A128GCM | 1 | AES-GCM mode w/ 128-bit key |
| | | | | | | |
| A192GCM | 2 | AES-GCM mode w/ 192-bit key | | A192GCM | 2 | AES-GCM mode w/ 192-bit key |
| | | | | | | |
| A256GCM | 3 | AES-GCM mode w/ 256-bit key | | A256GCM | 3 | AES-GCM mode w/ 256-bit key |
+---------+-------+-----------------------------+ +---------+-------+-----------------------------+
Table 7: Algorithm Value for AES-GCM Table 7: Algorithm Value for AES-GCM
Keys may be obtained either from a key structure or from a recipient Keys may be obtained either from a key structure or from a recipient
structure. If the key obtained from a key structure, the key type structure. If the key obtained from a key structure, the key type
MUST be 'Symmetric'. Implementations creating and validating MAC MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST
values MUST validate that the key type, key length and algorithm are validate that the key type, key length and algorithm are correct and
correct and appropriate for the entities involved. appropriate for the entities involved.
10.1.1. Security Considerations 10.1.1. Security Considerations
When using AES-CCM the following restrictions MUST be enforced: When using AES-CCM, the following restrictions MUST be enforced:
o The key and nonce pair MUST be unique for every message encrypted. o The key and nonce pair MUST be unique for every message encrypted.
o The total amount of data encrypted MUST NOT exceed 2^39 - 256 o The total amount of data encrypted MUST NOT exceed 2^39 - 256
bits. An explicit check is required only in environments where it bits. An explicit check is required only in environments where it
is expected that it might be exceeded. is expected that it might be exceeded.
10.2. AES CCM 10.2. AES CCM
Counter with CBC-MAC (CCM) is a generic authentication encryption Counter with CBC-MAC (CCM) is a generic authentication encryption
skipping to change at page 34, line 50 skipping to change at page 34, line 38
The CCM mode has two parameter choices. The first choice is M, the The CCM mode has two parameter choices. The first choice is M, the
size of the authentication field. The choice of the value for M size of the authentication field. The choice of the value for M
involves a trade-off between message expansion and the probably that involves a trade-off between message expansion and the probably that
an attacker can undetectably modify a message. The second choice is an attacker can undetectably modify a message. The second choice is
L, the size of the length field. This value requires a trade-off L, the size of the length field. This value requires a trade-off
between the maximum message size and the size of the Nonce. between the maximum message size and the size of the Nonce.
It is unfortunate that the specification for CCM specified L and M as It is unfortunate that the specification for CCM specified L and M as
a count of bytes rather than a count of bits. This leads to possible a count of bytes rather than a count of bits. This leads to possible
misunderstandings where AES-CCM-8 is frequently used to refer to a misunderstandings where AES-CCM-8 is frequently used to refer to a
version of CCM mode where the size of the authentication is 64-bits version of CCM mode where the size of the authentication is 64 bits
and not 8-bits. These values have traditionally been specified as and not 8 bits. These values have traditionally been specified as
bit counts rather than byte counts. This document will follow the bit counts rather than byte counts. This document will follow the
tradition of using bit counts so that it is easier to compare the tradition of using bit counts so that it is easier to compare the
different algorithms presented in this document. different algorithms presented in this document.
We define a matrix of algorithms in this document over the values of We define a matrix of algorithms in this document over the values of
L and M. Constrained devices are usually operating in situations L and M. Constrained devices are usually operating in situations
where they use short messages and want to avoid doing recipient where they use short messages and want to avoid doing recipient
specific cryptographic operations. This favors smaller values of M specific cryptographic operations. This favors smaller values of M
and larger values of L. Less constrained devices do will want to be and larger values of L. Less constrained devices do will want to be
able to user larger messages and are more willing to generate new able to user larger messages and are more willing to generate new
keys for every operation. This favors larger values of M and smaller keys for every operation. This favors larger values of M and smaller
values of L. (The use of a large nonce means that random generation values of L. (The use of a large nonce means that random generation
of both the key and the nonce will decrease the chances of repeating of both the key and the nonce will decrease the chances of repeating
the pair on two different messages.) the pair on two different messages.)
The following values are used for L: The following values are used for L:
16-bits (2) limits messages to 2^16 bytes (64 KiB) in length. This 16 bits (2) limits messages to 2^16 bytes (64 KiB) in length. This
sufficiently long for messages in the constrained world. The sufficiently long for messages in the constrained world. The
nonce length is 13 bytes allowing for 2^(13*8) possible values of nonce length is 13 bytes allowing for 2^(13*8) possible values of
the nonce without repeating. the nonce without repeating.
64-bits (8) limits messages to 2^64 bytes in length. The nonce 64 bits (8) limits messages to 2^64 bytes in length. The nonce
length is 7 bytes allowing for 2^56 possible values of the nonce length is 7 bytes allowing for 2^56 possible values of the nonce
without repeating. without repeating.
The following values are used for M: The following values are used for M:
64-bits (8) produces a 64-bit authentication tag. This implies that 64 bits (8) produces a 64-bit authentication tag. This implies that
there is a 1 in 2^64 chance that a modified message will there is a 1 in 2^64 chance that a modified message will
authenticate. authenticate.
128-bits (16) produces a 128-bit authentication tag. This implies 128 bits (16) produces a 128-bit authentication tag. This implies
that there is a 1 in 2^128 chance that a modified message will that there is a 1 in 2^128 chance that a modified message will
authenticate. authenticate.
+--------------------+-------+----+-----+-----+---------------------+ +--------------------+-------+----+-----+-----+---------------------+
| name | value | L | M | k | description | | name | value | L | M | k | description |
+--------------------+-------+----+-----+-----+---------------------+ +--------------------+-------+----+-----+-----+---------------------+
| AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode | | AES-CCM-16-64-128 | 10 | 16 | 64 | 128 | AES-CCM mode |
| | | | | | 128-bit key, 64-bit | | | | | | | 128-bit key, 64-bit |
| | | | | | tag, 13-byte nonce | | | | | | | tag, 13-byte nonce |
| | | | | | | | | | | | | |
skipping to change at page 36, line 49 skipping to change at page 36, line 49
| AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode | | AES-CCM-64-128-256 | 33 | 64 | 128 | 256 | AES-CCM mode |
| | | | | | 256-bit key, | | | | | | | 256-bit key, |
| | | | | | 128-bit tag, 7-byte | | | | | | | 128-bit tag, 7-byte |
| | | | | | nonce | | | | | | | nonce |
+--------------------+-------+----+-----+-----+---------------------+ +--------------------+-------+----+-----+-----+---------------------+
Table 8: Algorithm Values for AES-CCM Table 8: Algorithm Values for AES-CCM
Keys may be obtained either from a key structure or from a recipient Keys may be obtained either from a key structure or from a recipient
structure. If the key obtained from a key structure, the key type structure. If the key obtained from a key structure, the key type
MUST be 'Symmetric'. Implementations creating and validating MAC MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST
values MUST validate that the key type, key length and algorithm are validate that the key type, key length and algorithm are correct and
correct and appropriate for the entities involved. appropriate for the entities involved.
10.2.1. Security Considerations 10.2.1. Security Considerations
When using AES-CCM the following restrictions MUST be enforced: When using AES-CCM, the following restrictions MUST be enforced:
o The key and nonce pair MUST be unique for every message encrypted. o The key and nonce pair MUST be unique for every message encrypted.
o The total number of times the AES block cipher is used MUST NOT o The total number of times the AES block cipher is used MUST NOT
exceed 2^61 operations. This limitation is the sum of times the exceed 2^61 operations. This limitation is the sum of times the
block cipher is used in computing the MAC value and in performing block cipher is used in computing the MAC value and in performing
stream encryption operations. An explicit check is required only stream encryption operations. An explicit check is required only
in environments where it is expected that it might be exceeded. in environments where it is expected that it might be exceeded.
[RFC3610] additionally calls out one other consideration of note. It [RFC3610] additionally calls out one other consideration of note. It
skipping to change at page 37, line 32 skipping to change at page 37, line 32
increasing the key size used. Using a portion of the nonce for a increasing the key size used. Using a portion of the nonce for a
random value will decrease the number of messages that a single key random value will decrease the number of messages that a single key
can be used for. Increasing the key size may require more resources can be used for. Increasing the key size may require more resources
in the constrained device. See sections 5 and 10 of [RFC3610] for in the constrained device. See sections 5 and 10 of [RFC3610] for
more information. more information.
10.3. ChaCha20 and Poly1305 10.3. ChaCha20 and Poly1305
ChaCha20 and Poly1305 combined together is a new AEAD mode that is ChaCha20 and Poly1305 combined together is a new AEAD mode that is
defined in [RFC7539]. This is a new algorithm defined to be a cipher defined in [RFC7539]. This is a new algorithm defined to be a cipher
which is not AES and thus would not suffer from any future weaknesses that is not AES and thus would not suffer from any future weaknesses
found in AES. These cryptographic functions are designed to be fast found in AES. These cryptographic functions are designed to be fast
in software only implementations. in software-only implementations.
The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no The ChaCha20/Poly1305 AEAD construction defined in [RFC7539] has no
parameterization. It takes a 256-bit key and a 96-bit nonce as well parameterization. It takes a 256-bit key and a 96-bit nonce as well
as the plain text and additional data as inputs and produces the as the plain text and additional data as inputs and produces the
cipher text as an option. We define one algorithm identifier for cipher text as an option. We define one algorithm identifier for
this algorithm in Table 9. this algorithm in Table 9.
+-------------------+-------+----------------------------------+ +-------------------+-------+----------------------------------+
| name | value | description | | name | value | description |
+-------------------+-------+----------------------------------+ +-------------------+-------+----------------------------------+
| ChaCha20/Poly1305 | 11 | ChaCha20/Poly1305 w/ 256-bit key | | ChaCha20/Poly1305 | 11 | ChaCha20/Poly1305 w/ 256-bit key |
+-------------------+-------+----------------------------------+ +-------------------+-------+----------------------------------+
Table 9: Algorithm Value for AES-GCM Table 9: Algorithm Value for AES-GCM
Keys may be obtained either from a key structure or from a recipient Keys may be obtained either from a key structure or from a recipient
structure. If the key obtained from a key structure, the key type structure. If the key obtained from a key structure, the key type
MUST be 'Symmetric'. Implementations creating and validating MAC MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST
values MUST validate that the key type, key length and algorithm are validate that the key type, key length and algorithm are correct and
correct and appropriate for the entities involved. appropriate for the entities involved.
10.3.1. Security Considerations 10.3.1. Security Considerations
The pair of key, nonce MUST be unique for every invocation of the The pair of key, nonce MUST be unique for every invocation of the
algorithm. Nonce counters are considered to be an acceptable way of algorithm. Nonce counters are considered to be an acceptable way of
ensuring that they are unique. ensuring that they are unique.
11. Key Derivation Functions (KDF) 11. Key Derivation Functions (KDF)
Key Derivation Functions (KDFs) are used to take some secret value Key Derivation Functions (KDFs) are used to take some secret value
and generate a different one. The original secret values come in and generate a different one. The original secret values come in
three basic flavors: three basic flavors:
o Secrets which are uniformly random: This is the type of secret o Secrets that are uniformly random: This is the type of secret
which is created by a good random number generator. which is created by a good random number generator.
o Secrets which are not uniformly random: This is type of secret o Secrets that are not uniformly random: This is type of secret
which is created by operations like key agreement. which is created by operations like key agreement.
o Secrets which are not random: This is the type of secret that o Secrets that are not random: This is the type of secret that
people generate for things like passwords. people generate for things like passwords.
General KDF functions work well with the first type of secret, can do General KDF functions work well with the first type of secret, can do
reasonable well with the second type of secret and generally do reasonable well with the second type of secret and generally do
poorly with the last type of secret. None of the KDF functions in poorly with the last type of secret. None of the KDF functions in
this section are designed to deal with the type of secrets that are this section are designed to deal with the type of secrets that are
used for passwords. Functions like PBSE2 [RFC2898] need to be used used for passwords. Functions like PBSE2 [RFC2898] need to be used
for that type of secret. for that type of secret.
Many functions are going to handle the first two type of secrets Many functions are going to handle the first two type of secrets
skipping to change at page 39, line 9 skipping to change at page 39, line 9
context information. Context information is used to allow for context information. Context information is used to allow for
different keying information to be derived from the same secret. The different keying information to be derived from the same secret. The
use of context based keying material is considered to be a good use of context based keying material is considered to be a good
security practice. This document defines a single context structure security practice. This document defines a single context structure
and a single KDF function. and a single KDF function.
11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 11.1. HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
The HKDF key derivation algorithm is defined in [RFC5869]. The HKDF key derivation algorithm is defined in [RFC5869].
The HKDF algorithm is defined to take a number of inputs. These The HKDF algorithm takes these inputs:
inputs are:
secret - a shared value that is secret. Secrets may be either secret - a shared value that is secret. Secrets may be either
previously shared or derived from operations like a DH key previously shared or derived from operations like a DH key
agreement. agreement.
salt - an optional public value that is used to change the salt - an optional public value that is used to change the
generation process. If specified, the salt is carried using the generation process. If specified, the salt is carried using the
'salt' algorithm parameter. While [RFC5869] suggests that the 'salt' algorithm parameter. While [RFC5869] suggests that the
length of the salt be the same as the length of the underlying length of the salt be the same as the length of the underlying
hash value, any amount of salt will improve the security as hash value, any amount of salt will improve the security as
skipping to change at page 39, line 48 skipping to change at page 39, line 47
HKDF is defined to use HMAC as the underlying PRF. However, it is HKDF is defined to use HMAC as the underlying PRF. However, it is
possible to use other functions in the same construct to provide a possible to use other functions in the same construct to provide a
different KDF function that may be more appropriate in the different KDF function that may be more appropriate in the
constrained world. Specifically, one can use AES-CBC-MAC as the PRF constrained world. Specifically, one can use AES-CBC-MAC as the PRF
for the expand step, but not for the extract step. When using a good for the expand step, but not for the extract step. When using a good
random shared secret of the correct length, the extract step can be random shared secret of the correct length, the extract step can be
skipped. The extract cannot be skipped if the secret is not skipped. The extract cannot be skipped if the secret is not
uniformly random, for example if it is the result of an ECDH key uniformly random, for example if it is the result of an ECDH key
agreement step. agreement step.
The algorithms defined in this document are found in Table 10 The algorithms defined in this document are found in Table 10.
+-------------+-------------+----------+----------------------------+ +-------------+-------------+----------+----------------------------+
| name | hash | Skip | context | | name | hash | Skip | context |
| | | extract | | | | | extract | |
+-------------+-------------+----------+----------------------------+ +-------------+-------------+----------+----------------------------+
| HKDF | SHA-256 | no | XXX | | HKDF | SHA-256 | no | XXX |
| SHA-256 | | | | | SHA-256 | | | |
| | | | | | | | | |
| HKDF | SHA-512 | no | XXX | | HKDF | SHA-512 | no | XXX |
| SHA-512 | | | | | SHA-512 | | | |
| | | | | | | | | |
skipping to change at page 40, line 40 skipping to change at page 40, line 41
11.2. Context Information Structure 11.2. Context Information Structure
The context information structure is used to ensure that the derived The context information structure is used to ensure that the derived
keying material is "bound" to the context of the transaction. The keying material is "bound" to the context of the transaction. The
context information structure used here is based on that defined in context information structure used here is based on that defined in
[SP800-56A]. By using CBOR for the encoding of the context [SP800-56A]. By using CBOR for the encoding of the context
information structure, we automatically get the same type of type and information structure, we automatically get the same type of type and
length separation of fields that is obtained by the use of ASN.1. length separation of fields that is obtained by the use of ASN.1.
This means that there is no need to encode the lengths for the base This means that there is no need to encode the lengths for the base
elements as it is done by the JOSE encoding. [CREF7] elements as it is done by the JOSE encoding. [CREF8]
The context information structure refers to PartyU and PartyV as the The context information structure refers to PartyU and PartyV as the
two parties which are doing the key derivation. Unless the two parties which are doing the key derivation. Unless the
application protocol defines differently, we assign PartyU to the application protocol defines differently, we assign PartyU to the
entity that is creating the message and PartyV to the entity that is entity that is creating the message and PartyV to the entity that is
receiving the message. By doing this association, different keys receiving the message. By doing this association, different keys
will be derived for each direction as the context information is will be derived for each direction as the context information is
different in each direction. different in each direction.
Application protocols are free to define the roles differently. For Application protocols are free to define the roles differently. For
skipping to change at page 44, line 31 skipping to change at page 44, line 31
? SuppPrivInfo : bstr ? SuppPrivInfo : bstr
] ]
12. Recipient Algorithm Classes 12. Recipient Algorithm Classes
Recipient algorithms can be defined into a number of different Recipient algorithms can be defined into a number of different
classes. COSE has the ability to support many classes of recipient classes. COSE has the ability to support many classes of recipient
algorithms. In this section, a number of classes are listed and then algorithms. In this section, a number of classes are listed and then
a set of algorithms are specified for each of the classes. The names a set of algorithms are specified for each of the classes. The names
of the recipient algorithm classes used here are the same as are of the recipient algorithm classes used here are the same as are
defined in [RFC7517]. Other specifications use different terms for defined in [RFC7516]. Other specifications use different terms for
the recipient algorithm classes or do not support some of our the recipient algorithm classes or do not support some of our
recipient algorithm classes. recipient algorithm classes.
12.1. Direct Encryption 12.1. Direct Encryption
The direct encryption class algorithms share a secret between the The direct encryption class algorithms share a secret between the
sender and the recipient that is used either directly or after sender and the recipient that is used either directly or after
manipulation as the content key. When direct encryption mode is manipulation as the content key. When direct encryption mode is
used, it MUST be the only mode used on the message. used, it MUST be the only mode used on the message.
skipping to change at page 46, line 4 skipping to change at page 46, line 4
then the key for all messages is also determined. then the key for all messages is also determined.
12.1.2. Direct Key with KDF 12.1.2. Direct Key with KDF
These recipient algorithms take a common shared secret between the These recipient algorithms take a common shared secret between the
two parties and applies the HKDF function (Section 11.1) using the two parties and applies the HKDF function (Section 11.1) using the
context structure defined in Section 11.2 to transform the shared context structure defined in Section 11.2 to transform the shared
secret into the necessary key. Either the 'salt' parameter of HKDF secret into the necessary key. Either the 'salt' parameter of HKDF
or the partyU 'nonce' parameter of the context structure MUST be or the partyU 'nonce' parameter of the context structure MUST be
present. This parameter can be generated either randomly or present. This parameter can be generated either randomly or
deterministically, the requirement is that it be a unique value for deterministically. The requirement is that it be a unique value for
the key pair in question. the key pair in question.
If the salt/nonce value is generated randomly, then it is suggested If the salt/nonce value is generated randomly, then it is suggested
that the length of the random value be the same length as the hash that the length of the random value be the same length as the hash
function underlying HKDF. While there is no way to guarantee that it function underlying HKDF. While there is no way to guarantee that it
will be unique, there is a high probability that it will be unique. will be unique, there is a high probability that it will be unique.
If the salt/nonce value is generated deterministically, it can be If the salt/nonce value is generated deterministically, it can be
guaranteed to be unique and thus there is no length requirement. guaranteed to be unique and thus there is no length requirement.
A new IV must be used if the same key is used in more than one A new IV must be used if the same key is used in more than one
skipping to change at page 46, line 46 skipping to change at page 46, line 46
| | | MAC-128 | MAC 128-bit key | | | | MAC-128 | MAC 128-bit key |
| | | | | | | | | |
| direct+HKDF-AES-256 | * | HKDF AES- | Shared secret w/ AES- | | direct+HKDF-AES-256 | * | HKDF AES- | Shared secret w/ AES- |
| | | MAC-256 | MAC 256-bit key | | | | MAC-256 | MAC 256-bit key |
+---------------------+-------+-------------+-----------------------+ +---------------------+-------+-------------+-----------------------+
Table 14: Direct Key Table 14: Direct Key
12.1.2.1. Security Considerations 12.1.2.1. Security Considerations
The shared secret need to have some method to be regularly updated The shared secret needs to have some method to be regularly updated
over time. The shared secret is forming the basis of trust, although over time. The shared secret forms the basis of trust. Although not
not used directly it should still be subject to scheduled rotation. used directly, it should still be subject to scheduled rotation.
12.2. Key Wrapping 12.2. Key Wrapping
In key wrapping mode, the CEK is randomly generated and that key is In key wrapping mode, the CEK is randomly generated and that key is
then encrypted by a shared secret between the sender and the then encrypted by a shared secret between the sender and the
recipient. All of the currently defined key wrapping algorithms for recipient. All of the currently defined key wrapping algorithms for
JOSE (and thus for COSE) are AE algorithms. Key wrapping mode is JOSE (and thus for COSE) are AE algorithms. Key wrapping mode is
considered to be superior to direct encryption if the system has any considered to be superior to direct encryption if the system has any
capability for doing random key generation. This is because the capability for doing random key generation. This is because the
shared key is used to wrap random data rather than data has some shared key is used to wrap random data rather than data has some
skipping to change at page 47, line 37 skipping to change at page 47, line 37
o The plain text to be encrypted is the key from next layer down o The plain text to be encrypted is the key from next layer down
(usually the content layer). (usually the content layer).
o At a minimum, the 'unprotected' field MUST contain the 'alg' o At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the shared parameter and SHOULD contain a parameter identifying the shared
secret. secret.
12.2.1. AES Key Wrapping 12.2.1. AES Key Wrapping
The AES Key Wrapping algorithm is defined in [RFC3394]. This The AES Key Wrapping algorithm is defined in [RFC3394]. This
algorithm uses an AES key to wrap a value that is a multiple of algorithm uses an AES key to wrap a value that is a multiple of 64
64-bits, as such it can be used to wrap a key for any of the content bits. As such, it can be used to wrap a key for any of the content
encryption algorithms defined in this document. The algorithm encryption algorithms defined in this document. The algorithm
requires a single fixed parameter, the initial value. This is fixed requires a single fixed parameter, the initial value. This is fixed
to the value specified in Section 2.2.3.1 of [RFC3394]. There are no to the value specified in Section 2.2.3.1 of [RFC3394]. There are no
public parameters that vary on a per invocation basis. public parameters that vary on a per invocation basis.
Keys may be obtained either from a key structure or from a recipient Keys may be obtained either from a key structure or from a recipient
structure. If the key obtained from a key structure, the key type structure. If the key obtained from a key structure, the key type
MUST be 'Symmetric'. Implementations creating and validating MAC MUST be 'Symmetric'. Implementations encrypting and decrrypting MUST
values MUST validate that the key type, key length and algorithm are validate that the key type, key length and algorithm are correct and
correct and appropriate for the entities involved. appropriate for the entities involved.
+--------+-------+----------+-----------------------------+ +--------+-------+----------+-----------------------------+
| name | value | key size | description | | name | value | key size | description |
+--------+-------+----------+-----------------------------+ +--------+-------+----------+-----------------------------+
| A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key | | A128KW | -3 | 128 | AES Key Wrap w/ 128-bit key |
| | | | | | | | | |
| A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key | | A192KW | -4 | 192 | AES Key Wrap w/ 192-bit key |
| | | | | | | | | |
| A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key | | A256KW | -5 | 256 | AES Key Wrap w/ 256-bit key |
+--------+-------+----------+-----------------------------+ +--------+-------+----------+-----------------------------+
skipping to change at page 49, line 7 skipping to change at page 49, line 7
agreement method to create a shared secret. A KDF is then applied to agreement method to create a shared secret. A KDF is then applied to
the shared secret to derive a key to be used in protecting the data. the shared secret to derive a key to be used in protecting the data.
This key is normally used as a CEK or MAC key, but could be used for This key is normally used as a CEK or MAC key, but could be used for
other purposes if more than two layers are in use (see Appendix B). other purposes if more than two layers are in use (see Appendix B).
The most commonly used key agreement algorithm used is Diffie- The most commonly used key agreement algorithm used is Diffie-
Hellman, but other variants exist. Since COSE is designed for a Hellman, but other variants exist. Since COSE is designed for a
store and forward environment rather than an on-line environment, store and forward environment rather than an on-line environment,
many of the DH variants cannot be used as the receiver of the message many of the DH variants cannot be used as the receiver of the message
cannot provide any key material. One side-effect of this is that cannot provide any key material. One side-effect of this is that
perfect forward security is not achievable, a static key will always perfect forward security is not achievable. A static key will always
be used for the receiver of the COSE message. be used for the receiver of the COSE message.
Two variants of DH that are easily supported are: Two variants of DH that are easily supported are:
- Ephemeral-Static DH: where the sender of the message creates a - Ephemeral-Static DH: where the sender of the message creates a
one time DH key and uses a static key for the recipient. The use one time DH key and uses a static key for the recipient. The use
of the ephemeral sender key means that no additional random input of the ephemeral sender key means that no additional random input
is needed as this is randomly generated for each message. is needed as this is randomly generated for each message.
Static-Static DH: where a static key is used for both the sender Static-Static DH: where a static key is used for both the sender
and the recipient. The use of static keys allows for recipient to and the recipient. The use of static keys allows for recipient to
get a weak version of data origination for the message. When get a weak version of data origination for the message. When
static-static key agreement is used, then some piece of unique static-static key agreement is used, then some piece of unique
data is require to ensure that a different key is created for each data is required to ensure that a different key is created for
message each message.
In this specification, both variants are specified. This has been In this specification, both variants are specified. This has been
done to provide the weak data origination option for use with MAC done to provide the weak data origination option for use with MAC
operations. operations.
When direct key agreement mode is used, there MUST be only one When direct key agreement mode is used, there MUST be only one
recipient in the message. This method creates the key directly and recipient in the message. This method creates the key directly and
that makes it difficult to mix with additional recipients. If that makes it difficult to mix with additional recipients. If
multiple recipients are needed, then the version with key wrap needs multiple recipients are needed, then the version with key wrap needs
to be used. to be used.
skipping to change at page 50, line 9 skipping to change at page 50, line 9
The basic mathematics for Elliptic Curve Diffie-Hellman can be found The basic mathematics for Elliptic Curve Diffie-Hellman can be found
in [RFC6090]. in [RFC6090].
ECDH is parameterized by the following: ECDH is parameterized by the following:
o Curve Type/Curve: The curve selected controls not only the size of o Curve Type/Curve: The curve selected controls not only the size of
the shared secret, but the mathematics for computing the shared the shared secret, but the mathematics for computing the shared
secret. The curve selected also controls how a point in the curve secret. The curve selected also controls how a point in the curve
is represented and what happens for the identity points on the is represented and what happens for the identity points on the
curve. In this specification we allow for a number of different curve. In this specification, we allow for a number of different
curves to be used. The curves are defined in Table 19. curves to be used. The curves are defined in Table 19.
Since the only the math is changed by changing the curve, the Since the only the math is changed by changing the curve, the
curve is not fixed for any of the algorithm identifiers we define, curve is not fixed for any of the algorithm identifiers we define.
instead it is defined by the points used. Instead, it is defined by the points used.
o Ephemeral-static or static-static: The key agreement process may o Ephemeral-static or static-static: The key agreement process may
be done using either a static or an ephemeral key at the sender's be done using either a static or an ephemeral key at the sender's
side. When using ephemeral keys, the sender MUST generate a new side. When using ephemeral keys, the sender MUST generate a new
ephemeral key for every key agreement operation. The ephemeral ephemeral key for every key agreement operation. The ephemeral
key is placed in the 'ephemeral key' parameter and MUST be present key is placed in the 'ephemeral key' parameter and MUST be present
for all algorithm identifiers which use ephemeral keys. When for all algorithm identifiers that use ephemeral keys. When using
using static keys, the sender MUST either generate a new random static keys, the sender MUST either generate a new random value
value placed in either in the KDF parameters or the context placed in either in the KDF parameters or the context structure.
structure. For the KDF functions used, this means either in the For the KDF functions used, this means either in the 'salt'
'salt' parameter for HKDF (Table 11) or in the 'PartyU nonce' parameter for HKDF (Table 11) or in the 'PartyU nonce' parameter
parameter for the context structure (Table 12) MUST be present. for the context structure (Table 12) MUST be present. (Both may
(Both may be present if desired.) The value in the parameter MUST be present if desired.) The value in the parameter MUST be unique
be unique for the key pair being used. It is acceptable to use a for the key pair being used. It is acceptable to use a global
global counter which is incremented for every static-static counter that is incremented for every static-static operation and
operation and use the resulting value. When using static keys, use the resulting value. When using static keys, the static key
the static key needs to be identified to the recipient. The needs to be identified to the recipient. The static key can be
static key can be identified either by providing the key ('static identified either by providing the key ('static key') or by
key') or by providing a key identifier for the static key ('static providing a key identifier for the static key ('static key id').
key id'). Both of these parameters are defined in Table 17 Both of these parameters are defined in Table 17
o Key derivation algorithm: The result of an ECDH key agreement o Key derivation algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret, as such it process does not provide a uniformly random secret. As such, it
needs to be run through a KDF in order to produce a usable key. needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the Processing the secret through a KDF also allows for the
introduction of both context material, how the key is going to be introduction of both context material, how the key is going to be
used, and one time material in the even to of a static-static key used, and one time material in the even to of a static-static key
agreement. agreement.
o Key Wrap algorithm: The key wrap algorithm can be 'none' if the o Key Wrap algorithm: The key wrap algorithm can be 'none' if the
result of the KDF is going to be used as the key directly. This result of the KDF is going to be used as the key directly. This
option, along with static-static, should be used if knowledge option, along with static-static, should be used if knowledge
about the sender is desired. If 'none' is used then the content about the sender is desired. If 'none' is used, then the content
layer encryption algorithm size is value fed to the context layer encryption algorithm size is value fed to the context
structure. Support is also provided for any of the key wrap structure. Support is also provided for any of the key wrap
algorithms defined in Section 12.2.1. If one of these options is algorithms defined in Section 12.2.1. If one of these options is
used, the input key size to the key wrap algorithm is the value used, the input key size to the key wrap algorithm is the value
fed into the context structure as the key size. fed into the context structure as the key size.
The set of algorithms direct ECDH defined in this document are found The set of direct ECDH algorithms defined in this document are found
in Table 16. in Table 16.
+-------------+------+-------+----------------+--------+------------+ +-------------+------+-------+----------------+--------+------------+
| name | valu | KDF | Ephemeral- | Key | descriptio | | name | valu | KDF | Ephemeral- | Key | descriptio |
| | e | | Static | Wrap | n | | | e | | Static | Wrap | n |
+-------------+------+-------+----------------+--------+------------+ +-------------+------+-------+----------------+--------+------------+
| ECDH-ES + | 50 | HKDF | yes | none | ECDH ES w/ | | ECDH-ES + | 50 | HKDF | yes | none | ECDH ES w/ |
| HKDF-256 | | - SHA | | | HKDF - | | HKDF-256 | | - SHA | | | HKDF - |
| | | -256 | | | generate | | | | -256 | | | generate |
| | | | | | key | | | | | | | key |
skipping to change at page 52, line 50 skipping to change at page 52, line 50
| | | | | | | | | | | |
| static | -3 | bstr | ECDH-SS | Static Public key | | static | -3 | bstr | ECDH-SS | Static Public key |
| key id | | | | identifier for the | | key id | | | | identifier for the |
| | | | | sender | | | | | | sender |
+-----------+-------+----------+-----------+------------------------+ +-----------+-------+----------+-----------+------------------------+
Table 17: ECDH Algorithm Parameters Table 17: ECDH Algorithm Parameters
This document defines these algorithms to be used with the curves This document defines these algorithms to be used with the curves
P-256, P-384, P-521. Implementations MUST verify that the key type P-256, P-384, P-521. Implementations MUST verify that the key type
and curve are correct, different curves are restricted to different and curve are correct. Different curves are restricted to different
key types. Implementations MUST verify that the curve and algorithm key types. Implementations MUST verify that the curve and algorithm
are appropriate for the entities involved. are appropriate for the entities involved.
12.5. Key Agreement with KDF 12.5. Key Agreement with KDF
Key Agreement with Key Wrapping uses a randomly generated CEK. The Key Agreement with Key Wrapping uses a randomly generated CEK. The
CEK is then encrypted using a Key Wrapping algorithm and a key CEK is then encrypted using a Key Wrapping algorithm and a key
derived from the shared secret computed by the key agreement derived from the shared secret computed by the key agreement
algorithm. algorithm.
skipping to change at page 53, line 32 skipping to change at page 53, line 32
o A parameter identifying the recipient's key SHOULD be present. A o A parameter identifying the recipient's key SHOULD be present. A
parameter identifying the sender's key SHOULD be present. parameter identifying the sender's key SHOULD be present.
12.5.1. ECDH 12.5.1. ECDH
These algorithms are defined in Table 16. These algorithms are defined in Table 16.
13. Keys 13. Keys
The COSE_Key object defines a way to hold a single key object, it is The COSE_Key object defines a way to hold a single key object. It is
still required that the members of individual key types be defined. still required that the members of individual key types be defined.
This section of the document is where we define an initial set of This section of the document is where we define an initial set of
members for specific key types. members for specific key types.
For each of the key types, we define both public and private members. For each of the key types, we define both public and private members.
The public members are what is transmitted to others for their usage. The public members are what is transmitted to others for their usage.
We define private members mainly for the purpose of archival of keys We define private members mainly for the purpose of archival of keys
by individuals. However, there are some circumstances where private by individuals. However, there are some circumstances in which
keys may be distributed by various entities in a protocol. Examples private keys may be distributed by various entities in a protocol.
include: Entities which have poor random number generation. Examples include: entities that have poor random number generation,
Centralized key creation for multi-cast type operations. Protocols centralized key creation for multi-cast type operations, and
where a shared secret is used as a bearer token for authorization protocols in which a shared secret is used as a bearer token for
purposes. authorization purposes.
Key types are identified by the 'kty' member of the COSE_Key object. Key types are identified by the 'kty' member of the COSE_Key object.
In this document we define four values for the member. In this document, we define four values for the member:
+-----------+-------+--------------------------------------------+ +-----------+-------+--------------------------------------------+
| name | value | description | | name | value | description |
+-----------+-------+--------------------------------------------+ +-----------+-------+--------------------------------------------+
| EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair | | EC2 | 2 | Elliptic Curve Keys w/ X,Y Coordinate pair |
| | | | | | | |
| Symmetric | 4 | Symmetric Keys | | Symmetric | 4 | Symmetric Keys |
| | | | | | | |
| Reserved | 0 | This value is reserved | | Reserved | 0 | This value is reserved |
+-----------+-------+--------------------------------------------+ +-----------+-------+--------------------------------------------+
Table 18: Key Type Values Table 18: Key Type Values
13.1. Elliptic Curve Keys 13.1. Elliptic Curve Keys
Two different key structures could be defined for Elliptic Curve Two different key structures could be defined for Elliptic Curve
keys. One version uses both an x and a y coordinate, potentially keys. One version uses both an x and a y coordinate, potentially
with point compression. This is the traditional EC point with point compression. This is the traditional EC point
representation that is used in [RFC5480]. The other version uses representation that is used in [RFC5480]. The other version uses
only the x coordinate as the y coordinate is either to be recomputed only the x coordinate as the y coordinate is either to be recomputed
or not needed for the key agreement operation Currently no algorithms or not needed for the key agreement operation. Currently no
are defined using this key structure. algorithms are defined using this key structure.
+-------+----------+-------+------------------------------------+ +-------+----------+-------+------------------------------------+
| name | key type | value | description | | name | key type | value | description |
+-------+----------+-------+------------------------------------+ +-------+----------+-------+------------------------------------+
| P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 | | P-256 | EC2 | 1 | NIST P-256 also known as secp256r1 |
| | | | | | | | | |
| P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 | | P-384 | EC2 | 2 | NIST P-384 also known as secp384r1 |
| | | | | | | | | |
| P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 | | P-521 | EC2 | 3 | NIST P-521 also known as secp521r1 |
+-------+----------+-------+------------------------------------+ +-------+----------+-------+------------------------------------+
skipping to change at page 55, line 15 skipping to change at page 55, line 15
crv contains an identifier of the curve to be used with the key. crv contains an identifier of the curve to be used with the key.
The curves defined in this document for this key type can be found The curves defined in this document for this key type can be found
in Table 19. Other curves may be registered in the future and in Table 19. Other curves may be registered in the future and
private curves can be used as well. private curves can be used as well.
x contains the x coordinate for the EC point. The integer is x contains the x coordinate for the EC point. The integer is
converted to an octet string as defined in [SEC1]. Zero octets converted to an octet string as defined in [SEC1]. Zero octets
MUST NOT be removed from the front of the octet string. MUST NOT be removed from the front of the octet string.
y contains either the sign bit or the value of y coordinate for the y contains either the sign bit or the value of y coordinate for the
EC point. For the value, the integer is converted to an octet EC point. When encoding the value y, the integer is converted to
string as defined in [SEC1]. Zero octets MUST NOT be removed from an octet string (as defined in [SEC1]) and encoded as a CBOR bstr.
the front of the octet string. For the sign bit, the value is Leading zero octets MUST be preserved. When encoding the sign of
true if the value of y is positive. y, the expression 'y > 0' is evaluated and encoded a CBOR boolean.
d contains the private key. d contains the private key.
For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in For public keys, it is REQUIRED that 'crv', 'x' and 'y' be present in
the structure. For private keys, it is REQUIRED that 'crv' and 'd' the structure. For private keys, it is REQUIRED that 'crv' and 'd'
be present in the structure. For private keys, it is RECOMMENDED be present in the structure. For private keys, it is RECOMMENDED
that 'x' and 'y' also be present, but they can be recomputed from the that 'x' and 'y' also be present, but they can be recomputed from the
required elements and omitting them saves on space. required elements and omitting them saves on space.
+------+-------+-------+---------+----------------------------------+ +------+-------+-------+---------+----------------------------------+
skipping to change at page 57, line 23 skipping to change at page 57, line 23
| | | | | | | |
| TBD4 | COSE_Mac | COSE Mac-ed Data Object | | TBD4 | COSE_Mac | COSE Mac-ed Data Object |
| | | | | | | |
| TBD5 | COSE_Key, COSE_KeySet | COSE Key or COSE Key Set | | TBD5 | COSE_Key, COSE_KeySet | COSE Key or COSE Key Set |
| | | Object | | | | Object |
+-----------+-----------------------+-------------------------------+ +-----------+-----------------------+-------------------------------+
15.2. COSE Header Parameter Registry 15.2. COSE Header Parameter Registry
It is requested that IANA create a new registry entitled "COSE Header It is requested that IANA create a new registry entitled "COSE Header
Parameters". Parameters". The registery is to be created as Expert Review
Required.
The columns of the registry are: The columns of the registry are:
name The name is present to make it easier to refer to and discuss name The name is present to make it easier to refer to and discuss
the registration entry. The value is not used in the protocol. the registration entry. The value is not used in the protocol.
Names are to be unique in the table. Names are to be unique in the table.
label This is the value used for the label. The label can be either label This is the value used for the label. The label can be either
an integer or a string. Registration in the table is based on the an integer or a string. Registration in the table is based on the
value of the label requested. Integer values between 1 and 255 value of the label requested. Integer values between 1 and 255
and strings of length 1 are designated as Standards Track Document and strings of length 1 are designated as Standards Track Document
required. Integer values from 256 to 65535 and strings of length required. Integer values from 256 to 65535 and strings of length
2 are designated as Specification Required. Integer values of 2 are designated as Specification Required. Integer values of
greater than 65535 and strings of length greater than 2 are greater than 65535 and strings of length greater than 2 are
designated as first come first server. Integer values in the designated as first come, first served. Integer values in the
range -1 to -65536 are delegated to the "COSE Header Algorithm range -1 to -65536 are delegated to the "COSE Header Algorithm
Label" registry. Integer values beyond -65536 are marked as Label" registry. Integer values beyond -65536 are marked as
private use. private use.
value This contains the CBOR type for the value portion of the value This contains the CBOR type for the value portion of the
label. label.
value registry This contains a pointer to the registry used to value registry This contains a pointer to the registry used to
contain values where the set is limited. contain values where the set is limited.
skipping to change at page 58, line 14 skipping to change at page 58, line 17
The initial contents of the registry can be found in Table 1. The The initial contents of the registry can be found in Table 1. The
specification column for all rows in that table should be this specification column for all rows in that table should be this
document. document.
Additionally, the label of 0 is to be marked as 'Reserved'. Additionally, the label of 0 is to be marked as 'Reserved'.
15.3. COSE Header Algorithm Label Table 15.3. COSE Header Algorithm Label Table
It is requested that IANA create a new registry entitled "COSE Header It is requested that IANA create a new registry entitled "COSE Header
Algorithm Labels". Algorithm Labels". The registery is to be created as Expert Review
Required.
The columns of the registry are: The columns of the registry are:
name The name is present to make it easier to refer to and discuss name The name is present to make it easier to refer to and discuss
the registration entry. The value is not used in the protocol. the registration entry. The value is not used in the protocol.
algorithm The algorithm(s) that this registry entry is used for. algorithm The algorithm(s) that this registry entry is used for.
This value is taken from the "COSE Algorithm Value" registry. This value is taken from the "COSE Algorithm Value" registry.
Multiple algorithms can be specified in this entry. For the Multiple algorithms can be specified in this entry. For the
table, the algorithm, label pair MUST be unique. table, the algorithm, label pair MUST be unique.
skipping to change at page 58, line 40 skipping to change at page 58, line 44
label. label.
value registry This contains a pointer to the registry used to value registry This contains a pointer to the registry used to
contain values where the set is limited. contain values where the set is limited.
description This contains a brief description of the header field. description This contains a brief description of the header field.
specification This contains a pointer to the specification defining specification This contains a pointer to the specification defining
the header field (where public). the header field (where public).
The initial contents of the registry can be found in: Table 11, The initial contents of the registry can be found in Table 11,
Table 12, Table 17. The specification column for all rows in that Table 12, and Table 17. The specification column for all rows in
table should be this document. that table should be this document.
15.4. COSE Algorithm Registry 15.4. COSE Algorithm Registry
It is requested that IANA create a new registry entitled "COSE It is requested that IANA create a new registry entitled "COSE
Algorithm Registry". Algorithm Registry". The registery is to be created as Expert Review
Required.
The columns of the registry are: The columns of the registry are:
value The value to be used to identify this algorithm. Algorithm value The value to be used to identify this algorithm. Algorithm
values MUST be unique. The value can be a positive integer, a values MUST be unique. The value can be a positive integer, a
negative integer or a string. Integer values between 0 and 255 negative integer or a string. Integer values between 0 and 255
and strings of length 1 are designated as Standards Track Document and strings of length 1 are designated as Standards Track Document
required. Integer values from 256 to 65535 and strings of length required. Integer values from 256 to 65535 and strings of length
2 are designated as Specification Required. Integer values of 2 are designated as Specification Required. Integer values of
greater than 65535 and strings of length greater than 2 are greater than 65535 and strings of length greater than 2 are
designated as first come first server. Integer values in the designated as first come, first served. Integer values in the
range -1 to -65536 are delegated to the "COSE Header Algorithm range -1 to -65536 are delegated to the "COSE Header Algorithm
Label" registry. Integer values beyond -65536 are marked as Label" registry. Integer values beyond -65536 are marked as
private use. private use.
description A short description of the algorithm. description A short description of the algorithm.
specification A document where the algorithm is defined (if publicly specification A document where the algorithm is defined (if publicly
available). available).
The initial contents of the registry can be found in the following: The initial contents of the registry can be found in Table 8,
Table 8, Table 7, Table 9, Table 4, Table 5, Table 6, Table 13, Table 7, Table 9, Table 4, Table 5, Table 6, Table 13, Table 14,
Table 14, Table 15, Table 16. The specification column for all rows Table 15, and Table 16. The specification column for all rows in
in that table should be this document. that table should be this document.
15.5. COSE Key Common Parameter Registry 15.5. COSE Key Common Parameter Registry
It is requested that IANA create a new registry entitled "COSE Key It is requested that IANA create a new registry entitled "COSE Key
Common Parameter" Registry. Common Parameter" Registry. The registery is to be created as Expert
Review Required.
The columns of the registry are: The columns of the registry are:
name This is a descriptive name that enables easier reference to the name This is a descriptive name that enables easier reference to the
item. It is not used in the encoding. item. It is not used in the encoding.
label The value to be used to identify this algorithm. Key map label The value to be used to identify this algorithm. Key map
labels MUST be unique. The label can be a positive integer, a labels MUST be unique. The label can be a positive integer, a
negative integer or a string. Integer values between 0 and 255 negative integer or a string. Integer values between 0 and 255
and strings of length 1 are designated as Standards Track Document and strings of length 1 are designated as Standards Track Document
required. Integer values from 256 to 65535 and strings of length required. Integer values from 256 to 65535 and strings of length
2 are designated as Specification Required. Integer values of 2 are designated as Specification Required. Integer values of
greater than 65535 and strings of length greater than 2 are greater than 65535 and strings of length greater than 2 are
designated as first come first server. Integer values in the designated as first come, first served. Integer values in the
range -1 to -65536 are used for key parameters specific to a range -1 to -65536 are used for key parameters specific to a
single algorithm delegated to the "COSE Key Parameter Label" single algorithm delegated to the "COSE Key Parameter Label"
registry. Integer values beyond -65536 are marked as private use. registry. Integer values beyond -65536 are marked as private use.
CBOR Type This field contains the CBOR type for the field CBOR Type This field contains the CBOR type for the field
registry This field denotes the registry that values come from, if registry This field denotes the registry that values come from, if
one exists. one exists.
description This field contains a brief description for the field description This field contains a brief description for the field
specification This contains a pointer to the public specification specification This contains a pointer to the public specification
for the field if one exists for the field if one exists
This registry will be initially populated by the values in This registry will be initially populated by the values in
Section 7.1. The specification column for all of these entries will Section 7.1. The specification column for all of these entries will
be this document. be this document.
15.6. COSE Key Type Parameter Registry 15.6. COSE Key Type Parameter Registry
It is requested that IANA create a new registry "COSE Key Type It is requested that IANA create a new registry "COSE Key Type
skipping to change at page 60, line 14 skipping to change at page 60, line 19
specification This contains a pointer to the public specification specification This contains a pointer to the public specification
for the field if one exists for the field if one exists
This registry will be initially populated by the values in This registry will be initially populated by the values in
Section 7.1. The specification column for all of these entries will Section 7.1. The specification column for all of these entries will
be this document. be this document.
15.6. COSE Key Type Parameter Registry 15.6. COSE Key Type Parameter Registry
It is requested that IANA create a new registry "COSE Key Type It is requested that IANA create a new registry "COSE Key Type
Parameters". Parameters". The registery is to be created as Expert Review
Required.
The columns of the table are: The columns of the table are:
key type This field contains a descriptive string of a key type. key type This field contains a descriptive string of a key type.
This should be a value that is in the COSE General Values table This should be a value that is in the COSE General Values table
and is placed in the 'kty' field of a COSE Key structure. and is placed in the 'kty' field of a COSE Key structure.
name This is a descriptive name that enables easier reference to the name This is a descriptive name that enables easier reference to the
item. It is not used in the encoding. item. It is not used in the encoding.
skipping to change at page 60, line 36 skipping to change at page 60, line 42
range of values is from -256 to -1. Labels are expected to be range of values is from -256 to -1. Labels are expected to be
reused for different keys. reused for different keys.
CBOR type This field contains the CBOR type for the field CBOR type This field contains the CBOR type for the field
description This field contains a brief description for the field description This field contains a brief description for the field
specification This contains a pointer to the public specification specification This contains a pointer to the public specification
for the field if one exists for the field if one exists
This registry will be initially populated by the values in Table 20, This registry will be initially populated by the values in Table 20
and Table 21. The specification column for all of these entries will and Table 21. The specification column for all of these entries will
be this document. be this document.
15.7. COSE Elliptic Curve Registry 15.7. COSE Elliptic Curve Registry
It is requested that IANA create a new registry "COSE Elliptic Curve It is requested that IANA create a new registry "COSE Elliptic Curve
Parameters". Parameters". The registery is to be created as Expert Review
Required.
The columns of the table are: The columns of the table are:
name This is a descriptive name that enables easier reference to the name This is a descriptive name that enables easier reference to the
item. It is not used in the encoding. item. It is not used in the encoding.
value This is the value used to identify the curve. These values value This is the value used to identify the curve. These values
MUST be unique. The integer values from -256 to 255 are MUST be unique. The integer values from -256 to 255 are
designated as Standards Track Document Required. The integer designated as Standards Track Document Required. The integer
values from 256 to 65535 and -65536 to -257 are designated as values from 256 to 65535 and -65536 to -257 are designated as
Specification Required. Integer values over 65535 are designated Specification Required. Integer values over 65535 are designated
as first come first serve. Integer values less than -65536 are as first come, first served. Integer values less than -65536 are
marked as private use. marked as private use.
key type This designates the key type(s) that can be used with this key type This designates the key type(s) that can be used with this
curve. curve.
description This field contains a brief description of the curve. description This field contains a brief description of the curve.
specification This contains a pointer to the public specification specification This contains a pointer to the public specification
for the curve if one exists. for the curve if one exists.
This registry will be initially populated by the values in Table 18. This registry will be initially populated by the values in Table 18.
The specification column for all of these entries will be this The specification column for all of these entries will be this
document. document.
15.8. Media Type Registrations 15.8. Media Type Registrations
15.8.1. COSE Security Message 15.8.1. COSE Security Message
This section registers the "application/cose" and "application/ This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry. [CREF8] These cose+cbor" media types in the "Media Types" registry. [CREF9] These
media types are used to indicate that the content is a COSE_MSG. media types are used to indicate that the content is a COSE_MSG.
[CREF9] [CREF10]
Type name: application Type name: application
Subtype name: cose Subtype name: cose
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: binary Encoding considerations: binary
skipping to change at page 63, line 21 skipping to change at page 63, line 27
Restrictions on usage: N/A Restrictions on usage: N/A
Author: Jim Schaad, ietf@augustcellars.com Author: Jim Schaad, ietf@augustcellars.com
Change Controller: IESG Change Controller: IESG
Provisional registration? No Provisional registration? No
15.8.2. COSE Key media type 15.8.2. COSE Key media type
This section registers the "application/cose+json" and "application/ This section registers the "application/cose-key+cbor" and
cose-set+json" media types in the "Media Types" registry. These "application/cose-key-set+cbor" media types in the "Media Types"
media types are used to indicate, respectively, that content is a registry. These media types are used to indicate, respectively, that
COSE_Key or COSE_KeySet object. content is a COSE_Key or COSE_KeySet object.
Type name: application Type name: application
Subtype name: cose-key+cbor Subtype name: cose-key+cbor
Required parameters: N/A Required parameters: N/A
Optional parameters: N/A Optional parameters: N/A
Encoding considerations: binary Encoding considerations: binary
skipping to change at page 65, line 15 skipping to change at page 65, line 22
Author: Jim Schaad, ietf@augustcellars.com Author: Jim Schaad, ietf@augustcellars.com
Change Controller: IESG Change Controller: IESG
Provisional registration? No Provisional registration? No
15.9. CoAP Content Format Registrations 15.9. CoAP Content Format Registrations
This section registers a set of content formats for CoAP. ID This section registers a set of content formats for CoAP. ID
assignment in the 24-255 range requested. assignment in the 24-255 range is requested.
+--------------------------+----------+-------+-----------------+ +--------------------------+----------+-------+-----------------+
| Media Type | Encoding | ID | Reference | | Media Type | Encoding | ID | Reference |
+--------------------------+----------+-------+-----------------+ +--------------------------+----------+-------+-----------------+
| application/cose | | TBD10 | [This Document] | | application/cose | | TBD10 | [This Document] |
| | | | | | | | | |
| application/cose-key | | TBD11 | [This Document] | | application/cose-key | | TBD11 | [This Document] |
| | | | | | | | | |
| application/cose-key-set | | TBD12 | [This Document | | application/cose-key-set | | TBD12 | [This Document |
+--------------------------+----------+-------+-----------------+ +--------------------------+----------+-------+-----------------+
16. Security Considerations 16. Security Considerations
There are security considerations: There are security considerations:
1. Protect private keys 1. Protect private keys.
2. MAC messages with more than one recipient means one cannot figure 2. MAC messages with more than one recipient means one cannot figure
out who sent the message out which party sent the message.
3. Use of direct key with other recipient structures hands the key 3. Use of a direct key with other recipient structures hands the key
to other recipients. to the other recipients.
4. Use of direct ECDH direct encryption is easy for people to leak 4. Use of direct ECDH direct encryption is easy for people to leak
information on if there are other recipients in the message. information on if there are other recipients in the message.
5. Considerations about protected vs unprotected header fields. 5. Considerations about protected vs unprotected header fields.
6. Need to verify that: 1) the kty field of the key matches the key 6. Need to verify that: 1) the kty field of the key matches the key
and algorithm being used. 2) the kty field needs to be included and algorithm being used, 2) the kty field needs to be included
in the trust decision as well as the other key fields. 3) the in the trust decision as well as the other key fields, and 3) the
algorithm be included in the trust decision. algorithm is included in the trust decision.
17. References 17. References
17.1. Normative References 17.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, October 2013. Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>.
17.2. Informative References 17.2. Informative References
[AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D:
Recommendation for Block Cipher Modes of Operation: Recommendation for Block Cipher Modes of Operation:
Galois/Counter Mode (GCM) and GMAC.", Nov 2007. Galois/Counter Mode (GCM) and GMAC.", Nov 2007.
[DSS] U.S. National Institute of Standards and Technology, [DSS] U.S. National Institute of Standards and Technology,
"Digital Signature Standard (DSS)", July 2013. "Digital Signature Standard (DSS)", July 2013.
[I-D.greevenbosch-appsawg-cbor-cddl] [I-D.greevenbosch-appsawg-cbor-cddl]
Vigano, C., Birkholz, H., and R. Sun, "CBOR data Vigano, C. and H. Birkholz, "CBOR data definition language
definition language: a notational convention to express (CDDL): a notational convention to express CBOR data
CBOR data structures.", draft-greevenbosch-appsawg-cbor- structures", draft-greevenbosch-appsawg-cbor-cddl-07 (work
cddl-05 (work in progress), March 2015. in progress), October 2015.
[MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication",
May 1985. May 1985.
[MultiPrimeRSA] [MultiPrimeRSA]
Hinek, M. and D. Cheriton, "On the Security of Multi-prime Hinek, M. and D. Cheriton, "On the Security of Multi-prime
RSA", June 2006. RSA", June 2006.
[PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a
Signature Scheme with Partial Message Recover", February Signature Scheme with Partial Message Recover", February
2000. 2000.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104, February Hashing for Message Authentication", RFC 2104, DOI
1997. 10.17487/RFC2104, February 1997,
<http://www.rfc-editor.org/info/rfc2104>.
[RFC2633] Ramsdell, B., "S/MIME Version 3 Message Specification", [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message
RFC 2633, June 1999. Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999,
<http://www.rfc-editor.org/info/rfc2633>.
[RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography
Specification Version 2.0", RFC 2898, DOI 10.17487/ Specification Version 2.0", RFC 2898, DOI 10.17487/
RFC2898, September 2000, RFC2898, September 2000,
<http://www.rfc-editor.org/info/rfc2898>. <http://www.rfc-editor.org/info/rfc2898>.
[RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard
(AES) Key Wrap Algorithm", RFC 3394, September 2002. (AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394,
September 2002, <http://www.rfc-editor.org/info/rfc3394>.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003. Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February
2003, <http://www.rfc-editor.org/info/rfc3447>.
[RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with [RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with
CBC-MAC (CCM)", RFC 3610, September 2003. CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September
2003, <http://www.rfc-editor.org/info/rfc3610>.
[RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA-
224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC
4231, December 2005. 4231, DOI 10.17487/RFC4231, December 2005,
<http://www.rfc-editor.org/info/rfc4231>.
[RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/
Multipurpose Internet Mail Extensions (S/MIME) Multipurpose Internet Mail Extensions (S/MIME)
Capabilities", RFC 4262, December 2005. Capabilities", RFC 4262, DOI 10.17487/RFC4262, December
2005, <http://www.rfc-editor.org/info/rfc4262>.
[RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk,
"Elliptic Curve Cryptography Subject Public Key "Elliptic Curve Cryptography Subject Public Key
Information", RFC 5480, March 2009. Information", RFC 5480, DOI 10.17487/RFC5480, March 2009,
<http://www.rfc-editor.org/info/rfc5480>.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009. RFC 5652, DOI 10.17487/RFC5652, September 2009,
<http://www.rfc-editor.org/info/rfc5652>.
[RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet
Mail Extensions (S/MIME) Version 3.2 Message Mail Extensions (S/MIME) Version 3.2 Message
Specification", RFC 5751, January 2010. Specification", RFC 5751, DOI 10.17487/RFC5751, January
2010, <http://www.rfc-editor.org/info/rfc5751>.
[RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in
Cryptographic Message Syntax (CMS)", RFC 5752, January Cryptographic Message Syntax (CMS)", RFC 5752, DOI
2010. 10.17487/RFC5752, January 2010,
<http://www.rfc-editor.org/info/rfc5752>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869, May 2010. Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/
RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>.
[RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner, [RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner,
"Use of the RSA-KEM Key Transport Algorithm in the "Use of the RSA-KEM Key Transport Algorithm in the
Cryptographic Message Syntax (CMS)", RFC 5990, September Cryptographic Message Syntax (CMS)", RFC 5990, DOI
2010. 10.17487/RFC5990, September 2010,
<http://www.rfc-editor.org/info/rfc5990>.
[RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
Curve Cryptography Algorithms", RFC 6090, February 2011. Curve Cryptography Algorithms", RFC 6090, DOI 10.17487/
RFC6090, February 2011,
<http://www.rfc-editor.org/info/rfc6090>.
[RFC6151] Turner, S. and L. Chen, "Updated Security Considerations [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations
for the MD5 Message-Digest and the HMAC-MD5 Algorithms", for the MD5 Message-Digest and the HMAC-MD5 Algorithms",
RFC 6151, March 2011. RFC 6151, DOI 10.17487/RFC6151, March 2011,
<http://www.rfc-editor.org/info/rfc6151>.
[RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature
Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature
Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August
2013, <http://www.rfc-editor.org/info/rfc6979>. 2013, <http://www.rfc-editor.org/info/rfc6979>.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, DOI 10.17487/ Application Protocol (CoAP)", RFC 7252, DOI 10.17487/
RFC7252, June 2014, RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>. <http://www.rfc-editor.org/info/rfc7252>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, May 2015. Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <http://www.rfc-editor.org/info/rfc7515>.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, May 2015. RFC 7516, DOI 10.17487/RFC7516, May 2015,
<http://www.rfc-editor.org/info/rfc7516>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015. [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/
RFC7517, May 2015,
<http://www.rfc-editor.org/info/rfc7517>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI
2015. 10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>.
[RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF [RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF
Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015, Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015,
<http://www.rfc-editor.org/info/rfc7539>. <http://www.rfc-editor.org/info/rfc7539>.
[SEC1] Standards for Efficient Cryptography Group, "SEC 1: [SEC1] Standards for Efficient Cryptography Group, "SEC 1:
Elliptic Curve Cryptography", May 2009. Elliptic Curve Cryptography", May 2009.
[SP800-56A] [SP800-56A]
Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST
Special Publication 800-56A: Recommendation for Pair-Wise Special Publication 800-56A: Recommendation for Pair-Wise
Key Establishment Schemes Using Discrete Logarithm Key Establishment Schemes Using Discrete Logarithm
Cryptography", May 2013. Cryptography", May 2013.
Appendix A. CDDL Grammar Appendix A. CDDL Grammar
For people who prefer using a formal language to describe the syntax For people who prefer using a formal language to describe the syntax
of the CBOR, in this section a CDDL grammar is given that corresponds of the CBOR, in this section a CDDL grammar is given that corresponds
to [I-D.greevenbosch-appsawg-cbor-cddl]. This grammar is to [I-D.greevenbosch-appsawg-cbor-cddl]. This grammar is
informational, in the event of differences between this grammar and informational. In the event of differences between this grammar and
the prose, the prose is considered to be authoritative. the prose, the prose is considered to be authoritative.
The collected CDDL can be extracted from the XML version of this The collected CDDL can be extracted from the XML version of this
document via the following XPath expression below. (Depending on the document via the following XPath expression below. (Depending on the
XPath evaluator one is using, it may be necessary to deal with &gt; XPath evaluator one is using, it may be necessary to deal with &gt;
as an entity.) as an entity.)
//artwork[@type='CDDL']/text() //artwork[@type='CDDL']/text()
; This is define to make the tool quieter
Internal_Types = Sig_structure / Enc_structure / MAC_structure /
COSE_KDF_Context
Appendix B. Three Levels of Recipient Information Appendix B. Three Levels of Recipient Information
All of the currently defined recipient algorithms classes only use All of the currently defined recipient algorithms classes only use
two levels of the COSE_Encrypt structure. The first level is the two levels of the COSE_Encrypt structure. The first level is the
message content and the second level is the content key encryption. message content and the second level is the content key encryption.
However, if one uses a recipient algorithm such as RSA-KEM (see However, if one uses a recipient algorithm such as RSA-KEM (see
Appendix A of RSA-KEM [RFC5990], then it make sense to have three Appendix A of RSA-KEM [RFC5990], then it make sense to have three
levels of the COSE_Encrypt structure. levels of the COSE_Encrypt structure.
These levels would be: These levels would be:
skipping to change at page 70, line 49 skipping to change at page 71, line 49
]) ])
Appendix C. Examples Appendix C. Examples
The examples can be found at https://github.com/cose-wg/Examples. The examples can be found at https://github.com/cose-wg/Examples.
The file names in each section correspond the same file names in the The file names in each section correspond the same file names in the
repository. I am currently still in the process of getting the repository. I am currently still in the process of getting the
examples up there along with some control information for people to examples up there along with some control information for people to
be able to check and reproduce the examples. be able to check and reproduce the examples.
Examples may have some features that are in questions but not yet Examples may have some features that are in question but not yet
incorporated in the document. incorporated in the document.
To make it easier to read, the examples are presented using the To make it easier to read, the examples are presented using the
CBOR's diagnostic notation rather than a binary dump. A ruby based CBOR's diagnostic notation rather than a binary dump. A ruby based
tool exists to convert between a number of formats. This tool can be tool exists to convert between a number of formats. This tool can be
installed with the command line: installed with the command line:
gem install cbor-diag gem install cbor-diag
The diagnostic notation can be converted into binary files using the The diagnostic notation can be converted into binary files using the
skipping to change at page 76, line 40 skipping to change at page 77, line 40
}, },
h'' h''
] ]
] ]
]) ])
C.2.2. Direct plus Key Derivation C.2.2. Direct plus Key Derivation
This example uses the following: This example uses the following:
o CEK: AES-CCM w/128-bit key, truncate the tag to 64-bits o CEK: AES-CCM w/128-bit key, truncate the tag to 64 bits
o Recipient class: Use HKDF on a shared secret with the following o Recipient class: Use HKDF on a shared secret with the following
implicit fields as part of the context. implicit fields as part of the context.
* APU identity: "lighting-client" * APU identity: "lighting-client"
* APV identity: "lighting-server" * APV identity: "lighting-server"
* Supplementary Public Other: "Encryption Example 02" * Supplementary Public Other: "Encryption Example 02"
skipping to change at page 82, line 46 skipping to change at page 83, line 46
6d6a09eff', 6d6a09eff',
-3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed2 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed2
8bbfc117e', 8bbfc117e',
-4: h'57c92077664146e876760c9520d054aa93c3afb04e306705db60903 -4: h'57c92077664146e876760c9520d054aa93c3afb04e306705db60903
08507b4d3' 08507b4d3'
} }
] ]
Appendix D. Document Updates Appendix D. Document Updates
D.1. Version -05 to -06 D.1. Version -06 to -07
o Editorial Changes
o Make new IANA registries be Expert Review
D.2. Version -05 to -06
o Remove new CFRG Elliptical Curve key agreement algorithms. o Remove new CFRG Elliptical Curve key agreement algorithms.
o Remove RSA algorithms o Remove RSA algorithms
o Define a creation time and sequence number for discussions. o Define a creation time and sequence number for discussions.
o Remove message type field from all structures. o Remove message type field from all structures.
o Define CBOR tagging for all structures with IANA registrations. o Define CBOR tagging for all structures with IANA registrations.
D.2. Version -04 to -05 D.3. Version -04 to -05
o Removed the jku, x5c, x5t, x5t#S256, x5u, and jwk headers. o Removed the jku, x5c, x5t, x5t#S256, x5u, and jwk headers.
o Add enveloped data vs encrypted data structures. o Add enveloped data vs encrypted data structures.
o Add counter signature parameter. o Add counter signature parameter.
D.3. Version -03 to -04 D.4. Version -03 to -04
o Change top level from map to array. o Change top level from map to array.
o Eliminate the term "key management" from the document. o Eliminate the term "key management" from the document.
o Point to content registries for the 'content type' attribute o Point to content registries for the 'content type' attribute
o Push protected field into the KDF functions for recipients. o Push protected field into the KDF functions for recipients.
o Remove password based recipient information. o Remove password based recipient information.
o Create EC Curve Registry. o Create EC Curve Registry.
D.4. Version -02 to -03 D.5. Version -02 to -03
o Make a pass over all of the algorithm text. o Make a pass over all of the algorithm text.
o Alter the CDDL so that Keys and KeySets are top level items and o Alter the CDDL so that Keys and KeySets are top level items and
the key examples validate. the key examples validate.
o Add sample key structures. o Add sample key structures.
o Expand text on dealing with Externally Supplied Data. o Expand text on dealing with Externally Supplied Data.
o Update the examples to match some of the renumbering of fields. o Update the examples to match some of the renumbering of fields.
D.5. Version -02 to -03 D.6. Version -02 to -03
o Add a set of straw man proposals for algorithms. It is possible/ o Add a set of straw man proposals for algorithms. It is possible/
expected that this text will be moved to a new document. expected that this text will be moved to a new document.
o Add a set of straw man proposals for key structures. It is o Add a set of straw man proposals for key structures. It is
possible/expected that this text will be moved to a new document. possible/expected that this text will be moved to a new document.
o Provide guidance on use of externally supplied authenticated data. o Provide guidance on use of externally supplied authenticated data.
o Add external authenticated data to signing structure. o Add external authenticated data to signing structure.
D.6. Version -01 to -2 D.7. Version -01 to -2
o Add first pass of algorithm information o Add first pass of algorithm information
o Add direct key derivation example. o Add direct key derivation example.
D.7. Version -00 to -01 D.8. Version -00 to -01
o Add note on where the document is being maintained and o Add note on where the document is being maintained and
contributing notes. contributing notes.
o Put in proposal on MTI algorithms. o Put in proposal on MTI algorithms.
o Changed to use labels rather than keys when talking about what o Changed to use labels rather than keys when talking about what
indexes a map. indexes a map.
o Moved nonce/IV to be a common header item. o Moved nonce/IV to be a common header item.
skipping to change at page 84, line 39 skipping to change at page 85, line 47
o Start marking element 0 in registries as reserved. o Start marking element 0 in registries as reserved.
o Update examples. o Update examples.
Editorial Comments Editorial Comments
[CREF1] JLS: Need to check this list for correctness before publishing. [CREF1] JLS: Need to check this list for correctness before publishing.
[CREF2] JLS: I have not gone through the document to determine what [CREF2] JLS: I have not gone through the document to determine what
needs to be here yet. We mostly want to grab terms which are needs to be here yet. We mostly want to grab terms that are
used in unusual ways or are not generally understood. used in unusual ways or are not generally understood.
[CREF3] JLS: It would be possible to extend this section to talk about [CREF3] JLS: It would be possible to extend this section to talk about
those decisions which an application needs to think about rather those decisions that an application needs to think about rather
than just talking about MTI algorithms. than just talking about MTI algorithms.
[CREF4] JLS: A completest version of this grammar would list the options [CREF4] JLS: A completest version of this grammar would list the options
available in the protected and unprotected headers. Do we want available in the protected and unprotected headers. Do we want
to head that direction? to head that direction?
[CREF5] Hannes: Ensure that the list of examples only includes items [CREF5] Hannes: Ensure that the list of examples only includes items
which are implemented in this specification. Check the other that are implemented in this specification. Check the other
places where such lists occur and ensure that they also follow places where such lists occur and ensure that they also follow
this rule. this rule.
[CREF6] JLS: We can really simplify the grammar for COSE_Key to be just [CREF6] JLS: Don't talk about items which we do not define in this
specification.
[CREF7] JLS: We can really simplify the grammar for COSE_Key to be just
the kty (the one required field) and the generic item. The the kty (the one required field) and the generic item. The
reason to do this is that it makes things simpler. The reason reason to do this is that it makes things simpler. The reason
not to do this says that we really need to add a lot more items not to do this says that we really need to add a lot more items
so that a grammar check can be done that is more tightly so that a grammar check can be done that is more tightly
enforced. enforced.
[CREF7] Ilari: Look to see if we need to be clearer about how the fields [CREF8] Ilari: Look to see if we need to be clearer about how the fields
defined in the table are transported and thus why they have defined in the table are transported and thus why they have
labels. labels.
[CREF8] JLS: Should we register both or just the cose+cbor one? [CREF9] JLS: Should we register both or just the cose+cbor one?
[CREF9] JLS: Should we create the equivalent of the smime-type parameter [CREF10] JLS: Should we create the equivalent of the smime-type
to identify the inner content type? parameter to identify the inner content type?
Author's Address Author's Address
Jim Schaad Jim Schaad
August Cellars August Cellars
Email: ietf@augustcellars.com Email: ietf@augustcellars.com
 End of changes. 155 change blocks. 
289 lines changed or deleted 336 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/