Draft: draft-schaad-cose

Commentary: This fleshes out the change discussed on the mailing list . I believe the improvement of a clear separation between the two concepts is massive .
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 unsigned and
negative integers) as map keys, as well as data items to identify
specific choices.  The (negative and unsigned) integers are used for
compactness of encoding and easy comparison.  Since the word "key" is
mainly used in its other meaning as a cryptographic key, we use the
term "label" for this usage of either an integer or a string to
identify map keys and choice data items.
The top level of each of the COSE message structures are encoded as
arrays.
We use an integer to distinguish between 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 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 the
syntax is for the rest of the elements in the map.
Implementations SHOULD 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.  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.
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.
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 defined can be found in
Header-Table.
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.
We use the values in TOP-Level-Keys as labels in the COSE_Sign map.
While other labels can be present in the map, it is not generally a
recommended practice.  See the note in CBOR-Canonical about options
for allowing or disallowing other labels.
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.
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 labels in the COSE_signature
map.  While other labels can be present in the map, it is not
generally a recommended practice.  See the note in CBOR-Canonical
about options for allowing or disallowing other labels.
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 accommodated 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.
All parsers used SHOULD fail on both parsing and generation if the
same label is used twice as a key for the same map.
While it is permitted to have label 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 accommodated 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 create a new registry entitled "COSE Header
Key".
It is requested that IANA create a new registry entitled "COSE Header
Label".
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 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 delegated to the "COSE Header Algorithm Label" registry.
Integer values beyond -65536 are marked as private use.
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 label parameters specific to a single algoirthm
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 bythe values in
COSE_KEY_labels.  The specification column for all of these entries
will be this document.
The key is to be unique 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 by the 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_labels.  The specification column for all of these
entries will be this document.