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

Caps Disco #136

Merged
merged 5 commits into from
Nov 14, 2024
Merged

Caps Disco #136

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5ba5b42
caps-disco rebased on develop
michielbdejong Oct 17, 2024
0c0f836
Invitation->Invite, clarify the version string refers to this spec ve…
michielbdejong Oct 24, 2024
eeda4ec
update list of 4 capabilities as per https://github.com/cs3org/OCM-AP…
michielbdejong Oct 24, 2024
a46af6f
revert text about versioning, document invites capability
michielbdejong Nov 7, 2024
79dfdbe
Update spec.yaml accordingly
michielbdejong Nov 14, 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
29 changes: 19 additions & 10 deletions IETF-RFC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,10 +234,10 @@ Step 7: The JSON response body is the data that was discovered.
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. MUST start with `"1."` and clients MUST ignore the rest of the string.
Copy link
Member

Choose a reason for hiding this comment

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

As already commented, I'd not enforce any value, in particular the MUST start with 1. - we will have 2.0 :)

Maybe just It is provided for information purposes only: clients SHOULD NOT infer capabilities based on its value, or (better) say that when discussing capabilities.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

My idea was that servers can announce which version of the spec they support. So if they support the version that says "announce me as 1.*", then that is what they should announce.

We could keep it as "anything goes" but we don't want a 1.* server to announce a 2.* API version, right?

we will have 2.0 :)

Exactly, and then we'll change the "MUST start with 1." to "MUST start with 2.", that's how we link the api version to the spec text. We can discuss it in today's meeting!

Copy link
Member

Choose a reason for hiding this comment

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

(I'll miss today's meeting)
Hmm I'm not sure - IMHO the spec's version is an attribute, a "payload", not an inherent feature ("MUST start with...").

And whether a server announces version A.B but actually implements C.D, this is more a matter of compliance that can (and should) be independently tested, e.g. by (y)our test suite, not of "adhering to a standard" I think.

* 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 supported resource types with their access protocols. Each item in this list should
* 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
itself be an object containing the following fields:
* name (string) - A supported resource type (file, folder, calendar, contact, ...).
Implementations MUST support `file` at a minimum. Each resource type is identified by its `name`: the list MUST NOT
Expand All @@ -246,7 +246,7 @@ itself be an object containing the following fields:
The supported recipient share types.
MUST contain `"user"` at a minimum, plus optionally `"group"` and `"federation"`.
Example: `["user"]`
* protocols (object) - The supported protocols for accessing shared resources.
* protocols (object) - The supported protocols for accessing shared resources of this type.
Implementations MUST support at least `webdav` for `file` resources,
any other combination of resources and protocols is optional. Example:
```json
Expand Down Expand Up @@ -275,11 +275,20 @@ itself be an object containing the following fields:
* OPTIONAL: capabilities (array of string) - The optional capabilities supported by this OCM Server.
As implementations MUST accept Share Creation Notifications to be compliant,
it is not necessary to expose that as a capability.
Example: `["/notifications"]`. The array MAY include for instance:
* `"/notifications"` - to indicate this OCM server is capable of processing OCM Notifications
* `"/invite-accepted"` - to indicate that this OCM server is capable of processing Invite Acceptance Requests.
* `"/mfa-capable"` - to indicate that this OCM server can apply a Sending Server's MFA requirements for a Share on their behalf.

Example: `["receive-code", "webdav-uri"]`. The array MAY include for instance:
* `"enforce-mfa"` - to indicate that this OCM server can apply a Sending Server's MFA requirements for a Share on their behalf.
* `"webdav-uri"` - to indicate that this OCM server can append a relative URI to the path listed for WebDAV in the appropriate `resourceTypes` entry
* `"receive-code"` - to indicate that this OCM server can receive a `code` as part of a Share Creation Notification, and exchange it for a bearer token at the Sending Server's `/token` API endpoint.
* OPTIONAL: criteria (array of string) - The criteria for accepting a Share Creation Notification.
glpatcern marked this conversation as resolved.
Show resolved Hide resolved
As all Receiving Servers should require the use of TLS in API calls,
it is not necessary to expose that as a criterium.
Example: `["http-request-signatures", "code"]`. The array MAY include for instance:
* `"http-request-signatures"` - to indicate that API requests without http signatures will be rejected.
* `"code"` - to indicate that API requests without code will be rejected (i.e. the `sharedSecret` in the protocol details will be ignored).
* `"denylist"` - some servers may be blocked based on their IP address
* `"allowlist"` - unknown servers may be blocked based on their IP address
* `"invite"` - an invite must have been exchanged between the sender and the receiver before a Share Creation Notification can be sent

* OPTIONAL: publicKey (object) - The signatory used to sign outgoing request to confirm its origin. The
signatory is optional, but if present, it MUST contain two string fields, `id` and `publicKeyPem`.
properties:
Expand Down Expand Up @@ -489,7 +498,7 @@ Otherwise, if `protocol.webdav.sharedSecret` is not empty, the receiver MUST pas

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.

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

# Share Deletion
A `"SHARE_ACCEPTED"` notification followed by a `"SHARE_UNSHARED"` notification is
Expand All @@ -506,7 +515,7 @@ Receiving Server to persuade the Sending Server to share the same Resource with
TODO: document how the Receiving Party can know if the Sending Party understood and processed the
reshare request.

## Appendix A: Multi Factor Authentication
# Appendix A: Multi Factor Authentication
If a Receiving Server exposes the capability `/mfa-capable`, it indicates that it will try and comply with a MFA requirement set on a Share. If the Sending Server trusts the Receiving Server, the Sending Server MAY set the requirement `mfa-enforced` on a Share, which the Receiving Server MUST honor. A compliant Receiving Server that signals that it is MFA-capable MUST not allow access to a resource protected with the `mfa-enforced` requirement, if the Receiving Party has not provided a second factor to establish their identity with greater confidence.

Since there is no way to guarantee that the Receiving Server will actually enforce the MFA requirement, it is up to the Sending Server to establish a trust with the Receiving Server such that it is reasonable to assume that the Receiving Server will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted Receiving Servers. The procedure of establishing trust is out of scope for this specification: a mechanism similar to the [ScienceMesh](https://sciencemesh.io) integration for the [Invite](#invite-flow) capability may be envisaged.
Expand Down