Draft: draft-ietf-cose-msg

Commentary: Copy Editing Pretty up the tables Address issue cose - wg / cose - issues
Concise Binary Object Representation (CBOR) is data format designed
for small code size and small message size.  There is a need for the
ability to have the basic security services defined for this data
format.  This document specifies procesing for signatures, message
authentication codes, and encryption using CBOR.  This document also
specifies a represention for cryptographic keys using CBOR.
Concise Binary Object Representation (CBOR) is data format designed
for small code size and small message size.  There is a need for the
ability to have the basic security services defined for this data
format.  This document specifies processing for signatures, message
authentication codes, and encryption using CBOR.  This document also
specifies a representation for cryptographic keys using CBOR.
Recipient processing has been made more uniform.  A recipient
structure is required for all recipients rather than only for
some.
MAC messages have the ability to use all recipient algorithms on
the MAC authentication key.
MAC messages have the ability to use the same set of recipient
algorithms as enveloped messages do to obtain the MAC
authentication key.
The set of cryptographic algorithms has been expanded in some
directions, and trimmed in others.
The non-terminal Internal_Types is defined for dealing with the
automated validation tools used during the writing of this document.
It references those non-terminals that are used for security
computations.
In JSON, maps are called objects and only have one kind of map key: a
string.  In COSE, we use both strings and integers (both negative and
unsigned integers) as map keys.  The integers are used for
compactness of encoding and easy comparison.  (Generally, in this
document the value zero is going to be reserved and not used.)  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
keys.
The non-terminal Internal_Types is defined for dealing with the
automated validation tools used during the writing of this document.
It references those non-terminals that are used for security
computations, but are not emitted for transport.
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.
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.
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 specific message type is known from the context in which it is
placed.  This may be defined by a marker in the containing
structure or by restrictions specified by the application
protocol.
The message type is identified by a CBOR tag.  This document
defines a CBOR tag for each of the message structures.
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 the
CBOR array type.  The first three elements of the array contain the
same information.
The specific message type is known from the context.  This may be
defined by a marker in the containing structure or by restrictions
specified by the application protocol.
The message type is identified by a CBOR tag.  This document
defines a CBOR tag for each of the message structures.  These tags
can be found in CBOR-Tags.
When a COSE object is carried in a CoAP message, 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.
The structure of COSE has been designed to have two buckets of
information that are not considered to be part of the payload itself,
but are used for holding information about content, algorithms, keys,
or evaluation hints for the processing of the layer.  These two
buckets are available for use in all of the structures in this
document except for keys.  While these buckets can be present, they
may not all be usable in all instances.  For example, while the
protected bucket is defined as part of recipient structures, most of
the algorithms that are used for recipients do not provide the
necessary functionality to provide the needed protection and thus the
bucket should not be used.
The structure of COSE has been designed to have two buckets of
information that are not considered to be part of the payload itself,
but are used for holding information about content, algorithms, keys,
or evaluation hints for the processing of the layer.  These two
buckets are available for use in all of the structures in this
document except for keys.  While these buckets can be present, they
may not all be usable in all instances.  For example, while the
protected bucket is defined as part of recipient structures, most of
the algorithms that are used for recipients do not provide for
authenticated data and thus the bucket should not be used.
Contains parameters about the current layer that are to be
cryptographically protected.  This bucket MUST be empty if it is
not going to be included in a cryptographic computation.  This
bucket is encoded in the message as a binary object.  This value
is obtained by CBOR encoding the protected map and wrapping it in
a bstr object.  Senders SHOULD encode an empty protected map as a
zero length binary object (it is shorter).  Recipients MUST accept
both a zero length binary value and a zero length map encoded in
the binary value.  The wrapping allows for the encoding of the
protected map to be transported with a greater chance that it will
not be altered in transit.  (Badly behaved intermediates could
decode and re-encode, but this will result in a failure to verify
unless the re-encoded byte string is identical to the decoded byte
string.)  This finesses the problem of all parties needing to be
able to do a common canonical encoding.
Contains parameters about the current layer that are to be
cryptographically protected.  This bucket MUST be empty if it is
not going to be included in a cryptographic computation.  This
bucket is encoded in the message as a binary object.  This value
is obtained by CBOR encoding the protected map and wrapping it in
a bstr object.  Senders SHOULD encode an empty protected map as a
zero length binary object (it is both shorter and the version used
in the authentication structures).  Recipients MUST accept both a
zero length binary value and a zero length map encoded in the
binary value.  The wrapping allows for the encoding of the
protected map to be transported with a greater chance that it will
not be altered in transit.  (Badly behaved intermediates could
decode and re-encode, but this will result in a failure to verify
unless the re-encoded byte string is identical to the decoded byte
string.)  This finesses the problem of all parties needing to be
able to do a common canonical encoding.
This section defines a set of common header parameters.  A summary of
those parameters can be found in Header-Table.  This table should be
consulted to determine the value of label used as well as the type of
the value.
This parameter is used to indicate the algorithm used for the
security processing.  This parameter MUST be present at each level
of a signed, encrypted or authenticated message.  When the
algorithm supports authenticating extenral data, this parameter
MUST be in the protected header bucket.  The value is taken from
the 'COSE Algorithm Registry' (see cose-algorithm-registry).
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 parameter is used to indicate the algorithm used for the
security processing.  This parameter MUST be present at each level
of a signed, encrypted or authenticated message.  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 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.
Integer labels in the range of 0 to 10 SHOULD be omitted.
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.  The
array MUST have at least one value in it.
Not all labels need to be included in the 'crit' parameter.
Integer labels in the range of 0 to 8 SHOULD be omitted.
This parameter one of the ways that can be used to find the key to
be used.  The value of this parameter is matched against the 'kid'
member in a COSE_Key structure.  Applications MUST NOT assume that
'kid' values are unique.  There may be more than one key with the
same 'kid' value, it may be required that all of the keys need to
be checked to find the correct one.  The internal structure of
'kid' values is not defined and generally cannot be relied on by
applications.  Key identifier values are hints about which key to
use.  They are not directly a security critical field.  For this
reason, they can be placed in the unprotected headers bucket.
This parameter one of the ways that can be used to find the key to
be used.  The value of this parameter is matched against the 'kid'
member in a COSE_Key structure.  Applications MUST NOT assume that
'kid' values are unique.  There may be more than one key with the
same 'kid' value, it may be required that all of the keys need to
be checked to find the correct one.  The internal structure of
'kid' 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 a part of the IV value.  When using the
COSE_Encrypted structure, frequently a portion of the IV is part
of the context associated with the key value.  This field is used
to carry the portion of the IV that changes for each message.  As
the IV is authenticated by the encryption process, this value can
be placed in the unprotected header bucket.
The final IV is generated by concatenating the fixed portion of
the IV, a zero string and the changing portion of the IV.  The
length of the zero string is computed by taking the required IV
length and subtracting the lengths of the fixed and changing IV
portions.
This parameter holds a part of the IV value.  When using the
COSE_Encrypted structure, frequently a portion of the IV is part
of the context associated with the key value.  This field is used
to carry the portion of the IV that changes for each message.  As
the IV is authenticated by the encryption process, this value can
be placed in the unprotected header bucket.  The 'Initialization
Vector' and 'Partial Initialization Vector' parameters MUST NOT be
present in the same security layer.
The final IV is generated by concatenating the fixed portion of
the IV, a zero string and the changing portion of the IV.  The
length of the zero string is computed by taking the required IV
length and subtracting the lengths of the fixed and changing IV
portions.
COSE supports two different signature structures.  COSE_Sign allows
for one or more signers to be applied to a single content.
COSE_Sign1 is restricted to a single signer.
COSE supports two different signature structures.  COSE_Sign allows
for one or more signers to be applied to a single content.
COSE_Sign1 is restricted to a single signer.  The structures cannot
be converted between each other, the signature computation includes a
parameter identifying which structure is being used.
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.  [CREF3] 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.  An example of a
parameter about the content is the content type.  Examples of
parameters about the signature would be the algorithm and key used to
create the signature, when the signature was created, and a counter-
signature.
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.
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, 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.
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.
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.
is described in full-signature.
as described in full-signature.
for the the content encryption of an encrypted data structure.
for the content encryption of an encrypted data structure.
COSE supports two different MAC structures.  COSE_MAC is used when
the key needs to be explicitly identified.  The structure supports
the use of recipient structures to allow for random content
encryption keys to be used.  COSE_MAC0 is used when the a recipient
structure is not needed because the key to be used is implicitly
known.
COSE supports two different MAC structures.  COSE_MAC is used when
the key needs to be explicitly identified.  The structure supports
the use of recipient structures to allow for random content
encryption keys to be used.  COSE_MAC0 is used when a recipient
structure is not needed because the key to be used is implicitly
known.
contains the recipient information.  See the description under
COSE_Encryption for more info.
contains the recipient information.  See the description under
COSE_Enveloped for more info.
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.
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 recommended that different keys be derived
in each direction to avoid reflection problems.
The 'recipients' field is normally absent, but can be used.
Applications MUST deal with a recipients field present, not being
able to decrypt that recipient is an acceptable way of dealing
with it.  Failing to process the message is not an acceptable way
of dealing with it.
The 'recipients' field is normally absent, but can be used.
Applications MUST deal with a recipient field present, not being
able to decrypt that recipient is an acceptable way of dealing
with it.  Failing to process the message is not an acceptable way
of dealing with it.