Draft: draft-ietf-cose-msg

Commentary: ( Sorry , I messed this slightly up -- this also contains the cddl - use changes . )
As well as the prose description, a version of a CBOR grammar is
presented in CDDL.  Since CDDL has not be published as an RFC, this
grammar may not work with the final version of CDDL.  The CDDL
grammar is informational, the prose description is normative.
As well as the prose description, a version of a CBOR grammar is
presented in CDDL.  Since CDDL has not been published as an RFC, this
grammar may not work with the final version of CDDL.  The CDDL
grammar is informational, the prose description is normative.
In JSON, maps are called objects and only have one kind of map key: a
string.  In COSE, we use strings, negative integers and unsigned
integers as map keys.  The integers are used for compactness of
encoding and easy comparison.  Since the work "key" is mainly used in
its other meaning, as a cryptographic key, we use the term "label"
for this usage as a map key.
In JSON, maps are called objects and only have one kind of map key: a
string.  In COSE, we use strings, negative integers and unsigned
integers as map keys.  The integers are used for compactness of
encoding and easy comparison.  Since the word "key" is mainly used in
its other meaning, as a cryptographic key, we use the term "label"
for this usage as a map key.
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.
When a COSE object is carried as a CoAP payload, the CoAP Content-
Format Option can be used to identify the message content.  The
CoAP Content-Format values can be found in CoAP_content_type.  The
CBOR tag for the message structure is not required as each
security message is uniquely identified.
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 holds the Initialization Vector (IV) value.  For
some symmetric encryption algorithms this may be referred to as a
nonce.  As the IV is authenticated by encryption process, it can
be placed in the unprotected header 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, so all of the keys may 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 holds the Initialization Vector (IV) value.  For
some symmetric encryption algorithms this may be referred to as a
nonce.  As the IV is authenticated by the encryption process, it
can be placed in the unprotected header bucket.
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_Sign1,
COSE_Signature, COSE_Encrypt, COSE_recipient, COSE_Encrypt1,
COSE_Mac and COSE_Mac0.  These structures all have the same
beginning elements 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 one or more counter signature values.
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_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient,
COSE_Encrypt1, COSE_Mac and COSE_Mac0.  These structures all have
the same beginning elements so that a consistent calculation of
the counter signature can be computed.  Details on computing
counter signatures are found in counter_signature.
A COSE Signed 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 Signed Messages can be found in
SignedExamples.
A COSE Signed Message is defined in 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 Signed Messages can be found in
SignedExamples.
contains the serialized content to be signed.  If the payload is
not present in the message, the application is required to supply
the payload separately.  The payload is wrapped in a bstr to
ensure that it is transported without changes.  If the payload is
transported separately (i.e. detached content), then a nil CBOR
object is placed in this location and it is the responsibility of
the application to ensure that it will be transported without
changes.
contains the serialized content to be signed.  If the payload is
not present in the message, the application is required to supply
the payload separately.  The payload is wrapped in a bstr to
ensure that it is transported without changes.  If the payload is
transported separately ("detached content"), then a nil CBOR
object is placed in this location and it is the responsibility of
the application to ensure that it will be transported without
changes.
Create a Enc_structure and populate it with the appropriate
fields.
Create an Enc_structure and populate it with the appropriate
fields.
Extreme care needs to be taken when using a Base IV in an
application.  Many encryption algorithms loose security if the
same IV is used twice.
Extreme care needs to be taken when using a Base IV in an
application.  Many encryption algorithms lose security if the same
IV is used twice.
If the 'alg' field present, it MUST match the ECDSA signature
algorithm being used.
If the 'alg' field is present, it MUST match the ECDSA signature
algorithm being used.
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 and allows for
reproducible signature values which helps testing.
Note: Use of this technique is 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 and allows
for reproducible signature values which helps testing.
The algorithm defined in this document can be found in table-hmac.
Some recipient algorithms carry the key while others derive a key
from secret data.  For those algorithms that carry the key (i.e.
AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the
underlying hash function.  For those algorithms that derive the key
(i.e.  ECDH), the derived key MUST be the same size as the underlying
hash function.
The algorithms defined in this document can be found in table-hmac.
Some recipient algorithms carry the key while others derive a key
from secret data.  For those algorithms that carry the key (such as
AES-KeyWrap), the size of the HMAC key SHOULD be the same size as the
underlying hash function.  For those algorithms that derive the key
(such as ECDH), the derived key MUST be the same size as the
underlying hash function.
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.
The GCM mode is parameterized 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.
We define a matrix of algorithms in this document over the values of
L and M.  Constrained devices are usually operating in situations
where they use short messages and want to avoid doing recipient
specific cryptographic operations.  This favors smaller values of
both L and M.  Less constrained devices do will want to be able to
user larger messages and are more willing to generate new keys for
every operation.  This favors larger values of L and M.
limits messages to 2^16 bytes (64 KiB) in length.  This
sufficiently long for messages in the constrained world.  The
nonce length is 13 bytes allowing for 2^(13*8) possible values of
the nonce without repeating.
We define a matrix of algorithms in this document over the values of
L and M.  Constrained devices are usually operating in situations
where they use short messages and want to avoid doing recipient
specific cryptographic operations.  This favors smaller values of
both L and M.  Less constrained devices will want to be able to user
larger messages and are more willing to generate new keys for every
operation.  This favors larger values of L and M.
limits messages to 2^16 bytes (64 KiB) in length.  This is
sufficiently long for messages in the constrained world.  The
nonce length is 13 bytes allowing for 2^(13*8) possible values of
the nonce without repeating.
The same KDF function can be setup to deal with the first two types
of secrets different.  The KDF function defined in HKDF is such a
function.  This is reflected in the set of algorithms defined for
HKDF.
The same KDF function can be setup to deal with the first two types
of secrets in a different way.  The KDF function defined in HKDF is
such a function.  This is reflected in the set of algorithms defined
for HKDF.
The headers SHOULD identify the senders key for the static-static
versions and MUST contain the senders ephemeral key for the
ephemeral-static versions.
The headers SHOULD identify the sender's key for the static-static
versions and MUST contain the sender's ephemeral key for the
ephemeral-static versions.
parameters are defined in table-ecdh-es-parameter-table.
Key derivation algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret.  As such, it
needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the
introduction of context material: how the key is going to be used,
and one time material for static-static key agreement.  All of the
algorithm define in this document use one of the HKDF algorithms
defined in HKDF with the context structure defined in context.
Key derivation algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret.  As such, it
needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the
introduction of context material: how the key is going to be used,
and one time material for static-static key agreement.  All of the
algorithms defined in this document use one of the HKDF algorithms
defined in HKDF with the context structure defined in context.
Applications need to determine the set of security algorithms that
are to be used.  When selecting the algorithms to be used as the
mandatory to implement set, consideration should be given to
choosing different types of algorithms when two are chosen for a
specific purpose.  An example of this would be choosing HMAC-
SHA512 and AES-CMAC as different MAC algorithms, the construction
is vastly different between these two algorithms.  This means that
a weakening of one algorithm would be unlikely to lead to a
weakening of the other algorithms.  Of course, these algorithms do
not provide the same level of security and thus may not be
comparable for the desired security functionality.
Applications need to determine the set of security algorithms that
are to be used.  When selecting the algorithms to be used as the
mandatory to implement set, consideration should be given to
choosing different types of algorithms when two are chosen for a
specific purpose.  An example of this would be choosing HMAC-
SHA512 and AES-CMAC as different MAC algorithms; the construction
is vastly different between these two algorithms.  This means that
a weakening of one algorithm would be unlikely to lead to a
weakening of the other algorithms.  Of course, these algorithms do
not provide the same level of security and thus may not be
comparable for the desired security functionality.
The tags to be assigned are in table CBOR-Tags.
The tags to be assigned are in CBOR-Tags.
It is requested that IANA create a new registry entitled "COSE Header
Parameters".  The registry is to be created as Expert Review
Required.  Expert review guidelines are provided in review.
This is the value used for the label.  The label can be either an
integer or a string.  Registration in the table is based on the
value of the label requested.  Integer values between 1 and 255
and strings of length 1 are designated as Standards Track Document
required.  Integer values from 256 to 65535 and strings of length
2 are designated as Specification Required.  Integer values of
greater than 65535 and strings of length greater than 2 are
designated as expert review.  Integer values in the range -1 to
-65536 are delegated to the "COSE Header Algorithm Label"
registry.  Integer values beyond -65536 are marked as private use.
This is the value used for the label.  The label can be either an
integer or a string.  Registration in the table is based on the
value of the label requested.  Integer values between 1 and 255
and strings of length 1 are designated as Standards Track Document
required.  Integer values from 256 to 65535 and strings of length
2 are designated as Specification Required.  Integer values of
greater than 65535 and strings of length greater than 2 are
designated as expert review.  Integer values in the range -1 to
-65536 are delegated to the "COSE Header Algorithm Label"
registry.  Integer values less than -65536 are marked as private
use.
It is requested that IANA create a new registry entitled "COSE Header
Algorithm Labels".  The registry is to be created as Expert Review
Required.  Expert review guidelines are provided in review.
It is requested that IANA create a new registry entitled "COSE
Algorithm Registry".  The registry is to be created as Expert Review
Required.  Expert review guidelines are provided in review.
The value to be used to identify this algorithm.  Algorithm values
MUST be unique.  The value can be a positive integer, a negative
integer or a string.  Integer values between -256 and 255 and
strings of length 1 are designated as Standards Track Document
required.  Integer values from -65536 to 65535 and strings of
length 2 are designated as Specification Required.  Integer values
of greater than 65535 and strings of length greater than 2 are
designated as expert review.  Integer values beyond -65536 are
marked as private use.
The value to be used to identify this algorithm.  Algorithm values
MUST be unique.  The value can be a positive integer, a negative
integer or a string.  Integer values between -256 and 255 and
strings of length 1 are designated as Standards Track Document
required.  Integer values from -65536 to 65535 and strings of
length 2 are designated as Specification Required.  Integer values
of greater than 65535 and strings of length greater than 2 are
designated as expert review.  Integer values less than -65536 are
marked as private use.
It is requested that IANA create a new registry entitled "COSE Key
Common Parameter" Registry.  The registry is to be created as Expert
Review Required.  Expert review guidelines are provided in review.
The value to be used to identify this algorithm.  Key map labels
MUST be unique.  The label can be a positive integer, a negative
integer or a string.  Integer values between 0 and 255 and strings
of length 1 are designated as Standards Track Document required.
Integer values from 256 to 65535 and strings of length 2 are
designated as Specification Required.  Integer values of greater
than 65535 and strings of length greater than 2 are designated as
expert review.  Integer values in the range -1 to -65536 are used
for key parameters specific to a single algorithm delegated to the
"COSE Key Type Parameter Label" registry.  Integer values beyond
-65536 are marked as private use.
The value to be used to identify this algorithm.  Key map labels
MUST be unique.  The label can be a positive integer, a negative
integer or a string.  Integer values between 0 and 255 and strings
of length 1 are designated as Standards Track Document required.
Integer values from 256 to 65535 and strings of length 2 are
designated as Specification Required.  Integer values of greater
than 65535 and strings of length greater than 2 are designated as
expert review.  Integer values in the range -1 to -65536 are used
for key parameters specific to a single algorithm delegated to the
"COSE Key Type Parameter Label" registry.  Integer values less
than -65536 are marked as private use.
It is requested that IANA create a new registry "COSE Key Type
Parameters".  The registry is to be created as Expert Review
Required.  Expert review guidelines are provided in review.
This contains a pointer to the public specification for the field
if one exists.
It is requested that IANA create a new registry "COSE Elliptic Curve
Parameters".  The registry is to be created as Expert Review
Required.  Expert review guidelines are provided in review.
This section registers the "application/cose-key+cbor" and
"application/cose-key-set+cbor" media types in the "Media Types"
registry.  These media types are used to indicate, respectively, that
content is a COSE_Key or COSE_KeySet object.
This section registers the "application/cose-key" and "application/
cose-key-set" media types in the "Media Types" registry.  These media
types are used to indicate, respectively, that content is a COSE_Key
or COSE_KeySet object.
Specifications are required for the standards track range of point
assignment.  Specifications should exist for specification
required ranges, but early assignment before a specification is
available is considered to be permissible.  Specifications are
needed for the first-come, first-serve range if they are expected
to be used outside of closed environments in an inoperable way.
When specifications are not provided, the description provided
needs to have sufficient information to identify what point is
being used for.
Specifications are required for the standards track range of point
assignment.  Specifications should exist for specification
required ranges, but early assignment before a specification is
available is considered to be permissible.  Specifications are
needed for the first-come, first-serve range if they are expected
to be used outside of closed environments in an interoperable way.
When specifications are not provided, the description provided
needs to have sufficient information to identify what point is
being used for.
Languages: There are three different languages that are current
supported: JAVA, C# and C.
Languages: There are three different languages that are currently
supported: Java, C# and C.
an 'oct' key is expected.
an 'OKP' key is expected.