DECADE Working Group D. Wang Internet-Draft Huawei Intended status: Standards Track Y.R. Yang Expires: April 26, 2012 Yale University Oct 24, 2011 An HTTP-based DECADE Resource Protocol draft-wang-decade-drp-00 Abstract This document explores the design of an HTTP-based DECADE Resource Protocol (DRP), which can be used for content and resource management between a DECADE Client and a DECADE Server, or between two DECADE Servers. We identify the function entities, and present initial protocol message flow and syntax design. The purpose of this document is to get design discussions started, not to provide a complete solution. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on April 16, 2012. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must Wang Expires April 26, 2012 [Page 1] Internet-Draft HTTP DECADE DRP Oct 2011 include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Wang Expires April 26, 2012 [Page 2] Internet-Draft HTTP DECADE DRP Oct 2011 Table of Contents Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminologies and concepts . . . . . . . . . . . . . . . . . . 4 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Function Entity . . . . . . . . . . . . . . . . . . . . . 4 3.3. Protocol Architecture . . . . . . . . . . . . . . . . . . 5 3.4. Object Naming Scheme . . . . . . . . . . . . . . . . . . . 5 3.5. Protocol Operations . . . . . . . . . . . . . . . . . . . 5 4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Common Message Processing . . . . . . . . . . . . . . . . 6 4.3. DECADE Messages . . . . . . . . . . . . . . . . . . . . . 7 4.3.1. Transport_Query Message . . . . . . . . . . . . . . . 7 4.3.2. Access_Token Message . . . . . . . . . . . . . . . . . 8 4.3.3. Server_State_Query Message . . . . . . . . . . . . . . 8 4.3.4. Object_Property_Query Message . . . . . . . . . . . . 12 4.3.5. Object_Property_Set Message . . . . . . . . . . . . . 12 4.3.5. Delete_Object Message . . . . . . . . . . . . . . . . 13 4.4. Error Response Messages . . . . . . . . . . . . . . . . . 14 5. Integration with an HTTP-based SDT . . . . . . . . . . . . . . 14 5.1. Put_Object Message . . . . . . . . . . . . . . . . . . . . 14 5.2. Get_Object Message . . . . . . . . . . . . . . . . . . . . 16 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 1. Introduction The DECADE Architecture document [I-D.ietf-decade-arch-03] identifies a DECADE architecture that consists of two logically independent protocols: the DECADE Resource Protocol (DRP) and the Standard Data Transport (SDT). The former provides access control and resource scheduling between two DECADE peers, while the latter is used to transfer data objects to and from a DECADE Server. The architecture document observes that the two protocols may be realized on the same wire. In this document, we present an initial design of a DRP based on HTTP. We use the DECADE requirements [I-D.ietf-decade-reqs-04] to guide our design. The purpose of this document is to get design discussions started, not to provide a complete solution. Wang Expires April 26, 2012 [Page 3] Internet-Draft HTTP DECADE DRP Oct 2011 Specifically, the DRP we present provides a signaling layer for transport negotiation, content management, access control and resource control. The SDT is responsible for data put, retrieve, delete, and metadata update, and the implementation of access control and resource control policies. We also show that the HTTP based DRP may be extended to include an HTTP based SDT, achieving a same-wire design, although it is also possible to use another SDT. 2. Terminologies and concepts The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "MAY", "MAY NOT" and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. This draft uses the terms defined in [I-D.ietf-decade-problem- statement-03] and in [I-D.ietf-decade-arch-03]. DECADE peers: Entities involved in the DECADE protocol, such as a DECADE Server or a DECADE Client. 3. Protocol Overview 3.1. Overview A DECADE Protocol is spoken between a DECADE Client and a DECADE Server or between two DECADE Servers to manage, store, and retrieve data objects for data distribution. A DECADE Client can be an application server, or embedded in a web browser, etc. DECADE needs a mandatory naming scheme, that can be used to achieve content security and de-duplication. In this initial design, we assume that the name space is flat for simplicity. We anticipate that the name scheme should also allow for group operations on a set of data objects with a similar/same attribute. 3.2. Function Entity We consider two primary function entities involved in DECADE: the DECADE Server and the DECADE Client. DECADE Server: A DECADE Server stores DECADE data inside the network, and thereafter manages both stored data and access to them[I-D.ietf-decade-arch-03]. DECADE Client: A DECADE Client stores and retrieves data at DECADE Wang Expires April 26, 2012 [Page 4] Internet-Draft HTTP DECADE DRP Oct 2011 Servers [I-D.ietf-decade-arch-02]. 3.3. Protocol Architecture +------+ DRP +------+ |DECADE|<--------------->|DECADE| |Server|<--------------->|Server| +------+ SDT +------+ ^ ^ ^ ^ | | | | DRP| | SDT DRP| |SDT | | | | v v v v +------+ +------+ |DECADE| |DECADE| |Client| |Client| +------+ +------+ 3.4. Object Naming Scheme (To be added...) 3.5. Protocol Operations The DRP we present is a request-response protocol. Requests and corresponding responses are exchanged between DECADE Client and Server or between DECADE Servers. In particular, we identify the following operations: Access Token: This operation allows the DECADE Server to limit access and resource control of data objects stored on it via authenticated tokens. The token should limit permitted operations to permitted objects by permitted clients during permitted period, as well as priority for bandwidth given to requested operation, and so on. OAUTH is adopted here to realize access and resource control. Query Server State (from the system's view): This operation allows a DECADE Client to query aggregated server status of a DECADE Server, e.g., resource availability, and so on. Query Server State (from the user view): This operation allows a DECADE Client to query its particular state, e.g., a list of objects stored in the Server belonging to the DECADE Client, the Client's available resources, and so on. Query Object Property: This operation allows a DECADE Client to Wang Expires April 26, 2012 [Page 5] Internet-Draft HTTP DECADE DRP Oct 2011 query properties associated with a data object. Examples include TTL of the object, object size, and object type. Set Object Property: This operation allows a DECADE Client to set data object properties. Delete Data Object: This operation is used to delete data objects from a DECADE Server. Complementing the preceding DRP operations, the following SDT operations may be defined for a complete DECADE Protocol: Get Data Object: This operation is used to download data objects from a DECADE Server. Put Data Object: This operation is used to write data objects to a DECADE Server. 4. Message Syntax and Processing We now present the encoding and processing. 4.1. Encoding The DRP in this document follows the standard request and response formats for HTTP Request and Response messages [RFC2616]. Specifically, the header fields in both request and response messages follows the standard rules for HTTP/1.1 Header fields, which MAY be included in the messages if necessary. We use JSON to encode the bodies for both request and response messages. In the following messages, *** represent numeric data to be insert. (To be continued...) 4.2. Common Message Processing After receiving a DRP protocol message, some basic processing will be performed, regardless of the message type or the receiving entity. Upon receiving a message, the receiver examines the message header to ensure that it is properly formed, which is done by the receiver itself. If not, appropriate standard HTTP errors MUST be generated. If the message is found to be incorrectly formed or the length does Wang Expires April 26, 2012 [Page 6] Internet-Draft HTTP DECADE DRP Oct 2011 not match the length encoded in the header, the receiver MUST reply with an HTTP 400 response. If the version number is not supported by the receiver, the receiver MUST reply with an HTTP 400 response. If the receiver is unable to process the message temporarily because it is in an overloaded state, the receiver SHOULD reply with an HTTP 503 response. If the receiver encounters an internal error while attempting to process the message, the receiver MUST generate an HTTP 500 response. 4.3. DECADE Messages 4.3.1. Transport_Query Message After a DECADE Client locates its authenticated DECADE Server, it MUST query the SDT capability of the Server. This query is the Transport_Query message. Below is an example Transport_Query message: GET /decade/transport/ HTTP/1.1 Host: example.com Content-Type: application/decade-transport-req+json X-DECADE-Protocol-Version: 1.0 If the query message is valid, the DECADE Server sends back a response listing the supported SDT protocols. An example is shown below: Wang Expires April 26, 2012 [Page 7] Internet-Draft HTTP DECADE DRP Oct 2011 HTTP/1.1 200 OK Content-Length: *** Content-Type: application/decade-transport-ans+json X-DECADE-Protocol-Version: 1.0 { "transport-protocol": { "HTTP": true, "NFS": true, "WebDAV": true, } } JSON object: object { JSONBool HTTP; [OPTIONAL] JSONBool NFS; [OPTIONAL] JSONBool WebDav; [OPTIONAL] ... } TransportProtocol; object { TransportProtocol transport-protocol; } 4.3.2. Access_Token Message This operation allows a DECADE CLient to obtain an access token from a DECADE Server to limit access and achieve resource control. Specifically, an access token should limit permitted operations to permitted objects by permitted clients during permitted period, as well as priority for bandwidth given to requested operation, and so on. In DECADE architecture, a user delegation scheme is proposed. We anticipate that a DECADE Client can generate such Access Token locally as well. An access token to be generated may be depended on the SDT specified, should the token to be carried by the SDT operation. 4.3.3. Server_State_Query Message This operation allows state query. The state can be either system- wide or on a particular user. An example message is: Wang Expires April 26, 2012 [Page 8] Internet-Draft HTTP DECADE DRP Oct 2011 Wang Expires April 26, 2012 [Page 9] Internet-Draft HTTP DECADE DRP Oct 2011 POST /decade/status HTTP/1.1 Host: example.com Content-Length: *** Content-Type: application/decade-stat-req+json X-DECADE-Protocol-Version: 1.0 X-DECADE-TOKEN: XXX { "status-request": { "StorageUsed": true; "StorageAvailable": true; "BandwidthUsed": true; "BandwidthAvailable": ture; "NumObjects": true; "ObjectList": true; } "user-type": { "System": true, } "token": XXX } JSON Object: Object { JSONBool StorageUsed; [OPTIONAL] JSONBool StorageAvailable; [OPTIONAL] JSONBool BandwidthUsed; [OPTIONAL] JSONBool BandwidthAvailable; [OPTIONAL] JSONBool NumObjects; [OPTIONAL] JSONBool ObjectList; [OPTIONAL] } StatusRequest; Object{ JSONBool System; [OPTIONAL] JSONBool User; [OPTIONAL] }UserType object{ StatusRequest status-request; } object{ UserType user-type; } If a state query message is valid, the DECADE Server responses with . Wang Expires April 26, 2012 [Page 10] Internet-Draft HTTP DECADE DRP Oct 2011 An example of the Response message is as following: HTTP/1.1 200 OK Content-Length: *** Content-Type: application/decade-stat-ans+Jason X-DECADE-Protocol-Version: 1.0 { "data-object-list": [ "data-object1": { "object-name": string; } "data-object2": { "object-name": string; } ... ] "resource-available": { "BandwidthAvailable": number; "SpaceAvailable": number; ... } } JSON Object: Object { JSONNumber bandwidth-available; JSONNumber space-available; ... } ResourceAvailable; Object{ JSONArray data-object-list; } Object{ ResourceAvailable resource-available; } Object{ JSONString object-name; }DataObject Wang Expires April 26, 2012 [Page 11] Internet-Draft HTTP DECADE DRP Oct 2011 Object{ DataObject data-object1; DataObject data-object2; ... } 4.3.4. Object_Property_Query Message This operation allows a DECADE Client to query object properties, including TTL of object, object size, and object type. The request message is as following: GET /decade/object//property HTTP/1.1 Host: example.com Content-Length: *** Content-Type: application/decade-propquery-req+json X-DECADE-Protocol-Version: 1.0 X-DECADE-TOKEN: XXX If an object property query message is valid, the DECADE Server replies the requested info. An example of response is: HTTP/1.1 200 OK Content-Length: *** Content-Type: application/decade-propquery-ans+json X-DECADE-Protocol-Version: 1.0 { "object-property": { "object-type": string, "object-size": number, "TTL": number, } } JSON Object: object { JSONString object-type; [OPTIONAL] JSONNumber TTL; [OPTIONAL] } ObjectProperty; Object{ ObjectProperty object-property; } 4.3.5. Object_Property_Set Message Wang Expires April 26, 2012 [Page 12] Internet-Draft HTTP DECADE DRP Oct 2011 This operation allows a DECADE Client to set object properties (meta- data). An example request message is: PUT /decade/ object/property HTTP/1.1 Host: example.com Content-Length: *** Content-Type: application/decade-propset-req+json X-DECADE-Protocol-Version: 1.0 X-DECADE-TOKEN: XXX { "object-property": { "object-type:" true, "object-size": true, "TTL": true } } 4.3.5. Delete_Object Message This operation is used to delete objects from a DECADE Server. The request message body is as following: DELETE /decade/ HTTP/1.1 Host: example.com Content-Length: *** Content-Type: application/decade-deledata-req+json X-DECADE-Protocol-Version: 1.0 X-DECADE-TOKEN: XXX Wang Expires April 26, 2012 [Page 13] Internet-Draft HTTP DECADE DRP Oct 2011 4.4. Error Response Messages The error response messages for the DECADE protocol are described below: SUCCESSFUL (200 OK): a message has been processed properly and the desired operation has completed. If the message is a request for information, the body will also include the requested information. NO CONTENT (204 NO CONTENT): The server successfully processed the request, but is not returning any content. INVALID SYNTAX (400 Bad Request): Indicates an error in the format of the message/message body. VERSION NOT SUPPORTED (400 Bad Request): Invalid version of the protocol or message bodies. AUTHENTICATION REQUIRED (401 UNAUTHORISED): Authentication is required to access this information. MESSAGE FORBIDDEN (403 FORBIDDEN): The requester is not allowed to make this request. OBJECT NOT FOUND (404 NOT FOUND): The requested object cannot be found. SERVER NOT FOUND (404 NOT FOUND): The requested server cannot be found. 5. Integration with an HTTP-based SDT There can be multiple SDT protocols. One possibility is to use the same DRP as SDT. 5.1. Put_Object Message This operation is used to write objects to a DECADE Server. An example of the request message is as following: PUT /decade/ HTTP/1.1 Host: example.com Content-Length: *** Content-Type: application/decade-putdata-req+json X-DECADE-Protocol-Version: 1.0 X-DECADE-TOKEN: XXX { Wang Expires April 26, 2012 [Page 14] Internet-Draft HTTP DECADE DRP Oct 2011 "data-object-list": [ "data-object1": { "object-name": string; } "data-object2": { "object-name": string; } ... ] } JSON Object: Object{ JSONArray data-object-list; } object { JSONString owner; JSONNumber TTL; ... }ObjectMetadata; object { JSONString object-type; JSONNumber object-size; ObjectMetadata metadata ; } DataObject; Object{ DataObject data-object1; DataObject data-object2; ... } object { ObjectOperation permitted-operations<0..*>; JSONObject permitted-objects; JSONObject permitted-clients; JSONNumber expiration-time; JSONNumber priority; }AuthToken; Object{ Read; Wang Expires April 26, 2012 [Page 15] Internet-Draft HTTP DECADE DRP Oct 2011 Write; Delete; }ObjectOperation; 5.2. Get_Object Message This operation is used to download objects from a DECADE Server. An example of the request message body is as following: GET /decade/ HTTP/1.1 Host: example.com Content-Length: *** Content-Type: application/decade-getdata-req+json X-DECADE-Protocol-Version: 1.0 X-DECADE-TOKEN: XXX 6. IANA Considerations (TBA) 7. Security Considerations (TBA) 8. Acknowledgements (TBA) Wang Expires April 26, 2012 [Page 16] Internet-Draft HTTP DECADE DRP Oct 2011 Authors' Addresses Wang Danhua Huawei No. 101 Software Avenue Nanjing, Jiangsu Province 210001 P.R.China Email: wangdanhua@huawei.com Y. Richard Yang Yale University 51 Prospect Street New Haven, CT 06511 USA Email: yry@cs.yale.edu Wang Expires April 26, 2012 [Page 17]