draft-ietf-cose-msg-15.txt   draft-ietf-cose-msg-16.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Intended status: Standards Track July 25, 2016 Intended status: Standards Track August 10, 2016
Expires: January 26, 2017 Expires: February 11, 2017
CBOR Object Signing and Encryption (COSE) CBOR Object Signing and Encryption (COSE)
draft-ietf-cose-msg-15 draft-ietf-cose-msg-16
Abstract Abstract
Concise Binary Object Representation (CBOR) is data format designed Concise Binary Object Representation (CBOR) is data format designed
for small code size and small message size. There is a need for the for small code size and small message size. There is a need for the
ability to have the basic security services defined for this data ability to have the basic security services defined for this data
format. This document defines the CBOR Object Signing and Encryption format. This document defines the CBOR Object Signing and Encryption
(COSE) specification. This specification describes how to create and (COSE) specification. This specification describes how to create and
process signature, message authentication codes and encryption using process signature, message authentication codes and encryption using
CBOR for serialization. This specification additionally specifies CBOR for serialization. This specification additionally specifies
skipping to change at page 1, line 45 skipping to change at page 1, line 45
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 26, 2017. This Internet-Draft will expire on February 11, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Design changes from JOSE . . . . . . . . . . . . . . . . 5 1.1. Design changes from JOSE . . . . . . . . . . . . . . . . 5
1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6 1.2. Requirements Terminology . . . . . . . . . . . . . . . . 6
1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6 1.3. CBOR Grammar . . . . . . . . . . . . . . . . . . . . . . 6
1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 7 1.4. CBOR Related Terminology . . . . . . . . . . . . . . . . 7
1.5. Document Terminology . . . . . . . . . . . . . . . . . . 7 1.5. Document Terminology . . . . . . . . . . . . . . . . . . 8
2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8 2. Basic COSE Structure . . . . . . . . . . . . . . . . . . . . 8
3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10 3. Header Parameters . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 11 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12
4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 15 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16
4.1. Signing with One or More Signers . . . . . . . . . . . . 15 4.1. Signing with One or More Signers . . . . . . . . . . . . 16
4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 17 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18
4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 18 4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19
4.4. Signing and Verification Process . . . . . . . . . . . . 19 4.4. Signing and Verification Process . . . . . . . . . . . . 20
4.5. Computing Counter Signatures . . . . . . . . . . . . . . 20 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 21
5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 21 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22
5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 21 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22
5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 23 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 24
5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 24 5.2. Single Recipient Encrypted . . . . . . . . . . . . . . . 25
5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 24 5.3. How to encrypt and decrypt for AEAD Algorithms . . . . . 25
5.4. Encryption algorithm for AE algorithms . . . . . . . . . 27 5.4. How to encrypt and decrypt for AE Algorithms . . . . . . 28
6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 28 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.1. MACed Message with Recipients . . . . . . . . . . . . . . 28 6.1. MACed Message with Recipients . . . . . . . . . . . . . . 29
6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 29 6.2. MACed Messages with Implicit Key . . . . . . . . . . . . 30
6.3. How to compute and verify a MAC . . . . . . . . . . . . . 30 6.3. How to compute and verify a MAC . . . . . . . . . . . . . 31
7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 32 7. Key Objects . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 32 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 33
8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 35 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 36
8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 36 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.1.1. Security Considerations . . . . . . . . . . . . . . . 38 8.1.1. Security Considerations . . . . . . . . . . . . . . . 39
8.2. Edwards-curve Digital Signature Algorithms (EdDSA) . . . 39 8.2. Edwards-curve Digital Signature Algorithms (EdDSA) . . . 40
8.2.1. Security Considerations . . . . . . . . . . . . . . . 40 8.2.1. Security Considerations . . . . . . . . . . . . . . . 41
9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 40 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 41
9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 40 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 41
9.1.1. Security Considerations . . . . . . . . . . . . . . . 42 9.1.1. Security Considerations . . . . . . . . . . . . . . . 43
9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 42 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 43
9.2.1. Security Considerations . . . . . . . . . . . . . . . 43 9.2.1. Security Considerations . . . . . . . . . . . . . . . 44
10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 44 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 45
10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 44 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 45
10.1.1. Security Considerations . . . . . . . . . . . . . . 45 10.1.1. Security Considerations . . . . . . . . . . . . . . 46
10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 46 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 47
10.2.1. Security Considerations . . . . . . . . . . . . . . 49 10.2.1. Security Considerations . . . . . . . . . . . . . . 50
10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 49 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 50
10.3.1. Security Considerations . . . . . . . . . . . . . . 50 10.3.1. Security Considerations . . . . . . . . . . . . . . 51
11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 50 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 51
11.1. HMAC-based Extract-and-Expand Key Derivation Function 11.1. HMAC-based Extract-and-Expand Key Derivation Function
(HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 51 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 52
11.2. Context Information Structure . . . . . . . . . . . . . 53 11.2. Context Information Structure . . . . . . . . . . . . . 54
12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 56 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 57
12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 57 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 58
12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 57 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 58
12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 58 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 59
12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 59 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 60
12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 60 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 61
12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 61 12.3. Key Transport . . . . . . . . . . . . . . . . . . . . . 62
12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 61 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 62
12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 62 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 63
12.4.2. Security Considerations . . . . . . . . . . . . . . 65 12.4.2. Security Considerations . . . . . . . . . . . . . . 66
12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 66 12.5. Key Agreement with Key Wrap . . . . . . . . . . . . . . 67
12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 66 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 67
13. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 68 13. Key Object Parameters . . . . . . . . . . . . . . . . . . . . 69
13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 68 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 69
13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 69 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 70
13.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 70 13.2. Octet Key Pair . . . . . . . . . . . . . . . . . . . . . 71
13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 71 13.3. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 72
14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 72 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 73
15. Application Profiling Considerations . . . . . . . . . . . . 72 15. Application Profiling Considerations . . . . . . . . . . . . 73
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75
16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 74 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 75
16.2. COSE Header Parameters Registry . . . . . . . . . . . . 74 16.2. COSE Header Parameters Registry . . . . . . . . . . . . 75
16.3. COSE Header Algorithm Parameters Registry . . . . . . . 75 16.3. COSE Header Algorithm Parameters Registry . . . . . . . 76
16.4. COSE Algorithms Registry . . . . . . . . . . . . . . . . 75 16.4. COSE Algorithms Registry . . . . . . . . . . . . . . . . 76
16.5. COSE Key Common Parameters Registry . . . . . . . . . . 76 16.5. COSE Key Common Parameters Registry . . . . . . . . . . 77
16.6. COSE Key Type Parameters Registry . . . . . . . . . . . 77 16.6. COSE Key Type Parameters Registry . . . . . . . . . . . 78
16.7. COSE Key Type Registry . . . . . . . . . . . . . . . . . 78 16.7. COSE Key Type Registry . . . . . . . . . . . . . . . . . 79
16.8. COSE Elliptic Curve Parameters Registry . . . . . . . . 78 16.8. COSE Elliptic Curve Parameters Registry . . . . . . . . 79
16.9. Media Type Registrations . . . . . . . . . . . . . . . . 79 16.9. Media Type Registrations . . . . . . . . . . . . . . . . 80
16.9.1. COSE Security Message . . . . . . . . . . . . . . . 79 16.9.1. COSE Security Message . . . . . . . . . . . . . . . 80
16.9.2. COSE Key media type . . . . . . . . . . . . . . . . 80 16.9.2. COSE Key media type . . . . . . . . . . . . . . . . 81
16.10. CoAP Content-Format Registrations . . . . . . . . . . . 82 16.10. CoAP Content-Format Registrations . . . . . . . . . . . 83
16.11. Expert Review Instructions . . . . . . . . . . . . . . . 82 16.11. Expert Review Instructions . . . . . . . . . . . . . . . 83
17. Implementation Status . . . . . . . . . . . . . . . . . . . . 83 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 84
17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 84 17.1. Author's Versions . . . . . . . . . . . . . . . . . . . 85
17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 85 17.2. COSE Testing Library . . . . . . . . . . . . . . . . . . 86
18. Security Considerations . . . . . . . . . . . . . . . . . . . 85 18. Security Considerations . . . . . . . . . . . . . . . . . . . 86
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 87 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 88
19.1. Normative References . . . . . . . . . . . . . . . . . . 87 19.1. Normative References . . . . . . . . . . . . . . . . . . 88
19.2. Informative References . . . . . . . . . . . . . . . . . 88 19.2. Informative References . . . . . . . . . . . . . . . . . 89
Appendix A. Making Mandatory Algorithm Header Optional . . . . . 91 Appendix A. Making Mandatory Algorithm Header Optional . . . . . 92
A.1. Algorithm Identification . . . . . . . . . . . . . . . . 91 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 92
A.2. Counter Signature Without Headers . . . . . . . . . . . . 94 A.2. Counter Signature Without Headers . . . . . . . . . . . . 95
Appendix B. Two Layers of Recipient Information . . . . . . . . 95 Appendix B. Two Layers of Recipient Information . . . . . . . . 96
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 96 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 97
C.1. Examples of Signed Message . . . . . . . . . . . . . . . 97 C.1. Examples of Signed Message . . . . . . . . . . . . . . . 98
C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 97 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 98
C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 98 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 99
C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 99 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 100
C.1.4. Signature w/ Criticality . . . . . . . . . . . . . . 100 C.1.4. Signature w/ Criticality . . . . . . . . . . . . . . 101
C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 101 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 102
C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 101 C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 102
C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 102 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 103
C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 102 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 103
C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 103 C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 104
C.3.3. Counter Signature on Encrypted Content . . . . . . . 104 C.3.3. Counter Signature on Encrypted Content . . . . . . . 105
C.3.4. Encrypted Content with External Data . . . . . . . . 106 C.3.4. Encrypted Content with External Data . . . . . . . . 107
C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 106 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 107
C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 106 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 107
C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 107 C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 108
C.5. Examples of MACed messages . . . . . . . . . . . . . . . 107 C.5. Examples of MACed messages . . . . . . . . . . . . . . . 108
C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 107 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 108
C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 108 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 109
C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 109 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 110
C.5.4. Multi-recipient MACed message . . . . . . . . . . . . 110 C.5.4. Multi-recipient MACed message . . . . . . . . . . . . 111
C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 111 C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 112
C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 111 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 112
C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 112 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 113
C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 112 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 113
C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 113 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 114
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 115 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 116
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 116 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 117
1. Introduction 1. Introduction
There has been an increased focus on the small, constrained devices There has been an increased focus on the small, constrained devices
that make up the Internet of Things (IoT). One of the standards that that make up the Internet of Things (IoT). One of the standards that
has come out of this process is the Concise Binary Object has come out of this process is the Concise Binary Object
Representation (CBOR) [RFC7049]. CBOR extended the data model of the Representation (CBOR) [RFC7049]. CBOR extended the data model of the
JavaScript Object Notation (JSON) [RFC7159] by allowing for binary JavaScript Object Notation (JSON) [RFC7159] by allowing for binary
data, among other changes. CBOR is being adopted by several of the data, among other changes. CBOR is being adopted by several of the
IETF working groups dealing with the IoT world as their encoding of IETF working groups dealing with the IoT world as their encoding of
skipping to change at page 6, line 21 skipping to change at page 6, line 21
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119]. [RFC2119].
When the words appear in lower case, their natural language meaning When the words appear in lower case, their natural language meaning
is used. is used.
1.3. CBOR Grammar 1.3. CBOR Grammar
There currently is no standard CBOR grammar available for use by There currently is no standard CBOR grammar available for use by
specifications. We therefore describe the CBOR structures in prose. specifications. The CBOR structures are therefore described in
prose.
The document was developed by first working on the grammar and then 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 developing the prose to go with it. An artifact of this is that the
prose was written using the primitive type strings defined by CBOR prose was written using the primitive type strings defined by CBOR
Data Definition Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl]. Data Definition Language (CDDL) [I-D.greevenbosch-appsawg-cbor-cddl].
In this specification, the following primitive types are used: In this specification, the following primitive types are used:
any - non-specific value that permits all CBOR values to be placed any - non-specific value that permits all CBOR values to be placed
here. here.
skipping to change at page 7, line 32 skipping to change at page 7, line 32
The non-terminal Internal_Types is defined for dealing with the The non-terminal Internal_Types is defined for dealing with the
automated validation tools used during the writing of this document. automated validation tools used during the writing of this document.
It references those non-terminals that are used for security It references those non-terminals that are used for security
computations, but are not emitted for transport. computations, but are not emitted for transport.
1.4. CBOR Related Terminology 1.4. CBOR Related Terminology
In JSON, maps are called objects and only have one kind of map key: a In JSON, maps are called objects and only have one kind of map key: a
string. In COSE, we use strings, negative integers and unsigned string. In COSE, we use strings, negative integers and unsigned
integers as map keys. The integers are used for compactness of integers as map keys. The integers are used for compactness of
encoding and easy comparison. Since the word "key" is mainly used in encoding and easy comparison. The incusion of strings allows for an
its other meaning, as a cryptographic key, we use the term "label" additional range of short encoded values to be used as well. Since
for this usage as a map key. the word "key" is mainly used in its other meaning, as a
cryptographic key, we use the term "label" for this usage as a map
key.
The presence of a label in a COSE map which is not a string or an The presence of a label in a COSE map which is not a string or an
integer is an error. Applications can either fail processing or integer is an error. Applications can either fail processing or
process messages with incorrect labels, however they MUST NOT create process messages with incorrect labels, however they MUST NOT create
messages with incorrect labels. messages with incorrect labels.
A CDDL grammar fragment is defined that defines the non-terminals A CDDL grammar fragment is defined that defines the non-terminals
'label', as in the previous paragraph and 'values', which permits any 'label', as in the previous paragraph and 'values', which permits any
value to be used. value to be used.
skipping to change at page 8, line 36 skipping to change at page 8, line 42
2. The set of unprotected header parameters as a map. 2. The set of unprotected header parameters as a map.
3. The content of the message. The content is either the plain text 3. The content of the message. The content is either the plain text
or the cipher text as appropriate. The content may be detached, or the cipher text as appropriate. The content may be detached,
but the location is still used. The content is wrapped in a bstr but the location is still used. The content is wrapped in a bstr
when present and is a nil value when detached. when present and is a nil value when detached.
Elements after this point are dependent on the specific message type. Elements after this point are dependent on the specific message type.
COSE messages are also built using the concept of using layers to
separate different types of cryptographic concepts. As an example of
how this works consider the COSE_Encrypt message (Section 5.1). This
message type is broken into two layers: the content layer and the
recipient layer. In the content layer, the plain text is encrypted
and information about the encrypted message are placed. In the
recipient layer, the content encryption key (CEK) is encrypted and
information about how it is encrypted for each recipient is placed.
A single layer version of the encryption message COSE_Encrypt0
(Section 5.2) is provided for cases where the CEK is pre-shared.
Identification of which type of message has been presented is done by Identification of which type of message has been presented is done by
the following method: the following method:
1. The specific message type is known from the context. This may be 1. The specific message type is known from the context. This may be
defined by a marker in the containing structure or by defined by a marker in the containing structure or by
restrictions specified by the application protocol. restrictions specified by the application protocol.
2. The message type is identified by a CBOR tag. Messages with a 2. The message type is identified by a CBOR tag. Messages with a
CBOR tag are known in this specification as tagged messages, CBOR tag are known in this specification as tagged messages,
while those without the CBOR tag are known as untagged messages. while those without the CBOR tag are known as untagged messages.
skipping to change at page 10, line 34 skipping to change at page 11, line 23
in the "COSE Header Parameters" IANA registry (Section 16.2). in the "COSE Header Parameters" IANA registry (Section 16.2).
Two buckets are provided for each layer: Two buckets are provided for each layer:
protected: Contains parameters about the current layer that are to protected: Contains parameters about the current layer that are to
be cryptographically protected. This bucket MUST be empty if it be cryptographically protected. This bucket MUST be empty if it
is not going to be included in a cryptographic computation. This is not going to be included in a cryptographic computation. This
bucket is encoded in the message as a binary object. This value bucket is encoded in the message as a binary object. This value
is obtained by CBOR encoding the protected map and wrapping it in is obtained by CBOR encoding the protected map and wrapping it in
a bstr object. Senders SHOULD encode an empty protected map as a a bstr object. Senders SHOULD encode an empty protected map as a
zero length binary object (i.e., the byte string h'a0'). This zero length binary object (i.e., the byte string h'40'). This
encoding is used because it is both shorter and the version used encoding is used because it is both shorter and the version used
in the serialization structures for cryptographic computation. in the serialization structures for cryptographic computation.
Recipients MUST accept both a zero length binary value and a zero Recipients MUST accept both a zero length binary value and a zero
length map encoded in the binary value. The wrapping allows for length map encoded in the binary value. The wrapping allows for
the encoding of the protected map to be transported with a greater the encoding of the protected map to be transported with a greater
chance that it will not be altered in transit. (Badly behaved chance that it will not be altered in transit. (Badly behaved
intermediates could decode and re-encode, but this will result in intermediates could decode and re-encode, but this will result in
a failure to verify unless the re-encoded byte string is identical a failure to verify unless the re-encoded byte string is identical
to the decoded byte string.) This avoids the problem of all to the decoded byte string.) This avoids the problem of all
parties needing to be able to do a common canonical encoding. parties needing to be able to do a common canonical encoding.
unprotected: Contains parameters about the current layer that are unprotected: Contains parameters about the current layer that are
not cryptographically protected. not cryptographically protected.
Only parameters that deal with the current layer are to be placed at Only parameters that deal with the current layer are to be placed at
that layer. As an example of this, the parameter 'content type' that layer. As an example of this, the parameter 'content type'
describes the content of the message being carried in the message. describes the content of the message being carried in the message.
As such, this parameter is placed only in the content layer and is As such, this parameter is placed only in the content layer and is
not placed in the recipient or signature layers. In principle, one not placed in the recipient or signature layers. In principle, one
should be able to process any given layer without reference to any should be able to process any given layer without reference to any
other layer. (With the exception of the COSE_Sign structure, the other layer. With the exception of the COSE_Sign structure, the only
only data that needs to cross layers is the cryptographic key.) data that needs to cross layers is the cryptographic key.
The buckets are present in all of the security objects defined in The buckets are present in all of the security objects defined in
this document. The fields in order are the 'protected' bucket (as a this document. The fields in order are the 'protected' bucket (as a
CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map' CBOR 'bstr' type) and then the 'unprotected' bucket (as a CBOR 'map'
type). The presence of both buckets is required. The parameters type). The presence of both buckets is required. The parameters
that go into the buckets come from the IANA "COSE Header Parameters" that go into the buckets come from the IANA "COSE Header Parameters"
registry (Section 16.2). Some common parameters are defined in the registry (Section 16.2). Some common parameters are defined in the
next section, but a number of parameters are defined throughout this next section, but a number of parameters are defined throughout this
document. document.
skipping to change at page 12, line 25 skipping to change at page 13, line 17
understand. Parameters defined in this document do not need to be understand. Parameters defined in this document do not need to be
included as they should be understood by all implementations. included as they should be understood by all implementations.
When present, this parameter MUST be placed in the protected When present, this parameter MUST be placed in the protected
header bucket. The array MUST have at least one value in it. header bucket. The array MUST have at least one value in it.
Not all labels need to be included in the 'crit' parameter. The Not all labels need to be included in the 'crit' parameter. The
rules for deciding which header labels are placed in the array rules for deciding which header labels are placed in the array
are: are:
* Integer labels in the range of 0 to 8 SHOULD be omitted. * Integer labels in the range of 0 to 8 SHOULD be omitted.
* Integer labels in the range -1 to -255 can be omitted as they * Integer labels in the range -1 to -128 can be omitted as they
are algorithm dependent. If an application can correctly are algorithm dependent. If an application can correctly
process an algorithm, it can be assumed that it will correctly process an algorithm, it can be assumed that it will correctly
process all of the common parameters associated with that process all of the common parameters associated with that
algorithm. (The algorithm range is -1 to -65536; the higher algorithm. Integer labels in the range -129 to -65536 SHOULD
end is for more optional algorithm specific items.) be included as these would be less common parameters that might
not be generally supported.
* Labels for parameters required for an application MAY be * Labels for parameters required for an application MAY be
omitted. Applications should have a statement if the label can omitted. Applications should have a statement if the label can
be omitted. be omitted.
The header parameter values indicated by 'crit' can be processed The header parameter values indicated by 'crit' can be processed
by either the security library code or by an application using a by either the security library code or by an application using a
security library; the only requirement is that the parameter is security library; the only requirement is that the parameter is
processed. If the 'crit' value list includes a value for which processed. If the 'crit' value list includes a value for which
the parameter is not in the protected bucket, this is a fatal the parameter is not in the protected bucket, this is a fatal
skipping to change at page 13, line 18 skipping to change at page 14, line 10
structure. Other methods of key distribution can define an structure. Other methods of key distribution can define an
equivalent field to be matched. Applications MUST NOT assume that equivalent field to be matched. Applications MUST NOT assume that
'kid' values are unique. There may be more than one key with the 'kid' values are unique. There may be more than one key with the
same 'kid' value, so all of the keys may need to be checked to same 'kid' value, so all of the keys may need to be checked to
find the correct one. The internal structure of 'kid' values is find the correct one. The internal structure of 'kid' values is
not defined and cannot be relied on by applications. Key not defined and cannot be relied on by applications. Key
identifier values are hints about which key to use. This is not a identifier values are hints about which key to use. This is not a
security critical field. For this reason, it SHOULD be placed in security critical field. For this reason, it SHOULD be placed in
the unprotected headers bucket. the unprotected headers bucket.
Initialization Vector This parameter holds the Initialization Vector IV This parameter holds the Initialization Vector (IV) value. For
(IV) value. For some symmetric encryption algorithms this may be some symmetric encryption algorithms this may be referred to as a
referred to as a nonce. As the IV is authenticated by the nonce. As the IV is authenticated by the encryption process, it
encryption process, it SHOULD be placed in the unprotected header SHOULD be placed in the unprotected header bucket.
bucket.
Partial Initialization Vector This parameter holds a part of the IV Partial IV This parameter holds a part of the IV value. When using
value. When using the COSE_Encrypt0 structure, a portion of the the COSE_Encrypt0 structure, a portion of the IV can be part of
IV can be part of the context associated with the key. This field the context associated with the key. This field is used to carry
is used to carry a value that causes the IV to be changed for each a value that causes the IV to be changed for each message. As the
message. As the IV is authenticated by the encryption process, IV is authenticated by the encryption process, this value can be
this value can be placed in the unprotected header bucket. The placed in the unprotected header bucket. The 'Initialization
'Initialization Vector' and 'Partial Initialization Vector' Vector' and 'Partial Initialization Vector' parameters MUST NOT
parameters MUST NOT both be present in the same security layer. both be present in the same security layer.
The message IV is generated by the following steps: The message IV is generated by the following steps:
1. Left pad the partial IV with zeros to the length of IV. 1. Left pad the partial IV with zeros to the length of IV.
2. XOR the padded partial IV with the context IV. 2. XOR the padded partial IV with the context IV.
counter signature This parameter holds one or more counter signature counter signature This parameter holds one or more counter signature
values. Counter signatures provide a method of having a second values. Counter signatures provide a method of having a second
party sign some data. The counter signature can occur as an party sign some data. The counter signature parameter can occur
unprotected attribute in any of the following structures: as an unprotected attribute in any of the following structures:
COSE_Sign, COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_Sign1, COSE_Signature, COSE_Encrypt, COSE_recipient,
COSE_recipient, COSE_Encrypt0, COSE_Mac and COSE_Mac0. These COSE_Encrypt0, COSE_Mac and COSE_Mac0. These structures all have
structures all have the same beginning elements so that a the same beginning elements so that a consistent calculation of
consistent calculation of the counter signature can be computed. the counter signature can be computed. Details on computing
Details on computing counter signatures are found in Section 4.5. counter signatures are found in Section 4.5.
+-----------+-------+----------------+-------------+----------------+ +-----------+-------+----------------+-------------+----------------+
| name | label | value type | value | description | | name | label | value type | value | description |
| | | | registry | | | | | | registry | |
+-----------+-------+----------------+-------------+----------------+ +-----------+-------+----------------+-------------+----------------+
| alg | 1 | int / tstr | COSE | Cryptographic | | alg | 1 | int / tstr | COSE | Cryptographic |
| | | | Algorithms | algorithm to | | | | | Algorithms | algorithm to |
| | | | registry | use | | | | | registry | use |
| | | | | | | | | | | |
| crit | 2 | [+ label] | COSE Header | Critical | | crit | 2 | [+ label] | COSE Header | Critical |
skipping to change at page 23, line 5 skipping to change at page 24, line 5
recipients : [+COSE_recipient] recipients : [+COSE_recipient]
] ]
The COSE_recipient structure is a CBOR array. The fields of the The COSE_recipient structure is a CBOR array. The fields of the
array in order are: array in order are:
protected as described in Section 3. protected as described in Section 3.
unprotected as described in Section 3. unprotected as described in Section 3.
ciphertext contains the encrypted key encoded as a bstr. If there ciphertext contains the encrypted key encoded as a bstr. All
is not an encrypted key, then this field is encoded as a nil encoded keys are symetric keys, the binary value of the key is the
value. content. If there is not an encrypted key, then this field is
encoded as a nil value.
recipients contains an array of recipient information structures. recipients contains an array of recipient information structures.
The type for the recipient information structure is a The type for the recipient information structure is a
COSE_recipient. (An example of this can be found in Appendix B.) COSE_recipient. (An example of this can be found in Appendix B.)
If there are no recipient information structures, this element is If there are no recipient information structures, this element is
absent. absent.
The CDDL fragment that corresponds to the above text for The CDDL fragment that corresponds to the above text for
COSE_recipient is: COSE_recipient is:
skipping to change at page 24, line 40 skipping to change at page 25, line 40
ciphertext as described in Section 5.1. ciphertext as described in Section 5.1.
The CDDL fragment for COSE_Encrypt0 that corresponds to the above The CDDL fragment for COSE_Encrypt0 that corresponds to the above
text is: text is:
COSE_Encrypt0 = [ COSE_Encrypt0 = [
Headers, Headers,
ciphertext : bstr / nil, ciphertext : bstr / nil,
] ]
5.3. Encryption Algorithm for AEAD algorithms 5.3. How to encrypt and decrypt for AEAD Algorithms
The encryption algorithm for AEAD algorithms is fairly simple. The The encryption algorithm for AEAD algorithms is fairly simple. The
first step is to create a consistent byte stream for the first step is to create a consistent byte stream for the
authenticated data structure. For this purpose, we use a CBOR array. authenticated data structure. For this purpose, we use a CBOR array.
The fields of the array in order are: The fields of the array in order are:
1. A text string identifying the context of the authenticated data 1. A text string identifying the context of the authenticated data
structure. The context string is: structure. The context string is:
"Encrypt0" for the content encryption of a COSE_Encrypt0 data "Encrypt0" for the content encryption of a COSE_Encrypt0 data
skipping to change at page 27, line 5 skipping to change at page 28, line 5
KDF used for the recipient. (For direct, the KDF can be KDF used for the recipient. (For direct, the KDF can be
thought of as the identity operation.) Examples of these thought of as the identity operation.) Examples of these
algorithms are found in Section 12.1.2 and Section 12.4.1. algorithms are found in Section 12.1.2 and Section 12.4.1.
Other: The key is determined by decoding and decrypting one of Other: The key is determined by decoding and decrypting one of
the recipient structures. the recipient structures.
4. Call the decryption algorithm with K (the decryption key to use), 4. Call the decryption algorithm with K (the decryption key to use),
C (the cipher text) and AAD. C (the cipher text) and AAD.
5.4. Encryption algorithm for AE algorithms 5.4. How to encrypt and decrypt for AE Algorithms
How to encrypt a message: How to encrypt a message:
1. Verify that the 'protected' field is empty. 1. Verify that the 'protected' field is empty.
2. Verify that there was no external additional authenticated data 2. Verify that there was no external additional authenticated data
supplied for this operation. supplied for this operation.
3. Determine the encryption key. This step is dependent on the 3. Determine the encryption key. This step is dependent on the
class of recipient algorithm being used. For: class of recipient algorithm being used. For:
skipping to change at page 32, line 15 skipping to change at page 33, line 15
7. Key Objects 7. Key Objects
A COSE Key structure is built on a CBOR map object. The set of A COSE Key structure is built on a CBOR map object. The set of
common parameters that can appear in a COSE Key can be found in the common parameters that can appear in a COSE Key can be found in the
IANA "COSE Key Common Parameters" registry (Section 16.5). IANA "COSE Key Common Parameters" registry (Section 16.5).
Additional parameters defined for specific key types can be found in Additional parameters defined for specific key types can be found in
the IANA "COSE Key Type Parameters" registry (Section 16.6). the IANA "COSE Key Type Parameters" registry (Section 16.6).
A COSE Key Set uses a CBOR array object as its underlying type. The A COSE Key Set uses a CBOR array object as its underlying type. The
values of the array elements are COSE Keys. A Key Set MUST have at values of the array elements are COSE Keys. A Key Set MUST have at
least one element in the array. least one element in the array. Examples of Key Sets can be found in
Appendix C.7.
Each element in a key set MUST be processed independently. If one Each element in a key set MUST be processed independently. If one
element in a key set is either malformed or uses a key that is not element in a key set is either malformed or uses a key that is not
understood by an application, that key is ignored and the other keys understood by an application, that key is ignored and the other keys
are processed normally. are processed normally.
The element "kty" is a required element in a COSE_Key map. The element "kty" is a required element in a COSE_Key map.
The CDDL grammar describing COSE_Key and COSE_KeySet is: The CDDL grammar describing COSE_Key and COSE_KeySet is:
skipping to change at page 66, line 12 skipping to change at page 67, line 12
is used in a store and forward format rather than in on line key is used in a store and forward format rather than in on line key
exchange. In order for this to be a problem, either the receiver exchange. In order for this to be a problem, either the receiver
public key has to be chosen maliciously or the sender has to be public key has to be chosen maliciously or the sender has to be
malicious. In either case, all security evaporates anyway. malicious. In either case, all security evaporates anyway.
A proof of possession of the private key associated with the public A proof of possession of the private key associated with the public
key is recommended when a key is moved from untrusted to trusted. key is recommended when a key is moved from untrusted to trusted.
(Either by the end user or by the entity that is responsible for (Either by the end user or by the entity that is responsible for
making trust statements on keys.) making trust statements on keys.)
12.5. Key Agreement with KDF 12.5. Key Agreement with Key Wrap
Key Agreement with Key Wrapping uses a randomly generated CEK. The Key Agreement with Key Wrapping uses a randomly generated CEK. The
CEK is then encrypted using a Key Wrapping algorithm and a key CEK is then encrypted using a Key Wrapping algorithm and a key
derived from the shared secret computed by the key agreement derived from the shared secret computed by the key agreement
algorithm. algorithm.
The COSE_Encrypt structure for the recipient is organized as follows: The COSE_Encrypt structure for the recipient is organized as follows:
o The 'protected' field is fed into the KDF context structure. o The 'protected' field is fed into the KDF context structure.
 End of changes. 22 change blocks. 
153 lines changed or deleted 169 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/