Draft: draft-ietf-cose-msg

Commentary: Do a spelling and grammar pass update the changes list at the end of the document .
It is expected that COSE is going to be used in a wide variety of
applications and on a wide variety of devices.  Many of the
constrained devices are going to be setup to used a small fixed set
of algorithms, and this set of algorithms may not match those
available on a device.  We therefore have deferred to the application
protocols the decision of what to specify for mandatory algorithms.
It is expected that COSE is going to be used in a wide variety of
applications and on a wide variety of devices.  Many of the
constrained devices are going to be setup to use a small fixed set of
algorithms, and this set of algorithms may not match those available
on a device.  We therefore have deferred to the application protocols
the decision of what to specify for mandatory algorithms.
The COSE Message 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 build on a CBOR
array type.  The first three elements of the array contains the same
basic information.  The first element is a set of protected header
information.  The second element is a set of unprotected header
information.  The third element is the content of the message (either
as plain text or encrypted).  Elements after this point are dependent
on the specific message type.
The COSE Message 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 a CBOR
array type.  The first three elements of the array contains the same
basic information.  The first element is a set of protected header
information.  The second element is a set of unprotected header
information.  The third element is the content of the message (either
as plain text or encrypted).  Elements after this point are dependent
on the specific message type.
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, an 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 fields are not
present in their corresponding maps, 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, an 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.
COSE supports two different encryption structures.  OOSE_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 the a
recipient structure is not needed because the key to be used is known
implicitly.
COSE supports two different encryption structures.  OOSE_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.
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 parameters associated with the content can be
authenticated by the content encryption algorithm.  The parameters
associated with the recipient can be authenticated by the recipient
algorithm (when the algorithm supports it).  Examples of parameters
about the content are the type of the content, when the content was
created, and the content encryption algorithm.  Examples of
parameters about the recipient are the recipients 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 parameters associated with the content can be
authenticated by the content encryption algorithm.  The parameters
associated with the recipient can be authenticated by the recipient
algorithm (when the algorithm supports it).  Examples of parameters
about the content are the type of the content, when the content was
created, and the content encryption algorithm.  Examples of
parameters about the recipient are the recipient's key identifier,
the recipient encryption algorithm.
The CEK is the same as as the identified previously distributed
symmetric key or derived from a previously distributed secret.
The CEK is the same as the identified previously distributed
symmetric key or derived from a previously distributed secret.
The GCM mode is is a generic authenticated encryption block cipher
mode defined in AES-GCM.  The GCM mode is combined with the AES block
encryption algorithm to define a an AEAD cipher.
The GCM mode is a generic authenticated encryption block cipher mode
defined in AES-GCM.  The GCM mode is combined with the AES block
encryption algorithm to define an AEAD cipher.
produces a 64-bit authentication tag.  This implies that there is
a 1 in 2^64 chance that an modified message will authenticate.
produces a 128-bit authentication tag.  This implies that there is
a 1 in 2^128 chance that an modified message will authenticate.
produces a 64-bit authentication tag.  This implies that there is
a 1 in 2^64 chance that a modified message will authenticate.
produces a 128-bit authentication tag.  This implies that there is
a 1 in 2^128 chance that a modified message will authenticate.
The ChaCha20/Poly1305 AEAD construction defined in RFC7539 has no
parameterization.  It takes a 256-bit key and an 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.
HKDF is defined to use HMAC as the underlying PRF.  However, it is
possible to use other functions in the same construct to provide a
different KDF function that may be more appropriate in the
constrained world.  Specifically, one can use AES-CBC-MAC as the PRF
for the expand step, but not for the extract step.  When using a good
random shared secret of the correct length, the extract step can be
skipped.  The extract cannot be skipped if the secret is not
uniformly random, for example if it is the result of a ECDH key
agreement step.
HKDF is defined to use HMAC as the underlying PRF.  However, it is
possible to use other functions in the same construct to provide a
different KDF function that may be more appropriate in the
constrained world.  Specifically, one can use AES-CBC-MAC as the PRF
for the expand step, but not for the extract step.  When using a good
random shared secret of the correct length, the extract step can be
skipped.  The extract cannot be skipped if the secret is not
uniformly random, for example if it is the result of an ECDH key
agreement step.
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 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).
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 is for a protocol to assign identities is to use a name
based on a naming system (i.e.  DNS, X.509 names).
Key Wrap algorithm: The key wrap algorithm can be 'none' if the
result of the KDF is going to be used as the key directly.  This
option, along with static-static, should be used if knowledge
about the sender is desired.  If 'none' is used then the content
layer encryption algorithm size is value fed to the context
structure.  Support is also provided for any of the key wrap
algorithms defined in section key_wrap_algs.  If one of these
options is used, the input key size to the key wrap algorithm is
the value fed into the context structure as the key size.
Key Wrap algorithm: The key wrap algorithm can be 'none' if the
result of the KDF is going to be used as the key directly.  This
option, along with static-static, should be used if knowledge
about the sender is desired.  If 'none' is used then the content
layer encryption algorithm size is value fed to the context
structure.  Support is also provided for any of the key wrap
algorithms defined in key_wrap_algs.  If one of these options is
used, the input key size to the key wrap algorithm is the value
fed into the context structure as the key size.
A parameter identifying the recipient's key SHOULD be present.  A
parameter identifying the senders key SHOULD be present.
A parameter identifying the recipient's key SHOULD be present.  A
parameter identifying the sender's key SHOULD be present.
This is the value used to identify the curve.  These values MUST
be unique.  The integer values from -256 to 255 are designated as
Standards Track Document Required.  The the integer values from
256 to 65535 and -65536 to -257 are designated as Specification
Required.  Integer values over 65535 are designated as first come
first serve.  Integer values less than -65536 are marked as
private use.
This is the value used to identify the curve.  These values MUST
be unique.  The integer values from -256 to 255 are designated as
Standards Track Document Required.  The integer values from 256 to
65535 and -65536 to -257 are designated as Specification Required.
Integer values over 65535 are designated as first come first
serve.  Integer values less than -65536 are marked as private use.
Need to verify that: 1) the kty field of the key matches the key
and algorithm being used.  2) that the kty field needs to be
included in the trust decision as well as the other key fields.
3) that the algorithm be included in the trust decision.
Need to verify that: 1) the kty field of the key matches the key
and algorithm being used.  2) the kty field needs to be included
in the trust decision as well as the other key fields.  3) the
algorithm be included in the trust decision.