Draft: draft-ietf-cose-msg

Commentary: Add external data to signed after discussions with ACE people General cleanup to try and tighten language
contains attributes about the layer that are not cryptographically
protected.
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.  This field using the integer
'1' for the label.  The value is taken from the 'COSE Algorithm
Registry' (see IANA-Alg-Registry).
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.
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.
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 indicate the content type of the data in the
payload or ciphertext fields.  The field uses the integer of '3'
for the label.  The value can be either an integer or a string.
[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.  This field uses the integer
value of '4' for the label.  The value of field is the CBOR 'bstr'
type.  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.
This table contains a list of all of the generic header parameters
defined in document.  In the table is the data value type to be used
for CBOR as well as the integer value that can be used as a
replacement for the name in order to further decrease the size of the
sent item.
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.
contains additional information to be authenticated by the
signature.  The field holds data about the signature operation.
The field MUST NOT hold attributes about the payload being signed.
The content is a CBOR map of attributes that is encoded to a byte
stream.  At least one of protected and unprotected MUST be
present.
contains attributes about the signature that are not protected by
the signature.  This field MUST NOT contain attributes about the
payload being signed.  At least one of protected and unprotected
MUST be present.
One of the features that we supply in the COSE document is the
ability for applications to provide additional data to be
authenticated as part of the security, but that is not carried as
part of the COSE object.  The primary reason for supporting this can
be seen by looking at the CoAP message struture RFC7252 where the
facility exists for options to be carried before the payload.  An
example of data that can be placed in this location would be
transaction ids and nonces to check for replay protection.  If the
data is in the options section, then it is available for routers to
help in performing the replay detection and prevention.  However, it
may also be desired to protect these values so that they cannot be
modified in transit.  This is the purpose of the externally supplied
data field.
If multiple items are included, care needs to be taken that data
cannot bleed between the items.  This is usually addressed by
making fields fixed width and/or encoding the length of the field.
Using options from CoAP as an example, these fields use a TLV
structure so they can be concatenated without any problems.
If multiple items are included, a defined order for the items
needs to be defined.  Using options from CoAP as an example, an
application could state that the fields are to be ordered by the
option number.
contains the information about the plain text or encryption
process that is to be integrity protected.  The field is encoded
in CBOR as a 'bstr'.  The contents of the protected field is a
CBOR map of the protected data names and values.  The map is CBOR
encoded before placing it into the bstr.  Only values associated
with the current cipher text are to be placed in this location
even if the value would apply to multiple recipient structures.
contains information about the plain text that is not integrity
protected.  Only values associated with the current cipher text
are to be placed in this location even if the value would apply to
multiple recipient structures.
In this section we describe the structure and methods to be used when
doing MAC authentication in COSE.  JOSE used a variant of the
signature structure for doing MAC operations and it is restricted to
using a single pre-shared secret to do the authentication.  [CREF14]
This document allows for the use of all of the same methods of key
management as are allowed for encryption.
In this section we describe the structure and methods to be used when
doing MAC authentication in COSE.  This document allows for the use
of all of the same methods of key management as are allowed for
encryption.
contains attributes about the payload that are to be protected by
the MAC.  An example of such an attribute would be the content
type ('cty') attribute.  The content is a CBOR map of attributes
that is encoded to a byte stream.  This field MUST NOT contain
attributes about the recipient, even if those attributes are
common across multiple recipients.  At least one of protected and
unprotected MUST be present.
contains attributes about the payload that are not protected by
the MAC.  An example of such an attribute would be the content
type ('cty') attribute.  This field MUST NOT contain attributes
about a recipient, even if the attributes are common across
multiple recipients.  At least one of protected and unprotected
MUST be present.
If the application has supplied external authenticated data,
encode it as a binary value and place in the MAC_structure.  If
there is no external authenticated data, then use a zero length
'bstr'.
There are only a few changes between JOSE and COSE for how keys are
formatted.  As with JOSE, COSE uses a map to contain the elements of
a key.  Those values, which in JOSE are base64url encoded because
they are binary values, are encoded as bstr values in COSE.
The element "kty" is a required element in a COSE_Key map.  All other
elements are optional and not all of the elements listed in RFC7517
or RFC7518 have been listed here even though they can all appear in a
COSE_Key map.
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.
The element "kty" is a required element in a COSE_Key map.
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.  [CREF18]
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.  [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.
In direct encryption mode, a shared secret between the sender and the
recipient is used as the key.  [CREF19] 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.  [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.
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.  [CREF20] 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.  [CREF16] 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.[CREF21] 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.[CREF17] Applications can impose additional restrictions on
the length of the modulus.
contains an identifier of the curve to be used with the key.
[CREF26] 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.
[CREF22] 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.  [CREF30] 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.  [CREF26] These
media types are used to indicate that the content is a COSE_MSG.