Draft: draft-ietf-cose-rfc8152bis-algs

Commentary: Deal with Laurence 's github issue Deal with review from Francesa on capabilities . 
 The protected buckets are sometimes referred to as headers . 
 The first is already covered in . I am not sure that there is any benefit in changing the second . 
 Also , in section 4.4 and 6.3 the protected headers / buckets are referred to as " protected attributes " . When I first read this section , I had to do a bit of deduction to convince myself the protected attributes where the protected headers . It seems this important part of COSE should be explicitly clear . Also , the term " signer structure " could be more explicit by referring to the " signatures " part of the COSE_Sign or some such text . I searched the document for " protected attribute " , " body structure " and " signer structure " to be sure what these were , but the searches did n't help much . Going back to , I think " attribute " is sometimes used to refer to a header parameter and occurrences of it should be checked . 
 done 
 Is a kid , iv , content type ... a " header " , a " parameter " or a " header parameter " ? The textual description of each refers to them as " parameters " -- " This parameter is used to indicate ... " The summarizing table 2 calls them " header parameters " . The paragraph on CDDL and the CDDL refers them as " headers " . I was theorizing that protected and unprotected are headers and kid , iv ... are parameters or header parameters , but that is n't consistent with the text . No ambiguity when implementing , but a little confusing to read . If the official name is " header parameter " and " parameter " is the short name , then the main divergence is the CDDL and CDDL - related text . If the CDDL and CDDL - related text where changed to use " header parameter " it seems like all would be consistent . 
 Done - and I do n't see why it is marked open
