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 1 commit
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
37 changes: 19 additions & 18 deletions IETF-RFC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
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,12 @@ 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 MAY be relative,
in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
be used, or it MAY be absolute. The latter is recommended in case the
receiver cannot unambiguously identify the sending server's endpoint (e.g.
because of reverse proxies).
* 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 +416,13 @@ 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 MAY
be relative, in which case the prefix exposed by the `/.well-known/ocm`
endpoint MUST be used, or it MAY be absolute. Similar considerations
as for the `webdav.uri` field apply.
* 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 +432,17 @@ 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 MAY be relative,
in which case the prefix exposed by the `/.well-known/ocm` endpoint MUST
be used, or it MAY be absolute. Similar considerations as for the
`webdav.uri` field apply.
* 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
36 changes: 15 additions & 21 deletions spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -606,21 +606,20 @@ 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 MAY 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.
or it MAY be absolute, including a hostname. The latter is
recommended in case the receiver cannot unambiguously identify
the sending server's endpoint (e.g. because of reverse proxies).
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 +664,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 URI MAY 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 +687,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 +701,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
SHOULD be relative, such as a key or a UUID, in which case the
An URI to access the resource at the sending server. The URI
MAY 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