| TOC |
|
The XRD Provisioning Protocol (XRDP) is an application-level protocol for editing resource descriptors. The protocol is based on HTTP transfer of XRD-formatted representations. XRD is a simple generic format for describing and discovering resources.
1.
Introduction
2.
Notational Conventions
3.
Terminology
4.
Protocol Model
4.1.
Identifying Links
4.1.1.
By Combination of rel, type, and href or template Attributes
4.1.2.
By xml:id Attribute
4.2.
Control and Provisioning
5.
Protocol Operations
5.1.
Locating the XRDP Service Endpoint
5.2.
Adding a Link
5.3.
Updating a Link
5.4.
Removing a Link
5.5.
Use of HTTP Response Codes
6.
Securing the XRD Provisioning Protocol
7.
References
Appendix A.
Acknowledgments
Appendix B.
Document History
§
Author's Address
| TOC |
The XRD Provisioning Protocol is an application-level protocol for editing resource descriptors in XRD (Hammer-Lahav, E. and W. Norris, “Extensible Resource Descriptor (XRD) Version 1.0, Working Draft 15,” .) [9] format using HTTP. The protocol supports the provisioning of XRD resource descriptors and provides facilities for:
XRD resource descriptor documents provide machine-readable information about resources (resource metadata) for the purpose of promoting interoperability. They also assist in interacting with unknown resources that support known interfaces.
By allowing an XRD resource descriptor to be provisioned, the capabilities and services of a resource can be refined over time. Furthermore, these capabilities and services can be implemented in a decentralized manner, as the target link can be be serviced by a different host than that of the context resource.
| TOC |
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.) [1].
| TOC |
- XRDP Service Endpoint
- A URL which accepts XRDP protocol messages.
| TOC |
The XRD Provisioning Protocol specifies operations for adding, updating, and removing links from an XRD document. It uses XRD-formatted representations to describe the metadata of those links.
| TOC |
XRDP operations are performed on links contained in an XRD document. These links need to be uniquely identified in order to execute the operations. Links can be identified by the combination of rel, type, and href or template attributes. Optionally, links can be identified by an xml:id attribute.
| TOC |
XRD defines <Link> elements as having rel, type, and either an href or template attribute. The combination of these attributes is sufficient to uniquely identify a link within an XRD document.
This criteria is based on the assumption that having two <Link> elements with the same rel, type, and href or template tuple is neither required nor necessary in an XRD document.
| TOC |
<Link> elements MAY be given an xml:id [REC-xml-id (Walsh, N., Veillard, D., and J. Marsh, “xml:id Version 1.0,” September 2005.) [8]] attribute the value of which is unique within the XML document.
The value of the xml:id attribute is generated by the entity requesting the link to be added to the XRD. The uniqueness of the ID within the XRD document MUST be ensured by the provider of the XRDP Service Endpoint.
| TOC |
XRDP uses HTTP methods to provision XRD documents as follows:
Since all aspects of client-server interaction are defined in terms of HTTP, RFC 2616 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [3] should be consulted for any areas not covered in this specification.
| TOC |
| TOC |
The XRDP Service Endpoint is identified by a link with the following rel value: http://xrdprovisioning.net/rel/provision
For example:
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"> <Subject>http://www.example.com/jane</Subject> <Link rel="http://xrdprovisioning.net/rel/provision" href="http://www.example.com/jane/xrd" /> </XRD>
It is RECOMMENDED that the URI of the link be the same as the URI of the XRD document. This recommendation is in accordance with REST principles and web architecture guidelines [REC-webarch (Jacobs, I. and N. Walsh, “Architecture of the World Wide Web, Volume One,” December 2004.) [7]].
The XRDP Service Endpoint link differs from most XRD links in that the relation is between the XRD document itself and the XRDP Service Endpoint, and not between the resource described by the XRD and the XRDP Service Endpoint.
| TOC |
Add operations are made by issuing an HTTP POST request to the XRDP Service Endpoint for the XRD. The body of the request MUST be of content type application/xrd+xml and include the single <Link> element that is being added.
For example:
POST /jane/xrd HTTP/1.1 Host: www.example.com Content-Type: application/xrd+xml Content-Length: nnn <Link xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0" rel="foo" href="http://api.example.net/foo" type="application/foo+xml" />
The server signals a successful addition with a status code of 200. The response includes a representation of the resource descriptor in the body of the response.
For example:
HTTP/1.1 200 OK Content-Type: application/xrd+xml Content-Length: nnn <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"> <Subject>http://www.example.com/jane</Subject> <Link rel="foo" href="http://api.example.net/foo" type="application/foo+xml" /> <Link rel="http://xrdprovisioning.net/rel/provision" href="http://www.example.com/jane/xrd" /> </XRD>
If the link being added conflicts with the identity of an existing link in the XRD document, the server signals an error with a status code of 409.
As described in XRD Extensibility, the <Link> element allows inclusion of attributes and child elements from arbitrary namespaces (except for the XRD namespace). Service implementations MUST preserve any extension attributes and elements, including those they cannot interpret.
| TOC |
Update operations are made by issuing an HTTP PUT request to the XRDP Service Endpoint for the XRD. The body of the request MUST be of content type application/xrd+xml and include the single <Link> element that is updating an existing link. The link to update is identified by including the appropriate URL parameters in the request.
Parameter values MUST be percent-encoded per RFC 3986 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [5].
For example:
PUT /jane/xrd?rel=foo&href=http%3A%2F%2Fapi.example.net%2Ffoo&type=application%2Ffoo%2Bxml HTTP/1.1 Host: www.example.com Content-Type: application/xrd+xml Content-Length: nnn <Link xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0" rel="foo" href="http://api.cdn.example.net/foo" type="application/foo+xml" />
The server signals a successful update with a status code of 200. The response includes a representation of the resource descriptor in the body of the response.
For example:
HTTP/1.1 200 OK Content-Type: application/xrd+xml Content-Length: nnn <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"> <Subject>http://www.example.com/jane</Subject> <Link rel="foo" href="http://api.cdn.example.net/foo" type="application/foo+xml" /> <Link rel="http://xrdprovisioning.net/rel/provision" href="http://www.example.com/jane/xrd" /> </XRD>
If the entity updating the link does not have authorization to do so, the server signals an error with a status code of 403.
As described in XRD Extensibility, the <Link> element allows inclusion of attributes and child elements from arbitrary namespaces (except for the XRD namespace). Service implementations MUST preserve any extension attributes and elements, including those they cannot interpret.
| TOC |
Remove operations are made by issuing an HTTP DELETE request to the XRDP Service Endpoint for the XRD. The link to delete is identified by including the appropriate URL parameters in the request.
Parameter values MUST be percent-encoded per RFC 3986 (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [5].
For example:
DELETE /jane/xrd?rel=foo&href=http%3A%2F%2Fapi.cdn.example.net%2Ffoo&type=application%2Ffoo%2Bxml HTTP/1.1 Host: www.example.com
The server signals a successful removal with a status code of 200. The response includes a representation of the resource descriptor in the body of the response.
For example:
HTTP/1.1 200 OK Content-Type: application/xrd+xml Content-Length: nnn <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"> <Subject>http://www.example.com/jane</Subject> <Link rel="http://xrdprovisioning.net/rel/provision" href="http://www.example.com/jane/xrd" /> </XRD>
If the entity removing the link does not have authorization to do so, the server signals an error with a status code of 403.
| TOC |
XRDP uses the response status codes defined in HTTP to indicate the success or failure of an operation. Consult the HTTP specification [RFC 2616 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [3]] for detailed definitions of each status code.
| TOC |
XRDP is based on HTTP. Authentication requirements for HTTP are covered in Section 11 of RFC 2616.
The use of authentication mechanisms to prevent provisioning by unknown or unauthorized clients is RECOMMENDED but not required. The type of authentication deployed is a decision made by the service operator.
Use of HTTP Basic Authentication [RFC 2617 (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.) [4]], in conjunction with a connection made with TLS 1.0 [RFC 2246 (Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.) [2]], is sufficient to restrict access to provisioning capabilities. This scenario is appropriate when the authenticating entity is the administrator of an XRD document and has authorization to modify the entirety of its contents.
In web-based environments, authorization to provision an XRD will be granted to web applications. Common scenarios involve the user delegating permission to the web application to act on the user's behalf. Such authorization may apply to a restricted portion of an XRD document. For example, it may allow updating and removing of links added by the web application in question, but disallow updating or removing of any other links. Service operators are responsible for enforcing appropriate authorization rules.
The choice of authentication mechanism will impact interoperability. At the time of publication of this specification, use of HTTP Basic Authentication with TLS is considered good practice for desktop and mobile applications that don't require delegated authorization. For web applications requiring delegated authorization, use of OAuth 1.0a [OAuth Core 1.0a (OAuth Core Workgroup, “OAuth Core 1.0a,” .) [10]] is considered good practice. Implementation of these mechanisms is sufficient for establishing a baseline for interoperability.
Implementers are encouraged to investigate and use alternative mechanisms regarded as equivalently good or better at the time of deployment. In particular, implementors are encouraged to monitor the progress of the IETF OAuth Working Group as it defines specifications for OAuth WRAP [I-D.hardt-oauth (Hardt, D., Tom, A., Eaton, B., and Y. Goland, “OAuth Web Resource Authorization Profiles,” January 2010.) [6]] and OAuth 2.0. It is RECOMMENDED that clients be implemented in such a way that new authentication schemes can be deployed.
Because this protocol uses HTTP response status codes as the primary means of reporting the result of a request, servers are advised to respond to unauthorized or unauthenticated requests using an appropriate 4xx HTTP response code (e.g., 401 "Unauthorized" or 403 "Forbidden") in accordance with RFC 2617 (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.) [4].
| TOC |
| TOC |
| TOC |
Working Draft 01
| TOC |
| Jared Hanson | |
| Email: | jaredhanson@gmail.com |
| URI: | http://jaredhanson.net/ |