draft-ietf-cose-msg-10.txt   draft-ietf-cose-msg-11.txt 
COSE Working Group J. Schaad COSE Working Group J. Schaad
Internet-Draft August Cellars Internet-Draft August Cellars
Intended status: Informational February 7, 2016 Intended status: Informational March 21, 2016
Expires: August 10, 2016 Expires: September 22, 2016
CBOR Encoded Message Syntax CBOR Encoded Message Syntax
draft-ietf-cose-msg-10 draft-ietf-cose-msg-11
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 specifies processing for signatures, message format. This document specifies processing for signatures, message
authentication codes, and encryption using CBOR. This document also authentication codes, and encryption using CBOR. This document also
specifies a representation for cryptographic keys using CBOR. specifies a representation for cryptographic keys using CBOR.
skipping to change at page 1, line 43 skipping to change at page 1, line 43
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 August 10, 2016. This Internet-Draft will expire on September 22, 2016.
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 30 skipping to change at page 2, line 30
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 . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . 12 3.1. Common COSE Headers Parameters . . . . . . . . . . . . . 12
4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16 4. Signing Objects . . . . . . . . . . . . . . . . . . . . . . . 16
4.1. Signing with One or More Signers . . . . . . . . . . . . 16 4.1. Signing with One or More Signers . . . . . . . . . . . . 16
4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18 4.2. Signing with One Signer . . . . . . . . . . . . . . . . . 18
4.3. Externally Supplied Data . . . . . . . . . . . . . . . . 19 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 . . . . . . . . . . . . . . 21 4.5. Computing Counter Signatures . . . . . . . . . . . . . . 21
5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22 5. Encryption Objects . . . . . . . . . . . . . . . . . . . . . 22
5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22 5.1. Enveloped COSE Structure . . . . . . . . . . . . . . . . 22
5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 24 5.1.1. Recipient Algorithm Classes . . . . . . . . . . . . . 24
5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 24 5.2. Encrypted COSE structure . . . . . . . . . . . . . . . . 24
5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 25 5.3. Encryption Algorithm for AEAD algorithms . . . . . . . . 25
5.4. Encryption algorithm for AE algorithms . . . . . . . . . 26 5.4. Encryption algorithm for AE algorithms . . . . . . . . . 27
6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 27 6. MAC Objects . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.1. MAC Message with Recipients . . . . . . . . . . . . . . . 27 6.1. MAC Message with Recipients . . . . . . . . . . . . . . . 28
6.2. MAC Messages with Implicit Key . . . . . . . . . . . . . 28 6.2. MAC Messages with Implicit Key . . . . . . . . . . . . . 30
6.3. How to compute a MAC . . . . . . . . . . . . . . . . . . 29 6.3. How to compute and verify a MAC . . . . . . . . . . . . . 30
7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 30 7. Key Structure . . . . . . . . . . . . . . . . . . . . . . . . 32
7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 31 7.1. COSE Key Common Parameters . . . . . . . . . . . . . . . 32
8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 33 8. Signature Algorithms . . . . . . . . . . . . . . . . . . . . 35
8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 34 8.1. ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.1.1. Security Considerations . . . . . . . . . . . . . . . 35 8.1.1. Security Considerations . . . . . . . . . . . . . . . 38
9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 36 9. Message Authentication (MAC) Algorithms . . . . . . . . . . . 39
9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 36 9.1. Hash-based Message Authentication Codes (HMAC) . . . . . 39
9.1.1. Security Considerations . . . . . . . . . . . . . . . 38 9.1.1. Security Considerations . . . . . . . . . . . . . . . 41
9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 38 9.2. AES Message Authentication Code (AES-CBC-MAC) . . . . . . 41
9.2.1. Security Considerations . . . . . . . . . . . . . . . 39 9.2.1. Security Considerations . . . . . . . . . . . . . . . 42
10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 40 10. Content Encryption Algorithms . . . . . . . . . . . . . . . . 42
10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 40 10.1. AES GCM . . . . . . . . . . . . . . . . . . . . . . . . 43
10.1.1. Security Considerations . . . . . . . . . . . . . . 41 10.1.1. Security Considerations . . . . . . . . . . . . . . 44
10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 42 10.2. AES CCM . . . . . . . . . . . . . . . . . . . . . . . . 44
10.2.1. Security Considerations . . . . . . . . . . . . . . 45 10.2.1. Security Considerations . . . . . . . . . . . . . . 47
10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 45 10.3. ChaCha20 and Poly1305 . . . . . . . . . . . . . . . . . 47
10.3.1. Security Considerations . . . . . . . . . . . . . . 46 10.3.1. Security Considerations . . . . . . . . . . . . . . 48
11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 46 11. Key Derivation Functions (KDF) . . . . . . . . . . . . . . . 48
11.1. HMAC-based Extract-and-Expand Key Derivation Function 11.1. HMAC-based Extract-and-Expand Key Derivation Function
(HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 47 (HKDF) . . . . . . . . . . . . . . . . . . . . . . . . . 49
11.2. Context Information Structure . . . . . . . . . . . . . 49 11.2. Context Information Structure . . . . . . . . . . . . . 51
12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 53 12. Recipient Algorithm Classes . . . . . . . . . . . . . . . . . 54
12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 53 12.1. Direct Encryption . . . . . . . . . . . . . . . . . . . 55
12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 53 12.1.1. Direct Key . . . . . . . . . . . . . . . . . . . . . 55
12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 54 12.1.2. Direct Key with KDF . . . . . . . . . . . . . . . . 56
12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 56 12.2. Key Wrapping . . . . . . . . . . . . . . . . . . . . . . 57
12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 56 12.2.1. AES Key Wrapping . . . . . . . . . . . . . . . . . . 58
12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 57 12.3. Key Encryption . . . . . . . . . . . . . . . . . . . . . 59
12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 58 12.4. Direct Key Agreement . . . . . . . . . . . . . . . . . . 59
12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 59 12.4.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 60
12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 62 12.5. Key Agreement with KDF . . . . . . . . . . . . . . . . . 64
12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 62 12.5.1. ECDH . . . . . . . . . . . . . . . . . . . . . . . . 64
13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 13. Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 63 13.1. Elliptic Curve Keys . . . . . . . . . . . . . . . . . . 65
13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 64 13.1.1. Double Coordinate Curves . . . . . . . . . . . . . . 66
13.2. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 65 13.2. Symmetric Keys . . . . . . . . . . . . . . . . . . . . . 67
14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 66 14. CBOR Encoder Restrictions . . . . . . . . . . . . . . . . . . 68
15. Application Profiling Considerations . . . . . . . . . . . . 66 15. Application Profiling Considerations . . . . . . . . . . . . 68
16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 67 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69
16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 67 16.1. CBOR Tag assignment . . . . . . . . . . . . . . . . . . 69
16.2. COSE Header Parameter Registry . . . . . . . . . . . . . 68 16.2. COSE Header Parameter Registry . . . . . . . . . . . . . 70
16.3. COSE Header Algorithm Label Table . . . . . . . . . . . 68 16.3. COSE Header Algorithm Label Table . . . . . . . . . . . 70
16.4. COSE Algorithm Registry . . . . . . . . . . . . . . . . 69 16.4. COSE Algorithm Registry . . . . . . . . . . . . . . . . 71
16.5. COSE Key Common Parameter Registry . . . . . . . . . . . 70 16.5. COSE Key Common Parameter Registry . . . . . . . . . . . 72
16.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 71 16.6. COSE Key Type Parameter Registry . . . . . . . . . . . . 73
16.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 71 16.7. COSE Elliptic Curve Registry . . . . . . . . . . . . . . 73
16.8. Media Type Registrations . . . . . . . . . . . . . . . . 72 16.8. Media Type Registrations . . . . . . . . . . . . . . . . 74
16.8.1. COSE Security Message . . . . . . . . . . . . . . . 72 16.8.1. COSE Security Message . . . . . . . . . . . . . . . 74
16.8.2. COSE Key media type . . . . . . . . . . . . . . . . 73 16.8.2. COSE Key media type . . . . . . . . . . . . . . . . 75
16.9. CoAP Content Format Registrations . . . . . . . . . . . 75 16.9. CoAP Content Format Registrations . . . . . . . . . . . 77
16.10. Expert Review Instructions . . . . . . . . . . . . . . . 76 16.10. Expert Review Instructions . . . . . . . . . . . . . . . 78
17. Security Considerations . . . . . . . . . . . . . . . . . . . 77 17. Security Considerations . . . . . . . . . . . . . . . . . . . 79
18. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 78 18. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 80
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 78 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 80
19.1. Normative References . . . . . . . . . . . . . . . . . . 78 19.1. Normative References . . . . . . . . . . . . . . . . . . 80
19.2. Informative References . . . . . . . . . . . . . . . . . 79 19.2. Informative References . . . . . . . . . . . . . . . . . 81
Appendix A. Making Mandatory Items Optional . . . . . . . . . . 82 Appendix A. Making Mandatory Algorithm Header Optional . . . . . 84
A.1. Algorithm Identification . . . . . . . . . . . . . . . . 82 A.1. Algorithm Identification . . . . . . . . . . . . . . . . 84
A.2. Countersignature Without Headers . . . . . . . . . . . . 82 A.2. Counter Signature Without Headers . . . . . . . . . . . . 87
Appendix B. Three Levels of Recipient Information . . . . . . . 82 Appendix B. Three Levels of Recipient Information . . . . . . . 88
Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 83 Appendix C. Examples . . . . . . . . . . . . . . . . . . . . . . 89
C.1. Examples of Signed Message . . . . . . . . . . . . . . . 84 C.1. Examples of Signed Message . . . . . . . . . . . . . . . 90
C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 84 C.1.1. Single Signature . . . . . . . . . . . . . . . . . . 90
C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 85 C.1.2. Multiple Signers . . . . . . . . . . . . . . . . . . 91
C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 86 C.1.3. Counter Signature . . . . . . . . . . . . . . . . . . 92
C.1.4. Signature w/ Operation Time and Criticality . . . . . 87 C.1.4. Signature w/ Operation Time and Criticality . . . . . 93
C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 88 C.2. Single Signer Examples . . . . . . . . . . . . . . . . . 94
C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 88 C.2.1. Single ECDSA signature . . . . . . . . . . . . . . . 94
C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 89 C.3. Examples of Enveloped Messages . . . . . . . . . . . . . 95
C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 89 C.3.1. Direct ECDH . . . . . . . . . . . . . . . . . . . . . 95
C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 90 C.3.2. Direct plus Key Derivation . . . . . . . . . . . . . 96
C.3.3. Counter Signature on Encrypted Content . . . . . . . 91 C.3.3. Counter Signature on Encrypted Content . . . . . . . 97
C.3.4. Encrypted Content with External Data . . . . . . . . 93 C.3.4. Encrypted Content with External Data . . . . . . . . 99
C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 93 C.4. Examples of Encrypted Messages . . . . . . . . . . . . . 99
C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 93 C.4.1. Simple Encrypted Message . . . . . . . . . . . . . . 99
C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 94 C.4.2. Encrypted Message w/ a Partial IV . . . . . . . . . . 100
C.5. Examples of MAC messages . . . . . . . . . . . . . . . . 94 C.5. Examples of MAC messages . . . . . . . . . . . . . . . . 100
C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 94 C.5.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 100
C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 95 C.5.2. ECDH Direct MAC . . . . . . . . . . . . . . . . . . . 101
C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 96 C.5.3. Wrapped MAC . . . . . . . . . . . . . . . . . . . . . 102
C.5.4. Multi-recipient MAC message . . . . . . . . . . . . . 97 C.5.4. Multi-recipient MAC message . . . . . . . . . . . . . 103
C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 98 C.6. Examples of MAC0 messages . . . . . . . . . . . . . . . . 104
C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 98 C.6.1. Shared Secret Direct MAC . . . . . . . . . . . . . . 104
C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 99 C.7. COSE Keys . . . . . . . . . . . . . . . . . . . . . . . . 105
C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 99 C.7.1. Public Keys . . . . . . . . . . . . . . . . . . . . . 105
C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 100 C.7.2. Private Keys . . . . . . . . . . . . . . . . . . . . 106
Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 102 Appendix D. Document Updates . . . . . . . . . . . . . . . . . . 108
D.1. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 102 D.1. Version -09 to -10 . . . . . . . . . . . . . . . . . . . 108
D.2. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 103 D.2. Version -08 to -09 . . . . . . . . . . . . . . . . . . . 109
D.3. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 103 D.3. Version -07 to -08 . . . . . . . . . . . . . . . . . . . 109
D.4. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 103 D.4. Version -06 to -07 . . . . . . . . . . . . . . . . . . . 109
D.5. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 103 D.5. Version -05 to -06 . . . . . . . . . . . . . . . . . . . 109
D.6. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 103 D.6. Version -04 to -05 . . . . . . . . . . . . . . . . . . . 109
D.7. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 104 D.7. Version -03 to -04 . . . . . . . . . . . . . . . . . . . 110
D.8. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 104 D.8. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 110
D.9. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 104 D.9. Version -02 to -03 . . . . . . . . . . . . . . . . . . . 110
D.10. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 104 D.10. Version -01 to -2 . . . . . . . . . . . . . . . . . . . . 110
D.11. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 105 D.11. Version -00 to -01 . . . . . . . . . . . . . . . . . . . 111
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 111
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). CBOR extended the data model of the Representation (CBOR). CBOR extended the data model of the
JavaScript Object Notation (JSON) by allowing for binary data among JavaScript Object Notation (JSON) by allowing for binary data among
other changes. CBOR is being adopted by several of the IETF working other changes. CBOR is being adopted by several of the IETF working
groups dealing with the IOT world as their encoding of data groups dealing with the IOT world as their encoding of data
skipping to change at page 9, line 7 skipping to change at page 9, line 7
tags can be found in Table 1. tags can be found in Table 1.
3. When a COSE object is carried in a media type of application/ 3. When a COSE object is carried in a media type of application/
cose, the optional parameter 'cose-type' can be used to identify cose, the optional parameter 'cose-type' can be used to identify
the embedded object. The parameter is OPTIONAL if the tagged the embedded object. The parameter is OPTIONAL if the tagged
version of the structure is used. The parameter is REQUIRED if version of the structure is used. The parameter is REQUIRED if
the untagged version of the structure is used. The value to use the untagged version of the structure is used. The value to use
with the parameter for each of the structures can be found in with the parameter for each of the structures can be found in
Table 1. Table 1.
4. When a COSE object is carried in a CoAP message, the CoAP content 4. When a COSE object is carried as a CoAP payload, the CoAP content
type parameter can be used to identify the message content. The type parameter can be used to identify the message content. The
CoAP content types can be found in Table 23. The CBOR Tag for CoAP content types can be found in Table 23. The CBOR Tag for
the message structure is not required as each security message is the message structure is not required as each security message is
uniquely identified. uniquely identified.
+---------+----------------+-----------------+----------------------+ +---------+----------------+-----------------+----------------------+
| Tag | cose-type | Data Item | Semantics | | Tag | cose-type | Data Item | Semantics |
| Value | | | | | Value | | | |
+---------+----------------+-----------------+----------------------+ +---------+----------------+-----------------+----------------------+
| TBD1 | cose-sign | COSE_Sign | COSE Signed Data | | TBD1 | cose-sign | COSE_Sign | COSE Signed Data |
skipping to change at page 10, line 24 skipping to change at page 10, line 24
3. Header Parameters 3. Header Parameters
The structure of COSE has been designed to have two buckets of The structure of COSE has been designed to have two buckets of
information that are not considered to be part of the payload itself, information that are not considered to be part of the payload itself,
but are used for holding information about content, algorithms, keys, but are used for holding information about content, algorithms, keys,
or evaluation hints for the processing of the layer. These two or evaluation hints for the processing of the layer. These two
buckets are available for use in all of the structures except for buckets are available for use in all of the structures except for
keys. While these buckets can be present, they may not all be usable keys. While these buckets can be present, they may not all be usable
in all instances. For example, while the protected bucket is defined in all instances. For example, while the protected bucket is defined
as part of recipient structures, most of the algorithms that are used as part of the recipient structure, some of the algorithms used for
for recipients do not provide for authenticated data and thus the recipient structures do not provide for authenticated data. If this
bucket should not be used. is the case, the protected bucket should be left empty.
Both buckets are implemented as CBOR maps. The map key is a 'label' Both buckets are implemented as CBOR maps. The map key is a 'label'
(Section 1.4). The value portion is dependent on the definition for (Section 1.4). The value portion is dependent on the definition for
the label. Both maps use the same set of label/value pairs. The the label. Both maps use the same set of label/value pairs. The
integer and string values for labels has been divided into several integer and string values for labels has been divided into several
sections with a standard range, a private range, and a range that is sections with a standard range, a private range, and a range that is
dependent on the algorithm selected. The defined labels can be found dependent on the algorithm selected. The defined labels can be found
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:
skipping to change at page 12, line 27 skipping to change at page 12, line 27
This section defines a set of common header parameters. A summary of This section defines a set of common header parameters. A summary of
these parameters can be found in Table 2. This table should be these parameters can be found in Table 2. This table should be
consulted to determine the value of label as well as the type of the consulted to determine the value of label as well as the type of the
value. value.
The set of header parameters defined in this section are: The set of header parameters defined in this section are:
alg This parameter is used to indicate the algorithm used for the alg This parameter is used to indicate the algorithm used for the
security processing. This parameter MUST be present at each level security processing. This parameter MUST be present at each level
of a signed, encrypted or authenticated message. When the of a signed, encrypted or authenticated message except the
algorithm supports authenticating associated data, this parameter COSE_Sign structure. When the algorithm supports authenticating
MUST be in the protected header bucket. The value is taken from associated data, this parameter MUST be in the protected header
the 'COSE Algorithm Registry' (see Section 16.4). bucket. The value is taken from the 'COSE Algorithm Registry'
(see Section 16.4).
crit The parameter is used to indicate which protected header labels crit The parameter is used to indicate which protected header labels
an application that is processing a message is required to an application that is processing a message is required to
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:
skipping to change at page 13, line 22 skipping to change at page 13, line 22
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
error in processing the message. error in processing the message.
content type This parameter is used to indicate the content type of content type This parameter is used to indicate the content type of
the data in the payload or ciphertext fields. Integers are from the data in the payload or ciphertext fields. Integers are from
the 'CoAP Content-Formats' IANA registry table. Strings are from the 'CoAP Content-Formats' IANA registry table. Strings are from
the IANA 'Media Types' registry. Applications SHOULD provide this the IANA 'Media Types' registry. Applications SHOULD provide this
parameter if the content structure is potentially ambiguous. parameter if the content structure is potentially ambiguous.
kid This parameter one of the ways that can be used to find the key kid This parameter identifies one piece of data that can be used as
to be used. The value of this parameter is matched against the input to find the needed cryptographic key. The value of this
'kid' member in a COSE_Key structure. Applications MUST NOT parameter can be matched against the 'kid' member in a COSE_Key
assume that 'kid' values are unique. There may be more than one structure. Other methods of key distribution can define an
key with the same 'kid' value, it may be required that all of the equivalent field to be matched. Applications MUST NOT assume that
keys need to be checked to find the correct one. The internal 'kid' values are unique. There may be more than one key with the
structure of 'kid' values is not defined and cannot be relied on same 'kid' value, it may be required that all of the keys need to
by applications. Key identifier values are hints about which key be checked to find the correct one. The internal structure of
to use. They are not directly a security critical field. For 'kid' values is not defined and cannot be relied on by
this reason, they can be placed in the unprotected headers bucket. applications. Key identifier values are hints about which key to
use. They are not directly a security critical field. For this
reason, they can be placed in the unprotected headers bucket.
Initialization Vector This parameter holds the Initialization Vector Initialization Vector This parameter holds the Initialization Vector
(IV) value. For some symmetric encryption algorithms this may be (IV) value. For some symmetric encryption algorithms this may be
referred to as a nonce. As the IV is authenticated by encryption referred to as a nonce. As the IV is authenticated by encryption
process, it can be placed in the unprotected header bucket. process, it can be placed in the unprotected header bucket.
Partial Initialization Vector This parameter holds a part of the IV Partial Initialization Vector This parameter holds a part of the IV
value. When using the COSE_Encrypted structure, frequently a value. When using the COSE_Encrypted structure, frequently a
portion of the IV is part of the context associated with the key portion of the IV is part of the context associated with the key
value. This field is used to carry the portion of the IV that value. This field is used to carry a value that causes the IV to
changes for each message. As the IV is authenticated by the be changed for each message. As the IV is authenticated by the
encryption process, this value can be placed in the unprotected encryption process, this value can be placed in the unprotected
header bucket. The 'Initialization Vector' and 'Partial header bucket. The 'Initialization Vector' and 'Partial
Initialization Vector' parameters MUST NOT be present in the same Initialization Vector' parameters MUST NOT be present in the same
security layer. security layer.
The final IV is generated by concatenating the fixed portion of The message IV is generated by the following steps:
the IV, a zero string and the changing portion of the IV. The
length of the zero string is computed by taking the required IV 1. Left pad the partial IV with zeros to the length of IV.
length and subtracting the lengths of the fixed and changing IV
portions. 2. XOR the padded partial IV with the context IV.
counter signature This parameter holds a counter signature value. counter signature This parameter holds a counter signature value.
Counter signatures provide a method of having a second party sign Counter signatures provide a method of having a second party sign
some data. The counter signature can occur as an unprotected some data. The counter signature can occur as an unprotected
attribute in any of the following structures: COSE_Sign, attribute in any of the following structures: COSE_Sign,
COSE_Sign1, COSE_Signature, COSE_Enveloped, COSE_recipient, COSE_Sign1, COSE_Signature, COSE_Enveloped, COSE_recipient,
COSE_Encrypted, COSE_Mac and COSE_Mac0. These structures all have COSE_Encrypted, COSE_Mac and COSE_Mac0. These structures all have
the same beginning elements so that a consistent calculation of the same beginning elements so that a consistent calculation of
the counter signature can be computed. Details on computing the counter signature can be computed. Details on computing
counter signatures are found in Section 4.5. counter signatures are found in Section 4.5.
operation time This parameter provides the time the content operation time This parameter provides the time the content
cryptographic operation is performed. For signatures and cryptographic operation is performed. For signatures and
recipient structures, this would be the time that the signature or recipient structures, this would be the time that the signature or
recipient key object was created. For content structures, this recipient key object was created. For content structures, this
would be the time that the content structure was created. The would be the time that the content structure was created. The
unsigned integer value is the number of seconds, excluding leap unsigned integer value is the number of seconds, excluding leap
seconds, after midnight UTC, January 1, 1970. The field is seconds, after midnight UTC, January 1, 1970. The field is
primarily intended to be to be used for countersignatures, however primarily intended to be to be used for counter signatures,
it can additionally be used for replay detection as well. however it can additionally be used for replay detection as well.
+-----------+-------+----------------+-------------+----------------+ +-----------+-------+----------------+-------------+----------------+
| 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 |
| | | | Algorithm | algorithm to | | | | | Algorithm | algorithm to |
| | | | Registry | use | | | | | Registry | use |
| | | | | | | | | | | |
| crit | 2 | [+ label] | COSE Header | Critical | | crit | 2 | [+ label] | COSE Header | Critical |
skipping to change at page 16, line 12 skipping to change at page 16, line 12
because they do not need to be in every map, headers required in because they do not need to be in every map, headers required in
specific maps are discussed above. specific maps are discussed above.
Generic_Headers = ( Generic_Headers = (
? 1 => int / tstr, ; algorithm identifier ? 1 => int / tstr, ; algorithm identifier
? 2 => [+label], ; criticality ? 2 => [+label], ; criticality
? 3 => tstr / int, ; content type ? 3 => tstr / int, ; content type
? 4 => bstr, ; key identifier ? 4 => bstr, ; key identifier
? 5 => bstr, ; IV ? 5 => bstr, ; IV
? 6 => bstr, ; Partial IV ? 6 => bstr, ; Partial IV
? 7 => COSE_Signature, ; Counter signature ? 7 => COSE_Signature / [+COSE_Signature], ; Counter signature
? 8 => uint ; Operation time ? 8 => uint ; Operation time
) )
4. Signing Objects 4. Signing Objects
COSE supports two different signature structures. COSE_Sign allows COSE supports two different signature structures. COSE_Sign allows
for one or more signers to be applied to a single content. for one or more signers to be applied to a single content.
COSE_Sign1 is restricted to a single signer. The structures cannot COSE_Sign1 is restricted to a single signer. The structures cannot
be converted between each other, the signature computation includes a be converted between each other, the signature computation includes a
parameter identifying which structure is being used. parameter identifying which structure is being used.
4.1. Signing with One or More Signers 4.1. Signing with One or More Signers
The signature structure allows for one or more signatures to be The signature structure allows for one or more signatures to be
applied to a message payload. There are provisions for parameters applied to a message payload. There are provisions for parameters
about the content and parameters about the signature to be carried about the content and parameters about the signature to be carried
along with the signature itself. These parameters may be along with the signature itself. These parameters may be
authenticated by the signature, or just present. An example of a authenticated by the signature, or just present. An example of a
parameter about the content is the content type. Examples of parameter about the content is the content type. Examples of
parameters about the signature would be the algorithm and key used to parameters about the signature would be the algorithm and key used to
create the signature, when the signature was created, and a counter- create the signature, when the signature was created, and counter
signature. signatures.
When more than one signature is present, the successful validation of When more than one signature is present, the successful validation of
one signature associated with a given signer is usually treated as a one signature associated with a given signer is usually treated as a
successful signature by that signer. However, there are some successful signature by that signer. However, there are some
application environments where other rules are needed. An application environments where other rules are needed. An
application that employs a rule other than one valid signature for application that employs a rule other than one valid signature for
each signer must specify those rules. Also, where simple matching of each signer must specify those rules. Also, where simple matching of
the signer identifier is not sufficient to determine whether the the signer identifier is not sufficient to determine whether the
signatures were generated by the same signer, the application signatures were generated by the same signer, the application
specification must describe how to determine which signatures were specification must describe how to determine which signatures were
skipping to change at page 18, line 38 skipping to change at page 18, line 38
4.2. Signing with One Signer 4.2. Signing with One Signer
The signature structure can be encoded either with or without a tag The signature structure can be encoded either with or without a tag
depending on the context it will be used in. The signature structure depending on the context it will be used in. The signature structure
is identified by the CBOR tag TBD7. The CDDL fragment that is identified by the CBOR tag TBD7. The CDDL fragment that
represents this is: represents this is:
COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7 COSE_Sign1_Tagged = #6.997(COSE_Sign1) ; Replace 997 with TBD7
The CBOR object that carries the body, the signature and the
information about the body and signature is called the COSE_Sign1
structure. Examples of COSE Single signature messages can be found
in Appendix C.2.
The COSE_Sign1 structure is a CBOR array. The fields of the array in The COSE_Sign1 structure is a CBOR array. The fields of the array in
order are: 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.
payload as described in Section 4.1. payload as described in Section 4.1.
signature contains the computed signature value. The type of the signature contains the computed signature value. The type of the
skipping to change at page 19, line 24 skipping to change at page 19, line 30
ability for applications to provide additional data to be ability for applications to provide additional data to be
authenticated as part of the security, but that is not carried as authenticated as part of the security, but that is not carried as
part of the COSE object. The primary reason for supporting this can part of the COSE object. The primary reason for supporting this can
be seen by looking at the CoAP message structure [RFC7252] where the be seen by looking at the CoAP message structure [RFC7252] where the
facility exists for options to be carried before the payload. An facility exists for options to be carried before the payload. An
example of data that can be placed in this location would be CoAP example of data that can be placed in this location would be CoAP
options for transaction ids and nonces to check for replay options for transaction ids and nonces to check for replay
protection. If the data is in the options section, then it is protection. If the data is in the options section, then it is
available for routers to help in performing the replay detection and available for routers to help in performing the replay detection and
prevention. However, it may also be desired to protect these values prevention. However, it may also be desired to protect these values
so that if they cannot be modified in transit it can be detected. so that if they are be modified in transit it can be detected. This
This is the purpose of the externally supplied data field. is the purpose of the externally supplied data field.
This document describes the process for using a byte array of This document describes the process for using a byte array of
externally supplied authenticated data, however the method of externally supplied authenticated data, however the method of
constructing the byte array is a function of the application. constructing the byte array is a function of the application.
Applications that use this feature need to define how the externally Applications that use this feature need to define how the externally
supplied authenticated data is to be constructed. Such a supplied authenticated data is to be constructed. Such a
construction needs to take into account the following issues: construction needs to take into account the following issues:
o If multiple items are included, care needs to be taken that data o If multiple items are included, care needs to be taken that data
cannot bleed between the items. This is usually addressed by cannot bleed between the items. This is usually addressed by
skipping to change at page 20, line 26 skipping to change at page 20, line 34
bstr type. If there are no protected attributes, a bstr of bstr type. If there are no protected attributes, a bstr of
length zero is used. length zero is used.
3. The protected attributes from the signer structure encoded in a 3. The protected attributes from the signer structure encoded in a
bstr type. If there are no protected attributes, a bstr of bstr type. If there are no protected attributes, a bstr of
length zero is used. This field is omitted for the COSE_Sign1 length zero is used. This field is omitted for the COSE_Sign1
signature structure. signature structure.
4. The protected attributes from the application encoded in a bstr 4. The protected attributes from the application encoded in a bstr
type. If this field is not supplied, it defaults to a zero type. If this field is not supplied, it defaults to a zero
length binary string. length binary string. (See Section 4.3 for application guidance
on constructing this field.)
5. The payload to be signed encoded in a bstr type. The payload is 5. The payload to be signed encoded in a bstr type. The payload is
placed here independent of how it is transported. placed here independent of how it is transported.
The CDDL fragment which describes the above text is. The CDDL fragment which describes the above text is.
Sig_structure = [ Sig_structure = [
context: "Signature" / "Signature1" / "CounterSignature", context: "Signature" / "Signature1" / "CounterSignature",
body_protected: bstr, body_protected: bstr,
? sign_protected: bstr, ? sign_protected: bstr,
external_aad: bstr, external_aad: bstr,
payload: bstr payload: bstr
] ]
How to compute a signature: How to compute a signature:
1. Create a Sig_structure and populate it with the appropriate 1. Create a Sig_structure and populate it with the appropriate
fields. fields.
2. Create the value ToBeSigned by encoding the Sig_structure to a 2. Create the value ToBeSigned by encoding the Sig_structure to a
byte string. byte string using the encoding described in Section 14.
3. Call the signature creation algorithm passing in K (the key to 3. Call the signature creation algorithm passing in K (the key to
sign with), alg (the algorithm to sign with) and ToBeSigned (the sign with), alg (the algorithm to sign with) and ToBeSigned (the
value to sign). value to sign).
4. Place the resulting signature value in the 'signature' field of 4. Place the resulting signature value in the 'signature' field of
the map. the array.
How to verify a signature: How to verify a signature:
1. Create a Sig_structure object and populate it with the 1. Create a Sig_structure object and populate it with the
appropriate fields. appropriate fields.
2. Create the value ToBeSigned by encoding the Sig_structure to a 2. Create the value ToBeSigned by encoding the Sig_structure to a
byte string. byte string using the encoding described in Section 14..
3. Call the signature verification algorithm passing in K (the key 3. Call the signature verification algorithm passing in K (the key
to verify with), alg (the algorithm used sign with), ToBeSigned to verify with), alg (the algorithm used sign with), ToBeSigned
(the value to sign), and sig (the signature to be verified). (the value to sign), and sig (the signature to be verified).
In addition to performing the signature verification, one must also In addition to performing the signature verification, one must also
perform the appropriate checks to ensure that the key is correctly perform the appropriate checks to ensure that the key is correctly
paired with the signing identity and that the appropriate paired with the signing identity and that the appropriate
authorization is done. authorization is done.
skipping to change at page 21, line 48 skipping to change at page 22, line 9
of routing (i.e. a proxy signature). of routing (i.e. a proxy signature).
An example of a counter signature on a signature can be found in An example of a counter signature on a signature can be found in
Appendix C.1.3. An example of a counter signature in an encryption Appendix C.1.3. An example of a counter signature in an encryption
object can be found in Appendix C.3.3. object can be found in Appendix C.3.3.
The creation and validation of counter signatures over the different The creation and validation of counter signatures over the different
items relies on the fact that the structure of the objects have the items relies on the fact that the structure of the objects have the
same structure. The elements are a set of protected attributes, a same structure. The elements are a set of protected attributes, a
set of unprotected attributes and a body in that order. This means set of unprotected attributes and a body in that order. This means
that the Sig_structure can be used for in a uniform manner to get the that the Sig_structure can be used in a uniform manner to get the
byte stream for processing a signature. If the counter signature is byte stream for processing a signature. If the counter signature is
going to be computed over a COSE_Enveloped structure, the going to be computed over a COSE_Enveloped structure, the
body_protected and payload items can be mapped into the Sig_structure body_protected and payload items can be mapped into the Sig_structure
in the same manner as from the COSE_Sign structure. in the same manner as from the COSE_Sign structure.
It should be noted that only a signature algorithm with appendix (see It should be noted that only a signature algorithm with appendix (see
Section 8) can be used for counter signatures. This is because the Section 8) can be used for counter signatures. This is because the
body should be able to be processed without having to evaluate the body should be able to be processed without having to evaluate the
countersignature, and this is not possible for signature schemes with counter signature, and this is not possible for signature schemes
message recovery. with message recovery.
5. Encryption Objects 5. Encryption Objects
COSE supports two different encryption structures. COSE_Encrypted is COSE supports two different encryption structures. COSE_Encrypted is
used when a recipient structure is not needed because the key to be used when a recipient structure is not needed because the key to be
used is known implicitly. COSE_Enveloped is used the rest of time used is known implicitly. COSE_Enveloped is used the rest of time
time. This includes cases where there are multiple recipients, a time. This includes cases where there are multiple recipients, a
recipient algorithm other than direct is to be used, or the key to be recipient algorithm other than direct is to be used, or the key to be
used is not known. used is not known.
skipping to change at page 25, line 21 skipping to change at page 25, line 31
The CDDL fragment for COSE_Encrypted that corresponds to the above The CDDL fragment for COSE_Encrypted that corresponds to the above
text is: text is:
COSE_Encrypted = [ COSE_Encrypted = [
Headers, Headers,
ciphertext: bstr / nil, ciphertext: bstr / nil,
] ]
5.3. Encryption Algorithm for AEAD algorithms 5.3. Encryption Algorithm for AEAD algorithms
The encryption algorithm for AEAD algorithms is fairly simple. The encryption algorithm for AEAD algorithms is fairly simple. The
first step is to create a consistent byte stream for the
1. Create a CBOR array (Enc_structure) to encode the authenticated authenticated data structure. For this purpose we use a CBOR array,
data. the fields of the array in order are:
2. Place a context string in the form of a tstr in the first 1. A text string identifying the context of the authenticated data
location to identify the data and location being encoded. The structure. The context string is:
strings defined are:
"Encrypted" for the content encryption of an encrypted data "Encrypted" for the content encryption of an encrypted data
structure. structure.
"Enveloped" for the first level of an enveloped data structure "Enveloped" for the first level of an enveloped data structure
(i.e. for content encryption). (i.e. for content encryption).
"Env_Recipient" for a recipient encoding to be placed in an "Env_Recipient" for a recipient encoding to be placed in an
enveloped data structure. enveloped data structure.
"Mac_Recipient" for a recipient encoding to be placed in a MAC "Mac_Recipient" for a recipient encoding to be placed in a MAC
message structure. message structure.
"Rec_Recipient" for a recipient encoding to be placed in a "Rec_Recipient" for a recipient encoding to be placed in a
recipient structure. recipient structure.
3. Copy the protected header field from the message to be sent to 2. The protected attributes from the body structure encoded in a
the second location in the Enc_structure. bstr type. If there are no protected attributes, a bstr of
length zero is used.
4. If the application has supplied external additional authenticated 3. The protected attributes from the application encoded in a bstr
data to be included in the computation, then it is placed in the type. If this field is not supplied, it defaults to a zero
third location ('external_aad' field) of the Enc_structure. If length bstr. (See Section 4.3 for application guidance on
no data was supplied, then a zero length binary value is used. constructing this field.)
(See Section 4.3 for application guidance on constructing this The CDDL fragment which describes the above text is:
field.)
5. Encode the Enc_structure using a CBOR Canonical encoding Enc_structure = [
Section 14 to get the AAD value. context : "Enveloped" / "Encrypted" / "Env_Recipient" /
"Mac_Recipient" / "Rec_Recipient",
protected: bstr,
external_aad: bstr
]
6. Determine the encryption key. This step is dependent on the How to encrypt a message:
1. Create a Enc_structure and populate it with the appropriate
fields.
2. Encode the Enc_structure to a byte stream (AAD) using the
encoding described in Section 14.
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:
No Recipients: The key to be used is determined by the algorithm No Recipients: The key to be used is determined by the algorithm
and key at the current level. and key at the current level.
Direct and Direct Key Agreement: The key is determined by the Direct and Direct Key Agreement: The key is determined by the
key and algorithm in the recipient structure. The encryption key and algorithm in the recipient structure. The encryption
algorithm and size of the key to be used are inputs into the algorithm and size of the key to be used are inputs into the
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.) thought of as the identity operation.)
Other: The key is randomly generated. Other: The key is randomly generated.
7. Call the encryption algorithm with K (the encryption key to use), 4. Call the encryption algorithm with K (the encryption key to use),
P (the plain text) and AAD (the additional authenticated data). P (the plain text) and AAD. Place the returned cipher text into
Place the returned cipher text into the 'ciphertext' field of the the 'ciphertext' field of the structure.
structure.
8. For recipients of the message, recursively perform the encryption 5. For recipients of the message, recursively perform the encryption
algorithm for that recipient using the encryption key as the algorithm for that recipient using the encryption key as the
plain text. plain text.
The CDDL fragment which defines the Enc_structure used for the How to decrypt a message:
authenticated data structure is:
Enc_structure = [ 1. Create a Enc_structure and populate it with the appropriate
context : "Enveloped" / "Encrypted" / "Env_Recipient" / fields.
"Mac_Recipient" / "Rec_Recipient",
protected: bstr, 2. Encode the Enc_structure to a byte stream (AAD) using the
external_aad: bstr encoding described in Section 14.
]
3. Determine the decryption key. This step is dependent on the
class of recipient algorithm being used. For:
No Recipients: The key to be used is determined by the algorithm
and key at the current level.
Direct and Direct Key Agreement: The key is determined by the
key and algorithm in the recipient structure. The encryption
algorithm and size of the key to be used are inputs into the
KDF used for the recipient. (For direct, the KDF can be
thought of as the identity operation.)
Other: The key is determined by decoding and decrypting the
recipient structure.
4. Call the decryption algorithm with K (the decryption key to use),
C (the cipher text) and AAD.
5.4. Encryption algorithm for AE algorithms 5.4. Encryption algorithm for AE algorithms
How to encrypt a message:
1. Verify that the 'protected' field is absent. 1. Verify that the 'protected' field is absent.
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:
No Recipients: The key to be used is determined by the algorithm No Recipients: The key to be used is determined by the algorithm
and key at the current level. and key at the current level.
skipping to change at page 27, line 24 skipping to change at page 28, line 13
Other: The key is randomly generated. Other: The key is randomly generated.
4. Call the encryption algorithm with K (the encryption key to use) 4. Call the encryption algorithm with K (the encryption key to use)
and the P (the plain text). Place the returned cipher text into and the P (the plain text). Place the returned cipher text into
the 'ciphertext' field of the structure. the 'ciphertext' field of the structure.
5. For recipients of the message, recursively perform the encryption 5. For recipients of the message, recursively perform the encryption
algorithm for that recipient using the encryption key as the algorithm for that recipient using the encryption key as the
plain text. plain text.
How to decrypt a message:
1. Verify that the 'protected' field is absent.
2. Verify that there was no external additional authenticated data
supplied for this operation.
3. Determine the decryption key. This step is dependent on the
class of recipient algorithm being used. For:
No Recipients: The key to be used is determined by the algorithm
and key at the current level.
Direct and Direct Key Agreement: The key is determined by the
key and algorithm in the recipient structure. The encryption
algorithm and size of the key to be used are inputs into the
KDF used for the recipient. (For direct, the KDF can be
thought of as the identity operation.)
Other: The key is determined by decoding and decrypting the
recipient structure.
4. Call the decryption algorithm with K (the decryption key to use),
C (the cipher text) and AAD.
6. MAC Objects 6. MAC Objects
COSE supports two different MAC structures. COSE_MAC0 is used when a COSE supports two different MAC structures. COSE_MAC0 is used when a
recipient structure is not needed because the key to be used is recipient structure is not needed because the key to be used is
implicitly known. COSE_MAC is used for all other cases. These implicitly known. COSE_MAC is used for all other cases. These
include a requirement for multiple recipients, the key being unknown, include a requirement for multiple recipients, the key being unknown,
a recipient algorithm of other than direct. a recipient algorithm of other than direct.
6.1. MAC Message with Recipients 6.1. MAC Message with Recipients
skipping to change at page 29, line 6 skipping to change at page 30, line 19
recipients: [+COSE_recipient] recipients: [+COSE_recipient]
] ]
6.2. MAC Messages with Implicit Key 6.2. MAC Messages with Implicit Key
In this section we describe the structure and methods to be used when In this section we describe the structure and methods to be used when
doing MAC authentication for those cases where the recipient is doing MAC authentication for those cases where the recipient is
implicitly known. implicitly known.
The MAC message uses the COSE_Mac0 structure defined in this section The MAC message uses the COSE_Mac0 structure defined in this section
for carrying the body. for carrying the body. Examples of MAC messages with an implicit key
can be found in Appendix C.6.
The MAC structure can be encoded either with or without a tag The MAC structure can be encoded either with or without a tag
depending on the context it will be used in. The MAC structure is depending on the context it will be used in. The MAC structure is
identified by the CBOR tag TBD6. The CDDL fragment that represents identified by the CBOR tag TBD6. The CDDL fragment that represents
this is: this is:
COSE_Mac0_Tagged = #6.996(COSE_Mac0) ; Replace 996 with TBD6 COSE_Mac0_Tagged = #6.996(COSE_Mac0) ; Replace 996 with TBD6
The COSE_Mac0 structure is a CBOR array. The fields of the array in The COSE_Mac0 structure is a CBOR array. The fields of the array in
order are: order are:
skipping to change at page 29, line 34 skipping to change at page 30, line 48
tag contains the MAC value. tag contains the MAC value.
The CDDL fragment which corresponds to the above text is: The CDDL fragment which corresponds to the above text is:
COSE_Mac0 = [ COSE_Mac0 = [
Headers, Headers,
payload: bstr / nil, payload: bstr / nil,
tag: bstr, tag: bstr,
] ]
6.3. How to compute a MAC 6.3. How to compute and verify a MAC
In order to get a consistent encoding of the data to be In order to get a consistent encoding of the data to be
authenticated, the MAC_structure is used to have a canonical form. authenticated, the MAC_structure is used to have a canonical form.
The MAC_structure is a CBOR array. The fields of the MAC_structure The MAC_structure is a CBOR array. The fields of the MAC_structure
in order are: in order are:
1. A text string that identifies the structure that is being 1. A text string that identifies the structure that is being
encoded. This string is "MAC" for the COSE_Mac structure. This encoded. This string is "MAC" for the COSE_Mac structure. This
string is "MAC0" for the COSE_Mac0 structure. string is "MAC0" for the COSE_Mac0 structure.
2. The protected attributes from the COSE_MAC structure. If there 2. The protected attributes from the COSE_MAC structure. If there
are no protected attributes, a zero length bstr is used. are no protected attributes, a zero length bstr is used.
skipping to change at page 30, line 19 skipping to change at page 31, line 35
MAC_structure = [ MAC_structure = [
context: "MAC" / "MAC0", context: "MAC" / "MAC0",
protected: bstr, protected: bstr,
external_aad: bstr, external_aad: bstr,
payload: bstr payload: bstr
] ]
The steps to compute a MAC are: The steps to compute a MAC are:
1. Create a MAC_structure and fill in the fields. 1. Create a MAC_structure and populate it with the appropriate
fields.
2. Encode the MAC_structure using a canonical CBOR encoder. The 2. Encode the MAC_structure to a byte stream using the encoding
resulting bytes are the value to compute the MAC on. described in Section 14.
3. Compute the MAC and place the result in the 'tag' field of the 3. Call the MAC creation algorithm passing in K (the key to use),
COSE_Mac structure. alg (the algorithm to MAC with) and ToBeMaced (the value to
compute the MAC on).
4. Encrypt and encode the MAC key for each recipient of the message. 4. Place the resulting MAC in the 'tag' field of the COSE_Mac
structure.
5. Encrypt and encode the MAC key for each recipient of the message.
How to verify a MAC are:
1. Create a MAC_structure object and populate it with the
appropriate fields.
2. Encode the MAC_structure to a byte stream using the encoding
described in Section 14.
3. Obtain the cryptographic key from one of the recipients of the
message.
4. Call the MAC creation algorithm passing in K (the key to use),
alg (the algorithm to MAC with) and ToBeMaced (the value to
compute the MAC on).
5. Compare the MAC value to the 'tag' field of the COSE_Mac
structure.
7. Key Structure 7. Key Structure
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 registry 'COSE Key Common Parameter Registry' (Section 16.5). IANA registry 'COSE Key Common Parameter 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 registry 'COSE Key Type Parameters' (Section 16.6). the IANA registry 'COSE Key Type Parameters' (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
skipping to change at page 31, line 40 skipping to change at page 33, line 23
| | | | | permissible | | | | | | permissible |
| | | | | operations | | | | | | operations |
| | | | | | | | | | | |
| alg | 3 | tstr / int | COSE | Key usage | | alg | 3 | tstr / int | COSE | Key usage |
| | | | Algorithm | restriction to | | | | | Algorithm | restriction to |
| | | | Values | this algorithm | | | | | Values | this algorithm |
| | | | | | | | | | | |
| kid | 2 | bstr | | Key Identification | | kid | 2 | bstr | | Key Identification |
| | | | | value - match to | | | | | | value - match to |
| | | | | kid in message | | | | | | kid in message |
| | | | | |
| Base IV | 5 | bstr | | Base IV to be xor- |
| | | | | ed with Partial |
| | | | | IVs |
+---------+-------+----------------+-----------+--------------------+ +---------+-------+----------------+-----------+--------------------+
Table 3: Key Map Labels Table 3: Key Map Labels
kty: This parameter is used to identify the family of keys for this kty: This parameter is used to identify the family of keys for this
structure, and thus the set of key type specific parameters to be structure, and thus the set of key type specific parameters to be
found. The set of values defined in this document can be found in found. The set of values defined in this document can be found in
Table 19. This parameter MUST be present in a key object. Table 19. This parameter MUST be present in a key object.
Implementations MUST verify that the key type is appropriate for Implementations MUST verify that the key type is appropriate for
the algorithm being processed. The key type MUST be included as the algorithm being processed. The key type MUST be included as
skipping to change at page 32, line 26 skipping to change at page 34, line 11
identifier is not structured and can be anything from a user identifier is not structured and can be anything from a user
provided string to a value computed on the public portion of the provided string to a value computed on the public portion of the
key. This field is intended for matching against a 'kid' key. This field is intended for matching against a 'kid'
parameter in a message in order to filter down the set of keys parameter in a message in order to filter down the set of keys
that need to be checked. that need to be checked.
key_ops: This parameter is defined to restrict the set of operations key_ops: This parameter is defined to restrict the set of operations
that a key is to be used for. The value of the field is an array that a key is to be used for. The value of the field is an array
of values from Table 4. of values from Table 4.
Base IV: This parameter is defined to carry the base portion of an
IV. It is designed to be used with the partial IV header
parameter defined in Section 3.1. This field provides the ability
to associate a partial IV with a key that is then modified on a
per message basis with the parital IV.
Care needs to be taken that this is only used as part of a key
distribution algorithm that will ensure that it will be given only
to parties that will use it correctly. This is due to the fact
that many of the content encryption algorithms defined for COSE
require that IVs be unique for every message. Use of this field
will easily allow for this rule to be broken if not used
carefully. This field MUST be ignored unless an application
specifically calls for its use.
+---------+-------+-------------------------------------------------+ +---------+-------+-------------------------------------------------+
| name | value | description | | name | value | description |
+---------+-------+-------------------------------------------------+ +---------+-------+-------------------------------------------------+
| sign | 1 | The key is used to create signatures. Requires | | sign | 1 | The key is used to create signatures. Requires |
| | | private key fields. | | | | private key fields. |
| | | | | | | |
| verify | 2 | The key is used for verification of signatures. | | verify | 2 | The key is used for verification of signatures. |
| | | | | | | |
| encrypt | 3 | The key is used for key transport encryption. | | encrypt | 3 | The key is used for key transport encryption. |
| | | | | | | |
skipping to change at page 49, line 23 skipping to change at page 51, line 23
11.2. Context Information Structure 11.2. Context Information Structure
The context information structure is used to ensure that the derived The context information structure is used to ensure that the derived
keying material is "bound" to the context of the transaction. The keying material is "bound" to the context of the transaction. The
context information structure used here is based on that defined in context information structure used here is based on that defined in
[SP800-56A]. By using CBOR for the encoding of the context [SP800-56A]. By using CBOR for the encoding of the context
information structure, we automatically get the same type and length information structure, we automatically get the same type and length
separation of fields that is obtained by the use of ASN.1. This separation of fields that is obtained by the use of ASN.1. This
means that there is no need to encode the lengths for the base means that there is no need to encode the lengths for the base
elements as it is done by the encoding used in JOSE (Section 4.6.2 of elements as it is done by the encoding used in JOSE (Section 4.6.2 of
[RFC7518]). [CREF2] [RFC7518]).
The context information structure refers to PartyU and PartyV as the The context information structure refers to PartyU and PartyV as the
two parties which are doing the key derivation. Unless the two parties which are doing the key derivation. Unless the
application protocol defines differently, we assign PartyU to the application protocol defines differently, we assign PartyU to the
entity that is creating the message and PartyV to the entity that is entity that is creating the message and PartyV to the entity that is
receiving the message. By doing this association, different keys receiving the message. By doing this association, different keys
will be derived for each direction as the context information is will be derived for each direction as the context information is
different in each direction. different in each direction.
The context structure is built from information that is known to both The context structure is built from information that is known to both
skipping to change at page 50, line 5 skipping to change at page 52, line 5
o Fields can be defined by parameters from the message. We define a o Fields can be defined by parameters from the message. We define a
set of parameters in Table 13 which can be used to carry the set of parameters in Table 13 which can be used to carry the
values associated with the context structure. Examples of this values associated with the context structure. Examples of this
are identities and nonce values. These parameters are designed to are identities and nonce values. These parameters are designed to
be placed in the unprotected bucket of the recipient structure. be placed in the unprotected bucket of the recipient structure.
(They do not need to be in the protected bucket since they already (They do not need to be in the protected bucket since they already
are included in the cryptographic computation by virtue of being are included in the cryptographic computation by virtue of being
included in the context structure.) included in the context structure.)
+---------------+-------+-----------+-------------------------------+
| name | label | type | description |
+---------------+-------+-----------+-------------------------------+
| PartyU | -21 | bstr | Party U identity Information |
| identity | | | |
| | | | |
| PartyU nonce | -22 | bstr / | Party U provided nonce |
| | | int | |
| | | | |
| PartyU other | -23 | bstr | Party U other provided |
| | | | information |
| | | | |
| PartyV | -24 | bstr | Party V identity Information |
| identity | | | |
| | | | |
| PartyV nonce | -25 | bstr / | Party V provided nonce |
| | | int | |
| | | | |
| PartyV other | -26 | bstr | Party V other provided |
| | | | information |
+---------------+-------+-----------+-------------------------------+
Table 13: Context Algorithm Parameters
We define a CBOR object to hold the context information. This object We define a CBOR object to hold the context information. This object
is referred to as CBOR_KDF_Context. The object is based on a CBOR is referred to as CBOR_KDF_Context. The object is based on a CBOR
array type. The fields in the array are: array type. The fields in the array are:
AlgorithmID This field indicates the algorithm for which the key AlgorithmID This field indicates the algorithm for which the key
material will be used. This field is required to be present. The material will be used. This field is required to be present. The
field exists in the context information so that if the same field exists in the context information so that if the same
environment is used for different algorithms, then completely environment is used for different algorithms, then completely
different keys will be generated each of those algorithms. (This different keys will be generated each of those algorithms. (This
practice means if algorithm A is broken and thus can is easier to practice means if algorithm A is broken and thus can is easier to
skipping to change at page 52, line 5 skipping to change at page 54, line 27
SuppPrivInfo This field contains private information that is SuppPrivInfo This field contains private information that is
mutually known information. An example of this information would mutually known information. An example of this information would
be a pre-existing shared secret. (This could for example, be used be a pre-existing shared secret. (This could for example, be used
in combination with an ECDH key agreement to provide a secondary in combination with an ECDH key agreement to provide a secondary
proof of identity.) The field is optional and will only be proof of identity.) The field is optional and will only be
present if the application defines a structure for this present if the application defines a structure for this
information. Applications that define this SHOULD use CBOR to information. Applications that define this SHOULD use CBOR to
encode the data so that types and lengths are correctly included. encode the data so that types and lengths are correctly included.
+---------------+-------+-----------+-------------------------------+
| name | label | type | description |
+---------------+-------+-----------+-------------------------------+
| PartyU | -21 | bstr | Party U identity Information |
| identity | | | |
| | | | |
| PartyU nonce | -22 | bstr / | Party U provided nonce |
| | | int | |
| | | | |
| PartyU other | -23 | bstr | Party U other provided |
| | | | information |
| | | | |
| PartyV | -24 | bstr | Party V identity Information |
| identity | | | |
| | | | |
| PartyV nonce | -25 | bstr / | Party V provided nonce |
| | | int | |
| | | | |
| PartyV other | -26 | bstr | Party V other provided |
| | | | information |
+---------------+-------+-----------+-------------------------------+
Table 13: Context Algorithm Parameters
The following CDDL fragment corresponds to the text above. The following CDDL fragment corresponds to the text above.
PartyInfo = ( PartyInfo = (
? nonce : bstr / int, ? nonce : bstr / int,
? identity : bstr, ? identity : bstr,
? other : bstr, ? other : bstr,
) )
COSE_KDF_Context = [ COSE_KDF_Context = [
AlgorithmID : int / tstr, AlgorithmID : int / tstr,
skipping to change at page 60, line 28 skipping to change at page 62, line 16
| ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ | | ECDH-ES + | -25 | HKDF - | yes | none | ECDH ES w/ |
| HKDF-256 | | SHA-256 | | | HKDF - | | HKDF-256 | | SHA-256 | | | HKDF - |
| | | | | | generate key | | | | | | | generate key |
| | | | | | directly | | | | | | | directly |
| | | | | | | | | | | | | |
| ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ | | ECDH-ES + | -26 | HKDF - | yes | none | ECDH ES w/ |
| HKDF-512 | | SHA-512 | | | HKDF - | | HKDF-512 | | SHA-512 | | | HKDF - |
| | | | | | generate key | | | | | | | generate key |
| | | | | | directly | | | | | | | directly |
| | | | | | | | | | | | | |
| ECDH-SS + | -27 | HKDF - | no | none | ECDH ES w/ | | ECDH-SS + | -27 | HKDF - | no | none | ECDH SS w/ |
| HKDF-256 | | SHA-256 | | | HKDF - | | HKDF-256 | | SHA-256 | | | HKDF - |
| | | | | | generate key | | | | | | | generate key |
| | | | | | directly | | | | | | | directly |
| | | | | | | | | | | | | |
| ECDH-SS + | -28 | HKDF - | no | none | ECDH ES w/ | | ECDH-SS + | -28 | HKDF - | no | none | ECDH SS w/ |
| HKDF-512 | | SHA-512 | | | HKDF - | | HKDF-512 | | SHA-512 | | | HKDF - |
| | | | | | generate key | | | | | | | generate key |
| | | | | | directly | | | | | | | directly |
| | | | | | | | | | | | | |
| ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ | | ECDH-ES + | -29 | HKDF - | yes | A128KW | ECDH ES w/ |
| A128KW | | SHA-256 | | | Concat KDF | | A128KW | | SHA-256 | | | Concat KDF |
| | | | | | and AES Key | | | | | | | and AES Key |
| | | | | | wrap w/ 128 | | | | | | | wrap w/ 128 |
| | | | | | bit key | | | | | | | bit key |
| | | | | | | | | | | | | |
skipping to change at page 66, line 43 skipping to change at page 68, line 43
interoperability requirements are provided for how each of the interoperability requirements are provided for how each of the
individual services are used and how the algorithms are to be used individual services are used and how the algorithms are to be used
for interoperability. The requirements about which algorithms and for interoperability. The requirements about which algorithms and
which services are needed is deferred to each application. which services are needed is deferred to each application.
Applications are therefore intended to profile the usage of this Applications are therefore intended to profile the usage of this
document. This section provides a set of guidelines and topics that document. This section provides a set of guidelines and topics that
applications need to consider when using this document. applications need to consider when using this document.
o Applications need to determine the set of messages defined in this o Applications need to determine the set of messages defined in this
document that it will be using. The set of messages corresponds document that they will be using. The set of messages corresponds
fairly directly to the set of security services that are needed fairly directly to the set of security services that are needed
and to the security levels needed. and to the security levels needed.
o Applications may define new header parameters for a specific o Applications may define new header parameters for a specific
purpose. Applications will often times select specific header purpose. Applications will often times select specific header
parameters to use or not to use. For example, an application parameters to use or not to use. For example, an application
would normally state a preference for using either the IV or the would normally state a preference for using either the IV or the
partial IV parameter. If the partial IV parameter is specified, partial IV parameter. If the partial IV parameter is specified,
then the application would also need to define how the fixed then the application would also need to define how the fixed
portion of the IV would be determined. portion of the IV would be determined.
o When applications use externally defined authenticated data, they o When applications use externally defined authenticated data, they
need to define how that data is to be defined. This document need to define how that data is encoded. This document assumes
assumes that the data will be provided as a byte stream. More that the data will be provided as a byte stream. More information
information can be found in Section 4.3. can be found in Section 4.3.
o Applications need to determine the set of security algorithms that o Applications need to determine the set of security algorithms that
are to be used. When selecting the algorithms to be used as the are to be used. When selecting the algorithms to be used as the
mandatory to implement set, consideration should be given to mandatory to implement set, consideration should be given to
choosing different types of algorithms when two are chosen for a choosing different types of algorithms when two are chosen for a
specific purpose. An example of this would be choosing HMAC- specific purpose. An example of this would be choosing HMAC-
SHA512 and AES-CMAC as different MAC algorithms, the construction SHA512 and AES-CMAC as different MAC algorithms, the construction
is vastly different between these two algorithms. This means that is vastly different between these two algorithms. This means that
a weakening of one algorithm would be unlikely to lead to a a weakening of one algorithm would be unlikely to lead to a
weakening of the other algorithms. Of course, these algorithms do weakening of the other algorithms. Of course, these algorithms do
skipping to change at page 67, line 46 skipping to change at page 69, line 46
* Minimum requirements for the S/MIME, which have been updated * Minimum requirements for the S/MIME, which have been updated
over time [RFC2633][RFC5751]. over time [RFC2633][RFC5751].
16. IANA Considerations 16. IANA Considerations
16.1. CBOR Tag assignment 16.1. CBOR Tag assignment
It is requested that IANA assign the following tags from the "Concise It is requested that IANA assign the following tags from the "Concise
Binary Object Representation (CBOR) Tags" registry. It is requested Binary Object Representation (CBOR) Tags" registry. It is requested
that the tags be assigned in the 24 to 255 value range. that the tags for COSE_Sign1, COSE_Encrypted and COSE_Mac0 be
assigned in the 1 to 23 value range (i.e. one byte long when
encoded). It is requested that the rest of the tags be assigned in
the 24 to 255 value range (i.e. two bytes long when encoded).
The tags to be assigned are in table Table 1. The tags to be assigned are in table Table 1.
16.2. COSE Header Parameter Registry 16.2. COSE Header Parameter Registry
It is requested that IANA create a new registry entitled "COSE Header It is requested that IANA create a new registry entitled "COSE Header
Parameters". The registry is to be created as Expert Review Parameters". The registry is to be created as Expert Review
Required. Expert review guidelines are provided in Section 16.10 Required. Expert review guidelines are provided in Section 16.10
The columns of the registry are: The columns of the registry are:
skipping to change at page 77, line 12 skipping to change at page 79, line 12
requirements of the community and the messages structures should requirements of the community and the messages structures should
not be registered. not be registered.
17. Security Considerations 17. Security Considerations
There are a number of security considerations that need to be taken There are a number of security considerations that need to be taken
into account by implementers of this specification. The security into account by implementers of this specification. The security
considerations that are specific to an individual algorithm are considerations that are specific to an individual algorithm are
placed next to the description of the algorithm. While some placed next to the description of the algorithm. While some
considerations have been highlighted here, additional considerations considerations have been highlighted here, additional considerations
may be found in the documents referred to that have full details of may be found in the documents listed in the references.
the algorithm.
Implementations need to protect the private key for any individuals. Implementations need to protect the private key for any individuals.
There are some cases in this document that need to be highlighted on There are some cases in this document that need to be highlighted on
this issue. this issue.
o Using a the same key for two different algorithms can leak o Using the same key for two different algorithms can leak
information about the key. It is therefore recommended that keys information about the key. It is therefore recommended that keys
be restricted to a single algorithm. be restricted to a single algorithm.
o Use of 'direct' as a recipient algorithm combined with a second o Use of 'direct' as a recipient algorithm combined with a second
recipient algorithm, either directly in a separate message, recipient algorithm, either directly in a separate message,
exposes the direct key to the second recipient. exposes the direct key to the second recipient.
o Several of the algorithms in this document have limits on the o Several of the algorithms in this document have limits on the
number of times that a key can be used without leaking information number of times that a key can be used without leaking information
about the key. about the key.
skipping to change at page 78, line 11 skipping to change at page 80, line 10
different algorithm, but to include that selection of algorithm in different algorithm, but to include that selection of algorithm in
any distribution of key material and strictly enforce the matching of any distribution of key material and strictly enforce the matching of
algorithms in the key structure to algorithms in the message algorithms in the key structure to algorithms in the message
structure. In addition to checking that algorithms are correct, the structure. In addition to checking that algorithms are correct, the
key form needs to be checked as well. Do not use an 'EC2' key where key form needs to be checked as well. Do not use an 'EC2' key where
an 'oct' key is expected. an 'oct' key is expected.
Before using a key for transmission, or before acting on information Before using a key for transmission, or before acting on information
recieved, a trust decision on a key needs to be made. Is the data or recieved, a trust decision on a key needs to be made. Is the data or
action something that the entity associated with the key has a right action something that the entity associated with the key has a right
to see or a right to request. A number of factors are assoicated to see or a right to request. A number of factors are associated
with this trust decision. Some of the ones that are highlighted here with this trust decision. Some of the ones that are highlighted here
are: are:
o What are the permissions assoicated with the key owner? o What are the permissions associated with the key owner?
o Is the cryptographic algorithm acceptable in the current context? o Is the cryptographic algorithm acceptable in the current context?
o Have the restrictions associated with the key, such as algorithm o Have the restrictions associated with the key, such as algorithm
or freshness, been checked are are correct? or freshness, been checked and are correct?
o Is the request something that is reasonable given the current o Is the request something that is reasonable given the current
state of the application? state of the application?
o Have any security considerations that are part of the message been o Have any security considerations that are part of the message been
enforced? (As specified by the application or crit parameter.) enforced? (As specified by the application or crit parameter.)
One area that has been starting to get exposure is doing traffic
analysis of encrypted messages based on the length of the message.
This specification does not provide for a uniform method of providing
padding as part of the message structure. An observer can
distinguish between two different strings (for example 'YES' and
'NO') based on length for all of the content encryption algorithms
that are defined in this document. This means that it is up to
applications to document how content padding is to be done in order
to prevent or discourage such analysis. (For example the strings
could be defined as 'YES' and 'NO '.)
18. Acknowledgments 18. Acknowledgments
This document is a product of the COSE working group of the IETF. This document is a product of the COSE working group of the IETF.
19. References 19. References
19.1. Normative References 19.1. Normative References
[AES-GCM] Dworkin, M., "NIST Special Publication 800-38D: [AES-GCM] Dworkin, M., "NIST Special Publication 800-38D:
Recommendation for Block Cipher Modes of Operation: Recommendation for Block Cipher Modes of Operation:
skipping to change at page 82, line 11 skipping to change at page 84, line 19
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, DOI 10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>. <http://www.rfc-editor.org/info/rfc7518>.
[SP800-56A] [SP800-56A]
Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST Barker, E., Chen, L., Roginsky, A., and M. Smid, "NIST
Special Publication 800-56A: Recommendation for Pair-Wise Special Publication 800-56A: Recommendation for Pair-Wise
Key Establishment Schemes Using Discrete Logarithm Key Establishment Schemes Using Discrete Logarithm
Cryptography", May 2013. Cryptography", May 2013.
Appendix A. Making Mandatory Items Optional Appendix A. Making Mandatory Algorithm Header Optional
There has been a minority of the working group who have expressed a
strong desire to relax the rule that the algorithm identifier be
required to appear in each level of a COSE mesage. 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 which contains no attributes about itself.
A.1. Algorithm Identification A.1. Algorithm Identification
A.2. Countersignature Without Headers In this section are laid out three sets of recommendations. The
first set of recommendations apply to having an implicit algorithm
identified for a single layer of a COSE message. The second set of
recommendations apply to having multiple implicit algorithm
identified for multiple layers of a COSE message. The third set of
recommendations apply to having implicit algorithms for multiple COSE
message constructs.
RFC 2119 language is 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 message object. This normally applies to the
smallest of the COSE messages, specifically COSE_Sign1, COSE_Mac0 and
COSE_Encrypted, 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 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, the
key, the algorithm and the COSE structures it can be used for.
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 which make the algorithm identifier
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. (Exhaustive search 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 probably 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 security
coordinator) or if the system the application runs on combines
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 which 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 which use a KDF function
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 already protected by virtue of being used in the cryptogrpahic
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 message. An example of how this
would work is that the encryption context that an application
specifies contains a content encryption algorithm, a key wrap
algorithm, a key identifier, and a shared secret. The sender would
then omit sending the algorithm identifier at both the content layer
and the recipient layer leaving only the key identifier in situations
where it could not be implied.
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 normally in the recipient layer.
o
The third case is having multiple implicit algorithm identifiers, but
targeted at potentially unrelated layers or different COSE messages.
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, 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, 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 MAC messages, 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 which have different keys, but where the keys
may be used in coordinated manner.
For these cases, the following items need to be considered:
o Applications need to ...
A.2. Counter Signature Without Headers
TBD
o No parameter for counter sig
o Define to be signed structure
o id how key is decided
o external data struture includes alg id
o bind key in distribution
o single alg of key structure
o uniques of kid not real
o very specialized for small size
o kid can be either implied OR show as kid of what is counter signed
Appendix B. Three Levels of Recipient Information Appendix B. Three Levels of Recipient Information
All of the currently defined recipient algorithms classes only use All of the currently defined recipient algorithms classes only use
two levels of the COSE_Enveloped structure. The first level is the two levels of the COSE_Enveloped structure. The first level is the
message content and the second level is the content key encryption. message content and the second level is the content key encryption.
However, if one uses a recipient algorithm such as RSA-KEM (see However, if one uses a recipient algorithm such as RSA-KEM (see
Appendix A of RSA-KEM [RFC5990], then it make sense to have three Appendix A of RSA-KEM [RFC5990], then it make sense to have three
levels of the COSE_Enveloped structure. levels of the COSE_Enveloped structure.
skipping to change at page 105, line 30 skipping to change at page 111, line 30
o Start marking element 0 in registries as reserved. o Start marking element 0 in registries as reserved.
o Update examples. o Update examples.
Editorial Comments Editorial Comments
[CREF1] JLS: I have not gone through the document to determine what [CREF1] JLS: I have not gone through the document to determine what
needs to be here yet. We mostly want to grab terms that are needs to be here yet. We mostly want to grab terms that are
used in unusual ways or are not generally understood. used in unusual ways or are not generally understood.
[CREF2] Ilari: Look to see if we need to be clearer about how the fields
defined in the table are transported and thus why they have
labels.
Author's Address Author's Address
Jim Schaad Jim Schaad
August Cellars August Cellars
Email: ietf@augustcellars.com Email: ietf@augustcellars.com
 End of changes. 63 change blocks. 
230 lines changed or deleted 516 lines changed or added

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