RFC 8152
CBOR Object Signing and Encryption (COSE)
18. References
18.1. Normative References
[AES-GCM] National Institute of Standards and Technology, "Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC", NIST Special Publication 800-38D, DOI 10.6028/NIST.SP.800-38D, November 2007, <https://csrc.nist.gov/publications/nistpubs/800- 38D/SP-800-38D.pdf>. [COAP.Formats] IANA, "Constrained RESTful Environments (CoRE) Parameters", <http://www.iana.org/assignments/core-parameters/>. [DSS] National Institute of Standards and Technology, "Digital Signature Standard (DSS)", FIPS PUB 186-4, DOI 10.6028/NIST.FIPS.186-4, July 2013, <http://nvlpubs.nist.gov/nistpubs/FIPS/
NIST.FIPS.186-4.pdf>.
[MAC] National Institute of Standards and Technology, "Computer
Data Authentication", FIPS PUB 113, May 1985,
<http://csrc.nist.gov/publications/fips/fips113/
fips113.html>.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
Hashing for Message Authentication", RFC 2104,
DOI 10.17487/RFC2104, February 1997,
<http://www.rfc-editor.org/info/rfc2104>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard
(AES) Key Wrap Algorithm", RFC 3394, DOI 10.17487/RFC3394,
September 2002, <http://www.rfc-editor.org/info/rfc3394>.
[RFC3610] Whiting, D., Housley, R., and N. Ferguson, "Counter with
CBC-MAC (CCM)", RFC 3610, DOI 10.17487/RFC3610, September
2003, <http://www.rfc-editor.org/info/rfc3610>.
[RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand
Key Derivation Function (HKDF)", RFC 5869,
DOI 10.17487/RFC5869, May 2010,
<http://www.rfc-editor.org/info/rfc5869>.
[RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic
Curve Cryptography Algorithms", RFC 6090,
DOI 10.17487/RFC6090, February 2011,
<http://www.rfc-editor.org/info/rfc6090>.
[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>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <http://www.rfc-editor.org/info/rfc7049>.
[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>.
[RFC7748] Langley, A., Hamburg, M., and S. Turner, "Elliptic Curves for Security", RFC 7748, DOI 10.17487/RFC7748, January 2016, <http://www.rfc-editor.org/info/rfc7748>. [RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, DOI 10.17487/RFC8032, January 2017, <http://www.rfc-editor.org/info/rfc8032>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <http://www.rfc-editor.org/info/rfc8174>. [SEC1] Certicom Research, "SEC 1: Elliptic Curve Cryptography", Standards for Efficient Cryptography, Version 2.0, May 2009, <http://www.secg.org/sec1-v2.pdf>.18.2. Informative References
[CDDL] Vigano, C. and H. Birkholz, "CBOR data definition language (CDDL): a notational convention to express CBOR data structures", Work in Progress, draft-greevenbosch-appsawg- cbor-cddl-09, March 2017. [OSCOAP] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security of CoAP (OSCOAP)", Work in Progress, draft-ietf-core-object-security-03, May 2017. [PVSig] Brown, D. and D. Johnson, "Formal Security Proofs for a Signature Scheme with Partial Message Recovery", DOI 10.1007/3-540-45353-9_11, LNCS Volume 2020, June 2000. [RFC2633] Ramsdell, B., Ed., "S/MIME Version 3 Message Specification", RFC 2633, DOI 10.17487/RFC2633, June 1999, <http://www.rfc-editor.org/info/rfc2633>. [RFC4231] Nystrom, M., "Identifiers and Test Vectors for HMAC-SHA- 224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512", RFC 4231, DOI 10.17487/RFC4231, December 2005, <http://www.rfc-editor.org/info/rfc4231>. [RFC4262] Santesson, S., "X.509 Certificate Extension for Secure/ Multipurpose Internet Mail Extensions (S/MIME) Capabilities", RFC 4262, DOI 10.17487/RFC4262, December 2005, <http://www.rfc-editor.org/info/rfc4262>.
[RFC4493] Song, JH., Poovendran, R., Lee, J., and T. Iwata, "The AES-CMAC Algorithm", RFC 4493, DOI 10.17487/RFC4493, June 2006, <http://www.rfc-editor.org/info/rfc4493>. [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007, <http://www.rfc-editor.org/info/rfc4949>. [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, <http://www.rfc-editor.org/info/rfc5116>. [RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk, "Elliptic Curve Cryptography Subject Public Key Information", RFC 5480, DOI 10.17487/RFC5480, March 2009, <http://www.rfc-editor.org/info/rfc5480>. [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, RFC 5652, DOI 10.17487/RFC5652, September 2009, <http://www.rfc-editor.org/info/rfc5652>. [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.2 Message Specification", RFC 5751, DOI 10.17487/RFC5751, January 2010, <http://www.rfc-editor.org/info/rfc5751>. [RFC5752] Turner, S. and J. Schaad, "Multiple Signatures in Cryptographic Message Syntax (CMS)", RFC 5752, DOI 10.17487/RFC5752, January 2010, <http://www.rfc-editor.org/info/rfc5752>. [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, DOI 10.17487/RFC5990, September 2010, <http://www.rfc-editor.org/info/rfc5990>. [RFC6151] Turner, S. and L. Chen, "Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms", RFC 6151, DOI 10.17487/RFC6151, March 2011, <http://www.rfc-editor.org/info/rfc6151>. [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <http://www.rfc-editor.org/info/rfc6838>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>. [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, DOI 10.17487/RFC7515, May 2015, <http://www.rfc-editor.org/info/rfc7515>. [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, <http://www.rfc-editor.org/info/rfc7516>. [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <http://www.rfc-editor.org/info/rfc7517>. [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, DOI 10.17487/RFC7518, May 2015, <http://www.rfc-editor.org/info/rfc7518>. [RFC8017] Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, "PKCS #1: RSA Cryptography Specifications Version 2.2", RFC 8017, DOI 10.17487/RFC8017, November 2016, <http://www.rfc-editor.org/info/rfc8017>. [RFC8018] Moriarty, K., Ed., Kaliski, B., and A. Rusch, "PKCS #5: Password-Based Cryptography Specification Version 2.1", RFC 8018, DOI 10.17487/RFC8018, January 2017, <http://www.rfc-editor.org/info/rfc8018>. [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <http://www.rfc-editor.org/info/rfc8126>. [SP800-56A] Barker, E., Chen, L., Roginsky, A., and M. Smid, "Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography", NIST Special Publication 800-56A, Revision 2, DOI 10.6028/NIST.SP.800-56Ar2, May 2013, <http://nvlpubs.nist.gov/nistpubs/SpecialPublications/ NIST.SP.800-56Ar2.pdf>.
[W3C.WebCrypto] Watson, M., "Web Cryptography API", W3C Recommendation, January 2017, <https://www.w3.org/TR/WebCryptoAPI/>.
Appendix A. Guidelines for External Data Authentication of Algorithms
A portion of the working group has expressed a strong desire to relax the rule that the algorithm identifier be required to appear in each level of a COSE object. There are two basic reasons that have been advanced to support this position. First, the resulting message will be smaller if the algorithm identifier is omitted from the most common messages in a CoAP environment. Second, there is a potential bug that will arise if full checking is not done correctly between the different places that an algorithm identifier could be placed (the message itself, an application statement, the key structure that the sender possesses, and the key structure the recipient possesses). This appendix lays out how such a change can be made and the details that an application needs to specify in order to use this option. Two different sets of details are specified: those needed to omit an algorithm identifier and those needed to use a variant on the counter signature attribute that contains no attributes about itself.A.1. Algorithm Identification
In this section, three sets of recommendations are laid out. The first set of recommendations apply to having an implicit algorithm identified for a single layer of a COSE object. The second set of recommendations apply to having multiple implicit algorithms identified for multiple layers of a COSE object. The third set of recommendations apply to having implicit algorithms for multiple COSE object constructs. The key words from RFC 2119 are deliberately not used here. This specification can provide recommendations, but it cannot enforce them. This set of recommendations applies to the case where an application is distributing a fixed algorithm along with the key information for use in a single COSE object. This normally applies to the smallest of the COSE objects, specifically COSE_Sign1, COSE_Mac0, and COSE_Encrypt0, but could apply to the other structures as well. The following items should be taken into account: o Applications need to list the set of COSE structures that implicit algorithms are to be used in. Applications need to require that the receipt of an explicit algorithm identifier in one of these structures will lead to the message being rejected. This requirement is stated so that there will never be a case where there is any ambiguity about the question of which algorithm should be used, the implicit or the explicit one. This applies
even if the transported algorithm identifier is a protected
attribute. This applies even if the transported algorithm is the
same as the implicit algorithm.
o Applications need to define the set of information that is to be
considered to be part of a context when omitting algorithm
identifiers. At a minimum, this would be the key identifier (if
needed), the key, the algorithm, and the COSE structure it is used
with. Applications should restrict the use of a single key to a
single algorithm. As noted for some of the algorithms in this
document, the use of the same key in different related algorithms
can lead to leakage of information about the key, leakage about
the data or the ability to perform forgeries.
o In many cases, applications that make the algorithm identifier
implicit will also want to make the context identifier implicit
for the same reason. That is, omitting the context identifier
will decrease the message size (potentially significantly
depending on the length of the identifier). Applications that do
this will need to describe the circumstances where the context
identifier is to be omitted and how the context identifier is to
be inferred in these cases. (An exhaustive search over all of the
keys would normally not be considered to be acceptable.) An
example of how this can be done is to tie the context to a
transaction identifier. Both would be sent on the original
message, but only the transaction identifier would need to be sent
after that point as the context is tied into the transaction
identifier. Another way would be to associate a context with a
network address. All messages coming from a single network
address can be assumed to be associated with a specific context.
(In this case, the address would normally be distributed as part
of the context.)
o Applications cannot rely on key identifiers being unique unless
they take significant efforts to ensure that they are computed in
such a way as to create this guarantee. Even when an application
does this, the uniqueness might be violated if the application is
run in different contexts (i.e., with a different context
provider) or if the system combines the security contexts from
different applications together into a single store.
o Applications should continue the practice of protecting the
algorithm identifier. Since this is not done by placing it in the
protected attributes field, applications should define an
application-specific external data structure that includes this
value. This external data field can be used as such for content
encryption, MAC, and signature algorithms. It can be used in the
SuppPrivInfo field for those algorithms that use a KDF to derive a
key value. Applications may also want to protect other
information that is part of the context structure as well. It
should be noted that those fields, such as the key or a Base IV,
are protected by virtue of being used in the cryptographic
computation and do not need to be included in the external data
field.
The second case is having multiple implicit algorithm identifiers
specified for a multiple layer COSE object. An example of how this
would work is the encryption context that an application specifies,
which contains a content encryption algorithm, a key wrap algorithm,
a key identifier, and a shared secret. The sender omits sending the
algorithm identifier for both the content layer and the recipient
layer leaving only the key identifier. The receiver then uses the
key identifier to get the implicit algorithm identifiers.
The following additional items need to be taken into consideration:
o Applications that want to support this will need to define a
structure that allows for, and clearly identifies, both the COSE
structure to be used with a given key and the structure and
algorithm to be used for the secondary layer. The key for the
secondary layer is computed as normal from the recipient layer.
The third case is having multiple implicit algorithm identifiers, but
targeted at potentially unrelated layers or different COSE objects.
There are a number of different scenarios where this might be
applicable. Some of these scenarios are:
o Two contexts are distributed as a pair. Each of the contexts is
for use with a COSE_Encrypt message. Each context will consist of
distinct secret keys and IVs and potentially even different
algorithms. One context is for sending messages from party A to
party B, and the second context is for sending messages from party
B to party A. This means that there is no chance for a reflection
attack to occur as each party uses different secret keys to send
its messages; a message that is reflected back to it would fail to
decrypt.
o Two contexts are distributed as a pair. The first context is used
for encryption of the message, and the second context is used to
place a counter signature on the message. The intention is that
the second context can be distributed to other entities
independently of the first context. This allows these entities to
validate that the message came from an individual without being
able to decrypt the message and see the content.
o Two contexts are distributed as a pair. The first context
contains a key for dealing with MACed messages, and the second
context contains a key for dealing with encrypted messages. This
allows for a unified distribution of keys to participants for
different types of messages that have different keys, but where
the keys may be used in a coordinated manner.
For these cases, the following additional items need to be
considered:
o Applications need to ensure that the multiple contexts stay
associated. If one of the contexts is invalidated for any reason,
all of the contexts associated with it should also be invalidated.
A.2. Counter Signature without Headers
There is a group of people who want to have a counter signature
parameter that is directly tied to the value being signed, and thus
the authenticated and unauthenticated buckets can be removed from the
message being sent. The focus on this is an even smaller size, as
all of the information on the process of creating the counter
signature is implicit rather than being explicitly carried in the
message. This includes not only the algorithm identifier as
presented above, but also items such as the key identification, which
is always external to the signature structure. This means that the
entities that are doing the validation of the counter signature are
required to infer which key is to be used from context rather than
being explicit. One way of doing this would be to presume that all
data coming from a specific port (or to a specific URL) is to be
validated by a specific key. (Note that this does not require that
the key identifier be part of the value signed as it does not serve a
cryptographic purpose. If the key validates the counter signature,
then it should be presumed that the entity associated with that key
produced the signature.)
When computing the signature for the bare counter signature header,
the same Sig_structure defined in Section 4.4 is used. The
sign_protected field is omitted, as there is no protected header
field in this counter signature header. The value of
"CounterSignature0" is placed in the context field of the
Sig_stucture.
+-------------------+-------+-------+-------+-----------------------+ | Name | Label | Value | Value | Description | | | | Type | | | +-------------------+-------+-------+-------+-----------------------+ | CounterSignature0 | 9 | bstr | | Counter signature | | | | | | with implied signer | | | | | | and headers | +-------------------+-------+-------+-------+-----------------------+ Table 27: Header Parameter for CounterSignature0Appendix B. Two Layers of Recipient Information
All of the currently defined recipient algorithm classes only use two layers of the COSE_Encrypt structure. The first layer is the message content, and the second layer is the content key encryption. However, if one uses a recipient algorithm such as the RSA Key Encapsulation Mechanism (RSA-KEM) (see Appendix A of RSA-KEM [RFC5990]), then it makes sense to have three layers of the COSE_Encrypt structure. These layers would be: o Layer 0: The content encryption layer. This layer contains the payload of the message. o Layer 1: The encryption of the CEK by a KEK. o Layer 2: The encryption of a long random secret using an RSA key and a key derivation function to convert that secret into the KEK. This is an example of what a triple layer message would look like. The message has the following layers: o Layer 0: Has a content encrypted with AES-GCM using a 128-bit key. o Layer 1: Uses the AES Key Wrap algorithm with a 128-bit key. o Layer 2: Uses ECDH Ephemeral-Static direct to generate the layer 1 key.
In effect, this example is a decomposed version of using the
ECDH-ES+A128KW algorithm.
Size of binary file is 183 bytes
96(
[
/ protected / h'a10101' / {
\ alg \ 1:1 \ AES-GCM 128 \
} / ,
/ unprotected / {
/ iv / 5:h'02d1f7e6f26c43d4868d87ce'
},
/ ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e2852948658f0
811139868826e89218a75715b',
/ recipients / [
[
/ protected / h'',
/ unprotected / {
/ alg / 1:-3 / A128KW /
},
/ ciphertext / h'dbd43c4e9d719c27c6275c67d628d493f090593db82
18f11',
/ recipients / [
[
/ protected / h'a1013818' / {
\ alg \ 1:-25 \ ECDH-ES + HKDF-256 \
} / ,
/ unprotected / {
/ ephemeral / -1:{
/ kty / 1:2,
/ crv / -1:1,
/ x / -2:h'b2add44368ea6d641f9ca9af308b4079aeb519f11
e9b8a55a600b21233e86e68',
/ y / -3:false
},
/ kid / 4:'meriadoc.brandybuck@buckland.example'
},
/ ciphertext / h''
]
]
]
]
]
)
Appendix C. Examples
This appendix includes a set of examples that show the different features and message types that have been defined in this document. To make the examples easier to read, they are presented using the extended CBOR diagnostic notation (defined in [CDDL]) rather than as a binary dump. A GitHub project has been created at <https://github.com/cose-wg/ Examples> that contains not only the examples presented in this document, but a more complete set of testing examples as well. Each example is found in a JSON file that contains the inputs used to create the example, some of the intermediate values that can be used in debugging the example and the output of the example presented in both a hex and a CBOR diagnostic notation format. Some of the examples at the site are designed failure testing cases; these are clearly marked as such in the JSON file. If errors in the examples in this document are found, the examples on GitHub will be updated, and a note to that effect will be placed in the JSON file. As noted, the examples are presented using the CBOR's diagnostic notation. A Ruby-based tool exists that can convert between the diagnostic notation and binary. 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: diag2cbor.rb < inputfile > outputfile The examples can be extracted from the XML version of this document via an XPath expression as all of the artwork is tagged with the attribute type='CBORdiag'. (Depending on the XPath evaluator one is using, it may be necessary to deal with > as an entity.) //artwork[@type='CDDL']/text()
C.1. Examples of Signed Messages
C.1.1. Single Signature
This example uses the following: o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 Size of binary file is 103 bytes 98( [ / protected / h'', / unprotected / {}, / payload / 'This is the content.', / signatures / [ [ / protected / h'a10126' / { \ alg \ 1:-7 \ ECDSA 256 \ } / , / unprotected / { / kid / 4:'11' }, / signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb 5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b 98f53afd2fa0f30a' ] ] ] )C.1.2. Multiple Signers
This example uses the following: o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256 o Signature Algorithm: ECDSA w/ SHA-512, Curve P-521
Size of binary file is 277 bytes
98(
[
/ protected / h'',
/ unprotected / {},
/ payload / 'This is the content.',
/ signatures / [
[
/ protected / h'a10126' / {
\ alg \ 1:-7 \ ECDSA 256 \
} / ,
/ unprotected / {
/ kid / 4:'11'
},
/ signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb
5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b
98f53afd2fa0f30a'
],
[
/ protected / h'a1013823' / {
\ alg \ 1:-36
} / ,
/ unprotected / {
/ kid / 4:'bilbo.baggins@hobbiton.example'
},
/ signature / h'00a2d28a7c2bdb1587877420f65adf7d0b9a06635dd1
de64bb62974c863f0b160dd2163734034e6ac003b01e8705524c5c4ca479a952f024
7ee8cb0b4fb7397ba08d009e0c8bf482270cc5771aa143966e5a469a09f613488030
c5b07ec6d722e3835adb5b2d8c44e95ffb13877dd2582866883535de3bb03d01753f
83ab87bb4f7a0297'
]
]
]
)
C.1.3. Counter Signature
This example uses the following:
o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256
o The same parameters are used for both the signature and the
counter signature.
Size of binary file is 180 bytes
98(
[
/ protected / h'',
/ unprotected / {
/ countersign / 7:[
/ protected / h'a10126' / {
\ alg \ 1:-7 \ ECDSA 256 \
} / ,
/ unprotected / {
/ kid / 4:'11'
},
/ signature / h'5ac05e289d5d0e1b0a7f048a5d2b643813ded50bc9e4
9220f4f7278f85f19d4a77d655c9d3b51e805a74b099e1e085aacd97fc29d72f887e
8802bb6650cceb2c'
]
},
/ payload / 'This is the content.',
/ signatures / [
[
/ protected / h'a10126' / {
\ alg \ 1:-7 \ ECDSA 256 \
} / ,
/ unprotected / {
/ kid / 4:'11'
},
/ signature / h'e2aeafd40d69d19dfe6e52077c5d7ff4e408282cbefb
5d06cbf414af2e19d982ac45ac98b8544c908b4507de1e90b717c3d34816fe926a2b
98f53afd2fa0f30a'
]
]
]
)
C.1.4. Signature with Criticality
This example uses the following:
o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256
o There is a criticality marker on the "reserved" header parameter
Size of binary file is 125 bytes
98(
[
/ protected / h'a2687265736572766564f40281687265736572766564' /
{
"reserved":false,
\ crit \ 2:[
"reserved"
]
} / ,
/ unprotected / {},
/ payload / 'This is the content.',
/ signatures / [
[
/ protected / h'a10126' / {
\ alg \ 1:-7 \ ECDSA 256 \
} / ,
/ unprotected / {
/ kid / 4:'11'
},
/ signature / h'3fc54702aa56e1b2cb20284294c9106a63f91bac658d
69351210a031d8fc7c5ff3e4be39445b1a3e83e1510d1aca2f2e8a7c081c7645042b
18aba9d1fad1bd9c'
]
]
]
)
C.2. Single Signer Examples
C.2.1. Single ECDSA Signature
This example uses the following:
o Signature Algorithm: ECDSA w/ SHA-256, Curve P-256
Size of binary file is 98 bytes
18(
[
/ protected / h'a10126' / {
\ alg \ 1:-7 \ ECDSA 256 \
} / ,
/ unprotected / {
/ kid / 4:'11'
},
/ payload / 'This is the content.',
/ signature / h'8eb33e4ca31d1c465ab05aac34cc6b23d58fef5c083106c4
d25a91aef0b0117e2af9a291aa32e14ab834dc56ed2a223444547e01f11d3b0916e5
a4c345cacb36'
]
)
C.3. Examples of Enveloped Messages
C.3.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 151 bytes
96(
[
/ protected / h'a10101' / {
\ alg \ 1:1 \ AES-GCM 128 \
} / ,
/ unprotected / {
/ iv / 5:h'c9cf4df2fe6c632bf7886413'
},
/ ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0
c52a357da7a644b8070a151b0',
/ recipients / [
[
/ protected / h'a1013818' / {
\ alg \ 1:-25 \ ECDH-ES + HKDF-256 \
} / ,
/ unprotected / {
/ ephemeral / -1:{
/ kty / 1:2,
/ crv / -1:1,
/ x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf
bf054e1c7b4d91d6280',
/ y / -3:true
},
/ kid / 4:'meriadoc.brandybuck@buckland.example'
},
/ ciphertext / h''
]
]
]
)
C.3.2. Direct Plus Key Derivation
This example uses the following:
o CEK: AES-CCM w/ 128-bit key, truncate the tag to 64 bits
o Recipient class: Use HKDF on a shared secret with the following
implicit fields as part of the context.
* salt: "aabbccddeeffgghh"
* PartyU identity: "lighting-client"
* PartyV identity: "lighting-server"
* Supplementary Public Other: "Encryption Example 02"
Size of binary file is 91 bytes
96(
[
/ protected / h'a1010a' / {
\ alg \ 1:10 \ AES-CCM-16-64-128 \
} / ,
/ unprotected / {
/ iv / 5:h'89f52f65a1c580933b5261a76c'
},
/ ciphertext / h'753548a19b1307084ca7b2056924ed95f2e3b17006dfe93
1b687b847',
/ recipients / [
[
/ protected / h'a10129' / {
\ alg \ 1:-10
} / ,
/ unprotected / {
/ salt / -20:'aabbccddeeffgghh',
/ kid / 4:'our-secret'
},
/ ciphertext / h''
]
]
]
)
C.3.3. Counter Signature on Encrypted Content
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 326 bytes
96(
[
/ protected / h'a10101' / {
\ alg \ 1:1 \ AES-GCM 128 \
} / ,
/ unprotected / {
/ iv / 5:h'c9cf4df2fe6c632bf7886413',
/ countersign / 7:[
/ protected / h'a1013823' / {
\ alg \ 1:-36
} / ,
/ unprotected / {
/ kid / 4:'bilbo.baggins@hobbiton.example'
},
/ signature / h'00929663c8789bb28177ae28467e66377da12302d7f9
594d2999afa5dfa531294f8896f2b6cdf1740014f4c7f1a358e3a6cf57f4ed6fb02f
cf8f7aa989f5dfd07f0700a3a7d8f3c604ba70fa9411bd10c2591b483e1d2c31de00
3183e434d8fba18f17a4c7e3dfa003ac1cf3d30d44d2533c4989d3ac38c38b71481c
c3430c9d65e7ddff'
]
},
/ ciphertext / h'7adbe2709ca818fb415f1e5df66f4e1a51053ba6d65a1a0
c52a357da7a644b8070a151b0',
/ recipients / [
[
/ protected / h'a1013818' / {
\ alg \ 1:-25 \ ECDH-ES + HKDF-256 \
} / ,
/ unprotected / {
/ ephemeral / -1:{
/ kty / 1:2,
/ crv / -1:1,
/ x / -2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbf
bf054e1c7b4d91d6280',
/ y / -3:true
},
/ kid / 4:'meriadoc.brandybuck@buckland.example'
},
/ ciphertext / h''
]
]
]
)
C.3.4. Encrypted Content with External Data
This example uses the following: o CEK: AES-GCM w/ 128-bit key o Recipient class: ECDH static-Static, Curve P-256 with AES Key Wrap o Externally Supplied AAD: h'0011bbcc22dd44ee55ff660077' Size of binary file is 173 bytes 96( [ / protected / h'a10101' / { \ alg \ 1:1 \ AES-GCM 128 \ } / , / unprotected / { / iv / 5:h'02d1f7e6f26c43d4868d87ce' }, / ciphertext / h'64f84d913ba60a76070a9a48f26e97e863e28529d8f5335 e5f0165eee976b4a5f6c6f09d', / recipients / [ [ / protected / h'a101381f' / { \ alg \ 1:-32 \ ECHD-SS+A128KW \ } / , / unprotected / { / static kid / -3:'peregrin.took@tuckborough.example', / kid / 4:'meriadoc.brandybuck@buckland.example', / U nonce / -22:h'0101' }, / ciphertext / h'41e0d76f579dbd0d936a662d54d8582037de2e366fd e1c62' ] ] ] )C.4. Examples of Encrypted Messages
C.4.1. Simple Encrypted Message
This example uses the following: o CEK: AES-CCM w/ 128-bit key and a 64-bit tag
Size of binary file is 52 bytes
16(
[
/ protected / h'a1010a' / {
\ alg \ 1:10 \ AES-CCM-16-64-128 \
} / ,
/ unprotected / {
/ iv / 5:h'89f52f65a1c580933b5261a78c'
},
/ ciphertext / h'5974e1b99a3a4cc09a659aa2e9e7fff161d38ce71cb45ce
460ffb569'
]
)
C.4.2. Encrypted Message with a Partial IV
This example uses the following:
o CEK: AES-CCM w/ 128-bit key and a 64-bit tag
o Prefix for IV is 89F52F65A1C580933B52
Size of binary file is 41 bytes
16(
[
/ protected / h'a1010a' / {
\ alg \ 1:10 \ AES-CCM-16-64-128 \
} / ,
/ unprotected / {
/ partial iv / 6:h'61a7'
},
/ ciphertext / h'252a8911d465c125b6764739700f0141ed09192de139e05
3bd09abca'
]
)
C.5. Examples of MACed Messages
C.5.1. Shared Secret Direct MAC
This example uses the following:
o MAC: AES-CMAC, 256-bit key, truncated to 64 bits
o Recipient class: direct shared secret
Size of binary file is 57 bytes
97(
[
/ protected / h'a1010f' / {
\ alg \ 1:15 \ AES-CBC-MAC-256//64 \
} / ,
/ unprotected / {},
/ payload / 'This is the content.',
/ tag / h'9e1226ba1f81b848',
/ recipients / [
[
/ protected / h'',
/ unprotected / {
/ alg / 1:-6 / direct /,
/ kid / 4:'our-secret'
},
/ ciphertext / h''
]
]
]
)
C.5.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
Size of binary file is 214 bytes
97(
[
/ protected / h'a10105' / {
\ alg \ 1:5 \ HMAC 256//256 \
} / ,
/ unprotected / {},
/ payload / 'This is the content.',
/ tag / h'81a03448acd3d305376eaa11fb3fe416a955be2cbe7ec96f012c99
4bc3f16a41',
/ recipients / [
[
/ protected / h'a101381a' / {
\ alg \ 1:-27 \ ECDH-SS + HKDF-256 \
} / ,
/ unprotected / {
/ static kid / -3:'peregrin.took@tuckborough.example',
/ kid / 4:'meriadoc.brandybuck@buckland.example',
/ U nonce / -22:h'4d8553e7e74f3c6a3a9dd3ef286a8195cbf8a23d
19558ccfec7d34b824f42d92bd06bd2c7f0271f0214e141fb779ae2856abf585a583
68b017e7f2a9e5ce4db5'
},
/ ciphertext / h''
]
]
]
)
C.5.3. Wrapped MAC
This example uses the following:
o MAC: AES-MAC, 128-bit key, truncated to 64 bits
o Recipient class: AES Key Wrap w/ a pre-shared 256-bit key
Size of binary file is 109 bytes
97(
[
/ protected / h'a1010e' / {
\ alg \ 1:14 \ AES-CBC-MAC-128//64 \
} / ,
/ unprotected / {},
/ payload / 'This is the content.',
/ tag / h'36f5afaf0bab5d43',
/ recipients / [
[
/ protected / h'',
/ unprotected / {
/ alg / 1:-5 / A256KW /,
/ kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037'
},
/ ciphertext / h'711ab0dc2fc4585dce27effa6781c8093eba906f227
b6eb0'
]
]
]
)
C.5.4. Multi-Recipient MACed 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. AES Key Wrap w/ 256-bit key
Size of binary file is 309 bytes
97(
[
/ protected / h'a10105' / {
\ alg \ 1:5 \ HMAC 256//256 \
} / ,
/ unprotected / {},
/ payload / 'This is the content.',
/ tag / h'bf48235e809b5c42e995f2b7d5fa13620e7ed834e337f6aa43df16
1e49e9323e',
/ recipients / [
[
/ protected / h'a101381c' / {
\ alg \ 1:-29 \ ECHD-ES+A128KW \
} / ,
/ unprotected / {
/ ephemeral / -1:{
/ kty / 1:2,
/ crv / -1:3,
/ x / -2:h'0043b12669acac3fd27898ffba0bcd2e6c366d53bc4db
71f909a759304acfb5e18cdc7ba0b13ff8c7636271a6924b1ac63c02688075b55ef2
d613574e7dc242f79c3',
/ y / -3:true
},
/ kid / 4:'bilbo.baggins@hobbiton.example'
},
/ ciphertext / h'339bc4f79984cdc6b3e6ce5f315a4c7d2b0ac466fce
a69e8c07dfbca5bb1f661bc5f8e0df9e3eff5'
],
[
/ protected / h'',
/ unprotected / {
/ alg / 1:-5 / A256KW /,
/ kid / 4:'018c0ae5-4d9b-471b-bfd6-eef314bc7037'
},
/ ciphertext / h'0b2c7cfce04e98276342d6476a7723c090dfdd15f9a
518e7736549e998370695e6d6a83b4ae507bb'
]
]
]
)
C.6. Examples of MAC0 Messages
C.6.1. Shared Secret Direct MAC
This example uses the following: o MAC: AES-CMAC, 256-bit key, truncated to 64 bits o Recipient class: direct shared secret Size of binary file is 37 bytes 17( [ / protected / h'a1010f' / { \ alg \ 1:15 \ AES-CBC-MAC-256//64 \ } / , / unprotected / {}, / payload / 'This is the content.', / tag / h'726043745027214f' ] ) Note that this example uses the same inputs as Appendix C.5.1.C.7. COSE Keys
C.7.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" 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 EC key with a kid of "11"
Size of binary file is 481 bytes
[
{
-1:1,
-2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0
8551d',
-3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008
4d19c',
1:2,
2:'meriadoc.brandybuck@buckland.example'
},
{
-1:1,
-2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a
09eff',
-3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf
c117e',
1:2,
2:'11'
},
{
-1:3,
-2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de
7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8
f42ad',
-3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e
60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1
d9475',
1:2,
2:'bilbo.baggins@hobbiton.example'
},
{
-1:1,
-2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91
d6280',
-3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf
822bb',
1:2,
2:'peregrin.took@tuckborough.example'
}
]
C.7.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 EC key with a kid of "11" Size of binary file is 816 bytes [ { 1:2, 2:'meriadoc.brandybuck@buckland.example', -1:1, -2:h'65eda5a12577c2bae829437fe338701a10aaa375e1bb5b5de108de439c0 8551d', -3:h'1e52ed75701163f7f9e40ddf9f341b3dc9ba860af7e0ca7ca7e9eecd008 4d19c', -4:h'aff907c99f9ad3aae6c4cdf21122bce2bd68b5283e6907154ad911840fa 208cf' }, { 1:2, 2:'11', -1:1, -2:h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a 09eff', -3:h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbf c117e', -4:h'57c92077664146e876760c9520d054aa93c3afb04e306705db609030850 7b4d3' }, { 1:2, 2:'bilbo.baggins@hobbiton.example',
-1:3,
-2:h'0072992cb3ac08ecf3e5c63dedec0d51a8c1f79ef2f82f94f3c737bf5de
7986671eac625fe8257bbd0394644caaa3aaf8f27a4585fbbcad0f2457620085e5c8
f42ad',
-3:h'01dca6947bce88bc5790485ac97427342bc35f887d86d65a089377e247e
60baa55e4e8501e2ada5724ac51d6909008033ebc10ac999b9d7f5cc2519f3fe1ea1
d9475',
-4:h'00085138ddabf5ca975f5860f91a08e91d6d5f9a76ad4018766a476680b
55cd339e8ab6c72b5facdb2a2a50ac25bd086647dd3e2e6e99e84ca2c3609fdf177f
eb26d'
},
{
1:4,
2:'our-secret',
-1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4
27188'
},
{
1:2,
-1:1,
2:'peregrin.took@tuckborough.example',
-2:h'98f50a4ff6c05861c8860d13a638ea56c3f5ad7590bbfbf054e1c7b4d91
d6280',
-3:h'f01400b089867804b8e9fc96c3932161f1934f4223069170d924b7e03bf
822bb',
-4:h'02d1f7e6f26c43d4868d87ceb2353161740aacf1f7163647984b522a848
df1c3'
},
{
1:4,
2:'our-secret2',
-1:h'849b5786457c1491be3a76dcea6c4271'
},
{
1:4,
2:'018c0ae5-4d9b-471b-bfd6-eef314bc7037',
-1:h'849b57219dae48de646d07dbb533566e976686457c1491be3a76dcea6c4
27188'
}
]
Acknowledgments
This document is a product of the COSE working group of the IETF. The following individuals are to blame for getting me started on this project in the first place: Richard Barnes, Matt Miller, and Martin Thomson. The initial version of the specification was based to some degree on the outputs of the JOSE and S/MIME working groups. The following individuals provided input into the final form of the document: Carsten Bormann, John Bradley, Brain Campbell, Michael B. Jones, Ilari Liusvaara, Francesca Palombini, Ludwig Seitz, and Goran Selander.Author's Address
Jim Schaad August Cellars Email: ietf@augustcellars.com