idnits 2.17.1 draft-richardson-anima-smarkaklink-03.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 date (November 02, 2020) is 1271 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '14' on line 933 == Outdated reference: A later version (-45) exists of draft-ietf-anima-bootstrapping-keyinfra-44 -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IOTOPS Working Group M. Richardson 3 Internet-Draft Sandelman Software Works 4 Intended status: Informational J. Latour 5 Expires: May 6, 2021 CIRA Labs 6 November 02, 2020 8 BRSKI enrollment of with disconnected Registrars -- smarkaklink 9 draft-richardson-anima-smarkaklink-03 11 Abstract 13 This document details the mechanism used for initial enrollment using 14 a smartphone of a BRSKI Registrar system. 16 There are two key differences in assumption from 17 [I-D.ietf-anima-bootstrapping-keyinfra]: that the intended registrar 18 has Internet, and that the Pledge has no user-interface. 20 This variation on BRSKI is intended to be used in the situation where 21 the registrar device is new out of the box and is the intended 22 gateway to the Internet (such as a home gateway), but has not yet 23 been configured. This work is also intended as a transition to the 24 Wi-Fi Alliance work on the Device Provisioning Protocol (DPP). 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on May 6, 2021. 43 Copyright Notice 45 Copyright (c) 2020 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Intermittent Device connectivity . . . . . . . . . . . . 4 62 1.2. Additional Motivation . . . . . . . . . . . . . . . . . . 4 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. History and Origin of the name . . . . . . . . . . . . . 6 65 3. Assumptions and Required Setup . . . . . . . . . . . . . . . 6 66 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 67 4.1. Scan the QR code . . . . . . . . . . . . . . . . . . . . 7 68 4.2. Enroll with the manufacturer . . . . . . . . . . . . . . 7 69 4.3. Gather name details for new device . . . . . . . . . . . 7 70 4.4. Connect to BRSKI join network . . . . . . . . . . . . . . 8 71 4.5. Connect to Adolescent Registrar (AR) . . . . . . . . . . 8 72 4.6. Smartphone Requests Voucher-Request from the Adolescent 73 Registrar . . . . . . . . . . . . . . . . . . . . . . . . 9 74 4.7. AR processing of voucher-request, request. . . . . . . . 9 75 4.7.1. Additions to Voucher-Request . . . . . . . . . . . . 10 76 4.8. Smartphone validates connection . . . . . . . . . . . . . 10 77 4.9. Smart-Phone connects to MASA . . . . . . . . . . . . . . 11 78 4.10. MASA processing . . . . . . . . . . . . . . . . . . . . . 11 79 4.11. Smartpledge processing of voucher . . . . . . . . . . . . 11 80 4.12. Adolescent Registrar (AR) receives voucher . . . . . . . 12 81 4.13. Adolescent Registrar (AR) grows up . . . . . . . . . . . 12 82 4.14. Enrollment status . . . . . . . . . . . . . . . . . . . . 12 83 4.15. Smartphone enrolls . . . . . . . . . . . . . . . . . . . 13 84 4.16. Validation of connection . . . . . . . . . . . . . . . . 13 85 5. Protocol Details . . . . . . . . . . . . . . . . . . . . . . 14 86 5.1. Quick Response Code (QR code) . . . . . . . . . . . . . . 14 87 5.1.1. The Smarkaklink Attribute . . . . . . . . . . . . . . 14 88 5.1.2. Link-Layer Address Attribute . . . . . . . . . . . . 15 89 5.1.3. ESSID Name Attribute . . . . . . . . . . . . . . . . 15 90 5.2. Enrollment using EST . . . . . . . . . . . . . . . . . . 15 91 6. Smart Pledge enrollment with manufacturer . . . . . . . . . . 15 92 6.1. minimal Smart Pledge enrollment . . . . . . . . . . . . . 17 93 7. Threat Analysis . . . . . . . . . . . . . . . . . . . . . . . 17 94 7.1. Wrong Administrator . . . . . . . . . . . . . . . . . . . 17 95 7.2. Rogue Administrator . . . . . . . . . . . . . . . . . . . 18 96 7.3. Attack from Internal device . . . . . . . . . . . . . . . 18 97 7.4. Attack from camera enabled robot . . . . . . . . . . . . 18 98 7.5. Attack from manipulator enabled robot . . . . . . . . . . 18 99 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 100 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 101 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18 102 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 103 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 104 11.2. Informative References . . . . . . . . . . . . . . . . . 19 105 Appendix A. Resulting DPP QR code specification . . . . . . . . 20 106 Appendix B. Swagger.IO definition of API . . . . . . . . . . . . 20 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 109 1. Introduction 111 The problem of bootstrapping a new device is described at length in 112 [I-D.ietf-anima-bootstrapping-keyinfra] (aka BRSKI). The problem 113 that BRSKI solves is the case of a smart, properly configured network 114 with a minimum of network connectivity (or previously pre-previoned 115 with nonceless vouchers), and a relatively stupid new device (the 116 Pledge), which lacks a user interface. 118 The BRSKI problem is one of trust: how does the new device trust that 119 it has found the correct network to join, and how does the new 120 network become convinced that the new device is a device that is 121 intended to join. BRSKI solves the problem well for the case where 122 the network is well connected and can easily talk to the device's 123 Manufacturer Authorized Signing Authority (MASA), while providing 124 appropriate proxy mechanisms to enable the new pledge to communicate 125 it's proximity assertion to the MASA as well. 127 This document is about a variation of the problem: when the new 128 device being introduce has no network connectivity, but a new device 129 is intended to serve as the Registrar for the network. This new 130 device is likely a home (or small office) gateway, and until it is 131 properly configured there will be no direct network connectivity. 133 There are a number of protocols that permit an ISP to consider a new 134 router brought into a home to be a new pledge to the ISPs' network, 135 and for that new device to integrated into the ISP's (autonomic) 136 network. BRSKI can be used itself, and there are ways to use the 137 Broadband Form's TR-069 to bootstrap the device in this way. This 138 document is not about the situation where the router device is 139 intended to belong to the ISP, but about the situation where the home 140 user intends to own and control the device. 142 1.1. Intermittent Device connectivity 144 There is an additional variation which this variation solves: the 145 case where there is one or more devices in a place with no immediate 146 connectivity to a Registrar. An example of this could be a new home 147 construction where a furnace, thermostat or other control systems 148 need to be introduced to each other. If a registrar exists it will 149 have no Internet connectivity (as above), until the home becomes 150 owned by the first owner. There might never be a registrar though. 152 The basement case is important because the assumption is that the 153 _installer_ may have poor or no LTE connectivity in that location. 154 The installer will have to exit the basement, perhaps even return to 155 their truck, in order to have network connectivity for their 156 provisioning device (a smartphone equivalent). 158 1.2. Additional Motivation 160 The Wi-Fi Alliance has released the Device Provisioning Protocol 161 [dpp]. The specification is available only via "free" registation. 162 The specification relies on being able to send and receive 802.11 163 Public Action frames, as well as Generic Advertisement Service (GAS) 164 Public Action frames. Access to send new layer-2 frames is generally 165 restricted in most smartphone operating systems (iOS, Android). At 166 present there are no known public APIs that a generic application 167 writer could use, and therefore the smart-phone side of the DPP can 168 only be implemented at present by the vendors of those operating 169 systems. 171 As both dominant vendors have competing proprietary mechanisms, it is 172 unclear if generic applications will be produced soon. It is 173 probably impractical for a vendor an a smart-appliance to 174 independantly produce an application that can do proper DPP in 2019. 175 As one of the common goals of this document and DPP is that there 176 need not be an application-per-device only one DPP application need 177 exist. Until such time as such an application becomes universal it 178 is a goal of this document to lay the groundwork for a transition to 179 full use of DPP by leveraging the QR code infrastructure that DPP 180 depends upon. 182 In addition to the above concern, DPP is primary concerned about 183 provisioning WiFi credentials to devices. DPP can provision access 184 points themselves, but it lacks any kind of manufacturer integration. 185 BRSKI provides this integration, and therefore an audit trail history 186 for the device. 188 The smarkaklink enrollment process described in this document is 189 about securely initializing the administrative connection with a 190 device that is the WiFi Access Point. 192 2. Terminology 194 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 195 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 196 "OPTIONAL" in this document are to be interpreted as described in 197 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 198 capitals, as shown here. 200 The following terminology is copied from 201 [I-D.ietf-anima-bootstrapping-keyinfra] 203 enrollment: The process where a device presents key material to a 204 network and acquires a network specific identity. For example when a 205 certificate signing request is presented to a certification authority 206 and a certificate is obtained in response. 208 pledge: The prospective device, which has an identity installed at 209 the factory. 211 IDevID: a manufacturer signed keypair (different from the QRkey) 212 which is generated at the factory. This is the 802.1AR artifact 213 which is mandated by [I-D.ietf-anima-bootstrapping-keyinfra]. 215 The following new terminology has been added 217 smarkaphone: The prospective administrator device, usually a 218 smartphone equipped with a QR capable camera, wifi and 3G 219 connectivity. 221 adolescent router (AR): a home router or device containing a 222 registrar. The device does not yet have network connectivity, and 223 has no administrator. It is considered not a "baby" device in the 224 same way that the pledge is, but it is not yet an adult. A better 225 term would be welcome. 227 SelfDevID: a public/private key pair generated by the smartpledge, 228 formed into a self-signed PKIX certificate. The private key part 229 remains always on the smartpledge, but like other secondary device 230 keys, should be encrypted for backup purposes. {EDNOTE: any 231 references to Apple or Android APIs/specifications here?} 233 QRkey: a unique, raw ECDSA or EdDSA key pair generated in (or for) 234 the adolescent router at the factory, and stored in the 235 configuration portion of the firmware. The public portion is 236 printed in a QRcode. This key is not formed into a certificate of 237 any kind. 239 smarkaklink: the name of this protocol. 241 adolescent router (AR): a home router or device containing a 242 registrar. The device does not yet have network connectivity, and 243 has no administrator. 245 2.1. History and Origin of the name 247 This document was originally called the "smartpledge" variation of 248 BRSKI. This name was intended to indicate that the variation is one 249 where the BRSKI role of Pledge is taken on by the smartphone device. 251 While the end-goal is to have the smartphone enrolled into a PKI 252 hosted by the fully-grown Router, the activities of each device do 253 not map into the BRSKI roles at the beginning. In fact, they are 254 reversed with the Adolescent Router being the Pledge. Review of this 255 document suggested that removing the word pledge would help. 257 The new name "smarkaklink" is intended to sound like the sound that 258 two (wine, beer) glasses make after a toast is made. 260 3. Assumptions and Required Setup 262 The first assumption is that intended device owner is active and is 263 present. The device owner has a smart-phone that is capable of using 264 Wi-Fi or being wired into the adolescent router (AR). 266 The smartpledge application generates a self-signed certificate with 267 public/private keypair that it knows. It may generate a unique 268 certificate for each manufacturer. This certificate is called the 269 SelfDevID. 271 The second assumption is that the device has a QR code printed on the 272 outside of the unit, and/or provided with the packaging/ 273 documentation. The QR code is as specified in section 5.3 of [dpp], 274 with the additions specified in Section 5.1 276 The third assumption is that the AR, at manufacturing time, has the 277 anchor for it's MASA (same assumption as for BRSKI pledge's). In 278 addition, like the BRSKI pledge, the AR has an IDevID certificate 279 (and associated private key) signed by the manufacturer. 281 The fourth assumption is that the key in the "K:" attribute 282 Section 5.1 is a different public key pair. It MUST be different 283 from the key used in the IDevID. This key is called the DPP-Keypair. 285 4. Protocol Overview 287 This is the overview of the process. {EDNOTE: there are many details 288 here that belong in the next section. The goal in this section is to 289 consisely explain the interaction among the components. Clearly this 290 text currently fails in that regard} 292 4.1. Scan the QR code 294 The operator of the smartphone invokes the smarkaklink application, 295 and scans the QR code on the AR. The smartphone learns the ESSID, 296 Public-Key, mac-address, smarkaklink URL, and link-local address of 297 the AR. 299 4.2. Enroll with the manufacturer 301 The smartphone uses it's 3G, or other WiFi internet access to connect 302 to the manufacturer with TLS. The manufacturer is identified with 303 the smartpledge URL. 305 The operator of the smartphone may need to move to another location 306 to get connectivity. It is desireable that an operator be able to 307 scan many QR codes before moving, performing this operation in a 308 batch. There may be multiple devices from the same manufacturer, and 309 the smarkalink application SHOUld enroll with the manufacturer a 310 single time for all devices. 312 The smartphone does an HTTP POST to the provided URL using it's 313 generated certificate as it's ClientCertificate. As described in 314 Section 6, the manufacturer MAY respond with a 302 result code, and 315 have the end user go through a web browser based process to enroll. 316 After that process, a redirection will occur using OAUTH2. 318 The result should finally be a 201 result code, and at that URL is a 319 new certificate signed by the manufacturer. 321 4.3. Gather name details for new device 323 The contents of the scanned QR code may some necessary information to 324 facilititate the connection. After enrolling with the manufacturer, 325 the smartphone makes a request to the manufacturer to get more 326 details. 328 A POST request is made containing the public key of the device. The 329 public key is used as an index, and this MAY result in a literal 330 reply, or may result in an HTTP 201 response with a Location: header 331 where details on the device may be obtained. 333 The final result is a JSON object that provides additional details 334 about the device. At present, a key detail that does not fit into 335 the QR code is the full certificate distinguished name that the 336 device will respond with. 338 This is the Adolescent Router Fully Qualified Domain Name, or AD- 339 FQDN. 341 Additionally, if the device does not have a certificate that has a 342 public WebPKI anchor, then the manufacturer will include an 343 appropriate trust anchor with which to validate the device. If the 344 device has a self-signed certificate, then it may be returned. 346 4.4. Connect to BRSKI join network 348 The application then reconnects the Wi-Fi interface of the smartphone 349 to the ESSID of the AR. This involves normal 802.11 station 350 attachment. The given ESSID explicitely has no WPA or other security 351 required on it. 353 There will be no DHCPv4 on this network. This simplifies the 354 operation of the devices that are enrolling, but it also makes the 355 network uninteresting to other random users that may stumble upon the 356 open ESSID. 358 A IPv6 Router Solicitation may elicit an answer (confirming the 359 device is there), but it is acceptable for there to be no prefix 360 information. An IPv6 Neighbour Discovery is done for the IPv6 Link- 361 Local address of the AR. Receipt of an answer confirms that the 362 ESSID is correct and present. 364 (XXX - not using GRASP here. Could use GRASP, but QR code is better) 366 4.5. Connect to Adolescent Registrar (AR) 368 The smarkaklink application then makes a direct (no proxy) TLS 369 connection to port 8081 (!To be confirmed!) of the AR, on the IPv6 370 Link-Local address given. 372 This is as in section 5.1 of [I-D.ietf-anima-bootstrapping-keyinfra]. 373 The smartphone uses it's SelfDevID as the TLS ClientCertificate, as 374 the smartphone and smarkaklink will not have a manufacturer signed 375 IDevID. 377 Additionally, the AR will use it's IDevID certificate as the 378 ServerCertificate of the TLS conncetion. As with other BRSKI IDevID, 379 it will have a MASA URL extension, as described in 380 [I-D.ietf-anima-bootstrapping-keyinfra] section 2.3.2. 382 The Adolescent Registrar is acting here in the role of pledge. 384 Given typical libraries, the connection will be made initially with 385 all TLS peer name validation turned off, as the connection will not 386 be to an IPv6 Link-Local address, which can not be placed into a 387 certificate. The certificate should still be verified if possible up 388 to a public trust anchor. 390 After connecting, the certificate presented by the AR MUST contain 391 the AR-FQDN provided above as a subjectAltName rfc822Name extension. 393 Alternatively, a custom certification verification call back may be 394 made. 396 4.6. Smartphone Requests Voucher-Request from the Adolescent Registrar 398 The smartphone generates a random nonce _SPnonce_. (Do we need 399 something time-based too here?) 401 The smarkaklink client encrypts this to the public key of the AR, 402 which was found in the QR code. If the key is RSA, this is a simple 403 public key operation (we need to reference appropriate padding due to 404 various attacks). In the mandatory to implement ECDSA case, then 405 ECIES is used instead. 407 The result goes into the Voucher-Request-Request, posted as a JSON 408 containing a single field: _voucher-request challenge_. This is 409 placed in the voucher-challenge-nonce field. 411 (XXX-should be done with JOSE? Probably) 413 NOTE: DPP has a round with the SHA256 of the device's key to make 414 sure that the correct device has been chosen. The TLS connection 415 effectively provides the same privacy that the Bx keys provided. 417 The resulting object is POST'ed to the new BRSKI endpoint: 419 /.well-known/est/requestvoucherrequest 421 [or should it be named: /.well-known/est/requestvoucherchallenge 423 ] 425 4.7. AR processing of voucher-request, request. 427 The AR processes this POST. First it uses the private key that is 428 associated with it's QR printed public key to decrypt the voucher- 429 request challenge. Included in this challenge is a nonce, and also 430 the link-local address of the smartphone. 432 The AR SHOULD verify that the link-local address matches the 433 originating address of the connection on which the request is 434 received. 436 The AR then forms a voucher-request identically to as described in 437 section 5.2 of [I-D.ietf-anima-bootstrapping-keyinfra]. Note that 438 the AR uses it's IDevID to sign the voucher-request. This is the 439 same key used to terminate the TLS connection. 441 Note: It MUST be different from the public key printed in the QR 442 code. 444 In addition to the randomly generated nonce that the AR generates to 445 place in the the voucher-request, into the nonce field, it also 446 includes the _SPnonce_ in a new _voucher-challenge-nonce_ field. 447 {EDNOTE: hash of nonce?} 449 This voucher-request is then _returned_ during the POST operation to 450 the smartphone. (This is in constrast that in ANIMA the voucher- 451 request is sent by the device to the Registrar, or the MASA) 453 4.7.1. Additions to Voucher-Request 455 QUESTION: should the _voucher-challenge-nonce_ be provided directly 456 in the voucher-request, or should only a hash of the nonce be used? 457 The nonce is otherwise not disclosed, and a MITM on the initial TLS 458 connection would get to see the nonce. A hash of the nonce validates 459 the nonce as easily. 461 4.8. Smartphone validates connection 463 The smartphone then examines the resulting voucher-request. The 464 smartphone validates that the voucher-request is signed by the same 465 public key as was seen in the TLS ServerCertificate. 467 The smartphone then examines the contents of the voucher-request, and 468 looks for the _voucher-challenge-nonce_. As this nonce was encrypted 469 to the AR, the only way that the resulting nonce could be correct is 470 if the correct private key was present on the AR to decrypt it. 471 Succesful verification of the _voucher-challenge-nonce_ (or the hash 472 of it, see below) results in the smartphone moving it's end of the 473 connection from provisional to validated. 475 4.9. Smart-Phone connects to MASA 477 The smarkaklink application running on the smartphone then examines 478 the MASA URL provided in the TLS ServerCertificate of the AR. The 479 smarkaklink application then connects to that URL using it's 3G/LTE 480 connection, taking on the temporary role of Registrar. 482 A wrapped voucher-request is formed by the smartphone in the same way 483 as described in section 5.4 of 484 [I-D.ietf-anima-bootstrapping-keyinfra]. The prior-signed-voucher- 485 request is filled in with the voucher-request that was created by the 486 AR in the previous step. 488 The proximity-registrar-cert of the wrapped voucher-request is set to 489 be the SelfDevID certificate of the smartphone. The voucher-request 490 is to be signed by the SelfDevID. 492 The voucher-request is POST'ed to the MASA using the same URL that is 493 used for Registrar/MASA operation: 495 /.well-known/est/requestvoucher 497 4.10. MASA processing 499 The MASA processing occurs as specified in section 5.5 of 500 [I-D.ietf-anima-bootstrapping-keyinfra] as before. The MASA MUST 501 also copy the _voucher-challenge-nonce_ into the resulting voucher. 503 4.11. Smartpledge processing of voucher 505 The smartphone will receive a voucher that contains it's IDevID as 506 the _pinned-domain-cert_, and the _voucher-challenge-nonce_ that it 507 created will also be present. The smartphone SHOULD verify the 508 signature on the artifact, but may be unable to validate that the 509 certificate used has a relationship to the TLS ServerCertificate used 510 by the MASA. (This limitation exists in ANIMA as well). 512 The smartphone will then POST the resulting voucher to the AR using 513 the URL 515 /.well-known/est/voucher 517 If an existing TLS connection is still available, it MAY be reused. 519 If a TLS session-resumption ticket (see [RFC8446] section 2.2 for TLS 520 1.3, and [RFC5077] for TLS 1.2) has been obtained, it SHOULD be used 521 if the TLS connection needs to be rebuilt. This is particularly 522 useful in the disconnected use case explained in Section 1.1. 524 4.12. Adolescent Registrar (AR) receives voucher 526 When the AR receives the voucher, it validates that it is signed by 527 it's manufacturer. This process is the same as section 5.5.1 of 528 [I-D.ietf-anima-bootstrapping-keyinfra]. 530 Again note that the AR is acting in the role of a pledge. 532 Inside the voucher, the pinned-domain-cert is examined. It should 533 match the TLS ClientCertificate that the smartphone used to connect. 534 This is the SelfDevID. 536 At this point the AR has validated the identity of the smartphone, 537 and the AR moves it's end of the connection from provisional to 538 validated. 540 4.13. Adolescent Registrar (AR) grows up 542 The roles are now changed. 544 If necessary, the AR generates a new key pair as it's Domain CA key. 545 It MAY generate intermediate CA certificates and a seperate Registrar 546 certificate, but this is discouraged for home network use. 548 The AR is now considered a full registrar. The AR now takes on the 549 role of Registrar. 551 4.14. Enrollment status 553 The AR responds to the POST of the voucher with the enrollment status 554 as the reply to the POST, as per the enrollment status object defined 555 in BRSKI section 5.9.4. 557 The smartphone MAY POST the resulting enrollment status to the MASA, 558 in a manner similar to BRSKI section 5.9.4. Note that the operation 559 described in that section is about telemetry from the pledge to the 560 Registrar. That telemetry was return as part of the POST above. 562 Returning enrollment status to the MASA is an optional action; while 563 there are privacy implications of doing so, the logicstics feedback 564 of a failure likely will result in a service technician visit, which 565 is hardly privacy enhancing. This telemetry return is strongly 566 encouraged. 568 The POST to /.well-known/est/enrollstatus MUST include some 569 additional information to tell the MASA which device was involved. 570 This section therefore defines a new element for the status return to 571 be the "voucher" attribute; it is to be filled in with the base64 572 encoding of the voucher that was provided. While this is excessive, 573 it discloses no information that the MASA does not already have, has 574 been signed and identifies both the Adolescent Router and the Smart 575 Phone client involved. 577 4.15. Smartphone enrolls 579 At this stage of the smarkaklink protocol, the typical BRSKI exchange 580 is over. A Secure Transport has been established between the 581 smartphone and the fully-grown AR. The smartphone now takes on the 582 role of secured pledge, or EST client. 584 The smartphone MUST now request the full list of CA Certificates, as 585 per [RFC7030] section 4.1. As the Registrar's CA certificate has 586 just been generated, the smartphone has no other way of knowing it. 588 The smartphone MUST now also generate a CSR request as per 589 [I-D.ietf-anima-bootstrapping-keyinfra] section 5.8.3. The 590 smartpledge MAY reuse the SelfDevID key pair for this purpose. (XXX 591 - maybe there are good reasons not to reuse?) 593 The Registrar SHOULD grant administrator privileges to the smartphone 594 via the certificate that is issued. This may be done via special 595 attributes in the issued certificate, or it may pin the certificate 596 in a database. Which method to use is a local matter. 598 The TLS/EST connection MUST remain open at this point. This is 599 connection one. 601 4.16. Validation of connection 603 The smartphone MUST now open a new HTTPS connection to the Registrar 604 (AR), using it's newly issued certificate. (XXX should this be on a 605 different IP, or a different port? If so, how is this indicated?) 607 The smartphone MUST validate that the new connection's TLS Server 608 certificate can be validated by the Registrar's new CA certificate. 610 The registrar MUST validate that the smartphone's ClientCertificate 611 is validated by the Registrar's CA. The smartphone SHOULD perform a 612 POST operation on this new connection to the 613 [I-D.ietf-anima-bootstrapping-keyinfra] Enrollment Status Telemetry 614 mechanism, see section 5.8.3. 616 Upon success, the original TLS/EST connection (one) MAY now be 617 closed. 619 5. Protocol Details 621 5.1. Quick Response Code (QR code) 623 Section 5.3 of [dpp] describes the contents for an [iso18004] image. 624 It specifies content that starts with DPP:, and the contains a series 625 of semi-colon (;) deliminated section with a single letter and colon. 626 This markup is terminated with a double semi-colon. 628 Although no amending formula is defined in DPP 1.0, this document is 629 defining two extensions. This requires amending the ABNF from 630 section 5.2.1 as follows: 632 dpp-qr = "DPP:" [channel-list ";"] [channel-list ";"] 633 [mac ";"] [information ";"] public-key 634 [";" llv6-addr ] [";" mudurl ] 635 [";" smarkaklink ] [";" essid ] ";;" 636 llv6-addr = "L:" 8*hex-octet 637 essid = "E:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 638 smarkaklink = "S:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 639 mudurl = "D:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 641 While the ABNF defined in the [dpp] document assumes a specific order 642 (C:, M:, I:, K:), this specification relaxes this so that the tags 643 can come in any order. However, in order to make interoperation with 644 future DPP-only clients as seamless as possible, the extensions 645 suggested here are placed at the end of the list. This is consistent 646 with the Postel Principle. 648 It is intended that parts of this protocol could be performed by an 649 actual DPP implementation, should it become possible to implement DPP 650 using current smartphone operating systems in an unprivileged way. 652 5.1.1. The Smarkaklink Attribute 654 The _smarkaklink_ attribute indicates that the device is capable of 655 the protocol specified in this document. The contents of the 656 smarkaklink attribute contains part or all of an IRI which identifies 657 the manufacturer of the device. 659 It SHOULD contain the _iauthority_ of an IRI as specified in section 660 2.2 of [RFC3987]. The scheme is implicitely "https://", with an 661 ipath of "/.well-known/est/smarkaklink". This implicit form exists 662 to save bytes in the QR code. 664 If the string contains any "/" characters, then it is not an 665 _iauthority_, but an entire IRI. This takes many more characters, 666 but is useful in a variety of debugging situations, and also provides 667 for new innovations. 669 Short URLs are important to fit into typical QR code space. 671 5.1.2. Link-Layer Address Attribute 673 The _llv6-addr_ attribute is optional. When present, it specifies 674 the IPv6 Link-Local address at which the adolescent router is 675 listening. If not specified, then the link-local address may be 676 formed according to the historical (privacy-violating) process 677 described in [RFC4291] Appendix A. The _llv6-addr_ attribute is 678 present so that devices that have implemented [RFC7217] stable 679 addresses can express that address clearly. 681 5.1.3. ESSID Name Attribute 683 The _essid_ attribute provides the name of the 802.11 network on 684 which the enrollment will occur. If this attribute is absent, then 685 it defaults to "BRSKI". 687 5.2. Enrollment using EST 689 TBD 691 6. Smart Pledge enrollment with manufacturer 693 While it is assumed that there will be many makers of Smarkaklink 694 applications, a goal of this specification is to eliminate the need 695 for an "app" per device, providing onboarding mechanism for a variety 696 of devices from a single app. 698 Given the secondary goal of a transition to use of Device 699 Provisioning Protocol (DPP), the smarkaklink application may have to 700 be provided as part of the smart phone system, as a system service. 701 This is due to the need to send/receive wifi management frames from 702 DPP. As such each vendor of a smart device will need to produce a 703 smarkaklink app, and it will be impossible for the vendor of the 704 Registrar device (or other DPP capable IoT device) to provide an app 705 on their own. 707 Having stated this goal, it is understood that initially the app may 708 well come from the manufacturer of the Registrar, but this protocol 709 is designed on the assumption that there is no such vertical 710 integration. 712 So, there can be no initial relationship between the Smart Pledge and 713 the manufacturer of the Registrar. 715 But, in a traditional [I-D.ietf-anima-bootstrapping-keyinfra] 716 scenario the pledge would have been provided with an IDevID at 717 manufacturing time. While an IDevID could have been built-in to the 718 SmartPledge "app", such a key would not be private if it was built- 719 in. A key could be generated by the app upon installation. It could 720 be self-signed, it could be signed by the maker of the app, or it 721 could be signed by another party. 723 o a self-signed certificate is just a container for a public key. 724 For the purposes of the trust relationship with the Registrar, it 725 would be sufficient. 727 o a certificate signed by the maker of the app (or the maker of the 728 smart-phone) would carry no specific trust beyond what a self- 729 signed certificate would have. Any linking in the certificate to 730 a network expressable identity (such as layer-2 address) would 731 simply be a privacy violation. 733 o a certificate signed by another party would similarly have little 734 additional relevance, unless the third party is the manufacturer 735 of the Registrar! 737 The smarkaklink enrollment process uses a combination of the first 738 and third choice. The involvement of the manufacturer at this step 739 affords an opporuntity to do sales-channel integration with the 740 manufacturer. The manufacturer can associate an account with the 741 user using a wide variety of OAUTH2 [RFC6749] processes. In 742 addition, based upon the URL provided the manufacturer can do 743 redirection along a value-added reseller process. For instance, the 744 manufacturer of a home router could redirect the pledge to the ISP 745 that resold the router. 747 While [RFC7030] describes a Certificate Signing Request in order to 748 have a certificate assigned, the actual contents of the certificate 749 are not interesting at all, and the process of attempting to come up 750 with a meaningful contents tends to cause more interoperability 751 issues than having nothing. 753 The Smarkaklink takes the _smartpledge attribute_ from the QR code, 754 forming a URL as describe above. An HTTPS POST is performed to this 755 URL, with the JSON body of: 757 { 758 "mac" : 759 } 761 The HTTPS POST MUST be performed with freshly created self-signed 762 certificate. If the smarkaklink application has previously 763 communicated with this URL, it MAY skip this step and use a 764 previously returned certificate. Doing so has a privacy implication 765 discussed below, but is appropriate when enrolling many devices from 766 the same manufacturer into the same network. 768 The smarkaklink client should be prepared for three cases: 770 o A certificate is immediately returned. 772 o A 201 status code is returned, and Location: header is provided. 773 A GET request to that location will retrieve the certificate. 775 o A 302 redirection occurs with some initiation of an OAUTH2 process 776 to establish some additional authorization. 778 o Any other error (4xx and 5xx) are typically unrecoverable errors. 780 In the third case, the 302 response SHOULD take the smarkaklink 781 operator to the given URL in an interactive browser. The operator 782 SHOULD be given access to their normal set of cookies and third-party 783 logins such that they can use appropriate third party (Google, 784 Facebook, Github, Live.com, etc.) logins to help validate the 785 operator as a real person, and not a malware. Such logins are 786 optional, and it is a manufacturer choice as to what integrations 787 they want to make. 789 After the OAUTH2 process, the SmartPledge will be redirected back to 790 the MASA and a 201 status code will be returned when successful as 791 above. 793 6.1. minimal Smart Pledge enrollment 795 A manufacturer who has not built-in any restrictions on the identity 796 that the smarkaklink uses, MAY return the same self-signed 797 certificate that the smartpledge used to connect with. 799 7. Threat Analysis 801 The following attacks have been considered. 803 7.1. Wrong Administrator 805 Neighbours with similar setups wind up managing each other's network 806 (by mistake). 808 7.2. Rogue Administrator 810 Uninitialized networks can be adopted by 'wardrivers' who search for 811 networks that have no administrator. 813 7.3. Attack from Internal device 815 A compromised device inside the home can be used by an attack to take 816 control of the home router. 818 7.4. Attack from camera enabled robot 820 A robot (such as a home vacuum cleaner) could be compromised, and 821 then used by an attacker to observe and/or scan the router QRcode. 823 7.5. Attack from manipulator enabled robot 825 A robot (for instance, a toy) could be compromised, and then used by 826 an attacker to push the WPA and/or factory reset button on the 827 router. 829 8. Security Considerations 831 XXX: Go through the list of attacks above, and explain how each has 832 been mitigated. 834 Go through the list of concerns in ANIMA and EST-RFC7030 and indicate 835 if there are additional concerns, or if a concern does not apply. 837 9. IANA Considerations 839 TBD. 841 10. Acknowledgements 843 This work was supported by the Canadian Internet Registration 844 Authority https://cira.ca/blogs/cira-labs/about-cira-labs. 846 11. References 848 11.1. Normative References 850 [dpp] "Device Provisioning Protocol Specification", n.d., 851 . 855 [I-D.ietf-anima-bootstrapping-keyinfra] 856 Pritikin, M., Richardson, M., Eckert, T., Behringer, M., 857 and K. Watsen, "Bootstrapping Remote Secure Key 858 Infrastructures (BRSKI)", draft-ietf-anima-bootstrapping- 859 keyinfra-44 (work in progress), September 2020. 861 [iso18004] 862 "Information technology -- Automatic identification and 863 data capture techniques -- Bar code symbology -- QR Codes 864 (ISO/IEC 18004:2015)", n.d., 865 . 868 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 869 Requirement Levels", BCP 14, RFC 2119, 870 DOI 10.17487/RFC2119, March 1997, 871 . 873 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 874 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 875 January 2005, . 877 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 878 "Enrollment over Secure Transport", RFC 7030, 879 DOI 10.17487/RFC7030, October 2013, 880 . 882 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 883 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 884 May 2017, . 886 11.2. Informative References 888 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 889 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 890 2006, . 892 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 893 "Transport Layer Security (TLS) Session Resumption without 894 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 895 January 2008, . 897 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 898 RFC 6749, DOI 10.17487/RFC6749, October 2012, 899 . 901 [RFC7217] Gont, F., "A Method for Generating Semantically Opaque 902 Interface Identifiers with IPv6 Stateless Address 903 Autoconfiguration (SLAAC)", RFC 7217, 904 DOI 10.17487/RFC7217, April 2014, 905 . 907 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 908 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 909 . 911 Appendix A. Resulting DPP QR code specification 913 This is a merge of the additions from section Section 5.1 and section 914 5.2.1 of [dpp]: 916 dpp-qr = "DPP:" [channel-list ";"] 917 [";" llv6-addr ] [";" mudurl ] 918 [";" smarkaklink ] [";" essid ] ";;" 919 llv6-addr = "L:" 8*hex-octet 920 essid = "E:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 921 smarkaklink = "S:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 922 mudurl = "D:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 923 pkex-bootstrap-info = [information] 924 channel-list = "C:" class-and-channels *("," class-and-channels) 925 class-and-channels = class "/" channel *("," channel) 926 class = 1*3DIGIT 927 channel = 1*3DIGIT 928 mac = "M:" 6hex-octet ; MAC address 929 hex-octet = 2HEXDIG 930 information = "I:" *(%x20-3A / %x3C-7E) ; semicolon not allowed 931 public-key = "K:" *PKCHAR 932 ; DER of ASN.1 SubjectPublicKeyInfo encoded in 933 ; "base64" as per [14] 934 PKCHAR = ALPHA / DIGIT / %x2b / %x2f / %x3d 935 llv6-addr = "L:" 8*hex-octet 936 essid = "E:" *(%x21-3A / %x3C-7E) ; semicolon not allowed 937 smartpledge = "S:" *(%x21-3A / %x3C-7E) ; semicolon not allowed 939 Appendix B. Swagger.IO definition of API 941 This is a work-in-progress definition of the smarkaklink to MASA API 942 in the form of Swagger.IO format: 944 --- 945 swagger: "2.0" 946 info: 947 description: | 948 The smartpledge API is described in detail in 949 draft-richardson-anima-smartpledge. This API is 950 a variation of BRSKI (draft-ietf-anima-bootstrapping-keyinfra) 951 which provides an initial bootstrap of the 952 Secure Home Gateway registrar. 953 version: 1.0.0 954 title: Secure Home Gateway secure enrollment API (smartpledge-BRSKI) 955 contact: 956 email: securehomegateway@cira.ca 957 license: 958 name: Apache 2.0 959 url: http://www.apache.org/licenses/LICENSE-2.0.html 960 host: virtserver.swaggerhub.com 961 basePath: /CIRALabs/smartpledge/1.0.0 962 tags: 963 - name: est 964 description: Enrollment over Secure Transport 965 schemes: 966 - https 967 paths: 968 /voucherrequest: 969 get: 970 tags: 971 - developers 972 summary: searches inventory 973 description: | 974 By passing in the appropriate options, you can search for 975 available inventory in the system 976 operationId: searchInventory 977 produces: 978 - application/json 979 parameters: 980 - name: searchString 981 in: query 982 description: | 983 pass an optional search string for looking up inventory 984 required: false 985 type: string 986 - name: skip 987 in: query 988 description: number of records to skip for pagination 989 required: false 990 type: integer 991 minimum: 0 992 format: int32 993 - name: limit 994 in: query 995 description: maximum number of records to return 996 required: false 997 type: integer 998 maximum: 50 999 minimum: 0 1000 format: int32 1001 responses: 1002 200: 1003 description: search results matching criteria 1004 schema: 1005 type: array 1006 items: 1007 $ref: '#/definitions/InventoryItem' 1008 400: 1009 description: bad input parameter 1010 post: 1011 tags: 1012 - admins 1013 summary: adds an inventory item 1014 description: Adds an item to the system 1015 operationId: addInventory 1016 consumes: 1017 - application/json 1018 produces: 1019 - application/json 1020 parameters: 1021 - in: body 1022 name: inventoryItem 1023 description: Inventory item to add 1024 required: false 1025 schema: 1026 $ref: '#/definitions/InventoryItem' 1027 responses: 1028 201: 1029 description: item created 1030 400: 1031 description: invalid input, object invalid 1032 409: 1033 description: an existing item already exists 1034 definitions: 1035 InventoryItem: 1036 type: object 1037 required: 1038 - id 1039 - manufacturer 1040 - name 1041 - releaseDate 1042 properties: 1043 id: 1044 type: string 1045 format: uuid 1046 example: d290f1ee-6c54-4b01-90e6-d701748f0851 1047 name: 1048 type: string 1049 example: Widget Adapter 1050 releaseDate: 1051 type: string 1052 format: date-time 1053 example: 2016-08-29T09:12:33.001Z 1054 manufacturer: 1055 $ref: '#/definitions/Manufacturer' 1056 Manufacturer: 1057 required: 1058 - name 1059 properties: 1060 name: 1061 type: string 1062 example: ACME Corporation 1063 homePage: 1064 type: string 1065 format: url 1066 example: https://www.acme-corp.com 1067 phone: 1068 type: string 1069 example: 408-867-5309 1071 Authors' Addresses 1073 Michael Richardson 1074 Sandelman Software Works 1076 Email: mcr+ietf@sandelman.ca 1078 Jacques Latour 1079 CIRA Labs 1081 Email: Jacques.Latour@cira.ca