Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve share access process and share examples #158

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

Improve share access process and share examples #158

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
04c01f3
Reworked share examples
glpatcern Oct 21, 2024
6f223b9
Minor fix for consistency with access process
glpatcern Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 7 additions & 11 deletions IETF-RFC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ Second, when the Receiving Party accepts the Invite, the Receiving Server knows

Third, equivalently, the Sending Server knows it is essentially registering the Receiving Server as an API client at the request of the Receiving Party, to whom the right to request this has been traceably delegated by the Sending Party, which is one of its registered users.

Fourth, related to the second one, it removes the partial 'open relay' problem that exists when the Sending Server is allowed to include any Receiving Server FQDN in the Sending Gesture. Without the use of Invites, a Distributed Denial of Service attack could be organised if many internet users collude to flood a given OCM Server with Share Creation Notifications which will be hard to distinguish from legitimate requests without human interaction. An unsolicited (invalid) Invite Acceptance Request is much easier to filter out than an unsolicited (possibly valid, possibly invalid) OCM request, since the Invite Acceptance Request needs to contain an Invite Token that was previously uniquely generated at the Invite Sender OCM server.
Fourth, related to the second one, it removes the partial 'open relay' problem that exists when the Sending Server is allowed to include any Receiving Server FQDN in the Sending Gesture. Without the use of Invites, a Distributed Denial of Service attack could be organised if many internet users collude to flood a given OCM Server with Share Creation Notifications which will be hard to distinguish from legitimate requests without human interaction. An unsolicited (invalid) Invite Acceptance Request is much easier to filter out than an unsolicited (possibly valid, possibly invalid) Share Creation Notification Request, since the Invite Acceptance Request needs to contain an Invite Token that was previously uniquely generated at the Invite Sender OCM server.

# OCM API Discovery
## Introduction
Expand Down Expand Up @@ -477,17 +477,13 @@ If the Share Creation Notification is not discarded by the Receiving Server, the
They could give the Receiving Party the option to accept or reject the Share, or add the Share automatically and only send an informational notification that this happened.

