Draft: draft-ietf-cose-msg

Commentary: Deal with issues in Francesca 's email on 12/2/2016 .
When a COSE object is carried in a CoAP message, the CoAP content
type parameter can be used to identify the message content.  The
CoAP content types can be found in CoAP_content_type.  The CBOR
Tag for the message structure is not required as each security
message is uniquely identified.
When a COSE object is carried as a CoAP payload, the CoAP content
type parameter can be used to identify the message content.  The
CoAP content types can be found in CoAP_content_type.  The CBOR
Tag for the message structure is not required as each security
message is uniquely identified.
The structure of COSE has been designed to have two buckets of
information that are not considered to be part of the payload itself,
but are used for holding information about content, algorithms, keys,
or evaluation hints for the processing of the layer.  These two
buckets are available for use in all of the structures except for
keys.  While these buckets can be present, they may not all be usable
in all instances.  For example, while the protected bucket is defined
as part of recipient structures, most of the algorithms that are used
for recipients do not provide for authenticated data and thus the
bucket should not be used.
The structure of COSE has been designed to have two buckets of
information that are not considered to be part of the payload itself,
but are used for holding information about content, algorithms, keys,
or evaluation hints for the processing of the layer.  These two
buckets are available for use in all of the structures except for
keys.  While these buckets can be present, they may not all be usable
in all instances.  For example, while the protected bucket is defined
as part of the recipient structure, some of the algorithms used for
recipient structures do not provide for authenticated data.  If this
is the case, the protected bucket should be left empty.
This parameter one of the ways that can be used to find the key to
be used.  The value of this parameter is matched against the 'kid'
member in a COSE_Key structure.  Applications MUST NOT assume that
'kid' values are unique.  There may be more than one key with the
same 'kid' value, it may be required that all of the keys need to
be checked to find the correct one.  The internal structure of
'kid' values is not defined and cannot be relied on by
applications.  Key identifier values are hints about which key to
use.  They are not directly a security critical field.  For this
reason, they can be placed in the unprotected headers bucket.
This parameter identifies one piece of data that can be used as
input to find the needed cryptographic key.  The value of this
parameter can be matched against the 'kid' member in a COSE_Key
structure.  Other methods of key distribution can define an
equivalent field to be matched.  Applications MUST NOT assume that
'kid' values are unique.  There may be more than one key with the
same 'kid' value, it may be required that all of the keys need to
be checked to find the correct one.  The internal structure of
'kid' values is not defined and cannot be relied on by
applications.  Key identifier values are hints about which key to
use.  They are not directly a security critical field.  For this
reason, they can be placed in the unprotected headers bucket.
This parameter provides the time the content cryptographic
operation is performed.  For signatures and recipient structures,
this would be the time that the signature or recipient key object
was created.  For content structures, this would be the time that
the content structure was created.  The unsigned integer value is
the number of seconds, excluding leap seconds, after midnight UTC,
January 1, 1970.  The field is primarily intended to be to be used
for countersignatures, however it can additionally be used for
replay detection as well.
This parameter provides the time the content cryptographic
operation is performed.  For signatures and recipient structures,
this would be the time that the signature or recipient key object
was created.  For content structures, this would be the time that
the content structure was created.  The unsigned integer value is
the number of seconds, excluding leap seconds, after midnight UTC,
January 1, 1970.  The field is primarily intended to be to be used
for counter signatures, however it can additionally be used for
replay detection as well.
The signature structure allows for one or more signatures to be
applied to a message payload.  There are provisions for parameters
about the content and parameters about the signature to be carried
along with the signature itself.  These parameters may be
authenticated by the signature, or just present.  An example of a
parameter about the content is the content type.  Examples of
parameters about the signature would be the algorithm and key used to
create the signature, when the signature was created, and a counter-
signature.
The signature structure allows for one or more signatures to be
applied to a message payload.  There are provisions for parameters
about the content and parameters about the signature to be carried
along with the signature itself.  These parameters may be
authenticated by the signature, or just present.  An example of a
parameter about the content is the content type.  Examples of
parameters about the signature would be the algorithm and key used to
create the signature, when the signature was created, and counter
signatures.
The CBOR object that carries the body, the signature and the
information about the body and signature is called the COSE_Sign1
structure.  Examples of COSE Single signature messages can be found
in Sign1_Examples.
so that if they cannot be modified in transit it can be detected.
This is the purpose of the externally supplied data field.
so that if they are be modified in transit it can be detected.  This
is the purpose of the externally supplied data field.
The protected attributes from the application encoded in a bstr
type.  If this field is not supplied, it defaults to a zero length
binary string.
Place the resulting signature value in the 'signature' field of
the map.
Create the value ToBeSigned by encoding the Sig_structure to a
byte string using the encoding described in CBOR-Canonical.
Place the resulting signature value in the 'signature' field of
the array.
Create the value ToBeSigned by encoding the Sig_structure to a
byte string using the encoding described in CBOR-Canonical..
The creation and validation of counter signatures over the different
items relies on the fact that the structure of the objects have the
same structure.  The elements are a set of protected attributes, a
set of unprotected attributes and a body in that order.  This means
that the Sig_structure can be used for in a uniform manner to get the
byte stream for processing a signature.  If the counter signature is
going to be computed over a COSE_Enveloped structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
The creation and validation of counter signatures over the different
items relies on the fact that the structure of the objects have the
same structure.  The elements are a set of protected attributes, a
set of unprotected attributes and a body in that order.  This means
that the Sig_structure can be used in a uniform manner to get the
byte stream for processing a signature.  If the counter signature is
going to be computed over a COSE_Enveloped structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
It should be noted that only a signature algorithm with appendix (see
SigAlgs) can be used for counter signatures.  This is because the
body should be able to be processed without having to evaluate the
countersignature, and this is not possible for signature schemes with
message recovery.
It should be noted that only a signature algorithm with appendix (see
SigAlgs) can be used for counter signatures.  This is because the
body should be able to be processed without having to evaluate the
counter signature, and this is not possible for signature schemes
with message recovery.
The same techniques and structures are used for encrypting both the
plain text and the keys used to protect the text.  This is different
from the approach used by both RFC5652 and RFC7516 where different
structures are used for the content layer and for the recipient
layer.  Two structures are defined: COSE_Enveloped to hold the
encrypted content, and COSE_recipient to hold the encrypted keys for
recipients.  Examples of encrypted messages can be found in
EncryptedExamples.
The same techniques and structures are used for encrypting both the
plain text and the keys used to protect the text.  This is different
from the approach used by both RFC5652 and RFC7516 where different
structures are used for the content layer and for the recipient
layer.  Two structures are defined: COSE_Enveloped to hold the
encrypted content, and COSE_recipient to hold the encrypted keys for
recipients.  Examples of encrypted messages can be found in
EnvelopedExamples.
The structure defined to hold an encrypted message is COSE_Encrypted.
Examples of encrypted messages can be found in EncryptedExamples.
The structure defined to hold an encrypted message is COSE_Encrypted.
Examples of encrypted messages can be found in EnvelopedExamples.
The encryption algorithm for AEAD algorithms is fairly simple.
Create a CBOR array (Enc_structure) to encode the authenticated
data.
Copy the protected header field from the message to be sent to the
second location in the Enc_structure.
Encode the Enc_structure using a CBOR Canonical encoding CBOR-
Canonical to get the AAD value.
The protected attributes from the body structure encoded in a bstr
type.  If there are no protected attributes, a bstr of length zero
is used.
Call the encryption algorithm with K (the encryption key to use),
P (the plain text) and AAD (the additional authenticated data).
Place the returned cipher text into the 'ciphertext' field of the
structure.
Call the encryption algorithm with K (the encryption key to use),
P (the plain text) and AAD.  Place the returned cipher text into
the 'ciphertext' field of the structure.
Verify that there was no external additional authenticated data
supplied for this operation.
The MAC message uses the COSE_Mac0 structure defined in this section
for carrying the body.
The MAC message uses the COSE_Mac0 structure defined in this section
for carrying the body.  Examples of MAC messages with an implicit key
can be found in Mac0Examples.
Create a MAC_structure and fill in the fields.
Encode the MAC_structure using a canonical CBOR encoder.  The
resulting bytes are the value to compute the MAC on.
Compute the MAC and place the result in the 'tag' field of the
COSE_Mac structure.
Create a MAC_structure and populate it with the appropriate
fields.
Place the resulting MAC in the 'tag' field of the COSE_Mac
structure.
Create a MAC_structure object and populate it with the appropriate
fields.
Obtain the cryptographic key from one of the recipients of the
message.
Compare the MAC value to the 'tag' field of the COSE_Mac
structure.
Applications need to determine the set of messages defined in this
document that it will be using.  The set of messages corresponds
fairly directly to the set of security services that are needed
and to the security levels needed.
Applications need to determine the set of messages defined in this
document that they will be using.  The set of messages corresponds
fairly directly to the set of security services that are needed
and to the security levels needed.
When applications use externally defined authenticated data, they
need to define how that data is to be defined.  This document
assumes that the data will be provided as a byte stream.  More
information can be found in Extern_AAD.
When applications use externally defined authenticated data, they
need to define how that data is encoded.  This document assumes
that the data will be provided as a byte stream.  More information
can be found in Extern_AAD.
There are a number of security considerations that need to be taken
into account by implementers of this specification.  The security
considerations that are specific to an individual algorithm are
placed next to the description of the algorithm.  While some
considerations have been highlighted here, additional considerations
may be found in the documents referred to that have full details of
the algorithm.
Using a the same key for two different algorithms can leak
information about the key.  It is therefore recommended that keys
be restricted to a single algorithm.
There are a number of security considerations that need to be taken
into account by implementers of this specification.  The security
considerations that are specific to an individual algorithm are
placed next to the description of the algorithm.  While some
considerations have been highlighted here, additional considerations
may be found in the documents listed in the references.
Using the same key for two different algorithms can leak
information about the key.  It is therefore recommended that keys
be restricted to a single algorithm.
What are the permissions assoicated with the key owner?
Have the restrictions associated with the key, such as algorithm
or freshness, been checked are are correct?
What are the permissions associated with the key owner?
Have the restrictions associated with the key, such as algorithm
or freshness, been checked and are correct?