├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE-DOCUMENTATION ├── README.md ├── draft-hill-delegated-recovery.html ├── draft-hill-delegated-recovery.raw.txt └── draft-hill-delegated-recovery.xml /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated. 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to delegated-recovery 2 | We want to make contributing to this project as easy and transparent as 3 | possible. 4 | 5 | ## Code of Conduct 6 | The code of conduct is described in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). 7 | 8 | ## Pull Requests 9 | We actively welcome your pull requests. 10 | 11 | 1. Create a GitHub issue to track the reason for the proposed change. 12 | 2. Fork the repo and create your branch from `master`. 13 | 3. Make changes to the .xml source only. 14 | 4. Please ensure that your changes build with xml2rfc. 15 | 5. Do not include the resulting .html file in your pull request. The .html will 16 | be generated andupdated by the project maintainers. 17 | 4. If you haven't already, complete the Contributor License Agreement ("CLA"). 18 | 5. Submit your pull request 19 | 20 | ## Contributor License Agreement ("CLA") 21 | In order to accept your pull request, we need you to submit a CLA. You only need 22 | to do this once to work on any of Facebook's open source projects. 23 | 24 | Complete your CLA here: 25 | 26 | ## Issues 27 | We use GitHub issues to track public bugs. Please ensure your description is 28 | clear and has sufficient instructions to be able to reproduce the issue. 29 | 30 | Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe 31 | disclosure of security bugs. In those cases, please go through the process 32 | outlined on that page and do not file a public issue. 33 | 34 | ## License 35 | By contributing to delegated-recovery, you agree that your contributions will be licensed 36 | under the LICENSE file in the root directory of this source tree. 37 | -------------------------------------------------------------------------------- /LICENSE-DOCUMENTATION: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More_considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | Section 1 -- Definitions. 69 | 70 | a. Adapted Material means material subject to Copyright and Similar 71 | Rights that is derived from or based upon the Licensed Material 72 | and in which the Licensed Material is translated, altered, 73 | arranged, transformed, or otherwise modified in a manner requiring 74 | permission under the Copyright and Similar Rights held by the 75 | Licensor. For purposes of this Public License, where the Licensed 76 | Material is a musical work, performance, or sound recording, 77 | Adapted Material is always produced where the Licensed Material is 78 | synched in timed relation with a moving image. 79 | 80 | b. Adapter's License means the license You apply to Your Copyright 81 | and Similar Rights in Your contributions to Adapted Material in 82 | accordance with the terms and conditions of this Public License. 83 | 84 | c. Copyright and Similar Rights means copyright and/or similar rights 85 | closely related to copyright including, without limitation, 86 | performance, broadcast, sound recording, and Sui Generis Database 87 | Rights, without regard to how the rights are labeled or 88 | categorized. For purposes of this Public License, the rights 89 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 90 | Rights. 91 | 92 | d. Effective Technological Measures means those measures that, in the 93 | absence of proper authority, may not be circumvented under laws 94 | fulfilling obligations under Article 11 of the WIPO Copyright 95 | Treaty adopted on December 20, 1996, and/or similar international 96 | agreements. 97 | 98 | e. Exceptions and Limitations means fair use, fair dealing, and/or 99 | any other exception or limitation to Copyright and Similar Rights 100 | that applies to Your use of the Licensed Material. 101 | 102 | f. Licensed Material means the artistic or literary work, database, 103 | or other material to which the Licensor applied this Public 104 | License. 105 | 106 | g. Licensed Rights means the rights granted to You subject to the 107 | terms and conditions of this Public License, which are limited to 108 | all Copyright and Similar Rights that apply to Your use of the 109 | Licensed Material and that the Licensor has authority to license. 110 | 111 | h. Licensor means the individual(s) or entity(ies) granting rights 112 | under this Public License. 113 | 114 | i. Share means to provide material to the public by any means or 115 | process that requires permission under the Licensed Rights, such 116 | as reproduction, public display, public performance, distribution, 117 | dissemination, communication, or importation, and to make material 118 | available to the public including in ways that members of the 119 | public may access the material from a place and at a time 120 | individually chosen by them. 121 | 122 | j. Sui Generis Database Rights means rights other than copyright 123 | resulting from Directive 96/9/EC of the European Parliament and of 124 | the Council of 11 March 1996 on the legal protection of databases, 125 | as amended and/or succeeded, as well as other essentially 126 | equivalent rights anywhere in the world. 127 | 128 | k. You means the individual or entity exercising the Licensed Rights 129 | under this Public License. Your has a corresponding meaning. 130 | 131 | Section 2 -- Scope. 132 | 133 | a. License grant. 134 | 135 | 1. Subject to the terms and conditions of this Public License, 136 | the Licensor hereby grants You a worldwide, royalty-free, 137 | non-sublicensable, non-exclusive, irrevocable license to 138 | exercise the Licensed Rights in the Licensed Material to: 139 | 140 | a. reproduce and Share the Licensed Material, in whole or 141 | in part; and 142 | 143 | b. produce, reproduce, and Share Adapted Material. 144 | 145 | 2. Exceptions and Limitations. For the avoidance of doubt, where 146 | Exceptions and Limitations apply to Your use, this Public 147 | License does not apply, and You do not need to comply with 148 | its terms and conditions. 149 | 150 | 3. Term. The term of this Public License is specified in Section 151 | 6(a). 152 | 153 | 4. Media and formats; technical modifications allowed. The 154 | Licensor authorizes You to exercise the Licensed Rights in 155 | all media and formats whether now known or hereafter created, 156 | and to make technical modifications necessary to do so. The 157 | Licensor waives and/or agrees not to assert any right or 158 | authority to forbid You from making technical modifications 159 | necessary to exercise the Licensed Rights, including 160 | technical modifications necessary to circumvent Effective 161 | Technological Measures. For purposes of this Public License, 162 | simply making modifications authorized by this Section 2(a) 163 | (4) never produces Adapted Material. 164 | 165 | 5. Downstream recipients. 166 | 167 | a. Offer from the Licensor -- Licensed Material. Every 168 | recipient of the Licensed Material automatically 169 | receives an offer from the Licensor to exercise the 170 | Licensed Rights under the terms and conditions of this 171 | Public License. 172 | 173 | b. No downstream restrictions. You may not offer or impose 174 | any additional or different terms or conditions on, or 175 | apply any Effective Technological Measures to, the 176 | Licensed Material if doing so restricts exercise of the 177 | Licensed Rights by any recipient of the Licensed 178 | Material. 179 | 180 | 6. No endorsement. Nothing in this Public License constitutes or 181 | may be construed as permission to assert or imply that You 182 | are, or that Your use of the Licensed Material is, connected 183 | with, or sponsored, endorsed, or granted official status by, 184 | the Licensor or others designated to receive attribution as 185 | provided in Section 3(a)(1)(A)(i). 186 | 187 | b. Other rights. 188 | 189 | 1. Moral rights, such as the right of integrity, are not 190 | licensed under this Public License, nor are publicity, 191 | privacy, and/or other similar personality rights; however, to 192 | the extent possible, the Licensor waives and/or agrees not to 193 | assert any such rights held by the Licensor to the limited 194 | extent necessary to allow You to exercise the Licensed 195 | Rights, but not otherwise. 196 | 197 | 2. Patent and trademark rights are not licensed under this 198 | Public License. 199 | 200 | 3. To the extent possible, the Licensor waives any right to 201 | collect royalties from You for the exercise of the Licensed 202 | Rights, whether directly or through a collecting society 203 | under any voluntary or waivable statutory or compulsory 204 | licensing scheme. In all other cases the Licensor expressly 205 | reserves any right to collect such royalties. 206 | 207 | Section 3 -- License Conditions. 208 | 209 | Your exercise of the Licensed Rights is expressly made subject to the 210 | following conditions. 211 | 212 | a. Attribution. 213 | 214 | 1. If You Share the Licensed Material (including in modified 215 | form), You must: 216 | 217 | a. retain the following if it is supplied by the Licensor 218 | with the Licensed Material: 219 | 220 | i. identification of the creator(s) of the Licensed 221 | Material and any others designated to receive 222 | attribution, in any reasonable manner requested by 223 | the Licensor (including by pseudonym if 224 | designated); 225 | 226 | ii. a copyright notice; 227 | 228 | iii. a notice that refers to this Public License; 229 | 230 | iv. a notice that refers to the disclaimer of 231 | warranties; 232 | 233 | v. a URI or hyperlink to the Licensed Material to the 234 | extent reasonably practicable; 235 | 236 | b. indicate if You modified the Licensed Material and 237 | retain an indication of any previous modifications; and 238 | 239 | c. indicate the Licensed Material is licensed under this 240 | Public License, and include the text of, or the URI or 241 | hyperlink to, this Public License. 242 | 243 | 2. You may satisfy the conditions in Section 3(a)(1) in any 244 | reasonable manner based on the medium, means, and context in 245 | which You Share the Licensed Material. For example, it may be 246 | reasonable to satisfy the conditions by providing a URI or 247 | hyperlink to a resource that includes the required 248 | information. 249 | 250 | 3. If requested by the Licensor, You must remove any of the 251 | information required by Section 3(a)(1)(A) to the extent 252 | reasonably practicable. 253 | 254 | 4. If You Share Adapted Material You produce, the Adapter's 255 | License You apply must not prevent recipients of the Adapted 256 | Material from complying with this Public License. 257 | 258 | Section 4 -- Sui Generis Database Rights. 259 | 260 | Where the Licensed Rights include Sui Generis Database Rights that 261 | apply to Your use of the Licensed Material: 262 | 263 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 264 | to extract, reuse, reproduce, and Share all or a substantial 265 | portion of the contents of the database; 266 | 267 | b. if You include all or a substantial portion of the database 268 | contents in a database in which You have Sui Generis Database 269 | Rights, then the database in which You have Sui Generis Database 270 | Rights (but not its individual contents) is Adapted Material; and 271 | 272 | c. You must comply with the conditions in Section 3(a) if You Share 273 | all or a substantial portion of the contents of the database. 274 | 275 | For the avoidance of doubt, this Section 4 supplements and does not 276 | replace Your obligations under this Public License where the Licensed 277 | Rights include other Copyright and Similar Rights. 278 | 279 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 280 | 281 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 282 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 283 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 284 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 285 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 286 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 287 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 288 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 289 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 290 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 291 | 292 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 293 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 294 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 295 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 296 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 297 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 298 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 299 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 300 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 301 | 302 | c. The disclaimer of warranties and limitation of liability provided 303 | above shall be interpreted in a manner that, to the extent 304 | possible, most closely approximates an absolute disclaimer and 305 | waiver of all liability. 306 | 307 | Section 6 -- Term and Termination. 308 | 309 | a. This Public License applies for the term of the Copyright and 310 | Similar Rights licensed here. However, if You fail to comply with 311 | this Public License, then Your rights under this Public License 312 | terminate automatically. 313 | 314 | b. Where Your right to use the Licensed Material has terminated under 315 | Section 6(a), it reinstates: 316 | 317 | 1. automatically as of the date the violation is cured, provided 318 | it is cured within 30 days of Your discovery of the 319 | violation; or 320 | 321 | 2. upon express reinstatement by the Licensor. 322 | 323 | For the avoidance of doubt, this Section 6(b) does not affect any 324 | right the Licensor may have to seek remedies for Your violations 325 | of this Public License. 326 | 327 | c. For the avoidance of doubt, the Licensor may also offer the 328 | Licensed Material under separate terms or conditions or stop 329 | distributing the Licensed Material at any time; however, doing so 330 | will not terminate this Public License. 331 | 332 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 333 | License. 334 | 335 | Section 7 -- Other Terms and Conditions. 336 | 337 | a. The Licensor shall not be bound by any additional or different 338 | terms or conditions communicated by You unless expressly agreed. 339 | 340 | b. Any arrangements, understandings, or agreements regarding the 341 | Licensed Material not stated herein are separate from and 342 | independent of the terms and conditions of this Public License. 343 | 344 | Section 8 -- Interpretation. 345 | 346 | a. For the avoidance of doubt, this Public License does not, and 347 | shall not be interpreted to, reduce, limit, restrict, or impose 348 | conditions on any use of the Licensed Material that could lawfully 349 | be made without permission under this Public License. 350 | 351 | b. To the extent possible, if any provision of this Public License is 352 | deemed unenforceable, it shall be automatically reformed to the 353 | minimum extent necessary to make it enforceable. If the provision 354 | cannot be reformed, it shall be severed from this Public License 355 | without affecting the enforceability of the remaining terms and 356 | conditions. 357 | 358 | c. No term or condition of this Public License will be waived and no 359 | failure to comply consented to unless expressly agreed to by the 360 | Licensor. 361 | 362 | d. Nothing in this Public License constitutes or may be interpreted 363 | as a limitation upon, or waiver of, any privileges and immunities 364 | that apply to the Licensor or You, including from the legal 365 | processes of any jurisdiction or authority. 366 | 367 | ======================================================================= 368 | 369 | Creative Commons is not a party to its public licenses. 370 | Notwithstanding, Creative Commons may elect to apply one of its public 371 | licenses to material it publishes and in those instances will be 372 | considered the "Licensor." Except for the limited purpose of indicating 373 | that material is shared under a Creative Commons public license or as 374 | otherwise permitted by the Creative Commons policies published at 375 | creativecommons.org/policies, Creative Commons does not authorize the 376 | use of the trademark "Creative Commons" or any other trademark or logo 377 | of Creative Commons without its prior written consent including, 378 | without limitation, in connection with any unauthorized modifications 379 | to any of its public licenses or any other arrangements, 380 | understandings, or agreements concerning use of licensed material. For 381 | the avoidance of doubt, this paragraph does not form part of the public 382 | licenses. 383 | 384 | Creative Commons may be contacted at creativecommons.org. 385 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Delegated Recovery 2 | 3 | delegated-account-recovery is a protocol that allows an application to delegate the capability to recover an account (e.g. in the event of a credential loss or compromise) to an account controlled by the same user at a third party service provider. 4 | 5 | ## Usage 6 | This is a specification. 7 | 8 | Open Source SDKs and example applications implementing this specification can be found for Java and JavaScript at [https://github.com/facebook/DelegatedRecoveryReferenceImplementation](https://github.com/facebook/DelegatedRecoveryReferenceImplementation), and for Ruby (developed by GitHub) at [https://github.com/github/darrrr](https://github.com/github/darrrr). 9 | 10 | Facebook offers an implementation of the Recovery Provider portion of this protocol, currently in closed beta. Find more information at: [https://developers.facebook.com/docs/delegated-recovery/](https://developers.facebook.com/docs/delegated-recovery/). 11 | 12 | ## Dependencies 13 | 14 | The source of the specification is in the xml format used by, and the html generated with [xml2rfc](https://xml2rfc.tools.ietf.org/) 15 | 16 | ## Join the community 17 | See the CONTRIBUTING file for how to help out. 18 | 19 | ## License 20 | The specification is provided under the Creative Commons Attribution 4.0 International license. 21 | 22 | -------------------------------------------------------------------------------- /draft-hill-delegated-recovery.raw.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Facebook, Inc. B. Hill, Ed. 6 | Unofficial Draft Facebook, Inc. 7 | October 26, 2017 8 | Expires: April 29, 2018 9 | 10 | 11 | Delegated Account Recovery 12 | draft-hill-delegated-recovery 13 | 14 | Abstract 15 | 16 | Delegated Account Recovery allows an application to delegate the 17 | capability to recover an account (e.g. in the event of a credential 18 | loss or compromise) to an account controlled by the same user or 19 | entity at a third party service provider. 20 | 21 | Status of This Memo 22 | 23 | This Unofficial Draft will expire on April 29, 2018. 24 | 25 | Copyright Notice 26 | 27 | Copyright (c) 2016-2017 Facebook, Inc. and the persons identified as 28 | the document authors and published under the Creative Commons 29 | Attribution 4.0 International license. 30 | 31 | Table of Contents 32 | 33 | 1. Introduction 34 | 1.1. Notational Conventions 35 | 1.1.1. Presentation Language 36 | 1.2. Challenges with Existing Account Recovery Solutions 37 | 1.2.1. Recovery Questions 38 | 1.2.2. Password Hints 39 | 1.2.3. Email Recovery 40 | 1.2.4. Federated Authentication 41 | 1.2.5. Alternate Methods 42 | 1.3. Relationship to Other Protocols 43 | 1.4. Goals 44 | 1.5. Roles 45 | 1.6. Protocol Flow 46 | 1.6.1. Establishing a Delegated Recovery Capability 47 | 1.6.2. Exercising a Delegated Recovery Capability 48 | 1.7. TLS Version 49 | 1.8. HTTP Redirections 50 | 1.9. Application User Agents 51 | 2. Fetching Configuration 52 | 3. Protocol Endpoints 53 | 3.1. Save Token Endpoint 54 | 3.1.1. Processing Instructions 55 | 3.2. Save Token Return Endpoint 56 | 3.3. Save Token Async API Endpoint 57 | 3.3.1. Asynchronous Message Contract 58 | 3.4. Recover Account Endpoint 59 | 3.5. Recover Account Return Endpoint 60 | 3.6. Token Status Endpoint 61 | 3.6.1. Processing Instructions 62 | 3.6.2. Security Considerations 63 | 4. Token Generation 64 | 4.1. Recovery Token 65 | 4.1.1. Internal Structure 66 | 4.1.2. Opaque Data 67 | 4.1.3. Signature 68 | 4.2. Counter-Signed Recovery Token 69 | 4.2.1. Internal Structure 70 | 4.2.2. Counter-Signed Recovery Token Signature 71 | 5. Use in Key Recovery 72 | 6. Security Considerations 73 | 6.1. Deterministic Use of ECDSA 74 | 6.2. User Notification 75 | 6.3. Additional Verification 76 | 6.3.1. At the Recovery Provider 77 | 6.3.2. At the Account Provider 78 | 6.4. Low Friction Tokens and Delegated Multi-Factor 79 | Authentication 80 | 6.5. Cross-Site Request Forgery 81 | 6.6. Breach Detection 82 | 6.7. Clock Skew 83 | 6.8. Key Loss and Compromise 84 | 6.9. TLS or HTTPS Certificate Compromise 85 | 6.10. Token Leakage 86 | 7. Implementation Notes 87 | 8. IANA Considerations 88 | 9. Acknowledgements 89 | 10. Normative References 90 | Appendix A. Initial Algorithm Registry Contents 91 | Author's Address 92 | 93 | 1. Introduction 94 | 95 | 1.1. Notational Conventions 96 | 97 | In this document, the key words "MUST", "MUST NOT", "REQUIRED", 98 | "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 99 | and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 100 | [RFC2119]. 101 | 102 | 1.1.1. Presentation Language 103 | 104 | This document deals with the formatting of tokens in an external 105 | representation using a casually defined syntax drawing from that used 106 | in [RFC5246] and resembling the programming language "C". The 107 | purpose is to document the binary token format only. 108 | 109 | The basic numeric data type is an unsigned byte (uint8). All larger 110 | numeric data types are formed from fixed-length series of bytes 111 | concatenated from left to right and are also unsigned. The following 112 | numeric types are predefined. 113 | 114 | uint8 uint16[2]; 115 | uint8 uint32[4]; 116 | uint8 uint64[8]; 117 | 118 | All values, here and elsewhere in the specification, are stored in 119 | network byte (big-endian) order; the uint32 represented by the hex 120 | bytes 01 02 03 04 is equivalent to the decimal value 16909060. 121 | 122 | The type string is defined as a concatenated sequence of octet 123 | sequences representing ASCII characters, one per octet. [RFC3629] 124 | 125 | The term URL is defined by reference to [RFC3986] in this document. 126 | "URL" is used deliberately in preference to "URI" as all such objects 127 | in this document are used to access network resources and such 128 | objects as used by this document lack any persistent meaning after 129 | the resource to which they refer ceases to exist. 130 | 131 | 1.2. Challenges with Existing Account Recovery Solutions 132 | 133 | Network services that rely on user credentials must also cope with 134 | the reality that users may forget or lose exclusive control of these 135 | credentials. As a consequence, nearly every such service must 136 | implement an alternate authentication process to enable a user to 137 | recover control of an account. In practice, there are few good 138 | options for doing this, and these recovery flows are often the 139 | weakest link in securing accounts. 140 | 141 | 1.2.1. Recovery Questions 142 | 143 | A common and self-contained method of account recovery is to ask the 144 | user additional questions that they are less likely to forget the 145 | answer to than a more arbitrary password. The same features that 146 | make such a question useful for recovery also reduce its security: 147 | 148 | o Things that are memorable may often not be fully private. Friends 149 | and family members likely know the answers to many such questions, 150 | and for highly public figures it may be possible to research this 151 | information. 152 | 153 | o Allowing users to select their own questions may result in 154 | questions with a small possible domain of answers (favorite color, 155 | favorite superhero) that make brute force guessing highly 156 | effective, even if rate-limiting is applied. 157 | 158 | o Choosing questions that are both secure and memorable is 159 | difficult, and common choices of subject matter may not be 160 | applicable across cultural contexts (mother's maiden name, name of 161 | a pet), age ranges (first car) or other differentiating 162 | characteristics of large and diverse audiences. 163 | 164 | o The limited selection of questions which are both memorable and 165 | applicable to the broadest possible audience makes re-use of these 166 | questions and answers common among many service providers, with 167 | attendant risks that disclosure of answers to a malicious party by 168 | any provider may compromise many accounts at unrelated providers. 169 | Furthermore it is difficult for a user to change their answers in 170 | the event of such a compromise. 171 | 172 | 1.2.2. Password Hints 173 | 174 | Password hints are extremely problematic - by definition they must be 175 | revealed to an unauthenticated user, which implies reversibly 176 | encrypted storage at best, reveals information about a password (or 177 | often the password itself), and common hints at multiple services may 178 | reveal where a password is reused, facilitating further attacks. 179 | 180 | 1.2.3. Email Recovery 181 | 182 | Users are unlikely to forget their email address, and a common 183 | practice is to email the user URL that encodes the ability to recover 184 | the account. This is the most widely deployed mechanism at the time 185 | of this writing, but it has a number of shortcomings. 186 | 187 | o Forcing users to everywhere use an email address has privacy 188 | implications, potentially allowing service providers to collude to 189 | track individuals' activity across many domains. 190 | 191 | o Email addresses are not universal, and are becoming less so. 192 | Especially in the developing world or with younger audiences, 193 | email may not be the first network service individuals provision 194 | for themselves, if they provision it at all. 195 | 196 | o Email addresses get recycled and reassigned to new owners. 197 | 198 | o Users may use a weakly-secured email addresses when signing up for 199 | a new service, for example an address maintained to collect the 200 | unwanted commercial correspondence often expected to result from 201 | signing up for a new online service. 202 | 203 | o Email does not provide guarantees of deliverability or end-to-end 204 | transport security. An adversary performing pervasive 205 | surveillance may likely be able to abuse such weaknesses. 206 | 207 | o Emails in large organizations are rarely private to their 208 | recipient. In addition to the commonplace that high-value 209 | accounts belonging to executives may be accessible by their 210 | assistants, the contents and especially links in the email of 211 | every user in a modern organization may commonly be logged for 212 | legal discovery purposes, or crawled to identify malware and 213 | phishing attacks. 214 | 215 | o The capabilities of an emailed reset link must be encoded in the 216 | GET string to ensure compatibility with non-HTML capable mail user 217 | agents, and so may leak in the HTTP Referer header to any other 218 | content included in a recovery page. (e.g. an analytics script 219 | hosted at a third-party origin) 220 | 221 | o Users are commonly authenticated to email services all the time on 222 | many devices. Account recovery through email is an unstructured 223 | process which does not ensure the user was strongly authenticated 224 | for a high-risk action. A simple password compromise, or even 225 | brief loss of control of an unlocked device where the user is 226 | logged in, may be sufficient to transitively compromise many other 227 | accounts of the user. If the only way to notify the user that 228 | their account was reset is back through the same email channel, an 229 | attacker can easily cover their tracks. 230 | 231 | o The wide diversity of mail user agents means that even if account 232 | recovery emails could be detected heuristically by providers or 233 | explicitly identified with metadata from senders, it would be 234 | remain difficult for email providers to apply special treatment to 235 | such messages. 236 | 237 | o An attacker that compromises a user's account may change the email 238 | address associated with it. Without very carefully designed 239 | processes, it may be impossible for the genuine user to recover 240 | their account after such a change if recovery flows are purely 241 | email-based. 242 | 243 | o Email recovery flows cannot be used to recover capabilities, such 244 | as cryptographic keys, that may be necessary to use an account 245 | (e.g. a network-based file store that offers encrypted files) but 246 | which the user does not want the account provider to have access 247 | to at all times. 248 | 249 | 1.2.4. Federated Authentication 250 | 251 | Federated systems for authentication take many forms and solve the 252 | problem of account recovery (or at least delegate it implicitly to 253 | the Identity Provider). However, after fifteen years of widespread 254 | deployment of such systems, we see few mainstream services that are 255 | willing to rely exclusively on federated logins for a variety of 256 | reasons. 257 | 258 | o A user may be unwilling to disclose their identity, other 259 | information, or grant permissions to a new service they have just 260 | begun to use and about which they have not yet formed an opinion 261 | of its value or trustworthiness. 262 | 263 | o A service may be unwilling to depend on a third-party for access 264 | to its customer base. They may view "owning" their relationship 265 | with the customer as having business value, may have a regulatory 266 | mandate to do so, or may not want to be beholden to the 267 | availability of a third party for their most important customer 268 | interactions. 269 | 270 | o A service may view providers of federated login services as 271 | competitors or potential competitors, and not wish to disclose 272 | information about how often users are logging on, who their most 273 | active users are or not desire to show a competitor's logo as part 274 | of their login process. 275 | 276 | 1.2.5. Alternate Methods 277 | 278 | Methods do exist to strongly re-authenticate an account holder in the 279 | absence of a password or other primary credential. Device-based or 280 | multi-factor authentication, multi-device authentication, or trusted 281 | connections in a social network are possibilities. Unfortunately, of 282 | the potentially hundreds of services a user interacts with in a year, 283 | only a few are likely able to leverage such factors. The rest will 284 | lack the information, resources, and user consent needed. 285 | Furthermore, the characteristics that make good recovery systems 286 | strong also may make them unique to a particular service, preventing 287 | broad adoption as a best practice by other providers. 288 | 289 | 1.3. Relationship to Other Protocols 290 | 291 | Delegated Recovery is similar in some respects to OAuth [RFC5849]and 292 | related protocols. 293 | 294 | It is not constructed simply as a profile of one these protocols as 295 | it relies on different trust semantics. Because tokens granting an 296 | account recovery capability are expected to have an indefinite 297 | lifetime and should be able to remain valid even following the 298 | compromise and/or rotation of the keys they were originally issued 299 | under, tokens in this protocol derive their authority at a point in 300 | time from being signed with currently published public keys, 301 | discoverable over HTTPS. 302 | 303 | As this trust model is different than other protocols in the broad 304 | OAuth family, profiling an existing protocol to fit these needs would 305 | likely be considerably more complex than implementing a new, 306 | minimalist protocol from scratch. As such, the latter approach has 307 | been taken here. 308 | 309 | 1.4. Goals 310 | 311 | Goals for Delegated Account Recovery include: 312 | 313 | o Allow network services that do not have the resources or 314 | information to build a secure and usable account recovery process 315 | to delegate the function to network services that can. 316 | 317 | o Allow users to choose to use service providers that can strongly 318 | re-authenticate them to recover accounts at other services. 319 | 320 | o Disclose as little information as possible, and no more than is 321 | necessary, to protocol participants. 322 | 323 | o As much as possible, require multiple points of failure in order 324 | for accounts to be compromised through the recovery process. 325 | 326 | o Be resilient in the face of compromises, including loss of 327 | exclusive control of cryptographic key material, and allow re- 328 | establishment of trust in stored recovery capabilities without 329 | user action. 330 | 331 | o Provide, through the protocol semantics, explicit information 332 | about security-critical account actions and information flow 333 | between providers to enable better auditing, anomaly detection and 334 | remediation in the event of compromises. 335 | 336 | o Allow users to set up a durable recovery capability when in 337 | control of their account, which can be exercised even after 338 | malicious changes to the account (such as changing an associated 339 | email address or personal information) following a compromise. 340 | 341 | 1.5. Roles 342 | 343 | Delegated Recovery defines three roles: 344 | 345 | User 346 | The entity in control of the accounts. 347 | 348 | Account Provider 349 | The network service at which a user has an account they need to 350 | establish a recovery capability for. 351 | 352 | Recovery Provider 353 | The network service which offers the delegated account recovery 354 | service, and at which a user has an account and wishes to use to 355 | recover control of other accounts. 356 | 357 | 1.6. Protocol Flow 358 | 359 | 1.6.1. Establishing a Delegated Recovery Capability 360 | 361 | 362 | +--------+ +------+ +----+---+ 363 | |Account | | User | |Recovery| 364 | |Provider| | | |Provider| 365 | | | | | | | 366 | +-+------+ +--+---+ +----+---+ 367 | | | | 368 | | 1. Select Recovery | | 369 | | Provider | | 370 | |<--------------------+ | 371 | | | 2. Retrieve | 372 | | | Configuration | 373 | +---------------------------------------->| 374 | |<----------------------------------------+ 375 | | | | 376 | +----+ 3. Generate Recovery| | 377 | | | Token | | 378 | +--->| | | 379 | | | | 380 | | 4. Redirect User | | 381 | | Agent to Recovery | | 382 | | Provider with Token | | 383 | +-------------------->+------------------>| 384 | | | | 385 | | | 5. (if needed) | 386 | | | Authenticate User | 387 | | |<------------------+ 388 | | +------------------>| 389 | | | | 390 | | | 6. Retrieve | 391 | | | Configuration | 392 | |<----------------------------------------+ 393 | +---------------------------------------->| 394 | | | | 395 | | (optional) | 7. Verify and +---+ 396 | | 8. Notify Account | Save Recovery | | 397 | | Provider with | Token |<--+ 398 | | Result Code for | | 399 | | token ID | | 400 | |<----------------------------------------+ 401 | | | | 402 | | 9. Redirect User | | 403 | | Agent back to | | 404 | | Account Provider | | 405 | | | | 406 | |<--------------------+<------------------+ 407 | | | | 408 | | | | 409 | V V V 410 | 411 | 412 | 413 | Figure 1: Recovery Capability Establishment 414 | 415 | The abstract Delegated Recovery capability establishment flow 416 | illustrated in Figure 1 describes the interaction between the three 417 | roles and includes the following steps: 418 | 419 | 1. The User, having already established control of an account with 420 | the Account Provider, indicates to the Account Provider which 421 | Recovery Provider they would like to use. 422 | 423 | 2. The Account Provider makes a GET request to determine if the 424 | service of the user's choice offers the Delegated Recovery 425 | service and what its protocol endpoint URLs are. This step may 426 | be unnecesssary if the Account Provider already knows the 427 | configuration for the chosen Recovery Provider. 428 | 429 | 3. The Account Provider generates a recovery token for the User and 430 | Recovery Provider. 431 | 432 | 4. The Account Provider sends the Token to the User Agent with 433 | instructions to deliver it to the Recovery Provider URL indicated 434 | in the configuration. 435 | 436 | 5. Upon receiving the Token, the Recovery Provider authenticates the 437 | user if they are not logged in. 438 | 439 | 6. The Recovery Provider makes a GET request to the Account Provider 440 | to discover its public keys and protocol URLs. 441 | 442 | 7. The Recovery Provider validates the signature on the token and 443 | saves it. 444 | 445 | 8. The Recovery Provider optionally notifies the Account Provider of 446 | the status of the operation. 447 | 448 | 9. The Recovery Provider redirects the user agent back to the 449 | callback URL indicated by the configuration with a status code. 450 | 451 | 1.6.2. Exercising a Delegated Recovery Capability 452 | 453 | 454 | +--------+ +------+ +----+---+ 455 | |Account | | User | |Recovery| 456 | |Provider| | | |Provider| 457 | | | | | | | 458 | +-+------+ +--+---+ +----+---+ 459 | | (optional) | | 460 | | 1. Initiate Recovery| | 461 | | | | 462 | |<--------------------+ | 463 | | | | 464 | | | (optional) | 465 | | | 2. Retrieve | 466 | | | Configuration | 467 | +---------------------------------------->| 468 | |<----------------------------------------+ 469 | | | | 470 | | (optional) | | 471 | | 3. Offer User link | 1. Initiate | 472 | | to Recovery Provider| Recovery | 473 | | with origin hint | | 474 | +-------------------->+------------------>| 475 | | | | 476 | | | 4. (if needed) | 477 | | | Authenticate User | 478 | | |<------------------+ 479 | | +------------------>| 480 | | | | 481 | | | 5. Retrieve | 482 | | | Configuration | 483 | |<----------------------------------------+ 484 | +---------------------------------------->| 485 | | | | 486 | | | 6. Retrieve and +---+ 487 | | 7. Send User | Counter-Sign | | 488 | | Agent to Account | Recovery Token |<--+ 489 | | Provider with | | 490 | | Counter-Signed | | 491 | | Recovery Token | | 492 | |<--------------------+<------------------+ 493 | | | | 494 | | | 8. Retrieve | 495 | | | Configuration | 496 | +---------------------------------------->| 497 | |<----------------------------------------+ 498 | | | | 499 | +----+ 9. Validate | | 500 | | | Recovery Token | | 501 | +--->| | | 502 | | | | 503 | | | | 504 | | 10. Restore Control | | 505 | | of Account | | 506 | |-------------------->| | 507 | | | | 508 | V V V 509 | 510 | 511 | 512 | Figure 2: Exercising a Recovery Capability 513 | 514 | The abstract flow depicting the exercising of a Delegated Recovery 515 | capability in Figure 2 describes the interaction between the the 516 | roles and includes the following steps: 517 | 518 | 1. The user initiates a recovery, either at the Account Provider, 519 | or with the Recovery Provider. 520 | 521 | 2. (optional) the Account Provider GETs the current configuration 522 | for the Recovery Provider to be used. 523 | 524 | 3. (optional) The Account Provider offers or redirects the user to 525 | the Recovery Provider's endpoint, with a hint of the origin of 526 | the account the User wants to recover. 527 | 528 | 4. The Recovery Provider authenticates the user appropriately for 529 | conducting a recovery transaction. 530 | 531 | 5. The Recovery Provider makes a GET request to discover the 532 | current URL for exercising recovery at the Account Provider. 533 | 534 | 6. The Recovery Provider counter-signs the token and additional 535 | fields with its published key. 536 | 537 | 7. The Recovery Provider sends the user agent to the Account 538 | Provider's recovery URL with the counter-signed token. 539 | 540 | 8. The Account Provider receives a token, and retrieves the 541 | Recovery Provider's current configuration to discover its keys. 542 | 543 | 9. The Account Provider validates the counter-signature, additional 544 | fields, its originally issued token, and takes any other 545 | necessary steps to complete risk-appropriate re-authentication 546 | of the user. 547 | 548 | 10. The Account Provider restores control of the account to the user 549 | and allows a new primary authentication method or credential to 550 | be established. 551 | 552 | 1.7. TLS Version 553 | 554 | Whenever Transport Layer Security (TLS) is used by this 555 | specification, the appropriate version (or versions) of TLS will vary 556 | over time, based on the widespread deployment and known security 557 | vulnerabilities. At the time of this writing, TLS version 1.2 558 | [RFC5246]is the most recent and widely deployed version. 559 | 560 | Implementations may also support additional transport-layer security 561 | mechanisms that meet their security requirements. 562 | 563 | 1.8. HTTP Redirections 564 | 565 | This specification makes extensive use of HTTP redirections, in which 566 | the client or the authorization server directs the resource owner's 567 | user-agent to another destination. While the examples in this 568 | specification show the use of the HTTP 302 status code, any other 569 | method available via the user-agent to accomplish this redirection is 570 | allowed and is considered to be an implementation detail. 571 | 572 | When retrieving configuration servers SHOULD NOT follow redirects to 573 | reduce the risk of Server Side Request Forgery. 574 | 575 | 1.9. Application User Agents 576 | 577 | This specification is written primarily for a general purpose web 578 | browser as user agent but this is not the only possible 579 | implementation choice. On some platforms, some of either or both of 580 | the Account Provider and Recovery Provider functionality may be 581 | provided as part of a dedicated, platform-native application, AKA an 582 | "app". Generally, as the protocol aims to coordinate between 583 | authenticated sessions at multiple service providers, the platform 584 | standard web browser is the most standardized and convenient 585 | mechanism available and should be preferred. 586 | 587 | 2. Fetching Configuration 588 | 589 | Fetching Configuration is the process of determining the protocol 590 | endpoints and public keys used by Account Providers and Recovery 591 | Providers. 592 | 593 | Service providers may indicate that configuration responses are 594 | cacheable and may cache responses but cache lifetimes should be kept 595 | reasonably short to enable timely responses to events such as key 596 | compromise. 597 | 598 | Fetching configuration begins by normalizing the service provider to 599 | be used into an RFC6454[RFC6454] ASCII serialization of an Origin 600 | with an "https" scheme. 601 | 602 | Retrieval of the configuration is done using an HTTP "GET" request to 603 | the provider's configuration endpoint at the following absolute path 604 | relative to the https:// Origin. 605 | "/.well-known/delegated-account-recovery/configuration" 606 | 607 | The configuration resource path on the http:// scheme MUST NOT 608 | redirect to the https:// protocol, as this may mask configuration 609 | mistakes by consumers. Servers MUST return an empty response body 610 | and an HTTP status code in the 400 range (401 is recommended) if 611 | "/.well-known/delegated-account-recovery/configuration" is accessed 612 | with the http:// scheme 613 | 614 | When fetching configuration, service providers MUST NOT follow 615 | redirects that do not use an https:// scheme. Service providers 616 | generally should avoid utilizing redirects when returning 617 | configuration responses. As it is not mandatory that the issuer 618 | field or endpoints in a configuration agree with the origin of the 619 | configuration URL, directly returning the canonical data rather than 620 | a redirect reduces latency in the protocol. 621 | 622 | A Recovery Provider MUST return the following information in a JSON 623 | dictionary comprising the entire response body: 624 | 625 | +-------------------------------+-----------------------------------+ 626 | | name | value | 627 | +-------------------------------+-----------------------------------+ 628 | | issuer | the RFC6454 ASCII Serialization | 629 | | | of the Origin to which this | 630 | | | configuration statement applies. | 631 | | | MUST have an https: scheme | 632 | | | component. | 633 | +-------------------------------+-----------------------------------+ 634 | | countersign-pubkeys-secp256r1 | An array of ECDSA public keys on | 635 | | | the secp256r1 curve, encoded | 636 | | | uncompressed with the named curve | 637 | | | OID as per X9.62. The Recovery | 638 | | | Provider should not publish more | 639 | | | than two keys; enabling key | 640 | | | rotation with a small overlap | 641 | | | period is the primary purpose of | 642 | | | allowing more than one key to be | 643 | | | published. | 644 | +-------------------------------+-----------------------------------+ 645 | | token-max-size | The maximum length, in bytes, of | 646 | | | a recovery token that the | 647 | | | Recovery Provider will accept. | 648 | +-------------------------------+-----------------------------------+ 649 | | save-token | URL of the save token API | 650 | | | endpoint defined in section 3 | 651 | +-------------------------------+-----------------------------------+ 652 | | save-token-async-api-iframe | URL of the save async token API | 653 | | | resource defined in section 3 | 654 | +-------------------------------+-----------------------------------+ 655 | | recover-account | URL of the account recovery API | 656 | | | endpoint defined in section 3 | 657 | +-------------------------------+-----------------------------------+ 658 | | privacy-policy | The URL of a data privacy policy | 659 | | | that describes how the issuer | 660 | | | handles user data related to | 661 | | | account recovery. | 662 | +-------------------------------+-----------------------------------+ 663 | | icon-152px | The URL of a 152x152 pixel PNG | 664 | | | file representing the issuer | 665 | +-------------------------------+-----------------------------------+ 666 | 667 | * NOTE: A Recovery Provider may also impose per-account limitations 668 | on the total storage or number of recovery tokens it allows. The 669 | token-max-size property only sets an upper bound on the length of a 670 | single token, and it may still reject tokens below this bound for 671 | reasons not discoverable in public configuration. 672 | 673 | An Account Provider MUST return the following information in a JSON 674 | dictionary comprising the entire response body: 675 | 676 | +-----------------------------+-------------------------------------+ 677 | | name | value | 678 | +-----------------------------+-------------------------------------+ 679 | | issuer | The RFC6454 ASCII Serialization of | 680 | | | the Origin to which this | 681 | | | configuration statement applies. | 682 | | | MUST have an https: scheme | 683 | | | component. | 684 | +-----------------------------+-------------------------------------+ 685 | | tokensign-pubkeys-secp256r1 | An array of ECDSA public keys on | 686 | | | the secp256r1 curve, encoded | 687 | | | uncompressed with the named curve | 688 | | | OID as per X9.62. An Account | 689 | | | Provider should not publish more | 690 | | | than two keys; enabling key | 691 | | | rotation with a small overlap | 692 | | | period is the primary purpose of | 693 | | | allowing more than one key to be | 694 | | | published. | 695 | +-----------------------------+-------------------------------------+ 696 | | save-token-return | URL of the save token return URL | 697 | | | defined in section 3 | 698 | +-----------------------------+-------------------------------------+ 699 | | recover-account-return | URL of the account recovery | 700 | | | callback API endpoint defined in | 701 | | | section 3 | 702 | +-----------------------------+-------------------------------------+ 703 | | privacy-policy | The URL of a data privacy policy | 704 | | | that describes how the issuer | 705 | | | handles user data related to | 706 | | | account recovery. | 707 | +-----------------------------+-------------------------------------+ 708 | | icon-152px | The URL of a 152x152 pixel PNG file | 709 | | | representing the issuer | 710 | +-----------------------------+-------------------------------------+ 711 | 712 | An origin that acts as both an Account and a Recovery provider MUST 713 | return a single JSON dictionary as the entire response body 714 | containing all required keys. 715 | 716 | URLs [RFC3986]MUST have a scheme component that is "https", a host 717 | component, and optionally, port and path components, and no query or 718 | fragment components. Note that no relationship can be assumed 719 | between the host component of the "issuer" input and those of of the 720 | URLs in the configuration. (e.g. "https://www.messenger.com" might 721 | have account recovery endpoints at "https://www.facebook.com") 722 | 723 | 3. Protocol Endpoints 724 | 725 | Each phase (establishing, and exercising, an account recovery 726 | capability) utilizes three protocol endpoints. (HTTP resources) 727 | 728 | All protocol endpoints MUST use the https:// scheme, and the protocol 729 | endpoint paths at the http:// scheme MUST NOT redirect to the 730 | https:// protocol, as this may mask configuration mistakes by 731 | clients. A GET or POST to protocol endpoint paths using the http:// 732 | scheme MUST yield an empty response body and an HTTP status code 401. 733 | 734 | When establishing a recovery capability, the following endpoints are 735 | used: 736 | 737 | o "Save Token" at the Recovery Provider is the endpoint to which the 738 | Account Provider will instruct the user agent to deliver the 739 | Recovery Token. 740 | 741 | o "Save Token Async IFrame API" is a URL from which an HTML resource 742 | supporting an async postMessage API for saving tokens can be 743 | loaded. 744 | 745 | o "Save Token Return" is the endpoint at the Account Provider where 746 | the Recovery Provider redirects the user agent after processing an 747 | invocation of the "Save Token" endpoint. 748 | 749 | When exercising a recovery capability, the following endpoints are 750 | used: 751 | 752 | o "Recover Account" at the Recovery Provider is the endpoint at 753 | which the User will initiate an account recovery action at an 754 | Account Provider. The User may be directed to this resource by 755 | the Recovery Provider, or the Account Provider may utilize 756 | published configuration to direct the User to this endpoint. 757 | 758 | o "Recover Account Return" is the endpoint at the Account Provider 759 | where the Recovery Provider redirects the user agent with a 760 | counter-signed recovery token to complete the recovery of their 761 | account 762 | 763 | Additionally, an Account Provider may optionally provide a "Token 764 | Status" endpoint at a well-known location to allow the Recovery 765 | Provider to provide direct status updates for tokens, such as the 766 | success or failure of saving a token, token deletion, or repudiation 767 | of the exercise of a recovery capability. 768 | 769 | 3.1. Save Token Endpoint 770 | 771 | "save-token" is used to interact with the Recovery Provider and save 772 | a recovery token for later use. The Recovery Provider MUST first 773 | authenticate the User. The way in which the Recovery Provider 774 | authenticates the User is beyond the scope of this specification. 775 | 776 | Save Token endpoints which expect to receive invocations by web user 777 | agents MUST support the HTTP "POST" method and SHOULD reject the HTTP 778 | "GET" method. 779 | 780 | If navigating from an Account Provider implemented as a native app to 781 | a general purpose web browser and POST is not available, the Account 782 | Provider SHOULD first navigate the user agent to a resource under its 783 | control and use that resource to perform the POST. 784 | 785 | The POST body MUST be "application/x-www-form-urlencoded" formatted. 786 | It MUST contain a parameter "token" containing the recovery token. 787 | 788 | The POST body MAY contain the additional parameter 'login_hint'. 789 | This value may be set to indicate the Account Provider's notion of 790 | the primary contact point for the user. A Recovery Provider might 791 | match this against the currently logged in user to determine what UI 792 | treatments, if any, to apply to confirm saving of the recovery token. 793 | 794 | The POST body MAY contain the additional parameter 795 | 'login_hint_sha256'. This value may be set to indicate the Account 796 | Provider's notion of the primary contact point for the user. A 797 | Recovery Provider might match this against the currently logged in 798 | user to determine what UI treatments, if any, to apply to confirm 799 | saving of the recovery token. The value should contain the base64 800 | encoded concatenation of a 256 bit random salt value with the binary 801 | output of the SHA-256 hashing algorithm applied to the concatenation 802 | of the salt and an octet string representing the ASCII serialization 803 | of the primary contact point hint for the user at the Account 804 | Provider. Use of 'login_hint_sha256', when compared to 'login_hint', 805 | allows matching without disclosure, but introduces the possibility 806 | that legitimate matches will not be discovered due to differences in 807 | how contact point hints are represented or canonicalized before 808 | hashing. 809 | 810 | The POST body MAY contain an additional parameter 'nickname_hint' to 811 | suggest a nickname for the account to which the token relates. 812 | 813 | The POST body MAY contain an additional parameter 'confirmation'. If 814 | set to the value 'required', this indicates to the Recovery Provider 815 | that it SHOULD show some form of interstitial explicitly informing 816 | the user that a token will be saved, with the option to decline. 817 | 818 | The POST body type MAY contain an additional parameter, 'obsoletes'. 819 | The value of the 'obsoletes' is a token id which the current token is 820 | intended to replace. If the user at the Recovery Provider has a 821 | saved token with an id and issuer matching this property, it should 822 | be deleted or marked as invalid if the new token is successfully 823 | saved. 824 | 825 | The POST body MAY contain an additional parameter 'state', the value 826 | of which will be passed to the 'save-token-return' endpoint, 827 | unmodified. 828 | 829 | 3.1.1. Processing Instructions 830 | 831 | When a user wishes to save a recovery token, the Account Provider 832 | takes the following processing steps: 833 | 834 | 1. Authenticate the User. The exact nature of how the Account 835 | Provider authenticates the User is beyond the scope of this 836 | specification. 837 | 838 | 2. Obtain and normalize an origin with an "https" scheme from the 839 | user indicating the domain of their chosen Recovery Provider. 840 | Users might indicate this choice by picking among pre-configured 841 | options, entering a domain name, or it might be inferred from the 842 | domain portion of an email address. 843 | 844 | 3. Retrieve the Recovery Provider configuration as described in 845 | Section 2. 846 | 847 | 4. If necessary configuration cannot be obtained, abort these steps. 848 | 849 | 5. Prepare a recovery token as described in Section 4. Use the 850 | 'issuer' field of the retrieved configuration as the value of the 851 | 'audience' field in the token. 852 | 853 | 6. The Account Provider may save the token_id and audience fields 854 | from the token associated with the User's account, to assist the 855 | user in completing a recovery process at a future time. 856 | 857 | 7. The Account Provider should have some method of mapping an issued 858 | recovery token to the original public key it was issued under and 859 | any key used to encrypt the opaque data, to be able to complete 860 | the protocol when the token is returned. This might be 861 | maintained as server-side state, or key ids might be encoded into 862 | the token_id field. 863 | 864 | 8. Instruct the user's agent to POST the token to the Save Token 865 | endpoint at the Recovery Provider. The Account Provider may 866 | choose to do this in a new browsing context. (e.g. a popup) 867 | 868 | Upon receiving an invocation of the Save Token endpoint the Recovery 869 | Provider takes the following processing steps: 870 | 871 | 1. Authenticate the User. The exact nature of how the Recovery 872 | Provider authenticates the User is beyond the scope of this 873 | specification. 874 | 875 | 2. Parse the token. 876 | 877 | 3. Validate that the version value is 0. 878 | 879 | 4. Validate that the type value is 0. 880 | 881 | 5. Retrieve the Account Provider configuration as described in 882 | Section 2 using the issuer field of the token as the subject. 883 | HTTP redirects SHOULD NOT be followed. 884 | 885 | 6. Validate that the value of the issuer field of the configuration 886 | matches the value of the issuer field of the recovery token. 887 | 888 | 7. Validate the signature over the token according to processing 889 | rules for the algorithm implied by the version. 890 | 891 | 8. Validate that the audience field of the token identifies an 892 | origin which the provider considers itself authoritative for. 893 | (Often the audience will be same-origin with the Recovery 894 | Provider, but other values may be acceptable, e.g. 895 | "https://mail.example.com" and "https://social.example.com" may 896 | be acceptable audiences for "https://recovery.example.com".) 897 | 898 | 9. Validate that the timestamp is fresh within an acceptable clock 899 | skew. 900 | 901 | 10. If a token binding is present or required, validate that it is 902 | acceptable. 903 | 904 | 11. Save the token for the User. The means by which a Recovery 905 | Provider saves the token is beyond the scope of this 906 | specification. 907 | 908 | 12. Because recovery tokens do not reveal the account name at the 909 | Account Provider, and because a User might have multiple 910 | accounts, Recovery Providers may give the User an option to add 911 | attach a nickname (e.g. "home", "work") or other means of 912 | identifying the account the token is associated with. 913 | 914 | 13. When the user has completed the operation successfully, or if 915 | the user aborted or abandoned the operation, or if the operation 916 | cannot be completed due to an unrecoverable error, if the 917 | token's "status_requested" field is 1, the Recovery Provider MAY 918 | invoke the Token Status endpoint "token-status" for the "save- 919 | success" or "save-failure" status, as appropriate, following the 920 | processing instructions for that operation described below. 921 | 922 | 14. Redirect the User or user agent to the "save-token-return" 923 | endpoint defined by the Account Provider configuration, 924 | including the GET parameter "status" set to the value "save- 925 | success" or "save-failure" to report whether a token was 926 | successfully saved, regardless of whether asynchronous status 927 | updates for the token were requested. 928 | 929 | 15. If a 'state' parameter was included with the original request, 930 | send its value, unmodified, as an additional parameter in the 931 | redirect. 932 | 933 | 3.2. Save Token Return Endpoint 934 | 935 | Save Token Return is used to return the User to the Account Provider 936 | after invoking Save Token at the Recovery Provider. 937 | 938 | Save Token Return endpoints MUST support both the HTTP "GET" and 939 | "POST" methods. 940 | 941 | Upon receiving an invocation of the Save Token Return endpoint the 942 | Recovery Provider may use the "status" parameter to report whether a 943 | token was successfully saved, regardless of whether asynchronous 944 | status updates for the token were requested. The 'state' parameter 945 | may be used, if needed, to determine the next action to be taken. 946 | 947 | 3.3. Save Token Async API Endpoint 948 | 949 | In order to facilitate greater control over the user experience for 950 | an Account Provider, or to expose advanced features, a Recovery 951 | Provider may optionally provide as part of its configuration a save- 952 | token-async-api-iframe URL. 953 | 954 | This URL may be used as the src attribute of an