Draft: draft-schaad-cose

Commentary: Start a design changes section - I do n't know if this will last or should go nto an appendix instead Correct description on signature - it is now an array and not a map Expand description for encryption section . Add new sections describing each of the key management methods
We switched from using a map to using an array at the message
level.  While this change means that it is no longer possible to
add new information in the form of new fields to the message
object, this ability is still there as this data can be added to
the protected and unprotected maps.
In this section we describe the structure and methods to be used when
doing an encryption in COSE.  In COSE, we use the same techniques and
structures for encrypting both the plain text and the keys used to
protect the text.  This is different from the approach used by both
CMS and JWE where different structures are used both for the plain
text and for the different key management techniques.
In this section we describe the structure and methods to be used when
doing an encryption in COSE.  In COSE, we use the same techniques and
structures for encrypting both the plain text and the keys used to
protect the text.  This is different from the approach used by both
CMS and I-D.ietf-jose-json-web-encryption where different structures
are used both for the plain text and for the different key management
techniques.
The structure has two bags where data about the content can be
placed.  The data placed here is also the data which is used to
control how the decryption is to be done for this object.  When data
is placed in these two structures, it is extremely poor practice to
have data which is applicable to a different level.  For example, the
unprotected field at the level of a key management decryption should
not contain information either about how to interpret the plain text
(i.e. content type) or how to convert the cipher text back to plain
text (i.e. the kid for the recipient).
The structure has two maps where data about the content can be
placed.  The data placed here is also the data which is used to
control how the decryption is to be done for this object.  When data
is placed in these two structures, it is extremely poor practice to
have data which is applicable to a different level.  For example, the
unprotected field at the level of a key management decryption should
not contain information either about how to interpret the plain text
(i.e. content type) or how to convert the cipher text back to plain
text (i.e. the kid for the recipient).
The header parameters discussed here are taken from JWE.  For the
most part they are interpreted the same here as for JOSE.
contains the information about the plain text or encryption
process that is to be integrity protected.  The field is encoded
in CBOR as a 'bstr' if present and the value 'null' if there is no
data.  The contents of the protected field is a CBOR map of the
protected data names and values.  The map is CBOR encoded before
placing it into the bstr.
contains infomration about the plain text that is not integrity
protected.  If there are no field, then the value 'null' is used.
contains the initialization vector (IV), or it's equivalent, if
one is needed by the encryption algorithm.  If there is no IV,
then the value 'null' is used.
contains additional authenticated data (aad) supplied by the
application.  This field contains information about the plain text
data that is authenticated, but not encrypted.  If the application
does not provide this data, the value 'null' 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 value 'null'
is encoded here.
The header parameters discussed here are taken from I-D.ietf-jose-
json-web-encryption.  For the most part they are interpreted the same
here as for JOSE.
There are a number of header fields defined in JWE which are not
used.  These include PUT THE LIST OF UNUSED ITEMS HERE.  Includes
'enc'?
There are a number of header fields defined in I-D.ietf-jose-json-
web-encryption which are not used.  These include PUT THE LIST OF
UNUSED ITEMS HERE.  Includes 'enc'?
There are a number of different key management methods that can be
used in the COSE encryption system.  In this section we will discuss
each of the key management methods and what fields need to be
specified to deal with each of them.
The names of the key management methods used here are the same as are
defined in I-D.ietf-jose-json-web-key.  Other specifications use
different terms for the key management methods or do not support some
of the key management methods.
In direct encryption mode, a shared secret between the sender and the
recipient is used as the CEK.  For direct encryption mode, no
recipient structure is built.  All of the information about the key
is placed in either the protected or unprotected fields at the
content level.  When direct encryption mode is used, it MUST be the
only mode used on the message.  It is a massive security leak to have
both direct encryption and a different key management mode on the
same message.
For JOSE, direct encryption key management is the only key management
method allowed for doing MAC-ed messages.  In COSE, all of the key
management methods can be used for MAC-ed messages.
In key wrapping mode, the CEK is randomly generated and that key is
then encrypted by a shared secret between the sender and the
recipient.  All of the currently defined key wrapping algorithms for
JOSE (and thus for COSE) are AE algorithms.  Key wrapping mode is
considered to be superior to direct encryption if the system has any
capability for doing random key generation.  This is because the
shared key is used to wrap random data rather than data has some
degree of organization and may in fact be repeating the same content.
The 'protected', 'aad', and 'recipients' fields MUST be null.
At a minimum, the 'unprotected' field SHOULD contain the 'alg'
parameter as well as a parameter identifying the shared secret.
Use of the 'iv' field will depend on the key wrap algorithm.
Key Encryption mode is also called key transport mode in some
standards.  Key Encryption mode differs from Key Wrap mode in that it
uses an asymmetric encryption algorithm rather than a symmetric
encryption algorithm to protect the key.  The only current Key
Encryption mode algorithm supported is RSAES-OAEP.
At a minimum, the 'unprotected' field SHOULD contain the 'alg'
parameter as well as a parameter identifying the asymmetric key.
Direct Key Agreement derives the CEK from the shared secret computed
by the key agreement operation.  For Direct Key Agreement, no
recipient structure is built.  All of the information about the key
and key agreement process is placed in either the 'protected' or
'unprotected' fields at the content level.
When direct key agreement mode is used, it MUST be the only mode used
on the message.  It is a security leak to have both direct key
agreement and a different key management mode on the same message.
Key Agreement with Key Wrapping uses a randomly generated CEK.  The
CEK is then encrypted using a Key Wrapping algorithm and a key
derived from the shared secret computed by the key agreement
algorithm.
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.
Construct the octet string to be used as the AAD value for the
AEAD algorithm: Concatenate the values in the protected and aad
fields after applying the CBOR bstr encoding to them.
For each recipient of the message, recursively perform the
encryption algorithm for that recipient using the encryption key
as the plain text.
For recipient of the message, recursively perform the encryption
algorithm for that recipient using the encryption key as the plain
text.
For COSE we use the same set of fields that were defined in JWK.
For COSE we use the same set of fields that were defined in I-D.ietf-
jose-json-web-key.