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

Clarify how access happens for shares without absolute URIs #165

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

Clarify how access happens for shares without absolute URIs #165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0490247
Un-deprecate full URIs in share payloads
glpatcern Feb 25, 2025
abcd8a4
Fixed typo
glpatcern Mar 5, 2025
439aa3a
Clarified that discovery happens on the owner's OCM address
glpatcern Mar 5, 2025
d4e7093
Advertise latest version
glpatcern Mar 13, 2025
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
43 changes: 20 additions & 23 deletions IETF-RFC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ We define the following concepts (with some non-normative references to related
* __Discovering Server__ - a server that tries to obtain information in OCM API discovery
* __Discoverable Server__ - a server that tries to supply information in OCM API discovery
* __OCM Address__ - a string of the form `<Receiving Party's identifier>@<fqdn>` which can be used to uniquely identify a user or group "at" an OCM Server. `<Receiving Party's identifier>` is an opaque string,
unique at the server. `<fqdn>` is the Fully Qualified Domain Name by which the server is identified. This can, but doesn't need to be, the domain at which the OCM API of that server is hosted.
unique at the server. `<fqdn>` is the Fully Qualified Domain Name by which the server is identified. This MUST be the domain at which the OCM API of that server is hosted.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewing myself, I believe this is the only significant change, all the rest being a matter of better phrasing and realigning of the IETF text to the spec.

I believe we have to force a MUST here, otherwise my argument of un-deprecating full URIs in share payloads remains valid. Otherwise, if a share payload does not contain a usable owner, and the URI is relative, how can a receiver contact the sender, assuming that its remote address may not be valid?

Copy link
Contributor

@michielbdejong michielbdejong Mar 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this "doesn't have to be" phrase refers to the fact we are allowing the OCM API (i.e. where POST ./shares and other endpoints live) as advertised in /.well-known/ocm to be on a different server than /.well-known/ocm itself, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, my interpretation was that the /.well-known/ocm must be on the same server as the owner's (or recipient's) OCM address that is sent by a POST ./shares

* __OCM Notification__ - a message from the Receiving Server to the Sending Server or vice versa, using the OCM Notifications endpoint.
* __Invite Message__ - out-of-band message used to establish contact between parties and servers in the Invite Flow, containing an Invite Token (see below) and the Invite Sender's OCM Address
* __Invite Sender__ - the party sending an Invite
Expand Down Expand Up @@ -224,17 +224,17 @@ At the start of the process, the Discovering Server has either an OCM Address, o

Step 1: In case it has an OCM Address, it should first extract `<fqdn>` from it (the part after the `@` sign).
Step 2: The Discovering Server SHOULD attempt OCM API discovery a HTTP GET request to `https://<fqdn>/.well-known/ocm`.
Step 3: If that results in a valid HTTP response with a valid JSON response body within reasonable time, go to step 8.
Step 3: If that results in a valid HTTP response with a valid JSON response body within reasonable time, go to step 7.
Step 4: If not, try a HTTP GET with `https://<fqdn>/ocm-provider` as the URL instead.
Step 5: If that results in a valid HTTP response with a valid JSON response body within reasonable time, go to step 8.
Step 5: If that results in a valid HTTP response with a valid JSON response body within reasonable time, go to step 7.
Step 6: If not, fail.
Step 7: The JSON response body is the data that was discovered.

## Fields
The JSON response body offered by the Discoverable Server SHOULD contain the following information about its OCM API:

* REQUIRED: enabled (boolean) - Whether the OCM service is enabled at this endpoint
* REQUIRED: apiVersion (string) - The OCM API version this endpoint supports. Example: `"1.1.0"`
* REQUIRED: apiVersion (string) - The OCM API version this endpoint supports. Example: `"1.2.0"`
* REQUIRED: endPoint (string) - The URI of the OCM API available at this endpoint. Example: `"https://my-cloud-storage.org/ocm"`
* OPTIONAL: provider (string) - A friendly branding name of this endpoint. Example: `"MyCloudStorage"`
* REQUIRED: resourceTypes (array) - A list of all resource types this server supports in both the Sending Server role and the Receiving Server role, with their access protocols. Each item in this list should
Expand Down Expand Up @@ -375,7 +375,7 @@ To create a share, the sending server SHOULD make a HTTP POST request
Option 3: Set the `name` field to `multi`, and put the protocol
details in a field carrying the name of the protocol.

Option 1 using the `options` field now deprecated. Implementations are encouraged to
Option 1 using the `options` field is now deprecated. Implementations are encouraged to
transition to the new optional properties defined below, such that
this field may be removed in a future major version of the spec.

Expand All @@ -394,6 +394,10 @@ If `multi` is given, one or more protocol
only support `webdav`.

