Untitled diff

Created Diff never expires
138 removals
566 lines
158 additions
583 lines
INTERNET DRAFT Michiel B. de Jong
INTERNET DRAFT Michiel B. de Jong
Document: draft-dejong-remotestorage-00 (independent)
Document: draft-dejong-remotestorage-01 (independent)
F. Kooman
F. Kooman
Intended Status: Proposed Standard SURFnet
Intended Status: Proposed Standard SURFnet
Expires: 8 June 2013 5 December 2012
Expires: 10 December 2013 8 June 2013
remotestorage
remoteStorage
Abstract
Abstract
This draft describes a protocol by which client-side applications,
This draft describes a protocol by which client-side applications,
running inside a web browser, can communicate with a data storage
running inside a web browser, can communicate with a data storage
server that is hosted on a different domain name. This way, the
server that is hosted on a different domain name. This way, the
provider of a web application need not also play the role of data
provider of a web application need not also play the role of data
storage provider. The protocol supports storing, retrieving, and
storage provider. The protocol supports storing, retrieving, and
removing individual documents, as well as listing the contents of an
removing individual documents, as well as listing the contents of an
individual directory, and access control is based on bearer tokens.
individual directory, and access control is based on bearer tokens.
Status of this Memo
Status of this Memo
This Internet-Draft is submitted in full conformance with the
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 9 June 2013.
This Internet-Draft will expire on 10 December 2013.
Copyright Notice
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
described in the Simplified BSD License.
de Jong [Page 1]
de Jong [Page 1]
Internet-Draft remotestorage December 2012
Internet-Draft remoteStorage June 2013
Table of Contents
Table of Contents
1. Introduction...................................................2
1. Introduction...................................................2
2. Terminology....................................................2
2. Terminology....................................................2
3. Storage model..................................................3
3. Storage model..................................................3
4. Requests.......................................................3
4. Requests.......................................................3
5. Response codes.................................................4
5. Response codes.................................................4
6. Versioning.....................................................5
6. Versioning.....................................................5
7. CORS headers...................................................5
7. CORS headers...................................................5
8. Session description............................................5
8. Session description............................................5
9. Bearer tokens and access control...............................6
9. Bearer tokens and access control...............................6
10. Application-first bearer token issuance........................6
10. Application-first bearer token issuance........................6
11. Storage-first bearer token issuance............................7
11. Storage-first bearer token issuance............................7
12. Security Considerations........................................8
12. Security Considerations........................................8
13. IANA Considerations............................................9
13. IANA Considerations............................................9
14. Acknowledgments................................................9
14. Acknowledgments................................................9
15. References.....................................................9
15. References.....................................................9
15.1. Normative References......................................9
15.1. Normative References......................................9
15.2. Informative References....................................9
15.2. Informative References....................................9
16. Authors' addresses............................................10
16. Authors' addresses............................................10
1. Introduction
1. Introduction
Many services for data storage are available over the internet. This
Many services for data storage are available over the internet. This
specification describes a vendor-independent interface for such
specification describes a vendor-independent interface for such
services. It is based on https, CORS and bearer tokens. The
services. It is based on https, CORS and bearer tokens. The
metaphor for addressing data on the storage is that of folders
metaphor for addressing data on the storage is that of folders
containing documents and subfolders. The actions the interface
containing documents and subfolders. The actions the interface
exposes are:
exposes are:
* GET a folder: retrieve the names and current versions of the
* GET a folder: retrieve the names and current versions of the
documents and subfolders currently contained by the folder
documents and subfolders currently contained by the folder
* GET a document: retrieve its content type, current version,
* GET a document: retrieve its content type, current version,
and contents
and contents
* PUT a document: store a new version, its content type, and
* PUT a document: store a new version, its content type, and
contents, conditional on the current version
contents, conditional on the current version
* DELETE a document: remove it from the storage, conditional on
* DELETE a document: remove it from the storage, conditional on
the current version
the current version
The exact details of these four actions are described in this
The exact details of these four actions are described in this
specification.
specification.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
de Jong [Page 2]
de Jong [Page 2]
Internet-Draft remotestorage December 2012
Internet-Draft remoteStorage June 2013
2. Terminology
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 [WORDS].
document are to be interpreted as described in RFC 2119 [WORDS].
"SHOULD" and "SHOULD NOT" are appropriate when valid exceptions to a
"SHOULD" and "SHOULD NOT" are appropriate when valid exceptions to a
general requirement are known to exist or appear to exist, and it is
general requirement are known to exist or appear to exist, and it is
infeasible or impractical to enumerate all of them. However, they
infeasible or impractical to enumerate all of them. However, they
should not be interpreted as permitting implementors to fail to
should not be interpreted as permitting implementors to fail to
implement the general requirement when such failure would result in
implement the general requirement when such failure would result in
interoperability failure.
interoperability failure.
3. Storage model
3. Storage model
The server stores data in nodes that form a tree structure.
The server stores data in nodes that form a tree structure.
Internal nodes are called 'folders' and leaf nodes are called
Internal nodes are called 'folders' and leaf nodes are called
'documents'. For a folder, the server stores references to nodes
'documents'. For a folder, the server stores references to nodes
contained in the folder, and it should be able to produce a list of
contained in the folder, and it should be able to produce a list of
them, with for each contained item:
them, with for each contained item:
* item name
* item name
* item type (folder or document)
* item type (folder or document)
* current version
* current version
For a document, the server stores, and should be able to produce:
For a document, the server stores, and should be able to produce:
* content type
* content type
* content
* content
* current version
* current version
4. Requests
4. Requests
Client-to-server requests SHOULD be made over https [HTTPS]. The
Client-to-server requests SHOULD be made over https [HTTPS]. The
root folder of the storage tree is represented by the URL
root folder of the storage tree is represented by the URL
<storage_root> '/'. Subsequently, if <parent_folder> is the URL of a
<storage_root> '/'. Subsequently, if <parent_folder> is the URL of a
folder, then the URL of an item contained in it is
folder, then the URL of an item contained in it is
<parent_folder> <document_name> for a document, or
<parent_folder> <document_name> for a document, or
<parent_folder> <folder_name> '/' for a folder. Item names MAY
<parent_folder> <folder_name> '/' for a folder. Item names MAY
contain a-z, A-Z, 0-9, %, -, _.
contain a-z, A-Z, 0-9, %, ., -, _, and MUST NOT have zero length.
A successful GET request to a folder SHOULD be responded to with a
A successful GET request to a folder SHOULD be responded to with a
JSON document (content type 'application/json'), representing a map
JSON document (content type 'application/json'), representing a map
in which contained documents appear as entries <item_name> to
in which contained documents appear as entries <item_name> to
<current_version>, and contained folders appear as entries
<current_version>, and contained folders appear as entries
<item_name> '/' to <current_version>, for instance:
<item_name> '/' to <current_version>, for instance:
de Jong [Page 3]
Internet-Draft remoteStorage June 2013
{
{
"abc": 1234567890123,
"abc": 1234567890123,
"def/": 1234567890456
"def/": 1234567890456
}
}
Empty folders are treated as non-existing, and therefore GET
Empty folders are treated as non-existing, and therefore GET
requests to them SHOULD be responded to with a 404 response, and an
requests to them SHOULD be responded to with a 404 response, and an
de Jong [Page 3]
Internet-Draft remotestorage December 2012
empty folder MUST NOT be listed as an item in its parent folder.
empty folder MUST NOT be listed as an item in its parent folder.
Also, folders SHOULD be created silently, as necessary to contain
Also, folders SHOULD be created silently, as necessary to contain
newly added items. This way, PUT and DELETE requests only need to be
newly added items. This way, PUT and DELETE requests only need to be
made to documents, and folder management becomes an implicit result.
made to documents, and folder management becomes an implicit result.
A successful GET request to a document SHOULD be responded to with
A successful GET request to a document SHOULD be responded to with
the full document contents in the body, the document's content type
the full document contents in the body, the document's content type
in a 'Content-Type' header, and the document's current version in an
in a 'Content-Type' header, and the document's current version in an
'ETag' header.
'ETag' header.
A successful PUT request to a document MUST result in:
A successful PUT request to a document MUST result in:
* the request body being stored as the document's new content,
* the request body being stored as the document's new content,
* parent and further ancestor folders being silently created as
* parent and further ancestor folders being silently created as
necessary, with the document (name and version) being added to
necessary, with the document (name and version) being added to
its parent folder, and each folder added to its subsequent
its parent folder, and each folder added to its subsequent
parent,
parent,
* the value of its Content-Type header being stored as the
* the value of its Content-Type header being stored as the
document's new content type,
document's new content type,
* the current server time, in the form of milliseconds since
* its version being updated, as well as that of its parent folder
0:00 UCT, 1 January, 1970 being stored as the new version of
and further ancestor folders.
the document itself, as well as of its parent folder and
further ancestor folders.
The response MUST contain an ETag header, with the document's new
The response MUST contain an ETag header, with the document's new
version (milliseconds since the beginning of 1970) as its value.
version (for instance a hash of its contents) as its value.
A successful DELETE request to a document MUST result in the
A successful DELETE request to a document MUST result in the
deletion of that document from the storage, and from its parent
deletion of that document from the storage, and from its parent
folder. If the parent folder is left empty by this, then it MUST
folder. If the parent folder is left empty by this, then it MUST
also be removed, and so on for ancestor folders.
also be removed, and so on for ancestor folders.
A successful OPTIONS request SHOULD be responded to as described in
A successful OPTIONS request SHOULD be responded to as described in
the CORS section below.
the CORS section below.
5. Response codes
5. Response codes
The following responses SHOULD be given in the indicated cases, in
The following responses SHOULD be given in the indicated cases, in
order of preference, and SHOULD be recognized by the client:
order of preference, and SHOULD be recognized by the client:
de Jong [Page 4]
Internet-Draft remoteStorage June 2013
* 500 if an internal server error occurs,
* 500 if an internal server error occurs,
* 420 if the client makes too frequent requests or is suspected
* 420 if the client makes too frequent requests or is suspected
of malicious activity,
of malicious activity,
* 400 for all malformed requests (e.g. foreign characters in the
* 400 for all malformed requests (e.g. foreign characters in the
path or unrecognized http verb, etcetera), as well as for
path or unrecognized http verb, etcetera), as well as for
all PUT and DELETE requests to folders,
all PUT and DELETE requests to folders,
* 401 for all requests that don't have a bearer token with
* 401 for all requests that don't have a bearer token with
sufficient permissions,
sufficient permissions,
* 404 for all DELETE and GET requests to nodes that do not exist
* 404 for all DELETE and GET requests to nodes that do not exist
de Jong [Page 4]
Internet-Draft remotestorage December 2012
on the storage,
on the storage,
* 304 for a conditional GET request whose condition fails
* 412 for a conditional request whose pre-condition
(see "Versioning" below),
* 409 for a conditional PUT or DELETE request whose condition
fails (see "Versioning" below),
fails (see "Versioning" below),
* 200 for all successful requests, including PUT and DELETE,
* 507 in case the user's account is over its storage quota,
* 200 for all successful requests, including PUT and DELETE.
Clients SHOULD also handle the case where a response takes too long
Clients SHOULD also handle the case where a response takes too long
to arrive, or where no response is received at all.
to arrive, or where no response is received at all.
6. Versioning
6. Versioning
The current version of a document is the 13-digit decimal number
All successful requests MUST return an 'ETag' header [HTTP] with,
representing the number of milliseconds between 00:00 UCT, 1 January
in the case of GET, the current version, in the case of PUT, the
1970, and the last time its content or content type were set or
new version, and in case of DELETE, the version that was deleted.
changed successfully. The current version of a folder is the highest
PUT and DELETE requests MAY have an 'If-Match' request header
version of any of the items it contains.
[HTTP], and MUST fail with a 412 response code if that doesn't match
All successful requests MUST return an 'ETag' header with, in the
case of GET, the current version, in the case of PUT, the new
version, and in case of DELETE, the version that was deleted. PUT
and DELETE requests MAY have an 'If-Unmodified-Since' request
header, and MUST fail with a 409 response code if that doesn't match
the document's current version. GET requests MAY have an
the document's current version. GET requests MAY have an
'If-Modified-Since' header, and SHOULD be responded to with a 304 if
'If-None-Match' header [HTTP], and SHOULD be responded to with a 412
that matches the document or folder's current version.
response if that includes the document or folder's current version.
A PUT request MAY have an 'If-None-Match:*' header [HTTP], in which
case it MUST fail with a 412 response code if the document already
exists.
A provider MAY offer its users a way to roll back to a previous
version of the storage contents, but this specification does not
define any such rollback functionality.
7. CORS headers
7. CORS headers
All responses MUST carry CORS headers [CORS]. The server MUST also
All responses MUST carry CORS headers [CORS]. The server MUST also
reply to OPTIONS requests as per CORS. For GET requests, a wildcard
reply to OPTIONS requests as per CORS. For GET requests, a wildcard
origin MAY be returned, but for PUT and DELETE requests, the
origin MAY be returned, but for PUT and DELETE requests, the
response MUST echo back the Origin header sent by the client.
response MUST echo back the Origin header sent by the client.
de Jong [Page 5]
Internet-Draft remoteStorage June 2013
8. Session description
8. Session description
The information that a client needs to receive in order to be able
The information that a client needs to receive in order to be able
to connect to a server SHOULD reach the client as described in the
to connect to a server SHOULD reach the client as described in the
'bearer token issuance' sections below. It consists of:
'bearer token issuance' sections below. It consists of:
* <storage_root>, consisting of 'https://' followed by a server
* <storage_root>, consisting of 'https://' followed by a server
host, and optionally a server port and a path prefix as per
host, and optionally a server port and a path prefix as per
[IRI]. Examples:
[IRI]. Examples:
* 'https://example.com' (host only)
* 'https://example.com' (host only)
* 'https://example.com:8080' (host and port)
* 'https://example.com:8080' (host and port)
* 'https://example.com/some?path/to/storage' (host, port and
* 'https://example.com/path/to/storage' (host, port and
path prefix; note there is no trailing slash)
path prefix; note there is no trailing slash)
* <access_token> as per [OAUTH]. The token SHOULD be hard to
* <access_token> as per [OAUTH]. The token SHOULD be hard to
guess and SHOULD NOT be reused from one client to another. It
guess and SHOULD NOT be reused from one client to another. It
can however be reused in subsequent interactions with the same
can however be reused in subsequent interactions with the same
de Jong [Page 5]
Internet-Draft remotestorage December 2012
client, as long as that client is still trusted. Example:
client, as long as that client is still trusted. Example:
* 'ofb24f1ac3973e70j6vts19qr9v2eei'
* 'ofb24f1ac3973e70j6vts19qr9v2eei'
* <storage_api>, always 'draft-dejong-remotestorage-00' for this
* <storage_api>, always 'draft-dejong-remotestorage-01' for this
version of the specification.
version of the specification.
The client can make its requests using https with CORS and bearer
The client can make its requests using https with CORS and bearer
tokens, to the URL that is the concatenation of <storage_root> with
tokens, to the URL that is the concatenation of <storage_root> with
'/' plus one or more <folder> '/' strings indicating a path in the
'/' plus one or more <folder> '/' strings indicating a path in the
folder tree, followed by zero or one <document> strings, indicating
folder tree, followed by zero or one <document> strings, indicating
a document. For example, if <storage_root> is
a document. For example, if <storage_root> is
"https://storage.example.com/bob", then to retrieve the folder
"https://storage.example.com/bob", then to retrieve the folder
contents of the /public/documents/ folder, or to retrieve a
contents of the /public/documents/ folder, or to retrieve a
'draft.txt' document from that folder, the client would make
'draft.txt' document from that folder, the client would make
requests to, respectively:
requests to, respectively:
* https://storage.example.com/bob/public/documents/
* https://storage.example.com/bob/public/documents/
* https://storage.example.com/bob/public/documents/draft.txt
* https://storage.example.com/bob/public/documents/draft.txt
9. Bearer tokens and access control
9. Bearer tokens and access control
A bearer token represents one or more access scopes. These access
A bearer token represents one or more access scopes. These access
scopes are represented as strings of the form <module> <level>,
scopes are represented as strings of the form <module> <level>,
where the <module> string SHOULD be lower-case alphanumerical, other
where the <module> string SHOULD be lower-case alphanumerical, other
than the reserved word 'public', and <level> can be ':r' or ':rw'.
than the reserved word 'public', and <level> can be ':r' or ':rw'.
The access the bearer token gives is the sum of its access scopes,
The access the bearer token gives is the sum of its access scopes,
with each access scope representing the following permissions:
with each access scope representing the following permissions:
'root:rw') any request,
'root:rw') any request,
'root:r') any GET request,
'root:r') any GET request,
de Jong [Page 6]
Internet-Draft remoteStorage June 2013
<module> ':rw') any requests to paths that start with
<module> ':rw') any requests to paths that start with
'/' <module> '/' or '/public/' <module> '/',
'/' <module> '/' or '/public/' <module> '/',
<module> ':r') any GET requests to paths that start with
<module> ':r') any GET requests to paths that start with
'/' <module> '/' or '/public/' <module> '/',
'/' <module> '/' or '/public/' <module> '/',
As a special exceptions, GET requests to a document (but not a
As a special exceptions, GET requests to a document (but not a
folder) whose path starts with '/public/' are always allowed. They,
folder) whose path starts with '/public/' are always allowed. They,
as well as OPTIONS requests, can be made without a bearer token. All
as well as OPTIONS requests, can be made without a bearer token. All
other requests should present a bearer token with sufficient access
other requests should present a bearer token with sufficient access
scope, using a header of the following form:
scope, using a header of the following form:
Authorization: Bearer <access_token>
Authorization: Bearer <access_token>
10. Application-first bearer token issuance
10. Application-first bearer token issuance
To make a remotestorage server available as 'the remotestorage of
To make a remoteStorage server available as 'the remoteStorage of
<user> at <host>', exactly one link of the following format SHOULD
<user> at <host>', exactly one link of the following format SHOULD
be added to the webfinger record [WEBFINGER] of <user> at <host>:
be added to the webfinger record [WEBFINGER] of <user> at <host>:
de Jong [Page 6]
Internet-Draft remotestorage December 2012
{
{
href: <storage_root>,
href: <storage_root>,
rel: "remotestorage",
rel: "remotestorage",
type: <storage_api>,
type: <storage_api>,
properties: {
properties: {
'auth-method': "http://tools.ietf.org/html/rfc6749#section-4.2",
"http://tools.ietf.org/html/rfc6749#section-4.2": <auth-dialog>
'auth-endpoint': <auth_endpoint>
}
}
}
}
Here <storage_root> and <storage_api> are as per "Session
Here <storage_root> and <storage_api> are as per "Session
description" above, and <auth_endpoint> SHOULD be a URL where an
description" above, and <auth-dialog> SHOULD be a URL where an
OAuth2 implicit-grant flow dialog [OAUTH] is be presented, so the
OAuth2 implicit-grant flow dialog [OAUTH] is be presented, so the
user can supply her credentials (how, is out of scope), and allow or
user can supply her credentials (how, is out of scope), and allow or
reject a request by the connecting application to obtain a bearer
reject a request by the connecting application to obtain a bearer
token for a certain list of access scopes.
token for a certain list of access scopes.
The server SHOULD NOT expire bearer tokens unless they are revoked,
The server SHOULD NOT expire bearer tokens unless they are revoked,
and MAY require the user to register applications as OAuth clients
and MAY require the user to register applications as OAuth clients
before first use; if no client registration is required, then the
before first use; if no client registration is required, then the
server MAY ignore the client_id parameter in favour of relying on
server MAY ignore the client_id parameter in favour of relying on
the redirect_uri parameter for client identification.
the redirect_uri parameter for client identification.
11. Storage-first bearer token issuance
11. Storage-first bearer token issuance
The provider MAY also present a dashboard to the user, where she
The provider MAY also present a dashboard to the user, where she
de Jong [Page 7]
Internet-Draft remoteStorage June 2013
has some way to add open web app manifests [MANIFEST]. Adding a
has some way to add open web app manifests [MANIFEST]. Adding a
manifest to the dashboard is considered equivalent to clicking
manifest to the dashboard is considered equivalent to clicking
'accept' in the dialog of the application-first flow. Removing one
'accept' in the dialog of the application-first flow. Removing one
is considered equivalent to revoking its access token.
is considered equivalent to revoking its access token.
As an equivalent to OAuth's 'scope' parameter, a 'remotestorage'
As an equivalent to OAuth's 'scope' parameter, a 'remotestorage'
field SHOULD be present in the root of such an application manifest
field SHOULD be present in the root of such an application manifest
document, as a JSON array of strings, each string being one access
document, as a JSON array of strings, each string being one access
scope of the form <module> <level>.
scope of the form <module> <level>.
When the user gestures she wants to use a certain application whose
When the user gestures she wants to use a certain application whose
manifest is present on the dashboard, the dashboard SHOULD redirect
manifest is present on the dashboard, the dashboard SHOULD redirect
to the application or open it in a new window. To mimic coming back
to the application or open it in a new window. To mimic coming back
from the OAuth dialog, it MAY add 'access_token' and 'scope'
from the OAuth dialog, it MAY add 'access_token' and 'scope'
parameters to the URL fragment.
parameters to the URL fragment.
Regardless of whether 'access_token' and 'scope' are specified, it
Regardless of whether 'access_token' and 'scope' are specified, it
SHOULD add a 'remotestorage' parameter to the URL fragment, with a
SHOULD add a 'remotestorage' parameter to the URL fragment, with a
value of the form <user> '@' <host>. When the application detects
value of the form <user> '@' <host>. When the application detects
this parameter, it SHOULD resolve the webfinger record for <user> at
this parameter, it SHOULD resolve the webfinger record for <user> at
<host> and extract the <storage_root> and <storage_api> information.
<host> and extract the <storage_root> and <storage_api> information.
If no access_token was given, then the application SHOULD also
If no access_token was given, then the application SHOULD also
extract the <auth_endpoint> information from webfinger, and continue
extract the <auth_endpoint> information from webfinger, and continue
de Jong [Page 7]
Internet-Draft remotestorage December 2012
as per application-first bearer token issuance.
as per application-first bearer token issuance.
Note that whereas a remotestorage server SHOULD offer support of the
Note that whereas a remoteStorage server SHOULD offer support of the
application-first flow with webfinger and OAuth, it MAY choose not
application-first flow with webfinger and OAuth, it MAY choose not
to support the storage-first flow, provided that users will easily
to support the storage-first flow, provided that users will easily
remember their <user> '@' <host> webfinger address at that provider.
remember their <user> '@' <host> webfinger address at that provider.
Applications SHOULD, however, support both flows, which means
Applications SHOULD, however, support both flows, which means
checking the URL for a 'remotestorage' parameter, but giving the
checking the URL for a 'remoteStorage' parameter, but giving the
user a way to specify her webfinger address if there is none.
user a way to specify her webfinger address if there is none.
If a server provides an application manifest dashboard, then it
If a server provides an application manifest dashboard, then it
SHOULD merge the list of applications there with the list of
SHOULD merge the list of applications there with the list of
issued access tokens as specified by OAuth into one list. Also,
issued access tokens as specified by OAuth into one list. Also,
the interface for revoking an access token as specified by OAuth
the interface for revoking an access token as specified by OAuth
SHOULD coincide with removing an application from the dashboard.
SHOULD coincide with removing an application from the dashboard.
12. Security Considerations
12. Security Considerations
To prevent man-in-the-middle attacks, the use of https instead of
To prevent man-in-the-middle attacks, the use of https instead of
http is important for both the interface itself and all end-points
http is important for both the interface itself and all end-points
involved in webfinger, OAuth, and (if present) the storage-first
involved in webfinger, OAuth, and (if present) the storage-first
application launch dashboard.
application launch dashboard.
de Jong [Page 8]
Internet-Draft remoteStorage June 2013
A malicious party could link to an application, but specifying a
A malicious party could link to an application, but specifying a
remotestorage user address that it controls, thus tricking the user
remoteStorage user address that it controls, thus tricking the user
into using a trusted application to send sensitive data to the wrong
into using a trusted application to send sensitive data to the wrong
remotestorage server. To mitigate this, applications SHOULD clearly
remoteStorage server. To mitigate this, applications SHOULD clearly
display to which remotestorage server they are sending the user's
display to which remoteStorage server they are sending the user's
data.
data.
Applications could request scopes that the user did not intend to
Applications could request scopes that the user did not intend to
give access to. The user SHOULD always be prompted to carefully
give access to. The user SHOULD always be prompted to carefully
review which scopes an application is requesting.
review which scopes an application is requesting.
An application may upload malicious html pages and then trick the
An application may upload malicious html pages and then trick the
user into visiting them, or upload malicious client-side scripts,
user into visiting them, or upload malicious client-side scripts,
that take advantage of being hosted on the user's domain name. The
that take advantage of being hosted on the user's domain name. The
origin on which the remotestorage server has its interface SHOULD
origin on which the remoteStorage server has its interface SHOULD
therefore NOT be used for anything else, and the user SHOULD be
therefore NOT be used for anything else, and the user SHOULD be
warned not to visit any web pages on that origin. In particular, the
warned not to visit any web pages on that origin. In particular, the
OAuth dialog and launch dashboard or token revokation interface
OAuth dialog and launch dashboard or token revokation interface
SHOULD be on a different origin than the remotestorage interface.
SHOULD be on a different origin than the remoteStorage interface.
Where the use of bearer tokens is impractical, a user may choose to
Where the use of bearer tokens is impractical, a user may choose to
store documents on hard-to-guess URLs whose path after
store documents on hard-to-guess URLs whose path after
<storage_root> starts with '/public/', while sharing this URL only
<storage_root> starts with '/public/', while sharing this URL only
with the intended audience. That way, only parties who know the
with the intended audience. That way, only parties who know the
document's hard-to-guess URL, can access it. The server SHOULD
document's hard-to-guess URL, can access it. The server SHOULD
therefore make an effort to detect and stop brute-force attacks that
therefore make an effort to detect and stop brute-force attacks that
attempt to guess the location of such documents.
attempt to guess the location of such documents.
de Jong [Page 8]
Internet-Draft remotestorage December 2012
The server SHOULD also detect and stop denial-of-service attacks
The server SHOULD also detect and stop denial-of-service attacks
that aim to overwhelm its interface with too much traffic.
that aim to overwhelm its interface with too much traffic.
13. IANA Considerations
13. IANA Considerations
This document registers the 'remotestorage' link relation.
This document registers the 'remotestorage' link relation.
14. Acknowledgements
14. Acknowledgements
The authors would like to thank everybody who contributed to the
The authors would like to thank everybody who contributed to the
development of this protocol, including Kenny Bentley, Javier Diaz,
development of this protocol, including Kenny Bentley, Javier Diaz,
Daniel Groeber, Bjarni Runar, Jan Wildeboer, Charles Schultz, Peter
Daniel Groeber, Bjarni Runar, Jan Wildeboer, Charles Schultz, Peter
Svensson, Valer Mischenko, Michiel Leenaars, Jan-Christoph
Svensson, Valer Mischenko, Michiel Leenaars, Jan-Christoph
Borchardt, Garret Alfert, Sebastian Kippe, Max Wiehle, Melvin
Borchardt, Garret Alfert, Sebastian Kippe, Max Wiehle, Melvin
Carvalho, Martin Stadler, Geoffroy Couprie, Niklas Cathor, Marco
Carvalho, Martin Stadler, Geoffroy Couprie, Niklas Cathor, Marco
Stahl, James Coglan, Ken Eucker, Daniel Brolund, elf Pavlik, Nick
Stahl, James Coglan, Ken Eucker, Daniel Brolund, elf Pavlik, Nick
Jennings, and Markus Sabadello, among many others.
Jennings, Markus Sabadello, and Steven te Brinke, among many others.
de Jong [Page 9]
Internet-Draft remoteStorage June 2013
15. References
15. References
15.1. Normative References
15.1. Normative References
[WORDS]
[WORDS]
Bradner, S., "Key words for use in RFCs to Indicate Requirement
Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
Levels", BCP 14, RFC 2119, March 1997.
[IRI]
[IRI]
Duerst, M., "Internationalized Resource Identifiers (IRIs)",
Duerst, M., "Internationalized Resource Identifiers (IRIs)",
RFC 3987, January 2005.
RFC 3987, January 2005.
[WEBFINGER]
[WEBFINGER]
Jones, Paul E., Salguerio, Gonzalo, and Smarr, Joseph,
Jones, Paul E., Salguerio, Gonzalo, and Smarr, Joseph,
"WebFinger", draft-ietf-appsawg-webfinger-07, Work in Progress
"WebFinger", draft-ietf-appsawg-webfinger-13, Work in Progress
[OAUTH]
[OAUTH]
"Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth
"Section 4.2: Implicit Grant", in: Hardt, D. (ed), "The OAuth
2.0 Authorization Framework", RFC6749, October 2012.
2.0 Authorization Framework", RFC6749, October 2012.
15.2. Informative References
15.2. Informative References
[HTTPS]
[HTTPS]
Rescorla, E., "HTTP Over TLS", RFC2818, May 2000.
Rescorla, E., "HTTP Over TLS", RFC2818, May 2000.
[HTTP]
Fielding et al., "Hypertext Transfer Protocol -- HTTP/1.1",
RFC2616, June 1999.
[CORS]
[CORS]
van Kesteren, Anne (ed), "Cross-Origin Resource Sharing -- W3C
van Kesteren, Anne (ed), "Cross-Origin Resource Sharing -- W3C
Working Draft 3 April 2012",
Working Draft 3 April 2012",
http://www.w3.org/TR/2012/WD-cors-20120403/CORS, April 2012.
http://www.w3.org/TR/2012/WD-cors-20120403/CORS, April 2012.
[MANIFEST]
[MANIFEST]
Mozilla Developer Network (ed), "App manifest -- Revision
Mozilla Developer Network (ed), "App manifest -- Revision
330541", https://developer.mozilla.org/en-
US/docs/Apps/Manifest$revision/330541, November 2012.
de Jong [Page 9]
de Jong [Page 9]
Internet-Draft remotestorage December 2012
Internet-Draft remoteStorage June 2013
330541", https://developer.mozilla.org/en-
US/docs/Apps/Manifest$revision/330541, November 2012.
16. Authors' addresses
16. Authors' addresses
Michiel B. de Jong
Michiel B. de Jong
(independent)
(independent)
Email: michiel@michielbdejong.com
Email: michiel@michielbdejong.com
F. Kooman
F. Kooman
SURFnet bv
SURFnet bv
Postbus 19035
Postbus 19035
3501 DA Utrecht
3501 DA Utrecht
The Netherlands
The Netherlands
Email: Francois.Kooman@surfnet.nl
Email: Francois.Kooman@surfnet.nl
de Jong [Page 10]
de Jong [Page 10]