Draft: draft-ietf-cose-msg

Commentary: Address comments from Ilari in the document . Note the comments from Hannes in the document . Start shifting the CDDL so it looks less normative .
There currently is no standard CBOR grammar available for use by
specifications.  We therefore describe the CBOR structures in prose.
There is a version of a CBOR grammar in the CBOR Data Definition
Language (CDDL) I-D.greevenbosch-appsawg-cbor-cddl.  An informational
version of the CBOR grammar that reflects what is in the prose can be
found in Grammar_Appendix.  CDDL has not been fixed, so this grammar
may will only work with the version of CDDL at the time of
publishing.
bstr - byte string (major type 2).
int - an unsigned integer or a negative integer.
nil - a null value (tag 7.22).
nint - a negative integer (major type 1).
tstr - a UTF-8 text string (major type 3).
uint - an unsigned integer (major type 0).
NOTE: For the purposes of review, we are currently interlacing the
CDLL grammar into the text of document.  This is being done for
simplicity of comparision of the grammar againist the prose.  The
grammar will be removed to an appendix during WGLC.
Each of the top-level security objects use a CBOR array as the base
structure.
Implementations MUST be prepared to find an integer in this field
that does not correspond to the values 1 to 3.  If this is found then
the client MUST stop attempting to process 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
arrays.
Implementations MUST be prepared to find an integer in this field
that does not correspond to the values 1 to 3.  If a message type is
found then the client does not support the associated security
object, the client MUST stop attempting to process the structure and
fail.  The value of 0 is reserved and not assigned to a security
object.  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 the security
object might be.
The presence of both buckets is required.  The parameters that go
into the buckets come from the IANA "COSE Header Parameters" (cose-
header-key-table).  Some common parameters are defined in the next
section, but a number of parameters are defined throughout this
document.
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"
(cose-header-key-table).  Some common parameters are defined in the
next section, but a number of parameters are defined throughout this
document.
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.  The value is
taken from the 'COSE Algorithm Registry' (see IANA-Alg-Registry).
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.  The value is
taken from the 'COSE Algorithm Registry' (see cose-algorithm-
registry).
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, it is the responsibility of the
application to ensure that it will be transported without changes.
contains the computed signature value.
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.
contains the computed signature value.  The type of the field is a
bstr.
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.
The body protected attributes.  This is a bstr type containing the
protected attributes of the body.
The signature protected attributes.  This is a bstr type
containing the protected attributes of the signature.
The external protected attributes.  This is a bstr type containing
the protected attributes external to the COSE_Signature structure.
The payload to be signed.  The payload is encoded in a bstr.  The
payload is placed here independent of how it is transported.
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.
contains the encrypted plain text.  If the ciphertext is to be
transported independently of the control information about the
encryption process (i.e. detached content) then the field is
omitted.
contains the encrypted plain text.  If the ciphertext is to be
transported independently of the control information about the
encryption process (i.e. detached content) then the field is
encoded as a null object.
contains the serialized content to be MACed.  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 it is the responsibility of the application
to ensure that it will be transported without changes.
contains the serialized content to be MACed.  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 null CBOR object is placed in this
location and it is the responsibility of the application to ensure
that it will be transported without changes.
This parameter is used to identify the family of keys for this
structure, and thus the set of key type specific parameters to be
found.  The set of values can be found in table_key_types.  This
parameter MUST be present in a key object.
This parameter is used to identify the family of keys for this
structure, and thus the set of key type specific parameters to be
found.  The set of values can be found in table_key_types.  This
parameter MUST be present in a key object.  Implementations MUST
verify that the key type is appropriate for the algorithm being
processed.  The key type MUST be included as part of a trust
decision process.
In order to promote interoperability, it is suggested that SHA-256 be
used only with keys of length 256, SHA-384 be used only with keys of
length 384 and SHA-512 be used only with keys of length 521.  This is
aligned with the recommendation in Section 4 of RFC5480.
This document defines ECDSA to work only with the curves P-256, P-384
and P-521.  This document requires that the curves be encoded using
the 'EC2' key type.  Implementations need to check that the key type
and curve are correct when creating and verifying a signature.  Other
documents can defined it to work with other curves and points in the
future.
In order to promote interoperability, it is suggested that SHA-256 be
used only with curve P-256, SHA-384 be used only with curve P-384 and
SHA-512 be used with curve P-521.  This is aligned with the
recommendation in Section 4 of RFC5480.
Changing the curve used to validate the signature: If one changes
the curve used to validate the signature, then potentially one
could have a two messages with the same signature each computed
under a different curve.  The only requirement on the new curve is
that it's order be the same as the old one and it be acceptable to
the client.  An example would be to change from using the curve
P-256 to using Curve25519.  (Both are 256 bit curves.)  We current
do not have any way to deal with this version of the attack except
to restrict the overall set of curves that can be used.
Changing the curve used to validate the signature: If one changes
the curve used to validate the signature, then potentially one
could have a two messages with the same signature each computed
under a different curve.  The only requirement on the new curve is
that it's order be the same as the old one and it be acceptable to
the client.  An example would be to change from using the curve
secp256r1 (aka P-256) to using secp256k1.  (Both are 256 bit
curves.)  We current do not have any way to deal with this version
of the attack except to restrict the overall set of curves that
can be used.
Implementations need to check that the key type is 'RSA' when
creating or verifying a signature.
If the key obtained from a key structure, the key type MUST be
'Symmetric'.  Implementations creating and validating MAC values MUST
validate that the key type, key length and algorithm are correct and
appropriate for the entities involved.
The context information structure is used to ensure that the derived
keying material is "bound" to the context of the transaction.  The
context information structure used here is based on that defined in
SP800-56A.  By using CBOR for the encoding of the context information
structure, we automatically get the same type of type and length
separation of fields that is obtained by the use of ASN.1.  This
means that there is no need to encode the lengths for the base
elements as it is done by the CBOR encoding.
The context information structure refers to PartyU and PartyV as the
two parties which are doing the key derivation.  Unless the
application protocol defines differently, we assign PartyU to the
entity that is creating the message and PartyV to the entity that is
receiving the message.  This is because we are assuming a set of
standalone store and forward messaging processes.  In SP800-56A,
PartyU is the initiator and PartyV is the responder.  The
specification is written with the idea of on-line protocols rather
than store and forward protocols as the main consumer.
The context information structure refers to PartyU and PartyV as the
two parties which are doing the key derivation.  Unless the
application protocol defines differently, we assign PartyU to the
entity that is creating the message and PartyV to the entity that is
receiving the message.  By doing this association, different keys
will be derived for each direction as the context information is
different in each direction.
Using the PartyU and PartyV fields is the easiest way to get
different keys in each direction.  The use of a transaction
identifier, either in one of the supplemental fields or as the salt
if one is using HKDF, ensures that a unique key is generated for each
set of transactions.  Combining nonce fields with the transaction
identifier provides a method so that a different key is used for each
message in each direction.
The use of a transaction identifier, either in one of the
supplemental fields or as the salt if one is using HKDF, ensures that
a unique key is generated for each set of transactions.  Combining
nonce fields with the transaction identifier provides a method so
that a different key is used for each message in each direction.
When this algorithm is used, the protected field MUST be zero length.
When this algorithm is used, the protected field MUST be zero length.
The key type MUST be 'Symmetric'.
When these algorithms are used, the key type MUST be 'symmetric'.
The key type MUST be 'RSA'.
This document defines these algorithms to be used with the curves
P-256, P-384, P-521, X25519 and X448.  Implementations MUST verify
that the key type and curve are correct, different curves are
restricted to different key types.  Implementations MUST verify that
the curve and algorithm are appropriate for the entities involved.
Two different key structures are being defined for Elliptic Curve
keys.  One version uses both an x and a y coordinate, potentially
with point compression.  This is the traditional EC point
representation that is used in RFC5480.  The other version uses only
the x coordinate as the y coordinate is either to be recomputed or
not needed for the key agreement operation.  An example of this is
Curve25519 I-D.irtf-cfrg-curves.
contains an identifier of the curve to be used with the key.
[CREF10] The curves defined in this document for this key type can
be found in table-ec-curves.  Other curves may be registered in
the future and private curves can be used as well.
contains an identifier of the curve to be used with the key.
[CREF13] The curves defined in this document for this key type can
be found in table-ec-curves.  Other curves may be registered in
the future and private curves can be used as well.
This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry.  [CREF13] These
media types are used to indicate that the content is a COSE_MSG.
This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry.  [CREF16] These
media types are used to indicate that the content is a COSE_MSG.
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.