diff --git a/IETF-OCM-MLS.md b/IETF-OCM-MLS.md index ff6b4aa..80e135f 100644 --- a/IETF-OCM-MLS.md +++ b/IETF-OCM-MLS.md @@ -51,9 +51,9 @@ capabilities for resources shared with federated groups. Open Cloud Mesh [OCM] currently supports sharing resources with individual users across federated servers and with groups on a single -server. The specification also defines a `shareType` of `"federation"` -but does not further specify its semantics. This document gives -`"federation"` a concrete definition: a federated group identified by an +server. [OCM] also defines a `shareType` of `"federation"` but does +not further specify its semantics. This document gives `"federation"` +concrete semantics: a federated group identified by an OCM Address such as `research-group@receiver.example.org` whose membership spans multiple OCM servers, with group state managed through the MLS [RFC9420] epoch mechanism. @@ -641,7 +641,7 @@ takeover time T MAY be generous, for example several hours. Loose time synchronisation between servers is sufficient and is already assumed by MLS for leaf node lifetimes ([RFC9420] Section 7.2). -## MLS Notification Types +## MLS Notification Types {#mls-notification-types} All MLS group lifecycle messages are sent as OCM Notifications to `/notifications` using HTTP POST with `Content-Type: @@ -1833,6 +1833,40 @@ defined in [RFC9420] Section 17.3: - Recommended: N - Reference: This document +The following notification types are to be registered in the "OCM +Notification Types" registry defined in [OCM], within the "Open Cloud +Mesh (OCM) Parameters" group. All are group-scoped and therefore omit +the "providerId" field (see {{mls-notification-types}}): + +~~~ + +===================+=======+========+===============+ + | Notification Type | Scope | Status | Reference | + +===================+=======+========+===============+ + | MLS_WELCOME | Group | active | This document | + | MLS_PROPOSAL | Group | active | This document | + | MLS_COMMIT | Group | active | This document | + | MLS_APPLICATION | Group | active | This document | + | MLS_REJOIN | Group | active | This document | + +===================+=======+========+===============+ +~~~ + +The following entries are to be registered in the "OCM Share Payloads" +registry defined in [OCM], within the "Open Cloud Mesh (OCM) +Parameters" group. They extend the existing "webdav", "webapp", and +"ssh" protocols to the "federation" share type; the wire format of the +share payload for these combinations is completely specified by this +document together with [OCM] (see {{share-creation}}). These +registrations do not modify the protocols' own registrations: + +~~~ + +===============+============+=====================+===============+ + | Resource Type | Share Type | Protocols | Reference | + +===============+============+=====================+===============+ + | file | federation | webdav, webapp, ssh | This document | + | folder | federation | webdav, webapp, ssh | This document | + +===============+============+=====================+===============+ +~~~ + # Open Issues This section collects open design issues and shall be removed before diff --git a/IETF-OCM.md b/IETF-OCM.md index 13f1a42..2cdd055 100644 --- a/IETF-OCM.md +++ b/IETF-OCM.md @@ -834,6 +834,17 @@ If the Receiving Server does not advertise `must-exchange-token` in its `criteria`, the Sending Server MAY still include `must-exchange-token` voluntarily. +The Sending Server MUST NOT create a share for a combination of +resource type, share type, and protocol that the Receiving Server does +not advertise in its Discovery response. Specifically, for the +share's `resourceType` and `shareType`, and for each protocol offered +in the `protocol` object, the Receiving Server's `resourceTypes` array +MUST contain an entry whose `name` equals the `resourceType`, whose +`shareTypes` array contains the `shareType`, and whose `protocols` +object contains that protocol's `-receive` property. Each such +combination corresponds to an entry in the "OCM Share Payloads" +registry (see [IANA Considerations](#iana-considerations)). + When the notification includes `protocol.webapp`, the Sending Server MUST expose the `exchange-token` capability and a `tokenEndPoint`, because WebApp access requires the Receiving Server to exchange @@ -895,11 +906,15 @@ described in [OCM-IP]. Alternatively, the Receiving Server MAY hold the federated groups' metadata and act as an OCM proxy, forwarding the OCM requests to the actual members of the federation. + Registered values are listed in the "OCM Share Types" registry + (see [IANA Considerations](#iana-considerations)). * REQUIRED resourceType (string) Resource type (file, folder, calendar, contact, ...). If the Resource is a folder, implementations SHOULD advertise it as `folder` rather than `file`, in order to streamline the processing by the Receiving Server. + Registered values are listed in the "OCM Resource Types" registry + (see [IANA Considerations](#iana-considerations)). * OPTIONAL expiration (integer) The expiration time for the OCM share, in seconds of UTC time since Unix epoch. If omitted, it is assumed that the @@ -913,6 +928,10 @@ described in [OCM-IP]. - `webapp`, to access remote web applications. - `ssh`, to access the data via a public/private key pair. Other custom protocols might be added in the future. + Registered protocol values are listed in the "OCM Protocols" + registry, and the valid resource-type/share-type/protocol + combinations in the "OCM Share Payloads" registry (see + [IANA Considerations](#iana-considerations)). In case a single protocol is offered, there are three ways to specify this object: Option 1: Set the `name` field to the name of the protocol, @@ -1178,6 +1197,8 @@ Receiving Server MAY make a HTTP POST request Notification it MUST be one of: - 'SHARE_ACCEPTED' - 'SHARE_DECLINED' + Registered values are listed in the "OCM Notification Types" + registry (see [IANA Considerations](#iana-considerations)). * REQUIRED providerId (string) - copied from the Share Creation Notification for the Share this notification is about * OPTIONAL resourceType (string) - copied from the Share Creation @@ -1535,6 +1556,178 @@ Values" registry (using the template from [RFC9553]). |--------------|------------------------------------------| ~~~ +## Open Cloud Mesh Parameters Registry Group + +IANA is requested to create a new registry group titled "Open Cloud +Mesh (OCM) Parameters", containing the registries defined in the +following subsections. Unless stated otherwise, the registration +policy for each registry in this group is "Specification Required" +[RFC8126]. The Designated Expert SHOULD verify that a requested entry +is documented in a stable, publicly available specification and that it +does not duplicate an existing entry. + +## OCM Resource Types Registry + +IANA is requested to create the "OCM Resource Types" registry in the +"Open Cloud Mesh (OCM) Parameters" group. This registry records the +resource type values used both in the "resourceType" field of a +[Share Creation Notification](#share-creation-notification) and in the +"name" field of each entry in the "resourceTypes" array advertised by +the [OCM API Discovery](#ocm-api-discovery) endpoint. + + Registration Policy: Specification Required [RFC8126] + + Initial Contents: + +~~~ + +===============+=====================+===============+ + | Resource Type | Description | Reference | + +===============+=====================+===============+ + | file | A single file | This document | + | folder | A folder/collection | This document | + +===============+=====================+===============+ +~~~ + +## OCM Protocols Registry + +IANA is requested to create the "OCM Protocols" registry in the "Open +Cloud Mesh (OCM) Parameters" group. Each entry records a protocol +property name that MAY appear in the "protocols" object advertised by +the [OCM API Discovery](#ocm-api-discovery) endpoint or in the +"protocol" object of a +[Share Creation Notification](#share-creation-notification). + +A property whose "Role" is "send" (e.g. "webdav") advertises support +for the Sending Server role in Discovery and is the value used in the +share "protocol" object. Its "-receive" suffixed counterpart (e.g. +"webdav-receive"), whose "Role" is "receive", advertises support for +the Receiving Server role in Discovery. Which protocols MAY be used +for a given resource type and share type is governed by the +[OCM Share Payloads](#ocm-share-payloads-registry) registry. + + Registration Policy: Specification Required [RFC8126] + + Initial Contents: + +~~~ + +================+=========+===============+ + | Property | Role | Reference | + +================+=========+===============+ + | webdav | send | This document | + | webdav-receive | receive | This document | + | webapp | send | This document | + | webapp-receive | receive | This document | + | ssh | send | This document | + | ssh-receive | receive | This document | + +================+=========+===============+ +~~~ + +## OCM Share Types Registry + +IANA is requested to create the "OCM Share Types" registry in the +"Open Cloud Mesh (OCM) Parameters" group. Each entry records a share +type that MAY appear in the "shareTypes" array advertised by the +[OCM API Discovery](#ocm-api-discovery) endpoint or in the "shareType" +field of a [Share Creation Notification](#share-creation-notification). + + Registration Policy: Specification Required [RFC8126] + + Initial Contents: + +~~~ + +============+===============+ + | Share Type | Reference | + +============+===============+ + | user | This document | + | group | This document | + | federation | This document | + +============+===============+ +~~~ + +## OCM Share Payloads Registry + +IANA is requested to create the "OCM Share Payloads" registry in the +"Open Cloud Mesh (OCM) Parameters" group. Whereas the "OCM Resource +Types", "OCM Share Types", and "OCM Protocols" registries record the +identifiers advertised in Discovery, this registry records the +wire format of the share payload itself: each entry binds a meaningful +combination of resource type, share type, and one or more protocols to +the document that completely specifies the wire format of the +[Share Creation Notification](#share-creation-notification) for that +combination. Two implementations may agree on the Discovery +identifiers and still fail to interoperate if the fields and structure +of the payload are left unspecified; this registry is where that wire +format is pinned down. + +Every value in the "Resource Type", "Share Type", and "Protocols" +columns MUST already appear in the corresponding "OCM Resource Types", +"OCM Share Types", or "OCM Protocols" registry. For each entry, +the Designated Expert MUST verify that the referenced specification +completely specifies the wire format of the share payload for the +combination, including every required and optional field and the full +shape of the "protocol" details object. + +The registered combinations are a constrained subset, not the full +Cartesian product of those three registries, even though for the +initial content the subset and the Cartesian product is the same thing. +However, in other cases that file sharing, a protocol may only be +meaningful for certain resource types. A calendar event, for example, +is usually shared over CalDAV or JMAP, not over ssh. Other +specifications MAY register additional combinations, including ones +that extend an already-registered protocol to a new resource type or +share type; doing so does not modify that protocol's own registration. +The federation combinations are registered in this way by [OCM-MLS]. +If someone wants to specify how to share calendar events over ssh in an +interoperable way, they can do so using this very mechanism. + +A Sending Server MUST NOT send a share for a combination that the +Receiving Server does not advertise in Discovery (see +[Share Creation Notification](#share-creation-notification)). + + Registration Policy: Specification Required [RFC8126] + + Initial Contents: + +~~~ + +===============+============+=====================+===============+ + | Resource Type | Share Type | Protocols | Reference | + +===============+============+=====================+===============+ + | file | user | webdav, webapp, ssh | This document | + | file | group | webdav, webapp, ssh | This document | + | folder | user | webdav, webapp, ssh | This document | + | folder | group | webdav, webapp, ssh | This document | + +===============+============+=====================+===============+ +~~~ + +## OCM Notification Types Registry + +IANA is requested to create the "OCM Notification Types" registry in +the "Open Cloud Mesh (OCM) Parameters" group. This registry records +the values that MAY appear in the "notificationType" field of an OCM +notification sent to the "/notifications" endpoint (see +[Share Acceptance Notification](#share-acceptance-notification)). + +The "Scope" field indicates whether the notification refers to a Share, +in which case the "providerId" field is REQUIRED, or to a Group. The +"Status" field is one of "active" or "experimental". + + Registration Policy: Specification Required [RFC8126] + + Initial Contents: + +~~~ + +===========================+=======+==============+===============+ + | Notification Type | Scope | Status | Reference | + +===========================+=======+==============+===============+ + | SHARE_ACCEPTED | Share | active | This document | + | SHARE_DECLINED | Share | active | This document | + | SHARE_UNSHARED | Share | active | This document | + | REQUEST_RESHARE | Share | experimental | This document | + | RESHARE_UNDO | Share | experimental | This document | + | RESHARE_CHANGE_PERMISSION | Share | experimental | This document | + +===========================+=======+==============+===============+ +~~~ + # Security Considerations ## Trust @@ -1614,6 +1807,10 @@ https://datatracker.ietf.org/doc/html/rfc7517)", May 2015. Signature Algorithm (EdDSA)]( https://datatracker.ietf.org/doc/html/rfc8032)", January 2017. +[RFC8126] Cotton, M., Leiba, B. and Narten, T. "[Guidelines for +Writing an IANA Considerations Section in RFCs]( +https://datatracker.ietf.org/doc/html/rfc8126)", June 2017. + [RFC8174] Leiba, B. "[Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words](https://datatracker.ietf.org/html/rfc8174)", May 2017.