Draft: draft-ietf-cose-msg

Commentary: No response from  so replace his pull request
There has been an increased focus on the small, constrained devices
that make up the Internet of Things (IoT).  One of the standards that
has come out of this process is the Concise Binary Object
Representation (CBOR) RFC7049.  CBOR extended the data model of the
JavaScript Object Notation (JSON) RFC7159 by allowing for binary data
among other changes.  CBOR is being adopted by several of the IETF
working groups dealing with the IoT world as their encoding of data
structures.  CBOR was designed specifically to be both small in terms
of messages transport and implementation size as well having a schema
free decoder.  A need exists to provide message security services for
IoT and using CBOR as the message encoding format makes sense.
There has been an increased focus on the small, constrained devices
that make up the Internet of Things (IoT).  One of the standards that
has come out of this process is the Concise Binary Object
Representation (CBOR) RFC7049.  CBOR extended the data model of the
JavaScript Object Notation (JSON) RFC7159 by allowing for binary
data, among other changes.  CBOR is being adopted by several of the
IETF working groups dealing with the IoT world as their encoding of
data structures.  CBOR was designed specifically to be both small in
terms of messages transport and implementation size, as well having a
schema free decoder.  A need exists to provide message security
services for IoT and using CBOR as the message encoding format makes
sense.
CBOR has capabilities that are not present in JSON and should be
used.  One example of this is the fact that CBOR has a method of
encoding binary directly without first converting it into a base64
encoded string.
CBOR has capabilities that are not present in JSON and are
appropriate to use.  One example of this is the fact that CBOR has
a method of encoding binary directly without first converting it
into a base64 encoded string.
The presence of a label in a map which is not a string or an integer
is an error.  Applications can either fail processing or process
messages with incorrect labels, however they MUST NOT create messages
with incorrect labels.
A CDDL grammar fragment is defined that defines the non-terminals
'label' as in the previous paragraph and 'values' which permits any
value to be used.
The presence of a label in a map that is not a string or an integer
is an error.  Applications can either fail processing or process
messages with incorrect labels, however they MUST NOT create messages
with incorrect labels.
A CDDL grammar fragment is defined that defines the non-terminals
'label', as in the previous paragraph and 'values', which permits any
value to be used.
The COSE object structure is designed so that there can be a large
amount of common code when parsing and processing the different
security messages.  All of the message structures are built on the
CBOR array type.  The first three elements of the array contain the
same information.
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).
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).
The buckets are present in all of the security objects defined in
this document.  The fields in order are the 'protected' bucket (as a
CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map'
type).  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.
Labels in each of the maps MUST be unique.  When processing messages,
if a label appears multiple times the message MUST be rejected as
malformed.  Applications SHOULD perform the same checks that the
labels appearing in the protected and unprotected headers are unique
as well.  If the message is not rejected as malformed, attributes
MUST be obtained from the protected bucket before they are obtained
from the unprotected bucket.
The buckets are present in all of the security objects defined in
this document.  The fields in order are the 'protected' bucket (as a
CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map'
type).  The presence of both buckets is required.  The parameters
that go into the buckets come from the IANA "COSE Header Parameters"
registry (cose-header-key-table).  Some common parameters are defined
in the next section, but a number of parameters are defined
throughout this document.
Labels in each of the maps MUST be unique.  When processing messages,
if a label appears multiple times, the message MUST be rejected as
malformed.  Applications SHOULD perform the same checks that the
labels appearing in the protected and unprotected headers are unique
as well.  If the message is not rejected as malformed, attributes
MUST be obtained from the protected bucket before they are obtained
from the unprotected bucket.
The following CDDL fragment represents the two header buckets.  A
group Headers is defined in CDDL which represents the two buckets in
which attributes are placed.  This group is used to provide these two
fields consistently in all locations.  A type is also defined which
represents the map of header values.  It uses forward references to a
group definition of headers for generic and algorithms.
The following CDDL fragment represents the two header buckets.  A
group Headers is defined in CDDL that represents the two buckets in
which attributes are placed.  This group is used to provide these two
fields consistently in all locations.  A type is also defined that
represents the map of header values.  It uses forward references to a
group definition of headers for generic and algorithms.
This section defines a set of common header parameters.  A summary of
these parameters can be found in Header-Table.  This table should be
consulted to determine the value of label as well as the type of the
value.
This section defines a set of common header parameters.  A summary of
these parameters can be found in Header-Table.  This table should be
consulted to determine the value of label, and the type of the value.
This parameter is used to indicate the algorithm used for the
security processing.  This parameter MUST be present at each layer
of a signed, encrypted or authenticated message except the
COSE_Sign structure.  When the algorithm supports authenticating
associated data, this parameter MUST be in the protected header
bucket.  The value is taken from the 'COSE Algorithm Registry'
(see cose-algorithm-registry).
This parameter is used to indicate the algorithm used for the
security processing.  This parameter MUST be present at each layer
of a signed, encrypted or authenticated message except the
COSE_Sign structure.  When the algorithm supports authenticating
associated data, this parameter MUST be in the protected header
bucket.  The value is taken from the "COSE Algorithms" Registry
(see cose-algorithm-registry).
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 cipher text 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.
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 cipher text 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.
The CDDL fragment that represents the set of headers defined in this
section is given below.  Each of the headers is tagged as optional
because they do not need to be in every map, headers required in
specific maps are discussed above.
The CDDL fragment that represents the set of headers defined in this
section is given below.  Each of the headers is tagged as optional
because they do not need to be in every map; headers required in
specific maps are discussed above.
The signature structure can be encoded either with or without a tag
depending on the context it will be used in.  The signature structure
is identified by the CBOR tag TBD1.  The CDDL fragment that
represents this is.
The CDDL fragment which represents the above text for COSE_Sign
follows.
The CDDL fragment that represents the above text for COSE_Sign
follows.
The CDDL fragment which represents the above text for COSE_Signature
follows.
The CDDL fragment that represents the above text for COSE_Signature
follows.
The CBOR object that carries the body, the signature and the
information about the body and signature is called the COSE_Sign1
structure.  Examples of COSE Single signature messages can be found
in Sign1_Examples.
The CBOR object that carries the body, the signature, and the
information about the body and signature is called the COSE_Sign1
structure.  Examples of COSE Single signature messages can be found
in Sign1_Examples.
The CDDL fragment which represents the above text for COSE_Sign1
follows.
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 information to be carried before the payload.
Examples of data that can be placed in this location would be the
CoAP code, CoAP token, or CoAP options.  If the data is in the header
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 if they are modified in transit it can
be detected.
The CDDL fragment that represents the above text for COSE_Sign1
follows.
One of the features supplied 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.  Examples of data that can be
placed in this location would be the CoAP code, CoAP token, or CoAP
options.  If the data is in the header 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 if they are modified in transit, it can be detected.
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.
Applications need to ensure that the byte stream is going to be
the same on both sides.  Using options from CoAP might give a
problem if the same relative numbering is kept.  An intermediate
node could insert or remove an option changing how the relative
number is done.  An application would need to specify that the
relative number must be re-encoded to be relative only to the
options that are in the external data.
If multiple items are included, an 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.
Applications need to ensure that the byte stream is going to be
the same on both sides.  Using options from CoAP might give a
problem if the same relative numbering is kept.  An intermediate
node could insert or remove an option, changing how the relative
number is done.  An application would need to specify that the
relative number must be re-encoded to be relative only to the
options that are in the external data.
The CDDL fragment which describes the above text is.
The CDDL fragment that describes the above text is.
Call the signature creation algorithm passing in K (the key to
sign with), alg (the algorithm to sign with) and ToBeSigned (the
value to sign).
Call the signature creation algorithm passing in K (the key to
sign with), alg (the algorithm to sign with), and ToBeSigned (the
value to sign).
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_Encrypt 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).
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_Encrypt 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).
The creation and validation of counter signatures over the different
items relies on the fact that the structure of the 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 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_Encrypt structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
The creation and validation of counter signatures over the different
items relies on the fact that the structure of the 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 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_Encrypt structure, the
body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure.
The enveloped structure allows for one or more recipients of a
message.  There are provisions for parameters about the content and
parameters about the recipient information to be carried in the
message.  The protected parameters associated with the content are
authenticated by the content encryption algorithm.  The protected
parameters associated with the recipient are authenticated by the
recipient algorithm (when the algorithm supports it).  Examples of
parameters about the content are the type of the content, and the
content encryption algorithm.  Examples of parameters about the
recipient are the recipient's key identifier, the recipient
encryption algorithm.
The enveloped structure allows for one or more recipients of a
message.  There are provisions for parameters about the content and
parameters about the recipient information to be carried in the
message.  The protected parameters associated with the content are
authenticated by the content encryption algorithm.  The protected
parameters associated with the recipient are authenticated by the
recipient algorithm (when the algorithm supports it).  Examples of
parameters about the content are the type of the content and the
content encryption algorithm.  Examples of parameters about the
recipient are the recipient's key identifier and the recipient's
encryption algorithm.
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 CMS RFC5652 and JSON Web Encryption
(JWE) RFC7516 where different structures are used for the content
layer and for the recipient layer.  Two structures are defined:
COSE_Encrypt to hold the encrypted content, and COSE_recipient to
hold the encrypted keys for recipients.  Examples of encrypted
messages can be found in EnvelopedExamples.
The COSE_Encrypt structure can be encoded either with or without a
tag depending on the context it will be used in.  The structure is
identified by the CBOR tag TBD2.  The CDDL fragment that represents
this is.
contains the cipher text encoded as a bstr.  If the cipher text is
to be transported independently of the control information about
the encryption process (i.e. detached content) then the field is
encoded as a nil value.
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 CMS RFC5652 and JSON Web Encryption
(JWE) RFC7516 where different structures are used for the content
layer and for the recipient layer.  Two structures are defined:
COSE_Encrypt to hold the encrypted content and COSE_recipient to hold
the encrypted keys for recipients.  Examples of encrypted messages
can be found in EnvelopedExamples.
contains the cipher text encoded as a bstr.  If the cipher text is
to be transported independently of the control information about
the encryption process (i.e., detached content) then the field is
encoded as a nil value.
contains an array of recipient information structures.  The type
for the recipient information structure is a COSE_recipient.  (And
example of this can be found in three-layer.)  If there are no
recipient information structures, this element is absent.
contains an array of recipient information structures.  The type
for the recipient information structure is a COSE_recipient.  (An
example of this can be found in three-layer.)  If there are no
recipient information structures, this element is absent.
The COSE_Encrypt1 structure can be encoded either with or without a
tag depending on the context it will be used in.  The COSE_Encrypt1
structure is identified by the CBOR tag TBD3.  The CDDL fragment that
represents this is.
for the first layer of a COSE_Encrypt data structure (i.e. for
content encryption).
for the first layer of a COSE_Encrypt data structure (i.e., for
content encryption).
COSE supports two different MAC structures.  COSE_MAC0 is used when a
recipient structure is not needed because the key to be used is
implicitly known.  COSE_MAC is used for all other cases.  These
include a requirement for multiple recipients, the key being unknown,
a recipient algorithm of other than direct.
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 classes of recipient algorithms as are allowed for
encryption.
COSE supports two different MAC structures.  COSE_MAC0 is used when a
recipient structure is not needed because the key to be used is
implicitly known.  COSE_MAC is used for all other cases.  These
include a requirement for multiple recipients, the key being unknown,
and a recipient algorithm of other than direct.
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 classes of recipient algorithms as are allowed
for encryption.
contains the serialized content to be MACed.  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
value 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 MACed.  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
value is placed in this location and it is the responsibility of
the application to ensure that it will be transported without
changes.
The CDDL fragment which represents the above text for COSE_Mac
follows.
In this section we describe the structure and methods to be used when
doing MAC authentication for those cases where the recipient is
implicitly known.
The CDDL fragment that represents the above text for COSE_Mac
follows.
In this section, we describe the structure and methods to be used
when doing MAC authentication for those cases where the recipient is
implicitly known.
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).
Each element in a key set MUST be processed independently.  If one
element in a key set is either malformed or uses a key which is not
understood by an application, that key is ignored and the other keys
are processed normally.
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 "COSE Key Common Parameters" registry (cose-key-map-registry).
Additional parameters defined for specific key types can be found in
the IANA "COSE Key Type Parameters" registry (cose-key-parameter-
registry).
Each element in a key set MUST be processed independently.  If one
element in a key set is either malformed or uses a key that is not
understood by an application, that key is ignored and the other keys
are processed normally.
The following provides a CDDL fragment which duplicates the
assignment labels from table-key-labels.
The following provides a CDDL fragment that duplicates the assignment
labels from table-key-labels.
which are highly predictable require additional randomness to be
supplied as part of the signature process.  In the worst case, it
becomes the same as doing a signature with appendix.  Finally, in the
event that multiple signatures are applied to a message, all of the
signature algorithms are going to be required to consume the same
number of bytes of message content.  This means that mixing of the
different schemes in a single message is not supported, and if a
recovery signature scheme is used then the same amount of content
needs to be consumed by all of the signatures.
that are highly predictable require additional randomness to be
supplied as part of the signature process.  In the worst case, it
becomes the same as doing a signature with appendix.  Finally, in the
event that multiple signatures are applied to a message, all of the
signature algorithms are going to be required to consume the same
number of bytes of message content.  This means that mixing of the
different schemes in a single message is not supported, and if a
recovery signature scheme is used, then the same amount of content
needs to be consumed by all of the signatures.
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 deterministic signatures where poor random number generation
exists.
Systems that 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 deterministic signatures where poor random number generation
exists.
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.
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 algorithms defined in this document can be found in table-eddsa-
algs.  A single signature algorithm is defined which can be used for
multiple curves.
The algorithms defined in this document can be found in table-eddsa-
algs.  A single signature algorithm is defined, which can be used for
multiple curves.
MAC algorithms can be based on either a block cipher algorithm (i.e.
AES-MAC) or a hash algorithm (i.e.  HMAC).  This document defines a
MAC algorithm using each of these constructions.
MAC algorithms can be based on either a block cipher algorithm (i.e.,
AES-MAC) or a hash algorithm (i.e., HMAC).  This document defines a
MAC algorithm using each of these constructions.
The HMAC algorithm is parameterized by an inner and outer padding, a
hash function (h) and an authentication tag value length.  For this
specification, the inner and outer padding are fixed to the values
set in RFC2104.  The length of the authentication tag corresponds to
the difficulty of producing a forgery.  For use in constrained
environments, we define a set of HMAC algorithms that are truncated.
There are currently no known issues with truncation, however the
security strength of the message tag is correspondingly reduced in
strength.  When truncating, the left-most tag length bits are kept
and transmitted.
The HMAC algorithm is parameterized by an inner and outer padding, a
hash function (h), and an authentication tag value length.  For this
specification, the inner and outer padding are fixed to the values
set in RFC2104.  The length of the authentication tag corresponds to
the difficulty of producing a forgery.  For use in constrained
environments, we define a set of HMAC algorithms that are truncated.
There are currently no known issues with truncation, however the
security strength of the message tag is correspondingly reduced in
strength.  When truncating, the left-most tag length bits are kept
and transmitted.
Consideration was given to supporting smaller tag values, the
constrained community would desire tag sizes in the 64-bit range.
Doing so 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.
Consideration was given to supporting smaller tag values; the
constrained community would desire tag sizes in the 64-bit range.
Doing so 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.
The ChaCha20/Poly1305 AEAD construction defined in RFC7539 has no
parameterization.  It takes a 256-bit key and a 96-bit nonce as well
as the plain text and additional data as inputs and produces the
cipher text as an option.  We define one algorithm identifier for
this algorithm in Table-CHACHA.
The ChaCha20/Poly1305 AEAD construction defined in RFC7539 has no
parameterization.  It takes a 256-bit key and a 96-bit nonce, as well
as the plain text and additional data as inputs and produces the
cipher text as an option.  We define one algorithm identifier for
this algorithm in Table-CHACHA.
Secrets that are uniformly random: This is the type of secret
which is created by a good random number generator.
Secrets that are not uniformly random: This is type of secret
which is created by operations like key agreement.
General KDF functions work well with the first type of secret, can do
reasonable well with the second type of secret and generally do
poorly with the last type of secret.  None of the KDF functions in
this section are designed to deal with the type of secrets that are
used for passwords.  Functions like PBSE2 RFC2898 need to be used for
that type of secret.
Secrets that are uniformly random: This is the type of secret that
is created by a good random number generator.
Secrets that are not uniformly random: This is type of secret that
is created by operations like key agreement.
General KDF functions work well with the first type of secret, can do
reasonably well with the second type of secret, and generally do
poorly with the last type of secret.  None of the KDF functions in
this section are designed to deal with the type of secrets that are
used for passwords.  Functions like PBES2 RFC2898 need to be used for
that type of secret.
The extract step cannot be skipped if the secret is not uniformly
random, for example if it is the result of an ECDH key agreement
step.  (This implies that the AES HKDF version cannot be used with
ECDH.)  If the extract step is skipped, the 'salt' value is not used
as part of the HKDF functionality.
The extract step cannot be skipped if the secret is not uniformly
random, for example, if it is the result of an ECDH key agreement
step.  (This implies that the AES HKDF version cannot be used with
ECDH.)  If the extract step is skipped, the 'salt' value is not used
as part of the HKDF functionality.
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.  By doing this association, different keys
will be derived for each direction as the context information is
different in each direction.
The context information structure refers to PartyU and PartyV as the
two parties that 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.  By doing this association, different keys
will be derived for each direction as the context information is
different in each direction.
This contains the identity information for party U.  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 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 the identity information for party U.  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 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.
The field other is for free form data defined by the
application.  An example is that an application could defined
two different strings to be placed here to generate different
keys for a data stream vs a control stream.  This 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
private information.  An example of this information would be a
pre-existing shared secret.  (This could for example, be used in
combination with an ECDH key agreement to provide a secondary
proof of identity.)  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 field other is for free form data defined by the
application.  An example is that an application could defined
two different strings to be placed here to generate different
keys for a data stream vs a control stream.  This 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.
This field contains private information that is mutually known
private information.  An example of this information would be a
pre-existing shared secret.  (This could, for example, be used in
combination with an ECDH key agreement to provide a secondary
proof of identity.)  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.
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.
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
CEK.  The 'protected' field can be of non-zero length.  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 shared secret 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
CEK.  The 'protected' field can be of non-zero length.  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 shared secret in question.
A new IV must be used for each message if the same key is used.  The
IV can be modified in a predictable manner, a random manner or an
unpredictable manner (i.e. encrypting a counter).
A new IV must be used for each message if the same key is used.  The
IV can be modified in a predictable manner, a random manner or an
unpredictable manner (i.e., encrypting a counter).
If the 'key_ops' field is present, it MUST include 'deriveKey or
'deriveBits'.
If the 'key_ops' field is present, it MUST include 'deriveKey' or
'deriveBits'.
Ephemeral-Static DH: where the sender of the message creates a one
time DH key and uses a static key for the recipient.  The use of
the ephemeral sender key means that no additional random input is
needed as this is randomly generated for each message.
Ephemeral-Static DH: where the sender of the message creates a
one-time DH key and uses a static key for the recipient.  The use
of the ephemeral sender key means that no additional random input
is needed as this is randomly generated for each message.
The mathematics for Elliptic Curve Diffie-Hellman can be found in
RFC6090.  In this document the algorithm is extended to be used with
the two curves defined in RFC7748.
The mathematics for Elliptic Curve Diffie-Hellman can be found in
RFC6090.  In this document, the algorithm is extended to be used with
the two curves defined in RFC7748.
Computed Secret to Shared Secret: Once the computed secret is
known, the resulting value needs to be converted to a byte string
to run the KDF function.  The X coordinate is used for all of the
curves defined in this document.  For curves X25519 and X448, the
resulting value is used directly as it is a byte string of a known
length.  For the P-256, P-384 and P-521 curves, the X coordinate
is run through the I2OSP function defined in RFC3447 using the
same computation for n as is defined in ECDSA.
Computed Secret to Shared Secret: Once the computed secret is
known, the resulting value needs to be converted to a byte string
to run the KDF function.  The X coordinate is used for all of the
curves defined in this document.  For curves X25519 and X448, the
resulting value is used directly as it is a byte string of a known
length.  For the P-256, P-384 and P-521 curves, the X coordinate
is run through the I2OSP function defined in RFC3447, using the
same computation for n as is defined in ECDSA.
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.
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.
A new key type is defined for Octet Key Pairs (OKP).  Do not assume
that keys using this type are elliptic curves.  This key type could
be used for other curve types (for example mathematics based on
hyper-elliptic surfaces).
A new key type is defined for Octet Key Pairs (OKP).  Do not assume
that keys using this type are elliptic curves.  This key type could
be used for other curve types (for example, mathematics based on
hyper-elliptic surfaces).
This key structure does not have a form which contains only public
members.  As it is expected that this key structure is going to be
transmitted, care must be taking that it is never transmitted
accidentally or insecurely.  For symmetric keys, it is REQUIRED that
'k' be present in the structure.
This key structure does not have a form that contains only public
members.  As it is expected that this key structure is going to be
transmitted, care must be taking that it is never transmitted
accidentally or insecurely.  For symmetric keys, it is REQUIRED that
'k' be present in the structure.
This document is designed to provide a set of security services, but
not to provide implementation requirements for specific usage.  The
interoperability requirements are provided for how each of the
individual services are used and how the algorithms are to be used
for interoperability.  The requirements about which algorithms and
which services are needed is deferred to each application.
This document is designed to provide a set of security services, but
not to provide implementation requirements for specific usage.  The
interoperability requirements are provided for how each of the
individual services are used and how the algorithms are to be used
for interoperability.  The requirements about which algorithms and
which services are needed are deferred to each application.
It is requested that IANA assign the following tags from the "Concise
Binary Object Representation (CBOR) Tags" registry.  It is requested
that the tags for COSE_Sign1, COSE_Encrypt1 and COSE_Mac0 be assigned
in the 1 to 23 value range (i.e. one byte long when encoded).  It is
requested that the rest of the tags be assigned in the 24 to 255
value range (i.e. two bytes long when encoded).
It is requested that IANA assign the following tags from the "Concise
Binary Object Representation (CBOR) Tags" registry.  It is requested
that the tags for COSE_Sign1, COSE_Encrypt1 and COSE_Mac0 be assigned
in the 1 to 23 value range (i.e., one byte long when encoded).  It is
requested that the rest of the tags be assigned in the 24 to 255
value range (i.e., two bytes long when encoded).
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.
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 Labels"
registry.  Integer values less than -65536 are marked as private
use.
The algorithm(s) that this registry entry is used for.  This value
is taken from the "COSE Algorithm Value" registry.  Multiple
algorithms can be specified in this entry.  For the table, the
algorithm, label pair MUST be unique.
The algorithm(s) that this registry entry is used for.  This value
is taken from the "COSE Algorithm Values" registry.  Multiple
algorithms can be specified in this entry.  For the table, the
algorithm, label pair MUST be unique.
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.
It is requested that IANA create a new registry entitled "COSE
Algorithms Registry".  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 Key
Common Parameter" Registry.  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 Key
Common Parameters" 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 less
than -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 Labels" registry.  Integer values less
than -65536 are marked as private use.
This field contains a descriptive string of a key type.  This
should be a value that is in the COSE General Values table and is
placed in the 'kty' field of a COSE Key structure.
This field contains a descriptive string of a key type.  This
should be a value that is in the COSE Key Common Parameters table
and is placed in the 'kty' field of a COSE Key structure.
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.
Experts should take into account the expected usage of fields when
approving point assignment.  The fact that there is a range for
standards track documents does not mean that a standards track
document cannot have points assigned outside of that range.  Some
of the ranges are restricted in range, items which are not
expected to be common or are not expected to be used in restricted
environments should be assigned to values which will encode to
longer byte strings.
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 the point is
being used for.
Experts should take into account the expected usage of fields when
approving point assignment.  The fact that there is a range for
standards track documents does not mean that a standards track
document cannot have points assigned outside of that range.  Some
of the ranges are restricted in range, items that are not expected
to be common or are not expected to be used in restricted
environments should be assigned to values which will encode to
longer byte strings.
When algorithms are registered, vanity registrations should be
discouraged.  One way to do this is to require applications to
provide additional documentation on security analysis of
algorithms.  Another thing that should be considered is to request
for an opinion on the algorithm from the Cryptographic Forum
Research Group.  Algorithms which do not meet the security
requirements of the community and the messages structures should
not be registered.
When algorithms are registered, vanity registrations should be
discouraged.  One way to do this is to require applications to
provide additional documentation on security analysis of
algorithms.  Another thing that should be considered is to request
for an opinion on the algorithm from the Cryptographic Forum
Research Group.  Algorithms that do not meet the security
requirements of the community and the messages structures should
not be registered.
Coverage: The libraries currently do not have full support for
counter signatures of either variety.  They do have support to
allow for implicit algorithm support as they allow for the
application to set attributes which are not to be sent in the
message.
Coverage: The libraries currently do not have full support for
counter signatures of either variety.  They do have support to
allow for implicit algorithm support as they allow for the
application to set attributes that are not to be sent in the
message.
Description: A set of tests for the COSE library is provided as
part of the implementation effort.  Both success and fail tests
has been provided.  All of the examples in this document are part
of this example set.
Coverage: The attempt has been to have test cases for every
message type and algorithm in the document.  Current examples
dealing with counter signatures, EdDSA and ECDH with Curve24459
and Goldilocks are missing.
Description: A set of tests for the COSE library is provided as
part of the implementation effort.  Both success and fail tests
have been provided.  All of the examples in this document are part
of this example set.
Coverage: An attempt has been made to have test cases for every
message type and algorithm in the document.  Currently examples
dealing with counter signatures, EdDSA, and ECDH with Curve24459
and Goldilocks are missing.
The use of ECDH and direct plus KDF (with no key wrap) will not
directly lead to the private key being leaked, the one way function
of the KDF will prevent that.  There is however a different issue
that needs to be addressed.  Having two recipients, requires that the
CEK be shared between two recipients.  The second recipient therefore
has a CEK that was derived from material that can be used for the
weak proof of origin.  The second recipient could create a message
using the same CEK and send it to the first recipient, the first
recipient would, for either static-static ECDH or direct plus KDF,
make an assumption that the CEK could be used for proof of origin
even though it is from the wrong entity.  If the key wrap step is
added, then no proof of origin is implied and this is not an issue.
The use of ECDH and direct plus KDF (with no key wrap) will not
directly lead to the private key being leaked; the one way function
of the KDF will prevent that.  There is however, a different issue
that needs to be addressed.  Having two recipients requires that the
CEK be shared between two recipients.  The second recipient therefore
has a CEK that was derived from material that can be used for the
weak proof of origin.  The second recipient could create a message
using the same CEK and send it to the first recipient, the first
recipient would, for either static-static ECDH or direct plus KDF,
make an assumption that the CEK could be used for proof of origin
even though it is from the wrong entity.  If the key wrap step is
added, then no proof of origin is implied and this is not an issue.
Is the request something that is reasonable given the current
state of the application?
Is the request something that is reasonable, given the current
state of the application?
Have any security considerations that are part of the message been
enforced (as specified by the application or crit parameter)?