idnits 2.17.1 draft-dejong-remotestorage-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (5 December 2012) is 4159 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-18) exists of draft-ietf-appsawg-webfinger-07 -- Obsolete informational reference (is this intentional?): RFC 2818 (ref. 'HTTPS') (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET DRAFT Michiel B. de Jong 2 Document: draft-dejong-remotestorage-00 (independent) 3 F. Kooman 4 Intended Status: Proposed Standard SURFnet 5 Expires: 8 June 2013 5 December 2012 7 remotestorage 9 Abstract 11 This draft describes a protocol by which client-side applications, 12 running inside a web browser, can communicate with a data storage 13 server that is hosted on a different domain name. This way, the 14 provider of a web application need not also play the role of data 15 storage provider. The protocol supports storing, retrieving, and 16 removing individual documents, as well as listing the contents of an 17 individual directory, and access control is based on bearer tokens. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 9 June 2013. 36 Copyright Notice 38 Copyright (c) 2012 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction...................................................2 54 2. Terminology....................................................2 55 3. Storage model..................................................3 56 4. Requests.......................................................3 57 5. Response codes.................................................4 58 6. Versioning.....................................................5 59 7. CORS headers...................................................5 60 8. Session description............................................5 61 9. Bearer tokens and access control...............................6 62 10. Application-first bearer token issuance........................6 63 11. Storage-first bearer token issuance............................7 64 12. Security Considerations........................................8 65 13. IANA Considerations............................................9 66 14. Acknowledgments................................................9 67 15. References.....................................................9 68 15.1. Normative References......................................9 69 15.2. Informative References....................................9 70 16. Authors' addresses............................................10 72 1. Introduction 74 Many services for data storage are available over the internet. This 75 specification describes a vendor-independent interface for such 76 services. It is based on https, CORS and bearer tokens. The 77 metaphor for addressing data on the storage is that of folders 78 containing documents and subfolders. The actions the interface 79 exposes are: 81 * GET a folder: retrieve the names and current versions of the 82 documents and subfolders currently contained by the folder 84 * GET a document: retrieve its content type, current version, 85 and contents 87 * PUT a document: store a new version, its content type, and 88 contents, conditional on the current version 90 * DELETE a document: remove it from the storage, conditional on 91 the current version 93 The exact details of these four actions are described in this 94 specification. 96 2. Terminology 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in RFC 2119 [WORDS]. 102 "SHOULD" and "SHOULD NOT" are appropriate when valid exceptions to a 103 general requirement are known to exist or appear to exist, and it is 104 infeasible or impractical to enumerate all of them. However, they 105 should not be interpreted as permitting implementors to fail to 106 implement the general requirement when such failure would result in 107 interoperability failure. 109 3. Storage model 111 The server stores data in nodes that form a tree structure. 112 Internal nodes are called 'folders' and leaf nodes are called 113 'documents'. For a folder, the server stores references to nodes 114 contained in the folder, and it should be able to produce a list of 115 them, with for each contained item: 117 * item name 118 * item type (folder or document) 119 * current version 121 For a document, the server stores, and should be able to produce: 123 * content type 124 * content 125 * current version 127 4. Requests 129 Client-to-server requests SHOULD be made over https [HTTPS]. The 130 root folder of the storage tree is represented by the URL 131 '/'. Subsequently, if is the URL of a 132 folder, then the URL of an item contained in it is 133 for a document, or 134 '/' for a folder. Item names MAY 135 contain a-z, A-Z, 0-9, %, -, _. 137 A successful GET request to a folder SHOULD be responded to with a 138 JSON document (content type 'application/json'), representing a map 139 in which contained documents appear as entries to 140 , and contained folders appear as entries 141 '/' to , for instance: 143 { 144 "abc": 1234567890123, 145 "def/": 1234567890456 146 } 148 Empty folders are treated as non-existing, and therefore GET 149 requests to them SHOULD be responded to with a 404 response, and an 150 empty folder MUST NOT be listed as an item in its parent folder. 151 Also, folders SHOULD be created silently, as necessary to contain 152 newly added items. This way, PUT and DELETE requests only need to be 153 made to documents, and folder management becomes an implicit result. 155 A successful GET request to a document SHOULD be responded to with 156 the full document contents in the body, the document's content type 157 in a 'Content-Type' header, and the document's current version in an 158 'ETag' header. 160 A successful PUT request to a document MUST result in: 162 * the request body being stored as the document's new content, 163 * parent and further ancestor folders being silently created as 164 necessary, with the document (name and version) being added to 165 its parent folder, and each folder added to its subsequent 166 parent, 167 * the value of its Content-Type header being stored as the 168 document's new content type, 169 * the current server time, in the form of milliseconds since 170 0:00 UCT, 1 January, 1970 being stored as the new version of 171 the document itself, as well as of its parent folder and 172 further ancestor folders. 174 The response MUST contain an ETag header, with the document's new 175 version (milliseconds since the beginning of 1970) as its value. 177 A successful DELETE request to a document MUST result in the 178 deletion of that document from the storage, and from its parent 179 folder. If the parent folder is left empty by this, then it MUST 180 also be removed, and so on for ancestor folders. 182 A successful OPTIONS request SHOULD be responded to as described in 183 the CORS section below. 185 5. Response codes 187 The following responses SHOULD be given in the indicated cases, in 188 order of preference, and SHOULD be recognized by the client: 190 * 500 if an internal server error occurs, 191 * 420 if the client makes too frequent requests or is suspected 192 of malicious activity, 193 * 400 for all malformed requests (e.g. foreign characters in the 194 path or unrecognized http verb, etcetera), as well as for 195 all PUT and DELETE requests to folders, 196 * 401 for all requests that don't have a bearer token with 197 sufficient permissions, 198 * 404 for all DELETE and GET requests to nodes that do not exist 199 on the storage, 200 * 304 for a conditional GET request whose condition fails 201 (see "Versioning" below), 202 * 409 for a conditional PUT or DELETE request whose condition 203 fails (see "Versioning" below), 204 * 200 for all successful requests, including PUT and DELETE, 206 Clients SHOULD also handle the case where a response takes too long 207 to arrive, or where no response is received at all. 209 6. Versioning 211 The current version of a document is the 13-digit decimal number 212 representing the number of milliseconds between 00:00 UCT, 1 January 213 1970, and the last time its content or content type were set or 214 changed successfully. The current version of a folder is the highest 215 version of any of the items it contains. 217 All successful requests MUST return an 'ETag' header with, in the 218 case of GET, the current version, in the case of PUT, the new 219 version, and in case of DELETE, the version that was deleted. PUT 220 and DELETE requests MAY have an 'If-Unmodified-Since' request 221 header, and MUST fail with a 409 response code if that doesn't match 222 the document's current version. GET requests MAY have an 223 'If-Modified-Since' header, and SHOULD be responded to with a 304 if 224 that matches the document or folder's current version. 226 7. CORS headers 228 All responses MUST carry CORS headers [CORS]. The server MUST also 229 reply to OPTIONS requests as per CORS. For GET requests, a wildcard 230 origin MAY be returned, but for PUT and DELETE requests, the 231 response MUST echo back the Origin header sent by the client. 233 8. Session description 235 The information that a client needs to receive in order to be able 236 to connect to a server SHOULD reach the client as described in the 237 'bearer token issuance' sections below. It consists of: 239 * , consisting of 'https://' followed by a server 240 host, and optionally a server port and a path prefix as per 241 [IRI]. Examples: 242 * 'https://example.com' (host only) 243 * 'https://example.com:8080' (host and port) 244 * 'https://example.com/some?path/to/storage' (host, port and 245 path prefix; note there is no trailing slash) 246 * as per [OAUTH]. The token SHOULD be hard to 247 guess and SHOULD NOT be reused from one client to another. It 248 can however be reused in subsequent interactions with the same 249 client, as long as that client is still trusted. Example: 250 * 'ofb24f1ac3973e70j6vts19qr9v2eei' 251 * , always 'draft-dejong-remotestorage-00' for this 252 version of the specification. 254 The client can make its requests using https with CORS and bearer 255 tokens, to the URL that is the concatenation of with 256 '/' plus one or more '/' strings indicating a path in the 257 folder tree, followed by zero or one strings, indicating 258 a document. For example, if is 259 "https://storage.example.com/bob", then to retrieve the folder 260 contents of the /public/documents/ folder, or to retrieve a 261 'draft.txt' document from that folder, the client would make 262 requests to, respectively: 264 * https://storage.example.com/bob/public/documents/ 265 * https://storage.example.com/bob/public/documents/draft.txt 267 9. Bearer tokens and access control 269 A bearer token represents one or more access scopes. These access 270 scopes are represented as strings of the form , 271 where the string SHOULD be lower-case alphanumerical, other 272 than the reserved word 'public', and can be ':r' or ':rw'. 273 The access the bearer token gives is the sum of its access scopes, 274 with each access scope representing the following permissions: 276 'root:rw') any request, 278 'root:r') any GET request, 280 ':rw') any requests to paths that start with 281 '/' '/' or '/public/' '/', 283 ':r') any GET requests to paths that start with 284 '/' '/' or '/public/' '/', 286 As a special exceptions, GET requests to a document (but not a 287 folder) whose path starts with '/public/' are always allowed. They, 288 as well as OPTIONS requests, can be made without a bearer token. All 289 other requests should present a bearer token with sufficient access 290 scope, using a header of the following form: 292 Authorization: Bearer 294 10. Application-first bearer token issuance 296 To make a remotestorage server available as 'the remotestorage of 297 at ', exactly one link of the following format SHOULD 298 be added to the webfinger record [WEBFINGER] of at : 300 { 301 href: , 302 rel: "remotestorage", 303 type: , 304 properties: { 305 'auth-method': "http://tools.ietf.org/html/rfc6749#section-4.2", 306 'auth-endpoint': 307 } 308 } 310 Here and are as per "Session 311 description" above, and SHOULD be a URL where an 312 OAuth2 implicit-grant flow dialog [OAUTH] is be presented, so the 313 user can supply her credentials (how, is out of scope), and allow or 314 reject a request by the connecting application to obtain a bearer 315 token for a certain list of access scopes. 317 The server SHOULD NOT expire bearer tokens unless they are revoked, 318 and MAY require the user to register applications as OAuth clients 319 before first use; if no client registration is required, then the 320 server MAY ignore the client_id parameter in favour of relying on 321 the redirect_uri parameter for client identification. 323 11. Storage-first bearer token issuance 325 The provider MAY also present a dashboard to the user, where she 326 has some way to add open web app manifests [MANIFEST]. Adding a 327 manifest to the dashboard is considered equivalent to clicking 328 'accept' in the dialog of the application-first flow. Removing one 329 is considered equivalent to revoking its access token. 331 As an equivalent to OAuth's 'scope' parameter, a 'remotestorage' 332 field SHOULD be present in the root of such an application manifest 333 document, as a JSON array of strings, each string being one access 334 scope of the form . 336 When the user gestures she wants to use a certain application whose 337 manifest is present on the dashboard, the dashboard SHOULD redirect 338 to the application or open it in a new window. To mimic coming back 339 from the OAuth dialog, it MAY add 'access_token' and 'scope' 340 parameters to the URL fragment. 342 Regardless of whether 'access_token' and 'scope' are specified, it 343 SHOULD add a 'remotestorage' parameter to the URL fragment, with a 344 value of the form '@' . When the application detects 345 this parameter, it SHOULD resolve the webfinger record for at 346 and extract the and information. 348 If no access_token was given, then the application SHOULD also 349 extract the information from webfinger, and continue 350 as per application-first bearer token issuance. 352 Note that whereas a remotestorage server SHOULD offer support of the 353 application-first flow with webfinger and OAuth, it MAY choose not 354 to support the storage-first flow, provided that users will easily 355 remember their '@' webfinger address at that provider. 356 Applications SHOULD, however, support both flows, which means 357 checking the URL for a 'remotestorage' parameter, but giving the 358 user a way to specify her webfinger address if there is none. 360 If a server provides an application manifest dashboard, then it 361 SHOULD merge the list of applications there with the list of 362 issued access tokens as specified by OAuth into one list. Also, 363 the interface for revoking an access token as specified by OAuth 364 SHOULD coincide with removing an application from the dashboard. 366 12. Security Considerations 368 To prevent man-in-the-middle attacks, the use of https instead of 369 http is important for both the interface itself and all end-points 370 involved in webfinger, OAuth, and (if present) the storage-first 371 application launch dashboard. 373 A malicious party could link to an application, but specifying a 374 remotestorage user address that it controls, thus tricking the user 375 into using a trusted application to send sensitive data to the wrong 376 remotestorage server. To mitigate this, applications SHOULD clearly 377 display to which remotestorage server they are sending the user's 378 data. 380 Applications could request scopes that the user did not intend to 381 give access to. The user SHOULD always be prompted to carefully 382 review which scopes an application is requesting. 384 An application may upload malicious html pages and then trick the 385 user into visiting them, or upload malicious client-side scripts, 386 that take advantage of being hosted on the user's domain name. The 387 origin on which the remotestorage server has its interface SHOULD 388 therefore NOT be used for anything else, and the user SHOULD be 389 warned not to visit any web pages on that origin. In particular, the 390 OAuth dialog and launch dashboard or token revokation interface 391 SHOULD be on a different origin than the remotestorage interface. 393 Where the use of bearer tokens is impractical, a user may choose to 394 store documents on hard-to-guess URLs whose path after 395 starts with '/public/', while sharing this URL only 396 with the intended audience. That way, only parties who know the 397 document's hard-to-guess URL, can access it. The server SHOULD 398 therefore make an effort to detect and stop brute-force attacks that 399 attempt to guess the location of such documents. 401 The server SHOULD also detect and stop denial-of-service attacks 402 that aim to overwhelm its interface with too much traffic. 404 13. IANA Considerations 406 This document registers the 'remotestorage' link relation. 408 14. Acknowledgements 410 The authors would like to thank everybody who contributed to the 411 development of this protocol, including Kenny Bentley, Javier Diaz, 412 Daniel Groeber, Bjarni Runar, Jan Wildeboer, Charles Schultz, Peter 413 Svensson, Valer Mischenko, Michiel Leenaars, Jan-Christoph 414 Borchardt, Garret Alfert, Sebastian Kippe, Max Wiehle, Melvin 415 Carvalho, Martin Stadler, Geoffroy Couprie, Niklas Cathor, Marco 416 Stahl, James Coglan, Ken Eucker, Daniel Brolund, elf Pavlik, Nick 417 Jennings, and Markus Sabadello, among many others. 419 15. References 421 15.1. Normative References 423 [WORDS] 424 Bradner, S., "Key words for use in RFCs to Indicate Requirement 425 Levels", BCP 14, RFC 2119, March 1997. 427 [IRI] 428 Duerst, M., "Internationalized Resource Identifiers (IRIs)", 429 RFC 3987, January 2005. 431 [WEBFINGER] 432 Jones, Paul E., Salguerio, Gonzalo, and Smarr, Joseph, 433 "WebFinger", draft-ietf-appsawg-webfinger-07, Work in Progress 435 [OAUTH] 436 "Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth 437 2.0 Authorization Framework", RFC6749, October 2012. 439 15.2. Informative References 441 [HTTPS] 442 Rescorla, E., "HTTP Over TLS", RFC2818, May 2000. 444 [CORS] 445 van Kesteren, Anne (ed), "Cross-Origin Resource Sharing -- W3C 446 Working Draft 3 April 2012", 447 http://www.w3.org/TR/2012/WD-cors-20120403/CORS, April 2012. 449 [MANIFEST] 450 Mozilla Developer Network (ed), "App manifest -- Revision 451 330541", https://developer.mozilla.org/en- 452 US/docs/Apps/Manifest$revision/330541, November 2012. 454 16. Authors' addresses 456 Michiel B. de Jong 457 (independent) 459 Email: michiel@michielbdejong.com 461 F. Kooman 462 SURFnet bv 463 Postbus 19035 464 3501 DA Utrecht 465 The Netherlands 467 Email: Francois.Kooman@surfnet.nl