Draft: draft-ietf-cose-msg

Commentary: Finish the pass on algorithm identification Update the examples to match some of changes we made here .
M00TODO: Make a determination of which ones get 1-, 2- or 3-byte
identifiers.  I.e. which ones are going to be popular.
ChaCha20 and Poly1305 combined together is a new AEAD mode that is
defined in RFC7539.  This is a new mode defined to be a cipher which
is not AES and thus would not suffer from any future weaknesses found
in AES.  These cryptographic functions are designed to be fast in
software only implementations.
The ChaCha20/Poly1305 AEAD construction defined in RFC7539 has no
parameterization.  It takes a 256-bit key and an a 96-bit nonce as
well as the plain text and additional data as inputs and produces the
cipher text as an option.  We define one algorithm identifier for
this algorithm in Table-CHACHA.
The pair of key, nonce MUST be unique for every invocation of the
algorithm.  Nonce counters are considered to be an acceptable way of
ensuring that they are unique.
context information - Information that describes the context in
which the resulting value will be used.  Making this information
specific to the context that the material is going to be used
ensures that the resulting material will always be unique.
context information - Information that describes the context in
which the resulting value will be used.  Making this information
specific to the context that the material is going to be used
ensures that the resulting material will always be unique.  The
context structure used is encoded into the algorithm identifier.
HKDF is defined to use HMAC as the underlying PRF.  However, it is
possible to use other functions in the same construct to provide a
different KDF function that may be more appropriate in the
constrained world.  Specifically, one can use AES-CBC-MAC as the PRF
for the expand step, but not for the extract step.  When using a good
random shared secret of the correct length, the extract step can be
skipped.  The extract cannot be skipped if the secret is not
uniformly random, for example if it is the result of a ECDH key
agreement step.
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
stand alone store and forward messaging processes.
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
stand alone 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.
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 identity value supplied will be validated as part of the
key derivation process.  If the identity string is wrong, then
the wrong key will be created.
This contains a one time nonce value.  The nonce can either be
implicit from the protocol or carried as a value in the
unprotected headers.  [CREF14]
We define an algorithm parameter 'PartyU nonce' that can be
used to carry this value in the message However, the nonce
value could be determined by the application and the value
determined from elsewhere.
This item is optional and can be absent.
The identity value supplied will be integrity checked as part
of the key derivation process.  If the identity string is
wrong, then the wrong key will be created.
This contains a one time nonce value.  The nonce can either be
implicit from the protocol or carried as a value in the
unprotected headers.
We define an algorithm parameter 'PartyU nonce' that can be
used to carry this value in the message However, the nonce
value could be determined by the application and the value
determined from elsewhere.
This item is optional and can be absent.
This is set to the number of bits of the desired output value.
This key management technique is the simplest method, the supplied
key is directly used as the key for the next layer down in the
message.  There are no algorithm parameters defined for this key
management methods.
This key managment takes a common shared secret between the two
parties and applies the HKDF function (HKDF) using the context
structure defined in context to transform the shared secret into
the necessary key.  Either the 'salt' parameter of HKDF or the
partyU 'nonce' parameter of the context structure MUST be present.
This parameter can be generated either randomly or
deterministically, the requirement is that it be a unique value
for the key pair in question.
If the salt/nonce value is generated randomly, then it is
suggested that the length of the random value be the same length
as the hash function underlying HKDF, i.e 256-bits.  While there
is no way to guarantee that it will be unique, there is a high
probability that it will be unique.  If the salt/nonce value is
generated deterministically, it can be guaranteed to be unique and
thus there is no length requirement.
This key management technique is the simplest method, the supplied
key is directly used as the key for the next layer down in the
message.  There are no algorithm parameters defined for this key
management methods.  The algorithm identifier assignment can be found
in table-direct.
These keys need to have some method to be regularly updated over
time.  All of the content encryption algorithms specified in this
document have limits on how many times a key can be used without
significant loss of security.
These keys need to be dedicated to a single algorithm.  There have
been a number of attacks developed over time when a single key is
used for multiple different algorithms.  One example of this is
the use of a single key both for CBC encryption mode and CBC-MAC
authentication mode.
Breaking one message means all messages are broken.  If an
adversary succeeds in determining the key for a single message,
then the key for all messages is also determined.
This key managment takes a common shared secret between the two
parties and applies the HKDF function (HKDF) using the context
structure defined in context to transform the shared secret into the
necessary key.  Either the 'salt' parameter of HKDF or the partyU
'nonce' parameter of the context structure MUST be present.  This
parameter can be generated either randomly or deterministically, the
requirement is that it be a unique value for the key pair in
question.
If the salt/nonce value is generated randomly, then it is suggested
that the length of the random value be the same length as the hash
function underlying HKDF, i.e 256-bits.  While there is no way to
guarantee that it will be unique, there is a high probability that it
will be unique.  If the salt/nonce value is generated
deterministically, it can be guaranteed to be unique and thus there
is no length requirement.
Since with this technique a new key can be generated for every
message, the restrictions on IVs can frequently be relaxed.  For the
content encryption algorithms used in this document IVs must be
unique for a specific key.  If the key is altered then the IV can be
re-used.  Alternatively, an application can be the IV be generated
from the same context as the key is by changing the algorithm
identifier to the string "IV-GENERATION".
The set of algorithms defined in this document can be found in table-
direct-kdf.
The AES Key Wrapping 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.  [CREF15] 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.
There are no specific security considerations for this algorithm.
The AES Key Wrapping 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.  [CREF14] 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.
It is highly recommended that checks on the key length be done before
starting a decryption operation.  One potential denial of service
operation is to provide encrypted objects using either abnormally
long or oddly sized RSA modulus values.  Implementations SHOULD be
able to encrypt and decrypt with modulus between 2048 and 16K bits in
length.[CREF16] Applications can impose additional restrictions on
the length of the modulus.
It is highly recommended that checks on the key length be done before
starting a decryption operation.  One potential denial of service
operation is to provide encrypted objects using either abnormally
long or oddly sized RSA modulus values.  Implementations SHOULD be
able to encrypt and decrypt with modulus between 2048 and 16K bits in
length.[CREF15] Applications can impose additional restrictions on
the length of the modulus.
Ephemeral-Static DH: where the sender of the message creates a one
time DH key and uses a static key for the recipient.  The use of
the ephemeral sender key means that no additional random input is
needed as this is randomly generated for each message.
When direct key agreement mode is used, it MUST be the only key
management mode used on the message and there MUST be only one
recipient.  This method creates the key directly and that makes it
difficult to mix with additional recipients.  If multiple recipients
are needed, then the version with key wrap (ECDH-KeyWrap) needs to be
used.
When direct key agreement mode is used, it MUST be the only key
management mode used on the message and there MUST be only one
recipient.  This method creates the key directly and that makes it
difficult to mix with additional recipients.  If multiple recipients
are needed, then the version with key wrap needs to be used.
NOTE: Curves 25519 and Goldilocks are elements at risk.
We setup to use two different curve structures for the ECDH
algorithms.
Weierstrass Curves: These are the ones one is used to seeing from
NIST.  We define three NIST curves for use with this document.
These curves are P-256, P-384 and P-512.  (The mathematics can be
found in RFC6090.)  For these curves, the key type 'EC2' is used
(EC2-Keys).
Montgomery Curves: These curves are Curve25519 and Goldilocks.
(The mathematics can be found in I-D.irtf-cfrg-curves.)  For these
curves, the key type 'EC1' is used (EC1-Keys).
This parameter is used to hold and transport the ephemeral key
generated by the sender of the message.  This parameter has a
label of -1 and a type of COSE_Key.  This parameter can be
placed in the unprotected bucket, if it is changed then the
correct key will not be able to be generated.
The parameter is summarized in table-ecdh-es-parameter-table.
This parameter is used to hold and transport the static key
used by the sender of the message.  This parameter has the
label of -2 and a type of COSE_Key.  The parameter can be
placed in the unprotected bucket, if it is changed then the
correct key will not be able to be generated.  If the data
origination service is desired, then the message recipient
needs to validate that the key in this field is associated with
the sender.
This parameter is used to hold a reference to the static key
used by the sender of the message.  The value is expected to
match the 'kid' member of a COSE_Key structure published by the
sender.  The value in this field cannot be assumed to uniquely
identify a single key, multiple keys may need to be found and
tested.  Not all of the keys identified by a kid value may be
associated with the sender of the message.  If the data
origination service is desired, then the message recipient
needs to validate that the key in this field is associated with
the sender.
These parameters are summarized in table-ecdh-es-parameter-table.
M00TODO: Talk about curves and point formats.
The basic mathematics for Elliptic Curve Diffie-Hellman can be found
in RFC6090.  Two new curves have been defined in I-D.irtf-cfrg-
curves.
Curve Type/Curve: The curve selected controls not only the size of
the shared secret, but the mathematics for computing the shared
secret.  The curve selected also controls how a point in the curve
is represented and what happens for the identity points on the
curve.  In this specification we allow for a number of different
curves to be used.  The curves are defined in table-ec-curves.
Since the only the math is changed by changing the curve, the
curve is not fixed for any of the algorithm identifiers we define,
instead it is defined by the points used.
Key derivation algorithm: The result of an ECDH key agreement
process does not provide a uniformly random secret, as such it
needs to be run through a KDF in order to produce a usable key.
Processing the secret through a KDF also allows for the
introduction of both context material, how the key is going to be
used, and one time material in the even to of a static-static key
agreement.
Key Wrap algorithm: The key wrap algorithm can be 'none' if the
result of the KDF is going to be used as the key directly.  This
option, along with static-static, should be used if knowledge
about the sender is desired.  If 'none' is used then the content
layer encryption algorithm size is value fed to the context
structure.  Support is also provided for any of the key wrap
algorithms defined in section key_wrap_algs.  If one of these
options is used, the input key size to the key wrap algorithm is
the value fed into the context structure as the key size.
The set of algorithms direct ECDH defined in this document are found
in table-ecdh-es-table.
These algorithms are defined in table-ecdh-es-table.
contains an identifier of the curve to be used with the key.
[CREF20] 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.
[CREF18] 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 the x coordinate for the EC point.  The octet string
represents a little-endian encoding of x.
This section registers the "application/cose" and "application/
cose+cbor" media types in the "Media Types" registry.  [CREF25] 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.  [CREF22] These
media types are used to indicate that the content is a COSE_MSG.