| TOC |
This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 25, 2011.
This document describes a mechanism for domains to create ad-hoc, verified associations and then using these associations to enable user-to-user communication between domains. The protocol defined herein provides a generalized mechanism for communication between entities on different domains, but is intended primarily as a means to allow social network users to interact across network and application boundaries.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].
1.
Introduction
1.1.
Overview
2.
Addressing Scheme
2.1.
Overview
2.2.
Domain Identifier
2.3.
Entity Identifier
3.
Retrieving the Discovery Document for a Domain
3.1.
Overview
4.
Establishing Domain Associations with Domain Dialback
4.1.
Overview
4.2.
Determining the URL of a Domain's Association Endpoint
4.3.
Requesting an Association
4.4.
Verifying an Incoming Association Request
4.5.
Responding to the Association Request
5.
Establishing Domain Associations with pre-determined credentials
5.1.
Overview
6.
Other Mechanisms for Establishing Domain Associations
7.
HTTP Message Extensions
7.1.
Overview
7.2.
The DFPEntity Authentication Scheme
8.
Security Considerations
8.1.
Considerations for Domain Dialback
9.
Acknowledgements
10.
Normative References
§
Author's Address
| TOC |
| TOC |
The Domain Federation Protocol (DFP) is a protocol for federated communication between users or other entities on different domains. This protocol creates a verified, unidirectional association between two domains and establishes a means of identifying users or other entities within these domains, with the goal of enabling social networking interactions between said entities.
DFP is built on similar architectural principles to the Simple Mail Transfer Protocol (SMTP) and the Extensible Messaging and Presence Protocol (XMPP), but adapts the architectural model for use by applications communicating exclusively by Hypertext Transfer Protocol (HTTP) messages.
This protocol is designed primarily for use in asychronous, background communications. It is not optimized for scenarios where a foreground response to a user is blocked by the completion of this protocol.
This protocol is also designed to establish associations at the domain level, meaning that this protocol's efficiency is not degraded as more users are added to a given domain. However, since each domain pair requires a separate association, it is more efficient on a per-user resource investment basis to communicate with a domain with many users than a domain with fewer users.
| TOC |
| TOC |
An entity is anything that can be considered to have a presence on a social network. This includes but is not limited to users, organizations and software "bots". An entity is uniquely addressed, for the purposes of this protocol, by a node identifier and a domain identifier. For convenience these can be serialized into a single string called an entity identifier.
TODO: write some BNF for this. basically it's the obvious node@domain syntax, with similar syntax constraints to that of email addresses
| TOC |
The domain identifier consists of a fully qualified domain name, as defined by [RFC1035] (Mockapetris, P., “Domain Names - Implementation and Specification,” November 1987.). When used in this protocol, the domain is in ASCII. However, applications SHOULD accept user input of domains in Unicode and present domains to users in Unicode and apply the conversions defined in [RFC3490] (Faltstrom, P., “Internationalizing Domain Names in Applications,” March 2003.) to translate to and from the ASCII representation that will be used to serialize the domain identifier for use in DFP.
| TOC |
The entity identifier is a name, unique within a particular domain, that identifies an entity. An entity identifier is any sequence of octets that is considered valid and normalized UTF-8, except that this sequence may not contain codepoints U+0020 (space) nor U+0040 (at sign). Applications SHOULD reject identifiers that are not valid or normalized UTF-8. Given that only normalized UTF-8 is permitted, identifiers MAY be compared octet-for-octet internally by applications, but identifiers should be displayed to users using the unicode characters that result from decoding the octet sequence.
TODO: What is a good thing to reference about normalized UTF-8?
| TOC |
| TOC |
The discovery document for a domain is an HTTP resource that describes the federation resources available for a domain. The URL of a domain's discovery document is obtained by adding the prefix https:// and the suffix /.well-known/federation do the domain. This resource MUST respond to an HTTP GET request by returning an entity whose Content-Type is application/json and whose body is a valid JSON object. The properties of this object and their valid values can be defined by other specifications. This specification defines one initial property in Section 4 (Establishing Domain Associations with Domain Dialback).
Clients MUST make use of the standard HTTP caching mechanisms to avoid imposing unnecessary load on the target server.
| TOC |
| TOC |
Domain Dialback is a lightweight mechanism by which a target domain can verify a request from a source domain and then issue a temporary bearer token to the source domain for use in subsequent requests.
The domain dialback mechanism is made possible by the existence of the Domain Name System (DNS), since one server can (normally) discover the authoritative server for a given domain.
Domain dialback is uni-directional, and results in weak verification of identity in one direction. Mutual authentication is not possible via dialback. Therefore, domain dialback MUST be completed in each direction in order to enable bi-directional communications between two domains.
| TOC |
The URL of a domain's association endpoint is declared in the domain's discovery document (Section 3 (Retrieving the Discovery Document for a Domain)) via the property associate. Its value is a JSON string containing an absolute URL using the https: scheme.
| TOC |
A source domain requests a unidirectional association with a target domain by making an HTTP POST request to the target domain's association endpoint. The Content-Type of this request is application/x-www-form-urlencoded and its payload is the following parameters encoded with this encoding scheme:
- mode
- The literal string associate.
- domain
- The source domain.
- verifier
- A string, containing only ASCII characters, that allows the source domain to uniquely recognize this request during verification.
The response to this request is delayed until the dialback process is completed, as described in the following section.
| TOC |
A target domain verifies an association request by making an HTTP POST request to the target domain's association endpoint. Again, the Content-Type of this request is application/x-www-form-urlencoded. Its payload is the following parameters:
- mode
- The literal string verify.
- domain
- The target domain.
- verifier
- The token provided by the client in the association request.
If the provided domain and token represent a known, outstanding association request the source domain responds with a 200 OK response whose Content-Type is application/json and whose body is a JSON object with a single property verifier, whose value is a JSON string echoing back the verifier. The request is not verified if the response status is not 200, if the response body is not a JSON object or if the token value does not match the expected value. Requiring the verifier to be echoed back avoids falsely detecting a verified request for resources that return 200 OK unconditionally and are not intentionally responding to the verify request.
| TOC |
If the association request is verified, the response to the association request has the status 200 OK and the Content-Type application/json. The body of this response is a JSON object with the following properties:
- token
- A JSON string containing the bearer token that will act as a shared secret allowing the source domain to make authenticated requests to the target domain using this association.
- expires_in
- A JSON integer giving the number of seconds after which this association is invalid.
In order to reduce problems related to clock skew or response delay, the source domain MUST actually discard created association two minutes before the expire time, and the target domain MUST consider the association valid for two minutes after the expire time.
| TOC |
| TOC |
A target domain MAY offer a means by which a source domain can establish a relationship out of band of the DFP flow. In this case, the target domain issues the source domain a set of credentials which it can use in an extended version of the association request. A target domain MAY offer additional functionality for associations established in this way, for example if the prior relationship was dependent on the organisation responsible for the source domain agreeing to terms of use that are required for such additional access.
An existing relationship is identified by a client id and authenticated via a client secret. These terms are taken from OAuth 2.0 but in practice the target domain may issue any set of credentials it wishes, with no requirement that these credentials are also usable in any OAuth 2.0 request.
If the target domain does verification of domain ownership as part of the pre-registration process (using a mechanism that is out of scope for this specification), it MAY skip the dialback verification process when establishing an association. However, this is not required, and a target domain MAY still perform dialback verification for association requests that include client credentials, for example if the client credentials identify an application or organization but not any particular source domain.
The following parameters are used when supplying client credentials, in addition to the parameters specified in Section 4.3 (Requesting an Association), which are all still required in this case:
- client_id
- An opaque token issued by the target domain to identify the requesting application.
- client_secret
- A shared secret issued by the target domain to use with the provided client_id.
A target domain MAY require client credentials in order to establish an association, in which case it must respond to an association request without credentials using a client error HTTP response code such as 400 Bad Request. However, such a target domain MAY instead grant an association that provides limited access for requests without client credentials, allowing limited interoperability for clients that have not pre-registered.
| TOC |
Domain dialback as described in Section 4 (Establishing Domain Associations with Domain Dialback) provides a lightweight, generic mechanism for establishing an association between two arbitrary domains. A pair of domains MAY use an alternative means, not defined by this specification, to establish an association. This includes but is not limited to a protocol involving use and verification of SSL client certificates, or an application-specific domain pre-registration procedure.
Domains SHOULD support domain dialback in order to achieve maximum interoperability, but domains MAY consider associations established via domain dialback less trustworthy than those established by other means and provide differing levels of functionality depending on the mechanism used.
| TOC |
| TOC |
The sections that follow describe extensions to the Hypertext Transfer Protocol (HTTP) that allow an HTTP request to carry a verifyable source identity based on a previously-established domain association.
| TOC |
This specification establishes a new HTTP authentication scheme whose identifier is DFPEntity. This scheme can be used to act as an entity within a domain using a previously-established domain association bearer token.
Authorization: DFPEntity john.smith 1sb25b53534b34:44533
An HTTP server supporting this authentication scheme MUST determine, via a means outside the scope of this specification, which domain the given association bearer token belongs to. If no such association exists, authentication fails. If such an association exists, the identity of the requester is the entity identified by the given entity identifier and the domain identifier corresponding to the association bearer token.
| TOC |
| TOC |
The domain dialback mechanism described in Section 4 (Establishing Domain Associations with Domain Dialback) helps prevent against domain spoofing, thus making it more difficult to send a message that a target will falsely believe to be sent from another sender. It is not a mechanism for authenticating, securing or encrypting communications between two domains. It is susceptable to DNS poisoning attacks unless DNSSEC is used or unless a trustworthy verification of the source domain's TLS certificate is possible.
| TOC |
| TOC |
| [RFC1035] | Mockapetris, P., “Domain Names - Implementation and Specification,” November 1987. |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| [RFC3490] | Faltstrom, P., “Internationalizing Domain Names in Applications,” March 2003. |
| TOC |
| Martin Atkins | |
| SAY Media |