idnits 2.17.1 draft-lucas-assure-data-security-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 71 longer pages, the longest (page 56) being 68 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 71 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 3 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2679 has weird spacing: '... System o<-RS...' == Line 2983 has weird spacing: '...ap data mana...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (September 13, 2017) is 2414 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '16' on line 1261 == Missing Reference: 'Key' is mentioned on line 2794, but not defined == Missing Reference: 'Encryption' is mentioned on line 2795, but not defined == Missing Reference: 'Generation' is mentioned on line 2806, but not defined == Missing Reference: 'Owner' is mentioned on line 2925, but not defined == Missing Reference: 'Mgmt B' is mentioned on line 3087, but not defined == Unused Reference: 'RFC4279' is defined on line 3371, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 3376, but no explicit reference was found in the text == Unused Reference: 'RFC5652' is defined on line 3381, but no explicit reference was found in the text == Unused Reference: 'RFC6347' is defined on line 3385, but no explicit reference was found in the text == Unused Reference: 'RFC7049' is defined on line 3389, but no explicit reference was found in the text == Unused Reference: 'RFC7250' is defined on line 3393, but no explicit reference was found in the text == Unused Reference: 'RFC7252' is defined on line 3399, but no explicit reference was found in the text == Unused Reference: 'RFC2898' is defined on line 3408, but no explicit reference was found in the text == Unused Reference: 'RFC5753' is defined on line 3412, but no explicit reference was found in the text == Unused Reference: 'RFC7228' is defined on line 3417, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 2898 (Obsoleted by RFC 8018) Summary: 3 errors (**), 0 flaws (~~), 22 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 opsawg Lucas 3 Internet Draft Cisco International Limited 4 Intended status: Standards track September 13, 2017 5 Expires: March 17, 2018 7 aSSURE Data Security 8 draft-lucas-assure-data-security-00.txt 10 Abstract 12 aSSURE uses industry standards and best practice to provide a 13 secure communications platform for device configuration and life 14 cycle management across the entire range of smart devices, from 15 the largest servers through to more constrained devices, with 16 minimal human involvement. Based on extensions to current standard 17 methods, aSSURE also provides secure end to end communication 18 across any network type. 20 A new approach allows key distribution and encrypted channels to 21 be established between devices that support RSA, EC and/or simple 22 shared secrets. For devices that only support shared secrets, key 23 derivation algorithms ensure that forward and backward compatible 24 secrecy is supported so that secure change of ownership can be 25 obtained. Owners prove ownership via a "case ID" known by the 26 manufacturer and the "Trusted Authority" ID Server but not known 27 by the device. 29 aSSURE defines end-to-end encryption links, called "channels", so 30 that pairs of devices communicate with a unique set of encryption 31 keys. These unique keys, coupled with the end-to-end encryption, 32 mean communication is both secure and private. 34 DTLS supports both certificates and pre-shared keys, but does not 35 cover key distribution or management. DTLS does not support 36 client-specific pre-shared keys because the client cannot identify 37 itself during the handshake. Herein are all the APIs required to 38 support key distribution and management as well as an extension to 39 the DTLS handshake that allows the client identity to be provided. 41 aSSURE cleanly integrates with the Open Interconnect Consortium 42 (OIC) architecture. Both use CBOR encoded data with CoAP over UDP 43 and DTLS. aSSURE URIs do not collide with OIC URIs and aSSURE 44 channels can be used as a secure transport for OIC requests. 46 Status of this Memo 48 This Internet-Draft is submitted in full conformance with the 49 provisions of BCP 78 and BCP 79. 51 Internet-Drafts are working documents of the Internet Engineering 52 Task Force (IETF). Note that other groups may also distribute 53 working documents as Internet-Drafts. The list of current 54 Internet- 55 Drafts is at http://datatracker.ietf.org/drafts/current/. 57 Internet-Drafts are draft documents valid for a maximum of six 58 months and may be updated, replaced, or obsoleted by other 59 documents at any time. It is inappropriate to use Internet-Drafts 60 as reference material or to cite them other than as "work in 61 progress." 63 This Internet-Draft will expire on March 17, 2018. 65 Copyright Notice 67 Copyright (c) 2017 IETF Trust and the persons identified as the 68 document authors. All rights reserved. 70 This document is subject to BCP 78 and the IETF Trust's Legal 71 Provisions Relating to IETF Documents 72 (http://trustee.ietf.org/license-info) in effect on the date of 73 publication of this document. Please review these documents 74 carefully, as they describe your rights and restrictions with 75 respect to this document. Code Components extracted from this 76 document must include Simplified BSD License text as described in 77 Section 4.e of the Trust Legal Provisions and are provided without 78 warranty as described in the Simplified BSD License. 80 Table of Contents 82 1. INTRODUCTION..................................................... 7 83 2. THE ROLE OF ASSURE IN AN IOT ENVIRONMENT......................... 8 84 2.1. Background..................................................... 8 85 2.2. Who am I allowed to talk to?................................... 8 86 2.3. How can I authenticate them?................................... 9 87 2.4. What am I allowed to tell them?................................ 9 88 2.5. What are they allowed to tell me?.............................. 9 89 2.6. How can I ensure that our communication is private?............ 9 90 3. TERMINOLOGY..................................................... 10 91 4. THE ROLE OF THE MANAGEMENT SYSTEM IN ASSURE..................... 10 92 4.1. Overview...................................................... 10 93 4.2. Creation of Communication Topologies.......................... 10 94 4.3. Examples of communication topologies.......................... 11 95 4.3.1. A "star" topology........................................... 11 96 4.3.2. A "ring" topology........................................... 11 97 4.3.3. A "tree" topology........................................... 12 98 4.3.4. A "fully connected" topology................................ 12 99 5. ASSURE ARCHITECTURE............................................. 13 100 5.1. Internet Accessible Deployments............................... 13 101 5.2. Walled Garden Deployments..................................... 14 102 6. SECURITY CONSIDERATIONS......................................... 15 103 6.1. Overview...................................................... 15 104 6.2. Guidelines for manufacturers.................................. 17 105 6.2.1. Device UUID................................................. 17 106 6.2.2. Device Asymmetric Key....................................... 17 107 6.2.3. Device Shared Secret........................................ 17 108 6.2.4. Case ID..................................................... 17 109 6.2.5. QR Code..................................................... 17 110 7. DATA STRUCTURES................................................. 18 111 7.1. Overview...................................................... 18 112 7.2. Key Definition................................................ 18 113 7.3. Signature Definition.......................................... 20 114 7.4. Authenticated Key Definition.................................. 21 115 7.5. Content Type IDs.............................................. 22 116 7.6. Key Format IDs................................................ 23 117 7.7. Identity Class IDs............................................ 23 118 7.8. Cipher Suite IDs.............................................. 24 119 7.9. Signature Format IDs.......................................... 24 120 7.10. Authenticated Key Metadata................................... 25 121 7.11. aSSURE timestamps............................................ 25 122 7.11.1. Simple timestamps.......................................... 25 123 7.11.2. Precision timestamps....................................... 25 124 8. DTLS WITH ASSURE KEY IDENTITIES................................. 26 125 8.1. Overview...................................................... 26 126 8.2. Extension to (D)TLS........................................... 26 127 8.2.1. Peer Name Indication........................................ 26 128 8.3. Proof of identity by public key clients....................... 27 129 8.4. Proof of identity by shared secret clients.................... 28 130 9. TRUSTED AUTHORITY APIS.......................................... 29 131 9.1. Overview...................................................... 29 132 9.2. Manufacturer API.............................................. 29 133 9.2.1. PUT /v1/devices/...................................... 30 134 9.2.2. POST /v1/parametersets...................................... 31 135 9.2.3. PUT /v1/parametersets/................................ 31 136 9.2.4. GET /v1/parametersets/................................ 31 137 9.3. Owner API..................................................... 32 138 9.3.1. POST /v1/managementsystems.................................. 32 139 9.3.2. PUT /v1/devices//owner?case_string=........... 33 140 9.3.3. PUT /v1/devices//owner?mgmtid=................ 33 141 9.3.4. PUT /v1/devices//owner?case_string=................... 34 142 &mgmtid= 34 143 9.3.5. PUT /v1/devices//owner?mgmtid=NULL.................... 34 144 9.3.6. GET /v1/devices//parameterset......................... 34 145 9.3.7. PUT /v1/devices//bootstrap............................ 35 146 9.3.8. GET /v1/devices//bootstrap............................ 35 147 9.4. Bootstrap API................................................. 36 148 9.4.1. GET /v1/devices//bootstrap............................ 36 149 10. DEVICE MANAGEMENT API.......................................... 36 150 10.1.1. PUT /v1/keys/........................................ 37 151 10.1.2. POST /v1/keys/generate?type=&persistent= 37 152 10.1.3. GET /v1/keys/........................................ 38 153 10.1.4. DELETE /v1/keys/..................................... 38 154 10.1.5. GET /v1/keys............................................... 39 155 10.1.6. PUT /v1/channels........................................... 39 156 10.1.7. PUT /v1/channels/...................................... 40 157 10.1.8. PUT /v1/channels//open......................... 41 158 10.1.9. PUT /v1/channels//close........................ 41 159 10.1.10. DELETE /v1/channels/.......................... 41 160 10.1.11. GET /v1/channels/..................................... 42 161 10.1.12. GET /v1/channels.......................................... 43 162 10.1.13. PUT /v1/reboot............................................ 44 163 10.1.14. PUT /v1/shutdown.......................................... 44 164 10.1.15. PUT /v1/bootstrap......................................... 44 165 10.1.16. GET /v1/ping.............................................. 45 166 10.1.17. GET /v1/info.............................................. 45 167 11. MANAGEMENT SERVER API.......................................... 46 168 11.1. Overview..................................................... 46 169 11.2. Registration API............................................. 46 170 11.2.1. POST /v1/devices/?case_string=.......... 46 171 11.2.2. POST /v1/devices//replace?uuid=........ 47 172 11.2.3. GET /v1/devices//status.............................. 47 173 11.2.4. GET /v1/devices//info................................ 47 174 11.3. Presence API................................................. 48 175 11.3.1. PUT /v1/devices//info................................ 48 176 11.3.2. PUT /v1/devices//goodbye............................. 49 177 11.4. Miscellaneous................................................ 49 178 11.4.1. GET /v1/timestamp.......................................... 49 179 12. PHYSICAL / NETWORK LAYER IMPLEMENTATIONS....................... 50 180 12.1. BACnet....................................................... 50 181 12.1.1. aSSURE Bootstrap........................................... 50 182 12.1.2. aSSURE Secure Management Channels.......................... 52 183 12.1.3. aSSURE Secure Data Channels................................ 52 184 12.2. IP........................................................... 52 185 12.2.1. Bootstrap Server FQDN...................................... 53 186 12.3. Bluetooth.................................................... 53 187 12.4. Assigned address types....................................... 53 188 13. DTLS CONNECTION CONFIGURATION EXAMPLES......................... 54 189 13.1. Example Topology............................................. 54 190 13.2. Elliptic Curve device . Elliptic Curve device................ 55 191 13.3. Elliptic Curve device . RSA device........................... 55 192 13.3.1. Option 1 - Issue EC key to RSA device...................... 55 193 13.3.2. Option 2 - Issue RSA key to EC device...................... 55 194 13.3.3. Option 3 - Issue Shared Secret to both devices............. 55 195 13.4. Elliptic Curve device . Shared Secret device................. 55 196 13.5. RSA device . RSA device...................................... 55 197 13.6. RSA device . Shared Secret device............................ 56 198 13.7. Shared Secret device . Shared Secret device.................. 56 199 14. MESSAGE SEQUENCE DIAGRAMS...................................... 57 200 14.1. Manufacturing Flow........................................... 57 201 14.2. Management System Preparation................................ 58 202 14.3. Device Registration.......................................... 59 203 14.4. Device Ownership State Machine............................... 60 204 14.5. Device Configuration and Bootstrap........................... 61 205 14.6. Device Configuration and Bootstrap (Walled Garden)........... 62 206 14.7. Device Change Owner.......................................... 63 207 15. CONFIGURATION AND BOOTSTRAP DATA FORMATS....................... 65 208 15.1. Overview..................................................... 65 209 15.2. Configuration data format.................................... 65 210 15.3. Device connection to the bootstrap server using DTLS using... 66 211 pre-shared secrets........................................... 66 212 15.4. Device connection to the bootstrap server using DTLS using... 66 213 public keys.................................................. 66 214 15.5. Bootstrap data format........................................ 66 215 15.5.1. Payload protected by Elliptic Curve keys................... 67 216 15.5.2. Payload protected by RSA keys.............................. 68 217 15.5.3. Payload protected by shared secrets........................ 68 218 15.5.4. Decrypted payload content.................................. 68 219 16. SECURITY CONSIDERATIONS........................................ 69 220 17. IANA CONSIDERATIONS............................................ 69 221 18. CONCLUSIONS.................................................... 69 222 19. REFERENCES..................................................... 69 223 19.1. Normative References......................................... 69 224 19.2. Informative References....................................... 70 225 20. ACKNOWLEDGMENTS............................................... 711 226 Table of Figures 228 Star Topology 11 229 Ring Topology 11 230 Tree Topology 12 231 Fully Connected Topology 12 232 Internet-accessible architecture 13 233 Walled-garden architecture 14 234 DTLS Connection Example Topology 55 235 Manufacturing Flow Sequence Diagram 57 236 Management System Preparation Sequence Diagram 58 237 Device Registration Sequence Diagram 59 238 Device Ownership State Machine 60 239 Device Configuration and Bootstrap Sequence Diagram 61 240 Device Configuration and Bootstrap Sequence Diagram 241 (Walled Garden) 62 242 Device Change Owner Sequence Diagram (first part) 63 243 Device Change Owner Sequence Diagram (second part) 64 245 Glossary of Terms 247 API Application Programming Interface 248 CA Certificate Authority 249 CBOR Concise Binary Object Representation, RFC-7049 250 CoAP Constrained Application Protocol, RFC-7252 251 DHCP Dynamic Host Configuration Protocol 252 DNS Domain Name System 253 DTLS Datagram Transport Layer Security (v1.2), RFC-6347 254 EC Elliptic Curve 255 ECDSA E C Digital Signature Algorithm, NIST FIPS 186-4 256 ECIES Elliptic Curve Integrated Encryption Scheme, ANSI X9.63 257 FQDN Fully Qualified Domain Name 258 PKCS Public Key Cryptography Service 259 PKI Public Key Infrastructure 260 TA Trusted Authority 261 TLS Transport Layer Security (v1.2), RFC-5246 263 1. Introduction 265 This document provides the reference technical specification for 266 aSSURE. 268 aSSURE uses industry standards and best practice to provide a 269 secure communications platform for device configuration and life 270 cycle management. Where possible, a minimal approach is taken to 271 standards implementation so that the complexity and code footprint 272 for implementation is kept to a minimum. 274 The underlying standards are: 275 o Transport Layer Security, TLS v1.2, RFC-5246 276 o Datagram Transport Layer Security, DTLS v1.2, RFC-6347 277 o Constrained Application Framework, CoAP, RFC-7252 278 o Concise Binary Object Representation, CBOR, RFC-7049 279 o CoAP Block-wise Transfers, https://www.ietf.org/id/draft-ietf 280 o core-block-21.txt 282 The additional functionality provided by aSSURE is intended to 283 work within existing communications frameworks. This allows aSSURE 284 to provide an upgrade path to add a common security approach that 285 provides both secure communications and lifecycle management 286 including change of ownership. aSSURE uses a "Trusted Authority" 287 (TA), similar to the role that a Certificate Authority (CA) plays 288 in a Public Key Infrastructure (PKI) today, to track the 289 manufacture and ownership of devices. Any number of Trusted 290 Authorities may exist but each device will be assigned to a 291 specific TA during its manufacture and will remain assigned to 292 this TA for its entire life. 294 Device owners communicate with the various Trusted Authorities to 295 assert ownership of individual devices and upload the initial 296 configuration for the device. When the device powers up, it will 297 contact the Trusted Authority to obtain its initial configuration 298 - this process is called "bootstrap". The initial configuration 299 will provide sufficient information for the device to establish a 300 secure communications channel to the system that will be managing 301 it. Once this channel is established, additional configuration 302 will be provided from the management system directly to the device 303 and the device can enter "normal service". 305 The detailed device lifecycle flow is described elsewhere. 307 Note 308 aSSURE is designed to cleanly integrate with the Open Interconnect 309 Consortium (OIC) architecture. Both OIC and aSSURE use CBOR 310 encoded data with CoAP over UDP and DTLS. aSSURE URIs have been 311 deliberately chosen not to collide with OIC URIs and aSSURE 312 channels can be used as a secure transport for OIC requests. 314 2. The role of aSSURE in an IoT environment 316 2.1. Background 318 In any secure environment, there are five basic questions that any 319 device must ask: 321 1. Who am I allowed to talk to? 322 2. How can I authenticate them? 323 3. What am I allowed to tell them? 324 4. What are they allowed to tell me? 325 5. How can I ensure that our communication is private? 327 If these basic questions can all be answered with confidence, 328 there is the foundation for a secure system. If any of the above 329 are uncertain then the system has weaknesses that may be exploited 330 by an attacker. 332 The aSSURE standard provides an answer to all these questions in a 333 way that allows devices to communicate across different network 334 architectures and device capabilities yet still providing end-to 335 end security at a level that is appropriate to the abilities of 336 the devices that are communicating. 338 Furthermore, aSSURE provides this with a solution that involves 339 minimal human involvement. 341 The following sections will address each of these questions in 342 turn. 344 2.2. Who am I allowed to talk to? 346 In many ways, this is one of the biggest hurdles to overcome. If 347 we want to be able to manufacture and sell "generic" product that 348 has no pre-configuration, how does that device know that we own 349 it? There are a lot of different approaches to this with "Trusted 350 On First Use" (TOFU) being an obvious one, but with all of them 351 they either have weaknesses in the initial security or rely on 352 public key cryptography. 354 Public key cryptography is fine in more powerful devices, but not 355 an option in the smallest ones, so for a universally secure 356 solution, a different approach is required. 358 The aSSURE standard uses a Trusted Authority (TA) as the reference 359 for the device. The device is programmed with the identity and 360 credentials of the TA during manufacture and, on first power up, 361 will only talk to the TA. The user will register ownership of the 362 device with the TA and securely upload the initial configuration 363 data for the device to the TA. The TA will then forward that 364 configuration to the device. That configuration includes the 365 location and security parameters for the device to connect to the 366 owner's systems, so now the device knows that it can trust its 367 owner. 369 Once the device has connected to the owner's management system, 370 this system can deliver additional configuration parameters, 371 encryption keys, etc. to the device. This allows the management 372 system to tell devices to set up secure peer-to-peer connections, 373 connect to additional management systems and perform other 374 actions. 376 2.3. How can I authenticate them? 378 The same sequence as for 2.2. above is used to provide the 379 authentication details to the device. This information allows the 380 device to authenticate the owner's systems and allows the owner's 381 systems to authenticate the device. 383 2.4. What am I allowed to tell them? 385 The same sequence as for 2.2. above is used to provide the access 386 control rules for access to the device data. This allows the 387 device to know what information it can disclose. 389 2.5. What are they allowed to tell me? 391 The same sequence as for 2.2. above is used to provide the access 392 control rules for commands and configuration sent to the device. 393 This allows the device to know what parameters and commands it 394 will accept from the owner's systems. 396 2.6. How can I ensure that our communication is private? 398 The aSSURE standard defines end-to-end encryption links, called 399 "channels", that ensure each pair of devices communicate with a 400 unique set of encryption keys. These unique keys, coupled with the 401 end-to-end encryption, means that their communication is both 402 secure and private. 404 3. Terminology 406 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 407 NOT","SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 408 in this document are to be interpreted as described in RFC 2119 409 [RFC2119]. 411 In this document, these words will appear with that interpretation 412 only when in ALL CAPS. Lower case uses of these words are not to 413 be interpreted as carrying significance described in RFC 2119. 415 In this document, the characters ">>" preceding an indented 416 line(s) indicates a statement using the key words listed above. 417 This convention aids reviewers in quickly identifying or finding 418 The portions of this RFC covered by these keywords. 420 4. The role of the Management System in aSSURE 422 4.1. Overview 424 The Management System is a key part in the trust relationship that 425 the device creates. The root of trust is the Trusted Authority. 426 The Trusted Authority tells the device which management systems(s) 427 it can trust. The Management Systems tell the device which other 428 management systems and devices it can trust (if any) and what 429 their permissions are on the device. 431 4.2. Creation of Communication Topologies 433 The Management System can instruct the aSSURE devices to form any 434 topology that is within their capabilities. The limits on the 435 topology types and complexity are only: 437 o Limitations set by the underlying network architecture 438 o Limitations set by the device memory and/or processing power 439 o and/or software 440 o Limitations set by the management software 442 In aSSURE terminology, each connection between devices is called a 443 channel. The rules about how channel keys are determined and 444 assigned is described in detail in section 13. below. 446 4.3. Examples of communication topologies 448 4.3.1. A "star" topology 449 _______ 450 / \ 451 | Device| 452 _______ \_______/ ______ 453 / \ | / \ 454 | Device| | |Device| 455 \_______/\ | /\______/ 456 \ ___|___ / 457 / \ 458 | Device| 459 \_______/ 460 _______ / | \ _______ 461 / \/ | \/ \ 462 | Device| | | Device| 463 \_______/ ___|___ \_______/ 464 / \ 465 | Device| 466 \_______/ 468 Star Topology 470 4.3.2. A "ring" topology 471 _______ 472 / \ 473 | Device| 474 _______ /\_______/\ ______ 475 / \/ \/ \ 476 | Device| |Device| 477 \_______/ \______/ 478 | | 479 | | 480 ___|___ ___|___ 481 / \ / \ 482 | Device| | Device| 483 \_______/\ _______ /\_______/ 484 \/ \/ 485 | Device| 486 \_______/ 488 Ring Topology 490 4.3.3. A "tree" topology 491 _______ 492 / \ 493 | Device| 494 _______ \_______/ ______ 495 / \ | / \ 496 | Device| | |Device| 497 \_______/\ | /\______/ 498 \ ___|___ / 499 / \ 500 | Device| 501 \_______/ 502 _______ | _______ 503 / \ | / \ 504 | Device| | | Device| 505 \_______/\ ___|___ /\_______/ 506 \/ \/ 507 | Device| 508 \_______/ 510 Tree Topology 512 4.3.4. A "fully connected" topology 514 The fully connected topology shows four devices where each device 515 has a connector to all of the other three devices. If there are 516 "n" devices they each have "n-1" connectors. 517 _______ _______ 518 / \ / \ 519 | Device|<------->| Device| 520 \_______/ \_______/ 521 ^ ^ ^ ^ 522 | \ / | 523 | \ --/ | 524 | \ / | 525 | ------ | 526 | / \ | 527 | --/ \ | 528 | / \ | 529 __v_ _v_ v____v_ 530 / \ / \ 531 | Device|<------->| Device| 532 \_______/ \_______/ 534 Fully Connected Topology 536 5. aSSURE Architecture 538 5.1. Internet Accessible Deployments 540 TRUSTED AUTHORITY MANUFACTURER 541 +-------------------------+ +--------------------------+ 542 | | | | 543 |+----------------------+ | | +--------------+ | 544 || MANUFACTURER |<--(-)--------|MANUFACTURING |-- | 545 || GATEWAY | |Manufacturer| SYSTEM | | | 546 |+--------------------!-+ | Interface +--------------+ | | 547 | | ! | | V | 548 | | ! | | +-------+ | 549 | | ! | | Short-Lived | DEVICE| | 550 | | +--A-I-R-G-A-P-!---| | Make & Delete +-------+ | 551 | | | ! | | ! | 552 | | A LOCK ! | +--------------------!-----+ 553 | | I +-----------V-+ | ! 554 | | R | IDENTITY | | ! 555 | | G | SERVER | | ! 556 | | A +-----------!-+ | OWNER ! 557 | | P ! | +------------------------!-----+ 558 | | | ! | | ! | 559 | | +---A-I-R-G-A-P!---| | Bootstrap Interface+---v---+ | 560 | v ! | | -----(-)-------| DEVICE| | 561 |+-----------------+ ! | | / +-------+ | 562 || REGISTRATION | ! | | / /|QR CODE| | 563 || SERVER | ! | | / / +-------+ | 564 |+-----------------+ ! | | / / | | 565 | ^ ^ ! | |/ (/) | | 566 | | | ! | / Management v | 567 | | +------------V-+ | (/) Interface +-------+ | 568 | | | BOOTSTRAP |<--/ | (/) INSTALLER | 569 | | | SERVER | | | / +-------+ | 570 | | +--------------+ | | / / | 571 | | ^ | | / (/) | 572 | | | | | +------v----+ Registration | 573 | | | | | | | Interface | 574 | | | | | | MANAGEMENT| (/) | 575 |+-------------+ | | | SYSTEM | / | 576 || OWNER | | | | | / | 577 || GATEWAY |<--------(-)-----| | / | 578 |+-------------+ Owner | | |v | 579 | Interface| +-----------+ | 580 | | | | 581 | | | | 582 +-------------------------+ +------------------------------+ 584 Internet-accessible architecture 586 5.2. Walled Garden Deployments 588 TRUSTED AUTHORITY MANUFACTURER 589 +----------------------+ +----------------------------+ 590 | | | | 591 |+-------------------+ | | +----------------+ | 592 || MANUFACTURER |<----(-)------| MANUFACTURING |-- | 593 || GATEWAY | |Manufacturer| SYSTEM | | | 594 |+-----------------!-+ | Interface +----------------+ | | 595 | | ! | | V | 596 | | ! | | Short-lived +-------+ | 597 | | ! | | Make & Delete | DEVICE| | 598 | | +--A-I-R-G-A-P-!---| | +-------+ | 599 | | | ! | | ! | 600 | | A LOCK ! | +----------------------!-----+ 601 | | I +-----------V-+ | ! 602 | | R | IDENTITY | | ! 603 | | G | SERVER | | ! 604 | | A +-----------!-+ | OWNER ! 605 | | P ! | +----------------------------!-----+ 606 | | | ! | | ! | 607 | | +---A-I-R-G-A-P!---| |+-----------+ Bootstrap +---v---+ | 608 | v ! | || Bootstrap|<--(-)-----| DEVICE| | 609 |+--------------+ ! | || Server | Interface +-------+ | 610 || REGISTRATION | ! | |+-----------+ / |QR CODE| | 611 || SERVER | ! | | ^ (/) +-------+ | 612 |+--------------+ ! | | ! +----------+ Management | | 613 | ^ ^ ! | | ! |Management| Interface | | 614 | | | ! | | ! | Server |<-/ | | 615 | | +------------V-+ | | ! +----------+ | | 616 | | | BOOTSTRAP | | | ! ^ | | 617 | | | SERVER | | +=!===!===WALLED=GARDEN======|=====| 618 | | +--------------+ | | ! ! v | 619 | | ^ | | ! / +---------+ | 620 | | | | | ! / |INSTALLER| | 621 | | | | | !/ +---------+ | 622 | | | | |+----------+ / | 623 |+----------+ | ||INTERNET | (/) | 624 || OWNER | | || FACING | Registration | 625 || GATEWAY |<----(-)-----|MANAGEMENT| Interface | 626 |+----------+ Owner | || SYSTEM | (/) | 627 | Interface| || |<-----/ | 628 | | |+----------+ | 629 | | | | 630 +----------------------+ +----------------------------------+ 632 Walled-garden architecture 634 6. Security Considerations 636 6.1. Overview 638 The aSSURE framework is intended to be usable across the entire 639 range of smart devices - from the largest servers through to more 640 constrained devices (as defined in RFC-7228). This is a very 641 challenging goal and means that some security approaches in common 642 use today are not universally suitable. 644 Examples of approaches that are not universally suitable include: 646 o Public Key Cryptography, e.g. RSA, DSA, EC 647 o This is computationally intensive and may take too long to 648 be acceptable on devices with minimal processing ability. 649 o This is computationally intensive and the necessary 650 additional processing load may have an unacceptable impact 651 on battery life. 652 o This requires reasonably large code size to implement in 653 software and this may not be available on the more 654 constrained devices. 655 o X.509 certificates 656 o These use time stamps and small devices may not have a real 657 time clock. 658 o These assume public key cryptography (RSA, DSA or EC) and 659 constrained devices may not be able to support this as 660 explained above. 661 o These have a fixed lifetime, thus requiring them to be 662 reissued before they expire. 663 o These require a certificate authority to issue (and 664 reissue) them. 665 o Due to their complexity, these have been the target of 666 various attacks in the past, so removing them reduces the 667 attack surface. 668 o Complex text-based data representations such as ASN.1, HTML, 669 XML, YAML or JSON 670 o These are difficult to parse, requiring larger code 671 libraries and more processing power than simpler formats 672 such as CBOR. 673 o Due to their complexity, these have been the target of 674 various attacks in the past, so removing them reduces the 675 attack surface. 676 o Complex protocols such as SOAP, HTML, etc. 677 o Again, these are more difficult to parse, requiring larger 678 code libraries and more processing power than simpler 679 protocols such as CoAP. 680 o Full standards implementation 681 o Lots of industry standards are large and have a lot of 682 different options, most of which are unnecessary for a new 683 implementation with no legacy support requirements. 684 o For example, TLS supports over 200 different cipher suites 685 and this list continues to grow. 687 o Due to their complexity, these have been the target of 688 various attacks in the past, so reducing the scope of the 689 implementation also reduces the attack surface. 691 Support for shared secrets 693 Very constrained devices that cannot support public key 694 cryptography have to fall back on "shared secrets" (also known as 695 "pre-shared keys") to identify themselves. Typical approaches 696 using shared secrets require the secret to be disclosed to both 697 parties to set up the secure connection. Once a secret has been 698 disclosed, it can never be proved to have been forgotten. This 699 makes transfer of device ownership problematic, as the previous 700 owner of the device may still know the shared secret even after 701 the device has been transferred to a new owner. In this scenario, 702 the previous owner would be able to decrypt all traffic between 703 the device and its new owner, making the device untrustworthy to 704 the new owner. 706 aSSURE offers a new approach using shared secrets that allows the 707 original secret to be concealed from the peer involved in the 708 connection. 710 In the aSSURE scenario, a shared secret can be distributed to a 711 device (or multiple devices) with one or two derivation functions. 712 These derivation functions allow a device with the correct 713 reference key to derive the shared secret. Different derivation 714 functions exist to derive the shared secret from an Elliptic Curve 715 key, an RSA key or another shared secret. 717 This ability to derive shared secrets is used to secure the 718 ownership lifecycle for devices that do not support public key 719 cryptography. With this approach, the device owner is provided 720 with the parameters for the hashing function and the derived 721 shared secret but not the original shared secret programmed into 722 the device during manufacture. When the owner wishes to 723 communicate with the device, the owner provides the device with 724 the derived secret parameters, thus allowing the device to derive 725 the new secret from the original secret. The owner is provided 726 with a second derivation function that uses the owner key, so they 727 can also derive the same secret and hence establish a secure 728 communication link to the device. When the device changes owner, 729 the new owner is given a different derived secret, not the 730 original secret. The new owner can communicate with the device 731 using the new parameters and the knowledge of the new derived 732 secret. The previous owner, however, does not have the new owner's 733 key nor the device key, so cannot derive the new shared secret and 734 so is unable to decrypt the communications with the new owner. 736 The only entities that know the original device secret are the 737 device itself and the Identity server within the Trusted Authority 738 (this is described in more detail later). 740 Shared secrets are described more in 7.2. and 8.4. below. 742 6.2. Guidelines for manufacturers 744 6.2.1. Device UUID 746 All device UUIDs should be truly randomly generated. This means 747 that they are completely unpredictable and knowledge of the UUID 748 does not disclose any information about what the device is, who 749 manufactured it or when. 751 6.2.2. Device Asymmetric Key 753 If a device uses an RSA or EC asymmetric key, this should be 754 securely generated within the device and the private key must 755 never be disclosed outside of the device. The device should have 756 access to a suitable entropy source to ensure that the key is 757 truly randomly generated. 759 6.2.3. Device Shared Secret 761 If a device uses a shared secret, this should be truly randomly 762 generated and at least 128 bits in size. It may be generated 763 inside the device or on the local manufacturing station but, if 764 generated outside the device, must never be stored in an 765 unencrypted form and must be wiped from RAM as soon as it is no 766 longer needed. The device secret can only ever be stored in non 767 volatile storage AFTER it has been formed into the device identity 768 structure and encrypted as described in 9.2.1. below. 770 6.2.4. Case ID 772 The aSSURE solution needs a method for an owner to prove that a 773 device is in their possession. This is done through knowledge of a 774 "case ID", an identification string that is printed on the outside 775 of the case. This number is NOT known to the device - it is only 776 known to the manufacturer and the Trusted Authority's Identity 777 Server. The case ID should be a randomly generated number that is 778 at least 128 bits. 780 6.2.5. QR Code 782 The device ID and case ID should be printed in a QR Code on the 783 side of the device. The data should be encoded in CBOR as follows: 785 ARRAY { 786 INTEGER version // Set to 1 for aSSURE v1 787 BYTE STRING device_uuid 788 BYTE STRING case_id 789 } 790 If the device UUID and case UUID are both 128 bits then this will 791 encode in 36 bytes. This can be encoded in a type 3 QR code (27 x 792 27 pixels) with "M" level of error correction, a type 4 QR code 793 (33 x 33 pixels) with a "Q" level of error or a type 5 QR code (37 794 x 37 pixels) with "H" level of error correction. 796 The manufacturer may choose any of these QR formats, but the type 797 5 is recommended as it has a higher level of error correction and 798 is therefore less susceptible to damage. 800 7. Data Structures 802 7.1. Overview 804 Where possible, common data structures are used across the system. 805 This simplifies the development and allows better code reuse. 807 7.2. Key Definition 809 A key is defined using one of the following CBOR formats depending 810 on its type. All keys are identified by their ID, which is a 128 811 bit randomly assigned UUID. 813 Keys have a format which may be Elliptic Curve, RSA or derived 814 secret. Elliptic Curve and RSA keys must include the public key 815 part and may optionally also include the associated private key. 817 If the key is an Elliptic Curve key, the definition is: 819 ARRAY { 820 INTEGER content // "Key Content Type", see 7.5. below 821 INTEGER format // "EC key", see 7.6. below 822 BYTE STRING key_id // UUID 823 BYTE STRING public_key // ASN.1 DER encoded string 824 BYTE STRING private_key // ASN.1 DER encoded string 825 } 827 The private_key BYTE STRING must be zero length if only a public 828 key is provided. 830 Note that the private key definition is not encrypted so if the 831 private key is provided, the definition must be transferred over 832 an encrypted channel and stored in a protected store. 834 If the key is an RSA key, the definition is: 836 ARRAY { 837 INTEGER content // "Key Content Type", see 7.5. below 838 INTEGER format // "RSA key", see 7.6. below 839 BYTE STRING key_id // UUID 840 BYTE STRING public_key // ASN.1 DER encoded string 841 BYTE STRING private_key // ASN.1 DER encoded string 843 } 844 The private_key BYTE STRING must be zero length if only a public 845 key is provided. 847 Note that the private key definition is not encrypted so if the 848 private key is provided, the definition must be transferred over 849 an encrypted channel and stored in a protected store. 851 If the key is a derived secret, the definition is: 853 ARRAY { 854 INTEGER content // "Key Content Type", see 7.5. below 855 INTEGER format // "Derived shared secret", see 7.6. 856 below 857 // below 858 BYTE STRING key_id // UUID 859 ARRAY { 860 // Derivation definition 861 BYTE STRING reference_A_key // UUID 862 BYTE STRING salt 863 INTEGER iterations_or_cipher 864 BYTE_STRING encrypted_secret 865 } 866 // Additional derivation definitions may be present in 867 // the same format as above 868 } 870 The derived secret has one or more derivation definitions. All 871 derivations can be disclosed publicly and all derivations must 872 produce the same secret. A device may use any of the derivations 873 for which it already knows the reference key. 875 If the reference key is a shared secret then the PBKDF2 algorithm 876 is used with SHA2 as the digest function, the reference key shared 877 secret used as the passphrase, the "iterations_or_cipher" used as 878 the iteration count, salt and a length value determined by the 879 length of the "encrypted_secret". After the PBKDF2 is completed, 880 the result is XOR'd against the "encrypted_secret". This allows 881 secure generation of any byte sequence. 883 If the reference key is an elliptic curve key, then the "salt" and 884 "iterations_or_cipher" fields are ignored (and should be zero 885 length and value zero respectively). The "encrypted_secret" 886 contains the shared secret protected by the Cryptographic Message 887 Syntax with "enveloped-data" as the ContentInfo (see RFC 5652 and 888 RFC 5753) using the "Standard" variation of Ephemeral Static ECDH 889 (see RFC 5753 section 3.1). The default choices for encryption 890 cipher and hash function should be AES-128 and SHA-256 891 respectively. 893 If the reference key is an RSA key, then the "salt" and 894 "iterations_or_cipher" fields are ignored (and should be zero 895 length and value zero respectively). The "encrypted_secret" 896 contains the shared secret protected by the Cryptographic Message 897 Syntax with "enveloped-data" as the ContentInfo (see RFC 5652) 898 using RSAES-OAEP (see RFC 8017 section 7.1). The default choices 899 for encryption cipher and hash function should be AES-128 and SHA 900 256 respectively. The SHA-1 hash should not be used. 902 7.3. Signature Definition 904 Rather than use X.509 signatures, which require public key 905 cryptography and ASN.1 encoding, aSSURE uses a simpler approach 906 using CBOR that can also be used with derived secrets as well as 907 public keys. 909 If the signature is generated by an Elliptic Curve private key, 910 the signature structure is: 912 ARRAY { 913 INTEGER content // "Signature Content Type", see 914 // 7.5. below 915 INTEGER format // Signature format, see 7.9. below 916 INTEGER created_at 917 INTEGER valid_until 918 BYTE STRING key_id 919 BYTE STRING r 920 BYTE STRING s 921 } 922 Here, "r" and "s" are the signature values as defined in the 923 Elliptic Curve Digital Signature Algorithm (ECDSA). 925 If the signature is generated by an RSA private key, the signature 926 structure is: 928 ARRAY { 929 INTEGER content // "Signature Content Type", see 930 // 7.5. below 931 INTEGER format // Signature format, see 7.9. below 932 INTEGER created_at 933 INTEGER valid_until 934 BYTE STRING key_id 935 BYTE STRING s 936 } 937 Here, "s" are the signature values as defined in the RSA Digital 938 Signature Algorithm (PKCS #1 v1.5). 940 If the signature is generated by a derived secret, the signature 941 structure is: 943 ARRAY { 944 INTEGER content // "Signature Content Type", see 945 // 7.5. below 947 INTEGER format // Signature format, see 7.9. below 948 INTEGER created_at 949 INTEGER valid_until 950 BYTE STRING key_id 951 BYTE STRING hmac 952 } 954 In all cases, the signature covers the original data structure and 955 the signature structure with the "r", "s" and/or "hmac" fields 956 being treated as zero length when performing the sign or 957 validation actions (i.e. the BYTE STRING definition is considered 958 to be the value 0b010_00000). 960 Two timestamps are part of each signature: 962 o The timestamp of when the signature was created ("created_at") 963 o The timestamp after which the signature invalid ("valid_until") 964 o 965 Each signing authority is free to choose its own validity duration 966 for the signatures that it issues. The authority can therefore 967 balance the rate of re-issue of signatures against the time that a 968 signature or a compromised key would remain valid. These fields 969 can be set to zero to indicate a signature that is always valid 970 and never expires. These fields may also be zero if the signature 971 authority knows that the signature is being issued to a device 972 with no real-time clock capability. If a device has no knowledge 973 of the true time, these fields should be ignored when performing 974 signature validation. 976 7.4. Authenticated Key Definition 978 Rather than use X.509 certificates which require public key 979 cryptography, ASN.1 encoding and knowledge of real time, aSSURE 980 uses a simpler yet more flexible structure to authenticate a 981 public key or a key derived from a shared secret. 983 An authenticated key definition combines a header, key definition 984 as in 7.2. above, optional metadata and signature as in 7.3. 985 above. 987 ARRAY { 988 INTEGER content // "Identity Content Type", see 7.5. below 989 INTEGER class // Identity class, see 7.7. below 990 ARRAY { 991 // Key definition, see 7.2. above 992 INTEGER content // "Key Content Type", see 7.5. below 993 } 994 MAP { 995 // Metadata (key + value pairs), see 7.10. below 996 } 997 ARRAY { 998 // Signature definition, see 7.3. above 999 INTEGER content // "Signature Content Type", see 1000 // 7.5. below 1001 } 1002 } 1004 The device should validate an "authenticated key" as follows: 1006 1. Check that the key used to generate its signature is already 1007 present in the device 1008 2. Check that current time is within the timestamp range for the 1009 signature 1010 3. For each key in the hierarchy of keys required to validate this 1011 signature, check that current time is within the timestamp range 1012 for that key's signature 1013 4. Check that the class of the key used to generate the signature 1014 is allowed to sign the class of the new authenticated key. The 1015 rules for this are in 7.7. below. 1016 5. Check that the signature matches the authenticated key data 1018 If all the above checks pass, the authenticated key can be 1019 accepted. 1021 7.5. Content Type IDs 1023 +-------+------------------------------+ 1024 | Value | Meaning | 1025 +-------+------------------------------+ 1026 | 0 | Identity Content Type | 1027 | 1 | Key Content Type | 1028 | 2 | Configuration Content Type | 1029 | 3 | Encrypted Key Content Type | 1030 | 4 | Signature Content Type | 1031 | 5 | Owner Content Type | 1032 +-------+------------------------------+ 1034 +-------+------------------------------+ 1035 | Value | Meaning | 1036 +-------+------------------------------+ 1037 | 0 | Identity Content Type | 1038 +--------------------------------------+ 1039 | 1 | Key Content Type | 1040 +--------------------------------------+ 1041 | 2 | Configuration Content Type | 1042 +--------------------------------------+ 1043 | 3 | Encrypted Key Content Type | 1044 +--------------------------------------+ 1045 | 4 | Signature Content Type | 1046 +--------------------------------------+ 1047 | 5 | Owner Content Type | 1048 +-------+------------------------------+ 1050 7.6. Key Format IDs 1052 +-------+-------------------------------------+ 1053 | Value | Meaning | 1054 +-------+-------------------------------------+ 1055 | 0 | Elliptic Curve Key (ASN1.DER encoded| 1056 | | following industry standards) | 1057 | 1 | RSA Key (ASN1.DER encoded | 1058 | | following industry standards) | 1059 | 2 | Configuration Content Type | 1060 +-------+-------------------------------------+ 1062 7.7. Identity Class IDs 1064 +---+------------+---------------------------------------+ 1065 | | Signing Permissions| 1066 + +----+----+----+----+----+----+ | + 1067 | | Identity Classes | | | 1068 + +----+----+----+----+----+----+ | + 1069 | | M | | | | | | | | 1070 | | a | | | | | | | | 1071 | | n | |M S | | | | | | 1072 | | u |T A |a y |B S | | | |B D | 1073 | | f |r u |n s |o e | | | |o a | 1074 | | a |u t |a t |o r | | C | |o t | 1075 |---+------------| c |s h |g e |t v | D | h | C |t a | 1076 | V | | t |t o |e m |s i | e | a | o |s | 1077 | a | | u |e r |m |t c | v | n | n |t | 1078 | l | | r |d i |e |r e | i | n | f |r | 1079 + u + | e | t |n |a | c | e | i |a | 1080 | e |Name | r | y |t |p | e l g p | 1081 +---+------------+----+----+----+----+----+----+----+----+ 1082 | 0 |Manufacturer| Y | Y | N | N | Y | N | N | N | 1083 | | | | | | | | | | | 1084 +---+------------+----+----+----+----+----+----+----+----+ 1085 | 1 |Trusted | N | Y | Y | Y | Y | N | N | N | 1086 | |Authority | | | | | | | | | 1087 +---+------------+----+----+----+----+----+----+----+----+ 1088 | 2 |Management | N | N | Y | Y | Y | Y | Y | Y | 1089 | |System | | | | | | | | | 1090 +---+------------+----+----+----+----+----+----+----+----+ 1091 | 3 |Bootstrap | N | N | N | N | N | N | N | N | 1092 | |Service | | | | | | | | | 1093 +---+------------+----+----+----+----+----+----+----+----+ 1094 | 4 |Device | N | N | N | N | N | Y | N | N | 1095 | | | | | | | | | | | 1096 +---+------------+----+----+----+----+----+----+----+----+ 1097 | 5 |Channel | N | N | N | N | N | N | N | N | 1098 | | | | | | | | | | | 1099 +--------------------------------------------------------+ 1101 The Manufacturer is the manufacturer of the device. A manufacturer 1102 may install Device identification keys at the factory to allow the 1103 device to authenticate itself. If the device is public key 1104 >> capable, the manufacturer MUST install the identity for the 1105 Trusted Authority. 1107 The Trusted Authority refers to all systems running within the 1108 Trusted Authority. A Trusted Authority is only allowed to 1109 authenticate other systems running within the Trusted Authority, 1110 the Bootstrap Service, the owner's Management Systems or the 1111 Device. It is not allowed to authenticate Bootstrap data or 1112 device communications Channels. 1114 The Management System is not allowed to authenticate Manufacturers 1115 or Trusted Authorities but it can authenticate all other 1116 identities used by the device. 1118 The Bootstrap Service is not allowed to authenticate anything else 1119 - it is only able to deliver bootstrap data to the device. 1121 The Device is only allowed to authenticate channels. 1123 The Channel is not allowed to authenticate anything else - it is 1124 only allowed to transport data. 1126 7.8. Cipher Suite IDs 1128 +-------+-------------------------------------------------+ 1129 | Value | Meaning | 1130 +-------+-------------------------------------------------+ 1131 | 0 | "AES-128 CBC" (OID 2.16.840.1.101.3.4.2)" | 1132 | 1 | "AES-192 CBC" (OID 2.16.840.1.101.3.4.22)" | 1133 | 2 | "AES-256 CBC" (OID 2.16.840.1.101.3.4.42)" | 1134 | 3 | "AES-128 CCM" (OID 2.16.840.1.101.3.4.7)" | 1135 | 4 | "AES-192 CCM" (OID 2.16.840.1.101.3.4.27)" | 1136 | 5 | "AES-256 CCM" (OID 2.16.840.1.101.3.4.47)" | 1137 | 6 | "AES-128 GCM" (OID 2.16.840.1.101.3.4.6)" | 1138 | 7 | "AES-192 GCM" (OID 2.16.840.1.101.3.4.26)" | 1139 | 8 | "AES-256 GCM" (OID 2.16.840.1.101.3.4.46)" | 1140 +-------+-------------------------------------------------+ 1142 7.9. Signature Format IDs 1144 +-------+-------------------------------------------------+ 1145 | Value | Meaning | 1146 +-------+-------------------------------------------------+ 1147 | 0 | ecdsa-with-SHA256 (OID 1.2.840.10045.4.3.2) | 1148 +---------------------------------------------------------+ 1149 | 1 | ecdsa-with-SHA384 (OID 1.2.840.10045.4.3.3) | 1150 +---------------------------------------------------------+ 1151 | 2 | ecdsa-with-SHA512 (OID 1.2.840.10045.4.3.4) | 1152 +---------------------------------------------------------+ 1153 | 3-7 | Reserved..future expansion of ECDSA signatures | 1154 +---------------------------------------------------------+ 1155 | 8 | sha256-with-rsa-signature | 1156 | | (OID 1.2.840.113549.1.1.11) | 1157 +---------------------------------------------------------+ 1158 | 9 | sha384-with-rsa-signature | 1159 | | (OID 1.2.840.113549.1.1.12) | 1160 +---------------------------------------------------------- 1161 | 10 | sha512-with-rsa-signature | 1162 | | (OID 1.2.840.113549.1.1.13) | 1163 +---------------------------------------------------------+ 1164 | 11-15 | Reserved..future expansion of RSA signatures | 1165 +---------------------------------------------------------+ 1166 | 16 | hmacWithSHA256 (OID 1.2.840.113549.2.9) | 1167 +---------------------------------------------------------+ 1168 | 17 | hmacWithSHA384 (OID 1.2.840.113549.2.10) | 1169 +---------------------------------------------------------+ 1170 | 18 | hmacWithSHA512 (OID 1.2.840.113549.2.11) | 1171 +---------------------------------------------------------+ 1173 7.10. Authenticated Key Metadata 1175 +----------+------------------+---------------------------+ 1176 | Key | Value | Usage | 1177 +----------+------------------+---------------------------+ 1178 |INTEGER(0)| BYTE STRING | Indicates the device | 1179 | | () | owning the key | 1180 +----------+------------------+---------------------------+ 1182 7.11. aSSURE timestamps 1184 7.11.1. Simple timestamps 1186 aSSURE uses a variant of the Unix time format for all its 1187 timestamps. An aSSURE simple timestamp is an integer that tracks 1188 the number of seconds since midnight on Friday January 1st 2010 1189 GMT rather than midnight on January 1st 1970 GMT. This allows a 1190 signed 32-bit number to provide a valid timestamp until 2078 1191 rather than 2038. 1193 aSSURE_timestamp_secs = unix_timestamp_secs - 1262304000 1195 A simple timestamp is defined in CBOR as: 1197 INTEGER timestamp_secs 1199 7.11.2. Precision timestamps 1201 If more precision is required, a fractional part may also be 1202 provided. This holds the fractional part of the second as a 32-bit 1203 value (so the precision is ~233ps). 1205 A precision timestamp is defined in CBOR as: 1207 ARRAY { 1208 INTEGER timestamp_secs 1209 INTEGER timestamp_frac 1210 } 1212 8. DTLS with aSSURE key identities 1214 8.1. Overview 1216 aSSURE uses DTLS for all secure connections due to its low 1217 overhead both in code and operation. DTLS supports both 1218 certificates and pre-shared keys, but does not cover how the 1219 certificate authorities or pre-shared keys are to be securely 1220 distributed. 1222 This section shows how we extend the basic DTLS standard with 1223 additional RFC to provide the functionality required for aSSURE. 1224 It also shows how to setup DTLS connections in an aSSURE 1225 environment. 1227 8.2. Extension to (D)TLS 1229 aSSURE needs to be able to provide the client identity to the 1230 server during the DTLS handshake. This would normally be done 1231 using X.509 certificates, but aSSURE avoids the complexity and 1232 overhead of X.509 certificates so an alternative approach is 1233 required. 1234 aSSURE provides the client identity to the server using a new TLS 1235 extension, "Peer Name Indication" that is lightweight and similar 1236 to the "Server Name Indication" extension. 1238 8.2.1. Peer Name Indication 1240 TLS does not provide a mechanism for a client to tell a server the 1241 name of the client that is connecting before the ServerHello is 1242 returned. It may be desirable for clients to provide this 1243 information to facilitate secure connections to servers where the 1244 ServerHello should vary according to the client identity. 1246 In order to provide any of the names, clients MAY include an 1247 extension of type "peer_name" in the (extended) client hello. The 1248 "extension_data" field of this extension SHALL contain 1249 "PeerNameList" where: 1251 struct { 1252 NameType name_type; 1253 select (name_type) { 1254 case uuid: UUID; 1255 } name; 1256 } PeerName; 1257 enum { 1258 uuid(0), (255) 1259 } NameType; 1261 opaque UUID[16]; 1263 struct { 1264 PeerName peer_name_list<1..2^16-1> 1265 } PeerNameList; 1267 This allows the client to provide its UUID in a compact format to 1268 the server. It also allows other client formats to be used in the 1269 future. 1271 8.3. Proof of identity by public key clients 1273 A typical DTLS handshake uses X.509 certificates to allow both 1274 mutual authentication of identity and key exchange to set up the 1275 secure connection. aSSURE does not use X.509 certificates for the 1276 reasons explained in section 6.1. above so an alternative 1277 approach is required to allow mutual authentication and key 1278 exchange. 1280 aSSURE uses the device API calls to allow the management system to 1281 securely provide identity credentials for other peers to the 1282 device. An aSSURE device WILL NOT communicate with any peer that 1283 has not had the peer identity credentials provided to it by an 1284 authorised management system over a secured connection. 1286 aSSURE uses the Peer Name Indication extension (see 8.2.1. above) 1287 to allow a device to indicate its ID to the peer during the 1288 initial connection request. This allows the peer to check that the 1289 device is in its list of trusted devices. If the device is not in 1290 the list, the peer refuses the connection. 1292 Similarly, the server uses the Peer Name Indication extension to 1293 provide its ID to the client in the initial connection response. 1294 This allows the client to quickly check its database to check that 1295 the server is in its list of trusted peers. If the server is not 1296 in the list, the client aborts the connection attempt. 1298 aSSURE then uses the Raw Public Key Extension defined in RFC-7250 1299 to allow just the public keys to be exchanged between device and 1300 peer. Both the device and the peer cross-check the public keys 1301 provided in the DTLS handshake against the expected public keys 1302 their list of trusted devices. If either device or peer detect a 1303 public key mismatch, they abort the handshake. 1305 If all checks complete without error, the handshake is allowed to 1306 continue normally and the secure connection is established. 1308 8.4. Proof of identity by shared secret clients 1310 When establishing a secure connection, if either device cannot 1311 support public keys, they must use the derived shared secret 1312 method of authentication. Derived shared secrets are a weaker 1313 form of security than public keys, but if used carefully, can 1314 still provide a reasonable level of security. 1316 DTLS connections protected by derived shared secrets differ from 1317 public key cryptography in that both parties must know the same 1318 secret to allow the DTLS handshake to complete. Hence, a derived 1319 shared secret can be used to prove a link relationship but not an 1320 endpoint identity. 1322 The management system will have been provided with a unique 1323 derived shared secret for each device - this is provided to the 1324 device in the bootstrap configuration so that the device can trust 1325 the link relationship from itself to the management system. 1327 The management system will then generate a unique derived shared 1328 secret for each link that the device needs to establish using its 1329 knowledge of the available keys on the devices at each end of the 1330 link. The management system will then push that derived shared 1331 secret to both devices indicating the peer device ID to which the 1332 derived shared secret relates and instruct one of them to act as 1333 the client to establish the channel. 1335 The client will then attempt to connect to the peer using DTLS. 1337 aSSURE uses the Peer Name Indication extension (see 8.2.1. above) 1338 to allow a device to indicate its ID to the peer during the 1339 initial connection request. This allows the peer to check that the 1340 device is in its list of trusted devices. If the device is not in 1341 the list, the peer refuses the connection. 1343 Similarly, the server uses the Peer Name Indication extension to 1344 provide its ID to the client in the initial connection response. 1345 This allows the client to quickly check its database to check that 1346 the server is in its list of trusted peers. If the server is not 1347 in the list, the client aborts the connection attempt. 1349 aSSURE then uses the Pre-shared Key Identity Hint Extension 1350 defined in RFC-4279 to allow the server to provide the necessary 1351 key information to the client. The key information is encoded in 1352 Base64 because RFC-4279 recommends that the key information only 1353 contains printable characters. The key information will be one of: 1355 o The UUID of a key known to both client and server. The UUID is 1356 provided as a CBOR BYTE STRING of 16 bytes. 1357 o A key definition as in 7.2. above. 1359 The client can determine which is provided by inspecting the data. 1361 A simple UUID is a CBOR BYTE STRING whilst a key definition is a 1362 CBOR ARRAY. 1364 The client checks that the indicated (or reference) key is 1365 available and appropriate for this connection, derives the secret 1366 as appropriate and uses this as the pre-shared key for the DTLS 1367 session. The server also derives the secret from the key and uses 1368 this as the pre-shared key for the DTLS session. 1370 The DTLS handshake then continues as normal and the session is 1371 established. 1373 9. Trusted Authority APIs 1375 9.1. Overview 1377 The Trusted Authority provides three distinct APIs as follows: 1378 o Manufacturer API 1379 o Owner API 1380 o Bootstrap API 1382 The Manufacturer API is used by the manufacturer to upload 1383 manufacturing details about each device when it is created. Only 1384 the minimum amount of information about the device is uploaded and 1385 this information is stored in One-Time Programmable (OTP) memory 1386 on the device, so can never be changed. For this reason, the 1387 Manufacturing API has no requirement to allow device information 1388 to be updated after manufacture, such as during Return Merchandise 1389 Authorisation (RMA), because this information can never be 1390 changed. 1392 The Owner API is used by the device owner to assert ownership of 1393 the device, update the device bootstrap configuration and change 1394 device ownership. 1396 The Bootstrap API is used by the devices themselves to download 1397 their bootstrap configuration so that they can connect to their 1398 management systems and enter service. 1400 9.2. Manufacturer API 1402 The Manufacturer API is used by the manufacturer to upload data 1403 about the device when it is manufactured. The manufacturer API is 1404 a RESTful interface using JSON over HTTPS with client 1405 authentication. Generation of the client key and issuing of the 1406 client certificate is out of scope for this document (this 1407 information could easily be exchanged via email). Similarly, 1408 delivery of the Trusted Authority "Identity Service" certificate 1409 to the manufacturer and disclosure of the Manufacturer API URL is 1410 also out of scope (again, this information could easily be 1411 provided via email). 1413 9.2.1. PUT /v1/devices/ 1415 After a device is manufactured, the manufacturer builds the device 1416 data into a JSON data structure as follows: 1418 { 1419 "id": "", 1420 "bootstrap_server": , 1421 "case_string": "", 1422 "shared_secret": "" 1423 "public_key": "" 1424 "parameter_set": "" 1425 "capabilities": { // Device bootstrap capabilities 1426 "ec_capable": , 1427 "rsa_capable": , 1428 "sha384_capable": , 1429 "sha512_capable": , 1430 "aes256_capable": , 1431 // Additional capabilities may be added in the future 1432 } 1433 } 1435 If the device uses an RSA or EC key as its device key, the 1436 "shared_secret" will not present. If the device is only shared 1437 secret capable then the "public_key" will not be present. The JSON 1438 data will NEVER have both "shared_secret" and "public_key" fields. 1440 All devices must support SHA-256, AES-128 and shared secrets. If 1441 the device can support other keys, hashing algorithms or ciphers 1442 during bootstrap, these should be indicated here. 1444 The manufacturer's production line will have encrypted the device 1445 data immediately after the device has been tested. The device data 1446 is encrypted using ECIES and the Identity Service public key 1447 (which must be a strong Elliptic Curve key). The ECIES 1448 configuration uses SHA512 and AES-256. The encrypted data is then 1449 provided as a binary payload in the request. 1451 No payload is returned. The response code will be one of: 1452 +--------------+------------------------------------------+ 1453 | Response | Description | 1454 +--------------+------------------------------------------+ 1455 |201 Created | The new device has been created | 1456 +--------------+------------------------------------------+ 1457 |403 Forbidden | The manufacturer cannot update the | 1458 | | device because it already exists | 1459 +--------------+------------------------------------------+ 1460 | 503 Service | The device cannot be created at | 1461 | Unavailable | this time | 1462 +--------------+------------------------------------------+ 1463 Only a single device is uploaded in each PUT request, but the 1464 client may re-use the HTTPS session to send additional requests. 1466 9.2.2. POST /v1/parametersets 1468 This allows a manufacturer to upload a parameter set definition. 1469 The format of the parameter set definition is TBD. The parameter 1470 set is defined in CBOR and provided as the request payload. The 1471 parameter set is provided in the configuration data to the 1472 Management System to guide the bootstrap data definition as 1473 described in 15.2. below. 1475 The payload will contain the assigned UUID as a simple ASCII 1476 string. The response code will be one of: 1477 +--------------+------------------------------------------+ 1478 | Response | Description | 1479 +--------------+------------------------------------------+ 1480 |201 Created | The new parameter set has been created | 1481 +--------------+------------------------------------------+ 1482 | 503 Service | The parameter set cannot be created at | 1483 | Unavailable | this time | 1484 +--------------+------------------------------------------+ 1486 9.2.3. PUT /v1/parametersets/ 1488 This allows a manufacturer to replace a parameter set definition. 1489 The format of the parameter set definition is TBD. The parameter 1490 set is defined in CBOR and provided as the request payload. The 1491 parameter set is provided in the configuration data to the 1492 Management System to guide the bootstrap data definition as 1493 described in 15.2. below. 1495 No payload is returned. The response code will be one of: 1496 +--------------+------------------------------------------+ 1497 | Response | Description | 1498 +--------------+------------------------------------------+ 1499 |201 Created | The new parameter set has been created | 1500 +--------------+------------------------------------------+ 1501 |403 Forbidden | The manufacturer cannot update the | 1502 | | parameter set because it does not exist | 1503 | | or belongs to a different manufacturer | 1504 +--------------+------------------------------------------+ 1505 | 503 Service | The parameter set cannot be created at | 1506 | Unavailable | this time | 1507 +--------------+------------------------------------------+ 1509 Only a single parameter set is uploaded in each POST request, but 1510 the client may re-use the HTTPS session to send additional 1511 requests. 1513 9.2.4. GET /v1/parametersets/ 1515 This allows a manufacturer to download a parameter set definition. 1517 The format of the parameter set definition is TBD and is exactly 1518 the data as provided in 9.2.2. above. 1520 The returned payload is the parameter set data. The response code 1521 will be one of: 1522 +--------------+------------------------------------------+ 1523 | Response | Description | 1524 +--------------+------------------------------------------+ 1525 |200 OK | The parameter set has been returned | 1526 +--------------+------------------------------------------+ 1527 |403 Forbidden | The parameter set does not exist or was | 1528 | | provided by a different manufacturer | 1529 +--------------+------------------------------------------+ 1531 9.3. Owner API 1533 The Owner API is used to take ownership of a device, set the 1534 bootstrap data for the device and transfer ownership of the 1535 device. 1537 As with the Manufacturer API, the Owner API is a RESTful interface 1538 using JSON over HTTPS with client authentication. 1540 9.3.1. POST /v1/managementsystems 1542 This is used by management systems to register with the Owner API. 1543 The connection does not require client authentication. 1545 Before making this request, the management system should generate 1546 a new Elliptic Curve key and associated X.509 certificate signing 1547 request (CSR). The management system provides the CSR in DER 1548 format as the request payload. The Owner API will immediately 1549 issue a certificate for this CSR and return it as the response 1550 payload in DER format. 1552 All management systems must support both Elliptic Curve and RSA 1553 public keys, SHA-256, SHA-512, AES-128 and AES-256 so that they 1554 can correctly interoperate with all devices irrespective of the 1555 device abilities (or lack of abilities). 1557 The response code will be one of: 1558 +--------------+------------------------------------------+ 1559 | Response | Description | 1560 +--------------+------------------------------------------+ 1561 |201 Created | The new management system ID | 1562 | | has been created | 1563 +--------------+------------------------------------------+ 1564 | 503 Service | The management system ID cannot be | 1565 | Unavailable | created at this time | 1566 +--------------+------------------------------------------+ 1567 Note: Some Trusted Authorities may require a username and password 1568 to be provided to authenticate this request to prevent attackers 1569 trying to overload the system with requests. Alternative 1570 validation approaches are also possible. Such extensions are out 1571 of scope of this document. 1573 Note: The serial number of the issued certificate is used as the 1574 "manufacturer ID" in owner management API requests (9.3.4. below 1575 and 9.3.5. below). For security reasons, the manufacturer ID 1576 should not be predictable so ought to be a large random number (>= 1577 64 bits). 1579 9.3.2. PUT /v1/devices//owner?case_string= 1581 This is used by management systems to take ownership of a device. 1582 The connection must be authenticated with the issued client 1583 certificate. 1585 The case identification string from the QR code must be provided 1586 as the "case_string" parameter. No payload is provided. 1587 No payload is returned and the response code will be one of: 1588 +--------------+------------------------------------------+ 1589 | Response | Description | 1590 +--------------+------------------------------------------+ 1591 |204 Changed | Ownership has been assigned to this | 1592 | | management system | 1593 +--------------+------------------------------------------+ 1594 |403 Forbidden | The device is owned by a different | 1595 | | management system, the wrong case string | 1596 | | was provided or the device does not exist| 1597 +--------------+------------------------------------------+ 1599 9.3.3. PUT /v1/devices//owner?mgmtid= 1601 This is a variant of 9.3.2. above and used by management systems 1602 to transfer ownership of a device to a different management 1603 system. The connection must be authenticated with the issued 1604 client certificate. 1605 The serial number of the certificate issued to the new management 1606 system must be provided as the "mgmtid" parameter. No payload is 1607 provided. 1609 No payload is returned and the response code will be one of: 1610 +--------------+------------------------------------------+ 1611 | Response | Description | 1612 +--------------+------------------------------------------+ 1613 |204 Changed | Ownership has been assigned to the new | 1614 | | owner | 1615 +--------------+------------------------------------------+ 1616 |403 Forbidden | The device is owned by a different | 1617 | | management system, or the device | 1618 | | does not exist | 1619 +--------------+------------------------------------------+ 1621 9.3.4. PUT /v1/devices//owner?case_string= 1622 &mgmtid= 1624 This is a combination of 9.3.2. and 9.3.3. above. It is used by 1625 management systems to take ownership of a device and immediately 1626 assign it to a different management system. The connection must be 1627 authenticated with the issued client certificate. 1629 The case identification string must be provided as the 1630 "case_string" parameter and the serial number of the certificate 1631 issued to the new management system must be provided as the 1632 "mgmtid" parameter. No payload is provided. 1634 No payload is returned and the response code will be one of: 1635 +--------------+------------------------------------------+ 1636 | Response | Description | 1637 +--------------+------------------------------------------+ 1638 |204 Changed | Ownership has been assigned to the new | 1639 | | owner | 1640 +--------------+------------------------------------------+ 1641 |403 Forbidden | The device is owned by a different | 1642 | | management system, or the device | 1643 | | does not exist | 1644 +--------------+------------------------------------------+ 1646 9.3.5. PUT /v1/devices//owner?mgmtid=NULL 1648 This is a variant of 9.3.2. above and used by management systems 1649 to release ownership of a device. Once a device has been released 1650 from ownership, any management system may take ownership of the 1651 device if knows the device UUID and case string. The connection 1652 must be authenticated with the issued client certificate. 1654 No payload is provided or returned and the response code will be 1655 one of: 1656 +--------------+------------------------------------------+ 1657 | Response | Description | 1658 +--------------+------------------------------------------+ 1659 |204 Changed | Ownership has been released | 1660 +--------------+------------------------------------------+ 1661 |403 Forbidden | The device is owned by a different | 1662 | | management system, or the device | 1663 | | does not exist | 1664 +--------------+------------------------------------------+ 1666 9.3.6. GET /v1/devices//parameterset 1668 This is used by management systems to obtain the parameter set 1669 required for the device. The connection must be authenticated with 1670 the issued client certificate. 1672 No payload is provided. If the request is successful, the 1673 parameter set will be returned in the payload. The format of the 1674 parameter set data is TBD. 1676 Note that this returns the same data as 9.2.4. above but 1677 references the device not the parameter set UUID itself. 1679 The response code will be one of: 1680 +--------------+------------------------------------------+ 1681 | Response | Description | 1682 +--------------+------------------------------------------+ 1683 |200 OK | The device parameter set has | 1684 | | been returned | 1685 +--------------+------------------------------------------+ 1686 |403 Forbidden | The device is owned by a different | 1687 | | management system, or the device | 1688 | | does not exist | 1689 +--------------+------------------------------------------+ 1691 9.3.7. PUT /v1/devices//bootstrap 1693 This is used by management systems to set the bootstrap data for a 1694 device. The connection must be authenticated with the issued 1695 client certificate. 1697 The bootstrap data is provided as a binary payload. The format of 1698 the device bootstrap data is device dependent and detailed in the 1699 device parameter set returned in 9.3.6. above. No payload is 1700 returned. The response code will be one of: 1701 +--------------+------------------------------------------+ 1702 | Response | Description | 1703 +--------------+------------------------------------------+ 1704 |204 Changed | The device bootstrap data has been | 1705 | | accepted | 1706 +--------------+------------------------------------------+ 1707 |403 Forbidden | The device is owned by a different | 1708 | | management system, or the device | 1709 | | does not exist | 1710 +--------------+------------------------------------------+ 1712 9.3.8. GET /v1/devices//bootstrap 1714 This is used by management systems to return the bootstrap data 1715 for a device. The connection must be authenticated with the issued 1716 client certificate. 1718 No payload is provided. If successful, the bootstrap data is 1719 returned as a binary payload. The response code will be one of: 1720 +--------------+------------------------------------------+ 1721 | Response | Description | 1722 +--------------+------------------------------------------+ 1723 |200 OK | The device bootstrap data has | 1724 | | been returned | 1725 +--------------+------------------------------------------+ 1726 |403 Forbidden | The device is owned by a different | 1727 | | management system, or the device | 1728 | | does not exist | 1729 +--------------+------------------------------------------+ 1731 9.4. Bootstrap API 1733 The Bootstrap API is used by the device to download its bootstrap 1734 data. The Bootstrap API is a RESTful interface using CBOR and CoAP 1735 over DTLS with client authentication. 1737 9.4.1. GET /v1/devices//bootstrap 1739 This is used by the device to obtain its bootstrap data. The DTLS 1740 connection must be authenticated with the device key as described 1741 in section 8. above. The in the URI must belong to the 1742 device authenticated during the DTLS handshake. 1744 No payload is provided. If successful, the bootstrap data is 1745 returned as a binary payload. The response code will be one of: 1746 +--------------+------------------------------------------+ 1747 | Response | Description | 1748 +--------------+------------------------------------------+ 1749 |2.05 | The device bootstrap data has | 1750 | | been returned | 1751 +--------------+------------------------------------------+ 1752 |4.03 | The device is not allowed to access the | 1753 | | requested bootstrap data, or the device | 1754 | | does not exist | 1755 +--------------+------------------------------------------+ 1757 10. Device Management API 1759 The device API is used by the management system to control the 1760 aSSURE functionality in the device. Like the Bootstrap API, the 1761 Device API is RESTful using CBOR and CoAP over DTLS. The transport 1762 of the DTLS messages will vary depending on the device type and 1763 installation - examples of different physical and/or network 1764 layers are provided in section 11. below. 1766 All requests on the Device Management API must be made over 1767 authenticated DTLS connections, known as "channels". The 1768 definition of channels is in 4.2. above. 1770 The Management API is used to define what privileges are assigned 1771 to each channel. These privileges are: 1773 +--------------+------------------------------------------+ 1774 | Privilege | Description | 1775 +--------------+------------------------------------------+ 1776 | Key | The connection is allowed to create, | 1777 | Management | reconfigure and delete keys on the | 1778 | | device. | 1779 +--------------+------------------------------------------+ 1780 | Channel | The connection is allowed to create, | 1781 | Management | reconfigure and delete channel | 1782 | | definitions on the device. | 1783 +--------------+------------------------------------------+ 1784 | System | The connection is allowed to instruct | 1785 | Management | the device to perform system level | 1786 | | actions such as bootstrap or reboot. | 1787 +--------------+------------------------------------------+ 1789 10.1.1. PUT /v1/keys/ 1791 This request requires "Key Management" privileges on the 1792 requesting channel. 1794 This instructs the device to add the indicated key to its key 1795 store. The key is provided in the payload as a CBOR object as 1796 defined in 7.4. above. 1798 The response code will be one of: 1799 +----------+----------------------------------------------+ 1800 | Response | Description | 1801 +----------+----------------------------------------------+ 1802 | 2.01 | The key has been created | 1803 +----------+----------------------------------------------+ 1804 | 2.04 | The key already exists on the device | 1805 +----------+----------------------------------------------+ 1806 | 4.01 | The channel does not have privileges to | 1807 | | manage keys | 1808 +----------+----------------------------------------------+ 1809 | 4.13 | The device has no space to add more keys | 1810 +----------+----------------------------------------------+ 1812 10.1.2. POST /v1/keys/generate?type=&persistent= 1814 This request requires "Key Management" privileges on the 1815 requesting channel. 1817 This instructs the device to create a new key of the indicated 1818 type in its key store. 1820 +----------+----------------------------------------------+ 1821 | Type | Description | 1822 +----------+----------------------------------------------+ 1823 | 0 | RSA 2048 bits | 1824 +----------+----------------------------------------------+ 1825 | 1 | Elliptic Curve (NIST P-256) | 1826 +----------+----------------------------------------------+ 1827 | 2 | Elliptic Curve (NIST P-384) | 1828 +----------+----------------------------------------------+ 1829 | 3 | Elliptic Curve (NIST P-521) | 1830 +----------+----------------------------------------------+ 1832 If the persistent flag is not set, the key will only exist in RAM 1833 and will be lost when the device next reboots or loses power. 1835 If the creation is successful, the device will create an 1836 authenticate key as defined in 7.4. above. The device will add 1837 its own ID in the MAP field and create the signature using its 1838 device key. The authenticate key is then returned in the response 1839 payload. 1841 The response code will be one of: 1842 +----------+----------------------------------------------+ 1843 | Response | Description | 1844 +----------+----------------------------------------------+ 1845 | 2.01 | The key has been created | 1846 +----------+----------------------------------------------+ 1847 | 4.01 | The channel does not have privileges to | 1848 | | manage keys | 1849 +----------+----------------------------------------------+ 1850 | 4.13 | The device has no space to add more keys | 1851 +----------+----------------------------------------------+ 1852 | 5.01 | Unsupported key type | 1853 +----------+----------------------------------------------+ 1855 10.1.3. GET /v1/keys/ 1857 This request requires "Key Management" privileges on the 1858 requesting channel. 1860 This instructs the device to return the indicated key in its key 1861 store. The key is returned in the payload as a CBOR object as 1862 defined in 7.4. above. 1864 The response code will be one of: 1865 +----------+----------------------------------------------+ 1866 | Response | Description | 1867 +----------+----------------------------------------------+ 1868 | 2.05 | The key information has been returned | 1869 +----------+----------------------------------------------+ 1870 | 4.01 | The channel does not have privileges to | 1871 | | return keys | 1872 +----------+----------------------------------------------+ 1873 | 4.04 | The key does not exist | 1874 +----------+----------------------------------------------+ 1876 10.1.4. DELETE /v1/keys/ 1877 This request requires "Key Management" privileges on the 1878 requesting channel. 1880 This instructs the device to delete the indicated key from its key 1881 store. The key must not be in use by any channel nor must it be 1882 used as a reference key by any other keys. The device will not 1883 permit any key defined in the bootstrap data to be deleted. 1885 The response code will be one of: 1886 +----------+----------------------------------------------+ 1887 | Response | Description | 1888 +----------+----------------------------------------------+ 1889 | 2.02 | The key has been deleted or did not exist | 1890 +----------+----------------------------------------------+ 1891 | 4.01 | The channel does not have privileges to | 1892 | | manage keys | 1893 +----------+----------------------------------------------+ 1894 | 4.03 | The key is in use and cannot be deleted at | 1895 | | this time or is not allowed to be deleted | 1896 +----------+----------------------------------------------+ 1898 10.1.5. GET /v1/keys 1900 This request requires "Key Management" privileges on the 1901 requesting channel. 1903 This instructs the device to list the keys in its key store. The 1904 key list is returned as a CBOR array of authenticated keys as 1905 defined in 7.4. above. For security reasons, no private keys will 1906 be disclosed. Instead, if the device has the private data for the 1907 key, the string "PRESENT" will be returned as the "private_key" 1908 byte string. If the device does not have the private data for the 1909 key, the "private_key" byte string will be zero length. 1911 The response code will be one of: 1912 +----------+----------------------------------------------+ 1913 | Response | Description | 1914 +----------+----------------------------------------------+ 1915 | 2.05 | The key list has been returned | 1916 +----------+----------------------------------------------+ 1917 | 4.01 | The channel does not have privileges to | 1918 | | manage keys | 1919 +----------+----------------------------------------------+ 1921 10.1.6. PUT /v1/channels 1923 This request requires "Channel Management" privileges on the 1924 requesting channel. 1926 This instructs the device to create a new channel. The channel 1927 configuration will be provided in the request payload in CBOR 1928 format as below: 1930 ARRAY { 1931 BYTE STRING local_key_id 1932 BYTE STRING peer_key_id // Zero length if the same as 1933 // local_key_id 1934 ARRAY { 1935 BOOLEAN persistent_across_reboots 1936 BOOLEAN open_immediately 1937 BOOLEAN channel_management_privilege 1938 BOOLEAN system_management_privilege 1939 BOOLEAN key_management_privilege 1940 // Additional configuration flags may follow 1941 } 1942 ARRAY { 1943 INTEGER address_type 1944 // Address content, structure varies depending on 1945 // address_type 1946 } 1947 } 1948 The format of the address content depends on the target device 1949 network and physical layer. As support for additional network and 1950 physical layers are added, additional address types and associated 1951 address content format will be defined. The list of assigned 1952 address types is in 12.4. below. 1954 The assigned channel ID will be returned in the response payload 1955 as a CBOR integer. 1957 The response code will be one of: 1958 +----------+----------------------------------------------+ 1959 | Response | Description | 1960 +----------+----------------------------------------------+ 1961 | 2.01 | The channel has been created | 1962 +----------+----------------------------------------------+ 1963 | 4.01 | The channel does not have privileges to | 1964 | | manage channels | 1965 +----------+----------------------------------------------+ 1966 | 4.13 | The device has no space to add more channels | 1967 +----------+----------------------------------------------+ 1969 10.1.7. PUT /v1/channels/ 1971 As per 10.1.6. above, "PUT /v1/channels" but where the channel ID 1972 is explicitly provided. The request and response payload formats 1973 are unchanged. 1975 Additional response codes may be: 1977 +----------+----------------------------------------------+ 1978 | Response | Description | 1979 +----------+----------------------------------------------+ 1980 | 2.04 | The channel already exists | 1981 +----------+----------------------------------------------+ 1983 10.1.8. PUT /v1/channels//open 1985 This request requires "Channel Management" privileges on the 1986 requesting channel. 1988 This instructs the device to open the indicated channel. No 1989 request payload is provided. 1991 The response code will be one of: 1992 +----------+----------------------------------------------+ 1993 | Response | Description | 1994 +----------+----------------------------------------------+ 1995 | 2.04 | The device will try to open the channel | 1996 +----------+----------------------------------------------+ 1997 | 4.01 | The channel does not have privileges to | 1998 | | manage channels | 1999 +----------+----------------------------------------------+ 2000 | 4.04 | The channel does not exist | 2001 +----------+----------------------------------------------+ 2003 Note that a 2.04 response DOES NOT mean that the channel has been 2004 successfully opened. Instead, it means that the device WILL TRY to 2005 open the channel. This may take some time and the status can be 2006 monitored with the channel status request in 10.1.11. below. 2008 10.1.9. PUT /v1/channels//close 2010 This request requires "Channel Management" privileges on the 2011 requesting channel. 2013 This instructs the device to close the indicated channel. No 2014 request payload is provided. 2016 The response code will be one of: 2017 +----------+----------------------------------------------+ 2018 | Response | Description | 2019 +----------+----------------------------------------------+ 2020 | 2.04 | The device will try to close the channel | 2021 +----------+----------------------------------------------+ 2022 | 4.01 | The channel does not have privileges to | 2023 | | manage channels | 2024 +----------+----------------------------------------------+ 2025 | 4.04 | The channel does not exist | 2026 +----------+----------------------------------------------+ 2028 Note that a 2.04 response DOES NOT mean that the channel has been 2029 successfully closed. Instead, it means that the device WILL TRY to 2030 close the channel. This may take some time and the status can be 2031 monitored with the channel status request in 10.1.11. below. 2033 10.1.10. DELETE /v1/channels/ 2034 This request requires "Channel Management" privileges on the 2035 requesting channel. 2037 This instructs the device to delete the indicated channel, closing 2038 it automatically if it is currently open. No request payload is 2039 provided. The device will not permit any channel defined in the 2040 bootstrap data to be deleted. 2042 The response code will be one of: 2043 +----------+----------------------------------------------+ 2044 | Response | Description | 2045 +----------+----------------------------------------------+ 2046 | 2.02 | The channel has been deleted or does not | 2047 | | exist | 2048 +----------+----------------------------------------------+ 2049 | 2.04 | The channel was open so will be cleanly | 2050 | | closed then deleted | 2051 +----------+----------------------------------------------+ 2052 | 4.01 | The channel does not have privileges to | 2053 | | manage channels | 2054 +----------+----------------------------------------------+ 2055 | 4.03 | The channel is not allowed to be deleted | 2056 +----------+----------------------------------------------+ 2058 Note that after a 2.04 response the client can poll the channel 2059 status using the "GET" request as in 10.1.11. below. If the 2060 channel is still being closed, the response will be a 2.05 with 2061 status = 4. As soon as the close completes, the channel will be 2062 deleted and the "GET" request in 10.1.11. below will return 4.04 2063 because the channel no longer exists. 2065 10.1.11. GET /v1/channels/ 2067 This request requires "Channel Management" privileges on the 2068 requesting channel. 2070 This requests the device to return the configuration and status of 2071 the channel. No request payload is provided. The channel 2072 configuration and status will be provided in the request payload 2073 in CBOR format as below: 2075 ARRAY { 2076 ARRAY { 2077 // Configuration structure as in 10.1.6. above 2078 } 2079 ARRAY { 2080 INTEGER channel_id 2081 INTEGER state 2082 // Additional status flags may follow 2083 } 2084 } 2085 The "status" integer will be one of: 2086 +----------+----------------------------------------------+ 2087 | Response | Description | 2088 +----------+----------------------------------------------+ 2089 | 0 | The channel is closed | 2090 +----------+----------------------------------------------+ 2091 | 1 | The channel is requested to be opened | 2092 +----------+----------------------------------------------+ 2093 | 2 | The channel handshake is in progress | 2094 +----------+----------------------------------------------+ 2095 | 3 | The channel is open | 2096 +----------+----------------------------------------------+ 2097 | 4 | The channel is being closed | 2098 +----------+----------------------------------------------+ 2099 | 10 | The channel handshake failed because the | 2100 | | peer did not answer | 2101 +----------+----------------------------------------------+ 2102 | 11 | The channel handshake failed because the | 2103 | | peer provided the wrong key ID | 2104 +----------+----------------------------------------------+ 2105 | 12 | The channel handshake failed because the | 2106 | | peer failed authentication | 2107 +----------+----------------------------------------------+ 2108 | 13 | The channel has experienced some other error | 2109 +----------+----------------------------------------------+ 2111 The response code will be one of: 2112 +----------+----------------------------------------------+ 2113 | Response | Description | 2114 +----------+----------------------------------------------+ 2115 | 2.05 | The channel information has been returned | 2116 +----------+----------------------------------------------+ 2117 | 4.01 | The channel does not have privileges to | 2118 | | manage channels | 2119 +----------+----------------------------------------------+ 2120 | 4.04 | The channel does not exist | 2121 +----------+----------------------------------------------+ 2123 10.1.12. GET /v1/channels 2125 This request requires "Channel Management" privileges on the 2126 requesting channel. 2127 This requests the device to return the configuration and status of 2128 all channels. No request payload is provided. The information is 2129 returned as a CBOR array of channel responses as defined in 2130 10.1.11. above. 2132 The response code will be one of: 2133 +----------+----------------------------------------------+ 2134 | Response | Description | 2135 +----------+----------------------------------------------+ 2136 | 2.05 | The configuration and status for all | 2137 | | channels has been returned | 2138 +----------+----------------------------------------------+ 2139 | 4.01 | The channel does not have privileges to | 2140 | | manage channels | 2141 +----------+----------------------------------------------+ 2143 10.1.13. PUT /v1/reboot 2145 This request requires "System Management" privileges on the 2146 requesting channel. 2148 This instructs the device to reboot. The device will reboot after 2149 returning the response. No request payload is provided and no 2150 response payload is returned. 2152 The response code will be one of: 2153 +----------+----------------------------------------------+ 2154 | Response | Description | 2155 +----------+----------------------------------------------+ 2156 | 2.04 | The device is about to reboot | 2157 +----------+----------------------------------------------+ 2158 | 4.01 | The channel does not have privileges to | 2159 | | manage the system | 2160 +----------+----------------------------------------------+ 2162 10.1.14. PUT /v1/shutdown 2164 This request requires "System Management" privileges on the 2165 requesting channel. 2167 This instructs the device to shut down. The device will shut down 2168 after returning the response. No request payload is provided and 2169 no response payload is returned. 2171 The response code will be one of: 2172 +----------+----------------------------------------------+ 2173 | Response | Description | 2174 +----------+----------------------------------------------+ 2175 | 2.04 | The device is about to shutdown | 2176 +----------+----------------------------------------------+ 2177 | 4.01 | The channel does not have privileges to | 2178 | | manage the system | 2179 +----------+----------------------------------------------+ 2181 10.1.15. PUT /v1/bootstrap 2183 This request requires "System Management" privileges on the 2184 requesting channel. 2186 This instructs the device to perform an aSSURE bootstrap. The 2187 device will bootstrap after returning the response. No request 2188 payload is provided and no response payload is returned. 2190 The response code will be one of: 2191 +----------+----------------------------------------------+ 2192 | Response | Description | 2193 +----------+----------------------------------------------+ 2194 | 2.04 | The device is about to bootstrap | 2195 +----------+----------------------------------------------+ 2196 | 4.01 | The channel does not have privileges to | 2197 | | manage the system | 2198 +----------+----------------------------------------------+ 2200 10.1.16. GET /v1/ping 2202 This request requires no privileges on the requesting channel. 2203 This is used to check that the device is online and able to 2204 respond to requests. 2206 A payload may be provided. The device will respond with the same 2207 payload (or as much of the payload as the device can return if it 2208 is a constrained device). The response code will be: 2210 +----------+----------------------------------------------+ 2211 | Response | Description | 2212 +----------+----------------------------------------------+ 2213 | 2.05 | Ping response | 2214 +----------+----------------------------------------------+ 2216 10.1.17. GET /v1/info 2218 This request requires no privileges on the requesting channel. 2220 This is used to return basic information about the device. The 2221 device will return the CBOR structure below: 2223 ARRAY { 2224 BYTE STRING device_id 2225 BYTE STRING device_mac_address 2226 TEXT STRING device_manufacturer 2227 TEXT STRING device_product_code 2228 TEXT STRING device_serial_number 2229 TEXT STRING device_build_date 2230 TEXT STRING software_manufacturer 2231 TEXT STRING software_product_code 2232 TEXT STRING software_version 2233 } 2235 The only field that must be present is the device_id. All other 2236 fields may be zero length if the device is unable to provide them 2237 for any reason. 2239 The response code will be: 2241 +----------+----------------------------------------------+ 2242 | Response | Description | 2243 +----------+----------------------------------------------+ 2244 | 2.05 | Information returned | 2245 +----------+----------------------------------------------+ 2247 11. Management Server API 2249 11.1. Overview 2251 The management server must support the registration and presence 2252 APIs. The registration API is used to allow devices to be 2253 registered with the management system. The presence API is used by 2254 devices after bootstrap to inform the management system of their 2255 presence on the network. 2257 11.2. Registration API 2259 The Registration API is used to register the device with the 2260 management system when it is installed. The Registration API is a 2261 RESTful interface using JSON over HTTPS. The authentication 2262 behaviour is determined by the Management Server implementation 2263 but either username + passphrase or client certificates are 2264 recommended. 2266 11.2.1. POST /v1/devices/?case_string= 2268 This is used to register the indicated device UUID with the 2269 management system. The case string is provided to prove the device 2270 is physically present. The UUID and case string would normally 2271 come from a QR code or similar attached to the device (use of an 2272 RFID is not recommended as the source for obvious security 2273 reasons). 2275 No payload is returned. The response code will be one of: 2276 +--------------+------------------------------------------+ 2277 | Response | Description | 2278 +--------------+------------------------------------------+ 2279 |201 Created | The new device has been registered | 2280 +--------------+------------------------------------------+ 2281 | 401 | The device cannot be registered because | 2282 | Unauthorised | it already exists | 2283 +--------------+------------------------------------------+ 2284 | 503 Service | The device cannot be registered | 2285 | Unavailable | at this time | 2286 +--------------+------------------------------------------+ 2288 Only a single device is uploaded in each POST request, but the 2289 client may re-use the HTTPS session to send additional requests. 2291 11.2.2. POST /v1/devices//replace?uuid= 2293 This is used to tell the management system that the indicated 2294 device with UUID has been replaced by the device with 2295 UUID . For example, this would occur when a device has 2296 failed and a maintenance engineer has replaced it. The management 2297 system can then update its database, etc. to allow the new device 2298 to "seamlessly replace" the old device (e.g. by applying the old 2299 device configuration to the new device). For security reasons, the 2300 management system should immediately disable the old device as 2301 this call indicates that the old device is no longer in use. 2303 The new device must be registered with the call in 11.2.1. above 2304 before performing this call to replace the old device. 2306 No payload is returned. The response code will be one of: 2307 +--------------+------------------------------------------+ 2308 | Response | Description | 2309 +--------------+------------------------------------------+ 2310 | 201 Created | The new device has replaced the old one | 2311 +--------------+------------------------------------------+ 2312 | 401 | The old device does not exist, the client| 2313 | | is not allowed to update the state of the| 2314 | | old device, the new device does not exist| 2315 | | or the client is not allowed to update | 2316 | | the state of the new device. | 2317 +--------------+------------------------------------------+ 2318 | 503 Service | The device cannot be replaced | 2319 | Unavailable | at this time | 2320 +--------------+------------------------------------------+ 2322 11.2.3. GET /v1/devices//status 2324 This is used to get the status of the device. The registration, 2325 configuration, bootstrap and presence of a device may take some 2326 time. A registration client may obtain the status of the device 2327 here to check if the device has entered service. 2329 If successful, the payload is a JSON structure: 2331 { 2332 status: , 2333 description: "" 2334 } 2336 11.2.4. GET /v1/devices//info 2338 This is used to get the information for the device. This is only 2339 available after the device has sent is presence message to the 2340 management system. 2342 If successful, the payload is a JSON structure with the same 2343 information as in 10.1.17. above: 2345 { 2346 "device_id": "", 2347 "device_mac_address": "", 2348 "device_manufacturer": "...", 2349 "device_product_code": "...", 2350 "device_serial_number": "...", 2351 "device_build_date": "...", 2352 "software_manufacturer": "...", 2353 "software_product_code": "...", 2354 "software_version": "..." 2355 } 2357 The response code will be one of: 2358 +--------------+------------------------------------------+ 2359 | Response | Description | 2360 +--------------+------------------------------------------+ 2361 | 200 OK | The device information has been returned | 2362 +--------------+------------------------------------------+ 2363 | 401 | The client is not authorised to access | 2364 | Unauthorised | this device | 2365 +--------------+------------------------------------------+ 2366 | 503 Service | Device information cannot be returned at | 2367 | Unavailable | this time | 2368 +--------------+------------------------------------------+ 2370 Only a single device response is permitted per GET request, but 2371 the client may re-use the HTTPS session to send additional 2372 requests. 2374 11.3. Presence API 2376 The Presence API is used by the device to indicate to the 2377 management system that its bootstrap process has completed and it 2378 is now online in the network. Like the Bootstrap API and Device 2379 Management APIs, the Presence API is RESTful using CBOR and CoAP 2380 over DTLS. 2382 11.3.1. PUT /v1/devices//info 2384 This is used by the device to confirm it is active and has 2385 completed its bootstrap. 2387 The device provides the same CBOR structure as in 10.1.17. above 2388 as the request payload. 2390 No payload is returned. The response code will be one of: 2391 +-------------+-------------------------------------------+ 2392 | Response | Description | 2393 +-------------+-------------------------------------------+ 2394 | 2.01 Created| The device presence has been acknowledged | 2395 +-------------+-------------------------------------------+ 2396 | 4.01 | The device has attempted to provide | 2397 |Unauthorized | information for a different device | 2398 +-------------+-------------------------------------------+ 2400 11.3.2. PUT /v1/devices//goodbye 2402 This is used by the device to indicate it is deliberately going 2403 offline. It will send this to all connected management systems. 2405 The device will provide a single INTEGER in CBOR format to 2406 indicate the reason. 2408 +---------+-----------------------------------------------+ 2409 | Value | Reason | 2410 +---------+-----------------------------------------------+ 2411 | 0 | Device is shutting down | 2412 +---------+-----------------------------------------------+ 2413 | 1 | Device has been instructed to reboot by | 2414 | | Management System | 2415 +---------+-----------------------------------------------+ 2416 | 2 | Device has been instructed to bootstrap by | 2417 | | Management System | 2418 +---------+-----------------------------------------------+ 2419 | 3 | Device has been instructed to reboot by | 2420 | | local controls (e.g. button) | 2421 +---------+-----------------------------------------------+ 2422 | 4 | Device has been instructed to bootstrap by | 2423 | | local controls (e.g. button) | 2424 +---------+-----------------------------------------------+ 2426 No payload is returned. The response code will be one of: 2427 +-------------+-------------------------------------------+ 2428 | Response | Description | 2429 +-------------+-------------------------------------------+ 2430 | 2.04 Changed| The device goodbye has been acknowledged | 2431 +-------------+-------------------------------------------+ 2432 | 4.01 | The device has attempted to provide | 2433 |Unauthorized | information for a different device | 2434 +-------------+-------------------------------------------+ 2436 11.4. Miscellaneous 2438 11.4.1. GET /v1/timestamp 2440 This is used to get the current time from a trusted source. A 2441 device may use this to set its clock without having to include 2442 support for other protocols such as NTP. This request may be made 2443 by any client with or without authentication. 2445 No payload is provided. The response is a timestamp in CBOR as 2446 defined in 7.11. above (both integer and fractional parts). 2448 The response code will be one of: 2449 +--------------+------------------------------------------+ 2450 | Response | Description | 2451 +--------------+------------------------------------------+ 2452 | 200 OK | The timestamp has been returned | 2453 +--------------+------------------------------------------+ 2454 | 503 Service | Device information cannot be returned at | 2455 | Unavailable | this time | 2456 +--------------+------------------------------------------+ 2458 12. Physical / Network Layer Implementations 2460 12.1. BACnet 2462 aSSURE traffic is fully compatible with existing BACnet traffic 2463 and is identified as Network Control messages using Message Types 2464 0x80 - 0x82 and Vendor ID 0x_TBD_. 2466 Message Types 0x80 through 0x82 are used to identify the aSSURE 2467 traffic as belonging to one of three logical groups. 2469 +-------------+-------------------------------------------+ 2470 | Message Type| Description | 2471 +-------------+-------------------------------------------+ 2472 | 0x80 | aSSURE Bootstrap | 2473 +-------------+-------------------------------------------+ 2474 | 0x81 | aSSURE Secure Management Channels | 2475 +-------------+-------------------------------------------+ 2476 | 0x82 | aSSURE Secure Data Channels | 2477 +-------------+-------------------------------------------+ 2479 When an address is indicated in a CBOR message, the address format 2480 is: 2482 ARRAY { 2483 INTEGER 0 // Address type 1 = BACnet 2484 INTEGER net 2485 BYTE STRING addr // "len" is the BYTE STRING length 2486 } 2488 If the "net" field is a NULL (CBOR Major: 7, Value: 22 => 0xF6) 2489 rather than an INTEGER (CBOR Major: 0), this indicates a local 2490 network address. When creating the BACnet NPDU, the NPDU 2491 destination specifier for that address would not be present. 2493 12.1.1. aSSURE Bootstrap 2495 The aSSURE Bootstrap messages are used to identify the bootstrap 2496 gateways on the BACnet network and assign a secure data channel 2497 for communication with the bootstrap server. This traffic cannot 2498 be secured because it happens BEFORE the bootstrap data has been 2499 received so the device has no keys for communicating with peers on 2500 the local network. 2502 All Insecure Control Messages are RESTful using CoAP in the NSDU 2503 part of an NPDU frame. They are therefore independent of any 2504 specific BACnet LLC such as BACnet IP or BACnet MS/TP. 2506 12.1.1.1. GET /v1/gateway/ 2508 This message is broadcast on BACnet to discover the best gateway 2509 capable of routing traffic to the indicated bootstrap server. No 2510 payload is provided. 2512 All gateways capable of routing traffic to the broadcast server 2513 should respond with their assigned priority for handling traffic 2514 (or zero if it has not been explicitly set). This means that a 2515 device may receive multiple replies to its GET message and it 2516 should be able to handle this. The device should wait a reasonable 2517 time (e.g. 5 seconds) for all replies to be received and should 2518 pick the gateway with the lowest priority value. If multiple 2519 gateways respond with the same lowest priority value, a gateway 2520 should be chosen at random. 2522 If no gateways respond, the device should backoff and retry. 2524 The gateway response should be a 2.00 status code with a CBOR 2525 payload containing the following content: 2527 INTEGER priority 2529 12.1.1.2. POST /v1/gateway/channel?server= 2531 This message is sent to the chosen gateway that responded to the 2532 discovery message described in 12.1.1.1. above. The gateway 2533 should assign a channel that routes messages to the indicated 2534 bootstrap server. No payload is provided. If successful, the 2535 gateway response should be a CBOR payload with the following 2536 content: 2538 INTEGER channel_id 2539 BYTE STRING token 2541 The cookie should be a random string of at least 4 bytes. The 2542 device must provide this token when closing the channel. 2544 The status code will be one of: 2545 +----------+----------------------------------------------+ 2546 | Response | Description | 2547 +----------+----------------------------------------------+ 2548 | 2.01 | The channel has been created | 2549 +----------+----------------------------------------------+ 2550 | 4.04 | The gateway cannot find a route to the | 2551 | | indicated bootstrap server | 2552 +----------+----------------------------------------------+ 2553 | 5.03 | The gateway cannot create the channel at | 2554 | | this time | 2555 +----------+----------------------------------------------+ 2557 12.1.1.3. DELETE/v1/gateway/channel/?token= 2559 This message is sent to the chosen gateway that responded to the 2560 discovery message described in 12.1.1.1. above. The gateway 2561 should assign a channel that routes messages to the indicated 2562 bootstrap server. No payload is provided and no payload is 2563 returned. The device must offer the token returned by the gateway 2564 in the channel assign request in 12.1.1.2. above and the DELETE 2565 request must come from the same network address as the POST 2566 request. 2568 The status code will be one of: 2569 +----------+----------------------------------------------+ 2570 | Response | Description | 2571 +----------+----------------------------------------------+ 2572 | 2.02 | The channel has been deleted | 2573 +----------+----------------------------------------------+ 2574 | 4.01 | The device is not allowed to delete this | 2575 | | channel | 2576 +----------+----------------------------------------------+ 2578 12.1.2. aSSURE Secure Management Channels 2580 These messages are used for encrypted aSSURE-protected DTLS 2581 sessions accessing the Device Management API defined in 10. 2582 above. All messages on the aSSURE Secure Management Channel have 2583 the following CBOR structure: 2585 INTEGER channel_id 2586 BYTE STRING dtls_data 2588 12.1.3. aSSURE Secure Data Channels 2590 These messages are used for all other aSSURE-protected DTLS 2591 session such as secure bootstrap or peer-to-peer channels. All 2592 messages on the aSSURE Secure Data Channel have the following CBOR 2593 structure: 2595 INTEGER channel_id 2596 BYTE STRING dtls_data 2598 12.2. IP 2600 When deployed on IP networks, aSSURE traffic uses UDP port TBD for 2601 Secure Management Channels and UDP port TBD for Secure Data 2602 Channels. The UDP payload is the DTLS data. The channel ID is 2603 inferred from the local port and remote address and port. 2605 When compared to BACnet, the "aSSURE Bootstrap" messages are not 2606 required because an IP network is already able to route traffic 2607 directly to the bootstrap servers without the explicit 2608 establishment of a channel. The device is assumed to be capable of 2609 DHCP and DNS to obtain a local IP address, determine the subnet 2610 gateway and resolve the bootstrap server FQDN. 2612 When an address is indicated in a CBOR message, the address format 2613 is: 2615 ARRAY { 2616 INTEGER 1 // Address type 1 = IP 2617 BYTE STRING remote_addr // 4 bytes for IPv4,network byte order 2618 //16 bytes for IPv6,network byte order 2619 INTEGER local_port // Local UDP port, 0=any 2620 INTEGER remote_port // Remote UDP port 2621 } 2623 12.2.1. Bootstrap Server FQDN 2625 The bootstrap server ID can be converted to a Fully Qualified 2626 Domain Name (FQDN) by suffixing the decimal value of the ID with 2627 the string ".*TBD*.net". Similarly, an aSSURE bootstrap server 2628 FQDN can be converted to the server ID by reversing the process. 2630 12.3. Bluetooth 2632 Bluetooth implementations should use the "Internet Protocol 2633 Support Profile" to allow the device to send and receive IPv6 2634 traffic. 2636 When an address is indicated in a CBOR message, the address format 2637 should be type 1 as in 12.2. above. 2638 When a Bluetooth MAC address is specifically indicated in a CBOR 2639 message, the address format is: 2641 ARRAY { 2642 INTEGER 2 // Address type 2 = Bluetooth 2643 BYTE STRING mac // MAC address, 6 bytes 2644 } 2646 In all other respects, the Bluetooth implementation follows the 2647 "IP" implementation as in 12.2. above. 2649 12.4. Assigned address types 2650 +-------------+-------------------------------------------+ 2651 | Address Type| Description | 2652 +-------------+-------------------------------------------+ 2653 | 0 | BACnet NPDU address | 2654 +-------------+-------------------------------------------+ 2655 | 1 | Destination IP address and UDP ports | 2656 +-------------+-------------------------------------------+ 2657 | 2 | Bluetooth MAC address | 2658 +-------------+-------------------------------------------+ 2659 13. DTLS Connection Configuration Examples 2661 13.1. Example Topology 2663 *********** *********** +++++++++++ 2664 +Device G +<-ec-->*Device A *<-ec-->*Device B * 2665 +++++++++++ *********** *********** 2666 ^ ^ ^ | ^ / ^ 2667 | | \ / | \ R | 2668 e e \ e e s S R 2669 c c R c c s A S 2670 | | SA-----RSA-------RS \/ A 2671 | e / | A/\ | 2672 e c-ec---/-e e /\ \ R 2673 c e c c / \ s S 2674 | c \ | / \ s A 2675 | / \ | / \ \ | 2676 v v v v v v v v 2677 *********** OOOOOOOOOOOO +++++++++++ 2678 * * oManagemento + + 2679 *Device F *--ec->o System o<-RSA--+Device C + 2680 *********** OOOOOOOOOOOO +++++++++++ 2681 ^ ^ ^ ^ ^ 2682 | / | \ | 2683 | / | \ | 2684 s / s \ s 2685 s ss-/ s \-ss s 2686 | / | \ | 2687 | / | \ | 2688 | / | \ | 2689 _____v_/_ _________ _\_v_____ 2690 / \ / \ / \ 2691 |Device E |<--ss->|Device E |<-ss-->|Device D | 2692 |Service X| |Service Y| | | 2693 \________ / \_________/ \_________/ 2695 *** - (Device A & F) Elliptic Curve and Shared Secret Capable 2696 +++ - (Device C) RSA and Shared Secret Capable 2698 *** _ (Device G) Elliptic Curve, RSA and Shared Secret Capable 2699 +++ (EC Device Key) 2701 +++ _ (Device B) Elliptic Curve, RSA and Shared Secret Capable 2702 *** (RSA Device Key) 2704 ___ - (device D and E) Only Shared Secret Capable 2705 (Shared Secret Device Key) 2707 "ec", "ss", "RSA" are the channels 2708 DTLS Connection Example Topology 2710 13.2. Elliptic Curve device . Elliptic Curve device 2712 e.g. Device A . Device F 2713 Both endpoints have Elliptic Curve keys so no additional keys need 2714 to be created. Each endpoint is sent a channel definition 2715 indicating the local device key, the peer device key, the peer 2716 address and the privileges for the channel. 2718 13.3. Elliptic Curve device . RSA device 2720 We cannot use the two device keys to directly secure the DTLS 2721 connection. There are three possible solutions to allow a secure 2722 link. These are presented in the order of most to least preferred. 2724 13.3.1. Option 1 - Issue EC key to RSA device 2726 e.g. Device A . Device B 2727 If the RSA device can support Elliptic Curve keys, then a new 2728 Elliptic Curve key should be created on (or issued to) the RSA 2729 device by the Management System. The Management System should sign 2730 the new key as assigned to the device. 2732 Now both devices have an EC key, so 13.2. above can be followed. 2734 13.3.2. Option 2 - Issue RSA key to EC device 2736 e.g. Device C . Device G 2737 If the EC device can support RSA keys, then a new RSA key should 2738 be created on (or issued to) the EC device by the Management 2739 System. The Management System should sign the new key as assigned 2740 to the device. 2742 Now both devices have an RSA key, so 13.5. below can be followed. 2744 13.3.3. Option 3 - Issue Shared Secret to both devices 2746 e.g. Device A . Device C 2747 Shared secrets must be used, so 13.7. below is followed. 2749 13.4. Elliptic Curve device . Shared Secret device 2751 e.g. Device F . Device E (Service X) 2752 Shared secrets must be used, so 13.7. below is followed. 2754 13.5. RSA device . RSA device 2756 e.g. Device B . Device C 2757 Both endpoints have RSA key so no additional keys need to be 2758 created. Each endpoint is sent a channel definition indicating the 2759 local device key, the peer device key, the peer address and the 2760 privileges for the channel. 2762 13.6. RSA device . Shared Secret device 2764 e.g. Device C . Device D 2765 Shared secrets must be used, so 13.7. below is followed. 2767 13.7. Shared Secret device . Shared Secret device 2769 e.g. Device D . Device E (Service Y) 2770 The management system must issue a new shared secret (called the 2771 "Channel Key") to both devices to identify the channel. Each 2772 endpoint is sent a channel definition indicating the Channel Key, 2773 the peer address and the privileges for the channel. 2775 14. Message Sequence Diagrams 2777 14.1. Manufacturing Flow 2779 +------+ +--------+ +--------+ +--------+ +------------+ +---------+ 2780 |DEVICE| | MAKER | | MAKER | |IDENTITY| |REGISTRATION| |BOOTSTRAP| 2781 | | | | |GATEWAY | | SERVER | | SERVER | | SERVER | 2782 +------+ +--------+ +--------+ +--------+ +------------+ +---------+ 2783 | | | | | | 2784 []<--UUID--| | | | | 2785 [Key Generation] | | | | 2786 []UUID+KEY-> | | | | 2787 | []POST | | | | 2788 | []/v1/devices->[] | | | 2789 | [] []-CheckDeviceExists()--->[] | 2790 | [] [] | [] | 2791 | [] []<-------FALSE-----------[] | 2792 | [] [] | | | 2793 | [] []-----CreareDevice()---->[] | 2794 | [Key] [] | [] | 2795 | [Encryption] []<--------ACK------------[] | 2796 | [] [] | | | 2797 | [] []--------------CreateDevice()--------->[] 2798 | [] [] | | [] 2799 | [] []<-----------------ACK-----------------[] 2800 | [] [] | | | 2801 | [] []SUBMIT device data | | 2802 | [] []--->| | | 2803 | []<201 Created-[] [] | | 2804 | | [Key Decryption] | | 2805 | | [Bootstrap and Registration Identity] | 2806 | | [Generation] | | 2807 | | []ISSUE device bootstrap data---->| 2808 | | [] | | 2809 | | []ISSUE device | | 2810 | | | registration | | 2811 | | | data------->| | 2812 | | | | | 2813 | | | [] [] 2814 | | | IMPORT IMPORT 2815 | | | data data 2816 | | | [] [] 2817 | | | | | 2818 | | | Ready for Ready for 2819 | | | device owner data 2820 | | | registration upload 2821 | | | | | 2823 Manufacturing Flow Sequence Diagram 2825 14.2. Management System Preparation 2827 +------------+ +-------+ 2828 | MANAGEMENT | | OWNER | 2829 | SYSTEM | |GATEWAY| 2830 +------------+ +-------+ 2831 | | 2832 [] | 2833 Certificate | 2834 Generation | 2835 [] POST | 2836 [] /v1/managementsystems | 2837 []------------------------------>[] 2838 [] [] 2839 [] 201 Created UUID [] 2840 []<------------------------------[] 2841 [] | 2842 | | 2844 Registration of the Management System with the Trusted Authority 2846 Management System Preparation Sequence Diagram 2848 14.3. Device Registration 2850 +------+ +---------+ +----------+ +-------+ +---------+ +-----------+ 2851 |DEVICE| |INSTALLER| |MANAGEMENT| | OWNER | |BOOTSTRAP| REGISTRATION| 2852 | | | | | SERVER | |GATEWAY| | SERVER | | SERVER | 2853 +------+ +---------+ +----------+ +-------+ +---------+ +-----------+ 2854 | | | | | | 2855 [Installed | | | | | 2856 On site ] | | | | | 2857 | | | | | | 2858 |------->[] | | | | 2859 | QR Code[]------------>[] | | | 2860 | scanned[] Upload UUID [] | | | 2861 | [] and case ID [] | | | 2862 | [] [] PUT | | 2863 | [] []/v1/devices//owner | | 2864 | [] []---------->[] | | 2865 | [] [] [] Set DeviceOwner() | 2866 | [] [] []------------------------>[] 2867 | [] [] [] ACK [] 2868 | [] [] []<------------------------[] 2869 | [] [] 200 OK [] | | 2870 | [] []<----------[] | | 2871 | [] ACK [] | | | 2872 | []<------------[] | | | 2873 | | | | | | 2874 | | | | | | 2876 Registration of the device with the management systems 2878 Device Registration Sequence Diagram 2880 14.4. Device Ownership State Machine 2882 O 2883 | 2884 | 2885 | 2886 V 2887 +------------+ 2888 | UNOWNED | 2889 | |<----------------- 2890 +------------+ | 2891 | | 2892 | | 2893 |POST |POST 2894 |/v1/devices//owner |/v1/devices//release 2895 | | 2896 V | 2897 +------------+ | 2898 | OWNED | | 2899 ------->| |------------------ 2900 | +------------+ 2901 | | 2902 | POST | 2903 ---------- 2904 /v1/devices//transfer 2906 Device Ownership State Machine 2908 14.5. Device Configuration and Bootstrap 2910 +------+ +----------------+ +----------+ +----------+ +------------+ 2911 |DEVICE| | MANAGEMENT | |OWNER | |BOOTSTRAP | |REGISTRATION| 2912 | | | SYSTEM | |GATEWAY | | SERVER | | SERVER | 2913 +------+ +----------------+ +----------+ +----------+ +------------+ 2914 | | | | | 2915 | [Device Registration | | | 2916 | Completed] | | | 2917 | [] | | | 2918 | [] GET | | | 2919 | []/v1/devices//configuration | | 2920 | []------------------->[] | | 2921 | [] [] | | 2922 | [] []GetDeviceData() | | 2923 | [] []-------------->[]GetDeviceOwner() 2924 | [] [] []------------>[] 2925 | [] [] [] [Owner] [] 2926 | [] [] []<------------[] 2927 | [] [] [data] [] | 2928 | [] []<--------------[] | 2929 | [] [] | | 2930 | [] 200 OK [data] [] | | 2931 | []<-------------------[] | | 2932 | [] | | | 2933 | | | | | 2934 [Power | | | | 2935 Applied] | | | | 2936 | | | | | 2937 [] GET /v1/devices//bootstrap | | 2938 []---------------------------------------------->[] | 2939 [] | | [] | 2940 [] | 200 OK [image] | [] | 2941 []<----------------------------------------------[] | 2942 [] | | | | 2943 [Validate and | | | 2944 decrypt bootstrap | | | 2945 image] | | | | 2946 [] | | | | 2947 [Apply bootstrap | | | 2948 Image] | | | | 2949 [] | | | | 2950 []PUT /v1/devices//info | | | 2951 []------->[] | | | 2952 [] [] | | | 2953 []<-------[] | | | 2954 | | | | | 2955 | | | | | 2957 Device Configuration and Bootstrap Sequence Diagram 2959 14.6. Device Configuration and Bootstrap (Walled Garden) 2960 +------+ +-------+ +-------+ +-------+ +-------+ +------+ +--------+ 2961 |DEVICE| |WALLED | |WALLED | |MANAGE | |OWNER | |BOOT | REG | 2962 | | |BOOT | |MANAGE | |SYSTEM | |GATEWAY| |SERVER| |SERVER | 2963 +------+ +-------+ +-------+ +-------+-+-------+ +------+ +--------+ 2964 | | |[Device Reg Done] | | | 2965 | | | [] | | | 2966 | | | [-GET------>] | | 2967 | | | [] ?/config[] [] | 2968 | | | [] [-GetDevData ] | 2969 | | | [] []---------->] | 2970 | | | [] [] [GetDevOwner 2971 | | | [] [] [--------->] 2972 | | | [] [] [] owner [] 2973 | | | [] [] data [<---------] 2974 | | | [] 200 OK []<----------] [] 2975 | | | []<---------] [] | 2976 | | | [] [] | | 2977 | | (Build Bootstrap Image)| | | 2978 | | | [] | | | 2979 | |<------------------[]EXPORT device bootstrap data | 2980 | | |<-----[]EXPORT device management data | 2981 | [] [] | | | | 2982 | IMPORT IMPORT | | | | 2983 | bootstrap data management data | | | 2984 | [] [] | | | | 2985 | | | | | | | 2986 [Power Applied] | | | | | 2987 [] | | | | | | 2988 [-GET----->[] | | | | | 2989 []?/bootstrap | | | | | 2990 [] [] | | | | | 2991 [] 200 OK [] | | | | | 2992 []<---------] | | | | | 2993 [] (image) [] | | | | | 2994 [] | | | | | 2995 [Validate and decrypt | | | | | 2996 Bootstrap image] | | | | | 2997 [Apply bootstrap image] | | | | | 2998 [] | | | | | | 2999 [] | [] | | | | 3000 []-POST ?/info---------->] | | | | 3001 [] | [] | | | | 3002 []<----------------------] | | | | 3003 [] | [] | | | | 3004 | | | | | | | 3006 ?/ is /v1/devices// 3007 Configuration of the device to connect to the management system 3009 Device Configuration and Bootstrap Sequence Diagram 3010 (Walled Garden) 3012 14.7. Device Change Owner 3014 +------+ +--------+ +--------+ +--------+ +----------+ +------------+ 3015 |DEVICE| | MAKER | | MAKER | |OWNER | |BOOTSTRAP | |REGISTRATION| 3016 | | |SYSTEM A| |SYSTEM B| |GATEWAY | | SERVER | | SERVER | 3017 +------+ +--------+ +--------+ +--------+ +----------+ +------------+ 3018 | | | | | | 3019 []<-data->[] []---GET--->] | | 3020 [] [] []?/configuration | | 3021 [] [] [] [] | | 3022 [] [] [] []GetDeviceData() | 3023 [] [] [] []----------->[]GetDeviceOwner() 3024 [] [] [] [] []----------->[] 3025 [] [] [] [] [] [Mgmt B] [] 3026 [] [] [] []UNAUTHORISED[]<-----------[] 3027 [] [] [] 403 []<-----------[] | 3028 [] [] []<--------[] | | 3029 [] [] | Forbidden| | | 3030 [] [] PUT | | | | 3031 [] []------------------------>] | | 3032 [] []?/transfer?mgmtid=$MgmtB[] SetDeviceOwner("Mgmt B") | 3033 [] [] | []------------------------->[] 3034 [] [] | [] | Reset [] 3035 [] [] | [] | Device [] 3036 [] [] | [] | Bootstrap()[] 3037 [] [] | [] []<-----------[] 3038 [] [] | [] [] ACK [] 3039 [] [] | [] []----------->[] 3040 [] [] | [] ACK | [] 3041 [] [] 200 OK []<-------------------------[] 3042 [] []<-----------------------[] | | 3043 []<-------[] | | | | 3044 [] PUT /v1/bootstrap | | | | 3045 [] [] | | | | 3046 []-------->] | | | | 3047 [] PUT ?/goodbye | | | | 3048 [] [] | | | | 3049 [] | | | | | 3050 []-----------GET /v1/devices//bootstrap---->[] | 3051 [] | | | [] | 3052 []<----------------- 204 No Content--------------[] | 3053 [] | | | | | 3054 | | | | | | 3055 [sleeps] | | | | | 3056 | | | | | | 3057 | | | | | | 3058 | | | | | | 3060 Device Change Owner Sequence Diagram (first part) 3062 | | | | | | 3063 +------+ +--------+ +--------+ +--------+ +----------+ +------------+ 3064 |DEVICE| | MAKER | | MAKER | |OWNER | |BOOTSTRAP | |REGISTRATION| 3065 | | |SYSTEM A| |SYSTEM B| |GATEWAY | | SERVER | | SERVER | 3066 +------+ +--------+ +--------+ +--------+ +----------+ +------------+ 3067 [sleeps] | | | | | 3068 | | []---GET--->] | | 3069 | | []?/configuration | | 3070 | | [] [] | | 3071 | | [] []GetDeviceData() | 3072 | | [] []----------->[]GetDeviceOwner() 3073 | | [] [] []----------->[] 3074 | | [] [] [] [Mgmt B] [] 3075 | | [] 200 OK [] [data] []<-----------[] 3076 | | [] [data] []<-----------[] | 3077 | | []<--------[] | | 3078 | | [] | | | 3079 | | [Build bootstrap image] | | | 3080 | | [] | | | 3081 | | [] POST ?/bootstrap | | 3082 | | []-------->[] | | 3083 | | [] []SetDeviceBootstrap() | 3084 | | [] []----------->[] | 3085 | | [] [] []GetDeviceOwner() 3086 | | [] [] []----------->[] 3087 | | [] [] [] [Mgmt B] [] 3088 | | [] [] ACK []<-----------[] 3089 | | [] 200 OK []<-----------[] | 3090 | | []<--------[] | | 3091 [wakes up] | | | | | 3092 | | | | | | 3093 [] | | | | | 3094 []-----------GET /v1/devices//bootstrap---->[] | 3095 [] | | | [] | 3096 []<-----------------------[image]-----------------[] | 3097 [] | | | | | 3098 [Validate and decrypt bootstrap data] | | | 3099 [] | | | | | 3100 [Apply bootstrap data] | | | | 3101 [] | | | | | 3102 []-PUT ?/info----------->[] | | | 3103 [] | [] | | | 3104 [] [data] [] | | | 3105 []<--------------------->[] | | | 3106 | | | | | | 3108 ?/ is /v1/devices// 3109 Device Change of Ownership 3110 Change the management system authorized for the device 3112 Device Change Owner Sequence Diagram (second part) 3114 15. Configuration and Bootstrap Data Formats 3116 15.1. Overview 3118 The bootstrap data is critical to the device to determine 3119 ownership and allow authentication of the management system. 3120 Additional parameters may be provided to the device as part of the 3121 bootstrap data. The Management System uploads the bootstrap data 3122 for a device to the bootstrap server so that the bootstrap server 3123 can be provide it to the device during the bootstrap sequence. he 3124 Management System therefore encrypts the bootstrap data so that 3125 only the target device can decode it (in the case of shared secret 3126 devices, the Identity Service is also theoretically capable of 3127 this decryption). This protects the data from exposure should the 3128 bootstrap server be compromised. 3130 The Management System needs to know what information the device 3131 needs to complete its bootstrap and it requests this in the 3132 request defined in 9.3.6. above. 3134 15.2. Configuration data format 3136 The configuration data for a device provides the manufacturing 3137 data for the device and information about the key to use to 3138 encrypt the bootstrap data. The data is in JSON format as below: 3139 { 3140 "device": { 3141 "id": "", 3142 "bootstrap_server": , 3143 "capabilities": { // Device bootstrap capabilities 3144 "ec_capable": , 3145 "rsa_capable": , 3146 "sha384_capable": , 3147 "sha512_capable": , 3148 "aes256_capable": , 3149 // Additional capabilities may be added in the future 3150 }, 3151 }, 3152 "authenticated_keys": [ 3153 // Array of base-64 encoded key identity strings as in 3154 // 7.4. above 3155 ], 3156 "owner_information": "", 3158 "parameter_choices": [ 3159 // List of sets of parameter choices. The Management 3160 // System should provide exactly one of the sets of 3161 // parameters, but it may choose to provide a different 3162 // parameter set if it has additional information about 3163 // what the device can support. 3164 ], 3165 } 3166 The format of the "parameter_choices" array depends on the types 3167 of messages that are required by the device. The exact format is 3168 TBD at this time. 3170 15.3. Device connection to the bootstrap server using DTLS using 3171 pre-shared secrets 3173 The array of "authenticated_keys" provided in the configuration 3174 data will include a bootstrap server key. This key and all keys 3175 that it relies on to derive it from the device key must be 3176 provided to the device by the bootstrap server during the DTLS 3177 handshake so that the device can establish the DTLS connection. 3178 The bootstrap service in the Trusted Authority will do this 3179 automatically. If a bootstrap service is used within the Walled 3180 Garden, it must be careful to include all these keys in the 3181 correct order (from device key to bootstrap server) so that the 3182 device can derive the key necessary for the DTLS session. 3184 15.4. Device connection to the bootstrap server using DTLS using 3185 public keys 3187 There is a special requirement for the device behaviour when 3188 establishing the DTLS connection to the bootstrap server. The DTLS 3189 handshake (with extensions as in RFC-7250 allowing raw public 3190 keys) uses public keys rather than certificates, so the device 3191 cannot authenticate the bootstrap server key during the DTLS 3192 handshake. 3194 The device must therefore temporarily accept the public key from 3195 the bootstrap server during the DTLS handshake and download the 3196 bootstrap data. The device must then check that the public key 3197 from the bootstrap server is in the list of identities in the 3198 bootstrap and that it has the "Bootstrap Service" identity class. 3200 Once the identity of the bootstrap server has been confirmed, 3201 validation of the bootstrap data can continue. If the identity of 3202 the bootstrap server cannot be confirmed, the bootstrap data 3203 should be discarded. 3205 15.5. Bootstrap data format 3207 The bootstrap data is constructed by the management system based 3208 on the configuration data and the additional information that the 3209 management system needs to provide. 3211 The bootstrap data is in CBOR format comprises three sections - a 3212 header, the encrypted content and the signature. The header 3213 includes one or more authenticated keys and the owner information. 3214 All authenticated keys in the configuration data must be included 3215 in the authenticated key list in the order provided. The 3216 management system may then append additional keys if it wishes. 3218 The order is important because the device will validate and import 3219 the authenticated keys in the order provided. If a key is invalid 3220 or depends on a key that is not yet imported, the bootstrap data 3221 will be rejected. 3223 The owner information tells the device the number of owners the 3224 device has had. This number starts at zero and is incremented each 3225 time the owner changes. The device must store this number in non 3226 volatile memory and only accept bootstrap data if the owner 3227 sequence_number in the bootstrap data is the same or higher than 3228 the owner_sequence_number stored in non-volatile memory. This 3229 prevents replay attacks of older owner data in an attempt to 3230 reclaim ownership of a device. The owner data must be signed by a 3231 manufacturer or registration identity as defined in 7.7. above. 3233 ARRAY { 3234 // One or more authenticated key definitions in 7.4. above 3235 ARRAY { 3236 ... // Authenticated key definition 3237 } 3239 // Owner information 3240 ARRAY { 3241 INTEGER content //"Owner Content Type" as in 7.5. above 3242 INTEGER owner_sequence_number 3243 ARRAY { 3244 // Signature for owner data, provided by bootstrap 3245 // server as in 7.3. above 3246 } 3247 } 3248 // End of owner information 3250 // Start of encryption information 3251 BYTE STRING decryption_key_id // Key UUID 3252 BYTE STRING encrypted_payload 3254 // Signature for the entire bootstrap data 3255 ARRAY { 3256 // Signature as in 7.3. above, signed by Management 3257 // Systems key 3258 // Signature covers ENCRYPTED payload, so signature 3259 //.validation is done before decryption 3260 } 3261 } 3263 15.5.1. Payload protected by Elliptic Curve keys 3265 If the decryption key refers to an Elliptic Curve key, the 3266 encrypted_payload is a Cryptographic Message Syntax object 3267 containing an enveloped-data block (see RFC 5652 and RFC 5753). 3268 The enveloped-data should be encrypted using the "Standard" 3269 variation of Ephemeral Static ECDH (see RFC 5753 section 3.1). The 3270 default choices for encryption cipher and hash function should be 3271 AES-128 and SHA-256 respectively. 3273 The "enveloped-data", after decryption, contains the payload CBOR 3274 structure as defined in 15.5.4. below. 3276 15.5.2. Payload protected by RSA keys 3278 If the decryption key refers to an RSA key, then the 3279 encrypted_payload is a Cryptographic Message Syntax object 3280 containing an enveloped-data block (see RFC 5652). 3282 The enveloped-data should be encrypted using RSAES-OAEP (see RFC 3283 8017 section 7.1). The default choices for encryption cipher and 3284 hash function should be AES-128 and SHA-256 respectively. 3285 The SHA-1 hash should NOT be used. 3287 The "enveloped-data", after decryption, contains the payload CBOR 3288 structure as defined in 15.5.4. below. 3290 15.5.3. Payload protected by shared secrets 3292 If the decryption key refers to a shared secret then the 3293 encrypted_payload contains the CBOR structure below. The salt, 3294 iterations_or_cipher and encrypted_secret fields are used to 3295 derive a decryption key for the cipher in the same way as a 3296 derived secret is obtained in section 7.2. above. This key is 3297 then used with the indicated cipher_suite with the cipher_IV and 3298 optional tag to decrypt the encrypted_data. 3300 ARRAY { 3301 BYTE STRING salt 3302 INTEGER iterations_or_cipher 3303 BYTE_STRING encrypted_secret 3304 INTEGER cipher_suite // As in 7.8. above 3305 BYTE STRING cipher_IV 3306 BYTE STRING tag // Zero length for CBC ciphers 3307 BYTE STRING encrypted_data 3308 } 3310 The "encrypted_data", after decryption, contains the payload CBOR 3311 structure as defined in 15.5.4. below. 3313 15.5.4. Decrypted payload content 3315 The payload has the following CBOR format: 3316 ARRAY { 3317 BYTE STRING coap_message0 3318 BYTE STRING coap_message1 3319 ... 3320 BYTE STRING coap_messageN 3321 } 3322 Each message is replayed to the local API in the order in the 3323 payload. 3325 If the device requires configuration messages to be replayed to a 3326 different API, a local API function should be created that 3327 understands how to replay the message content to the other API. 3328 E.g. replay of a BACnet APDU to the local device. 3330 16. Security Considerations 3332 This whole draft concerns security considerations. See Chapter 6. 3334 17. IANA Considerations 3336 None 3338 18. Conclusions 3340 End to end certificate handling and encrypted communication using 3341 "channels" within the DTLS framework can easily be achieved 3342 without inventing new standards, just by enhancing current ones. 3343 This covers devices from high end servers down to resource 3344 constrained devices across different types of network. 3346 The underlying standards are: 3348 Transport Layer Security, TLS v1.2, RFC-5246 3349 Datagram Transport Layer Security, DTLS v1.2, RFC-6347 3350 Constrained Application Framework, CoAP, RFC-7252 3351 Concise Binary Object Representation, CBOR, RFC-7049 3352 CoAP Block-wise Transfers, https://www.ietf.org/id/draft-ietf 3353 core-block-21.txt 3355 The aSSURE specification lends itself to the industrial 3356 manufacture and distribution of IoT and other connected pieces of 3357 equipment and can serve many markets both in retrofit and new 3358 build. Indeed IoT is currently disgorging millions of devices in 3359 architectures that are not secure enough and could be repaired 3360 using the aSSURE framework and philosophy. This problem is better 3361 described by Bob Hinden in his paper "Internet of Insecure Things" 3362 published in the Internet Protocol Journal. 3364 19. References 3366 19.1. Normative References 3368 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3369 Requirement Levels", BCP 14, RFC 2119, March 1997. 3371 [RFC4279] Eronen, P., Ed., and H. Tschofenig, Ed., "Pre-Shared Key 3372 Ciphersuites for Transport Layer Security (TLS)", RFC4279, DOI 3373 10.17487/RFC4279, December 2005, . 3376 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer 3377 Security (TLS) Protocol Version 1.2", RFC 5246, DOI 3378 10.17487/RFC5246, August 2008, . 3381 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 3382 70, RFC 5652, DOI 10.17487/RFC5652, September 2009, 3383 . 3385 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3386 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 3387 2012, . 3389 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3390 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 3391 2013, . 3393 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 3394 Weiler, S., and T. Kivinen, "Using Raw Public Keys in Transport 3395 Layer Security (TLS) and Datagram Transport Layer Security 3396 (DTLS)", RFC 7250, DOI 10.17487/RFC7250, June 2014, 3397 . 3399 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3400 Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 3401 2014, . 3403 19.2. Informative References 3405 CoAP Block-wise Transfers, https://www.ietf.org/id/draft-ietf 3406 core-block-21.txt 3408 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 3409 Specification Version 2.0", RFC 2898, DOI 10.17487/RFC2898, 3410 September 2000, . 3412 [RFC5753] Turner, S. and D. Brown, "Use of Elliptic Curve 3413 Cryptography (ECC) Algorithms in Cryptographic Message Syntax 3414 (CMS)", RFC 5753, DOI 10.17487/RFC5753, January 2010, 3415 . 3417 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 3418 Constrained-Node Networks", RFC 7228, DOI 10.17487/RFC7228, May 3419 2014, . 3421 "Internet of Insecure Things", Hinden, B., Internet Protocol 3422 Journal March 2017 Vol 20, Number 1, Page 12. 3423 . 3426 20. Acknowledgments 3428 This document is a byproduct of the "aSSURE" project, partially 3429 funded by Innovate UK. It is provided "as is" and without 3430 any express or implied warranties, including, without limitation, 3431 the implied warranties of fitness for a particular purpose. The 3432 views and conclusion contained herein are those of the authors and 3433 should not be interpreted as necessarily representing the official 3434 policies or endorsements, either expressed or implied, of the 3435 aSSURE project or Innovate UK. 3437 Author's Address 3439 Roger Lucas 3440 c/o Cisco International Limited 3441 10, New Square Park 3442 Bedfont Lakes 3443 Feltham 3444 TW14 8HA 3445 United Kingdom 3446 Email: iot@hiddenengine.co.uk