Draft: draft-ietf-cose-msg

Commentary: Do a pass to try and get some consistent usage of these terms . Also include a comment in the xml so that authors might notice how they are to be used in the future . 
 JOSE now allows for a single recipient to be encoded at the same level as the content . While COSE does not allow for quite the same way of encoding this it would be possible to do something similar . Current syntax is " recipients : COSEencrypta\ null ; " Do so would allow for a single recipient to be appended to the end of the current array of values rather than creating two array sub - encodings in CBOR . This encoding saves 2 bytes in the event of a single recipient at the expense of needing to pass in an offset in the array structure when parsing it . Not really that hard to do from a programmers point of view . 
 Open for group discussion 
 Based on the messages , there seems to be no support for combining the two maps together into a single map . I have therefore removed that from my working copy of the draft . There was one request for allowing option b ( where a single recipient can be represented as a single map entry rather than as an array of a single map ) . I have looked at code size , and there does not seem to be a lot of code associated with this option , but as there was no outcry for this option I have not included it . Unless others have opinions that they believe need to be expressed , I am closing this issue .
Implementations MUST be prepared to find an integer under this label
that does not correspond to the values 1 to 3.  If this is found then
the client MUST stop attempting to parse the structure and fail.  The
value of 0 is reserved and not to be used.  If the value of 0 is
found, then clients MUST fail processing the structure.
Implementations need to recognize that the set of values might be
extended at a later date, but they should not provide a security
service based on guesses of what is there.
Implementations MUST be prepared to find an integer in this field
that does not correspond to the values 1 to 3.  If this is found then
the client MUST stop attempting to process the structure and fail.
The value of 0 is reserved and not to be used.  If the value of 0 is
found, then clients MUST fail processing the structure.
Implementations need to recognize that the set of values might be
extended at a later date, but they should not provide a security
service based on guesses of what is there.
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 algorithms, keys, or
evaluation hints for the processing of the layer.  These two buckets
are available for use in all of the structures in this document
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 the necessary
functionality to provide the needed protection and thus the bucket
should not be used.
Both buckets are implemented as CBOR maps.  The map key is a 'label'
(label).  The value portion is dependent on the definition for the
label.  Both maps use the same set of label/value pairs.  The integer
range for labels has been divided into several sections with a
standard range, a private range, and a range that is dependent on the
algorithm selected.  The defined labels can be found in the 'COSE
Header Parameters' IANA registry (cose-header-key-table).
contains parameters about the current layer that are to be
cryptographically protected.  This bucket MUST NOT be used if it
is not going to be included in a cryptographic computation.  This
bucket is encoded in the message as a binary object.  This value
is obtained by CBOR encoding the protected map and wrapping it in
a bstr object.  This wrapping allows for the encoding of the
protected map to be transported with a greater chance that it will
not be altered in transit.  (Badly behaved intermediates could
decode and re-encode, but this will result in a failure to verify
unless the re-encoded byte string is identical to the decoded byte
string.)  This finesses the problem of all parties needing to be
able to do a common connical encoding.
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 in this
document 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 the
necessary functionality to provide the needed protection and thus the
bucket should not be used.
Both buckets are implemented as CBOR maps.  The map key is a 'label'
(label).  The value portion is dependent on the definition for the
label.  Both maps use the same set of label/value pairs.  The integer
and string values for labels has been divided into several sections
with a standard range, a private range, and a range that is dependent
on the algorithm selected.  The defined labels can be found in the
'COSE Header Parameters' IANA registry (cose-header-key-table).
contains parameters about the current layer that are to be
cryptographically protected.  This bucket MUST be empty if it is
not going to be included in a cryptographic computation.  This
bucket is encoded in the message as a binary object.  This value
is obtained by CBOR encoding the protected map and wrapping it in
a bstr object.  This wrapping allows for the encoding of the
protected map to be transported with a greater chance that it will
not be altered in transit.  (Badly behaved intermediates could
decode and re-encode, but this will result in a failure to verify
unless the re-encoded byte string is identical to the decoded byte
string.)  This finesses the problem of all parties needing to be
able to do a common connical encoding.
The presence of both buckets is optional, however the requirement
that the 'alg' parameter be present at each level effectively imposes
a requirement that one of the buckets will always be present.  The
parameters that go into the buckets come from the IANA "COSE Header
Parameters" (cose-header-key-table).  Some common parameters are
defined in the next section, but a number of parameters are defined
throughout this document.
This document defines a set of common header parameters.  A summary
of the parameters defined in this section can be found in Header-
Table.  This table should be consulted to determine the value of
label used as well as the type of the value.
The presence of both buckets is required.  The parameters that go
into the buckets come from the IANA "COSE Header Parameters" (cose-
header-key-table).  Some common parameters are defined in the next
section, but a number of parameters are defined throughout this
document.
This section defines a set of common header parameters.  A summary of
those parameters can be found in Header-Table.  This table should be
consulted to determine the value of label used as well as the type of
the value.
The header parameter values indicated by 'crit' can be processed
by either the security library code or by an application using a
security library, the only requirement is that the parameter is
processed.
This parameter is used to indicate the content type of the data in
the payload or ciphertext fields.  [CREF8] Integers are from the
XXXXX[CREF9] IANA registry table.  Strings are from the IANA
'mime-content types' registry.  Applications SHOULD provide this
parameter if the content structure is potentially ambiguous.
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'
field 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 generally 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 normally be placed in the unprotected headers
bucket.
The header parameter values indicated by 'crit' can be processed
by either the security library code or by an application using a
security library, the only requirement is that the parameter is
processed.  If the 'crit' value list includes a value for which
the parameter is not in the protected bucket, this is a fatal
error in processing the message.
This parameter is used to indicate the content type of the data in
the payload or ciphertext fields.  Integers are from the 'CoAP
Content-Formats' IANA registry table.  Strings are from the IANA
'Media Types' registry.  Applications SHOULD provide this
parameter if the content structure is potentially ambiguous.
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 generally 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.
A COSE Key structure is built on a CBOR map object.  The set of
common parameters that can appear in a COSE Key can be found in the
IANA registry 'COSE Key Common Parameter Registry' (cose-key-map-
registry).  Additional parameters defined for different key types can
be found in the IANA registry 'COSE Key Type Parameters' (cose-key-
parameter-registry).
A COSE Key structure is built on a CBOR map object.  The set of
common parameters that can appear in a COSE Key can be found in the
IANA registry 'COSE Key Common Parameter Registry' (cose-key-map-
registry).  Additional parameters defined for specific key types can
be found in the IANA registry 'COSE Key Type Parameters' (cose-key-
parameter-registry).
This parameter is used to identify the family of keys for this
structure, and thus the set of key type specific parameters to be
found.  The set of values can be found in table_key_types.
This parameter is used to identify the family of keys for this
structure, and thus the set of key type specific parameters to be
found.  The set of values can be found in table_key_types.  This
parameter MUST be present in a key object.
Only the 'kty' field MUST be present in a key object.  All other
parameters can be omitted if their behavior is not needed.
The ECDSA signature algorithm is parameterized with a hash function
(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
are used.
The ECDSA signature algorithm is parameterized with a hash function
(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
are used.
The security strength of the signature is no greater than the minimum
of the security strength associated with the bit length of the key
and the security strength of the hash function.  When a hash function
is used that has greater security than is provided by the length of
the key, the signature algorithm uses the leftmost key length bits of
the hash function output.
System which have poor random number generation can leak their keys
by signing two messages with the same value of 'k'.  RFC6979 provides
a method to deal with this problem by making 'k' be deterministic
based on the message content rather than randomly generated.
Applications which specify ECDSA should evaluate the ability to get
good random number generation and recommend this when it is not
possible.  Note: Use of this technique even when good random number
generation exists may still be a good idea.
The security strength of the signature is no greater than the minimum
of the security strength associated with the bit length of the key
and the security strength of the hash function.
System which have poor random number generation can leak their keys
by signing two different messages with the same value of 'k'.
RFC6979 provides a method to deal with this problem by making 'k' be
deterministic based on the message content rather than randomly
generated.  Applications which specify ECDSA should evaluate the
ability to get good random number generation and require this when it
is not possible.  Note: Use of this technique a good idea even when
good random number generation exists.  Doing so both reduces the
possiblity of having the same value of 'k' in two signature
operations, but allows for reproducable signature values which helps
testing.
ChaCha20 and Poly1305 combined together is a new AEAD mode that is
defined in RFC7539.  This is a new mode defined to be a cipher which
is not AES and thus would not suffer from any future weaknesses found
in AES.  These cryptographic functions are designed to be fast in
software only implementations.
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
which is not AES and thus would not suffer from any future weaknesses
found in AES.  These cryptographic functions are designed to be fast
in software only implementations.
The context information structure refers to PartyU and PartyV as the
two parties which are doing the key derivation.  Unless the
application protocol defines differently, we assign PartyU to the
entity that is creating the message and PartyV to the entity that is
receiving the message.  This is because we are assuming a set of
stand alone store and forward messaging processes.  In SP800-56A,
PartyU is the initiator and PartyV is the responder.  The
specification is written with the idea of on-line protocols rather
than store and forward protocols as the main consumer.
The context information structure refers to PartyU and PartyV as the
two parties which are doing the key derivation.  Unless the
application protocol defines differently, we assign PartyU to the
entity that is creating the message and PartyV to the entity that is
receiving the message.  This is because we are assuming a set of
standalone store and forward messaging processes.  In SP800-56A,
PartyU is the initiator and PartyV is the responder.  The
specification is written with the idea of on-line protocols rather
than store and forward protocols as the main consumer.
Application protocols are free to define the roles differently.  For
example, they could assign the PartyU role to the entity that
initiates the connection and allow directly sending multiple messages
over the line without changing the role information.
Application protocols are free to define the roles differently.  For
example, they could assign the PartyU role to the entity that
initiates the connection and allow directly sending multiple messages
over the connection in both directions without changing the role
information.
The AES Key Wrapping algorithm is defined in RFC3394.  This algorithm
uses an AES key to wrap a value that is a multiple of 64-bits, as
such it can be used to wrap a key for any of the content encryption
algorithms defined in this document.  [CREF14] The algorithm 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 public
parameters that vary on a per invocation basis.
The AES Key Wrapping algorithm is defined in RFC3394.  This algorithm
uses an AES key to wrap a value that is a multiple of 64-bits, as
such it can be used to wrap a key for any of the content encryption
algorithms defined in this document.  [CREF11] The algorithm 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 public
parameters that vary on a per invocation basis.
It is highly recommended that checks on the key length be done before
starting a decryption operation.  One potential denial of service
operation is to provide encrypted objects using either abnormally
long or oddly sized RSA modulus values.  Implementations SHOULD be
able to encrypt and decrypt with modulus between 2048 and 16K bits in
length.[CREF15] Applications can impose additional restrictions on
the length of the modulus.
It is highly recommended that checks on the key length be done before
starting a decryption operation.  One potential denial of service
operation is to provide encrypted objects using either abnormally
long or oddly sized RSA modulus values.  Implementations SHOULD be
able to encrypt and decrypt with modulus between 2048 and 16K bits in
length.[CREF12] Applications can impose additional restrictions on
the length of the modulus.
contains an identifier of the curve to be used with the key.
[CREF18] The curves defined in this document for this key type can
be found in table-ec-curves.  Other curves may be registered in
the future and private curves can be used as well.
contains an identifier of the curve to be used with the key.
[CREF15] The curves defined in this document for this key type can
be found in table-ec-curves.  Other curves may be registered in
the future and private curves can be used as well.
This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry.  [CREF21] These
media types are used to indicate that the content is a COSE_MSG.
This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry.  [CREF18] These
media types are used to indicate that the content is a COSE_MSG.