draft-ietf-cose-msg-18.txt   draft-ietf-cose-msg-19.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Intended status: Standards Track September 10, 2016 Intended status: Standards Track September 27, 2016
Expires: March 14, 2017 Expires: March 31, 2017
CBOR Object Signing and Encryption (COSE) CBOR Object Signing and Encryption (COSE)
draft-ietf-cose-msg-18 draft-ietf-cose-msg-19
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 basic security services defined for this data format. ability to have basic security services defined for this data format.
This document defines the CBOR Object Signing and Encryption (COSE) This document defines the CBOR Object Signing and Encryption (COSE)
specification. This specification describes how to create and specification. This specification describes how to create and
process signature, message authentication codes and encryption using process signature, message authentication codes and encryption using
CBOR for serialization. This specification additionally specifies CBOR for serialization. This specification additionally specifies
skipping to change at page 1, line 45 skipping to change at page 1, line 45
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 March 14, 2017. This Internet-Draft will expire on March 31, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 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 39 skipping to change at page 2, line 39
3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12
4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16
4.1. Signing with One or More Signers . . . . . . . . . . . . 16 4.1. Signing with One or More Signers . . . . . . . . . . . . 16
4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18
4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19
4.4. Signing and Verification Process . . . . . . . . . . . . 20 4.4. Signing and Verification Process . . . . . . . . . . . . 20
4.5. Computing Counter Signatures . . . . . . . . . . . . . . 21 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 21
5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22
5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22
5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 24 5.1.1. Content Key Distribution Methods . . . . . . . . . . 24
5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 25 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 25
5.3. How to encrypt and decrypt for AEAD Algorithms . . . . . 25 5.3. How to encrypt and decrypt for AEAD Algorithms . . . . . 25
5.4. How to encrypt and decrypt for AE Algorithms . . . . . . 28 5.4. How to encrypt and decrypt for AE Algorithms . . . . . . 28
6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 29 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.1. MACed Message with Recipients . . . . . . . . . . . . . . 30 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 30
6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 31 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 31
6.3. How to compute and verify a MAC . . . . . . . . . . . . . 31 6.3. How to compute and verify a MAC . . . . . . . . . . . . . 31
7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 33 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 33 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 33
8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 36 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 36
skipping to change at page 3, line 21 skipping to change at page 3, line 21
10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 45 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 45
10.1.1. Security Considerations . . . . . . . . . . . . . . 46 10.1.1. Security Considerations . . . . . . . . . . . . . . 46
10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 47 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 47
10.2.1. Security Considerations . . . . . . . . . . . . . . 50 10.2.1. Security Considerations . . . . . . . . . . . . . . 50
10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 50 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 50
10.3.1. Security Considerations . . . . . . . . . . . . . . 51 10.3.1. Security Considerations . . . . . . . . . . . . . . 51
11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 51 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 51
11.1. HMAC-based Extract-and-Expand Key Derivation Function 11.1. HMAC-based Extract-and-Expand Key Derivation Function
(HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 52 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 52
11.2. Context Information Structure . . . . . . . . . . . . . 54 11.2. Context Information Structure . . . . . . . . . . . . . 54
12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 57 12. Content Key Distribution Methods . . . . . . . . . . . . . . 57
12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 58 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 58
12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 58 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 58
12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 59 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 59
12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 60 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 60
12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 61 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 61
12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 62 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 62
12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 62 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 62
12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 63 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 63
12.4.2. Security Considerations . . . . . . . . . . . . . . 66 12.4.2. Security Considerations . . . . . . . . . . . . . . 66
12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 67 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 67
skipping to change at page 8, line 26 skipping to change at page 8, line 26
algorithm with the encryption service. algorithm with the encryption service.
Authenticated Encryption with Authenticated Data (AEAD) algorithms Authenticated Encryption with Authenticated Data (AEAD) algorithms
provide the same content authentication service as AE algorithms, but provide the same content authentication service as AE algorithms, but
additionally provide for authentication of non-encrypted data as additionally provide for authentication of non-encrypted data as
well. well.
2. Basic COSE Structure 2. Basic COSE Structure
The COSE object structure is designed so that there can be a large The COSE object 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 types
security messages. All of the message structures are built on the of security messages. All of the message structures are built on the
CBOR array type. The first three elements of the array always CBOR array type. The first three elements of the array always
contain the same information: contain the same information:
1. The set of protected header parameters wrapped in a bstr. 1. The set of protected header parameters wrapped in a bstr.
2. The set of unprotected header parameters as a map. 2. The set of unprotected header parameters as a map.
3. The content of the message. The content is either the plain text 3. The content of the message. The content is either the plain text
or the cipher text as appropriate. The content may be detached, or the cipher text as appropriate. The content may be detached,
but the location is still used. The content is wrapped in a bstr but the location is still used. The content is wrapped in a bstr
when present and is a nil value when detached. when present and is a nil value when detached.
Elements after this point are dependent on the specific message type. Elements after this point are dependent on the specific message type.
COSE messages are also built using the concept of using layers to COSE messages are also built using the concept of layers to separate
separate different types of cryptographic concepts. As an example of different types of cryptographic concepts. As an example of how this
how this works consider the COSE_Encrypt message (Section 5.1). This works consider the COSE_Encrypt message (Section 5.1). This message
message type is broken into two layers: the content layer and the type is broken into two layers: the content layer and the recipient
recipient layer. In the content layer, the plain text is encrypted layer. In the content layer, the plain text is encrypted and
and information about the encrypted message are placed. In the information about the encrypted message are placed. In the recipient
recipient layer, the content encryption key (CEK) is encrypted and layer, the content encryption key (CEK) is encrypted and information
information about how it is encrypted for each recipient is placed. about how it is encrypted for each recipient is placed. A single
A single layer version of the encryption message COSE_Encrypt0 layer version of the encryption message COSE_Encrypt0 (Section 5.2)
(Section 5.2) is provided for cases where the CEK is pre-shared. is provided for cases where the CEK is pre-shared.
Identification of which type of message has been presented is done by Identification of which type of message has been presented is done by
the following method: the following method:
1. The specific message type is known from the context. This may be 1. The specific message type is known from the context. This may be
defined by a marker in the containing structure or by defined by a marker in the containing structure or by
restrictions specified by the application protocol. restrictions specified by the application protocol.
2. The message type is identified by a CBOR tag. Messages with a 2. The message type is identified by a CBOR tag. Messages with a
CBOR tag are known in this specification as tagged messages, CBOR tag are known in this specification as tagged messages,
skipping to change at page 11, line 10 skipping to change at page 11, line 10
buckets are available for use in all of the structures except for buckets are available for use in all of the structures except for
keys. While these buckets are present, they may not all be usable in keys. While these buckets are present, they may not all be usable in
all instances. For example, while the protected bucket is defined as all instances. For example, while the protected bucket is defined as
part of the recipient structure, some of the algorithms used for part of the recipient structure, some of the algorithms used for
recipient structures do not provide for authenticated data. If this recipient structures do not provide for authenticated data. If this
is the case, the protected bucket is left empty. is the case, the protected bucket is left empty.
Both buckets are implemented as CBOR maps. The map key is a 'label' Both buckets are implemented as CBOR maps. The map key is a 'label'
(Section 1.4). The value portion is dependent on the definition for (Section 1.4). The value portion is dependent on the definition for
the label. Both maps use the same set of label/value pairs. The the label. Both maps use the same set of label/value pairs. The
integer and string values for labels has been divided into several integer and string values for labels have been divided into several
sections with a standard range, a private range, and a range that is sections with a standard range, a private range, and a range that is
dependent on the algorithm selected. The defined labels can be found dependent on the algorithm selected. The defined labels can be found
in the "COSE Header Parameters" IANA registry (Section 16.2). in the "COSE Header Parameters" IANA registry (Section 16.2).
Two buckets are provided for each layer: Two buckets are provided for each layer:
protected: Contains parameters about the current layer that are to protected: Contains parameters about the current layer that are to
be cryptographically protected. This bucket MUST be empty if it be cryptographically protected. This bucket MUST be empty if it
is not going to be included in a cryptographic computation. This is not going to be included in a cryptographic computation. This
bucket is encoded in the message as a binary object. This value bucket is encoded in the message as a binary object. This value
skipping to change at page 12, line 12 skipping to change at page 12, line 12
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"
registry (Section 16.2). Some common parameters are defined in the registry (Section 16.2). Some common parameters are defined in the
next section, but a number of parameters are defined throughout this next section, but a number of parameters are defined throughout this
document. document.
Labels in each of the maps MUST be unique. When processing messages, Labels in each of the maps MUST be unique. When processing messages,
if a label appears multiple times, the message MUST be rejected as if a label appears multiple times, the message MUST be rejected as
malformed. Applications SHOULD perform the same checks that the same malformed. Applications SHOULD verify that the same label does not
label does not occur in both the protected and unprotected headers. occur in both the protected and unprotected headers. If the message
If the message is not rejected as malformed, attributes MUST be is not rejected as malformed, attributes MUST be obtained from the
obtained from the protected bucket before they are obtained from the protected bucket before they are obtained from the unprotected
unprotected bucket. bucket.
The following CDDL fragment represents the two header buckets. A The following CDDL fragment represents the two header buckets. A
group Headers is defined in CDDL that represents the two buckets in group Headers is defined in CDDL that represents the two buckets in
which attributes are placed. This group is used to provide these two which attributes are placed. This group is used to provide these two
fields consistently in all locations. A type is also defined which fields consistently in all locations. A type is also defined which
represents the map of common headers. represents the map of common headers.
Headers = ( Headers = (
protected : empty_or_serialized_map, protected : empty_or_serialized_map,
unprotected : header_map unprotected : header_map
skipping to change at page 13, line 38 skipping to change at page 13, line 38
The header parameter values indicated by 'crit' can be processed The header parameter values indicated by 'crit' can be processed
by either the security library code or by an application using a by either the security library code or by an application using a
security library; the only requirement is that the parameter is security library; the only requirement is that the parameter is
processed. If the 'crit' value list includes a value for which processed. If the 'crit' value list includes a value for which
the parameter is not in the protected bucket, this is a fatal the parameter is not in the protected bucket, this is a fatal
error in processing the message. error in processing the message.
content type This parameter is used to indicate the content type of content type This parameter is used to indicate the content type of
the data in the payload or cipher text fields. Integers are from the data in the payload or cipher text fields. Integers are from
the "CoAP Content-Formats" IANA registry table. Text values the "CoAP Content-Formats" IANA registry table [COAP.Formats].
following the syntax of Content-Type defined in Section 5.1 of Text values following the syntax of Content-Type defined in
[RFC2045] omitting the prefix string "Content-Type:". Leading and Section 5.1 of [RFC2045] omitting the prefix string "Content-
trailing whitespace is also omitted. Textual content values along Type:". Leading and trailing whitespace is also omitted. Textual
with parameters and subparameters can be located using the IANA content values along with parameters and subparameters can be
"Media Types" registry. Applications SHOULD provide this located using the IANA "Media Types" registry. Applications
parameter if the content structure is potentially ambiguous. SHOULD provide this parameter if the content structure is
potentially ambiguous.
kid This parameter identifies one piece of data that can be used as kid This parameter identifies one piece of data that can be used as
input to find the needed cryptographic key. The value of this input to find the needed cryptographic key. The value of this
parameter can be matched against the 'kid' member in a COSE_Key parameter can be matched against the 'kid' member in a COSE_Key
structure. Other methods of key distribution can define an structure. Other methods of key distribution can define an
equivalent field to be matched. Applications MUST NOT assume that equivalent field to be matched. Applications MUST NOT assume that
'kid' values are unique. There may be more than one key with the 'kid' values are unique. There may be more than one key with the
same 'kid' value, so all of the keys may need to be checked to same 'kid' value, so all of the keys may need to be checked to
find the correct one. The internal structure of 'kid' values is find the correct one. The internal structure of 'kid' values is
not defined and cannot be relied on by applications. Key not defined and cannot be relied on by applications. Key
identifier values are hints about which key to use. This is not a identifier values are hints about which key to use. This is not a
security critical field. For this reason, it can be placed in the security critical field. For this reason, it can be placed in the
unprotected headers bucket. unprotected headers bucket.
IV This parameter holds the Initialization Vector (IV) value. For IV This parameter holds the Initialization Vector (IV) value. For
some symmetric encryption algorithms this may be referred to as a some symmetric encryption algorithms this may be referred to as a
nonce. As the IV is authenticated by the encryption process, it nonce. The IV can be placed in the unprotected header as
can be placed in the unprotected header bucket. modifying the IV will cause the decryption to yield plaintext that
is readily detectable as garbled.
Partial IV This parameter holds a part of the IV value. When using Partial IV This parameter holds a part of the IV value. When using
the COSE_Encrypt0 structure, a portion of the IV can be part of the COSE_Encrypt0 structure, a portion of the IV can be part of
the context associated with the key. This field is used to carry the context associated with the key. This field is used to carry
a value that causes the IV to be changed for each message. As the a value that causes the IV to be changed for each message. The IV
IV is authenticated by the encryption process, this value can be can be placed in the unprotected header as modifying the IV will
placed in the unprotected header bucket. The 'Initialization cause the decryption to yield plaintext that is readily detectable
Vector' and 'Partial Initialization Vector' parameters MUST NOT as garbled. The 'Initialization Vector' and 'Partial
both be present in the same security layer. Initialization Vector' parameters MUST NOT both be present in the
same security layer.
The message IV is generated by the following steps: The message IV is generated by the following steps:
1. Left pad the partial IV with zeros to the length of IV. 1. Left pad the partial IV with zeros to the length of IV.
2. XOR the padded partial IV with the context IV. 2. XOR the padded partial IV with the context IV.
counter signature This parameter holds one or more counter signature counter signature This parameter holds one or more counter signature
values. Counter signatures provide a method of having a second values. Counter signatures provide a method of having a second
party sign some data. The counter signature parameter can occur party sign some data. The counter signature parameter can occur
as an unprotected attribute in any of the following structures: as an unprotected attribute in any of the following structures:
skipping to change at page 16, line 48 skipping to change at page 16, line 48
application environments where other rules are needed. An application environments where other rules are needed. An
application that employs a rule other than one valid signature for application that employs a rule other than one valid signature for
each signer must specify those rules. Also, where simple matching of each signer must specify those rules. Also, where simple matching of
the signer identifier is not sufficient to determine whether the the signer identifier is not sufficient to determine whether the
signatures were generated by the same signer, the application signatures were generated by the same signer, the application
specification must describe how to determine which signatures were specification must describe how to determine which signatures were
generated by the same signer. Support for different communities of generated by the same signer. Support for different communities of
recipients is the primary reason that signers choose to include more recipients is the primary reason that signers choose to include more
than one signature. For example, the COSE_Sign structure might than one signature. For example, the COSE_Sign structure might
include signatures generated with the Edwards Digital Signature include signatures generated with the Edwards Digital Signature
Algorithm (EdDSA) signature algorithm and with the Elliptic Curve Algorithm (EdDSA) [I-D.irtf-cfrg-eddsa] signature algorithm and with
Digital Signature Algorithm (ECDSA) signature algorithm. This allows the Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS]
recipients to verify the signature associated with one algorithm or signature algorithm. This allows recipients to verify the signature
the other. (The original source of this text is [RFC5652].) More associated with one algorithm or the other. (The original source of
detailed information on multiple signature evaluation can be found in this text is [RFC5652].) More detailed information on multiple
[RFC5752]. signature evaluation can be found in [RFC5752].
The signature structure can be encoded either as tagged or untagged The signature structure can be encoded either as tagged or untagged
depending on the context it will be used in. A tagged COSE_Sign depending on the context it will be used in. A tagged COSE_Sign
structure is identified by the CBOR tag TBD1. The CDDL fragment that structure is identified by the CBOR tag TBD1. The CDDL fragment that
represents this is: represents this is:
COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1 COSE_Sign_Tagged = #6.991(COSE_Sign) ; Replace 991 with TBD1
A COSE Signed Message is defined in two parts. The CBOR object that A COSE Signed Message is defined in two parts. The CBOR object that
carries the body and information about the body is called the carries the body and information about the body is called the
skipping to change at page 18, line 31 skipping to change at page 18, line 31
The CDDL fragment that represents the above text for COSE_Signature The CDDL fragment that represents the above text for COSE_Signature
follows. follows.
COSE_Signature = [ COSE_Signature = [
Headers, Headers,
signature : bstr signature : bstr
] ]
4.2. Signing with One Signer 4.2. Signing with One Signer
The COSE_Sign1 signature structure is used when only one signer is The COSE_Sign1 signature structure is used when only one signature is
going to be placed on a message. The parameters dealing with the going to be placed on a message. The parameters dealing with the
content and the signature are placed in the same pair of buckets content and the signature are placed in the same pair of buckets
rather than having the separation of COSE_Sign. rather than having the separation of COSE_Sign.
The structure can be encoded either tagged or untagged depending on The structure can be encoded either tagged or untagged depending on
the context it will be used in. A tagged COSE_Sign1 structure is the context it will be used in. A tagged COSE_Sign1 structure is
identified by the CBOR tag TBD7. The CDDL fragment that represents identified by the CBOR tag TBD7. The CDDL fragment that represents
this is: this is:
COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7 COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7
skipping to change at page 19, line 23 skipping to change at page 19, line 23
follows. follows.
COSE_Sign1 = [ COSE_Sign1 = [
Headers, Headers,
payload : bstr / nil, payload : bstr / nil,
signature : bstr signature : bstr
] ]
4.3. Externally Supplied Data 4.3. Externally Supplied Data
One of the features supplied in the COSE document is the ability for One of the features offered in the COSE document is the ability for
applications to provide additional data to be authenticated, but that applications to provide additional data to be authenticated, but that
is not carried as part of the COSE object. The primary reason for is not carried as part of the COSE object. The primary reason for
supporting this can be seen by looking at the CoAP message structure supporting this can be seen by looking at the CoAP message structure
[RFC7252], where the facility exists for options to be carried before [RFC7252], where the facility exists for options to be carried before
the payload. Examples of data that can be placed in this location the payload. Examples of data that can be placed in this location
would be the CoAP code or CoAP options. If the data is in the header would be the CoAP code or CoAP options. If the data is in the header
section, then it is available for proxies to help in performing its section, then it is available for proxies to help in performing its
operations. For example, the Accept Option can be used by a proxy to operations. For example, the Accept Option can be used by a proxy to
determine if an appropriate value is in the Proxy's cache. But the determine if an appropriate value is in the Proxy's cache. But the
sender can prevent a proxy from changing the set of values that it sender can prevent a proxy from changing the set of values that it
skipping to change at page 20, line 18 skipping to change at page 20, line 18
the same on both sides. Using options from CoAP might give a the same on both sides. Using options from CoAP might give a
problem if the same relative numbering is kept. An intermediate problem if the same relative numbering is kept. An intermediate
node could insert or remove an option, changing how the relative node could insert or remove an option, changing how the relative
number is done. An application would need to specify that the number is done. An application would need to specify that the
relative number must be re-encoded to be relative only to the relative number must be re-encoded to be relative only to the
options that are in the external data. options that are in the external data.
4.4. Signing and Verification Process 4.4. Signing and Verification Process
In order to create a signature, a well-defined byte stream is needed. In order to create a signature, a well-defined byte stream is needed.
This algorithm takes in the body information (COSE_Sign or This signing and verification process takes in the body information
COSE_Sign1), the signer information (COSE_Signature), and the (COSE_Sign or COSE_Sign1), the signer information (COSE_Signature),
application data (external source). A CBOR array is used to and the application data (external source). A CBOR array is used to
construct the byte stream. The fields of the array in order are: construct the byte stream. The fields of the array in order are:
1. A text string identifying the context of the signature. The 1. A text string identifying the context of the signature. The
context string is: context string is:
"Signature" for signatures using the COSE_Signature structure. "Signature" for signatures using the COSE_Signature structure.
"Signature1" for signatures using the COSE_Sign1 structure. "Signature1" for signatures using the COSE_Sign1 structure.
"CounterSignature" for signatures used as counter signature "CounterSignature" for signatures used as counter signature
skipping to change at page 21, line 47 skipping to change at page 21, line 47
to verify with), alg (the algorithm used sign with), ToBeSigned to verify with), alg (the algorithm used sign with), ToBeSigned
(the value to sign), and sig (the signature to be verified). (the value to sign), and sig (the signature to be verified).
In addition to performing the signature verification, one must also In addition to performing the signature verification, one must also
perform the appropriate checks to ensure that the key is correctly perform the appropriate checks to ensure that the key is correctly
paired with the signing identity and that the signing identity is paired with the signing identity and that the signing identity is
authorized before performing actions. authorized before performing actions.
4.5. Computing Counter Signatures 4.5. Computing Counter Signatures
Counter signatures provide a method of having a different signature Counter signatures provide a method of associating different
occur on some piece of content. This is normally used to provide a signature generated by different signers with some piece of content.
signature on a signature allowing for a proof that a signature This is normally used to provide a signature on a signature allowing
existed at a given time (i.e., a Timestamp). In this document, we for a proof that a signature existed at a given time (i.e., a
allow for counter signatures to exist in a greater number of Timestamp). In this document, we allow for counter signatures to
environments. As an example, it is possible to place a counter exist in a greater number of environments. As an example, it is
signature in the unprotected attributes of a COSE_Encrypt object. possible to place a counter signature in the unprotected attributes
This would allow for an intermediary to either verify that the of a COSE_Encrypt object. This would allow for an intermediary to
encrypted byte stream has not been modified, without being able to either verify that the encrypted byte stream has not been modified,
decrypt it, or for the intermediary to assert that an encrypted byte without being able to decrypt it, or for the intermediary to assert
stream either existed at a given time or passed through it in terms that an encrypted byte stream either existed at a given time or
of routing (i.e., a proxy signature). passed through it in terms of routing (i.e., a proxy signature).
An example of a counter signature on a signature can be found in An example of a counter signature on a signature can be found in
Appendix C.1.3. An example of a counter signature in an encryption Appendix C.1.3. An example of a counter signature in an encryption
object can be found in Appendix C.3.3. object can be found in Appendix C.3.3.
The creation and validation of counter signatures over the different The creation and validation of counter signatures over the different
items relies on the fact that the structure of the objects have the items relies on the fact that the structure of the objects have the
same structure. The elements are a set of protected attributes, a same structure. The elements are a set of protected attributes, a
set of unprotected attributes, and a body, in that order. This means set of unprotected attributes, and a body, in that order. This means
that the Sig_structure can be used in a uniform manner to get the that the Sig_structure can be used in a uniform manner to get the
skipping to change at page 24, line 25 skipping to change at page 24, line 25
The CDDL fragment that corresponds to the above text for The CDDL fragment that corresponds to the above text for
COSE_recipient is: COSE_recipient is:
COSE_recipient = [ COSE_recipient = [
Headers, Headers,
ciphertext : bstr / nil, ciphertext : bstr / nil,
? recipients : [+COSE_recipient] ? recipients : [+COSE_recipient]
] ]
5.1.1. Recipient Algorithm Classes 5.1.1. Content Key Distribution Methods
An encrypted message consists of an encrypted content and an An encrypted message consists of an encrypted content and an
encrypted CEK for one or more recipients. The CEK is encrypted for encrypted CEK for one or more recipients. The CEK is encrypted for
each recipient, using a key specific to that recipient. The details each recipient, using a key specific to that recipient. The details
of this encryption depend on which class the recipient algorithm of this encryption depend on which class the recipient algorithm
falls into. Specific details on each of the classes can be found in falls into. Specific details on each of the classes can be found in
Section 12. A short summary of the five recipient algorithm classes Section 12. A short summary of the five content key distribution
is: methods is:
direct: The CEK is the same as the identified previously distributed direct: The CEK is the same as the identified previously distributed
symmetric key or derived from a previously distributed secret. No symmetric key or derived from a previously distributed secret. No
CEK is transported in the message. CEK is transported in the message.
symmetric key-encryption keys: The CEK is encrypted using a symmetric key-encryption keys: The CEK is encrypted using a
previously distributed symmetric KEK. previously distributed symmetric KEK.
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
skipping to change at page 27, line 10 skipping to change at page 27, line 10
secrets. secrets.
Direct Encryption and Direct Key Agreement: The key is Direct Encryption and Direct Key Agreement: The key is
determined by the key and algorithm in the recipient determined by the key and algorithm in the recipient
structure. The encryption algorithm and size of the key to be structure. The encryption algorithm and size of the key to be
used are inputs into the KDF used for the recipient. (For used are inputs into the KDF used for the recipient. (For
direct, the KDF can be thought of as the identity operation.) direct, the KDF can be thought of as the identity operation.)
Examples of these algorithms are found in Section 12.1.2 and Examples of these algorithms are found in Section 12.1.2 and
Section 12.4.1. Section 12.4.1.
Other: The key is randomly generated. Other: The key is randomly or pseudo-randomly generated.
4. Call the encryption algorithm with K (the encryption key), P (the 4. Call the encryption algorithm with K (the encryption key), P (the
plain text) and AAD. Place the returned cipher text into the plain text) and AAD. Place the returned cipher text into the
'ciphertext' field of the structure. 'ciphertext' field of the structure.
5. For recipients of the message, recursively perform the encryption 5. For recipients of the message, recursively perform the encryption
algorithm for that recipient, using K (the encryption key) as the algorithm for that recipient, using K (the encryption key) as the
plain text. plain text.
How to decrypt a message: How to decrypt a message:
skipping to change at page 29, line 45 skipping to change at page 29, line 45
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 the 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 that created and sent the step). In both of these cases, the entity that created and sent the
message MAC can be validated. (This knowledge of sender assumes that message MAC can be validated. (This knowledge of sender 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.) The origination property can be obtained with both of the to yourself.) The origination property can be obtained with both of
MAC message structures. the MAC message structures.
6.1. MACed Message with Recipients 6.1. MACed Message with Recipients
The multiple recipient MACed message uses two structures, the The multiple recipient MACed message uses two structures, the
COSE_Mac structure defined in this section for carrying the body and COSE_Mac structure defined in this section for carrying the body and
the COSE_recipient structure (Section 5.1) to hold the key used for the COSE_recipient structure (Section 5.1) to hold the key used for
the MAC computation. Examples of MACed messages can be found in the MAC computation. Examples of MACed messages can be found in
Appendix C.5. Appendix C.5.
The MAC structure can be encoded either tagged or untagged depending The MAC structure can be encoded either tagged or untagged depending
skipping to change at page 57, line 40 skipping to change at page 57, line 40
PartyUInfo : [ PartyInfo ], PartyUInfo : [ PartyInfo ],
PartyVInfo : [ PartyInfo ], PartyVInfo : [ PartyInfo ],
SuppPubInfo : [ SuppPubInfo : [
keyDataLength : uint, keyDataLength : uint,
protected : empty_or_serialized_map, protected : empty_or_serialized_map,
? other : bstr ? other : bstr
], ],
? SuppPrivInfo : bstr ? SuppPrivInfo : bstr
] ]
12. Recipient Algorithm Classes 12. Content Key Distribution Methods
Recipient algorithms can be defined into a number of different Content key distribution methods (recipient algorithms) can be
classes. COSE has the ability to support many classes of recipient defined into a number of different classes. COSE has the ability to
algorithms. In this section, a number of classes are listed and then support many classes of recipient algorithms. In this section, a
a set of algorithms are specified for each of the classes. The names number of classes are listed and then a set of algorithms are
of the recipient algorithm classes used here are the same as are specified for each of the classes. The names of the recipient
defined in [RFC7516]. Other specifications use different terms for algorithm classes used here are the same as are defined in [RFC7516].
the recipient algorithm classes or do not support some of the Other specifications use different terms for the recipient algorithm
recipient algorithm classes. classes or do not support some of the 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 CEK. When direct encryption mode is used, it manipulation as the CEK. When direct encryption mode is used, it
MUST be the only mode used on the message. MUST be the only mode used on the message.
The COSE_Encrypt structure for the recipient is organized as follows: The COSE_Encrypt structure for the recipient is organized as follows:
skipping to change at page 73, line 47 skipping to change at page 73, line 47
15. Application Profiling Considerations 15. Application Profiling Considerations
This document is designed to provide a set of security services, but This document is designed to provide a set of security services, but
not to provide implementation requirements for specific usage. The not to provide implementation requirements for specific usage. The
interoperability requirements are provided for how each of the interoperability requirements are provided for how each of the
individual services are used and how the algorithms are to be used individual services are used and how the algorithms are to be used
for interoperability. The requirements about which algorithms and for interoperability. The requirements about which algorithms and
which services are needed are deferred to each application. which services are needed are deferred to each application.
It is intended that a profile of this document be created that It is intended that a profile of this document be created that
defines the interopability requirements for that specific defines the interoperability requirements for that specific
application. This section provides a set of guidelines and topics application. This section provides a set of guidelines and topics
that need to be considered when profiling this document. that need to be considered when profiling this document.
o Applications need to determine the set of messages defined in this o Applications need to determine the set of messages defined in this
document that they will be using. The set of messages corresponds document that they will be using. The set of messages corresponds
fairly directly to the set of security services that are needed fairly directly to the set of security services that are needed
and to the security levels needed. and to the security levels needed.
o Applications may define new header parameters for a specific o Applications may define new header parameters for a specific
purpose. Applications will often times select specific header purpose. Applications will often times select specific header
skipping to change at page 89, line 19 skipping to change at page 89, line 19
could be defined as 'YES' and 'NO '.) could be defined as 'YES' and 'NO '.)
19. References 19. References
19.1. Normative References 19.1. Normative 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.
[COAP.Formats]
IANA, , "CoAP Content-Formats".
[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.
[MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication", [MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication",
May 1985. May 1985.
[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, Hashing for Message Authentication", RFC 2104,
DOI 10.17487/RFC2104, February 1997, DOI 10.17487/RFC2104, February 1997,
<http://www.rfc-editor.org/info/rfc2104>. <http://www.rfc-editor.org/info/rfc2104>.
skipping to change at page 90, line 21 skipping to change at page 90, line 26
<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.
19.2. Informative References 19.2. Informative References
[I-D.greevenbosch-appsawg-cbor-cddl] [I-D.greevenbosch-appsawg-cbor-cddl]
Vigano, C. and H. Birkholz, "CBOR data definition language Vigano, C. and H. Birkholz, "CBOR data definition language
(CDDL): a notational convention to express CBOR data (CDDL): a notational convention to express CBOR data
structures", draft-greevenbosch-appsawg-cbor-cddl-08 (work structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work
in progress), March 2016. in progress), September 2016.
[I-D.irtf-cfrg-eddsa] [I-D.irtf-cfrg-eddsa]
Josefsson, S. and I. Liusvaara, "Edwards-curve Digital Josefsson, S. and I. Liusvaara, "Edwards-curve Digital
Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08 Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-08
(work in progress), August 2016. (work in progress), August 2016.
[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.
 End of changes. 26 change blocks. 
79 lines changed or deleted 85 lines changed or added

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