CBOR Encoded Message Syntax
draft-schaad-cose-alg-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | Jim Schaad | ||
| Last updated | 2015-10-17 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-schaad-cose-alg-00
COSE Working Group J. Schaad
Internet-Draft August Cellars
Intended status: Informational October 17, 2015
Expires: April 19, 2016
CBOR Encoded Message Syntax
draft-schaad-cose-alg-00
Abstract
More Alg and Headers for COSE.
Contributing to this document
The source for this draft is being maintained in GitHub. Suggested
changes should be submitted as pull requests at <https://github.com/
cose-wg/cose-algs>. Instructions are on that page as well.
Editorial changes can be managed in GitHub, but any substantial
issues need to be discussed on the COSE mailing list.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 19, 2016.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
Schaad Expires April 19, 2016 [Page 1]
Internet-Draft CBOR Encoded Message Syntax October 2015
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Terminology . . . . . . . . . . . . . . . . 3
1.2. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Document Terminology . . . . . . . . . . . . . . . . . . 4
2. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 4
2.1. RSASSA-PSS . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1. Security Considerations . . . . . . . . . . . . . . . 6
2.2. Edwards-curve Digital Signature Algorithms (EdDSA) . . . 6
3. Message Authentication (MAC) Algorithms . . . . . . . . . . . 7
4. Content Encryption Algorithms . . . . . . . . . . . . . . . . 7
4.1. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . . 8
4.1.1. Security Considerations . . . . . . . . . . . . . . . 8
5. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 9
6. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 9
6.1. Direct Encryption . . . . . . . . . . . . . . . . . . . . 10
6.1.1. Direct Key with KDF . . . . . . . . . . . . . . . . . 10
6.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 11
6.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 12
6.3.1. RSAES-OAEP . . . . . . . . . . . . . . . . . . . . . 12
6.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 13
6.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 14
6.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 17
6.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 18
6.6. Password . . . . . . . . . . . . . . . . . . . . . . . . 18
6.6.1. PBES2 . . . . . . . . . . . . . . . . . . . . . . . . 18
7. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . . 19
7.1.1. Single Coordinate Curves . . . . . . . . . . . . . . 19
7.2. RSA Keys . . . . . . . . . . . . . . . . . . . . . . . . 20
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
8.1. COSE Header Parameter Registry . . . . . . . . . . . . . 22
8.2. COSE Header Algorithm Label Table . . . . . . . . . . . . 22
8.3. COSE Algorithm Registry . . . . . . . . . . . . . . . . . 22
8.4. COSE Key Common Parameter Registry . . . . . . . . . . . 23
8.5. COSE Key Type Parameter Registry . . . . . . . . . . . . 23
8.6. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 24
9. Security Considerations . . . . . . . . . . . . . . . . . . . 24
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 25
10.1. Normative References . . . . . . . . . . . . . . . . . . 25
10.2. Informative References . . . . . . . . . . . . . . . . . 25
Appendix A. CDDL Grammar . . . . . . . . . . . . . . . . . . . . 28
Schaad Expires April 19, 2016 [Page 2]
Internet-Draft CBOR Encoded Message Syntax October 2015
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 28
B.1. Examples of MAC messages . . . . . . . . . . . . . . . . 29
B.1.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 29
B.1.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 29
B.1.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 30
B.1.4. Multi-recipient MAC message . . . . . . . . . . . . . 31
B.2. Examples of Encrypted Messages . . . . . . . . . . . . . 33
B.2.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 33
B.2.2. Direct plus Key Derivation . . . . . . . . . . . . . 33
B.3. Examples of Signed Message . . . . . . . . . . . . . . . 34
B.3.1. Single Signature . . . . . . . . . . . . . . . . . . 34
B.3.2. Multiple Signers . . . . . . . . . . . . . . . . . . 35
B.4. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 36
B.4.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 36
B.4.2. Private Keys . . . . . . . . . . . . . . . . . . . . 38
Appendix C. Document Updates . . . . . . . . . . . . . . . . . . 40
C.1. Version -00 . . . . . . . . . . . . . . . . . . . . . . . 40
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 41
1. Introduction
In the process of writing RFCXXXX [I-D.ietf-cose-msg] several items
were removed from that ocument to be addressed at a later date. This
document was created to address those items.
1.1. Requirements Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
When the words appear in lower case, their natural language meaning
is used.
1.2. CBOR Grammar
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 Appendix A. CDDL has not been fixed, so
this grammar may will only work with the version of CDDL at the time
of publishing.
The document was developed by first working on the grammar and then
developing the prose to go with it. An artifact of this is that the
Schaad Expires April 19, 2016 [Page 3]
Internet-Draft CBOR Encoded Message Syntax October 2015
prose was written using the primitive type strings defined by early
versions CDDL. In this specification the following primitive types
are used:
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).
Text from here to start of next section to be removed
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.
start = COSE_Untagged_Message / COSE_Tagged_Message / COSE_Key / COSE_KeySet
1.3. Document Terminology
In this document we use the following terminology: [CREF1]
2. Signature Algorithms
There are two basic signature algorithm structures that can be used.
The first is the common signature with appendix. In this structure,
the message content is processed and a signature is produced, the
signature is called the appendix. This is the message structure used
by our common algorithms such as ECDSA and RSASSA-PSS. (In fact the
SSA in RSASSA-PSS stands for Signature Scheme with Appendix.) The
basic structure becomes:
signature = Sign(message content, key)
valid = Verification(message content, key, signature)
The second is a signature with message recovery. (An example of such
an algorithm is [PVSig].) In this structure, the message content is
Schaad Expires April 19, 2016 [Page 4]
Internet-Draft CBOR Encoded Message Syntax October 2015
processed, but part of is included in the signature. Moving bytes of
the message content into the signature allows for an effectively
smaller signature, the signature size is still potentially large, but
the message content is shrunk. This has implications for systems
implementing these algoritms and for applications that use them. The
first is that the message content is not fully available until after
a signature has been validated. Until that point the part of the
message contained inside of the signature is unrecoverable. The
second is that the security analysis of the strength of the signature
is very much based on the structure of the message content. Messages
which are highly predictable require additional randomness to be
supplied as part of the signature process, in the worst case it
becomes the same as doing a signature with appendix. Thirdly, in the
event that multple signatures are applied to a message, all of the
signature algorithms are going to be required to consume the same
number of bytes of message content.
signature, message sent = Sign(message content, key)
valid, message content = Verification(message sent, key, signature)
At this time, only signatures with appendixes are defined for use
with COSE, however considerable interest has been expressed in using
a signature with message recovery algorithm due to the effective size
reduction that is possible. Implementations will need to keep this
in mind for later possible integration.
2.1. RSASSA-PSS
The RSASSA-PSS signature algorithm is defined in [RFC3447].
The RSASSA-PSS signature algorithm is parametized with a hash
function (h), a mask generation function (mgf) and a salt length
(sLen). For this specification, the mask generation function is
fixed to be MGF1 as defined in [RFC3447]. It has been recommended
that the same hash function be used for hashing the data as well as
in the mask generation function, for this specification we following
this recommendation. The salt length is the same length as the hash
function output.
Implementations need to check that the key type is 'RSA' when
creating or verifying a signature.
The algorithms defined in this document can be found in Table 1.
Schaad Expires April 19, 2016 [Page 5]
Internet-Draft CBOR Encoded Message Syntax October 2015
+-------+-------+---------+-------------+-----------------------+
| name | value | hash | salt length | description |
+-------+-------+---------+-------------+-----------------------+
| PS256 | -26 | SHA-256 | 32 | RSASSA-PSS w/ SHA-256 |
| | | | | |
| PS384 | -27 | SHA-384 | 48 | RSASSA-PSS w/ SHA-384 |
| | | | | |
| PS512 | -28 | SHA-512 | 64 | RSASSA-PSS w/ SHA-512 |
+-------+-------+---------+-------------+-----------------------+
Table 1: RSASSA-PSS Algorithm Values
2.1.1. Security Considerations
In addition to needing to worry about keys that are too small to
provide the required security, there are issues with keys that are
too large. Denial of service attacks have been mounted with overly
large keys. This has the potential to consume resources with
potentially bad keys. There are two reasonable ways to address this
attack. First, a key should not be used for a cryptographic
operation until it has been matched back to an authorized user. This
approach means that no cryptography would be done except for
authorized users. Second, applications can impose maximum as well as
minimum length requirements on keys. This limits the resources
consumed even if the matching is not performed until the cryptography
has been done.
There is a theoretical hash substitution attack that can be mounted
against RSASSA-PSS. However, the requirement that the same hash
function be used consistently for all operations is an effective
mitigation against it. Unlike ECDSA, hash functions are not
truncated so that the full hash value is always signed. The internal
padding structure of RSASSA-PSS means that one needs to have multiple
collisions between the two hash functions in order to be successful
in producing a forgery based on changing the hash function. This is
highly unlikely.
2.2. Edwards-curve Digital Signature Algorithms (EdDSA)
Reference for these is [I-D.irtf-cfrg-eddsa].
The algorithms defined in this document can be found in Table 2.
Schaad Expires April 19, 2016 [Page 6]
Internet-Draft CBOR Encoded Message Syntax October 2015
+---------+-------+-----------------------+
| name | value | description |
+---------+-------+-----------------------+
| Ed25519 | * | EdDSA for Curve 25591 |
| | | |
| Ed488 | * | EdDSA for Curve 448 |
+---------+-------+-----------------------+
Table 2: EdDSA Algorithm Values
3. Message Authentication (MAC) Algorithms
Message Authentication Codes (MACs) provide data authentication and
integrity protection. They provide either no or very limited data
origination. (One cannot, for example, be used to prove the identity
of the sender to a third party.)
MACs are designed in the same basic structure as signature with
appendix algorithms. The message content is processed and an
authentication code is produced, the authentication code is
frequently called a tag. The basic structure becomes:
tag = MAC_Create(message content, key)
valid = MAC_Verify(message content, key, tag)
MAC algorithms can be based on either a block cipher algorithm (i.e.
AES-MAC) or a hash algorithm (i.e. HMAC). This document defines a
MAC algorithm for each of these two constructions.
4. Content Encryption Algorithms
Content Encryption Algorithms provide data confidentialty for
potentially large blocks of data using a symmetric key. They provide
either no or very limited data origination. (One cannot, for
example, be used to prove the identity of the sender to a third
party.) The ability to provide data origination is linked to how the
symmetric key is obtained.
We restrict the set of legal content encryption algorithms to those
which support authentication both of the content and additional data.
The encryption process will generate some type of authentication
value, but that value may be either explicit or implicit in terms of
the algorithm definition. For simplicity sake, the authentication
code will normally be defined as being appended to the cipher text
stream. The basic structure becomes:
Schaad Expires April 19, 2016 [Page 7]
Internet-Draft CBOR Encoded Message Syntax October 2015
ciphertext = Encrypt(message content, key, additional data)
valid, message content = Decrypt(cipher text, key, additional data)
Most AEAD algorithms are logically defined as returning the message
content only if the decryption is valid. Many but not all
implementations will follow this convention. The message content
MUST NOT be used if the decryption does not validate.
4.1. ChaCha20 and Poly1305
ChaCha20 and Poly1305 combined together is a new AEAD mode that is
defined in [RFC7539]. This is a new algorithm 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 3.
+-------------------+-------+----------------------------------+
| name | value | description |
+-------------------+-------+----------------------------------+
| ChaCha20/Poly1305 | 11 | ChaCha20/Poly1305 w/ 256-bit key |
+-------------------+-------+----------------------------------+
Table 3: Algorithm Value for AES-GCM
Keys may be obtained either from a key structure or from a recipient
structure. 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.
4.1.1. Security Considerations
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.
Schaad Expires April 19, 2016 [Page 8]
Internet-Draft CBOR Encoded Message Syntax October 2015
5. Key Derivation Functions (KDF)
Key Derivation Functions (KDFs) are used to take some secret value
and generate a different one. The original secret values come in
three basic flavors:
o Secrets which are uniformly random: This is the type of secret
which is created by a good random number generator.
o Secrets which are not uniformly random: This is type of secret
which is created by operations like key agreement.
o Secrets which are not random: This is the type of secret that
people generate for things like passwords.
General KDF functions work well with the first type of secret, can do
reasonable well with the second type of secret and generally do
poorly with the last type of secret. None of the KDF functions in
this section are designed to deal with the type of secrets that are
used for passwords. Functions like PBSE2 [RFC2898] need to be used
for that type of secret.
Many functions are going to handle the first two type of secrets
differently. The KDF function defined in [HKDF] can use different
underlying constructions if the secret is uniformly random than if
the secret is not uniformly random. This is reflected in the set of
algorithms defined for HKDF.
When using KDF functions, one component that is generally included is
context information. Context information is used to allow for
different keying information to be derived from the same secret. The
use of context based keying material is considered to be a good
security practice. This document defines a single context structure
and a single KDF function.
6. Recipient Algorithm Classes
Recipient algorithms can be defined into a number of different
classes. COSE has the ability to support many classes of recipient
algorithms. In this section, a number of classes are listed and then
a set of algorithms are specified for each of the classes. The names
of the recipient algorithm classes used here are the same as are
defined in [RFC7517]. Other specifications use different terms for
the recipient algorithm classes or do not support some of our
recipient algorithm classes.
Schaad Expires April 19, 2016 [Page 9]
Internet-Draft CBOR Encoded Message Syntax October 2015
6.1. Direct Encryption
The direct encryption class algorithms share a secret between the
sender and the recipient that is used either directly or after
manipulation as the content key. When direct encryption mode is
used, it MUST be the only mode used on the message.
The COSE_encrypt structure for the recipient is organized as follows:
o The 'protected' field MUST be a zero length item if it is not used
in the computation of the content key.
o The 'alg' parameter MUST be present.
o A parameter identifying the shared secret SHOULD be present.
o The 'ciphertext' field MUST be a zero length item.
o The 'recipients' field MUST be absent.
6.1.1. Direct Key with KDF
These recipient algorithms take a common shared secret between the
two parties and applies the HKDF function 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. 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.
A new IV must be used if the same key is used in more than one
message. The IV can be modified in a predictable manner, a random
manner or an unpredictable manner. One unpredictable manner that can
be used is to use the HKDF function to generate the IV. If HKDF is
used for generating the IV, the algorithm identifier is set to "IV-
GENERATION".
When these algorithms are used, the key type MUST be 'symmetric'.
Schaad Expires April 19, 2016 [Page 10]
Internet-Draft CBOR Encoded Message Syntax October 2015
The set of algorithms defined in this document can be found in
Table 4.
+---------------------+-------+-------------+-----------------------+
| name | value | KDF | description |
+---------------------+-------+-------------+-----------------------+
| direct+HKDF-SHA-256 | * | HKDF | Shared secret w/ HKDF |
| | | SHA-256 | and SHA-256 |
| | | | |
| direct+HKDF-SHA-512 | * | HKDF | Shared secret w/ HKDF |
| | | SHA-512 | and SHA-512 |
| | | | |
| direct+HKDF-AES-128 | * | HKDF AES- | Shared secret w/ AES- |
| | | MAC-128 | MAC 128-bit key |
| | | | |
| direct+HKDF-AES-256 | * | HKDF AES- | Shared secret w/ AES- |
| | | MAC-256 | MAC 256-bit key |
+---------------------+-------+-------------+-----------------------+
Table 4: Direct Key
6.1.1.1. Security Considerations
The shared secret need to have some method to be regularly updated
over time. The shared secret is forming the basis of trust, although
not used directly it should still be subject to scheduled rotation.
6.2. Key Wrapping
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 COSE_encrypt structure for the recipient is organized as follows:
o The 'protected' field MUST be absent if the key wrap algorithm is
an AE algorithm.
o The 'recipients' field is normally absent, but can be used.
Applications MUST deal with a recipients field present, not being
able to decrypt that recipient is an acceptable way of dealing
with it. Failing to process the message is not an acceptable way
of dealing with it.
Schaad Expires April 19, 2016 [Page 11]
Internet-Draft CBOR Encoded Message Syntax October 2015
o The plain text to be encrypted is the key from next layer down
(usually the content layer).
o At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the shared
secret.
6.3. Key Encryption
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. This document defines one
Key Encryption mode algorithm.
When using a key encryption algorithm, the COSE_encrypt structure for
the recipient is organized as follows:
o The 'protected' field MUST be absent.
o The plain text to be encrypted is the key from next layer down
(usually the content layer).
o At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the
asymmetric key.
6.3.1. RSAES-OAEP
RSAES-OAEP is an asymmetric key encryption algorithm. The defintion
of RSAEA-OAEP can be find in Section 7.1 of [RFC3447]. The algorithm
is parameterized using a masking generation function (mgf), a hash
function (h) and encoding parameters (P). For the algorithm
identifiers defined in this section:
o mgf is always set to MFG1 from [RFC3447] and uses the same hash
function as h.
o P is always set to the empty octet string.
Table 5 summarizes the rest of the values.
Schaad Expires April 19, 2016 [Page 12]
Internet-Draft CBOR Encoded Message Syntax October 2015
+----------------------+-------+---------+-----------------------+
| name | value | hash | description |
+----------------------+-------+---------+-----------------------+
| RSAES-OAEP w/SHA-256 | -25 | SHA-256 | RSAES OAEP w/ SHA-256 |
| | | | |
| RSAES-OAEP w/SHA-512 | -26 | SHA-512 | RSAES OAEP w/ SHA-512 |
+----------------------+-------+---------+-----------------------+
Table 5: RSAES-OAEP Algorithm Values
The key type MUST be 'RSA'.
6.3.1.1. Security Considerations for RSAES-OAEP
A key size of 2048 bits or larger MUST be used with these algorithms.
This key size corresponds roughly to the same strength as provided by
a 128-bit symmetric encryption algorithm.
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. Applications can impose additional restrictions on the
length of the modulus.
6.4. Direct Key Agreement
The 'direct key agreement' class of recipient algorithms uses a key
agreement method to create a shared secret. A KDF is then applied to
the shared secret to derive a key to be used in protecting the data.
This key is normally used as a CEK or MAC key, but could be used for
other purposes if more than two layers are in use (see [THREE-LAYER]
).
The most commonly used key agreement algorithm used is Diffie-
Hellman, but other variants exist. Since COSE is designed for a
store and forward environment rather than an on-line environment,
many of the DH variants cannot be used as the receiver of the message
cannot provide any key material. One side-effect of this is that
perfect forward security is not achievable, a static key will always
be used for the receiver of the COSE message.
Two variants of DH that are easily supported are:
- 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
Schaad Expires April 19, 2016 [Page 13]
Internet-Draft CBOR Encoded Message Syntax October 2015
of the ephemeral sender key means that no additional random input
is needed as this is randomly generated for each message.
Static-Static DH: where a static key is used for both the sender
and the recipient. The use of static keys allows for recipient to
get a weak version of data origination for the message. When
static-static key agreement is used, then some piece of unique
data is require to ensure that a different key is created for each
message
In this specification, both variants are specified. This has been
done to provide the weak data origination option for use with MAC
operations.
When direct key agreement mode is used, there MUST be only one
recipient in the message. 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.
The COSE_encrypt structure for the recipient is organized as follows:
o The 'protected' field MUST be absent.
o At a minimum, the 'unprotected' field MUST contain the 'alg'
parameter and SHOULD contain a parameter identifying the
recipient's asymmetric key.
o The 'unprotected' field MUST contain the 'epk' parameter.
6.4.1. ECDH
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].
ECDH is parameterized by the following:
o 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 9.
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.
Schaad Expires April 19, 2016 [Page 14]
Internet-Draft CBOR Encoded Message Syntax October 2015
o Ephemeral-static or static-static: The key agreement process may
be done using either a static or an ephemeral key at the senders
side. When using ephemeral keys, the sender MUST generate a new
ephemeral key for every key agreement operation. The ephemeral
key is placed in in the 'ephemeral key' parameter and MUST be
present for all algorithm identifiers which use ephemeral keys.
When using static keys, the sender MUST either generate a new
random value placed in either in the KDF parameters or the context
structure. For the KDF functions used, this means either in the
'salt' parameter for HKDF [HKDF_Alg_Params]) or in in the 'PartyU
nonce' parameter for the context struture
([KDF_Context_Alg_Params]) MUST be present. (Both may be present
if desired.) The value in the parameter MUST be unique for the
key pair being used. It is acceptable to use a global counter
which is incremented for every static-static operation and use the
resulting value. When using static keys, the static key needs to
be identified to the recipient. The static key can be identified
either by providing the key ('static key') or by providing a key
identifier for the static key ('static key id'). Both of these
parameters are defined in Table 7
o 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.
o 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 6.
+-------------+------+-------+----------------+--------+------------+
| name | valu | KDF | Ephemeral- | Key | descriptio |
| | e | | Static | Wrap | n |
+-------------+------+-------+----------------+--------+------------+
| ECDH-ES + | 50 | HKDF | yes | none | ECDH ES w/ |
| HKDF-256 | | - SHA | | | HKDF - |
Schaad Expires April 19, 2016 [Page 15]
Internet-Draft CBOR Encoded Message Syntax October 2015
| | | -256 | | | generate |
| | | | | | key |
| | | | | | directly |
| | | | | | |
| ECDH-ES + | 51 | HKDF | yes | none | ECDH ES w/ |
| HKDF-512 | | - SHA | | | HKDF - |
| | | -256 | | | generate |
| | | | | | key |
| | | | | | directly |
| | | | | | |
| ECDH-SS + | 52 | HKDF | no | none | ECDH ES w/ |
| HKDF-256 | | - SHA | | | HKDF - |
| | | -256 | | | generate |
| | | | | | key |
| | | | | | directly |
| | | | | | |
| ECDH-SS + | 53 | HKDF | no | none | ECDH ES w/ |
| HKDF-512 | | - SHA | | | HKDF - |
| | | -256 | | | generate |
| | | | | | key |
| | | | | | directly |
| | | | | | |
| ECDH- | 54 | HKDF | yes | A128KW | ECDH ES w/ |
| ES+A128KW | | - SHA | | | Concat KDF |
| | | -256 | | | and AES |
| | | | | | Key wrap |
| | | | | | w/ 128 bit |
| | | | | | key |
| | | | | | |
| ECDH- | 55 | HKDF | yes | A192KW | ECDH ES w/ |
| ES+A192KW | | - SHA | | | Concat KDF |
| | | -256 | | | and AES |
| | | | | | Key wrap |
| | | | | | w/ 192 bit |
| | | | | | key |
| | | | | | |
| ECDH- | 56 | HKDF | yes | A256KW | ECDH ES w/ |
| ES+A256KW | | - SHA | | | Concat KDF |
| | | -256 | | | and AES |
| | | | | | Key wrap |
| | | | | | w/ 256 bit |
| | | | | | key |
| | | | | | |
| ECDH- | 57 | HKDF | no | A128KW | ECDH SS w/ |
| SS+A128KW | | - SHA | | | Concat KDF |
| | | -256 | | | and AES |
| | | | | | Key wrap |
| | | | | | w/ 128 bit |
Schaad Expires April 19, 2016 [Page 16]
Internet-Draft CBOR Encoded Message Syntax October 2015
| | | | | | key |
| | | | | | |
| ECDH- | 58 | HKDF | no | A192KW | ECDH SS w/ |
| SS+A192KW | | - SHA | | | Concat KDF |
| | | -256 | | | and AES |
| | | | | | Key wrap |
| | | | | | w/ 192 bit |
| | | | | | key |
| | | | | | |
| ECDH- | 59 | HKDF | no | A256KW | ECDH SS w/ |
| SS+A256KW | | - SHA | | | Concat KDF |
| | | -256 | | | and AES |
| | | | | | Key wrap |
| | | | | | w/ 256 bit |
| | | | | | key |
+-------------+------+-------+----------------+--------+------------+
Table 6: ECDH Algorithm Values
+-----------+-------+----------+-----------+------------------------+
| name | label | type | algorithm | description |
+-----------+-------+----------+-----------+------------------------+
| ephemeral | -1 | COSE_Key | ECDH-ES | Ephemeral Public key |
| key | | | | for the sender |
| | | | | |
| static | -2 | COSE_Key | ECDH-ES | Static Public key for |
| key | | | | the sender |
| | | | | |
| static | -3 | bstr | ECDH-SS | Static Public key |
| key id | | | | identifier for the |
| | | | | sender |
+-----------+-------+----------+-----------+------------------------+
Table 7: ECDH Algorithm Parameters
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.
6.5. Key Agreement with KDF
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.
Schaad Expires April 19, 2016 [Page 17]
Internet-Draft CBOR Encoded Message Syntax October 2015
The COSE_encrypt structure for the recipient is organized as follows:
o The 'protected' field is fed into the KDF context structure.
o The plain text to be encrypted is the key from next layer down
(usually the content layer).
o The 'alg' parameter MUST be present in the layer.
o A parameter identifying the recipient's key SHOULD be present. A
parameter identifying the senders key SHOULD be present.
6.5.1. ECDH
These algorithms are defined in Table 6.
6.6. Password
[CREF2]
6.6.1. PBES2
+--------------------+-------+--------------------------------------+
| name | value | description |
+--------------------+-------+--------------------------------------+
| PBES2-HS256+A128KW | * | PBES2 w/ HMAC SHA-256 and AES Key |
| | | wrap w/ 128 bit key |
| | | |
| PBES2-HS384+A192KW | * | PBES2 w/ HMAC SHA-384 and AES Key |
| | | wrap w/ 192 bit key |
| | | |
| PBES2-HS512+A256KW | * | PBES2 w/ HMAC SHA-512 and AES Key |
| | | wrap w/ 256 bit key |
+--------------------+-------+--------------------------------------+
7. Keys
The COSE_Key object defines a way to hold a single key object, it is
still required that the members of individual key types be defined.
This section of the document is where we define an initial set of
members for specific key types.
For each of the key types, we define both public and private members.
The public members are what is transmitted to others for their usage.
We define private members mainly for the purpose of archival of keys
by individuals. However, there are some circumstances where private
keys may be distributed by various entities in a protocol. Examples
include: Entities which have poor random number generation.
Schaad Expires April 19, 2016 [Page 18]
Internet-Draft CBOR Encoded Message Syntax October 2015
Centralized key creation for multi-cast type operations. Protocols
where a shared secret is used as a bearer token for authorization
purposes.
Key types are identified by the 'kty' member of the COSE_Key object.
In this document we define four values for the member.
+------+-------+------------------------------------------+
| name | value | description |
+------+-------+------------------------------------------+
| EC1 | 1 | Elliptic Curve Keys w/ X Coordinate only |
| | | |
| RSA | 3 | RSA Keys |
+------+-------+------------------------------------------+
Table 8: Key Type Values
7.1. Elliptic Curve Keys
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]. [CREF3]
+------------+----------+-------+-------------+
| name | key type | value | description |
+------------+----------+-------+-------------+
| Curve25519 | EC1 | 1 | Curve 25519 |
| | | | |
| Curve448 | EC1 | 2 | Curve 448 |
+------------+----------+-------+-------------+
Table 9: EC Curves
7.1.1. Single Coordinate Curves
One class of Elliptic Curve mathematics allows for a point to be
completely defined using the curve and the x coordinate of the point
on the curve. The two curves that are initially setup to use is
point format are Curve 25519 and Curve 448 which are defined in
[I-D.irtf-cfrg-curves].
For EC keys with only the x coordinates, the 'kty' member is set to 1
(EC1). The key parameters defined in this section are summarized in
Table 10. The members that are defined for this key type are:
Schaad Expires April 19, 2016 [Page 19]
Internet-Draft CBOR Encoded Message Syntax October 2015
crv contains an identifier of the curve to be used with the key.
[CREF4] The curves defined in this document for this key type can
be found in Table 9. Other curves may be registered in the future
and private curves can be used as well.
x contains the x coordinate for the EC point. The octet string
represents a little-endian encoding of x.
d contains the private key.
For public keys, it is REQUIRED that 'crv' and 'x' be present in the
structure. For private keys, it is REQUIRED that 'crv' and 'd' be
present in the structure. For private keys, it is RECOMMENDED that
'x' also be present, but it can be recomputed from the required
elements and omitting it saves on space.
+------+-------+-------+--------+-----------------------------------+
| name | key | value | type | description |
| | type | | | |
+------+-------+-------+--------+-----------------------------------+
| crv | 1 | -1 | int / | EC Curve identifier - Taken from |
| | | | tstr | the COSE General Registry |
| | | | | |
| x | 1 | -2 | bstr | X Coordinate |
| | | | | |
| d | 1 | -4 | bstr | Private key |
+------+-------+-------+--------+-----------------------------------+
Table 10: EC Key Parameters
7.2. RSA Keys
This document defines a key structure for both the public and private
halves of RSA keys. Together, an RSA public key and an RSA private
key form an RSA key pair. [CREF5]
The document also provides support for the so-called "multi-prime"
RSA where the modulus may have more than two prime factors. The
benefit of multi-prime RSA is lower computational cost for the
decryption and signature primitives. For a discussion on how multi-
prime affects the security of RSA crypto-systems, the reader is
referred to [MultiPrimeRSA].
This document follows the naming convention of [RFC3447] for the
naming of the fields of an RSA public or private key. The table
Table 11 provides a summary of the label values and the types
associated with each of those labels. The requirements for fields
for RSA keys are as follows:
Schaad Expires April 19, 2016 [Page 20]
Internet-Draft CBOR Encoded Message Syntax October 2015
o For all keys, 'kty' MUST be present and MUST have a value of 3.
o For public keys, the fields 'n' and 'e' MUST be present. All
other fields defined in Table 11 MUST be absent.
o For private keys with two primes, the fields 'other', 'r_i', 'd_i'
and 't_i' MUST be absent, all other fields MUST be present.
o For private keys with more than two primes, all fields MUST be
present. For the third to nth primes, each of the primes is
represented as a map containing the fields 'r_i', 'd_i' and 't_i'.
The field 'other' is an array of those maps.
+-------+----------+-------+-------+--------------------------------+
| name | key type | value | type | description |
+-------+----------+-------+-------+--------------------------------+
| n | 3 | -1 | bstr | Modulus Parameter |
| | | | | |
| e | 3 | -2 | int | Exponent Parameter |
| | | | | |
| d | 3 | -3 | bstr | Private Exponent Parameter |
| | | | | |
| p | 3 | -4 | bstr | First Prime Factor |
| | | | | |
| q | 3 | -5 | bstr | Second Prime Factor |
| | | | | |
| dP | 3 | -6 | bstr | First Factor CRT Exponent |
| | | | | |
| dQ | 3 | -7 | bstr | Second Factor CRT Exponent |
| | | | | |
| qInv | 3 | -8 | bstr | First CRT Coefficient |
| | | | | |
| other | 3 | -9 | array | Other Primes Info |
| | | | | |
| r_i | 3 | -10 | bstr | i-th factor, Prime Factor |
| | | | | |
| d_i | 3 | -11 | bstr | i-th factor, Factor CRT |
| | | | | Exponent |
| | | | | |
| t_i | 3 | -12 | bstr | i-th factor, Factor CRT |
| | | | | Coefficient |
+-------+----------+-------+-------+--------------------------------+
Table 11: RSA Key Parameters
Schaad Expires April 19, 2016 [Page 21]
Internet-Draft CBOR Encoded Message Syntax October 2015
8. IANA Considerations
8.1. COSE Header Parameter Registry
There are currently no registration requests here
8.2. COSE Header Algorithm Label Table
It is requested that IANA create a new registry entitled "COSE Header
Algorithm Labels".
The columns of the registry are:
name The name is present to make it easier to refer to and discuss
the registration entry. The value is not used in the protocol.
algorithm 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.
label This is the value used for the label. The label is an integer
in the range of -1 to -65536.
value This contains the CBOR type for the value portion of the
label.
value registry This contains a pointer to the registry used to
contain values where the set is limited.
description This contains a brief description of the header field.
specification This contains a pointer to the specification defining
the header field (where public).
The initial contents of the registry can be found in: Table 7. The
specification column for all rows in that table should be this
document.
8.3. COSE Algorithm Registry
It is requested that IANA create a new registry entitled "COSE
Algorithm Registry".
The columns of the registry are:
value The value to be used to identify this algorithm. Algorithm
values MUST be unique. The value can be a positive integer, a
Schaad Expires April 19, 2016 [Page 22]
Internet-Draft CBOR Encoded Message Syntax October 2015
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.
description A short description of the algorithm.
specification A document where the algorithm is defined (if publicly
available).
The initial contents of the registry can be found in the following:
Table 3, Table 1, Table 4, Table 5, Table 6. The specification
column for all rows in that table should be this document.
8.4. COSE Key Common Parameter Registry
There are currently no registration tasks inthis section.
8.5. COSE Key Type Parameter Registry
It is requested that IANA create a new registry "COSE Key Type
Parameters".
The columns of the table are:
key type This field contains a descriptive string of a key type.
This should be a value that is in the COSE General Values table
and is placed in the 'kty' field of a COSE Key structure.
name This is a descriptive name that enables easier reference to the
item. It is not used in the encoding.
label 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
reused for different keys.
CBOR type This field contains the CBOR type for the field
description This field contains a brief description for the field
specification This contains a pointer to the public specification
for the field if one exists
Schaad Expires April 19, 2016 [Page 23]
Internet-Draft CBOR Encoded Message Syntax October 2015
This registry will be initially populated by the values in Table 10,
and Table 11. The specification column for all of these entries will
be this document.
8.6. COSE Elliptic Curve Registry
It is requested that IANA create a new registry "COSE Elliptic Curve
Parameters".
The columns of the table are:
name This is a descriptive name that enables easier reference to the
item. It is not used in the encoding.
value This is the value used to identify the curve. These values
MUST be unique. The integer values from -256 to 255 are
designated as Standards Track Document Required. The the integer
values from 256 to 65535 and -65536 to -257 are designated as
Specification Required. Integer values over 65535 are designated
as first come first serve. Integer values less than -65536 are
marked as private use.
key type This designates the key type(s) that can be used with this
curve.
description This field contains a brief description of the curve.
specification This contains a pointer to the public specification
for the curve if one exists.
This registry will be initially populated by the values in Table 8.
The specification column for all of these entries will be this
document.
9. Security Considerations
There are security considerations:
1. Protect private keys
2. MAC messages with more than one recipient means one cannot figure
out who sent the message
3. Use of direct key with other recipient structures hands the key
to other recipients.
4. Use of direct ECDH direct encryption is easy for people to leak
information on if there are other recipients in the message.
Schaad Expires April 19, 2016 [Page 24]
Internet-Draft CBOR Encoded Message Syntax October 2015
5. Considerations about protected vs unprotected header fields.
6. 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.
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, October 2013.
10.2. Informative References
[AES-GCM] Dworkin, M., "NIST Special Publication 800-38D:
Recommendation for Block Cipher Modes of Operation:
Galois/Counter Mode (GCM) and GMAC.", Nov 2007.
[DSS] U.S. National Institute of Standards and Technology,
"Digital Signature Standard (DSS)", July 2013.
[I-D.greevenbosch-appsawg-cbor-cddl]
Vigano, C., Birkholz, H., and R. Sun, "CBOR data
definition language: a notational convention to express
CBOR data structures.", draft-greevenbosch-appsawg-cbor-
cddl-05 (work in progress), March 2015.
[I-D.ietf-cose-msg]
Schaad, J. and B. Campbell, "CBOR Encoded Message Syntax",
draft-ietf-cose-msg-05 (work in progress), September 2015.
[I-D.irtf-cfrg-curves]
Langley, A. and R. Salz, "Elliptic Curves for Security",
draft-irtf-cfrg-curves-02 (work in progress), March 2015.
[I-D.irtf-cfrg-eddsa]
Josefsson, S. and I. Liusvaara, "Edwards-curve Digital
Signature Algorithm (EdDSA)", draft-irtf-cfrg-eddsa-00
(work in progress), October 2015.
[MAC] NiST, N., "FIPS PUB 113: Computer Data Authentication",
May 1985.
Schaad Expires April 19, 2016 [Page 25]
Internet-Draft CBOR Encoded Message Syntax October 2015
[MultiPrimeRSA]
Hinek, M. and D. Cheriton, "On the Security of Multi-prime
RSA", June 2006.
[PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a
Signature Scheme with Partial Message Recover", February
2000.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104, February
1997.
[RFC2633] Ramsdell, B., "S/MIME Version 3 Message Specification",
RFC 2633, June 1999.
[RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography
Specification Version 2.0", RFC 2898, DOI 10.17487/
RFC2898, September 2000,
<http://www.rfc-editor.org/info/rfc2898>.
[RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard
(AES) Key Wrap Algorithm", RFC 3394, September 2002.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003.
[RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with
CBC-MAC (CCM)", RFC 3610, September 2003.
[RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA-
224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC
4231, December 2005.
[RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/
Multipurpose Internet Mail Extensions (S/MIME)
Capabilities", RFC 4262, December 2005.
[RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk,
"Elliptic Curve Cryptography Subject Public Key
Information", RFC 5480, March 2009.
[RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70,
RFC 5652, September 2009.
[RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet
Mail Extensions (S/MIME) Version 3.2 Message
Specification", RFC 5751, January 2010.
Schaad Expires April 19, 2016 [Page 26]
Internet-Draft CBOR Encoded Message Syntax October 2015
[RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in
Cryptographic Message Syntax (CMS)", RFC 5752, January
2010.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869, May 2010.
[RFC5990] Randall, J., Kaliski, B., Brainard, J., and S. Turner,
"Use of the RSA-KEM Key Transport Algorithm in the
Cryptographic Message Syntax (CMS)", RFC 5990, September
2010.
[RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
Curve Cryptography Algorithms", RFC 6090, February 2011.
[RFC6151] Turner, S. and L. Chen, "Updated Security Considerations
for the MD5 Message-Digest and the HMAC-MD5 Algorithms",
RFC 6151, March 2011.
[RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature
Algorithm (DSA) and Elliptic Curve Digital Signature
Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August
2013, <http://www.rfc-editor.org/info/rfc6979>.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, DOI 10.17487/
RFC7252, June 2014,
<http://www.rfc-editor.org/info/rfc7252>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, May 2015.
[RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, May 2015.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, May
2015.
[RFC7539] Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF
Protocols", RFC 7539, DOI 10.17487/RFC7539, May 2015,
<http://www.rfc-editor.org/info/rfc7539>.
Schaad Expires April 19, 2016 [Page 27]
Internet-Draft CBOR Encoded Message Syntax October 2015
[SEC1] Standards for Efficient Cryptography Group, "SEC 1:
Elliptic Curve Cryptography", May 2009.
[SP800-56A]
Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST
Special Publication 800-56A: Recommendation for Pair-Wise
Key Establishment Schemes Using Discrete Logarithm
Cryptography", May 2013.
Appendix A. CDDL Grammar
For people who prefer using a formal language to describe the syntax
of the CBOR, in this section a CDDL grammar is given that corresponds
to [I-D.greevenbosch-appsawg-cbor-cddl]. This grammar is
informational, in the event of differences between this grammar and
the prose, the prose is considered to be authorative.
The collected CDDL can be extracted from the XML version of this
document via the following XPath expression below. (Depending on the
XPath evaluator one is using, it may be necessary to deal with >
as an entity.)
//artwork[@type='CDDL']/text()
Appendix B. Examples
The examples can be found at https://github.com/cose-wg/Examples.
The file names in each section correspond the the same file names in
the repository. I am currently still in the process of getting the
examples up there along with some control information for people to
be able to check and reproduce the examples.
Examples may have some features that are in questions but not yet
incorporated in the document.
To make it easier to read, the examples are presented using the
CBOR's diagnostic notation rather than a binary dump. A ruby based
tool exists to convert between a number of formats. This tool can be
installed with the command line:
gem install cbor-diag
The diagnostic notation can be converted into binary files using the
following command line:
Schaad Expires April 19, 2016 [Page 28]
Internet-Draft CBOR Encoded Message Syntax October 2015
diag2cbor < inputfile > outputfile
The examples can be extracted from the XML version of this docuent
via an XPath expression as all of the artwork is tagged with the
attribute type='CBORdiag'.
B.1. Examples of MAC messages
B.1.1. Shared Secret Direct MAC
This example users the following:
o MAC: AES-CMAC, 256-bit key, trucated to 64 bits
o Recipient class: direct shared secret
o File name: Mac-04
Size of binary file is 73 bytes
996( [
h'a1016f4145532d434d41432d3235362f3634',
{
},
h'546869732069732074686520636f6e74656e742e',
h'd9afa663dd740848',
[
[
h'',
{
1: -6,
4: h'6f75722d736563726574'
},
h''
]
]
])
B.1.2. ECDH Direct MAC
This example uses the following:
o MAC: HMAC w/SHA-256, 256-bit key
o Recipient class: ECDH key agreement, two static keys, HKDF w/
context structure
Schaad Expires April 19, 2016 [Page 29]
Internet-Draft CBOR Encoded Message Syntax October 2015
Size of binary file is 217 bytes
996( [
h'a10104',
{
},
h'546869732069732074686520636f6e74656e742e',
h'2ba937ca03d76c3dbad30cfcbaeef586f9c0f9ba616ad67e9205d38576ad9
930',
[
[
h'',
{
1: 52,
4: h'6d65726961646f632e6272616e64796275636b406275636b6c61
6e642e6578616d706c65',
-3: h'706572656772696e2e746f6f6b407475636b626f726f7567682
e6578616d706c65',
"apu": h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d19558ccf
ec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a58368b01
7e7f2a9e5ce4db5'
},
h''
]
]
])
B.1.3. Wrapped MAC
This example uses the following:
o MAC: AES-MAC, 128-bit key, truncated to 64 bits
o Recipient class: AES keywrap w/ a pre-shared 256-bit key
Size of binary file is 124 bytes
Schaad Expires April 19, 2016 [Page 30]
Internet-Draft CBOR Encoded Message Syntax October 2015
996( [
h'a1016e4145532d3132382d4d41432d3634',
{
},
h'546869732069732074686520636f6e74656e742e',
h'6d1fa77b2dd9146a',
[
[
h'',
{
1: -5,
4: h'30313863306165352d346439622d343731622d626664362d6565
66333134626337303337'
},
h'711ab0dc2fc4585dce27effa6781c8093eba906f227b6eb0'
]
]
])
B.1.4. Multi-recipient MAC message
This example uses the following:
o MAC: HMAC w/ SHA-256, 128-bit key
o Recipient class: Uses three different methods
1. ECDH Ephemeral-Static, Curve P-521, AES-Key Wrap w/ 128-bit
key
2. RSA-OAEP w/ SHA-256
3. AES-Key Wrap w/ 256-bit key
Size of binary file is 672 bytes
996( [
h'a10104',
{
},
h'546869732069732074686520636f6e74656e742e',
h'7aaa6e74546873061f0a7de21ff0c0658d401a68da738dd893748651983ce
1d0',
[
[
h'',
{
1: 55,
Schaad Expires April 19, 2016 [Page 31]
Internet-Draft CBOR Encoded Message Syntax October 2015
4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861
6d706c65',
-1: {
1: 2,
-1: 3,
-2: h'43b12669acac3fd27898ffba0bcd2e6c366d53bc4db71f909
a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2d61
3574e7dc242f79c3',
-3: h'812dd694f4ef32b11014d74010a954689c6b6e8785b333d1a
b44f22b9d1091ae8fc8ae40b687e5cfbe7ee6f8b47918a07bb04e9f5b1a51a334
a16bc09777434113'
}
},
h'f20ad9c96134f3c6be4f75e7101c0ecc5efa071ff20a87fd1ac285109
41ee0376573e2b384b56b99'
],
[
h'',
{
1: -26,
4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861
6d706c65'
},
h'46c4f88069b650909a891e84013614cd58a3668f88fa18f3852940a20
b35098591d3aacf91c125a2595cda7bee75a490579f0e2f20fd6bc956623bfde3
029c318f82c426dac3463b261c981ab18b72fe9409412e5c7f2d8f2b5abaf780d
f6a282db033b3a863fa957408b81741878f466dcc437006ca21407181a016ca60
8ca8208bd3c5a1ddc828531e30b89a67ec6bb97b0c3c3c92036c0cb84aa0f0ce8
c3e4a215d173bfa668f116ca9f1177505afb7629a9b0b5e096e81d37900e06f56
1a32b6bc993fc6d0cb5d4bb81b74e6ffb0958dac7227c2eb8856303d989f93b4a
051830706a4c44e8314ec846022eab727e16ada628f12ee7978855550249ccb58
'
],
[
h'',
{
1: -5,
4: h'30313863306165352d346439622d343731622d626664362d6565
66333134626337303337'
},
h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a518e7736549e99
8370695e6d6a83b4ae507bb'
]
]
])
Schaad Expires April 19, 2016 [Page 32]
Internet-Draft CBOR Encoded Message Syntax October 2015
B.2. Examples of Encrypted Messages
B.2.1. Direct ECDH
This example uses the following:
o CEK: AES-GCM w/ 128-bit key
o Recipient class: ECDH Ephemeral-Static, Curve P-256
Size of binary file is 184 bytes
998( [
h'a10101',
{
5: h'c9cf4df2fe6c632bf7886413'
},
h'45fce2814311024d3a479e7d3eed063850f3f0b9f3f948677e3ae9869bcf9
ff4e1763812',
[
[
h'',
{
1: 50,
4: h'6d65726961646f632e6272616e64796275636b406275636b6c61
6e642e6578616d706c65',
-1: {
1: 2,
-1: 1,
-2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf05
4e1c7b4d91d6280',
-3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d
924b7e03bf822bb'
}
},
h''
]
]
])
B.2.2. Direct plus Key Derivation
This example uses the following:
o CEK: AES-CCM w/128-bit key, trucate the tag to 64-bits
o Recipient class: Use HKDF on a shared secret with the following
implicit fields as part of the context.
Schaad Expires April 19, 2016 [Page 33]
Internet-Draft CBOR Encoded Message Syntax October 2015
* APU identity: "lighting-client"
* APV identity: "lighting-server"
* Supplimentary Public Other: "Encryption Example 02"
Size of binary file is 97 bytes
998( [
h'a1010a',
{
5: h'89f52f65a1c580933b5261a7'
},
h'7b9dcfa42c4e1d3182c402dc18ef8b5637de4fb62cf1dd156ea6e6e0',
[
[
h'',
{
1: "dir+kdf",
4: h'6f75722d736563726574',
-20: h'61616262636364646565666667676868'
},
h''
]
]
])
B.3. Examples of Signed Message
B.3.1. Single Signature
This example uses the following:
o Signature Algorithm: RSA-PSS w/ SHA-384, MGF-1
Size of binary file is 332 bytes
Schaad Expires April 19, 2016 [Page 34]
Internet-Draft CBOR Encoded Message Syntax October 2015
999( [
h'',
{
},
h'546869732069732074686520636f6e74656e742e',
[
[
h'a20165505333383404581e62696c626f2e62616767696e7340686f626
269746f6e2e6578616d706c65',
{
},
h'6d9d88a90ef4d6d7c0079fb11a33c855e2274c773f358df43b68f7873
eeda210692a61d70cd6a24ba0e3d82e359384be09faafea496bb0ed16f02091c4
8c02f33574edab5b3e334bae68d19580021327cc131fbee38eb0b28289dbce118
3f9067891b17fe752674b80437da02e9928ab7a155fef707b11d2bd38a71f224f
53170480116d96cc3f7266487b268679a13cdedffa93252a550371acc19971369
b58039056b308cc4e158bebe7c55db7874442d4321fd27f17dbb820ef19f43dcc
16cd50ccdd1b7dfd7cdde239a9245af41d949cdbbf1337ca254af20eeb167a62d
a5a51c83899c6f6e7c7e01dc3db21a250092a69fc635b74a2e54f5c98cb955d83
'
]
]
])
B.3.2. Multiple Signers
This example uses the following:
o Signature Algorithm: RSA-PSS w/ SHA-256, MGF-1
o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521
Size of binary file is 498 bytes
Schaad Expires April 19, 2016 [Page 35]
Internet-Draft CBOR Encoded Message Syntax October 2015
999( [
h'',
{
},
h'546869732069732074686520636f6e74656e742e',
[
[
h'a1013819',
{
4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861
6d706c65'
},
h'0ee972d931c7ab906e4bb71b80da0cc99c104fa53ebbf1f2cf7b668b9
3d766d3d2da28299f074675bb0db3cd0792ba83050c23c96795d58f9c7d68f66a
bbb8f35af8a0b5df369517b6db85e2cb62d852b666bc135c9022e46b538f78c26
adc2668963e74a019de718254385bb9cb137926ad6a88d1ff70043f85e555fb57
84107ce6e9de7c89c4fbadf8eca363a35f415f7a23523a8331b1aa2dfbac59a06
3e4357bde8e53fe34195d59bcda37d2c604804fffe60362e81476436aaa677129
f34b26639fc41b8e758e5edf273079c61b30130f0f83c57aa6856347e2556f718
eaf79a1fee1397a4f0b16b1b34db946eaaff10c793e5d1e681cb21c4fd20c5fdf
'
],
[
h'',
{
1: -9,
4: h'62696c626f2e62616767696e7340686f626269746f6e2e657861
6d706c65'
},
h'0118eaa7d62778b5a9525a583f06b115d80cd246bc930f0c2850588ee
c85186b427026e096a076bfab738215f354be59f57643a7f6b2c92535cf3c37ee
2746a908ab1dcc673a63f327d9eff852b874f7a98b6638c7054fdeeaa3dce6542
4a21bd5dc728acedda7fcae6df6fc3298ff51ac911603a0f26d066935dccb85ea
eb0ae6d0e6'
]
]
])
B.4. COSE Keys
B.4.1. Public Keys
This is an example of a COSE Key set. This example includes the
public keys for all of the previous examples.
In order the keys are:
o An EC key with a kid of "meriadoc.brandybuck@buckland.example"
Schaad Expires April 19, 2016 [Page 36]
Internet-Draft CBOR Encoded Message Syntax October 2015
o An EC key with a kid of "peregrin.took@tuckborough.example"
o An EC key with a kid of "bilbo.baggins@hobbiton.example"
o An RSA key with a kid of "bilbo.baggins@hobbiton.example"
Size of binary file is 703 bytes
[
{
-1: 1,
-2: h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de4
39c08551d',
-3: h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eec
d0084d19c',
1: 2,
2: h'6d65726961646f632e6272616e64796275636b406275636b6c616e64
2e6578616d706c65'
},
{
-1: 3,
-2: h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737b
f5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620
085e5c8f42ad',
-3: h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e
247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f
3fe1ea1d9475',
1: 2,
2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70
6c65'
},
{
-1: 1,
-2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b
4d91d6280',
-3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e
03bf822bb',
1: 2,
2: h'706572656772696e2e746f6f6b407475636b626f726f7567682e6578
616d706c65'
},
{
-2: h'9f810fb4038273d02591e4073f31d2b6001b82cedb4d92f050165d4
7cfcab8a3c41cb778ac7553793f8ef975768d1a2374d8712564c3bcd77b9ea434
544899407cff0099920a931a24c4414852ab29bdb0a95c0653f36c60e60bf90b6
258dda56f37047ba5c2d1d029af9c9d40bac7aa41c78a0dd1068add699e808fea
011ea1441d8a4f7bb4e97be39f55f1ddd44e9c4ba335159703d4d34b603e65147
a4f23d6d3c0996c75edee846a82d190ae10783c961cf0387aed2106d2d0555b6f
Schaad Expires April 19, 2016 [Page 37]
Internet-Draft CBOR Encoded Message Syntax October 2015
d937fad5535387e0ff72ffbe78941402b0b822ea2a74b6058c1dabf9b34a76cb6
3b87faa2c6847b8e2837fff91186e6b1c14911cf989a89092a81ce601ddacd3f9
cf',
-1: h'010001',
1: 3,
2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70
6c65'
}
]
B.4.2. Private Keys
This is an example of a COSE Key set. This example includes the
private keys for all of the previous examples.
In order the keys are:
o An EC key with a kid of "meriadoc.brandybuck@buckland.example"
o A shared-secret key with a kid of "our-secret"
o An EC key with a kid of "peregrin.took@tuckborough.example"
o A shared-secret key with a kid of "018c0ae5-4d9b-471b-
bfd6-eef314bc7037"
o An EC key with a kid of "bilbo.baggins@hobbiton.example"
o An RSA key with a kid of "bilbo.baggins@hobbiton.example"
Size of binary file is 1884 bytes
[
{
1: 2,
2: h'6d65726961646f632e6272616e64796275636b406275636b6c616e64
2e6578616d706c65',
-1: 1,
-2: h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de4
39c08551d',
-3: h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eec
d0084d19c',
-4: h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad9118
40fa208cf'
},
{
1: 4,
2: h'6f75722d736563726574',
Schaad Expires April 19, 2016 [Page 38]
Internet-Draft CBOR Encoded Message Syntax October 2015
-1: h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dce
a6c427188'
},
{
1: 2,
2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70
6c65',
-1: 3,
-2: h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737b
f5de7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620
085e5c8f42ad',
-3: h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e
247e60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f
3fe1ea1d9475',
-4: h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476
680b55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609
fdf177feb26d'
},
{
1: 2,
-1: 1,
2: h'706572656772696e2e746f6f6b407475636b626f726f7567682e6578
616d706c65',
-2: h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b
4d91d6280',
-3: h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e
03bf822bb',
-4: h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522
a848df1c3'
},
{
1: 4,
2: h'30313863306165352d346439622d343731622d626664362d65656633
3134626337303337',
-1: h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dce
a6c427188'
},
{
1: 3,
2: h'62696c626f2e62616767696e7340686f626269746f6e2e6578616d70
6c65',
-2: h'9f810fb4038273d02591e4073f31d2b6001b82cedb4d92f050165d4
7cfcab8a3c41cb778ac7553793f8ef975768d1a2374d8712564c3bcd77b9ea434
544899407cff0099920a931a24c4414852ab29bdb0a95c0653f36c60e60bf90b6
258dda56f37047ba5c2d1d029af9c9d40bac7aa41c78a0dd1068add699e808fea
011ea1441d8a4f7bb4e97be39f55f1ddd44e9c4ba335159703d4d34b603e65147
a4f23d6d3c0996c75edee846a82d190ae10783c961cf0387aed2106d2d0555b6f
d937fad5535387e0ff72ffbe78941402b0b822ea2a74b6058c1dabf9b34a76cb6
Schaad Expires April 19, 2016 [Page 39]
Internet-Draft CBOR Encoded Message Syntax October 2015
3b87faa2c6847b8e2837fff91186e6b1c14911cf989a89092a81ce601ddacd3f9
cf',
-1: h'010001',
-3: h'6d6502f41f84151228f24a467e1d19bb218fbcc34abd858db41fe29
221fd936d1e4fe3b5abf23bf1e8999295f15d0d144c4b362ec3514bef2e25bbd0
f80d62ae4c0c48c90ad49dd74c681dae10a4bbd81195d63bb0d03f00a64687e43
aeb5ff8dab20d2d109ef16fa7677e2e8bfa8e7e42e72bd4160c3aa9688b00f9b3
3059648316ed8c5016309074cc1332d81aa39ed389e8a9eab5844c414c704e05d
90c5e2b85854ab5054ea5f83a84896c6a83cdac5edda1f8b3274f7d38e8039826
8462a33ef9b525107c60ac8564c19cfe6e0e3775f242a1cafd3b9617d225dacf7
4ce4f972976d61b057f82ff9870aea056aeee076c3df1cfc718d539c3a906b433
c1',
-4: h'dd297183f0f04d725c6fad3de51a17ca0402019e519c0bd9967a35c
a11ed9d47b1fdfa7b019ffd9d168eec75fff9215f1907aeb5aa364c38c3016538
56ea64f2bc3d251d00cd9d0dd9fbee2009abfd60ac986a5e36a4277afd53ec8c8
4b2787c50cb7e9f909a7e1922933844b2b9a7747e8bc4eaef44996c3e9e99bfc6
d4ab49',
-5: h'b8a136761f9c4dfe84445e24e1efe3cbbf067cf61421a532a12489b
81ce9dc2b9b937382aacea0ad3f1b47f72ed039b5319c169ad76a0f223de47ad4
7aadcc3f5e6f30c38df251d3799bb69662afc2a5bb6a757953384cd6267bcf8c8
c92e530156a01bf263cf7c117bd10fe85da91c47952a80675f76cc1de9545274b
3ba457',
-6: h'07c3d5bd792f26b8f62fe19843bbf7cbdafa2b0e60f526a15c1c2c5
94ce9d7d4d596023e615f39ab53486f5af142d0fe22c5d7477f936a77afb913d1
b7938139d88c190a7ca5bb76ea096361f294fc4f719fe4542c7cf4f9e77d13d81
72ca0f85469e0a73f8f7d0feadbda64e71587a09a74d3d41fd47bc2862c515f9f
5e8629',
-7: h'08b0e60c676e87295cf68eebf38ac45159fba7343a3c5f3763e8816
71e4d4fe4e99ce64a175a44ac031578acc5125e350e51c7aaa04b48cd16d6c385
6f04f16166439bab08ea88398936f0406202de09c929b8bfee4fef260187c07c6
03da5f63e7bcffb3c84903111b9ffabcb873f675d42abd02a0b6c9e2fa91d293d
5c605f',
-8: h'dcf8aabd740dd33c0c784fac06f6608b6f3d5cff57090177556a8fc
cc2a7220429eff4ee828ebe35904a090b0c7f71da1060634d526cfe370af3e4d1
5ef68a7beed931a423f157c175892cb1bbb434a0c386327e1ad8ac79a0d55aded
d707d1c7f0c601541e9421ec5a02ae3149ea1e99129305eb19ae8ece2a3293f3f
1a688e'
}
]
Appendix C. Document Updates
C.1. Version -00
o TBD
Schaad Expires April 19, 2016 [Page 40]
Internet-Draft CBOR Encoded Message Syntax October 2015
Editorial Comments
[CREF1] JLS: I have not gone through the document to determine what
needs to be here yet. We mostly want to grab terms which are
used in unusual ways or are not generally understood.
[CREF2] JLS: Do we want/need to support this? JOSE did it mainly to
support the encryption of private keys.
[CREF3] Ilari: Check to see what the curves are renamed to during final
publishing. It appears to be X25519 now.
[CREF4] JLS: Do we create a registry for curves? Is is the same
registry for both EC1 and EC2?
[CREF5] JLS: Looking at the CBOR specification, the bstr that we are
looking in our table below should most likely be specified as
big numbers rather than as binary strings. This means that we
would use the tag 6.2 instead. From my reading of the
specification, there is no difference in the encoded size of the
resulting output. The specification of bignum does explicitly
allow for integers encoded with leading zeros.
Author's Address
Jim Schaad
August Cellars
Email: ietf@augustcellars.com
Schaad Expires April 19, 2016 [Page 41]