# Resource Access
To access the Resource, the Receiving Server MAY use multiple ways, depending on the body of the Share Creation Notification and on the `protocol.name` property in there:
To access the Resource, the Receiving Server MAY use multiple ways, depending on the body of the Share Creation Notification. The procedure is as follows:
1. A root path `<sender-ocm-path>` MUST be obtained by querying the [Discovery](#ocm-api-discovery) endpoint at the Sending Server and getting `resourceTypes[0].protocols.webdav`.
2. If `code` is not empty, the receiver SHOULD make a signed POST request to the `/token` path inside the Sending Server's OCM API, to exchange the code for a short-lived bearer token, and then use that bearer token to access the Resource.
3. If `protocol.name` = `webdav`, the receiver SHOULD inspect the `protocol.options` property. If it contains a `sharedSecret`, as in the [legacy example](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post), then the receiver SHOULD make a HTTP PROPFIND request to `https://<sharedSecret>:@<sender-host><sender-ocm-path>`. Note that this access method, based on Basic Auth, is _deprecated_ and may be removed in a future release of the Protocol.
4. Otherwise, if `protocol.name` = `multi`, the receiver MUST inspect the `protocol.webdav.uri` property: if it's a complete URI, the receiver MUST make a HTTP PROPFIND request against it to access the remote resource. If it only contains an identifier `<key>`, the receiver MUST make a HTTP PROPFIND request to `https://<sender-host><sender-ocm-path>/<key>` in order to access the remote resource. Additionally, the receiver MUST pass an `Authorization: bearer` header with either the short-lived bearer token obtained in step 2, if applicable, or the `protocol.webdav.sharedSecret` value.

* If `protocol.name` = `multi`, the receiver MUST make a HTTP PROPFIND request to `protocol.webdav.uri` to access the remote share.
If `code` is not empty, the receiver SHOULD discover the sender's OCM endpoint and make a signed POST request to the `/token` path inside the Sending Server's OCM API, to exchange
the code for a short-lived bearer token,
and then use that bearer token to access the Resource.
Otherwise, if `protocol.webdav.sharedSecret` is not empty, the receiver MUST pass it as a `Authorization: bearer` header.

* If `protocol.name` = `webdav`, the receiver SHOULD inspect the `protocol.options` property. If it contains a `sharedSecret`, as in the [legacy example](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post), then the receiver SHOULD make a HTTP PROPFIND request to `https://<sharedSecret>:@<host><path>`, where `<host>` is the remote server, and `<path>` is obtained by querying the [Discovery](#ocm-api-discovery) endpoint at the Sending Server and getting `resourceTypes[0].protocols.webdav`. Note that this access method is _deprecated_ and may be removed in a future release of the Protocol.

In both cases, when the Resource is a folder and the Receiving Server accesses a resource within that shared folder, it SHOULD append its relative path to that URL.
In all cases, in case the Shared Resource is a folder and the Receiving Server accesses a resource within that shared folder, it SHOULD append its relative path to that URL. In other words, the Sending Server SHOULD support requests to URLs such as `https://<sender-host><sender-ocm-path>/path/to/resource.txt`.

Additionally, if `protocol.<protocolname>.requirements` include `mfa-enforced`, the Receiving Server MUST ensure that the Receiving Party has been authenticated with MFA.

Expand Down
70 changes: 42 additions & 28 deletions spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,22 +343,22 @@ definitions:
type: string
description: |
The top-level WebDAV path at this endpoint. In order to access
a remote shared resource, implementations MAY use this path
as a prefix, or as the full path (see sharing examples).
a remote shared resource, implementations SHOULD use this path
as a prefix (see sharing examples).
webapp:
type: string
description: |
The top-level path for web apps at this endpoint. This value
is provided for documentation purposes, and it SHALL NOT
be intended as a prefix for share requests.
The top-level path for web apps at this endpoint. In order to
access a remote web app, implementations SHOULD use this path
as a prefix (see sharing examples).
datatx:
type: string
description: |
The top-level path to be used for data transfers. This
value is provided for documentation purposes, and it SHALL
NOT be intended as a prefix. In addition, implementations
are expected to execute the transfer using WebDAV as
the wire protocol.
The top-level path to be used for data transfers. In order to
access a remote shared resource, implementations SHOULD use
this path as a prefix (see sharing examples). In addition,
implementations are expected to execute the transfer using
WebDAV as the wire protocol.
patternProperties:
"^.*$":
type: string
Expand All @@ -368,7 +368,7 @@ definitions:
URI to be used for that protocol.
example:
webdav: "/remote/dav/ocm/"
webapp: "/app/ocm/"
webapp: "/apps/ocm/"
talk: "/apps/spreed/api/"
capabilities:
type: array
Expand Down Expand Up @@ -517,6 +517,17 @@ definitions:
webdav:
type: object
properties:
uri:
type: string
description: |
An URI to access the remote resource. The URI SHOULD be relative,
such as a key or a UUID, in which case the prefix exposed by the
`/.well-known/ocm` endpoint MUST be used to access the resource,
or it MAY be absolute, including a hostname. The latter is NOT
recommended because of security concerns.
In all cases, for a `folder` resource, the composed URI acts
as the root path, such that other files located within SHOULD
be accessible by appending their relative path to that URI.
sharedSecret:
type: string
description: |
Expand Down Expand Up @@ -549,23 +560,21 @@ definitions:
MFA-authenticated. This requirement MAY be used if the
provider exposes the `mfa-capable` capability.
enum: ["mfa-enforced"]
uri:
type: string
description: |
An URI to access the remote resource. The URI MAY be relative,
in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
be used, or it may be absolute (recommended).
webapp:
type: object
properties:
uriTemplate:
uri:
type: string
description: |
A templated URI to a client-browsable view of the shared resource,
such that users may use a web application available at the sender site.
If the path includes a `{relative-path-to-shared-resource}` placeholder,
implementations SHOULD replace it with the actual path to ease user
interaction.
An URI to a client-browsable view of the remote resource, such that
users may use a web application available at the sender site.
The URI SHOULD be relative, such as a key or a UUID, in which case
the prefix exposed by the `/.well-known/ocm` endpoint MUST be used
to access the resource, or it MAY be absolute, including a hostname.
The latter is NOT recommended because of security concerns.
In all cases, for a `folder` resource, the composed URI acts
as the root path, such that other files located within SHOULD
be accessible by appending their relative path to that URI.
viewMode:
type: string
description: |
Expand Down Expand Up @@ -602,7 +611,12 @@ definitions:
srcUri:
type: string
description: |
An absolute URI to access the resource at the sending server.
An URI to access the resource at the sending server. The URI
SHOULD be relative, such as a key or a UUID, in which case the
prefix exposed by the `/.well-known/ocm` endpoint SHOULD be used
to access the resource, or it MAY be absolute, including
a hostname. The latter is NOT recommended because of security
concerns.
size:
type: integer
description: |
Expand All @@ -624,24 +638,24 @@ definitions:
singleProtocolNew:
name: "multi"
webdav:
uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01"
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
permissions: ["read", "write"]
requirements: ["none"]
uri: "https://open-cloud-mesh.org/remote/dav/ocm/7c084226-d9a1-11e6-bf26-cec0c932ce01/path/to/resource.txt"
multipleProtocols:
name: "multi"
webdav:
uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01"
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
permissions: ["read"]
requirements: ["mfa-enforced"]
uri: "https://open-cloud-mesh.org/remote/dav/ocm/7c084226-d9a1-11e6-bf26-cec0c932ce01/path/to/resource.txt"
webapp:
uri: "7c084226-d9a1-11e6-bf26-cec0c932ce01"
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
uriTemplate: "https://open-cloud-mesh.org/app/ocm/7c084226-d9a1-11e6-bf26-cec0c932ce01/{relative-path-to-shared-resource}"
viewMode: "read"
datatx:
srcUri: "7c084226-d9a1-11e6-bf26-cec0c932ce01"
sharedSecret: "hfiuhworzwnur98d3wjiwhr"
srcUri: "https://open-cloud-mesh.org/remote/dav/ocm/7c084226-d9a1-11e6-bf26-cec0c932ce01/path/to/resource.txt"
size: 100000
NewNotification:
type: object
Expand Down