* Protocol details for `webdav` MAY contain:
* REQUIRED uri (string)
An URI to access the remote resource. The URI SHOULD be relative,
in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
be used. Absolute URIs are deprecated.
* OPTIONAL sharedSecret (string) - required if no `code` field is given for the Share as a whole (see above).
An optional secret to be used to access the resource,
such as a bearer token.
Expand All @@ -410,19 +414,12 @@ If `multi` is given, one or more protocol
- `use-code` requires the consumer to exchange the given `code` via a
signed HTTPS request. This MAY be used if the recipient provider exposes
the `receive-code` capability.
* OPTIONAL uri (string)
An URI to access the remote resource. The URI MAY be relative,
in which case the prefix exposed by the `/ocm-provider` endpoint MUST
be used, or it may be absolute (recommended). Additionally, the URI
MAY include a secret hash in the path, in which case there MAY be
no associated `sharedSecret`.
* Protocol details for `webapp` MAY contain:
* REQUIRED uriTemplate (string)
A templated URI to a client-browsable view of the shared resource,
such that users may use the web applications available at the site.
The URI MAY include a secret hash in the path. If the path includes
a `{relative-path-to-shared-resource}` placeholder, implementations
MAY replace it with the actual path to ease user interaction.
* REQUIRED uri (string)
An URI to a client-browsable view of the shared resource, such that
users may use the web applications available at the site. The URI SHOULD
be relative, in which case the prefix exposed by the `/.well-known/ocm`
endpoint MUST be used. Absolute URIs are deprecated.
* REQUIRED viewMode (string)
The permissions granted to the sharee. A subset of:
- `view` allows access to the web app in view-only mode.
Expand All @@ -432,16 +429,16 @@ If `multi` is given, one or more protocol
An optional secret to be used to access the remote web app,
for example in the form of a bearer token.
* Protocol details for `datatx` MAY contain:
* REQUIRED srcUri (string)
An URI to access the remote resource. The URI SHOULD be relative,
in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
be used. Absolute URIs are deprecated.
* OPTIONAL sharedSecret (string)
An optional secret to be used to access the resource,
for example in the form of a bearer token.
To prevent leaking it in logs it MUST NOT appear in any URI.
* REQUIRED srcUri (string)
An URI to access the remote resource. The URI MAY be relative,
in which case the prefix exposed by the `/ocm-provider` endpoint MUST
be used, or it may be absolute (recommended). Additionally, the
URI MAY include a secret hash in the path.
* OPTIONAL size (integer)
The size of the file to be transferred from the sending server.

## Decision to Discard
The Receiving Server MAY discard the notification if any of the following hold true:
Expand Down Expand Up @@ -492,7 +489,7 @@ They could give the Receiving Party the option to accept or reject the Share, or

# Resource Access
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`.
1. The receiver MUST extract the OCM Server FQDN from the `owner` field of the received share, and MUST query the [Discovery](#ocm-api-discovery) endpoint at that address: the `resourceTypes[0].protocols.webdav` value is the `<sender-ocm-path>` to be used in step 3.
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.
Expand Down
32 changes: 12 additions & 20 deletions spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -606,21 +606,18 @@ components:
uri:
type: string
description: >
An URI to access the remote resource. The URI SHOULD be
relative,
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.
`/.well-known/ocm` endpoint MUST be used to access the resource, or
it MAY be absolute, including a hostname. The latter is deprecated.
In all cases, for a `folder` resource, the composed URI acts
as the root path, such that other files located within SHOULD
as the root path, such that other files located within it SHOULD
be accessible by appending their relative path to that URI.
sharedSecret:
type: string
description: >
An optional secret to be used to access the resource, such
as
a bearer token. If a `code` is provided, it SHOULD be used
as a bearer token. If a `code` is provided, it SHOULD be used
instead via the code flow interaction, and the `sharedSecret`
SHOULD be omitted. To prevent leaking it in logs it MUST NOT
appear in any URI.
Expand Down Expand Up @@ -665,13 +662,12 @@ components:
uri:
type: string
description: >
An URI to a client-browsable view of the remote resource,
such that
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.
Similar considerations as for the `webdav` case apply here.
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.
Expand All @@ -689,8 +685,7 @@ components:
sharedSecret:
type: string
description: >
An optional secret to be used to access the remote web
app, such as
An optional secret to be used to access the remote web app, such as
a bearer token. To prevent leaking it in logs it MUST NOT appear
in any URI. If a `code` is provided, then the sending host MUST
accept the short-lived bearer token when serving the web app,
Expand All @@ -704,22 +699,19 @@ components:
sharedSecret:
type: string
description: >
An optional secret to be used to access the resource, such
as
An optional secret to be used to access the resource, such as
a bearer token. If a `code` is provided, it SHOULD be used
instead via the code flow interaction, and the `sharedSecret`
SHOULD be omitted. To prevent leaking it in logs it MUST NOT
appear in any URI.
srcUri:
type: string
description: >
An URI to access the resource at the sending server. The
URI
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.
to access the resource, or it MAY be absolute, including a
hostname. Similar considerations as for the `webdav` case apply.
size:
type: integer
description: >
Expand Down