The signature algorithm results in a pair of integers (R, S).  These
integers will be the same length as the length of the key used for
the signature process.  The signature is encoded by converting the
integers into bit strings of the same length as the key size.  The
length is rounded up to the nearest byte and is left padded with zero
bits to get to the correct length.  The two integers are then
concatenated together to form a byte string that is the resulting
signature.
The signature algorithm results in a pair of integers (R, S).  These
integers will be the same length as the length of the key used for
the signature process.  The signature is encoded by converting the
integers into byte strings of the same length as the key size.  The
length is rounded up to the nearest byte and is left padded with zero
bits to get to the correct length.  The two integers are then
concatenated together to form a byte string that is the resulting
signature.
The AES Key Wrap algorithm is defined in RFC3394.  This algorithm
uses an AES key to wrap a value that is a multiple of 64 bits.  As
such, it can be used to wrap a key for any of the content encryption
algorithms defined in this document.  The algorithm requires a single
fixed parameter, the initial value.  This is fixed to the value
specified in Section 2.2.3.1 of RFC3394.  There are no public
parameters that vary on a per-invocation basis.  The protected header
field MUST be empty.
The AES Key Wrap algorithm is defined in RFC3394.  This algorithm
uses an AES key to wrap a value that is a multiple of 64 bits.  As
such, it can be used to wrap a key for any of the content encryption
algorithms defined in this document.  The algorithm requires a single
fixed parameter, the initial value.  This is fixed to the value
specified in Section 2.2.3.1 of RFC3394.  There are no public key
parameters that vary on a per-invocation basis.  The protected header
bucket MUST be empty.
Two different types of capabilities are defined: Capabilities for
algorithms and capabilities for key structures.  Once defined by
registration with IANA, the list capabilities is immutable.  As a
general rule, the capabilities are going to correspond to algorithm
or key fields, but they do not need to do so.  An example of this is
the HSS-LMS key capabilities defined below where the hash algorithm
used is included.
There is a presumption in the way that this is laid out is that the
algorithm identifier itself is not needed to be a part of this as it
is specified in a different location.
Two different types of capabilities are defined: Capabilities for
algorithms and capabilities for key structures.  Once defined by
registration with IANA, the list capabilities is immutable.  If it is
later found that a new capability is needed for a key type or an
algorithm, it will require that a new code point be assigned to deal
with that.  As a general rule, the capabilities are going to map to
algorithm specific header parameters or key parameters, but they do
not need to do so.  An example of this is the HSS-LMS key
capabilities defined below where the hash algorithm used is included.
For the current set of algorithms in the registry, those in this
document as well as those in RFC8230 and I-D.ietf-cose-hash-sig, the
capabilities is set to the single entry of the key type that will be
accepted.  It is expected other algorithms will have no items or
multiple items.
For the current set of algorithms in the registry, those in this
document as well as those in RFC8230 and I-D.ietf-cose-hash-sig, the
capabilities is set to the single entry of the key type (from the
"COSE Key Types" Registry) that will be accepted.  It is expected
future registered algorithms could have zero, one, multiple items.
In this section a trio of examples are provided.  In all three cases
the pair of capabilities is always provided as the algorithm and then
the key capabilities.  For simplicity's sake, a CBOR sequence I-
D.ietf-cbor-sequence is used for the two arrays.
IANA is requested to create a new column in the "COSE Key Types"
registry.  The new column is to be labeled "Capabilities".  The new
column is to be populated according the the entries in initial-kty-
caps.
IANA is requested to create a new column in the "COSE Algorithms"
registry.  The new column is to be labeled "Capabilities".  The new
column is populated with "kty" for all current, non-provisional,
registrations.  It is expected that the documents which define those
algorithms will be expanded to include this registration, if this is
not done then the DE should be consulted at the time of final
registration.
IANA is requested to create a new column in the "COSE Key Types"
registry.  The new column is to be labeled "Capabilities".  The new
column is to be populated according the entries in initial-kty-caps.
IANA is requested to create a new column in the "COSE Algorithms"
registry.  The new column is to be labeled "Capabilities".  The new
column is populated with "[kty]" for all current, non-provisional,
registrations.  It is expected that the documents which define those
algorithms will be expanded to include this registration, if this is
not done then the DE should be consulted final registration for this
document is done.
IANA is requested to update the reference column in the "COSE
Algorithms" registry to include  as a reference for
all rows where it is not already present.  Note to IANA: There is an
action in I-D.ietf-cose-rfc8152bis-struct which also modifies data in
the reference column.  That action should be applied first.
IANA is required to modify the description to "Public Key" for the
line with "Key Type" of 2 and the "Name" of "x".  See x-table-
ec1-keys which has been modified with this change.
One feature that is present in CMS RFC5652 that is not present in
this standard is a digest structure.  This omission is deliberate.
It is better for the structure to be defined in each document as
different protocols will want to include a different set of fields as
part of the structure.  While an algorithm identifier and the digesst
value are going to be common to all applications, the two values may
not always be adjacent as the algorithm could be defined once with
multiple values.  Applications may additionally want to define
additional data fields as part of the stucture.  A common structure
is going to include a URI or other pointer to where the data that is
being hashed is kept, allowing this to be application specific.
There was not a standard CBOR grammar available when COSE was
originally written.  For that reason the CBOR structures defined here
are described in prose.  Since that time CBOR Data Definition
Language (CDDL) RFC8610 has been published as an RFC.  The CBOR
grammar presented in this document is compatible with CDDL.
One feature that is present in CMS RFC5652 that is not present in
this standard is a digest structure.  This omission is deliberate.
It is better for the structure to be defined in each document as
different protocols will want to include a different set of fields as
part of the structure.  While an algorithm identifier and the digest
value are going to be common to all applications, the two values may
not always be adjacent as the algorithm could be defined once with
multiple values.  Applications may additionally want to define
additional data fields as part of the structure.  A common structure
is going to include a URI or other pointer to where the data that is
being hashed is kept, allowing this to be application specific.
There was not a standard CBOR grammar available when COSE was
originally written.  For that reason the CBOR data objects defined
here are described in prose.  Since that time CBOR Data Definition
Language (CDDL) RFC8610 has been published as an RFC.  The CBOR
grammar presented in this document is compatible with CDDL.
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.  The inclusion of strings allows for an
additional range of short encoded values to be used as well.  Since
the word "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 COSE map that is not a string or an
integer is an error.  Applications can either fail processing or
process messages by ignoring incorrect labels; however, they MUST NOT
create messages with incorrect labels.
In JSON, maps are called objects and only have one kind of map key: a
text string.  In COSE, we use text strings, negative integers, and
unsigned integers as map keys.  The integers are used for compactness
of encoding and easy comparison.  The inclusion of text strings
allows for an additional range of short encoded values to be used as
well.  Since the word "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 CBOR map that is not a text string or an
integer is an error.  Applications can either fail processing or
process messages by ignoring incorrect labels; however, they MUST NOT
create messages with incorrect labels.
Context is used throughout the document to represent information that
is not part of the COSE message.  Information which is part of the
context can come from several different sources including: Protocol
interactions, associated key structures and program configuration.
The context to use can be implicit, identified using the 'kid
context' header field defined in RFC8613, or identified by a protocol
specific identifier.  Context should generally be included in the
cryptographic configuration, for more details see Extern_AAD.
Context is used throughout the document to represent information that
is not part of the COSE message.  Information which is part of the
context can come from several different sources including: Protocol
interactions, associated key structures and program configuration.
The context to use can be implicit, identified using the 'kid
context' header parameter defined in RFC8613, or identified by a
protocol specific identifier.  Context should generally be included
in the cryptographic configuration, for more details see Extern_AAD.
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 have been divided into several sections
including 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).
Only parameters that deal with the current layer are to be placed at
that layer.  As an example of this, the parameter 'content type'
describes the content of the message being carried in the message.
As such, this parameter is placed only in the content layer and is
not placed in the recipient or signature layers.  In principle, one
should be able to process any given layer without reference to any
other layer.  With the exception of the COSE_Sign structure, the only
data that needs to cross layers is the cryptographic key.
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.
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 verify that the same label does not
occur in both the protected and unprotected headers.  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 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 common headers.
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.
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.
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 text string values for labels have been divided into several
sections including 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).
Only header parameters that deal with the current layer are to be
placed at that layer.  As an example of this, the header parameter
'content type' describes the content of the message being carried in
the message.  As such, this header parameter is placed only in the
content layer and is not placed in the recipient or signature layers.
In principle, one should be able to process any given layer without
reference to any other layer.  With the exception of the COSE_Sign
structure, the only data that needs to cross layers is the
cryptographic key.
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 header
parameters that go into the buckets come from the IANA "COSE Header
Parameters" registry (cose-header-key-table).  Some common header
parameters are defined in the next section.
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 verify that the same label does not
occur in both the protected and unprotected header parameters.  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 parameter
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 common header parameters.
This section defines a set of common header parameters.  A summary of
these header parameters can be found in Header-Table.  This table
should be consulted to determine the value of label and the type of
the value.
The CDDL fragment that represents the set of header parameters
defined in this section is given below.  Each of the header
parameters is tagged as optional because they do not need to be in
every map; header parameters required in specific maps are discussed
above.
The COSE_Sign structure allows for one or more signatures to be
applied to a message payload.  Parameters relating to the content and
parameters relating to the signature are 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
and counter signatures.
The COSE_Sign structure allows for one or more signatures to be
applied to a message payload.  Header parameters relating to the
content and header parameters relating to the signature are carried
along with the signature itself.  These header parameters may be
authenticated by the signature, or just present.  An example of
header a parameter about the content is the content type.  Examples
of a header parameters about the signature would be the algorithm and
key used to create the signature and counter signatures.
The COSE_Sign1 signature structure is used when only one signature is
going to be placed on a message.  The parameters dealing with the
content and the signature are placed in the same pair of buckets
rather than having the separation of COSE_Sign.
The COSE_Sign1 signature structure is used when only one signature is
going to be placed on a message.  The header parameters dealing with
the content and the signature are placed in the same pair of buckets
rather than having the separation of COSE_Sign.
One of the features offered in the COSE document is the ability for
applications to provide additional data to be authenticated, 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 or CoAP options.  If the data is in the header
section, then it is available for proxies to help in performing its
operations.  For example, the Accept Option can be used by a proxy to
determine if an appropriate value is in the proxy's cache.  But the
sender can cause a failure at the server if a proxy, or an attacker,
changes the set of accept values by including the field in the
application supplied data.
One of the features offered in the COSE document is the ability for
applications to provide additional data to be authenticated, 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 or CoAP options.  If the data is in the
headers of the CoAP message, then it is available for proxies to help
in performing its operations.  For example, the Accept Option can be
used by a proxy to determine if an appropriate value is in the
proxy's cache.  But the sender can cause a failure at the server if a
proxy, or an attacker, changes the set of accept values by including
the field in the application supplied data.
The byte string representing the signature value is placed in the
CounterSignature0 attribute.  This attribute is then encoded as an
unprotected header.  The attribute is defined below.
The byte string representing the signature value is placed in the
CounterSignature0 attribute.  This attribute is then encoded as an
unprotected header parameter.  The attribute is defined below.
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 enveloped structure allows for one or more recipients of a
message.  There are provisions for header parameters about the
content and header parameters about the recipient information to be
carried in the message.  The protected header parameters associated
with the content are authenticated by the content encryption
algorithm.  The protected header parameters associated with the
recipient are authenticated by the recipient algorithm (when the
algorithm supports it).  Examples of header parameters about the
content are the type of the content and the content encryption
algorithm.  Examples of header parameters about the recipient are the
recipient's key identifier and the recipient's encryption algorithm.
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.KeyParameters).
A COSE Key structure is built on a CBOR map.  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.KeyParameters).
Signature algorithms provide data origination and data integrity
services.  Data origination provides the ability to infer who
originated the data based on who signed the data.  Data integrity
provides the ability to verify that the data has not been modified
since it was signed.
The registeries and registrations listed below were created during
processing of RFC 8152 RFC8152.  The only known action at this time
is to update the references.
The registries and registrations listed below were created during
processing of RFC 8152 RFC8152.  The only known action at this time
is to update the references.