Draft: draft-ietf-cose-msg

Commentary: Do an editing pass for consistency of terms Point to the new issues tracker project .
Signed messages separate the concept of protected and unprotected
attributes that are for the content and the signature.
Signed messages separate the concept of protected and unprotected
parameters that are for the content and the signature.
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 present for 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 element
is not 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 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 Labels' IANA registry (cose-header-key-table.
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 attributes about the current layer that are not
cryptographically protected.
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 always be present.  The
parameters that go into the buckets come from the IANA "COSE Header
Labels" (cose-header-key-table).  The common parameters are defined
in the next section, but a number of parameters are defined
throughout this document.
contains parameters about the current layer that are not
cryptographically protected.
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 field is used to indicate the algorithm used for the security
processing.  This field MUST be present at each level of a signed,
encrypted or authenticated message.  The value is taken from the
'COSE Algorithm Registry' (see IANA-Alg-Registry).
This field is used to ensure that applications will take
appropriate action based on the values found.  The field is used
to indicate which protected header labels an application that is
processing a message is required to understand.  This field uses
the integer '2' for the label.  The value is an array of COSE
Header Labels.  When present, this MUST be placed in the protected
header bucket.
This parameter is used to indicate the algorithm used for the
security processing.  This parameter MUST be present at each level
of a signed, encrypted or authenticated message.  The value is
taken from the 'COSE Algorithm Registry' (see IANA-Alg-Registry).
This parameter is used to ensure that applications will take
appropriate action based on the values found.  The parameter is
used to indicate which protected header labels an application that
is processing a message is required to understand.  The value is
an array of COSE Header Labels.  When present, this parameter MUST
be placed in the protected header bucket.
The header 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 field is processed.
This field 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
field if the content structure is potentially ambiguous.
This field one of the ways that can be used to find the key to be
used.  This value can be 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'
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.
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 signature structure allows for one or more signatures to be
applied to a message payload.  There are provisions for attributes
about the content and attributes about the signature to be carried
along with the signature itself.  These attributes may be
authenticated by the signature, or just present.  Examples of
attributes about the content would be the type of content, when the
content was created, and who created the content.  Examples of
attributes about the signature would be the algorithm and key used to
create the signature, when the signature was created, and counter-
signatures.
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.  Examples of
parameters about the content would be the type of content, when the
content was created, and who created the content.  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.
key-management-algs provides details on a number of different key
management algorithms and discusses which elements need to be present
for each of the key management techniques.
key-management-algs provides details on a number of different key
management algorithms and discusses which parameters need to be
present for each of the key management techniques.
Create a MAC_structure and copy the protected and payload elements
from the COSE_mac structure.
Create a MAC_structure and copy the protected and payload fields
from the COSE_mac structure.
A COSE Key structure is built on a CBOR map object.  The set of
common attributes that can appear in a COSE Key can be found in the
IANA registry 'COSE Key Map Registry' (cose-key-map-registry).
Additional attributes defined for different key types can be found in
the IANA registry 'COSE Key Parameters' (cose-key-parameter-
registry).
A COSE Key Set uses a CBOR array object as it's underlying type.  The
values of the array elements are COSE Keys.  A Key Set MUST have at
least one element in the array.
This document defines a set of common map elements for a COSE Key
object.  table-key-labels provides a summary of the elements defined
in this section.  There are also a set of map elements that are
defined for a specific key type.  Key specific elements can be found
in Key-specific-labels.
This field is used to identify the family of keys for this
structure, and thus the set of fields to be found.  The set of
values can be found in table_key_types.
This field is used to restrict the algorithms that are to be used
with this key.  If this field is present in the key structure, the
application MUST verify that this algorithm matches the algorithm
for which the key is being used.  If the algorthms do not match,
then this key object MUST NOT be used to perform the cryptographic
operation.  Note that the same key can be in a different key
structure with a different or no algorithm specified, however this
is considered to be a poor security practice.
This field is used to give an identifier for a key.  The
identifier is not structured and can be anything from a user
provided string to a value computed on the public portion of the
key.  This field is intended for matching against a 'kid' field in
a message in order to filter down the set of keys that need to be
checked.
This field is defined to restrict the set of operations that a key
is to be used for.  The value of the field is an array of values
from table-key-ops.
Only the 'kty' field MUST be present in a key object.  All other
members may be omitted if their behavior is not needed.
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).
This document defines a set of common parameters for a COSE Key
object.  table-key-labels provides a summary of the parameters
defined in this section.  There are also a set of parameters that are
defined for a specific key type.  Key type specific parameters can be
found in Key-specific-labels.
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 restrict the algorithms that are to be
used with this key.  If this parameter is present in the key
structure, the application MUST verify that this algorithm matches
the algorithm for which the key is being used.  If the algorthms
do not match, then this key object MUST NOT be used to perform the
cryptographic operation.  Note that the same key can be in a
different key structure with a different or no algorithm
specified, however this is considered to be a poor security
practice.
This parameter is used to give an identifier for a key.  The
identifier is not structured and can be anything from a user
provided string to a value computed on the public portion of the
key.  This field is intended for matching against a 'kid'
parameter in a message in order to filter down the set of keys
that need to be checked.
This parameter is defined to restrict the set of operations that a
key is to be used for.  The value of the field is an array of
values from table-key-ops.
Only the 'kty' field MUST be present in a key object.  All other
parameters can be omitted if their behavior is not needed.
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 keyLength bits of
the hash function output.
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.
This contains a one time nonce value.  The nonce can either be
implicit from the protocol or carried as a value in the
unprotected headers.  [CREF14]
We define an algorithm parameter 'PartyU nonce' that can be
used to carry this value in the message However, the nonce
value could be determined by the application and the value
determined from elsewhere.
This item is optional and can be absent.
This contains a one time nonce value.  The nonce can either be
implicit from the protocol or carried as a value in the
unprotected headers.  [CREF15]
We define an algorithm parameter 'PartyU nonce' that can be
used to carry this value in the message However, the nonce
value could be determined by the application and the value
determined from elsewhere.
This item is optional and can be absent.
In direct encryption mode, a shared secret between the sender and the
recipient is used as the key.  [CREF15] When direct encryption mode
is used, it MUST be the only mode used on the message.  It is a
massive security leak to have both direct encryption and a different
key management mode on the same message.
In direct encryption mode, a shared secret between the sender and the
recipient is used as the key.  When direct encryption mode is used,
it MUST be the only mode used on the message.  It is a massive
security leak to have both direct encryption and a different key
management mode on the same message.
It is requested that IANA create a new registry entitled "COSE Header
Labels".
It is requested that IANA create a new registry entitled "COSE Header
Parameters".
It is requested that IANA create a new registry entitled "COSE Key
Map Registry".
It is requested that IANA create a new registry entitled "COSE Key
Common Parameter" Registry.
It is requested that IANA create a new registry "COSE Key
Parameters".
It is requested that IANA create a new registry "COSE Key Type
Parameters".