idnits 2.17.1 draft-richardson-anima-smarkaklink-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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-anima-bootstrapping-keyinfra]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 11, 2019) is 1870 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '14' on line 868 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-18 -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 6tisch Working Group M. Richardson 3 Internet-Draft Sandelman Software Works 4 Intended status: Informational J. Latour 5 Expires: September 12, 2019 CIRA Labs 6 F. Khan 7 A. Joshi 8 Twelve Dot Systems 9 March 11, 2019 11 BRSKI enrollment of with disconnected Registrars -- smarkaklink 12 draft-richardson-anima-smarkaklink-00 14 Abstract 16 This document details the mechanism used for initial enrollment using 17 a smartphone of a BRSKI Registrar system. 19 There are two key differences in assumption from 20 [I-D.ietf-anima-bootstrapping-keyinfra]: that the intended registrar 21 has Internet, and that the Pledge has no user-interface. 23 This variation on BRSKI is intended to be used in the situation where 24 the registrar device is new out of the box and is the intended 25 gateway to the Internet (such as a home gateway), but has not yet 26 been configured. This work is also intended as a transition to the 27 Wi-Fi Alliance work on the Device Provisioning Protocol (DPP). 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on September 12, 2019. 46 Copyright Notice 48 Copyright (c) 2019 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (https://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Intermittent Device connectivity . . . . . . . . . . . . 4 65 1.2. Additional Motivation . . . . . . . . . . . . . . . . . . 4 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 2.1. History and Origin of the name . . . . . . . . . . . . . 6 68 3. Requirements Language . . . . . . . . . . . . . . . . . . . . 6 69 4. Assumptions and Required Setup . . . . . . . . . . . . . . . 6 70 5. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 71 5.1. Scan the QR code . . . . . . . . . . . . . . . . . . . . 7 72 5.2. Enroll with the manufacturer . . . . . . . . . . . . . . 7 73 5.3. Connect to BRSKI join network . . . . . . . . . . . . . . 7 74 5.4. Connect to Adolescent Registrar (AR) . . . . . . . . . . 8 75 5.5. Pledge Requests Voucher-Request from the Adolescent 76 Registrar . . . . . . . . . . . . . . . . . . . . . . . . 8 77 5.6. AR processing of voucher-request, request. . . . . . . . 9 78 5.6.1. Additions to Voucher-Request . . . . . . . . . . . . 9 79 5.7. Smartphone validates connection . . . . . . . . . . . . . 9 80 5.8. Smart-Phone connects to MASA . . . . . . . . . . . . . . 10 81 5.9. MASA processing . . . . . . . . . . . . . . . . . . . . . 10 82 5.10. Smartpledge processing of voucher . . . . . . . . . . . . 10 83 5.11. Adolescent Registrar (AR) receives voucher . . . . . . . 11 84 5.12. Adolescent Registrar (AR) grows up . . . . . . . . . . . 11 85 5.13. Smartphone enrolls . . . . . . . . . . . . . . . . . . . 11 86 5.14. Validation of connection . . . . . . . . . . . . . . . . 12 87 6. Protocol Details . . . . . . . . . . . . . . . . . . . . . . 12 88 6.1. Quick Response Code (QR code) . . . . . . . . . . . . . . 12 89 6.1.1. The Smarkaklink Attribute . . . . . . . . . . . . . . 13 90 6.1.2. Link-Layer Address Attribute . . . . . . . . . . . . 13 91 6.1.3. ESSID Name Attribute . . . . . . . . . . . . . . . . 14 92 6.2. Enrollment using EST . . . . . . . . . . . . . . . . . . 14 93 7. Smart Pledge enrollment with manufacturer . . . . . . . . . . 14 94 7.1. minimal Smart Pledge enrollment . . . . . . . . . . . . . 16 95 8. Threat Analysis . . . . . . . . . . . . . . . . . . . . . . . 16 96 8.1. Wrong Administrator . . . . . . . . . . . . . . . . . . . 16 97 8.2. Rogue Administrator . . . . . . . . . . . . . . . . . . . 16 98 8.3. Attack from Internal device . . . . . . . . . . . . . . . 16 99 8.4. Attack from camera enabled robot . . . . . . . . . . . . 16 100 8.5. Attack from manipulator enabled robot . . . . . . . . . . 17 101 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 102 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 103 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 104 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 105 12.1. Normative References . . . . . . . . . . . . . . . . . . 17 106 12.2. Informative References . . . . . . . . . . . . . . . . . 18 107 Appendix A. Resulting DPP QR code specification . . . . . . . . 18 108 Appendix B. Swagger.IO definition of API . . . . . . . . . . . . 19 109 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 111 1. Introduction 113 The problem of bootstrapping a new device is described at length in 114 [I-D.ietf-anima-bootstrapping-keyinfra] (aka BRSKI). The problem 115 that BRSKI solves is the case of a smart, properly configured network 116 with a minimum of network connectivity (or previously pre-previoned 117 with nonceless vouchers), and a relatively stupid new device (the 118 Pledge), which lacks a user interface. 120 The BRSKI problem is one of trust: how does the new device trust that 121 it has found the correct network to join, and how does the new 122 network become convinced that the new device is a device that is 123 intended to join. BRSKI solves the problem well for the case where 124 the network is well connected and can easily talk to the device's 125 Manufacturer Authorized Signing Authority (MASA), while providing 126 appropriate proxy mechanisms to enable the new pledge to communicate 127 it's proximity assertion to the MASA as well. 129 This document is about a variation of the problem: when the new 130 device being introduce has no network connectivity, but a new device 131 is intended to serve as the Registrar for the network. This new 132 device is likely a home (or small office) gateway, and until it is 133 properly configured there will be no direct network connectivity. 135 There are a number of protocols that permit an ISP to consider a new 136 router brought into a home to be a new pledge to the ISPs' network, 137 and for that new device to integrated into the ISP's (autonomic) 138 network. BRSKI can be used itself, and there are ways to use the 139 Broadband Form's TR-069 to bootstrap the device in this way. This 140 document is not about the situation where the router device is 141 intended to belong to the ISP, but about the situation where the home 142 user intends to own and control the device. 144 1.1. Intermittent Device connectivity 146 There is an additional variation which this variation solves: the 147 case where there is one or more devices in a place with no immediate 148 connectivity to a Registrar. An example of this could be a new home 149 construction where a furnace, thermostat or other control systems 150 need to be introduced to each other. If a registrar exists it will 151 have no Internet connectivity (as above), until the home becomes 152 owned by the first owner. There might never be a registrar though. 154 The basement case is important because the assumption is that the 155 _installer_ may have poor or no LTE connectivity in that location. 156 The installer will have to exit the basement, perhaps even return to 157 their truck, in order to have network connectivity for their 158 provisioning device (a smartphone equivalent). 160 1.2. Additional Motivation 162 The Wi-Fi Alliance has released the Device Provisioning Protocol 163 [dpp]. The specification is available only via "free" registation. 164 The specification relies on being able to send and receive 802.11 165 Public Action frames, as well as Generic Advertisement Service (GAS) 166 Public Action frames. Access to send new layer-2 frames is generally 167 restricted in most smartphone operating systems (iOS, Android). At 168 present there are no known public APIs that a generic application 169 writer could use, and therefore the smart-phone side of the DPP can 170 only be implemented at present by the vendors of those operating 171 systems. 173 As both dominant vendors have competing proprietary mechanisms, it is 174 unclear if generic applications will be produced soon. It is 175 probably impractical for a vendor an a smart-appliance to 176 independantly produce an application that can do proper DPP in 2019. 177 As one of the common goals of this document and DPP is that there 178 need not be an application-per-device only one DPP application need 179 exist. Until such time as such an application becomes universal it 180 is a goal of this document to lay the groundwork for a transition to 181 full use of DPP by leveraging the QR code infrastructure that DPP 182 depends upon. 184 In addition to the above concern, DPP is primary concerned about 185 provisioning WiFi credentials to devices. DPP can provision access 186 points themselves, but it lacks any kind of manufacturer integration. 187 BRSKI provides this integration, and therefore an audit trail history 188 for the device. 190 The smarkaklink enrollment process described in this document is 191 about securely initializing the administrative connection with a 192 device that is the WiFi Access Point. 194 2. Terminology 196 The following terminology is copied from 197 [I-D.ietf-anima-bootstrapping-keyinfra] 199 enrollment: The process where a device presents key material to a 200 network and acquires a network specific identity. For example when a 201 certificate signing request is presented to a certification authority 202 and a certificate is obtained in response. 204 pledge: The prospective device, which has an identity installed at 205 the factory. 207 IDevID: a manufacturer signed keypair (different from the QRkey) 208 which is generated at the factory. This is the 802.1AR artifact 209 which is mandated by [I-D.ietf-anima-bootstrapping-keyinfra]. 211 The following new terminology has been added 213 smarkaphone: The prospective administrator device, usually a 214 smartphone equipped with a QR capable camera, wifi and 3G 215 connectivity. 217 adolescent router (AR): a home router or device containing a 218 registrar. The device does not yet have network connectivity, and 219 has no administrator. It is considered not a "baby" device in the 220 same way that the pledge is, but it is not yet an adult. A better 221 term would be welcome. 223 SelfDevID: a public/private key pair generated by the smartpledge, 224 formed into a self-signed PKIX certificate. The private key part 225 remains always on the smartpledge, but like other secondary device 226 keys, should be encrypted for backup purposes. {EDNOTE: any 227 references to Apple or Android APIs/specifications here?} 229 QRkey: a unique, raw ECDSA or EdDSA key pair generated in (or for) 230 the adolescent router at the factory, and stored in the 231 configuration portion of the firmware. The public portion is 232 printed in a QRcode. This key is not formed into a certificate of 233 any kind. 235 smarkaklink: the name of this protocol. 237 adolescent router (AR): a home router or device containing a 238 registrar. The device does not yet have network connectivity, and 239 has no administrator. 241 2.1. History and Origin of the name 243 This document was originally called the "smartpledge" variation of 244 BRSKI. This name was intended to indicate that the variation is one 245 where the BRSKI role of Pledge is taken on by the smartphone device. 247 While the end-goal is to have the smartphone enrolled into a PKI 248 hosted by the fully-grown Router, the activities of each device do 249 not map into the BRSKI roles at the beginning. In fact, they are 250 reversed with the Adolescent Router being the Pledge. Review of this 251 document suggested that removing the word pledge would help. 253 The new name "smarkaklink" is intended to sound like the sound that 254 two (wine, beer) glasses make after a toast is made. 256 3. Requirements Language 258 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 259 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 260 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 261 [RFC2119] and indicate requirement levels for compliant STuPiD 262 implementations. 264 4. Assumptions and Required Setup 266 The first assumption is that intended device owner is active and is 267 present. The device owner has a smart-phone that is capable of using 268 Wi-Fi or being wired into the adolescent router (AR). 270 The smartpledge application generates a self-signed certificate with 271 public/private keypair that it knows. It may generate a unique 272 certificate for each manufacturer. This certificate is called the 273 SelfDevID. 275 The second assumption is that the device has a QR code printed on the 276 outside of the unit, and/or provided with the packaging/ 277 documentation. The QR code is as specified in section 5.3 of [dpp], 278 with the additions specified in Section 6.1 280 The third assumption is that the AR, at manufacturing time, has the 281 anchor for it's MASA (same assumption as for BRSKI pledge's). In 282 addition, like the BRSKI pledge, the AR has an IDevID certificate 283 (and associated private key) signed by the manufacturer. 285 The fourth assumption is that the key in the "K:" attribute 286 Section 6.1 is a different public key pair. It MUST be different 287 from the key used in the IDevID. This key is called the DPP-Keypair. 289 5. Protocol Overview 291 This is the overview of the process. {EDNOTE: there are many details 292 here that belong in the next section. The goal in this section is to 293 consisely explain the interaction among the components. Clearly this 294 text currently fails in that regard} 296 5.1. Scan the QR code 298 The operator of the smartphone invokes the smarkaklink application, 299 and scans the QR code on the AR. The smartphone learns the ESSID, 300 Public-Key, mac-address, smarkaklink URL, and link-local address of 301 the AR. 303 5.2. Enroll with the manufacturer 305 The smartphone uses it's 3G, or other WiFi internet access to connect 306 to the manufacturer with TLS. The manufacturer is identified with 307 the smartpledge URL. 309 The operator of the smartphone may need to move to another location 310 to get connectivity. It is desireable that an operator be able to 311 scan many QR codes before moving, performing this operation in a 312 batch. There may be multiple devices from the same manufacturer, and 313 the smarkalink application SHOUld enroll with the manufacturer a 314 single time for all devices. 316 The smartphone does an HTTP POST to the provided URL using it's 317 generated certificate as it's ClientCertificate. As described in 318 Section 7, the manufacturer MAY respond with a 302 result code, and 319 have the end user go through a web browser based process to enroll. 320 After that process, a redirection will occur using OAUTH2. 322 The result should finally be a 201 result code, and at that URL is a 323 new certificate signed by the manufacturer. 325 5.3. Connect to BRSKI join network 327 The application then reconnects the Wi-Fi interface of the smartphone 328 to the ESSID of the AR. This involves normal 802.11 station 329 attachment. The given ESSID explicitely has no WPA or other security 330 required on it. 332 There will be no DHCPv4 on this network. This simplifies the 333 operation of the devices that are enrolling, but it also makes the 334 network uninteresting to other random users that may stumble upon the 335 open ESSID. 337 A IPv6 Router Solicitation may elicit an answer (confirming the 338 device is there), but it is acceptable for there to be no prefix 339 information. An IPv6 Neighbour Discovery is done for the IPv6 Link- 340 Local address of the AR. Receipt of an answer confirms that the 341 ESSID is correct and present. 343 (XXX - not using GRASP here. Could use GRASP, but QR code is better) 345 5.4. Connect to Adolescent Registrar (AR) 347 The smarkaklink application then makes a direct (no proxy) TLS 348 connection to port 8443 (!XXX!) of the AR, on the IPv6 Link-Local 349 address given. This is as in section 5.1 of 350 [I-D.ietf-anima-bootstrapping-keyinfra]. The smartphone uses it's 351 SelfDevID as the TLS ClientCertificate, as the smartphone and 352 smarkaklink will not have a manufacturer signed IDevID. 354 Additionally, the AR will use it's IDevID certificate as the 355 ServerCertificate of the TLS conncetion. As with other BRSKI IDevID, 356 it will have a MASA URL extension, as described in 357 [I-D.ietf-anima-bootstrapping-keyinfra] section 2.3.2. 359 The Adolescent Registrar acts in the role of pledge! 361 5.5. Pledge Requests Voucher-Request from the Adolescent Registrar 363 The smartphone generates a random nonce _SPnonce_. To this is added 364 SOMETHING-that-is-time-unique, to create a _voucher-request 365 challenge_. This is placed in the voucher-challenge-nonce field. 367 Using the public-key of the AR that was scanned from the QR code, the 368 smartphone encrypts the challenge using CMS (or COSE?). 370 NOTE: DPP has a round with the SHA256 of the device's key to make 371 sure that the correct device has been chosen. The TLS connection 372 effectively provides the same privacy that the Bx keys provided. 374 The resulting object is POST'ed to the new BRSKI endpoint: 376 /.well-known/est/requestvoucherrequest 378 [or should it be named: /.well-known/est/requestvoucherchallenge 379 ] 381 5.6. AR processing of voucher-request, request. 383 The AR processes this POST. First it uses the private key that is 384 associated with it's QR printed public key to decrypt the voucher- 385 request challenge. Included in this challenge is a nonce, and also 386 the link-local address of the smartphone. 388 The AR SHOULD verify that the link-local address matches the 389 originating address of the connection on which the request is 390 received. 392 The AR then forms a voucher-request identically to as described in 393 section 5.2 of [I-D.ietf-anima-bootstrapping-keyinfra]. Note that 394 the AR uses it's IDevID to sign the voucher-request. This is the 395 same key used to terminate the TLS connection. 397 Note: It MUST be different from the public key printed in the QR 398 code. 400 In addition to the randomly generated nonce that the AR generates to 401 place in the the voucher-request, into the nonce field, it also 402 includes the _SPnonce_ in a new _voucher-challenge-nonce_ field. 403 {EDNOTE: hash of nonce?} 405 This voucher-request is then _returned_ during the POST operation to 406 the smartphone. (This is in constrast that in ANIMA the voucher- 407 request is sent by the device to the Registrar, or the MASA) 409 5.6.1. Additions to Voucher-Request 411 QUESTION: should the _voucher-challenge-nonce_ be provided directly 412 in the voucher-request, or should only a hash of the nonce be used? 413 The nonce is otherwise not disclosed, and a MITM on the initial TLS 414 connection would get to see the nonce. A hash of the nonce validates 415 the nonce as easily. 417 5.7. Smartphone validates connection 419 The smartphone then examines the resulting voucher-request. The 420 smartphone validates that the voucher-request is signed by the same 421 public key as was seen in the TLS ServerCertificate. 423 The smartphone then examines the contents of the voucher-request, and 424 looks for the _voucher-challenge-nonce_. As this nonce was encrypted 425 to the AR, the only way that the resulting nonce could be correct is 426 if the correct private key was present on the AR to decrypt it. 428 Succesful verification of the _voucher-challenge-nonce_ (or the hash 429 of it, see below) results in the smartphone moving it's end of the 430 connection from provisional to validated. 432 5.8. Smart-Phone connects to MASA 434 The smarkaklink application running on the smartphone then examines 435 the MASA URL provided in the TLS ServerCertificate of the AR. The 436 smarkaklink application then connects to that URL using it's 3G/LTE 437 connection, taking on the temporary role of Registrar. 439 A wrapped voucher-request is formed by the smartphone in the same way 440 as described in section 5.4 of 441 [I-D.ietf-anima-bootstrapping-keyinfra]. The prior-signed-voucher- 442 request is filled in with the voucher-request that was created by the 443 AR in the previous step. 445 The proximity-registrar-cert of the wrapped voucher-request is set to 446 be the SelfDevID certificate of the smartphone. The voucher-request 447 is to be signed by the SelfDevID. 449 The voucher-request is POST'ed to the MASA using the same URL that is 450 used for Registrar/MASA operation: 452 /.well-known/est/requestvoucher 454 5.9. MASA processing 456 The MASA processing occurs as specified in section 5.5 of 457 [I-D.ietf-anima-bootstrapping-keyinfra] as before. The MASA MUST 458 also copy the _voucher-challenge-nonce_ into the resulting voucher. 460 5.10. Smartpledge processing of voucher 462 The smartphone will receive a voucher that contains it's IDevID as 463 the _pinned-domain-cert_, and the _voucher-challenge-nonce_ that it 464 created will also be present. The smartphone SHOULD verify the 465 signature on the artifact, but may be unable to validate that the 466 certificate used has a relationship to the TLS ServerCertificate used 467 by the MASA. (This limitation exists in ANIMA as well). 469 The smartphone will then POST the resulting voucher to the AR using 470 the URL 472 /.well-known/est/voucher 474 If an existing TLS connection is still available, it MAY be reused. 476 If a TLS session-resumption ticket (see [RFC8446] section 2.2 for TLS 477 1.3, and [RFC5077] for TLS 1.2) has been obtained, it SHOULD be used 478 if the TLS connection needs to be rebuilt. This is particularly 479 useful in the disconnected use case explained in Section 1.1. 481 5.11. Adolescent Registrar (AR) receives voucher 483 When the AR receives the voucher, it validates that it is signed by 484 it's manufacturer. This process is the same as section 5.5.1 of 485 [I-D.ietf-anima-bootstrapping-keyinfra]. 487 Again note that the AR is acting in the role of a pledge. 489 Inside the voucher, the pinned-domain-cert is examined. It should 490 match the TLS ClientCertificate that the smartphone used to connect. 491 This is the SelfDevID. 493 At this point the AR has validated the identity of the smartphone, 494 and the AR moves it's end of the connection from provisional to 495 validated. 497 5.12. Adolescent Registrar (AR) grows up 499 The roles are now changed. 501 If necessary, the AR generates a new key pair as it's Domain CA key. 502 It MAY generate intermediate CA certificates and a seperate Registrar 503 certificate, but this is discouraged for home network use. 505 The AR is now considered a full registrar. The AR now takes on the 506 role of Registrar. 508 5.13. Smartphone enrolls 510 At this stage of the smarkaklink protocol, the typical BRSKI exchange 511 is over. A Secure Transport has been established between the 512 smartphone and the fully-grown AR. The smartphone now takes on the 513 role of secured pledge, or EST client. 515 The smartphone MUST now request the full list of CA Certificates, as 516 per [RFC7030] section 4.1. As the Registrar's CA certificate has 517 just been generated, the smartphone has no other way of knowing it. 519 The smartphone MUST now also generate a CSR request as per 520 [I-D.ietf-anima-bootstrapping-keyinfra] section 5.8.3. The 521 smartpledge MAY reuse the SelfDevID key pair for this purpose. (XXX 522 - maybe there are good reasons not to reuse?) 523 The Registrar SHOULD grant administrator privileges to the smartphone 524 via the certificate that is issued. This may be done via special 525 attributes in the issued certificate, or it may pin the certificate 526 in a database. Which method to use is a local matter. 528 The TLS/EST connection MUST remain open at this point. This is 529 connection one. 531 5.14. Validation of connection 533 The smartphone MUST now open a new HTTPS connection to the Registrar 534 (AR), using it's newly issued certificate. (XXX should this be on a 535 different IP, or a different port? If so, how is this indicated?) 537 The smartphone MUST validate that the new connection's TLS Server 538 certificate can be validated by the Registrar's new CA certificate. 540 The registrar MUST validate that the smartphone's ClientCertificate 541 is validated by the Registrar's CA. The smartphone SHOULD perform a 542 POST operation on this new connection to the 543 [I-D.ietf-anima-bootstrapping-keyinfra] Enrollment Status Telemetry 544 mechanism, see section 5.8.3. 546 Upon success, the original TLS/EST connection (one) MAY now be 547 closed. 549 Should the validations above fail, then the original EST connection 550 MUST be used to GET a value from the 552 /.well-known/est/enrollstatus 554 from the Registrar. The contents of this value SHOULD then be sent 555 to the MASA, using a POST to the enrollstatus, and including the 556 reply from the AR in a new attribute, "adolescent-registrar-reason". 558 6. Protocol Details 560 6.1. Quick Response Code (QR code) 562 Section 5.3 of [dpp] describes the contents for an [iso18004] image. 563 It specifies content that starts with DPP:, and the contains a series 564 of semi-colon (;) deliminated section with a single letter and colon. 565 This markup is terminated with a double semi-colon. 567 Although no amending formula is defined in DPP 1.0, this document is 568 defining two extensions. This requires amending the ABNF from 569 section 5.2.1 as follows: 571 dpp-qr = "DPP:" [channel-list ";"] [channel-list ";"] 572 [mac ";"] [information ";"] public-key 573 [";" llv6-addr ] [";" mudurl ] 574 [";" smarkaklink ] [";" essid ] ";;" 575 llv6-addr = "L:" 8*hex-octet 576 essid = "E:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 577 smarkaklink = "S:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 578 mudurl = "D:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 580 While the ABNF defined in the [dpp] document assumes a specific order 581 (C:, M:, I:, K:), this specification relaxes this so that the tags 582 can come in any order. However, in order to make interoperation with 583 future DPP-only clients as seamless as possible, the extensions 584 suggested here are placed at the end of the list. This is consistent 585 with the Postel Principle. 587 It is intended that parts of this protocol could be performed by an 588 actual DPP implementation, should it become possible to implement DPP 589 using current smartphone operating systems in an unprivileged way. 591 6.1.1. The Smarkaklink Attribute 593 The _smarkaklink_ attribute indicates that the device is capable of 594 the protocol specified in this document. The contents of the 595 smarkaklink attribute contains part or all of an IRI which identifies 596 the manufacturer of the device. 598 It SHOULD contain the _iauthority_ of an IRI as specified in section 599 2.2 of [RFC3987]. The scheme is implicitely "https://", with an 600 ipath of "/.well-known/est/smarkaklink". This implicit form exists 601 to save bytes in the QR code. 603 If the string contains any "/" characters, then it is not an 604 _iauthority_, but an entire IRI. This takes many more characters, 605 but is useful in a variety of debugging situations, and also provides 606 for new innovations. 608 Short URLs are important to fit into typical QR code space. 610 6.1.2. Link-Layer Address Attribute 612 The _llv6-addr_ attribute is optional. When present, it specifies 613 the IPv6 Link-Local address at which the adolescent router is 614 listening. If not specified, then the link-local address may be 615 formed according to the historical (privacy-violating) process 616 described in [RFC4291] Appendix A. The _llv6-addr_ attribute is 617 present so that devices that have implemented [RFC7217] stable 618 addresses can express that address clearly. 620 6.1.3. ESSID Name Attribute 622 The _essid_ attribute provides the name of the 802.11 network on 623 which the enrollment will occur. If this attribute is absent, then 624 it defaults to "BRSKI". 626 6.2. Enrollment using EST 628 TBD 630 7. Smart Pledge enrollment with manufacturer 632 While it is assumed that there will be many makers of Smarkaklink 633 applications, a goal of this specification is to eliminate the need 634 for an "app" per device, providing onboarding mechanism for a variety 635 of devices from a single app. 637 Given the secondary goal of a transition to use of Device 638 Provisioning Protocol (DPP), the smarkaklink application may have to 639 be provided as part of the smart phone system, as a system service. 640 This is due to the need to send/receive wifi management frames from 641 DPP. As such each vendor of a smart device will need to produce a 642 smarkaklink app, and it will be impossible for the vendor of the 643 Registrar device (or other DPP capable IoT device) to provide an app 644 on their own. 646 Having stated this goal, it is understood that initially the app may 647 well come from the manufacturer of the Registrar, but this protocol 648 is designed on the assumption that there is no such vertical 649 integration. 651 So, there can be no initial relationship between the Smart Pledge and 652 the manufacturer of the Registrar. 654 But, in a traditional [I-D.ietf-anima-bootstrapping-keyinfra] 655 scenario the pledge would have been provided with an IDevID at 656 manufacturing time. While an IDevID could have been built-in to the 657 SmartPledge "app", such a key would not be private if it was built- 658 in. A key could be generated by the app upon installation. It could 659 be self-signed, it could be signed by the maker of the app, or it 660 could be signed by another party. 662 o a self-signed certificate is just a container for a public key. 663 For the purposes of the trust relationship with the Registrar, it 664 would be sufficient. 666 o a certificate signed by the maker of the app (or the maker of the 667 smart-phone) would carry no specific trust beyond what a self- 668 signed certificate would have. Any linking in the certificate to 669 a network expressable identity (such as layer-2 address) would 670 simply be a privacy violation. 672 o a certificate signed by another party would similarly have little 673 additional relevance, unless the third party is the manufacturer 674 of the Registrar! 676 The smarkaklink enrollment process uses a combination of the first 677 and third choice. The involvement of the manufacturer at this step 678 affords an opporuntity to do sales-channel integration with the 679 manufacturer. The manufacturer can associate an account with the 680 user using a wide variety of OAUTH2 [RFC6749] processes. In 681 addition, based upon the URL provided the manufacturer can do 682 redirection along a value-added reseller process. For instance, the 683 manufacturer of a home router could redirect the pledge to the ISP 684 that resold the router. 686 While [RFC7030] describes a Certificate Signing Request in order to 687 have a certificate assigned, the actual contents of the certificate 688 are not interesting at all, and the process of attempting to come up 689 with a meaningful contents tends to cause more interoperability 690 issues than having nothing. 692 The Smarkaklink takes the _smartpledge attribute_ from the QR code, 693 forming a URL as describe above. An HTTPS POST is performed to this 694 URL, with the JSON body of: 696 { 697 "mac" : 698 } 700 The HTTPS POST MUST be performed with freshly created self-signed 701 certificate. If the smarkaklink application has previously 702 communicated with this URL, it MAY skip this step and use a 703 previously returned certificate. Doing so has a privacy implication 704 discussed below, but is appropriate when enrolling many devices from 705 the same manufacturer into the same network. 707 The smarkaklink client should be prepared for three cases: 709 o A certificate is immediately returned. 711 o A 201 status code is returned, and Location: header is provided. 712 A GET request to that location will retrieve the certificate. 714 o A 302 redirection occurs with some initiation of an OAUTH2 process 715 to establish some additional authorization. 717 o Any other error (4xx and 5xx) are typically unrecoverable errors. 719 In the third case, the 302 response SHOULD take the smarkaklink 720 operator to the given URL in an interactive browser. The operator 721 SHOULD be given access to their normal set of cookies and third-party 722 logins such that they can use appropriate third party (Google, 723 Facebook, Github, Live.com, etc.) logins to help validate the 724 operator as a real person, and not a malware. Such logins are 725 optional, and it is a manufacturer choice as to what integrations 726 they want to make. 728 After the OAUTH2 process, the SmartPledge will be redirected back to 729 the MASA and a 201 status code will be returned when successful as 730 above. 732 7.1. minimal Smart Pledge enrollment 734 A manufacturer who has not built-in any restrictions on the identity 735 that the smarkaklink uses, MAY return the same self-signed 736 certificate that the smartpledge used to connect with. 738 8. Threat Analysis 740 The following attacks have been considered. 742 8.1. Wrong Administrator 744 Neighbours with similar setups wind up managing each other's network 745 (by mistake). 747 8.2. Rogue Administrator 749 Uninitialized networks can be adopted by 'wardrivers' who search for 750 networks that have no administrator. 752 8.3. Attack from Internal device 754 A compromised device inside the home can be used by an attack to take 755 control of the home router. 757 8.4. Attack from camera enabled robot 759 A robot (such as a home vacuum cleaner) could be compromised, and 760 then used by an attacker to observe and/or scan the router QRcode. 762 8.5. Attack from manipulator enabled robot 764 A robot (for instance, a toy) could be compromised, and then used by 765 an attacker to push the WPA and/or factory reset button on the 766 router. 768 9. Security Considerations 770 XXX: Go through the list of attacks above, and explain how each has 771 been mitigated. 773 Go through the list of concerns in ANIMA and EST-RFC7030 and indicate 774 if there are additional concerns, or if a concern does not apply. 776 10. IANA Considerations 778 TBD. 780 11. Acknowledgements 782 This work was supported by the Canadian Internet Registration 783 Authority https://cira.ca/blogs/cira-labs/about-cira-labs. 785 12. References 787 12.1. Normative References 789 [dpp] "Device Provisioning Protocol Specification", n.d., 790 . 794 [I-D.ietf-anima-bootstrapping-keyinfra] 795 Pritikin, M., Richardson, M., Behringer, M., Bjarnason, 796 S., and K. Watsen, "Bootstrapping Remote Secure Key 797 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 798 keyinfra-18 (work in progress), January 2019. 800 [iso18004] 801 "Information technology --- Automatic identification and 802 data capture techniques --- Bar code symbology --- QR 803 Codes (ISO/IEC 18004:2015)", n.d., 804 . 807 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 808 Requirement Levels", BCP 14, RFC 2119, 809 DOI 10.17487/RFC2119, March 1997, 810 . 812 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 813 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 814 January 2005, . 816 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 817 "Enrollment over Secure Transport", RFC 7030, 818 DOI 10.17487/RFC7030, October 2013, 819 . 821 12.2. Informative References 823 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 824 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 825 2006, . 827 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 828 "Transport Layer Security (TLS) Session Resumption without 829 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 830 January 2008, . 832 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 833 RFC 6749, DOI 10.17487/RFC6749, October 2012, 834 . 836 [RFC7217] Gont, F., "A Method for Generating Semantically Opaque 837 Interface Identifiers with IPv6 Stateless Address 838 Autoconfiguration (SLAAC)", RFC 7217, 839 DOI 10.17487/RFC7217, April 2014, 840 . 842 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 843 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 844 . 846 Appendix A. Resulting DPP QR code specification 848 This is a merge of the additions from section Section 6.1 and section 849 5.2.1 of [dpp]: 851 dpp-qr = "DPP:" [channel-list ";"] 852 [";" llv6-addr ] [";" mudurl ] 853 [";" smarkaklink ] [";" essid ] ";;" 854 llv6-addr = "L:" 8*hex-octet 855 essid = "E:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 856 smarkaklink = "S:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 857 mudurl = "D:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 858 pkex-bootstrap-info = [information] 859 channel-list = "C:" class-and-channels *("," class-and-channels) 860 class-and-channels = class "/" channel *("," channel) 861 class = 1*3DIGIT 862 channel = 1*3DIGIT 863 mac = "M:" 6hex-octet ; MAC address 864 hex-octet = 2HEXDIG 865 information = "I:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 866 public-key = "K:" *PKCHAR 867 ; DER of ASN.1 SubjectPublicKeyInfo encoded in 868 ; "base64" as per [14] 869 PKCHAR = ALPHA / DIGIT / %x2b / %x2f / %x3d 870 llv6-addr = "L:" 8*hex-octet 871 essid = "E:" *(%x21-3A / %x3C-7E) ; semicolon not allowed 872 smartpledge = "S:" *(%x21-3A / %x3C-7E) ; semicolon not allowed 874 Appendix B. Swagger.IO definition of API 876 This is a work-in-progress definition of the smarkaklink to MASA API 877 in the form of Swagger.IO format: 879 --- 880 swagger: "2.0" 881 info: 882 description: | 883 The smartpledge API is described in detail in 884 draft-richardson-anima-smartpledge. This API is 885 a variation of BRSKI (draft-ietf-anima-bootstrapping-keyinfra) 886 which provides an initial bootstrap of the 887 Secure Home Gateway registrar. 888 version: 1.0.0 889 title: Secure Home Gateway secure enrollment API (smartpledge-BRSKI) 890 contact: 891 email: securehomegateway@cira.ca 892 license: 893 name: Apache 2.0 894 url: http://www.apache.org/licenses/LICENSE-2.0.html 895 host: virtserver.swaggerhub.com 896 basePath: /CIRALabs/smartpledge/1.0.0 897 tags: 898 - name: est 899 description: Enrollment over Secure Transport 900 schemes: 901 - https 902 paths: 903 /voucherrequest: 904 get: 905 tags: 906 - developers 907 summary: searches inventory 908 description: | 909 By passing in the appropriate options, you can search for 910 available inventory in the system 911 operationId: searchInventory 912 produces: 913 - application/json 914 parameters: 915 - name: searchString 916 in: query 917 description: | 918 pass an optional search string for looking up inventory 919 required: false 920 type: string 921 - name: skip 922 in: query 923 description: number of records to skip for pagination 924 required: false 925 type: integer 926 minimum: 0 927 format: int32 928 - name: limit 929 in: query 930 description: maximum number of records to return 931 required: false 932 type: integer 933 maximum: 50 934 minimum: 0 935 format: int32 936 responses: 937 200: 938 description: search results matching criteria 939 schema: 940 type: array 941 items: 942 $ref: '#/definitions/InventoryItem' 943 400: 944 description: bad input parameter 945 post: 946 tags: 948 - admins 949 summary: adds an inventory item 950 description: Adds an item to the system 951 operationId: addInventory 952 consumes: 953 - application/json 954 produces: 955 - application/json 956 parameters: 957 - in: body 958 name: inventoryItem 959 description: Inventory item to add 960 required: false 961 schema: 962 $ref: '#/definitions/InventoryItem' 963 responses: 964 201: 965 description: item created 966 400: 967 description: invalid input, object invalid 968 409: 969 description: an existing item already exists 970 definitions: 971 InventoryItem: 972 type: object 973 required: 974 - id 975 - manufacturer 976 - name 977 - releaseDate 978 properties: 979 id: 980 type: string 981 format: uuid 982 example: d290f1ee-6c54-4b01-90e6-d701748f0851 983 name: 984 type: string 985 example: Widget Adapter 986 releaseDate: 987 type: string 988 format: date-time 989 example: 2016-08-29T09:12:33.001Z 990 manufacturer: 991 $ref: '#/definitions/Manufacturer' 992 Manufacturer: 993 required: 994 - name 995 properties: 997 name: 998 type: string 999 example: ACME Corporation 1000 homePage: 1001 type: string 1002 format: url 1003 example: https://www.acme-corp.com 1004 phone: 1005 type: string 1006 example: 408-867-5309 1008 Authors' Addresses 1010 Michael Richardson 1011 Sandelman Software Works 1013 Email: mcr+ietf@sandelman.ca 1015 Jacques Latour 1016 CIRA Labs 1018 Email: Jacques.Latour@cira.ca 1020 Faud Khan 1021 Twelve Dot Systems 1023 Email: faud.khan@twelvedot.com 1025 Abhishek Joshi 1026 Twelve Dot Systems 1028 Email: abhishek.joshi@twelvedot.com