Draft: draft-schaad-cose-msg

Commentary: Lots of large re - writes Change to using entities for the examples The Rakefile is now known to fail .
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 how to do signatures, message
authentication codes and encryption using this data format.  The work
in this document is derived in part from the JSON web security
documents using the same parameters and algorithm identifiers as they
do.
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 sting.
The authors did not always agree with some of the decisions made
by the JOSE working group.  Many of these decisions have been re-
examined, and where it seems to the authors to be superior or
simpler, replaced.
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 how to do signatures, message
authentication codes and encryption using this data format.
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 of of this process is the Concise Binary Object
Representation (CBOR).  This standard extends the data model of the
JavaScript Object Notation (JSON) by allowing for binary data among
other changes.  CBOR is being adopted by several of the IETF working
groups dealing with the IOT world to do their encoding of data
structures.  CBOR was designed specifically to be both small in terms
of messages transport and implementation size.  A need exists to
provide basic 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.
The author did not always agree with some of the decisions made by
the JOSE working group.  Many of these decisions have been re-
examined, and where it seems to the author to be superior or
simpler, replaced.
MAC messages have the ability to do key management on the MAC key.
Remove the authentiction tag for encryption algorithms as a
separate item.
Remove the flattened mode of encoding.  Forcing the use of an
array of recipients at all times forces the message size to be two
bytes larger, but one gets a corresponding decrease in the
implementation size that should compenstate for this.
MAC messages have the ability to do key management on the MAC
authentication key.
Combine the authentication tag for encryption algorithms with the
ciphertext.
The COSE_MSG structure is a top level CBOR object which corresponds
to the DataContent type in RFC5652.  This structure allows for a top
level message to be sent which could be any of the different security
services, where the security service is identified.  The presence of
this structure does not preclude a protocol to use one of the
individual structures as a stand alone component.
The top level of each of the COSE message structures are encoded as
arrays.
We use an integer to distingish bettwen the different security
message types.  By looking at the integer in the first element, one
can determine which security message is being used and thus what the
syntax is for the rest of the elements in the array.
Implementations SHOULD be prepared to find an integer in the location
which does not correspond to the values 1 to 3.  If this is found
then the client MUST stop attempting to parse the structure and fail.
Clients need to recognize that the set of values could be extended at
a later date, but should not provide a security service based on
guesses of what is there.
The structure of COSE has been designed to have two buckets of
information that are not considered to be part of the message
structure itself, but are used for holding information about
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 present for 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 element is not used.
Both buckets are implemented as CBOR maps.  The maps can be keyed by
negative integers, unsigned integers and strings.  The negative and
unsigned integers are used for compactness of encoding.  The value
portion is dependent on the key definition.  Both maps use the same
set of key/value pairs.  The integer key range has been divided into
several sections with a standard range, a private range, and a range
that is dependent on the algorithm selected.  The tables of keys
defined can be found in Header-Table.
NOTE: At some point we need to make some decisions about how we are
using CDDL in this document.  Since this draft has not been moving
forward at a great rate, changing all references on it to
informational is a good idea.  On the other hand, having some type of
syntax that can be examined by a machine to do syntax checking is a
big win.  The build system for this draft is currently using the
latest version of CDDL to check that the syntax of the examples is
correct.  Doing this has found problems in both the syntax checker,
the syntax and the examples.
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
non-negative integers) as map keys, as well as data items to identify
specific choices.  The integers (both positive and negative) 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 of either
an integer or a string to identify map keys and choice data items.
The COSE_MSG structure is a top level CBOR object which corresponds
to the DataContent type in the Cryptographic Message Syntax
(CMS)RFC5652.  This structure allows for a top level message to be
sent which could be any of the different security services.  The
security service is identified within the message.
The COSE_Tagged_MSG CBOR type takes the COSE_MSG and prepends a CBOR
tag of TBD1 to the encoding of COSE_MSG.  By having both a tagged and
untagged version of the COSE_MSG structure, it becomes easy to either
use COSE_MSG as a top level object or embedded in another object.
The tagged version allows for a method of placing the COSE_MSG
structure into a choice, using a consistent tag value to determine
that this is a COSE object.
The existence of the COSE_MSG and COSE_Tagged_MSG CBOR data types are
not intended to prevent protocols from using the individual security
primitives directly.  Where only a single service is required, that
structure can be used directly.
Each of the top-level security objects use a CBOR map as the base
structure.  Items in the map at the top level are identified by a
label.  This document defines a number of labels in the IANA "COSE
Object Labels Registry" (defined in IANA-Top-Level-Keys).
The set of labels present in a security object is not restricted to
those defined in this document.  However, it is not recommended that
additional fields be added to a structure unless this is going to be
done in a closed environment.  When new fields need to be added, it
is recommended that a new message type be created so that processing
of the field can be ensured.  Using an older structure with a new
field means that any security properties of the new field will not be
enforced.  Before a new field is added at the outer level, strong
consideration needs to be given to defining a new header field and
placing it into the protected headers.  Applications should make a
determination if non-standardized fields are going to be permitted.
It is suggested that libraries allow for an option to fail parsing if
non-standardized fields exist, this is especially true if they do not
allow for access to the fields in other ways.
0 - Reserved.
1 - Signed Message.
Implementations MUST be prepared to find an integer under this label
which does not correspond to the values 1 to 3.  If this is found
then the client MUST stop attempting to parse the structure and fail.
The value of 0 is reserved and not to be used.  If the value of 0 is
found, then clients MUST fail processing the structure.
Implementations need to recognize that the set of values might be
extended at a later date, but they should not provide a security
service based on guesses of what is there.
The top level of each of the COSE message structures are encoded as
maps.  We use an integer to distinguish between the different
security message types.  By searching for the integer under the label
identified by msg_type (which is in turn an integer), one can
determine which security message is being used and thus what syntax
is for the rest of the elements in the map.
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 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 present for 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 element
is not used.
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
range 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 tables of labels can be found in Header-
Table.
TODO: Do we need to repeat definitions for all or just for some and
refer to the JOSE documents?
TODO: Should we move table Header-Table to here or leave it as an
appendix.  Some what redundant if we document things in text.
This field is used to indicate the algorithm used for the security
processing.  This field MUST be present at each level of a signed,
encrypted or authenticated message.  This field using the integer
'1' for the label.  The value is taken from the 'COSE Algorithm
Registry' (see IANA-Alg-Registry).
This field is used to ensure that applications will take
appropriate action based on the values found.  This field uses the
integer '2' for the label.  The value is an array of COSE Header
Labels.  The field is used to indicate which protected header
labels an application which is processing a message is required to
understand.
Integer labels in the range of 0 to 10 SHOULD be omitted.
Integer labels in the range -1 to -255 can be omitted as they
are algorithm dependent.  If an application can correctly
process an algorithm, it can be assumed that it will correctly
process all of the parameters associated with that algorithm.
The header 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 field is processed.
This field is used to indicate the content type of the data in the
payload or ciphertext fields.  The field uses the integer of '3'
for the label.  The value can be either an integer or a string.
Integers are from the XXXXX[CREF6] IANA registry table.  Strings
are from the IANA 'mime-content types' registry.  Applications
SHOULD provide this field if the content structure is potentially
ambiguous.
This field one of the ways that can be used to find the key to be
used.  This value can be matched against the 'kid' field 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.  This field uses the integer
value of '4' for the label.  The value of field is the CBOR 'bstr'
type.  The internal structure of 'kid' is not defined and
generally cannot be relied on by applications.
This table contains a list of all of the parameters for use in
signature and encryption message types defined by the JOSE document
set.  In the table is the data value type to be used for CBOR as well
as the integer value that can be used as a replacement for the name
in order to further decrease the size of the sent item.
I am currently torn on the question "Should epk and iv/nonce be
algorithm specific or generic headers?"  They are really specific
to an algorithm and can potentially be defined in different ways
for different algorithms.  As an example, it would make sense to
defined nonce for CCM and GCM modes that can have the leading zero
bytes stripped, while for other algorithms this might be
undesirable.
We might want to define some additional items.  What are they?  A
possible example would be a sequence number as this might be
common.  On the other hand, this is the type of things that is
frequently used as the nonce in some places and thus should not be
used in the same way.  Other items might be challenge/response
fields for freshness as these are likely to be common.
with one algorithm or the other.  (Source of text is RFC5652.)  More
detailed information on multiple signature evaluation can be found in
RFC5752.
The keys in the COSE_Sign map are keyed by the values in TOP-Level-
Keys.  While other keys can be present in the map, it is not
generally a recommended practice.  The other keys can be either of
integer or string type, use of other types is strongly discouraged.
See the note in {{CBOR-Canonical} about options for allowing or
disallowing other keys.
contains attributes about the payload which are to be protected by
the signature.  An example of such an attribute would be the
content type ('cty') attribute.  The content is a CBOR map of
attributes which is encoded to a byte stream.  This field MUST NOT
contain attributes about the signature, even if those attributes
are common across multiple signatures.  This fields in this map
are typically keyed by Header-Table.  Other keys can be used
either as int or tstr values.  Other types MUST NOT be present in
the map as key values.
contains attributes about the payload which are not protected by
the signature.  An example of such an attribute would be the
content type ('cty') attribute.  This field MUST NOT contain
attributes about a signature, even if the attributes are common
across multiple signatures.  This fields int his map are typically
keyed by Header-Table.  Other keys can be used either as int or
tstr values.  Other types MUST NOT be present in the map as key
values.
with one algorithm or the other.  (The original source of this text
is RFC5652.)  More detailed information on multiple signature
evaluation can be found in RFC5752.
identifies this as providing the signed security service.  The
value MUST be msg_type_signed (1).
contains attributes about the payload which are to be protected by
the signature.  An example of such an attribute would be the
content type ('cty') attribute.  The content is a CBOR map of
attributes which is encoded to a byte stream.  This field MUST NOT
contain attributes about the signature, even if those attributes
are common across multiple signatures.  The labels in this map are
typically taken from Header-Table.
contains attributes about the payload which are not protected by
the signature.  An example of such an attribute would be the
content type ('cty') attribute.  This field MUST NOT contain
attributes about a signature, even if the attributes are common
across multiple signatures.  The labels in this map are typically
taken from Header-Table.
The keys in the COSE_signature map are keyed by the values in TOP-
Level-Keys.  While other keys can be present in the map, it is not
generally a recommended practice.  The other keys can be either of
integer or string type, use of other types is strongly discouraged.
See the note in {{CBOR-Canonical} about options for allowing or
disallowing other keys.
We use the values in Top-Level-Keys as the labels in the COSE_Sign
map.  While other labels can be present in the map, it is not
generally a recommended practice.  The other labels can be either of
integer or string type, use of other types SHOULD be treated as an
error.
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
be used.
Create the value to be hashed by encoding the Sig_structure to a
byte string.
Comput the hash value from the byte string.
Place the signature value into the appropriate signature field.
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).
Place the resulting signature value in the 'signature' field of
the map.
Call the signature verification algorithm passing in K (the key to
verify with), alg (the algorithm to sign with), ToBeSigned (the
value to sign), and sig (the signature to be verified).
In addition to performing the signature verification, one must also
perform the appropriate checks to ensure that the key is correctly
paired with the signing identity and that the appropriated
authorization is done.
One of the byproducts of using the same technique for encrypting and
encoding both the content and the keys using the various key
management techniques, is a requirement that all of the key
management techniques use an Authenticated Encryption (AE) algorithm.
(For the purpose of this document we use a slightly loose definition
of AE algorithms.)  When encrypting the plain text, it is normal to
use an Authenticated Encryption with Additional Data (AEAD)
algorithm.  For key management, either AE or AEAD algorithms can be
used.  See AE-algo for more details about the different types of
algorithms.
identifies this as providing the encrypted security service.  The
value MUST be msg_type_encrypted (2).
contains the initialization vector (IV), or it's equivalent, if
one is needed by the encryption algorithm.
contains additional authenticated data (aad) supplied by the
application.  This field contains information about the plain text
data that is authenticated, but not encrypted.
An array of COSE_encrypt elements, one for each recipient.
contains the recipient information.  It is required that at least
one recipient MUST be present for the content encryption layer.
The 'protected', 'iv', 'aad', 'ciphertext' and 'recipients' fields
MUST be absent.
The 'protected', 'ciphertext' and 'recipients' fields MUST be
absent.
The 'protected', 'aad', and 'recipients' fields MUST be absent.
Use of the 'iv' field will depend on the key wrap algorithm.
The 'protected', and 'recipients' fields MUST be absent.
At a minimum, the 'unprotected' field SHOULD contain the 'alg'
parameter, a parameter identifying the recipient asymmetric key,
and a parameter with the sender's asymmetric public key.
At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter, a parameter identifying the recipient asymmetric key,
and a parameter with the sender's asymmetric public key.
If there is protected data, CBOR encode the map to a byte string
and place in the protected field of the Enc_structure and the
COSE_Encrypt structure.
Copy the 'aad' field from the COSE_Encrypt structure to the
Enc_Structure.
Encrypt the plain text and place it in the 'ciphertext' field.
The AAD value is passed in as part of the encryption process.
For recipient of the message, recursively perform the encryption
algorithm for that recipient using the encryption key as the plain
text.
Copy the protected header field from the message to be sent.
If the application has supplied external additional authenticated
data to be included in the computation, then it is placed in the
'external_aad' field.  If no data was supplied, then a zero length
binary value is used.
Call the encryption algorithm with K (the encryption key to use),
P (the plain text) and AAD (the additional authenticated data).
Place the returned cipher text into the 'ciphertext' field of the
structure.
Verify that the 'aad' field is absent.
Encrypt the plain text and place in the 'ciphertext' field.
Verify that there was no external additional authenticated data
supplied for this operation.
Call the encryption algorithm with K (the encryption key to use)
and the P (the plain text).  Place the returned cipher text into
the 'ciphertext' field of the structure.
identifies this as providing the encrypted security service.  The
value MUST be msg_type_mac (3).
If the application has supplied external authenticated data,
encode it as a binary value and place in the MAC_structure.  If
there is no external authenticated data, then use a zero length
'bstr'.
The "key_ops" element is prefered over the "use" element as the
information provided that way is more finely detailed about the
operations allowed.  It is strongly suggested that this element be
present for all keys.
The "key_ops" element is preferred over the "use" element as the
information provided that way is more finely detailed about the
operations allowed.  It is strongly suggested that this element be
present for all keys.
Any item which is string (but not base64) encoded in JWK, is tstr
encoded for COSE.
All parsers used SHOULD fail on both parsing and generation if the
same key is used twice in a map.
While it is permitted to have key values other than those specified
in this document in the outer maps (COSE_Sign, COSE_Signature,
COSE_encrypt, COSE_recipient and COSE_mac), doing so is not
encouraged.  Applications should make a determination if it will be
permitted for that application.  In general, any needed new fields
can be accomadated by the introduction of new header fields to be
carried in the protected or unprotected fields.  Applications that
need to have new fields in these maps should consider getting new
message types assigned for these usages.  Without this change, old
applications will not see and process the new fields.
It is requested that IANA assign a new tag from the "Concise Binary
Object Represetion (CBOR) Tags" registry.  It is requested that the
tag be assigned in the 0 to 23 value range.
All parsers used SHOULD fail on both parsing and generation if the
same label is used twice as a key for the same map.
It is requested that IANA assign a new tag from the "Concise Binary
Object Representation (CBOR) Tags" registry.  It is requested that
the tag be assigned in the 0 to 23 value range.
It is requested that IANA create a new registry entitled "COSE Header
Key".
This table is initially populated by the table in Top-Level-Keys.
It is requested that IANA create a new registry entitled "COSE Header
Labels".
This is the value used for the key.  The key can be either an
integer or a string.  Registration in the table is based on the
value of the key requested.  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 first come first server.  Integer values in the
range -1 to -65536 are delegated to the "COSE Header Algorithm
Key" 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 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 first come first server.  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.
It is requested that IANA create a new registry entitled "COSE Header
Algorithm Keys".
It is requested that IANA create a new registry entitled "COSE Header
Algorithm Labels".
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, key pair MUST be unique.
This is the value used for the key.  The key is an integer in the
range of -1 to -65536.
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.
This is the value used for the label.  The label is an integer in
the range of -1 to -65536.
The value to be used to identify this algorithm.  Algorithm keys
MUST be unique.  The key 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
first come first server.  Integer values in the range -1 to -65536
are delegated to the "COSE Header Algorithm Key" registry.
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 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
first come first server.  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.
It is requested that IANA create a new registry entitied "COSE Key
Map Registry".
It is requested that IANA create a new registry entitled "COSE Key
Map Registry".
The value to be used to identify this algorithm.  Algorithm keys
MUST be unique.  The key 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
first come first server.  Integer values in the range -1 to -65536
are used for key parameters specific to a single algoirthm
delegated to the "COSE Key Parameter Key" registry.  Integer
values beyond -65536 are marked as private use.
The value to be used to identify this algorithm.  Algorithm 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
first come first server.  Integer values in the range -1 to -65536
are used for key parameters specific to a single algorithm
delegated to the "COSE Key Parameter Label" registry.  Integer
values beyond -65536 are marked as private use.
This registry will be initially populated bythe values in
COSE_KEY_KEYS.  The specification column for all of these entries
will be this document.
This registry will be initially populated by the values in
COSE_KEY_KEYS.  The specification column for all of these entries
will be this document.
The key is to be unqiue for every value of key type.  The range of
values is from -256 to -1.  Keys are expected to be re-used for
different keys.
The label is to be unique for every value of key type.  The range
of values is from -256 to -1.  Labels are expected to be re-used
for different keys.
This registry will be initially populated bythe values in
COSE_KEY_PARAM_KEYS.  The specification column for all of these
entries will be this document.
This registry will be initially populated by the values in
COSE_KEY_PARAM_KEYS.  The specification column for all of these
entries will be this document.
This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry.  [CREF9] These
media types are used to indicate that the content is a COSE_MSG.
This section registers the "application/jwk+json" and "application/
jwk-set+json" media typesin the "Media Types" registry.  These media
types are used to indicate, respectively, that content is a COSE_Key
or COSE_KeySet object.
Use of direcct ECDH direct encryption is easy for people to leak
information on if there are other recipients in the message.
Use of direct ECDH direct encryption is easy for people to leak
information on if there are other recipients in the message.
Considerations about protected vs unprotected header fields.