Draft: draft-ietf-cose-msg

Commentary: Doing a strict read through following some time away from the document .
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.
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.  When present,
this parameter MUST be placed in the protected header bucket.
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 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.  [CREF4] Strings are from
the IANA 'Media Types' registry.  Applications SHOULD provide this
parameter if the content structure is potentially ambiguous.
This parameter holds a counter signature value.  Counter
signatures provide a method of having a second party sign some
data.  The counter signature can occur as an unprotected attribute
in any of the following structures: COSE_Sign, COSE_signature,
COSE_enveloped, COSE_recipient, COSE_encryptedData, COSE_mac.
These structures all have the same basic structure so that a
consistent calculation of the counter signature can be computed.
Details on computing counter signatures are found in
counter_signature.
This parameter holds a counter signature value.  Counter
signatures provide a method of having a second party sign some
data.  The counter signature can occur as an unprotected attribute
in any of the following structures: COSE_Sign, COSE_signature,
COSE_Enveloped, COSE_recipient, COSE_EnvelopededData, COSE_mac.
These structures all have the same basic structure so that a
consistent calculation of the counter signature can be computed.
Details on computing counter signatures are found in
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.  Examples of
parameters about the content would be the type of content, when the
content was created, and who created the content.  [CREF4] 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 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.  [CREF5] 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.
A COSE Signing Message is divided into two parts.  The CBOR object
that carries the body and information about the body is called the
COSE_Sign structure.  The CBOR object that carries the signature and
information about the signature is called the COSE_Signature
structure.  Examples of COSE Signing Messages can be found in
SignedExamples.
is an array of signature items.  Each of these items uses the
COSE_signature structure for its representation.
is an array of signatures.  Each signature is represented as a
COSE_signature structure.
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 structure RFC7252 where the
facility exists for options to be carried before the payload.
[CREF5] 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.
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 structure RFC7252 where the
facility exists for options to be carried before the payload.
[CREF6] 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, 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 RFC7252 as an example, these fields use a
TLV structure so they can be concatenated without any problems.
Create a CBOR array and populate it with the appropriate fields.
For body_protected and sign_protected, if the fields are not
present in their corresponding maps, a bstr of length zero is
used.
Create a CBOR array and populate it with the appropriate fields.
For body_protected and sign_protected, if the map is empty, a bstr
of length zero is used.
Create a Sig_structure object and populate it with the appropriate
fields.  For body_protected and sign_protected, if the fields are
not present in their corresponding maps, a bstr of length zero is
used.
Call the signature verification algorithm passing in K (the key to
verify with), alg (the algorithm to sign with), ToBeSigned (the
value to sign), and sig (the signature to be verified).
Create a Sig_structure object and populate it with the appropriate
fields.  For body_protected and sign_protected, if the map is
empty, a bstr of length zero is used.
Call the signature verification algorithm passing in K (the key to
verify with), alg (the algorithm used sign with), ToBeSigned (the
value to sign), and sig (the signature to be verified).
Counter signatures provide a method of having a different signature
occur on some piece of content.  This is normally used to provide a
signature on a signature allowing for a proof that a signature
existed at a given time.  In this document we allow for counter
signatures to exist in a greater number of environments.  A counter
signature can exist, for example, on a COSE_encryptedData object and
allow for a signature to be present on the encrypted content of a
message.
The creation and validation of counter signatures over the different
items relies on the fact that the structure all of our objects have
the same structure.  The first element may be a message type, this is
followed by 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_encryptedData structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
While one can create a counter signature for a COSE_Sign structure,
there is not much of a point to doing so.  It is equivalent to create
a new COSE_signature structure and placing it in the signatures
array.  It is strongly suggested that it not be done, but it is not
banned.
COSE supports two different encryption structures.  COSE_enveloped is
used when the key needs to be explicitly identified.  This structure
supports the use of recipient structures to allow for random content
encryption keys to be used.  COSE_encrypted is used when a recipient
structure is not needed because the key to be used is known
implicitly.
Counter signatures provide a method of having a different signature
occur on some piece of content.  This is normally used to provide a
signature on a signature allowing for a proof that a signature
existed at a given time (i.e. a Timestamp).  In this document we
allow for counter signatures to exist in a greater number of
environments.  As an example, it is possible to place a counter
signature in the unprotected attributes of a COSE_EnvelopededData
object.  This would allow for an intermediary to either verify that
the encrypted byte stream has not been modified, without being able
to decrypt it.  Or for the intermediary to assert that an encrypted
byte stream either existed at a given time or passed through it in
terms of routing (i.e. a proxy signature).
An example of a proxy signature on a signature can be found in Sig-
03.  An example of a proxy signature on an encryption object can be
found in Enc-03.
The creation and validation of counter signatures over the different
items relies on the fact that the structure all of our 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_EnvelopededData structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
COSE supports two different encryption structures.  COSE_Enveloped is
used when the key needs to be explicitly identified.  This structure
supports the use of recipient structures to allow for random content
encryption keys to be used.  COSE_Envelopeded is used when a
recipient structure is not needed because the key to be used is known
implicitly.
the recipient encryption algorithm.
In COSE, 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.
In COSE, 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 CEK is the same as the identified previously distributed
symmetric key or derived from a previously distributed secret.
The CEK is encrypted using a previously distributed symmetric key-
encryption key.
the CEK is encrypted in a key-encryption key that is derived from
a password.
The CEK is the same as the identified previously distributed
symmetric key or derived from a previously distributed secret.  No
CEK is transported in the message.
The CEK is encrypted using a previously distributed symmetric KEK.
The CEK is encrypted with the recipient's public key.
The CEK is encrypted in a KEK that is derived from a password.
The encrypted structure does not have the ability to specify
recipients of the message.  The structure assumes that the recipient
of the object will already know the identity of the key to be used in
order to decrypt the message.  If a key needs to be identified to the
recipient, the enveloped structure is used.
The encrypted structure does not have the ability to specify
recipients of the message.  The structure assumes that the recipient
of the object will already know the identity of the key to be used in
order to decrypt the message.  If a key needs to be identified to the
recipient, the enveloped structure ought to be used.
The structure defined to hold an encrypted message is COSE_Encrypted.
Examples of encrypted messages can be found in EncryptedExamples.
contains the encrypted plain text.  If the ciphertext is to be
transported independently of the control information about the
encryption process (i.e. detached content) then the field is
encoded as a null object.
The encryption algorithm for AEAD algorithms is fairly simple.  In
order to get a consistent encoding of the data to be authenticated,
the Enc_structure is used to have canonical form of the AAD.
Copy the protected header field from the message to be sent.
contains the encrypted plain text.  If the ciphertext is to be
transported independently of the control information about the
encryption process (i.e. detached content) then the field is
encoded as a null value.
The encryption algorithm for AEAD algorithms is fairly simple.  In
order to get a consistent encoding of the data to be authenticated,
the Enc_structure is used to have canonical form of the AAD.  The
Enc_structure is a CBOR array.
Copy the protected header field from the message to be sent to the
first location in the Enc_structure.
The MAC message uses two structures, the COSE_Mac structure defined
in this section for carrying the body and the COSE_recipient
structure (EnvelopedData) to hold the key used for the MAC
computation.  Examples of MAC messages can be found in MacExamples.
In order to get a consistent encoding of the data to be
authenticated, the MAC_structure is used to have a canonical form.
The MAC_structure is a CBOR array.
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.  Implementations MUST
verify that the key type is appropriate for the algorithm being
processed.  The key type MUST be included as part of a trust
decision process.
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 defined in this document can be found in
table_key_types.  This parameter MUST be present in a key object.
Implementations MUST verify that the key type is appropriate for
the algorithm being processed.  The key type MUST be included as
part of a trust decision process.
System which have poor random number generation can leak their keys
by signing two different messages with the same value 'k' (the per-
message random value).  RFC6979 provides a method to deal with this
problem by making 'k' be deterministic based on the message content
rather than randomly generated.  Applications that 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 possibility of having the same value of 'k' in two
signature operations, but allows for reproducible signature values
which helps testing.
System which have poor random number generation can leak their keys
by signing two different messages with the same value 'k' (the per-
message random value).  RFC6979 provides a method to deal with this
problem by making 'k' be deterministic based on the message content
rather than randomly generated.  Applications that 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 possibility of having
the same value of 'k' in two signature operations, but allows for
reproducible signature values which helps testing.
Content Encryption Algorithms provide data confidentiality for
potentially large blocks of data using a symmetric key.  They provide
either no or very limited data origination.  (One cannot, for
example, be used to prove the identity of the sender to a third
party.)  The ability to provide data origination is linked to how the
symmetric key is obtained.
Content Encryption Algorithms provide data confidentiality for
potentially large blocks of data using a symmetric key.  They provide
integrity on the data that was encrypted, however they provide either
no or very limited data origination.  (One cannot, for example, be
used to prove the identity of the sender to a third party.)  The
ability to provide data origination is linked to how the symmetric
key is obtained.
The GCM mode is parameterized with by the size of the authentication
tag.  The size of the authentication tag is limited to a small set of
values.  For this document however, the size of the authentication
tag is fixed at 128 bits.
The GCM mode is parameterized with by the size of the authentication
tag and the size of the nonce.  This document fixes the size of the
nonce at 96-bits.  The size of the authentication tag is limited to a
small set of values.  For this document however, the size of the
authentication tag is fixed at 128 bits.
Consideration was given to supporting smaller tag values, the
constrained community would desire tag sizes in the 64-bit range.
Doing show drastically changes both the maximum messages size
(generally not an issue) and the number of times that a key can be
used.  Given that CCM is the usual mode for constrained environments
restricted modes are not supported.
hash function - The underlying hash function to be used in the
HKDF algorithm.  The hash function is encoded into the HKDF
algorithm selection.
PRF - The underlying pseudo-random function to be used in the HKDF
algorithm.  The PRF is encoded into the HKDF algorithm selection.
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 use of a transaction identifier, either in one of the
supplemental fields or as the salt if one is using HKDF, ensures that
a unique key is generated for each set of transactions.  Combining
nonce fields with the transaction identifier provides a method so
that a different key is used for each message in each direction.
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.  It is still reommended that different keys be derived
in each direction to avoid reflection problems.
Fields can be define by the application.  This is commonly used to
assign names to parties.
Fields can be defined by usage of the output.  Examples of this
are the algorithm and key size that are being generated.
The identity value supplied will be integrity checked as part
of the key derivation process.  If the identity string is
wrong, then the wrong key will be created.
M00TODO: Copy down from PartyUInfo when that text is ready.
This contains the identity information for party V.  The
identities can be assigned in one of two manners.  Firstly, a
protocol can assign identities based on roles.  For example,
the roles of "client" and "server" may be assigned to different
entities in the protocol.  Each entity would then use the
correct label for the data they send or receive.  The second
way is for a protocol to assign identities is to use a name
based on a naming system (i.e.  DNS, X.509 names).
We define an algorithm parameter 'PartyU identity' that can be
used to carry identity information in the message.  However,
identity information is often known as part of the protocol and
can thus be inferred rather than made explicit.  If identity
information is carried in the message, applications SHOULD have
a way of validating the supplied identity information.  The
identity information does not need to be specified and can be
left as 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.
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 other information that is defined by the
protocol.
This item is optional and can be absent.
This field contains private information that is mutually known
information.  An example of this information would be a pre-
existing shared secret.  The field is optional and will only be
present if the application defines a structure for this
information.  Applications that define this SHOULD use CBOR to
encode the data so that types and lengths are correctly include.
This field contains private information that is mutually known
information.  An example of this information would be a pre-
existing shared secret.  The field is optional and will only be
present if the application defines a structure for this
information.  Applications that define this SHOULD use CBOR to
encode the data so that types and lengths are correctly included.
The 'protected' field MUST be a zero length item when it is not
used in the computation of the content key.
The 'protected' field MUST be a zero length item unless it is used
in the computation of the content key.
This recipient algorithm is the simplest, the supplied key is
directly used as the key for the next layer down in the message.
There are no algorithm parameters defined for this algorithm.  The
algorithm identifier value is assigned in table-direct.
This recipient algorithm is the simplest, the identified key is
directly used as the key for the next layer down in the message.
There are no algorithm parameters defined for this algorithm.  The
algorithm identifier value is assigned in table-direct.
These recipient algorithms take a common shared secret between the
two parties and applies the HKDF function (HKDF) using the context
structure defined in context to transform the shared secret into the
necessary key.  Either the 'salt' parameter of HKDF or the partyU
'nonce' parameter of the context structure MUST be present.  This
parameter can be generated either randomly or deterministically.  The
requirement is that it be a unique value for the key pair in
question.
These recipient algorithms take a common shared secret between the
two parties and applies the HKDF function (HKDF) using the context
structure defined in context to transform the shared secret into the
necessary key.  The 'protected' field can be of non-zero length.  The
'protected' field is copied into the SuppPubInfo.protected field of
the context structure.  Either the 'salt' parameter of HKDF or the
partyU 'nonce' parameter of the context structure MUST be present.
The salt/nonce parameter can be generated either randomly or
deterministically.  The requirement is that it be a unique value for
the key pair in question.
In key wrapping mode, the CEK is randomly generated and that key is
then encrypted by a shared secret between the sender and the
recipient.  All of the currently defined key wrapping algorithms for
JOSE (and thus for COSE) are AE algorithms.  Key wrapping mode is
considered to be superior to direct encryption if the system has any
capability for doing random key generation.  This is because the
shared key is used to wrap random data rather than data has some
degree of organization and may in fact be repeating the same content.
In key wrapping mode, the CEK is randomly generated and that key is
then encrypted by a shared secret between the sender and the
recipient.  All of the currently defined key wrapping algorithms for
COSE are AE algorithms.  Key wrapping mode is considered to be
superior to direct encryption if the system has any capability for
doing random key generation.  This is because the shared key is used
to wrap random data rather than data has some degree of organization
and may in fact be repeating the same content.  The use of Key
Wrapping loses the weak data origination that is provided by the
direct encryption algorithms.
The shared secret need to have some method to be regularly updated
over time.  The shared secret is forming the basis of trust, although
not used directly it should still be subject to scheduled rotation.
The shared secret need to have some method to be regularly updated
over time.  The shared secret is the basis of trust.
Curve Type/Curve: The curve selected controls not only the size of
the shared secret, but the mathematics for computing the shared
secret.  The curve selected also controls how a point in the curve
is represented and what happens for the identity points on the
curve.  In this specification, we allow for a number of different
curves to be used.  The curves are defined in table-ec-curves.
Since the only the math is changed by changing the curve, the
curve is not fixed for any of the algorithm identifiers we define.
Instead, it is defined by the points used.
Curve Type/Curve: The curve selected controls not only the size of
the shared secret, but the mathematics for computing the shared
secret.  The curve selected also controls how a point in the curve
is represented and what happens for the identity points on the
curve.  In this specification, we allow for a number of different
curves to be used.  A set of curves are defined in table-ec-
curves.
Since the only the math is changed by changing the curve, the
curve is not fixed for any of the algorithm identifiers we define.
Instead, it is defined by the points used.
All parsers used SHOULD fail on both parsing and generation if the
same label is used twice as a key for the same map.
One of the issues that needs to be addressed is a requirement that a
standard specify a set of algorithms that are required to be
implemented.  [CREF8] This is done to promote interoperability as it
provides a minimal set of algorithms that all devices can be sure
will exist at both ends.  However, we have elected not to specify a
set of mandatory algorithms in this document.
Applications MUST not generate messages with the same label used
twice as a key in a single map.  Applications MUST not parse and
process messages with the same label used twice as a key in a
single map.  Applications can enforce the parse and process
requirement by using parsers that will fail the parse step or by
using parsers that will pass all keys to the application and the
application can perform the check for duplicate keys.
One of the issues that needs to be addressed is a requirement that a
standard specify a set of algorithms that are required to be
implemented.  [CREF10] This is done to promote interoperability as it
provides a minimal set of algorithms that all devices can be sure
will exist at both ends.  However, we have elected not to specify a
set of mandatory algorithms in this document.