Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
2008 lines (1567 sloc) 88.2 KB
Facebook, Inc. B. Hill, Ed.
Unofficial Draft Facebook, Inc.
October 26, 2017
Expires: April 29, 2018
Delegated Account Recovery
draft-hill-delegated-recovery
Abstract
Delegated Account Recovery 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 or
entity at a third party service provider.
Status of This Memo
This Unofficial Draft will expire on April 29, 2018.
Copyright Notice
Copyright (c) 2016-2017 Facebook, Inc. and the persons identified as
the document authors and published under the Creative Commons
Attribution 4.0 International license.
Table of Contents
1. Introduction
1.1. Notational Conventions
1.1.1. Presentation Language
1.2. Challenges with Existing Account Recovery Solutions
1.2.1. Recovery Questions
1.2.2. Password Hints
1.2.3. Email Recovery
1.2.4. Federated Authentication
1.2.5. Alternate Methods
1.3. Relationship to Other Protocols
1.4. Goals
1.5. Roles
1.6. Protocol Flow
1.6.1. Establishing a Delegated Recovery Capability
1.6.2. Exercising a Delegated Recovery Capability
1.7. TLS Version
1.8. HTTP Redirections
1.9. Application User Agents
2. Fetching Configuration
3. Protocol Endpoints
3.1. Save Token Endpoint
3.1.1. Processing Instructions
3.2. Save Token Return Endpoint
3.3. Save Token Async API Endpoint
3.3.1. Asynchronous Message Contract
3.4. Recover Account Endpoint
3.5. Recover Account Return Endpoint
3.6. Token Status Endpoint
3.6.1. Processing Instructions
3.6.2. Security Considerations
4. Token Generation
4.1. Recovery Token
4.1.1. Internal Structure
4.1.2. Opaque Data
4.1.3. Signature
4.2. Counter-Signed Recovery Token
4.2.1. Internal Structure
4.2.2. Counter-Signed Recovery Token Signature
5. Use in Key Recovery
6. Security Considerations
6.1. Deterministic Use of ECDSA
6.2. User Notification
6.3. Additional Verification
6.3.1. At the Recovery Provider
6.3.2. At the Account Provider
6.4. Low Friction Tokens and Delegated Multi-Factor
Authentication
6.5. Cross-Site Request Forgery
6.6. Breach Detection
6.7. Clock Skew
6.8. Key Loss and Compromise
6.9. TLS or HTTPS Certificate Compromise
6.10. Token Leakage
7. Implementation Notes
8. IANA Considerations
9. Acknowledgements
10. Normative References
Appendix A. Initial Algorithm Registry Contents
Author's Address
1. Introduction
1.1. Notational Conventions
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
[RFC2119].
1.1.1. Presentation Language
This document deals with the formatting of tokens in an external
representation using a casually defined syntax drawing from that used
in [RFC5246] and resembling the programming language "C". The
purpose is to document the binary token format only.
The basic numeric data type is an unsigned byte (uint8). All larger
numeric data types are formed from fixed-length series of bytes
concatenated from left to right and are also unsigned. The following
numeric types are predefined.
uint8 uint16[2];
uint8 uint32[4];
uint8 uint64[8];
All values, here and elsewhere in the specification, are stored in
network byte (big-endian) order; the uint32 represented by the hex
bytes 01 02 03 04 is equivalent to the decimal value 16909060.
The type string is defined as a concatenated sequence of octet
sequences representing ASCII characters, one per octet. [RFC3629]
The term URL is defined by reference to [RFC3986] in this document.
"URL" is used deliberately in preference to "URI" as all such objects
in this document are used to access network resources and such
objects as used by this document lack any persistent meaning after
the resource to which they refer ceases to exist.
1.2. Challenges with Existing Account Recovery Solutions
Network services that rely on user credentials must also cope with
the reality that users may forget or lose exclusive control of these
credentials. As a consequence, nearly every such service must
implement an alternate authentication process to enable a user to
recover control of an account. In practice, there are few good
options for doing this, and these recovery flows are often the
weakest link in securing accounts.
1.2.1. Recovery Questions
A common and self-contained method of account recovery is to ask the
user additional questions that they are less likely to forget the
answer to than a more arbitrary password. The same features that
make such a question useful for recovery also reduce its security:
o Things that are memorable may often not be fully private. Friends
and family members likely know the answers to many such questions,
and for highly public figures it may be possible to research this
information.
o Allowing users to select their own questions may result in
questions with a small possible domain of answers (favorite color,
favorite superhero) that make brute force guessing highly
effective, even if rate-limiting is applied.
o Choosing questions that are both secure and memorable is
difficult, and common choices of subject matter may not be
applicable across cultural contexts (mother's maiden name, name of
a pet), age ranges (first car) or other differentiating
characteristics of large and diverse audiences.
o The limited selection of questions which are both memorable and
applicable to the broadest possible audience makes re-use of these
questions and answers common among many service providers, with
attendant risks that disclosure of answers to a malicious party by
any provider may compromise many accounts at unrelated providers.
Furthermore it is difficult for a user to change their answers in
the event of such a compromise.
1.2.2. Password Hints
Password hints are extremely problematic - by definition they must be
revealed to an unauthenticated user, which implies reversibly
encrypted storage at best, reveals information about a password (or
often the password itself), and common hints at multiple services may
reveal where a password is reused, facilitating further attacks.
1.2.3. Email Recovery
Users are unlikely to forget their email address, and a common
practice is to email the user URL that encodes the ability to recover
the account. This is the most widely deployed mechanism at the time
of this writing, but it has a number of shortcomings.
o Forcing users to everywhere use an email address has privacy
implications, potentially allowing service providers to collude to
track individuals' activity across many domains.
o Email addresses are not universal, and are becoming less so.
Especially in the developing world or with younger audiences,
email may not be the first network service individuals provision
for themselves, if they provision it at all.
o Email addresses get recycled and reassigned to new owners.
o Users may use a weakly-secured email addresses when signing up for
a new service, for example an address maintained to collect the
unwanted commercial correspondence often expected to result from
signing up for a new online service.
o Email does not provide guarantees of deliverability or end-to-end
transport security. An adversary performing pervasive
surveillance may likely be able to abuse such weaknesses.
o Emails in large organizations are rarely private to their
recipient. In addition to the commonplace that high-value
accounts belonging to executives may be accessible by their
assistants, the contents and especially links in the email of
every user in a modern organization may commonly be logged for
legal discovery purposes, or crawled to identify malware and
phishing attacks.
o The capabilities of an emailed reset link must be encoded in the
GET string to ensure compatibility with non-HTML capable mail user
agents, and so may leak in the HTTP Referer header to any other
content included in a recovery page. (e.g. an analytics script
hosted at a third-party origin)
o Users are commonly authenticated to email services all the time on
many devices. Account recovery through email is an unstructured
process which does not ensure the user was strongly authenticated
for a high-risk action. A simple password compromise, or even
brief loss of control of an unlocked device where the user is
logged in, may be sufficient to transitively compromise many other
accounts of the user. If the only way to notify the user that
their account was reset is back through the same email channel, an
attacker can easily cover their tracks.
o The wide diversity of mail user agents means that even if account
recovery emails could be detected heuristically by providers or
explicitly identified with metadata from senders, it would be
remain difficult for email providers to apply special treatment to
such messages.
o An attacker that compromises a user's account may change the email
address associated with it. Without very carefully designed
processes, it may be impossible for the genuine user to recover
their account after such a change if recovery flows are purely
email-based.
o Email recovery flows cannot be used to recover capabilities, such
as cryptographic keys, that may be necessary to use an account
(e.g. a network-based file store that offers encrypted files) but
which the user does not want the account provider to have access
to at all times.
1.2.4. Federated Authentication
Federated systems for authentication take many forms and solve the
problem of account recovery (or at least delegate it implicitly to
the Identity Provider). However, after fifteen years of widespread
deployment of such systems, we see few mainstream services that are
willing to rely exclusively on federated logins for a variety of
reasons.
o A user may be unwilling to disclose their identity, other
information, or grant permissions to a new service they have just
begun to use and about which they have not yet formed an opinion
of its value or trustworthiness.
o A service may be unwilling to depend on a third-party for access
to its customer base. They may view "owning" their relationship
with the customer as having business value, may have a regulatory
mandate to do so, or may not want to be beholden to the
availability of a third party for their most important customer
interactions.
o A service may view providers of federated login services as
competitors or potential competitors, and not wish to disclose
information about how often users are logging on, who their most
active users are or not desire to show a competitor's logo as part
of their login process.
1.2.5. Alternate Methods
Methods do exist to strongly re-authenticate an account holder in the
absence of a password or other primary credential. Device-based or
multi-factor authentication, multi-device authentication, or trusted
connections in a social network are possibilities. Unfortunately, of
the potentially hundreds of services a user interacts with in a year,
only a few are likely able to leverage such factors. The rest will
lack the information, resources, and user consent needed.
Furthermore, the characteristics that make good recovery systems
strong also may make them unique to a particular service, preventing
broad adoption as a best practice by other providers.
1.3. Relationship to Other Protocols
Delegated Recovery is similar in some respects to OAuth [RFC5849]and
related protocols.
It is not constructed simply as a profile of one these protocols as
it relies on different trust semantics. Because tokens granting an
account recovery capability are expected to have an indefinite
lifetime and should be able to remain valid even following the
compromise and/or rotation of the keys they were originally issued
under, tokens in this protocol derive their authority at a point in
time from being signed with currently published public keys,
discoverable over HTTPS.
As this trust model is different than other protocols in the broad
OAuth family, profiling an existing protocol to fit these needs would
likely be considerably more complex than implementing a new,
minimalist protocol from scratch. As such, the latter approach has
been taken here.
1.4. Goals
Goals for Delegated Account Recovery include:
o Allow network services that do not have the resources or
information to build a secure and usable account recovery process
to delegate the function to network services that can.
o Allow users to choose to use service providers that can strongly
re-authenticate them to recover accounts at other services.
o Disclose as little information as possible, and no more than is
necessary, to protocol participants.
o As much as possible, require multiple points of failure in order
for accounts to be compromised through the recovery process.
o Be resilient in the face of compromises, including loss of
exclusive control of cryptographic key material, and allow re-
establishment of trust in stored recovery capabilities without
user action.
o Provide, through the protocol semantics, explicit information
about security-critical account actions and information flow
between providers to enable better auditing, anomaly detection and
remediation in the event of compromises.
o Allow users to set up a durable recovery capability when in
control of their account, which can be exercised even after
malicious changes to the account (such as changing an associated
email address or personal information) following a compromise.
1.5. Roles
Delegated Recovery defines three roles:
User
The entity in control of the accounts.
Account Provider
The network service at which a user has an account they need to
establish a recovery capability for.
Recovery Provider
The network service which offers the delegated account recovery
service, and at which a user has an account and wishes to use to
recover control of other accounts.
1.6. Protocol Flow
1.6.1. Establishing a Delegated Recovery Capability
+--------+ +------+ +----+---+
|Account | | User | |Recovery|
|Provider| | | |Provider|
| | | | | |
+-+------+ +--+---+ +----+---+
| | |
| 1. Select Recovery | |
| Provider | |
|<--------------------+ |
| | 2. Retrieve |
| | Configuration |
+---------------------------------------->|
|<----------------------------------------+
| | |
+----+ 3. Generate Recovery| |
| | Token | |
+--->| | |
| | |
| 4. Redirect User | |
| Agent to Recovery | |
| Provider with Token | |
+-------------------->+------------------>|
| | |
| | 5. (if needed) |
| | Authenticate User |
| |<------------------+
| +------------------>|
| | |
| | 6. Retrieve |
| | Configuration |
|<----------------------------------------+
+---------------------------------------->|
| | |
| (optional) | 7. Verify and +---+
| 8. Notify Account | Save Recovery | |
| Provider with | Token |<--+
| Result Code for | |
| token ID | |
|<----------------------------------------+
| | |
| 9. Redirect User | |
| Agent back to | |
| Account Provider | |
| | |
|<--------------------+<------------------+
| | |
| | |
V V V
Figure 1: Recovery Capability Establishment
The abstract Delegated Recovery capability establishment flow
illustrated in Figure 1 describes the interaction between the three
roles and includes the following steps:
1. The User, having already established control of an account with
the Account Provider, indicates to the Account Provider which
Recovery Provider they would like to use.
2. The Account Provider makes a GET request to determine if the
service of the user's choice offers the Delegated Recovery
service and what its protocol endpoint URLs are. This step may
be unnecesssary if the Account Provider already knows the
configuration for the chosen Recovery Provider.
3. The Account Provider generates a recovery token for the User and
Recovery Provider.
4. The Account Provider sends the Token to the User Agent with
instructions to deliver it to the Recovery Provider URL indicated
in the configuration.
5. Upon receiving the Token, the Recovery Provider authenticates the
user if they are not logged in.
6. The Recovery Provider makes a GET request to the Account Provider
to discover its public keys and protocol URLs.
7. The Recovery Provider validates the signature on the token and
saves it.
8. The Recovery Provider optionally notifies the Account Provider of
the status of the operation.
9. The Recovery Provider redirects the user agent back to the
callback URL indicated by the configuration with a status code.
1.6.2. Exercising a Delegated Recovery Capability
+--------+ +------+ +----+---+
|Account | | User | |Recovery|
|Provider| | | |Provider|
| | | | | |
+-+------+ +--+---+ +----+---+
| (optional) | |
| 1. Initiate Recovery| |
| | |
|<--------------------+ |
| | |
| | (optional) |
| | 2. Retrieve |
| | Configuration |
+---------------------------------------->|
|<----------------------------------------+
| | |
| (optional) | |
| 3. Offer User link | 1. Initiate |
| to Recovery Provider| Recovery |
| with origin hint | |
+-------------------->+------------------>|
| | |
| | 4. (if needed) |
| | Authenticate User |
| |<------------------+
| +------------------>|
| | |
| | 5. Retrieve |
| | Configuration |
|<----------------------------------------+
+---------------------------------------->|
| | |
| | 6. Retrieve and +---+
| 7. Send User | Counter-Sign | |
| Agent to Account | Recovery Token |<--+
| Provider with | |
| Counter-Signed | |
| Recovery Token | |
|<--------------------+<------------------+
| | |
| | 8. Retrieve |
| | Configuration |
+---------------------------------------->|
|<----------------------------------------+
| | |
+----+ 9. Validate | |
| | Recovery Token | |
+--->| | |
| | |
| | |
| 10. Restore Control | |
| of Account | |
|-------------------->| |
| | |
V V V
Figure 2: Exercising a Recovery Capability
The abstract flow depicting the exercising of a Delegated Recovery
capability in Figure 2 describes the interaction between the the
roles and includes the following steps:
1. The user initiates a recovery, either at the Account Provider,
or with the Recovery Provider.
2. (optional) the Account Provider GETs the current configuration
for the Recovery Provider to be used.
3. (optional) The Account Provider offers or redirects the user to
the Recovery Provider's endpoint, with a hint of the origin of
the account the User wants to recover.
4. The Recovery Provider authenticates the user appropriately for
conducting a recovery transaction.
5. The Recovery Provider makes a GET request to discover the
current URL for exercising recovery at the Account Provider.
6. The Recovery Provider counter-signs the token and additional
fields with its published key.
7. The Recovery Provider sends the user agent to the Account
Provider's recovery URL with the counter-signed token.
8. The Account Provider receives a token, and retrieves the
Recovery Provider's current configuration to discover its keys.
9. The Account Provider validates the counter-signature, additional
fields, its originally issued token, and takes any other
necessary steps to complete risk-appropriate re-authentication
of the user.
10. The Account Provider restores control of the account to the user
and allows a new primary authentication method or credential to
be established.
1.7. TLS Version
Whenever Transport Layer Security (TLS) is used by this
specification, the appropriate version (or versions) of TLS will vary
over time, based on the widespread deployment and known security
vulnerabilities. At the time of this writing, TLS version 1.2
[RFC5246]is the most recent and widely deployed version.
Implementations may also support additional transport-layer security
mechanisms that meet their security requirements.
1.8. HTTP Redirections
This specification makes extensive use of HTTP redirections, in which
the client or the authorization server directs the resource owner's
user-agent to another destination. While the examples in this
specification show the use of the HTTP 302 status code, any other
method available via the user-agent to accomplish this redirection is
allowed and is considered to be an implementation detail.
When retrieving configuration servers SHOULD NOT follow redirects to
reduce the risk of Server Side Request Forgery.
1.9. Application User Agents
This specification is written primarily for a general purpose web
browser as user agent but this is not the only possible
implementation choice. On some platforms, some of either or both of
the Account Provider and Recovery Provider functionality may be
provided as part of a dedicated, platform-native application, AKA an
"app". Generally, as the protocol aims to coordinate between
authenticated sessions at multiple service providers, the platform
standard web browser is the most standardized and convenient
mechanism available and should be preferred.
2. Fetching Configuration
Fetching Configuration is the process of determining the protocol
endpoints and public keys used by Account Providers and Recovery
Providers.
Service providers may indicate that configuration responses are
cacheable and may cache responses but cache lifetimes should be kept
reasonably short to enable timely responses to events such as key
compromise.
Fetching configuration begins by normalizing the service provider to
be used into an RFC6454[RFC6454] ASCII serialization of an Origin
with an "https" scheme.
Retrieval of the configuration is done using an HTTP "GET" request to
the provider's configuration endpoint at the following absolute path
relative to the https:// Origin.
"/.well-known/delegated-account-recovery/configuration"
The configuration resource path on the http:// scheme MUST NOT
redirect to the https:// protocol, as this may mask configuration
mistakes by consumers. Servers MUST return an empty response body
and an HTTP status code in the 400 range (401 is recommended) if
"/.well-known/delegated-account-recovery/configuration" is accessed
with the http:// scheme
When fetching configuration, service providers MUST NOT follow
redirects that do not use an https:// scheme. Service providers
generally should avoid utilizing redirects when returning
configuration responses. As it is not mandatory that the issuer
field or endpoints in a configuration agree with the origin of the
configuration URL, directly returning the canonical data rather than
a redirect reduces latency in the protocol.
A Recovery Provider MUST return the following information in a JSON
dictionary comprising the entire response body:
+-------------------------------+-----------------------------------+
| name | value |
+-------------------------------+-----------------------------------+
| issuer | the RFC6454 ASCII Serialization |
| | of the Origin to which this |
| | configuration statement applies. |
| | MUST have an https: scheme |
| | component. |
+-------------------------------+-----------------------------------+
| countersign-pubkeys-secp256r1 | An array of ECDSA public keys on |
| | the secp256r1 curve, encoded |
| | uncompressed with the named curve |
| | OID as per X9.62. The Recovery |
| | Provider should not publish more |
| | than two keys; enabling key |
| | rotation with a small overlap |
| | period is the primary purpose of |
| | allowing more than one key to be |
| | published. |
+-------------------------------+-----------------------------------+
| token-max-size | The maximum length, in bytes, of |
| | a recovery token that the |
| | Recovery Provider will accept. |
+-------------------------------+-----------------------------------+
| save-token | URL of the save token API |
| | endpoint defined in section 3 |
+-------------------------------+-----------------------------------+
| save-token-async-api-iframe | URL of the save async token API |
| | resource defined in section 3 |
+-------------------------------+-----------------------------------+
| recover-account | URL of the account recovery API |
| | endpoint defined in section 3 |
+-------------------------------+-----------------------------------+
| privacy-policy | The URL of a data privacy policy |
| | that describes how the issuer |
| | handles user data related to |
| | account recovery. |
+-------------------------------+-----------------------------------+
| icon-152px | The URL of a 152x152 pixel PNG |
| | file representing the issuer |
+-------------------------------+-----------------------------------+
* NOTE: A Recovery Provider may also impose per-account limitations
on the total storage or number of recovery tokens it allows. The
token-max-size property only sets an upper bound on the length of a
single token, and it may still reject tokens below this bound for
reasons not discoverable in public configuration.
An Account Provider MUST return the following information in a JSON
dictionary comprising the entire response body:
+-----------------------------+-------------------------------------+
| name | value |
+-----------------------------+-------------------------------------+
| issuer | The RFC6454 ASCII Serialization of |
| | the Origin to which this |
| | configuration statement applies. |
| | MUST have an https: scheme |
| | component. |
+-----------------------------+-------------------------------------+
| tokensign-pubkeys-secp256r1 | An array of ECDSA public keys on |
| | the secp256r1 curve, encoded |
| | uncompressed with the named curve |
| | OID as per X9.62. An Account |
| | Provider should not publish more |
| | than two keys; enabling key |
| | rotation with a small overlap |
| | period is the primary purpose of |
| | allowing more than one key to be |
| | published. |
+-----------------------------+-------------------------------------+
| save-token-return | URL of the save token return URL |
| | defined in section 3 |
+-----------------------------+-------------------------------------+
| recover-account-return | URL of the account recovery |
| | callback API endpoint defined in |
| | section 3 |
+-----------------------------+-------------------------------------+
| privacy-policy | The URL of a data privacy policy |
| | that describes how the issuer |
| | handles user data related to |
| | account recovery. |
+-----------------------------+-------------------------------------+
| icon-152px | The URL of a 152x152 pixel PNG file |
| | representing the issuer |
+-----------------------------+-------------------------------------+
An origin that acts as both an Account and a Recovery provider MUST
return a single JSON dictionary as the entire response body
containing all required keys.
URLs [RFC3986]MUST have a scheme component that is "https", a host
component, and optionally, port and path components, and no query or
fragment components. Note that no relationship can be assumed
between the host component of the "issuer" input and those of of the
URLs in the configuration. (e.g. "https://www.messenger.com" might
have account recovery endpoints at "https://www.facebook.com")
3. Protocol Endpoints
Each phase (establishing, and exercising, an account recovery
capability) utilizes three protocol endpoints. (HTTP resources)
All protocol endpoints MUST use the https:// scheme, and the protocol
endpoint paths at the http:// scheme MUST NOT redirect to the
https:// protocol, as this may mask configuration mistakes by
clients. A GET or POST to protocol endpoint paths using the http://
scheme MUST yield an empty response body and an HTTP status code 401.
When establishing a recovery capability, the following endpoints are
used:
o "Save Token" at the Recovery Provider is the endpoint to which the
Account Provider will instruct the user agent to deliver the
Recovery Token.
o "Save Token Async IFrame API" is a URL from which an HTML resource
supporting an async postMessage API for saving tokens can be
loaded.
o "Save Token Return" is the endpoint at the Account Provider where
the Recovery Provider redirects the user agent after processing an
invocation of the "Save Token" endpoint.
When exercising a recovery capability, the following endpoints are
used:
o "Recover Account" at the Recovery Provider is the endpoint at
which the User will initiate an account recovery action at an
Account Provider. The User may be directed to this resource by
the Recovery Provider, or the Account Provider may utilize
published configuration to direct the User to this endpoint.
o "Recover Account Return" is the endpoint at the Account Provider
where the Recovery Provider redirects the user agent with a
counter-signed recovery token to complete the recovery of their
account
Additionally, an Account Provider may optionally provide a "Token
Status" endpoint at a well-known location to allow the Recovery
Provider to provide direct status updates for tokens, such as the
success or failure of saving a token, token deletion, or repudiation
of the exercise of a recovery capability.
3.1. Save Token Endpoint
"save-token" is used to interact with the Recovery Provider and save
a recovery token for later use. The Recovery Provider MUST first
authenticate the User. The way in which the Recovery Provider
authenticates the User is beyond the scope of this specification.
Save Token endpoints which expect to receive invocations by web user
agents MUST support the HTTP "POST" method and SHOULD reject the HTTP
"GET" method.
If navigating from an Account Provider implemented as a native app to
a general purpose web browser and POST is not available, the Account
Provider SHOULD first navigate the user agent to a resource under its
control and use that resource to perform the POST.
The POST body MUST be "application/x-www-form-urlencoded" formatted.
It MUST contain a parameter "token" containing the recovery token.
The POST body MAY contain the additional parameter 'login_hint'.
This value may be set to indicate the Account Provider's notion of
the primary contact point for the user. A Recovery Provider might
match this against the currently logged in user to determine what UI
treatments, if any, to apply to confirm saving of the recovery token.
The POST body MAY contain the additional parameter
'login_hint_sha256'. This value may be set to indicate the Account
Provider's notion of the primary contact point for the user. A
Recovery Provider might match this against the currently logged in
user to determine what UI treatments, if any, to apply to confirm
saving of the recovery token. The value should contain the base64
encoded concatenation of a 256 bit random salt value with the binary
output of the SHA-256 hashing algorithm applied to the concatenation
of the salt and an octet string representing the ASCII serialization
of the primary contact point hint for the user at the Account
Provider. Use of 'login_hint_sha256', when compared to 'login_hint',
allows matching without disclosure, but introduces the possibility
that legitimate matches will not be discovered due to differences in
how contact point hints are represented or canonicalized before
hashing.
The POST body MAY contain an additional parameter 'nickname_hint' to
suggest a nickname for the account to which the token relates.
The POST body MAY contain an additional parameter 'confirmation'. If
set to the value 'required', this indicates to the Recovery Provider
that it SHOULD show some form of interstitial explicitly informing
the user that a token will be saved, with the option to decline.
The POST body type MAY contain an additional parameter, 'obsoletes'.
The value of the 'obsoletes' is a token id which the current token is
intended to replace. If the user at the Recovery Provider has a
saved token with an id and issuer matching this property, it should
be deleted or marked as invalid if the new token is successfully
saved.
The POST body MAY contain an additional parameter 'state', the value
of which will be passed to the 'save-token-return' endpoint,
unmodified.
3.1.1. Processing Instructions
When a user wishes to save a recovery token, the Account Provider
takes the following processing steps:
1. Authenticate the User. The exact nature of how the Account
Provider authenticates the User is beyond the scope of this
specification.
2. Obtain and normalize an origin with an "https" scheme from the
user indicating the domain of their chosen Recovery Provider.
Users might indicate this choice by picking among pre-configured
options, entering a domain name, or it might be inferred from the
domain portion of an email address.
3. Retrieve the Recovery Provider configuration as described in
Section 2.
4. If necessary configuration cannot be obtained, abort these steps.
5. Prepare a recovery token as described in Section 4. Use the
'issuer' field of the retrieved configuration as the value of the
'audience' field in the token.
6. The Account Provider may save the token_id and audience fields
from the token associated with the User's account, to assist the
user in completing a recovery process at a future time.
7. The Account Provider should have some method of mapping an issued
recovery token to the original public key it was issued under and
any key used to encrypt the opaque data, to be able to complete
the protocol when the token is returned. This might be
maintained as server-side state, or key ids might be encoded into
the token_id field.
8. Instruct the user's agent to POST the token to the Save Token
endpoint at the Recovery Provider. The Account Provider may
choose to do this in a new browsing context. (e.g. a popup)
Upon receiving an invocation of the Save Token endpoint the Recovery
Provider takes the following processing steps:
1. Authenticate the User. The exact nature of how the Recovery
Provider authenticates the User is beyond the scope of this
specification.
2. Parse the token.
3. Validate that the version value is 0.
4. Validate that the type value is 0.
5. Retrieve the Account Provider configuration as described in
Section 2 using the issuer field of the token as the subject.
HTTP redirects SHOULD NOT be followed.
6. Validate that the value of the issuer field of the configuration
matches the value of the issuer field of the recovery token.
7. Validate the signature over the token according to processing
rules for the algorithm implied by the version.
8. Validate that the audience field of the token identifies an
origin which the provider considers itself authoritative for.
(Often the audience will be same-origin with the Recovery
Provider, but other values may be acceptable, e.g.
"https://mail.example.com" and "https://social.example.com" may
be acceptable audiences for "https://recovery.example.com".)
9. Validate that the timestamp is fresh within an acceptable clock
skew.
10. If a token binding is present or required, validate that it is
acceptable.
11. Save the token for the User. The means by which a Recovery
Provider saves the token is beyond the scope of this
specification.
12. Because recovery tokens do not reveal the account name at the
Account Provider, and because a User might have multiple
accounts, Recovery Providers may give the User an option to add
attach a nickname (e.g. "home", "work") or other means of
identifying the account the token is associated with.
13. When the user has completed the operation successfully, or if
the user aborted or abandoned the operation, or if the operation
cannot be completed due to an unrecoverable error, if the
token's "status_requested" field is 1, the Recovery Provider MAY
invoke the Token Status endpoint "token-status" for the "save-
success" or "save-failure" status, as appropriate, following the
processing instructions for that operation described below.
14. Redirect the User or user agent to the "save-token-return"
endpoint defined by the Account Provider configuration,
including the GET parameter "status" set to the value "save-
success" or "save-failure" to report whether a token was
successfully saved, regardless of whether asynchronous status
updates for the token were requested.
15. If a 'state' parameter was included with the original request,
send its value, unmodified, as an additional parameter in the
redirect.
3.2. Save Token Return Endpoint
Save Token Return is used to return the User to the Account Provider
after invoking Save Token at the Recovery Provider.
Save Token Return endpoints MUST support both the HTTP "GET" and
"POST" methods.
Upon receiving an invocation of the Save Token Return endpoint the
Recovery Provider may use the "status" parameter to report whether a
token was successfully saved, regardless of whether asynchronous
status updates for the token were requested. The 'state' parameter
may be used, if needed, to determine the next action to be taken.
3.3. Save Token Async API Endpoint
In order to facilitate greater control over the user experience for
an Account Provider, or to expose advanced features, a Recovery
Provider may optionally provide as part of its configuration a save-
token-async-api-iframe URL.
This URL may be used as the src attribute of an <iframe> tag in an
HTML document. When loaded, the resource MUST expose an API based on
HTML cross-document messaging.
(https://html.spec.whatwg.org/multipage/comms.html#web-messaging)
The details of how such a resource communicates with services at the
Recovery Provider are not normatively specified by this document.
The normative API exposed is as follows:
3.3.1. Asynchronous Message Contract
The "message" argument to "postMessage()" MUST be a JSON object.
Messages related to this API MUST always contain the property
'delegated-account-recovery-api-message' with a value indicating the
type of the protocol message.
The following message types are defined by their literal string
values:
ready
Sent by API to parent to indicate it is ready to receive
messages.
save-token
Sent to API to initiate a token save operation that completes the
operation and returns results by navigating the parent frame.
save-token-no-navigation
Sent to API to initiate a token save operation. Calls of this
type MUST NOT result in the parent frame being navigated.
Results are returned with a 'save-token-result' message.
save-token-async-only
Sent to API to initiate a token save operation. Calls of this
type MUST NOT result in the parent frame being navigated.
Results are returned with a 'save-token-result' message.
save-token-result
Sent by API to parent frame to indicate completion status of a
'save-token-no-navigation' or 'save-token-async-only' message.
get-binding
Sent to API to retrieve a token binding.
binding
Sent by API to parent in response to a 'get-binding' message to
convey a token binding string.
For messages that elicit a response, the Account Provider may set an
'id' property on the message. If present, the Recovery Provider MUST
include its value as the value of the property 'in-reply-to' in the
correlated response.
The Account Provider SHOULD set the targetOrigin parameter to the
origin of the URL obtained from the Recovery Provider configuration,
to reduce the risk that messages will be visibile to unintended
recpiients.
On loading, the async API resource MUST post a message to its parent
of type 'ready'.
3.3.1.1. save-token message
This message type MUST have an additional property, 'token', that
contains the base64 encoded recovery token to be saved.
This message type MAY contain the additional property 'login_hint'.
These values may be set to indicate the Account Provider's notion of
the primary contact points for the user. A Recovery Provider might
match these against the currently logged in user to determine what UI
treatments, if any, to apply to confirm saving of the recovery token.
This message type MAY contain an additional property 'nickname_hint'
to suggest a nickname for the account to which the token relates.
This message type MAY contain an additional property 'state' which
will be passed, unmodified, as part of the redirect to the 'save-
token-return' endpoint.
This message type MAY contain an additional property, 'obsoletes'.
The value of the 'obsoletes' property is a token id which the current
token is intended to replace. If the user at the Recovery Provider
has a saved token with an id and issuer matching this property, it
should be deleted or marked as invalid if the new token is
successfully saved.
If no other keys are set on the message, the behavior of the Recovery
Provider iframe will be to process the message and navigate the
parent frame based on the results of that processing.
If the Recovery Provider needs to perform additional interactions
with the user to complete saving the token, (such as login,
confirmation of the save or collecting a token nickname) it can
redirect the parent window to whatever location is necessary to
complete the flow interactively at the Recovery Provider. It SHOULD
always attempt to return the user to the Account Provider's save-
token-return endpoint at the end of these flows, with the provided
'state' parameter, whether successful or not.
If the recovery token can be saved without user interaction, the
iframe SHOULD navigate the parent frame directly to the Account
Provider's save-token-return endpoint with the status parameter set
to 'save-success' and any 'state' parameter set.
3.3.1.2. save-token-no-navigation message
This message has identical arguments to the 'save-token' message.
It is processed identically, except it MUST NOT navigate the parent
frame. Instead, results are conveyed by it issuing a postMessage()
to its parent window with a message of type 'save-token-result' and a
'result' property.
This method may be preferred by a caller that wants to guarantee the
user isn't navigated away from a critical experience they are
interacting with, like an account creation funnel. The account
provider might choose to, e.g. open a popup with a POST directly to
the 'save-token' endpoint to complete any interaction with the
Recovery Provider if the value of 'result' is not 'save-success'.
The value of the 'state' property on the message, if set, is ignored.
3.3.1.3. save-token-async-only message
This message has identical arguments to the 'save-token' message.
It is processed identically, except that instead of navigating the
parent frame, it issues a postMessage() to its parent window
immediately after the message is accepted, with a message type of
'save-token-result' and a 'result' property. The only valid value
for the 'result' key in response to a 'save-token-async-only' message
is 'done'. No indication is provided of the success or failure of
the operation.
How a message is determined to be accepted is an implementation
detail at the discretion of the Recovery Provider. It might reject
messages locally (e.g. if it does not support silent acceptance for
this Account Provider or the user), it might dispatch them
immediately using an API like Beacon, if available, or it may need to
make an asynchronous HTTP request and wait for a response. It SHOULD
indicate "done" to the caller at the earliest practical moment.
This protocol message would typically be employed with a token that
sets the 'status-requested' flag and by an Account Provider that
keeps track of what recovery tokens have been recorded for an
account. It might be used to optimistically enroll users in recovery
as part of another action, with an offer to complete the flow
interactively at a later time made to users not successfully enrolled
asynchronously.
The value of the 'state' property on the message, if set, is ignored.
3.3.1.4. save-token-result message
This message is sent to the parent frame in response to a 'save-
token-no-navigation' or 'save-token-async-only' message.
This message contains a 'result' property. If sent in response to a
'save-token-no-navigation' message, the value of result will be
either 'save-token-success' or 'save-token-failure', indicating
whether the token was saved without user interaction. If sent in
response to a 'save-token-async-only' message, the value is always
'done', indicating when it is safe to navigate or otherwise destroy
the iframe hosting the API.
3.3.1.5. get-binding message
This message indicates a request for a token binding string from the
Recovery Provider. The reply contains a string that should be
treated as opaque by the receiver and placed into the 'binding' field
of a recovery token.
Bindings are optional according to this specification but individual
Recovery Providers MAY, at their discretion, require a token contain
a valid binding to be saved.
Bindings SHOULD be considered to be unique and single-use and the
string received in response to a call to 'get-binding' SHOULD NOT be
associated to more than one token.
This message has no arguments other than the optional 'id' for reply
correlation.
3.3.1.6. binding message
This message replies to a 'get-binding' message.
The API MUST provide a response to such a message. An empty string
is a valid binding string.
The property 'binding' of this message contains the binding string.
A recipient of this message SHOULD treat it as unique and single-use,
but the API implementation MAY return the same binding string for
multiple invocations at the same instance of the iframe resource.
3.3.1.7. Implementation Considerations
Recovery Providers are not required to process all APIs uniformly.
For example, a Recovery Provider might refuse to process 'save-token-
async-only' messages from certain issuers, or only attempt to process
them if the Account Provider is the canonical owner of the users's
primary contact point at the Recovery Provider. (e.g. a Recovery
Provider might silently accept a recovery token from
https://example.com only if it's own view of the authenticated user
had a confirmed email address at example.com)
3.3.1.8. Privacy Considerations
Implementers should take caution that the binding message does not
leak information about a user. It SHOULD NOT provide the same or a
correlatable response across different instances of the iframe
resource implementing the API, and SHOULD NOT provide bindings that
are distinguishable by callers based on user state or properties.
(logged in, user identifier, user IP address, etc)
3.4. Recover Account Endpoint
The Recover Account endpoint is used to exercise a saved recovery
capability.
A user may arrive at the Recover Account Endpoint in at least two
ways:
o The user deliberately visits the Recovery Provider and requests,
through a means outside the scope of this specification, to view
all of their saved tokens or those for a particular Account
Provider.
o The User visits the Account Provider and is unable to
authenticate. As part of an account recovery flow, the Account
Provider sends the user to this endpoint at the Recovery Provider.
Recover Account endpoints MUST support both the HTTP GET and POST
methods.
A query string or "application/x-www-form-urlencoded" formatted POST
body MAY be provided. If a query string is provided, it MAY contain
the parameter "issuer" set to the origin of the Account Provider and/
or a "id" parameter set to the hex value of a token_id. These
parameters can be used by the Recovery Provider to guide the user in
selecting the correct token. For example, if used as part of a
cryptographic key recovery ceremony, it may be necessary to select a
specific token among several the user has saved from a given issuer.
Upon receiving an invocation of the Recover Account endpoint the
Recovery Provider takes the following processing steps:
1. Authenticate the user. The exact nature of how the Recovery
Provider authenticates the user is beyond the scope of this
specification.
2. Select a token to exercise, based on some combination of user
choice and input parameters.
3. Retrieve the configuration for the token issuer as described in
Section 2.
4. Create a counter-signed token as described in Section 4 and sign
the token according to the algorithm's requirement.
5. Redirect the user agent to the "recover-account-return" endpoint
defined by the Account Provider configuration. The "application/
x-www-form-urlencoded" formatted POST body should include the
parameter "countersigned-token" set to the countersigned token.
6. The Recovery Provider should notify the user, via an out-of-band
means, that a recovery token has been exercised, for which domain
and nickname, if applicable.
7. If any of these steps fails, abort the algorithm.
3.5. Recover Account Return Endpoint
The Recover Account Return endpoint is used to return the User to the
Account Provider after invoking Recover Account at the Recovery
Provider.
Recover Account Return endpoints MUST support the HTTP POST and
SHOULD reject the HTTP GET method.
If navigating from a Recovery Provider implemented as a native app to
a general purpose web browser and POST is not available, the Recovery
Provider SHOULD first navigate the user agent to a resource under its
control and use that resource to perform the POST.
The POST body MUST be "application/x-www-form-urlencoded" formatted.
It must contain the query parameter "countersigned-token" containing
the countersigned recovery token.
Upon receiving an invocation of the Recover Account Return endpoint
the Account Provider takes the following processing steps:
1. Parse the countersigned-token.
2. Validate that the version field is 0.
3. Validate that the type field is 1.
4. De-serialize the original recovery token from the data field.
5. Validate the signature on the original recovery token.
6. Validate the issuer field is present in the countersigned-token,
and that it matches the audience field in the original token.
7. Validate that the timestamp is fresh within an acceptable closk
skew.
8. Validate the token binding for the countersigned token, if
present. (the token binding for the inner token is not relevant)
9. Optionally, validate that a token with this id has not been
recently used to recover this account, as an additional
protection against replay attacks.
10. Retrieve the current Recovery Provider configuration as
described in Section 2. HTTP redirects SHOULD NOT be followed
when retrieving the configuration.
11. Validate that the issuer field of the retrieved configuration
matches that of the counter-signed token.
12. Validate that the counter-signed token signature validates with
a current element of the "countersign-pubkeys-secp256r1" array.
13. Decrypt the data field from the original recovery token and
parse its information, if present.
14. Apply any additional processing which provider-specific data in
the opaque data portion may indicate is necessary.
15. If all steps have completed successfully, the recovery token may
be considered to have been successfully applied. At this point
the Account Provider may restore control of the account to the
user. The details of that process are beyond the scope of this
specification. An Account Provider may consider the completion
of this algorithm as only a single factor in a risk-based
assessment relating to account recovery and may require
additional steps to complete the process. Such decisions and
steps are beyond the scope of this specification.
16. The Account Provider should make a permanent record of the
recovery noting the Recovery Provider and time of recovery, to
remediate fraudulent recoveries in the event that a compromise
is subsequently determined to have occurred at the Recovery
Provider.
17. The Account Provider should notify the User via an out-of-band
means that an account recovery has occurred.
3.6. Token Status Endpoint
The Token Status endpoint is used by the Recovery Provider to notify
the Account Provider about the current status of a particular token
in the following cases:
1. When a new token is first saved, or fails to save, at the
Recovery Provider.
2. When a token is deleted at the Recovery Provider, or when the
associated account at the Recovery Provider is deleted or
deactivated.
3. When a token save or recovery action is repudiated by the holder
of a token at the Recovery Provider.
The Token Status Callback MUST be hosted at the following well known
location, relative to the server root of the https origin of the
Account Provider in the token.
/.well-known/delegated-account-recovery/token-status
Token Callback endpoints MUST support both the HTTP "POST" and "GET"
methods.
3.6.1. Processing Instructions
Support for Token Status Callbacks is optional for both the Account
Provider and Recovery Provider.
If an Account Provider wishes to receive Token Status Callbacks it
MUST set the "status_requested" field of the recovery token to 1.
If an Account Provider does not intend to take action based on Token
Status Callbacks or wishes to provide additional unlinkability and
privacy guarantees for a token it SHOULD set the "status_requested"
field to 0.
The following token lifecycle events can be reported to an Account
Provider by a Recovery Provider:
o "save-success" reports that a token has been successfully saved
with the Recovery Provider.
o "save-failure" reports that a token was sent to the Recovery
Provider but was not saved.
o "deleted" reports that the user has deleted the token at the
Recovery Provider. The Account Provider may want to prompt the
user to establish a new account recovery capability if the deleted
token was the only one associated with the account.
o "token-repudiated" reports that a user has informed the Recovery
Provider that a token was associated with their account without
their consent.
o "recovery-repudiated" reports that a user has informed the
Recovery Provider that a recovery action was initiated with a
token without their consent.
When sending a lifecycle event, the Recovery Provider invokes the
well-known endpoint with a "application/x-www-form-urlencoded"
formatted "POST" body including the parameter "id" set to the hex-
encoded value of the "token_id" field of the recovery token, and the
parameter "status" set to the literal ASCII string of the status
event from the above enumeration. (e.g. "save-success" or "deleted")
If the event being reported is "recovery-repudiated" the Recovery
Provider SHOULD also include a parameter, "countersigned_id", set to
the hex-encoded value of the "token_id" field for the countersigned
recovery token associated with the recovery action being repudiated.
3.6.2. Security Considerations
Because the Token Status Callback is a direct, server-to-server call,
hosting this endpoint only at a well-known location reduces the risk
of Server-Side Request Forgery.
Although the recommended entropy in the token id should make brute-
force of fraudulent events difficult, Account Providers might choose
to only request status callbacks from known Recovery Providers and
only accept requests from known IP ranges or require additional
authentication mechanisms beyond the scope of this protocol to
mitigate risks of forgery and denial-of-service with such requests.
4. Token Generation
4.1. Recovery Token
A Recovery Token is a credential representing the ability to recover
control of an account. It is defined as:
token = base64(token_internals || token_signature)
4.1.1. Internal Structure
The internal contents of a token are as follows:
token_internals = struct {
uint8 version
uint8 type
byte[16] token_id
uint8 options
uint16 issuer_length
string issuer[issuer_length]
uint16 audience_length
string audience[audience_length]
unit16 issued_time_length
string issued_time[issued_time_length]
uint16 data_length
opaque data[data_length]
uint16 binding_length
opaque binding[binding_length]
}
version
Version identifier. For this version of the protocol, the value
MUST be 0.
type
Message type. For the recovery token, the type is 0.
token_id
Token identifier. The identifier SHOULD contain at least 96 bits
of entropy. Because tokens may persist for a very long time,
issuers may wish to use a portion of the token_id field to encode
an identifier for the keys used originally to sign the token and
encrypt its data, to assist in revalidation in the event that
rotations of those keys have occurred since the token was
originally issued.
options
Token options bit flags
0x01: Status Requested
Set bit 0 to request the Recovery Provider make status
callbacks, if supported.
0x02: Low Friction Requested
Set bit 1 to request the Recovery Provider apply lower
friction verification during recovery, if supported.
0x04, 0x08, 0x10, 0x20, 0x40, 0x80:
RESERVED
issuer_length
Length of the issuer field.
issuer
The ASCII serialization of the Account Provider's Origin
[RFC6454]
audience_length
Length of the audience field.
audience
The contents of the issuer field in the Recovery Provider's
published configuration.
issued_time_length
Length of the issued_time field.
issued_time
The ASCII serialization of the time the token was issued,
represented as an ISO 8601 [ISO.8601.1988]Internet Date/Time
using the 'date-time' ABNF defined by RFC3339. [RFC3339]
data_length
Length of the data.
data
Opaque data.
binding_length
Length of the binding.
binding
Opaque token binding identifier obtained from the get-token
endpoint.
4.1.2. Opaque Data
The opaque data contains information that the Account Provider needs
to validate and restore control of an account, but which should not
be shared with the Recovery Provider. It MUST be encrypted to
prevent disclosure of its internal structure.
Because it is encrypted and opaque, it may contain whatever
information in whatever format the Account Provider feels is
necessary and appropriate, but any information beyond that specified
for inclusion in the outer token MUST be placed in the encrypted
portion and protected from disclosure to the Recovery Provider.
Recovery Providers MAY reject a token that is too large.
The choice of algorithm and key management is left to the discretion
of the Account Provider.
A recovery token may still be usable even if an attacker obtains the
key used to encrypt the opaque data, (though user privacy may be
compromised) but if the Account Provider loses this key (and the
ability to decrypt the token data) the account recovery capability
will be lost.
4.1.3. Signature
token_signature is a signature over the token_internals octet string
as defined according to the version field, with the private key
corresponding to the public key for the Recovery Provider currently
published as part of its configuration.
For this version (0) of the protocol, this is ECDSA over the SHA256
hash of the token_internals octet string. The signature is encoded
as DER-encoded ASN.1 structure (a SEQUENCE of two INTEGERs, for r and
s, in that order).
4.2. Counter-Signed Recovery Token
A Counter-Signed Recovery Token is a credential representing the
Recovery Provider's re-authentication of the account holder who
originally saved the Recovery Token it contains. It is defined as:
token = base64(countersigned_token_internals ||
countersigned_token_signature)
4.2.1. Internal Structure
The internal contents of a countersigned token are as follows:
countersigned_token_internals = struct {
uint8 version
uint8 type
byte[16] token_id
uint8 options
uint16 issuer_length
string issuer[issuer_length]
uint16 audience_length
string audience[audience_length]
uint16 issued_time_length
string issued_time[issued_time_length]
uint16 data_length
opaque data[data_length]
uint16 binding_length
opaque binding[binding_length]
}
version
Version identifier. For this version of the protocol, the value
MUST be 0.
type
Message type. For the countersigned recovery token, the type is
01.
token_id
Token identifier. This SHOULD contain at least 96 bits of
entropy.
options
Token options bit flags
0x01: Status Requested
Bit 0 must not be set in Countersigned Recovery Tokens.
0x02: Low Friction Applied
Set bit 1 to indicate to the Account Provider that the
account holder was re-authenticated with low assurance,
either because the inner Recovery Token requested low
friction or because stronger challenges were not available.
0x04, 0x08, 0x10, 0x20, 0x40, 0x80:
RESERVED
issuer_length
Length of the issuer field.
issuer
The ASCII serialization of the Account Provider's Origin
[RFC6454]
audience_length
Length of the audience field.
audience
This SHOULD repeat the contents of the inner recovery token's
issuer field.
issued_time_length
Length of the issued_time field.
issued_time
The ASCII serialization of the time this token was issued,
represented as an ISO 8601 [ISO.8601.1988]Internet Date/Time
using the 'date-time' ABNF defined by RFC3339. [RFC3339]
data_length
Length of the data.
data
The octet string of the original (token_internals ||
token_signature) as received by the Recovery Provider. (after
base64 decoding)
binding_length
Length of the token binding id.
binding
Opaque token binding id obtained from the get-binding endpoint.
4.2.2. Counter-Signed Recovery Token Signature
countersigned_token_signature is a signature over the
countersigned_token_internals octet string as defined according to
the algorithm field, with the private key corresponding to the public
key for the Recovery Provider currently published as part of its
configuration.
For this version of the protocol (0), the algorithm is ECDSA over the
SHA256 hash of the countersigned_token_internals octet string. The
signature is encoded as DER-encoded ASN.1 structure (a SEQUENCE of
two INTEGERs, for r and s, in that order)
5. Use in Key Recovery
This protocol, in addition to allowing recovery of accounts in a
delegated fashion, may be used to recover other capabilities, like a
recovery key for encrypted email or files. For example, the provider
of a an encryption service might use a threshold cryptosystem to
break a key into several parts, and ask the user to store the pieces
(encoded in the opaque data field) as account recovery tokens at
several providers. If the user loses their own copy of the key, they
can still recover it, but the backup is not subject to server-side
compromise by any single entity.
6. Security Considerations
6.1. Deterministic Use of ECDSA
As even slight biases in the selection of the random value k used by
ECDSA can lead to a key compromise. As such, implementers SHOULD
follow the method described in [RFC5246] for generating deterministic
values of k.
6.2. User Notification
Users should be notified, by both the Recovery Provider and Account
Provider, whenever a recovery capability is exercised, in order to
provide an opportunity to react if they did not initiate the action.
Out-of-band means (email, instant message, SMS, etc.) should be
preferred to reduce the opportunity for an attacker in control of a
user's account to remove such signals.
6.3. Additional Verification
6.3.1. At the Recovery Provider
An explicit goal of this specification is that account recovery
operations can be explicitly recognized as high-risk operations and
subject to additional authentication controls by a Recovery Provider.
Recovery Providers should treat the exercising of a recovery
capability as a high risk action and require a high degree of
confidence in the user's authentication to perform it. The nature of
this is application-specific at each Recovery Provider.
6.3.1.1. Session Fixation
To achieve a convenient and privacy-preserving user experience many
Recovery Providers will rely on the ambient authority of the user's
browser (e.g. cookies) to associate a recovery token to their
account. If an attacker can execute a session fixation attack on a
user, in which the user is unknowingly logged out of their account
and logged in to a different account under the control of an attacker
(e.g. through a logout/login CSRF attack), and then convince the user
to save an account recovery token, the attacker may be able to use
that to take control of the account for which the token grants a
recovery capability.
To mitigate this risk, Recovery Providers should take precautions to
prevent Cross-Site Request Forgery against login/logout endpoints.
Recovery Providers may also wish to track, for example through
persistent cookies, which user agents have been used with multiple
accounts, and require additional confirmation that the user is aware
of the current logged in user state before saving a recovery token.
6.3.2. At the Account Provider
This specification does not mandate that a counter-signed recovery
token be the exclusive means by which an Account Provider allows
restoring control or resetting the credentials of an account. They
may treat it as only one authentication signal among many possible or
necessary ones. Resetting a high-value account might require, e.g.
multiple instances of this protocol to be completed with independent
Recovery Providers, or make use of additional authentication factors
exclusively at the Account Provider.
Whether to accept or reject a presented counter-signed recovery token
is always at the discretion of the Account Provider. Use of this
protocol does not imply any contract or obligation to honor any
previously saved recovery capability.
The opaque data field can be also be used to encapsulate additional
information to use in strengthening the process. For example, a
traditional account recovery "secret question" and its answer might
be encoded into this data. This implementation reduces many of the
risks of such questions, as they cannot be seen or brute-force
guessed by an attacker that has not already compromised the user's
account at the Recovery Provider, and the content of such question /
answer sets cannot leak through a data breach at either the Recovery
or Account Provider individually.
If a user recovers their account following a period of compromise,
the Account Provider should take precautions to invalidate any new
recovery tokens that may have been issued during the compromise
period.
6.4. Low Friction Tokens and Delegated Multi-Factor Authentication
Generally, recovering an account is a high-security event, and a key
advantage of this protocol is that it identifies recoveries
explicitly, so they may have appropriate re-authentication and rate
limiting applied by a Recovery Provider.
However, the ability to anonymously attest continuity of control of
an account at an external source has other uses beyond recovering
account using this protocol as the sole source of evidence.
If an Account Provider sets the "Low Friction" bit in the token
options bitflag, it is indicating to the Recovery Provider that the
token will not be treated as a single authentication factor, and so
request that ease of use in "recovery" be prioritized over additional
security measures or strict rate limting. In this mode, the protcol
may be used as a generalized part of a multi-factor authentication
solution, replacing solutions like one-time passwords with a
decentralized mesh of user accounts.
When a Recovery Provider receives a token with the Low Friction flag
set, it SHOULD adjust rate limts and re-authentication strategies to
prioritize user success and ease of use above the level of
authentication assurance. It SHOULD then set the same flag in the
Countersigned Token it issues.
Additionally, a Recovery Provider MAY use the Low Friction flag in a
Countersigned Token to indicate to an Account Provider that, despite
best efforts for a Recovery Token where the Low Friction flag was not
set, a strong level of authentication assurance was not possible. It
is at the discretion of the Recovery Provider exactly what this
means, but suggested that this flag be set when the level of
authentication possible was no stronger than username/password. This
SHOULD only be used when stronger challenges are not available due to
the configuration of the account at the Recovery Provider. If a
strong authentication challenge was available but could not be
completed, the Recovery Provider should not issue a Countersigned
Token.
6.5. Cross-Site Request Forgery
Many web application endpoints require an unforgeable token be sent
as part of any HTTP POST to prevent Cross-Site Request Forgery (CSRF)
attacks from abusing the ambient authority represented by cookies or
other implicit credentials sent by a web user agent.
Because the architecture of Delegated Account Recovery relies on
deliberate cross-origin POSTs, normal protections of this sort cannot
be applied to the endpoints specified by this specification.
To prevent abuse, both Account and Recovery Providers should require
explicit user confirmation of actions in pages that contain anti-
automation measures, e.g. by setting an X-Frame-Options header
[RFC7034] or Content-Security-Policy "frame-ancestors" directive to
prevent clickjacking attacks.
Initiating sending a recovery token to a recovery provider should be
protected against Cross-Site Request Forgery and clickjacking, to
prevent users being tricked into sending tokens to fraudulent
providers. Account Providers may want to take special measures to
require unforgeable user consent or block entirely the delegation of
tokens to low-reputation Recovery Providers.
6.6. Breach Detection
Participants should monitor rates at which recovery capabilities are
exercised and rates at which users report unauthorized exercising of
recovery capabilities. A high rate of unauthorized recovery actions
initiated at a given Recovery Provider may indicate a compromised or
malicious provider. Both Recovery and Account Providers should
publish contact information for use in incident reporting and
response. Verification of token bindings and issued_time freshness
should also be performed to prevent disclosed tokens from being re-
associated to new accounts at a Recovery Provider.
6.7. Clock Skew
This protocol relies on comparison of timestamps from different
network servers as a defense-in-depth measure to prevent re-use of
leaked tokens, in particular re-association of a leaked token with a
different account at the same audience server. Although client clock
skews are a frequent issue for protocols with such dependencies, this
protocol only depends on reasonable clock synchronization between
servers, never the user-managed client clock. Participating servers
in this protocol should endeavor to issue tokens as close in time to
when they will be transmitted as possible and should take steps to
reduce their own clock skew, for example, by periodic synchronization
with standardized Internet time sources. The specifics of such
mechanisms are beyond the scope of this document.
6.8. Key Loss and Compromise
This protocol involves three keys: the public/private key pairs of
the Account and Recovery Providers, and whatever key the Account
Provider uses to encrypt the opaque data. Additionally, the recovery
tokens themselves convey some security capability. The protocol can
offer some resilience to loss or compromise of these keys and
artifacts.
If the Recovery Provider's key is compromised, it should publicize
the window in which it was compromised, and should notify Account
Providers with whom recovery capabilities were exercised during the
window of compromise. Mechanisms to communicate this are outside the
scope of this protocol. If notified by a Recovery Provider of a key
compromise, Account Providers should identify recovery capabilities
exercised from that provider during the window of compromise and
perform additional diligence for the security of those accounts.
Generally, if only the Recovery Provider's key is compromised, but
not the Recovery Provider's other infrastructure around this protocol
(e.g. if a key was generated using weak entropy but other operational
procedures were sound) then no attack is possible, since an attacker
must have both a genuine recovery token and the counter-signing key
to take over a user's account. Rotation of the published key is
sufficient to restore trust for the purposes of this protocol.
Stored recovery tokens do not need to be re-issued.
If a set of recovery tokens leak from a Recovery Provider, they do
not convey any capability without also being countersigned by the
Recovery Provider's key, and they by themselves convey no personally
identifying information about the account to which they apply. So
long as the Recovery Provider's published key remains secure, leaked
recovery tokens do not need to be distrusted or re-issued.
Verification of token bindings and refusal of tokens with a stale
"issued_time" prior to saving any recovery token can prevent leaked
tokens from being re-added to different accounts under an attacker's
control at the same Recovery Provider.
If an Account Provider loses control of only its token signing key,
this conveys limited capabilities to the attacker. It can cause
false tokens to be stored by a Recovery Provider, but only at an
account it also controls at the Recovery Provider, and will not have
the ability to forge the opaque data. To ensure this resistance, the
opaque data field should be encrypted using an AEAD mode or other
encrypt-then-MAC construction to prevent it from being malleable.
If an Account Provider loses its data encryption keys, tokens issued
under those keys will be unusable.
6.9. TLS or HTTPS Certificate Compromise
This protocol depends on TLS, HTTPS and the Web PKI to bootstrap its
self-organizing trust framework using HTTPS to distribute keys.
Because end-users' communication with the network service providers
in question, including transmission of credentials and session
management material, also are almost always dependent on TLS and the
HTTPS Web PKI, there is little value in attempting to eliminate this
as part of the trusted computing base for this specification.
Account and Recovery Providers should be cautious in the management
of the root certification authorities they trust when performing
configuration discovery operations over HTTPS, should use the latest
practical TLS version and should terminate the protocol without user
recourse if any errors are encountered. Participants may want to
employ additional means to reduce the risk of compromised HTTPS
connections that are beyond the scope of this document, such as HTTP
Public Key Pinning [RFC7469] and Certificate Transparency. [RFC6962]
6.10. Token Leakage
It may be possible that recovery tokens leak to third parties. Use
of the POST method and endpoints which are either well-known or
discovered from the configuration are intended as countermeasures.
Protocol participants should take additional precautions against
token leaks in their application-specific logic, such as avoiding
moving tokens from POST to GET parameters in cleartext during a login
flow prior to saving a token.
Use of a token binding can reduce these risks.
7. Implementation Notes
This section is non-normative.
Software platforms may represent Elliptic Curve public keys
differently. The configuration encoding required by this
specification is the format used by OpenSSL's Elliptic Curve
implementation (X9.62 / RFC 3280), which uses the alias "prime256v1"
to refer to the NIST secp256r1 curve. Some software only expects a
"raw" ECPoint representation as a public key. If your software's EC
public key representation is 65 octets long and begins with 0x04,
this is a raw ECPoint. Because they are of fixed length, these raw
points can be converted to the ASN.1 encoded form required by this
specification by simply prefixing the following 26 octets to the
buffer:
[48, 89, 48, 19, 6, 7, 42, 134, 72, 206, 61, 2, 1, 6, 8, 42, 134, 72, 206,
61, 3, 1, 7, 3, 66, 0]
8. IANA Considerations
Future revisions to this protocol may use a registry to map supported
cryptographic algorithms to the token version indiator.
9. Acknowledgements
The author would like to thank Andrey Labunets, Neil Matatall and
Patrick Toomey for their valuable contributions.
10. Normative References
[ISO.8601.1988]
International Organization for Standardization, "Data
elements and interchange formats - Information interchange
- Representation of dates and times", ISO Standard 8601,
June 1988.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
2003, <https://www.rfc-editor.org/info/rfc3629>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246,
DOI 10.17487/RFC5246, August 2008,
<https://www.rfc-editor.org/info/rfc5246>.
[RFC5480] Turner, S., Brown, D., Yiu, K., Housley, R., and T. Polk,
"Elliptic Curve Cryptography Subject Public Key
Information", RFC 5480, DOI 10.17487/RFC5480, March 2009,
<https://www.rfc-editor.org/info/rfc5480>.
[RFC5849] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol", RFC 5849,
DOI 10.17487/RFC5849, April 2010,
<https://www.rfc-editor.org/info/rfc5849>.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011,
<https://www.rfc-editor.org/info/rfc6454>.
[RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate
Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013,
<https://www.rfc-editor.org/info/rfc6962>.
[RFC7034] Ross, D. and T. Gondrom, "HTTP Header Field X-Frame-
Options", RFC 7034, DOI 10.17487/RFC7034, October 2013,
<https://www.rfc-editor.org/info/rfc7034>.
[RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning
Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469, April
2015, <https://www.rfc-editor.org/info/rfc7469>.
[X9.62] American National Standards Institute (ANSI), "ANS
X9.62-2005: The Elliptic Curve Digital Signature Algorithm
(ECDSA)", 2005.
Appendix A. Initial Algorithm Registry Contents
properties
+-------+---------------------------------------+-------------------+
| value | algorithm | references |
+-------+---------------------------------------+-------------------+
| 0 | ECDSA-SHA256 on the secp256r1 named | [X9.62] [RFC5480] |
| | curve | |
+-------+---------------------------------------+-------------------+
Author's Address
Brad Hill (editor)
Facebook, Inc.
EMail: hillbrad@fb.com
You can’t perform that action at this time.