idnits 2.17.1 draft-dejong-remotestorage-03.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 (13 June 2014) is 3605 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) -- Obsolete informational reference (is this intentional?): RFC 2818 (ref. 'HTTPS') (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 2616 (ref. 'HTTP') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 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-03 (independent) 3 F. Kooman 4 Intended Status: Proposed Standard (independent) 5 Expires: 15 December 2014 13 June 2014 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 folder, 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 15 December 2014. 36 Copyright Notice 38 Copyright (c) 2013 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....................................................3 55 3. Storage model..................................................3 56 4. Requests.......................................................4 57 5. Response codes.................................................6 58 6. Versioning.....................................................7 59 7. CORS headers...................................................8 60 8. Session description............................................8 61 9. Bearer tokens and access control...............................9 62 10. Application-first bearer token issuance........................9 63 11. Storage-first bearer token issuance...........................11 64 12. Example wire transcripts......................................12 65 12.1. WebFinger................................................12 66 12.2. OAuth dialog form........................................13 67 12.3. OAuth dialog form submission.............................13 68 12.4. OPTIONS preflight........................................14 69 12.5. Initial PUT..............................................14 70 12.6. Subsequent PUT...........................................15 71 12.7. GET......................................................15 72 12.8. DELETE...................................................16 73 13. Distributed versioning........................................16 74 14. Security Considerations.......................................18 75 15. IANA Considerations...........................................19 76 16. Acknowledgments...............................................19 77 17. References....................................................19 78 17.1. Normative References.....................................19 79 17.2. Informative References...................................19 80 18. Authors' addresses............................................20 82 1. Introduction 84 Many services for data storage are available over the internet. This 85 specification describes a vendor-independent interface for such 86 services. It is based on https, CORS and bearer tokens. The 87 metaphor for addressing data on the storage is that of folders 88 containing documents and subfolders. The actions the interface 89 exposes are: 91 * GET a folder: retrieve the names and current versions of the 92 documents and subfolders currently contained by the folder 94 * GET a document: retrieve its content type, current version, 95 and contents 97 * PUT a document: store a new version, its content type, and 98 contents, conditional on the current version 100 * DELETE a document: remove it from the storage, conditional on 101 the current version 103 * HEAD a folder or document: like GET, but omitting the response 104 body 106 The exact details of these four actions are described in this 107 specification. 109 2. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [WORDS]. 115 "SHOULD" and "SHOULD NOT" are appropriate when valid exceptions to a 116 general requirement are known to exist or appear to exist, and it is 117 infeasible or impractical to enumerate all of them. However, they 118 should not be interpreted as permitting implementors to fail to 119 implement the general requirement when such failure would result in 120 interoperability failure. 122 3. Storage model 124 The server stores data in nodes that form a tree structure. 125 Internal nodes are called 'folders' and leaf nodes are called 126 'documents'. For a folder, the server stores references to nodes 127 contained in the folder, and it should be able to produce a list of 128 them, with for each contained item: 130 * item name 131 * item type (folder or document) 132 * current version 133 * content type 134 * content length 136 For a document, the server stores, and should be able to produce: 138 * current version 139 * content type 140 * content length 141 * content 143 4. Requests 145 Client-to-server requests SHOULD be made over https [HTTPS], and 146 servers MUST comply with HTTP/1.1 [HTTP]. Specifically, they 147 MUST support chunked transfer coding on PUT requests. Servers MAY 148 also offer an optional switch from https to SPDY [SPDY]. 150 The root folder of the storage tree is represented by the following 151 URL: 153 URI_ENCODE( '/' ) 155 Subsequently, if is the URL of a folder, then the 156 URL of an item contained in it is: 158 URI_ENCODE( ) 160 for a document, or: 162 URI_ENCODE( '/' ) 164 for a folder. Item names MAY contain all characters except '/' and 165 the null character, and MUST NOT have zero length. 167 A document description is a map containing one string-valued 'ETag' 168 field, one string-valued 'Content-Type' and one integer-valued 169 'Content-Length' field. They represent the document's current 170 version, its content type, and its content length respectively. Note 171 that content length is measured in octets (bytes), not in 172 characters. 174 A folder description is a map containing a string-valued 'ETag' 175 field, representing the folder's current version. 177 A successful GET request to a folder SHOULD be responded to with a 178 JSON-LD [JSON-LD] document (content type 'application/ld+json'), 179 containing as its 'items' field a map in which contained documents 180 appear as entries to a document description, and 181 contained non-empty folders appear as entries '/' to a 182 folder description. It SHOULD also contain an '@context' field with 183 the value 'http://remotestorage.io/spec/folder-description'. For 184 instance: 186 { 187 "@context": "http://remotestorage.io/spec/folder-description", 188 "items": { 189 "abc": { 190 "ETag": "DEADBEEFDEADBEEFDEADBEEF", 191 "Content-Type": "image/jpeg", 192 "Content-Length": 82352 193 }, 194 "def/": { 195 "ETag": "1337ABCD1337ABCD1337ABCD" 196 } 197 } 198 } 200 All folders are treated as existing, and therefore GET requests to 201 untouched folders SHOULD be responded to with a folder description 202 with no items (the items field set to '{}'). However, an empty 203 folder MUST NOT be listed as an item in its parent folder. 205 Also, since folders exist automatically, PUT and DELETE requests 206 only need to be made to documents, and never to folders. A document 207 PUT will make all ancestor folders along its path become non-empty; 208 deleting the last document from a subtree will make that whole 209 subtree become empty. Folders will therefore show up in their parent 210 folder descriptions if and only if their subtree contains at least 211 one document. 213 A successful GET request to a document SHOULD be responded to with 214 the full document contents in the body, the document's content type 215 in a 'Content-Type' header, its content length in octets (not in 216 characters) in a 'Content-Length' header, and the document's current 217 version as a strong ETag in an 'ETag' header. 219 Note that the use of strong ETags prohibits changing the response 220 body based on request headers; in particular, the server will not be 221 able to serve the same document uncompressed to some clients and 222 gzipped when requested by the client, since the two bodies would not 223 be identical byte-for-byte. 225 Servers MAY support Content-Range headers [HTTP] on GET requests, 226 but whether or not they do SHOULD be announced through the 227 variable mentioned below in section 10. 229 A successful PUT request to a document MUST result in: 231 * the request body being stored as the document's new content, 232 * parent and further ancestor folders being silently created as 233 necessary, with the document (name and version) being added to 234 its parent folder, and each folder added to its subsequent 235 parent, 236 * the value of its Content-Type header being stored as the 237 document's new content type, 238 * its version being updated, as well as that of its parent folder 239 and further ancestor folders, using a strong validator [HTTP, 240 section 13.3.3]. 242 The response MUST contain a strong ETag header, with the document's 243 new version (for instance a hash of its contents) as its value. 245 A successful DELETE request to a document MUST result in: 247 * the deletion of that document from the storage, and from its 248 parent folder, 249 * silent deletion of the parent folder if it is left empty by 250 this, and so on for further ancestor folders, 251 * the version of its parent folder being updated, as well as that 252 of further ancestor folders. 254 A successful OPTIONS request SHOULD be responded to as described in 255 the CORS section below. 257 A successful HEAD request SHOULD be responded to like to the 258 equivalent GET request, but omitting the response body. 260 5. Response codes 262 Response codes SHOULD be given as defined by [HTTP, section 10] and 263 [BEARER, section 3.1]. The following is a non-normative checklist 264 of status codes that are likely to occur in practice: 266 * 500 if an internal server error occurs, 267 * 429 if the client makes too frequent requests or is suspected 268 of malicious activity, 269 * 414 if the request URI is too long, 270 * 416 if Range requests are supported by the server and the Range 271 request can not be satisfied, 272 * 401 for all requests that don't have a bearer token with 273 sufficient permissions, 274 * 404 for all DELETE and GET requests to nodes that do not exist 275 on the storage, 276 * 304 for a conditional GET request whose pre-condition 277 fails (see "Versioning" below), 278 * 409 for a PUT request where any folder name in the path 279 clashes with an existing document's name at the same 280 level, or where the document name coincides with an 281 existing folder's name at the same level. 282 * 412 for a conditional PUT or DELETE request whose pre-condition 283 fails (see "Versioning" below), 284 * 507 in case the user's account is over its storage quota, 285 * 4xx for all malformed requests (e.g. foreign characters in the 286 path), as well as for all PUT and DELETE requests to 287 folders, 288 * 2xx for all successful requests. 290 Clients SHOULD also handle the case where a response takes too long 291 to arrive, or where no response is received at all. 293 6. Versioning 295 All successful requests MUST return an 'Expires: 0' header, and an 296 'ETag' header [HTTP] with, in the case of GET, the current version, 297 in the case of PUT, the new version, and in case of DELETE, the 298 version that was deleted. PUT and DELETE requests MAY have an 299 'If-Match' request header [HTTP], and MUST fail with a 412 response 300 code if that doesn't match the document's current version. 302 GET requests MAY have a comma-separated list of revisions in an 303 'If-None-Match' header [HTTP], and SHOULD be responded to with a 412 304 response if that list includes the document or folder's current 305 version. A PUT request MAY have an 'If-None-Match: *' header [HTTP], 306 in which case it MUST fail with a 412 response code if the document 307 already exists. 309 In all 'ETag', 'If-Match' and 'If-None-Match' headers, revision 310 strings should appear inside double quotes ("). 312 A provider MAY offer version rollback functionality to its users, 313 but this specification does not define the user interface for that. 315 7. CORS headers 317 All responses MUST carry CORS headers [CORS]. The server MUST also 318 reply to OPTIONS requests as per CORS. For GET requests, a wildcard 319 origin MAY be returned, but for PUT and DELETE requests, the 320 response MUST echo back the Origin header sent by the client. 322 8. Session description 324 The information that a client needs to receive in order to be able 325 to connect to a server SHOULD reach the client as described in the 326 'bearer token issuance' sections below. It consists of: 328 * , consisting of 'https://' followed by a server 329 host, and optionally a server port and a path prefix as per 330 [IRI]. Examples: 331 * 'https://example.com' (host only) 332 * 'https://example.com:8080' (host and port) 333 * 'https://example.com/path/to/storage' (host, port and 334 path prefix; note there is no trailing slash) 335 * as per [OAUTH]. The token SHOULD be hard to 336 guess and SHOULD NOT be reused from one client to another. It 337 can however be reused in subsequent interactions with the same 338 client, as long as that client is still trusted. Example: 339 * 'ofb24f1ac3973e70j6vts19qr9v2eei' 340 * , always 'draft-dejong-remotestorage-03' for this 341 alternative version of the specification. 343 The client can make its requests using https with CORS and bearer 344 tokens, to the URL that is the concatenation of with 345 '/' plus one or more '/' strings indicating a path in the 346 folder tree, followed by zero or one strings, indicating 347 a document. For example, if is 348 "https://storage.example.com/bob", then to retrieve the folder 349 contents of the /public/documents/ folder, or to retrieve a 350 'draft.txt' document from that folder, the client would make 351 requests to, respectively: 353 * https://storage.example.com/bob/public/documents/ 354 * https://storage.example.com/bob/public/documents/draft.txt 356 9. Bearer tokens and access control 358 A bearer token represents one or more access scopes. These access 359 scopes are represented as strings of the form , 360 where the string SHOULD be lower-case alphanumerical, other 361 than the reserved word 'public', and can be ':r' or ':rw'. 362 The access the bearer token gives is the sum of its access scopes, 363 with each access scope representing the following permissions: 365 '*:rw') any request, 367 '*:r') any GET or HEAD request, 369 ':rw') any requests to paths that start with 370 '/' '/' or '/public/' '/', 372 ':r') any GET or HEAD requests to paths that start with 373 '/' '/' or '/public/' '/', 375 As a special exceptions, GET requests to a document (but not a 376 folder) whose path starts with '/public/' are always allowed. They, 377 as well as OPTIONS requests, can be made without a bearer token. 378 Unless [KERBEROS] is used (see section 10 below), all other requests 379 SHOULD present a bearer token with sufficient access scope, using a 380 header of the following form (no double quotes here): 382 Authorization: Bearer 384 In addition, providing the access token via a HTTP query parameter 385 for GET requests MAY be supported by the server, although its use 386 is not recommended, due to its security deficiencies; see [BEARER, 387 section 2.3]. 389 10. Application-first bearer token issuance 391 To make a remoteStorage server available as 'the remoteStorage of 392 at ', exactly one link of the following format SHOULD 393 be added to the webfinger record [WEBFINGER] of at : 395 { 396 "href": , 397 "rel": "remotestorage", 398 "properties": { 399 "http://remotestorage.io/spec/version": , 400 "http://tools.ietf.org/html/rfc6749#section-4.2": , 401 "http://tools.ietf.org/html/rfc6750#section-2.3": , 402 "https://tools.ietf.org/html/rfc2616#section-14.16": 403 } 404 } 406 Here and are as per "Session 407 description" above, and SHOULD be eihter the boolean 408 value false or a URL where an OAuth 2.0 implicit-grant flow dialog 409 [OAUTH] is presented. 411 If is a URL, the user can supply their credentials 412 there (how, is out of scope), and allow or reject a request by the 413 connecting application to obtain a bearer token for a certain list 414 of access scopes. 416 If is false, the client will not have a way to obtain 417 an access token, and SHOULD send all requests without Authorization 418 header, and rely on Kerberos [KERBEROS] instead for requests that 419 would normally be sent with a bearer token, but servers SHOULD NOT 420 impose any such access barriers for resources that would normally 421 not require an access token. 423 The variable SHOULD have the boolean value true if 424 the server supports passing the bearer token in the URI query 425 parameter as per section 2.3 of [BEARER], and false otherwise. 427 The variable SHOULD have a string value of "GET" if 428 Content-Range headers are supported for GET requests as per 429 [HTTP, section 14.16], and the boolean value false if not. 431 The server MAY expire bearer tokens, and MAY require the user to 432 register applications as OAuth clients before first use; if no 433 client registration is required, then the server MAY ignore the 434 client_id parameter in favor of relying on the redirect_uri 435 parameter for client identification. 437 11. Storage-first bearer token issuance 439 The provider MAY also present a dashboard to the user, where they 440 have some way to add open web app manifests [MANIFEST]. Adding a 441 manifest to the dashboard is considered equivalent to clicking 442 'accept' in the dialog of the application-first flow. Removing one 443 is considered equivalent to revoking its access token. 445 As an equivalent to OAuth's 'scope' parameter, a 'datastores-access' 446 field SHOULD be present in the root of such an application manifest 447 document, with entries -> '{"access": "readonly"}' for 448 'r' or '{"access": "readwrite"}' for 'rw', as 449 prescribed in [DATASTORE]. 451 When the user gestures they want to use a certain application whose 452 manifest is present on the dashboard, the dashboard SHOULD redirect 453 to the application or open it in a new window. To mimic coming back 454 from the OAuth dialog, it MAY add 'access_token' and 'scope' 455 fields to the URL fragment. 457 Regardless of whether 'access_token' and 'scope' are specified, it 458 SHOULD add a 'remotestorage' field to the URL fragment, with a 459 value of the form '@' . When the application detects 460 this parameter, it SHOULD resolve the webfinger record for at 461 and extract the and information. 463 If no access_token was given, then the application SHOULD also 464 extract the information from webfinger, and continue 465 as per application-first bearer token issuance. 467 Note that whereas a remoteStorage server SHOULD offer support of the 468 application-first flow with webfinger and OAuth, it MAY choose not 469 to support the storage-first flow, provided that users will easily 470 remember their '@' webfinger address at that provider. 471 Applications SHOULD, however, support both flows, which means 472 checking the URL for a 'remotestorage' parameter, but giving the 473 user a way to specify their webfinger address if there is none. 475 If a server provides an application manifest dashboard, then it 476 SHOULD merge the list of applications there with the list of 477 issued access tokens as specified by OAuth into one list. Also, 478 the interface for revoking an access token as specified by OAuth 479 SHOULD coincide with removing an application from the dashboard. 481 Servers MAY also provide a way to create access tokens directly from 482 their user interface. Such functionality would be aimed mainly at 483 developers, to manually copy and paste a token into a script or 484 debug tool, thus bypassing the need for an OAuth dance. Clients 485 SHOULD NOT rely on this in production. 487 12. Example wire transcripts 489 The following examples are not normative ("\" indicates a line was 490 wrapped). 492 12.1. WebFinger 494 In application-first, an in-browser application might issue the 495 following request, using XMLHttpRequest and CORS: 497 GET /.well-known/webfinger?resource=acct:michiel@michielbdejon\ 498 g.com HTTP/1.1 499 Host: michielbdejong.com 501 and the server's response might look like this: 503 HTTP/1.1 200 OK 504 Access-Control-Allow-Origin: * 505 Access-Control-Allow-Methods: GET 506 Access-Control-Allow-Headers: If-Match, If-None-Match 507 Access-Control-Expose-Headers: ETag, Content-Type, Content-Len\ 508 gth 510 { 511 "links":[{ 512 "href": "https://michielbdejong.com:7678/inbox", 513 "rel": "post-me-anything" 514 }, { 515 "href": "https://michielbdejong.com/me.jpg", 516 "rel": "avatar" 517 }, { 518 "href": "https://3pp.io:4439/storage/michiel", 519 "rel": "remotestorage", 520 "properties": { 521 "http://remotestorage.io/spec/version": "draft-dejong-re\ 523 motestorage-03", 524 "http://tools.ietf.org/html/rfc6750#section-4.2": "https\ 525 ://3pp.io:4439/oauth/michiel", 526 "http://tools.ietf.org/html/rfc6750#section-2.3": false, 527 "http://tools.ietf.org/html/rfc2616#section-14.16": false 528 } 529 }] 530 } 532 12.2. OAuth dialog form 534 Once the in-browser application has discovered the server's OAuth 535 end-point, it will typically redirect the user to this URL, in 536 order to obtain a bearer token. Say the application is hosted on 537 https://drinks-unhosted.5apps.com/ and wants read-write access to 538 the user's "myfavoritedrinks" scope: 540 GET /oauth/michiel?redirect_uri=https%3A%2F%2Fdrinks-unhosted.5\ 541 apps.com%2F&scope=myfavoritedrinks%3Arw&client_id=https%3A%2F%2Fdrinks-\ 542 unhosted.5apps.com&response_type=token HTTP/1.1 543 Host: 3pp.io 545 The server's response might look like this (truncated for brevity): 547 HTTP/1.1 200 OK 549 550 551 552 Allow access? 553 ... 555 12.3. OAuth dialog form submission 557 When the user submits the form, the request would look something 558 like this: 560 POST /oauth HTTP/1.1 561 Host: 3pp.io:4439 562 Origin: https://3pp.io:4439 563 Content-Type: application/x-www-form-urlencoded 564 Referer: https://3pp.io:4439/oauth/michiel?redirect_uri=https%3\ 566 A%2F%2Fdrinks-unhosted.5apps.com%2F&scope=myfavoritedrinks%3Arw&client_\ 567 id=https%3A%2F%2Fdrinks-unhosted.5apps.com&response_type=token 569 client_id=https%3A%2F%2Fdrinks-unhosted.5apps.com&redirect_uri=\ 570 https%3A%2F%2Fdrinks-unhosted.5apps.com%2F&response_type=token&scope=my\ 571 favoritedrinks%3Arw&state=&username=michiel&password=something&allow=Al\ 572 low 574 To which the server could respond with a 302 redirect, back to the 575 origin of the requesting application: 577 HTTP/1.1 302 Found 578 Location:https://drinks-unhosted.5apps.com/#access_token=j2YnGt\ 579 XjzzzHNjkd1CJxoQubA1o%3D&token_type=bearer&state= 581 12.4. OPTIONS preflight 583 When an in-browser application makes a cross-origin request which 584 may affect the server-state, the browser will make a preflight 585 request first, with the OPTIONS verb, for instance: 587 OPTIONS /storage/michiel/myfavoritedrinks/ HTTP/1.1 588 Host: 3pp.io:4439 589 Access-Control-Request-Method: GET 590 Origin: https://drinks-unhosted.5apps.com 591 Access-Control-Request-Headers: Authorization 592 Referer: https://drinks-unhosted.5apps.com/ 594 To which the server can for instance respond: 596 HTTP/1.1 200 OK 597 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 598 Access-Control-Allow-Methods: GET, PUT, DELETE 599 Access-Control-Allow-Headers: Authorization, Content-Length, Co\ 600 ntent-Type, Origin, X-Requested-With, If-Match, If-None-Match 602 12.5. Initial PUT 604 An initial PUT may contain an 'If-None-Match: *' header, like this: 606 PUT /storage/michiel/myfavoritedrinks/test HTTP/1.1 607 Host: 3pp.io:4439 608 Content-Length: 91 609 Origin: https://drinks-unhosted.5apps.com 610 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 611 Content-Type: application/json; charset=UTF-8 612 Referer: https://drinks-unhosted.5apps.com/? 613 If-None-Match: * 615 {"name":"test","@context":"http://remotestorage.io/spec/modules\ 616 /myfavoritedrinks/drink"} 618 And the server may respond with either a 201 Created or a 200 OK 619 status: 621 HTTP/1.1 201 Created 622 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 623 ETag: "1382694045000" 625 12.6. Subsequent PUT 627 A subsequent PUT may contain an 'If-Match' header referring to the 628 ETag previously returned, like this: 630 PUT /storage/michiel/myfavoritedrinks/test HTTP/1.1 631 Host: 3pp.io:4439 632 Content-Length: 91 633 Origin: https://drinks-unhosted.5apps.com 634 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 635 Content-Type: application/json; charset=UTF-8 636 Referer: https://drinks-unhosted.5apps.com/? 637 If-Match: "1382694045000" 639 {"name":"test", "updated":true, "@context":"http://remotestorag\ 640 e.io/spec/modules/myfavoritedrinks/drink"} 642 And the server may respond with a 412 Conflict or a 200 OK status: 644 HTTP/1.1 200 OK 645 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 646 ETag: "1382694048000" 648 12.7. GET 650 A GET request would also include the bearer token, and optionally 651 an If-None-Match header: 653 GET /storage/michiel/myfavoritedrinks/test HTTP/1.1 654 Host: 3pp.io:4439 655 Origin: https://drinks-unhosted.5apps.com 656 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 657 Referer: https://drinks-unhosted.5apps.com/? 658 If-None-Match: "1382694045000", "1382694048000" 660 {"name":"test", "updated":true, "@context":"http://remotestora\ 661 ge.io/spec/modules/myfavoritedrinks/drink"} 663 And the server may respond with a 304 Not Modified or a 200 OK 664 status: 666 HTTP/1.1 304 Not Modified 667 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 668 ETag: "1382694048000" 670 12.8. DELETE 672 A DELETE request may look like this: 674 DELETE /storage/michiel/myfavoritedrinks/test HTTP/1.1 675 Host: 3pp.io:4439 676 Origin: https://drinks-unhosted.5apps.com 677 Authorization: Bearer j2YnGtXjzzzHNjkd1CJxoQubA1o= 678 Content-Type: application/json; charset=UTF-8 679 Referer: https://drinks-unhosted.5apps.com/? 680 If-Match: "1382694045000" 682 And the server may respond with a 412 Conflict or a 200 OK status: 684 HTTP/1.1 412 Conflict 685 Access-Control-Allow-Origin: https://drinks-unhosted.5apps.com 686 ETag: "1382694048000" 688 13. Distributed versioning 690 This section is non-normative, and is intended to explain some of 691 the design choices concerning ETags and folder listings. At the 692 same time it will hopefully help readers who intend to develop an 693 application that uses remoteStorage as its per-user data storage. 694 When multiple clients have read/write access to the same document, 695 versioning conflicts may occur. For instance, client A may make 696 a PUT request that changes the document from version 1 to version 697 2, after which client B may make a PUT request attempting to change 698 the same document from version 1 to version 3. 700 In this case, client B can add an 'If-Match: "1"' header, which 701 would trigger a 412 Conflict response code, since the current 702 version ("2") does not match the version required as a condition by 703 the header If-Match header ("1"). 705 Client B is now aware of the conflict, and may consult the user, 706 saying the update to version 3 failed. The user may then choose, 707 through the user interface of client B, whether version 2 or 708 version 3 should be kept, or maybe the document should be reverted 709 on the server to version 1, or a merged version 4 is needed. Client 710 B may then make a request that puts the document to the version the 711 user wishes; this time setting an 'If-Match: "2"' header instead. 713 Both client A and client B would periodically poll the root 714 folder of each scope they have access to, to see if the version 715 of the root folder changed. If it did, then one of the versions 716 listed in there will necessarily have changed, and the client can 717 make a GET request to that child folder or document, to obtain 718 its latest version. 720 Because an update in a document will result in a version change of 721 its containing folder, and that change will propagate all the way 722 to the root folder, it is not necessary to poll each document for 723 changes individually. 725 As an example, the root folder may contain 10 directories, 726 each of which contain 10 directories, which each contain 10 727 documents, so their paths would be for instance '/0/0/1', '/0/0/2', 728 etcetera. Then one GET request to the root folder '/' will be 729 enough to know if any of these 1000 documents has changed. 731 Say document '/7/9/2' has changed; then the GET request to '/' will 732 come back with a different ETag, and entry '7/' will have a 733 different value in its JSON content. The client could then request 734 '/7/', '/7/9/', and '/7/9/2' to narrow down the one document that 735 caused the root folder's ETag to change. 737 Note that the remoteStorage server does not get involved in the 738 conflict resolution. It keeps the canonical current version at all 739 times, and allows clients to make conditional GET and PUT requests, 740 but it is up to whichever client discovers a given version 741 conflict, to resolve it. 743 14. Security Considerations 745 To prevent man-in-the-middle attacks, the use of https instead of 746 http is important for both the interface itself and all end-points 747 involved in webfinger, OAuth, and (if present) the storage-first 748 application launch dashboard. 750 A malicious party could link to an application, but specifying a 751 remoteStorage user address that it controls, thus tricking the user 752 into using a trusted application to send sensitive data to the wrong 753 remoteStorage server. To mitigate this, applications SHOULD clearly 754 display to which remoteStorage server they are sending the user's 755 data. 757 Applications could request scopes that the user did not intend to 758 give access to. The user SHOULD always be prompted to carefully 759 review which scopes an application is requesting. 761 An application may upload malicious html pages and then trick the 762 user into visiting them, or upload malicious client-side scripts, 763 that take advantage of being hosted on the user's domain name. The 764 origin on which the remoteStorage server has its interface SHOULD 765 therefore NOT be used for anything else, and the user SHOULD be 766 warned not to visit any web pages on that origin. In particular, the 767 OAuth dialog and launch dashboard or token revokation interface 768 SHOULD be on a different origin than the remoteStorage interface. 770 Where the use of bearer tokens is impractical, a user may choose to 771 store documents on hard-to-guess URLs whose path after 772 starts with '/public/', while sharing this URL only 773 with the intended audience. That way, only parties who know the 774 document's hard-to-guess URL, can access it. The server SHOULD 775 therefore make an effort to detect and stop brute-force attacks that 776 attempt to guess the location of such documents. 778 The server SHOULD also detect and stop denial-of-service attacks 779 that aim to overwhelm its interface with too much traffic. 781 15. IANA Considerations 783 This document registers the 'remotestorage' link relation, as well 784 as the following WebFinger properties: 785 * "http://remotestorage.io/spec/version" 786 * "http://tools.ietf.org/html/rfc6749#section-4.2" 787 * "http://tools.ietf.org/html/rfc6750#section-2.3" 788 * "https://tools.ietf.org/html/rfc2616#section-14.16 790 16. Acknowledgements 792 The authors would like to thank everybody who contributed to the 793 development of this protocol, including Kenny Bentley, Javier Diaz, 794 Daniel Groeber, Bjarni Runar, Jan Wildeboer, Charles Schultz, Peter 795 Svensson, Valer Mischenko, Michiel Leenaars, Jan-Christoph 796 Borchardt, Garret Alfert, Sebastian Kippe, Max Wiehle, Melvin 797 Carvalho, Martin Stadler, Geoffroy Couprie, Niklas Cathor, Marco 798 Stahl, James Coglan, Ken Eucker, Daniel Brolund, elf Pavlik, Nick 799 Jennings, Markus Sabadello, Steven te Brinke, Matthias Treydte, 800 Rick van Rein, Mark Nottingham, Julian Reschke, and Markus 801 Lanthaler, among many others. 803 17. References 805 17.1. Normative References 807 [WORDS] 808 Bradner, S., "Key words for use in RFCs to Indicate Requirement 809 Levels", BCP 14, RFC 2119, March 1997. 811 [IRI] 812 Duerst, M., "Internationalized Resource Identifiers (IRIs)", 813 RFC 3987, January 2005. 814 [WEBFINGER] 815 Jones, P., Salguerio, G., Jones, M, and Smarr, J., 816 "WebFinger", RFC7033, September 2013. 818 [OAUTH] 819 "Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth 820 2.0 Authorization Framework", RFC6749, October 2012. 822 17.2. Informative References 824 [HTTPS] 825 Rescorla, E., "HTTP Over TLS", RFC2818, May 2000. 826 [HTTP] 827 Fielding et al., "Hypertext Transfer Protocol -- HTTP/1.1", 828 RFC2616, June 1999. 830 [SPDY] 831 Mark Belshe, Roberto Peon, "SPDY Protocol - Draft 3.1", http:// 832 www.chromium.org/spdy/spdy-protocol/spdy-protocol-draft3-1, 833 September 2013. 835 [JSON-LD] 836 M. Sporny, G. Kellogg, M. Lanthaler, "JSON-LD 1.0", W3C 837 Proposed Recommendation, 838 http://www.w3.org/TR/2014/REC-json-ld-20140116/, January 2014. 840 [CORS] 841 van Kesteren, Anne (ed), "Cross-Origin Resource Sharing -- 842 W3C Candidate Recommendation 29 January 2013", 843 http://www.w3.org/TR/cors/, January 2013. 845 [MANIFEST] 846 Mozilla Developer Network (ed), "App manifest -- Revision 847 330541", https://developer.mozilla.org/en- 848 US/Apps/Build/Manifest$revision/566677, April 2014. 850 [DATASTORE] 851 "WebAPI/DataStore", MozillaWiki, retrieved May 2014. 852 https://wiki.mozilla.org/WebAPI/DataStore#Manifest 854 [KERBEROS] 855 C. Neuman et al., "The Kerberos Network Authentication Service 856 (V5)", RFC4120, 857 https://tools.ietf.org/html/rfc4120 859 [BEARER] 860 M. Jones, D. Hardt, "The OAuth 2.0 Authorization Framework: 861 Bearer Token Usage", RFC6750, 862 http://tools.ietf.org/html/rfc6750#section-2.3, October 2012. 864 18. Authors' addresses 866 Michiel B. de Jong 867 (independent) 869 Email: michiel@michielbdejong.com 871 F. Kooman 872 (independent) 874 Email: fkooman@tuxed.net