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