diff --git a/IETF-OCM-MLS.md b/IETF-OCM-MLS.md index dab4697..8a10aec 100644 --- a/IETF-OCM-MLS.md +++ b/IETF-OCM-MLS.md @@ -51,12 +51,20 @@ 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. This document defines a new `shareType`, `"federation"`, and -registers it in the "OCM Share Types" registry defined by [OCM]. A -`"federation"` share is addressed to 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. +server. This document specifies the mechanics of the `"federation"` +share type, registered in the "OCM Share Types" registry by [OCM], for +the case where the Receiving Party is a federated group of users: a +`"federation"` share is then addressed to a 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. + +This document further specifies how an MLS group can maintain the +membership of a Federation of OCM Servers itself, which is the +cryptographically guaranteed Directory Service model of [OCM] +({{servers-federation-groups}}). The two uses of MLS share all of +their machinery and differ only in what a leaf of the group represents: +a user, or an OCM Server. In many Enterprise File Sync and Share (EFSS) systems, which constitute the vast majority of all OCM Servers, there is a tight coupling between @@ -199,6 +207,23 @@ circumstances. enables adding an MLS client to a group asynchronously. KeyPackages MUST be used only once, except for a designated last resort KeyPackage ([RFC9420] Section 16.8). +- **Federation** - As defined in [OCM]: a group of OCM Servers whose +administrators have established mutual trust, identified by a +`federationId` and published at the Directory Endpoint of its members. +A Federation is a set of servers; it is never a Receiving Party of a +share. +- **Servers Federation group** - An MLS group whose members are the OCM +Servers of a Federation, with exactly one leaf per member server, used +to maintain that Federation's membership with cryptographic guarantees +({{servers-federation-groups}}). Wherever this document says "Group" +without qualification it means a federated group of users, as defined +above, and never a Servers Federation group. +- **Federation Admin Server** - A member of a Servers Federation group +whose MLS client is entitled to construct Commits for that group: the +counterpart, for a Servers Federation group, of an Admin. +- **Federation Owner Server** - The member of a Servers Federation +group currently arbitrating its Commits: the first Federation Admin +Server in that group's admin set. # MLS Roles in OCM @@ -260,6 +285,12 @@ For a Virtual Client, the user's home server MUST deliver messages sent to or by the Virtual Client to all of its Emulator Clients, as required by [ietf-mls-virtual-clients] Section 5.1. +In a Servers Federation group ({{servers-federation-groups}}) the same +arrangement applies with the member servers themselves in the place of +the users' home servers: proposals go to every Federation Admin Server, +the Federation Owner Server arbitrates Commits, and there is no FK +distribution. + Commits are constructed and signed by admin clients, but only the Commit accepted by the Group Owner Server takes effect; competing Commits for the same epoch are discarded by their senders. Designating a single @@ -404,11 +435,18 @@ its OCM discovery document at `/.well-known/ocm`: } ~~~ -No additional discovery fields are introduced. The notifications -endpoint is derived as `/notifications` per the base OCM -specification. The KeyPackage endpoint is derived as +No additional discovery fields are introduced by this document. The +notifications endpoint is derived as `/notifications` per the +base OCM specification. The KeyPackage endpoint is derived as `/mls-key-packages`. +A server that participates in a Servers Federation group +({{servers-federation-groups}}) additionally advertises the +`directoryEndPoint` field defined in [OCM], and publishes the +Federation's `mlsGroupId` in the directory document exposed there. +That field, and not a capability of its own, is what signals that the +server exposes a Federation membership. + A server that advertises `"federation"` MUST be able to receive OCM Notifications, since all MLS lifecycle messages are delivered as notifications, and SHOULD include `"notifications"` in its @@ -469,6 +507,43 @@ Address, not the bare identifier that [OCM] calls `userID`; the full address is required because these messages routinely cross server boundaries. +## KeyPackages for OCM Servers {#server-key-packages} + +In a Servers Federation group ({{servers-federation-groups}}) the MLS +client is the OCM Server itself, and its credential identifies the +server rather than one of its users. A server that participates in +such groups MUST expose KeyPackages for its own client at the same +endpoint, selected by `serverId` instead of `userId`: + +~~~ +GET /mls-key-packages?serverId={serverUrl} +~~~ + +Response: + +~~~ json +{ + "serverId": "https://cloud.example.org", + "keyPackages": [ + { + "mediaType": "message/mls", + "encoding": "base64url", + "content": "" + } + ] +} +~~~ + +The `serverId` value is the absolute URL of the OCM Server in the +format [OCM] specifies for the `url` field of a directory document, and +MUST equal the identity carried in the credential of every KeyPackage +returned. A server MUST reject a request whose `serverId` does not +identify itself. All other rules of this section apply unchanged: the +request MUST be signed, KeyPackages MUST be one-time use except for a +designated last resort KeyPackage, and the server MUST remove a +KeyPackage once delivered. A request MUST carry exactly one of +`userId` and `serverId`. + # Group Lifecycle The group lifecycle is entirely independent of other OCM lifecycles @@ -710,6 +785,17 @@ application data carried inside `MLS_APPLICATION` messages ({{key-distribution}}, {{credential-update}}) is the group's OCM Address, never the MLS `group_id`. +Both kinds of group defined in this document use these notification +types, with `shareType` set to `"federation"` in either case, and a +recipient distinguishes them by the contents of the +`notification.federation` object: for a Servers Federation group +({{servers-federation-groups}}) the object carries a `federationId` +field, and a `serverUrl` field wherever the federated-group form +carries `userId`; for a federated group of users it carries no +`federationId`. A recipient MUST reject a notification when both +`mlsGroupId` and `federationId` are present, and MUST similarly +reject one that carries both `userId` and `serverUrl`. + Since `MLS_PROPOSAL` is delivered only to Admin Servers and never broadcast to other Member Servers, Member Servers never observe pending proposals. Proposals covered by a Commit are instead redistributed @@ -1618,6 +1704,164 @@ share updates and share deletions, are likewise sent directly from the sending server to each Member Server, referencing the share by its `providerId` as in base OCM. +# Servers Federation Groups {#servers-federation-groups} + +[OCM] defines a Federation as a group of OCM Servers whose +administrators have established mutual trust, and specifies two models +for maintaining its membership: a peer-announced model, where each +member publishes the membership it knows, and a cryptographically +guaranteed model, which this section specifies. + +The model reuses the group machinery of this document with a single +substitution: the members of the group are the OCM Servers of the +Federation, not the users of a federated group. What follows in this +section stems from that substitution. + +## Relationship to Federated Groups + +A Servers Federation group is not a Receiving Party. No Share is ever +addressed to it, no `shareWith` names it, and the Encryption Model of +this document does not apply to it, as there is no shared resource and +therefore no File Key. Its only purpose is to answer one question - +which OCM Servers are currently members of this Federation - with the +guarantees MLS provides: all members agree on the answer at every +epoch, and each can verify it without trusting any other member's +configuration. + +The two kinds of group are independent. A Federation maintained as a +Servers Federation group MAY host any number of federated groups of +users among its members, and a federated group of users MAY span +servers that share no Federation. Membership in a Servers Federation +group is not a prerequisite for sending or receiving a share, and a +server does not become a member of a federated group by virtue of +being a member of the Federation. + +## Group State {#servers-federation-state} + +A Servers Federation group is an MLS group in which: + +- each member OCM Server has exactly one leaf node, held by the server +acting as an MLS client on behalf of its administrator. There are no +per-user leaves and no Virtual Clients: the administrator is not +represented in the group, the server is. +- the credential at each leaf is a basic credential ([RFC9420] Section +5.3) whose identity field is the UTF-8 encoded absolute URL of the OCM +Server, in the format [OCM] specifies for the `url` field of a +directory document. This is the same string by which the Federation's +directory identifies that server, so the group membership and the +published membership are directly comparable. +- the MLS `group_id` is the value published as `federation.mlsGroupId` +in the directory document of every member ([OCM]). As for any group in +this document, it SHOULD be a fresh random value at creation, as +recommended by [RFC9420] Section 11. +- the Federation's identity and its set of Federation Admin Servers are +carried in a GroupContext extension `ocm_servers_federation` ([RFC9420] +Section 13.4), the counterpart of `ocm_federated_group` +({{admin-set}}): + +~~~ +struct { + opaque server_url; +} FederationAdmin; + +struct { + opaque federation_id; + opaque federation_name; + FederationAdmin admins; +} OCMServersFederation; +~~~ + +All URLs are UTF-8 encoded absolute URLs of OCM Servers. The +`federation_id` field carries the Federation's `federationId` as +defined in [OCM] and MUST NOT change for the lifetime of the group; +`federation_name` carries its human-readable name and MAY change with a +GroupContextExtensions proposal. + +The `admins` list governs Commit construction and arbitration exactly +as the `admins` list of {{admin-set}} does: it is ordered by +appointment, its first entry names the Federation Owner Server, +succession is therefore automatic, and the list MUST NOT otherwise be +reordered. The coupling between the admin set and the membership, the +failover procedure of {{failover}}, the leaf update rules of +{{leaf-key-updates}}, and the rejoin and reinitialisation procedures of +{{rejoin}} and {{reinit}} all apply unchanged, reading "Member Server" +as "member OCM Server", "admin" as "Federation Admin Server", and +"admin client" as "the MLS client of a Federation Admin Server". As +for a federated group, the group MUST have at least one Federation +Admin Server at all times. + +A server MUST list the `ocm_servers_federation` extension type in the +`capabilities.extensions` field of the KeyPackages it publishes under +{{server-key-packages}}, since GroupContext extensions must be +supported by every member of the group ([RFC9420] Section 13.4). + +## Membership Changes + +A change of Federation membership is an MLS group operation: + +- admitting an OCM Server is an Add proposal, committed by the MLS +client of a Federation Admin Server, followed by an `MLS_WELCOME` to +the admitted server. As in {{admins}}, an Add MUST be explicitly +approved by an administrator before it is committed: this leaves +the same human-in-the-loop requirement introduced in [OCM] unchanged, +and recorded here in the group state. +- expelling an OCM Server is a Remove proposal, committed in the same +way and subject to the same approval. A server MAY always leave a +Federation by proposing its own removal, which requires no approval. + +Because the resulting epoch is agreed by every member, an expulsion +takes effect for the whole Federation at once. This is the guarantee +the peer-announced model cannot offer, where a removal states only that +the sender's own directory no longer lists the recipient. + +The notifications that carry these operations are the `MLS_*` types of +{{mls-notification-types}}, with `serverUrl` in place of `userId`. For +example, the Welcome delivered to a newly admitted server is: + +~~~ json +{ + "notificationType": "MLS_WELCOME", + "senderDomain": "ocm-server.example.org", + "shareType": "federation", + "notification": { + "federation": { + "federationId": "sciencemesh", + "mlsGroupId": "", + "serverUrl": "https://cloud.example.org", + "content": "" + } + } +} +~~~ + +As for a federated group, the Welcome MUST carry the group's ratchet +tree in a `ratchet_tree` extension, since the admitted server needs it +to derive the membership and to process subsequent Commits. + +The `OCM_SERVER_ADDED` and `OCM_SERVER_REMOVED` notifications of [OCM] +MAY still be sent to a prospective or a departing member. They remain +useful precisely because they reach the administrator of a server that +is not yet, or no longer, in the group, and therefore cannot receive +its MLS messages. They are advisory in this model: the membership is +what the group state says. + +## Publishing the Membership + +Every member of a Servers Federation group SHOULD publish the +Federation at its Directory Endpoint as specified in [OCM], with +`federationId` equal to the `federation_id` of the GroupContext +extension, `mlsGroupId` equal to the group's `group_id`, and one entry +in `servers` per leaf of the ratchet tree at the current epoch, whose +`url` is the identity carried in that leaf's credential. A member MUST +refresh the published document after processing a Commit that changes +the membership. + +The published document carries no signature of its own, as [OCM] +specifies. A consumer that is itself a member of the group derives the +authoritative membership from the group state and does not need the +document; a consumer that is not a member, a WAYF Page for instance, is +trusting the server it fetched the document from in either case. + # Trust and Authentication {#trust-and-authentication} The Authentication Service role ([RFC9420] Section 3) is fulfilled by @@ -1690,6 +1934,38 @@ Users who require protection of their key material from their own server should choose a native client implementation where cryptographic operations occur on the user's device. +## Servers Federation group credentials + +In a Servers Federation group ({{servers-federation-groups}}) the +credential identifies an OCM Server rather than a user, so the AS role +collapses onto the subject itself: a server attests its own identity. +A KeyPackage for such a group is considered validated when all of the +following hold: + +- it was fetched from the `/mls-key-packages` endpoint of the +server named by the URL in the credential, over TLS, with the response +signed using HTTP Signatures [RFC9421] verifying against that server's +JWKS [RFC7517]; +- the URL in the credential is identical to the `serverId` the +KeyPackage was requested for ({{server-key-packages}}), and its host +part names the server the KeyPackage was fetched from; and +- the KeyPackage signature verifies with the `signature_key` of its +LeafNode. + +This is the same channel binding as for a user credential, with the +subject and the attesting party coinciding. It therefore establishes +only that the party controlling that FQDN and its published keys asked +to join; it is not, and cannot be, evidence that the server ought to be +trusted. That judgement belongs to the administrators, as [OCM] +requires for both of its Directory Service models, and in this model it +is recorded in the group state by the admin approval of the Add +({{servers-federation-groups}}). + +The successor-credential policy above applies unchanged, with the +server URL taking the place of the OCM Address: a credential replacing +another MUST present the same URL, and members MUST reject the +proposal or Commit otherwise. + # Security Considerations {#security-considerations} ## Threat Model @@ -1969,6 +2245,15 @@ defined in [RFC9420] Section 17.3: - Recommended: N - Reference: This document +The GroupContext extension `ocm_servers_federation` defined in +{{servers-federation-state}} is to be registered in the same registry: + +- Value: TBD +- Name: ocm_servers_federation +- Message(s): GC +- 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: @@ -1985,19 +2270,6 @@ Mesh (OCM) Parameters" group: +===================+===========+===============+ ~~~ -The following entry is to be registered in the "OCM Share Types" -registry defined in [OCM], within the "Open Cloud Mesh (OCM) -Parameters" group. This document is the registering specification for -the "federation" share type: - -~~~ - +============+===============+ - | Share Type | Reference | - +============+===============+ - | federation | 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 @@ -2059,6 +2331,27 @@ version in the IETF datatracker. It is meant to ease the review process and it shall be removed when going to RFC last call. The complete changelog is updated in the OCM-API GitHub repository. +## Working Group Version 01 +* Specified Servers Federation groups: an MLS group whose members are + the OCM Servers of a Federation, providing the cryptographically + guaranteed Directory Service model of [OCM]. One leaf per member + server, a credential identifying the server by the same URL its + directory entry uses, a new `ocm_servers_federation` GroupContext + extension, and Add and Remove Commits as the membership changes. + The existing group machinery - admin set, failover, leaf updates, + rejoin and reinitialisation - is reused unchanged. +* Added a `serverId` selector to the KeyPackage endpoint, for the + server-level MLS client of a Servers Federation group, and specified + the corresponding credential validation. +* Reused the `MLS_*` notification types for Servers Federation groups, + with a `federationId` in the `notification.federation` object as the + discriminator between the two kinds of group. +* Dropped the registration of the `federation` share type, which is + now registered by [OCM] as it specifies its mechanics for a + Federation of OCM Servers. This document keeps specifying the + mechanics of that share type for federated groups of users, and + keeps the corresponding share payload registrations. + ## Working Group Version 00 * First Working Group version, adopted by the OCM Working Group. diff --git a/IETF-OCM.md b/IETF-OCM.md index b046901..ba3d212 100644 --- a/IETF-OCM.md +++ b/IETF-OCM.md @@ -88,13 +88,22 @@ they appear in all capitals, as shown here. We define the following concepts, with some non-normative references to related concepts from OAuth [RFC6749] and elsewhere: +* __Directory Endpoint__ - The URL, advertised in the + `directoryEndPoint` field of the OCM API Discovery response, at which + an OCM Server exposes the Federations it is a member of, along with + their membership. +* __Directory Service__ - The function that exposes the membership of + one or more Federations, either as a third-party service or as a + Directory Endpoint of each OCM Server that is a member of a + Federation (see [Directory Service](#directory-service)). * __Discoverable Server__ - A server that tries to supply information in OCM API Discovery. * __Discovering Server__ - A server that tries to obtain information in OCM API Discovery. * __Federation__ - A group of OCM Providers that have established mutual trust and agree on certain policies for interaction. A - Federation MAY be facilitated by a Directory Service. + Federation is facilitated by a Directory Service, and an OCM Provider + MAY be a member of multiple Federations. * __FQDN__ - Fully Qualified Domain Name, such as `"cloud.example.org"`. * __Invite Acceptance Gesture__ - Gesture from the Invite Receiver to the Invite Receiver OCM Server, supplying the Invite Token as well as @@ -160,6 +169,11 @@ related concepts from OAuth [RFC6749] and elsewhere: * __OCM Notification__ - A message from the Receiving Server to the Sending Server or vice versa, using the OCM Notifications endpoint. * __OCM Server__ - A server that has the OCM Provider function. +* __OCM Server Administrator__ - The person or team operating an OCM + Server, responsible for its trust configuration, including the + Federations the OCM Server is a member of. In the peer-announced + Directory Service model, the Administrator's agreement is the trust + anchor for any change of Federation membership. * __Receiving Party__ - A person, group or party who is granted access to the Resource through the Share; similar to "Requesting Party / RqP" in OAuth-UMA, identified by its OCM Address. @@ -237,8 +251,11 @@ _Discoverable Server_ and SHOULD be able to receive _Notifications_. ### OCM Directory Service -An OCM Directory Service is an entity that exposes information about a -_Federation_ of OCM Providers. +An OCM Directory Service is a function that exposes information about +one or more _Federations_ of OCM Providers. It MAY be provided by a +third-party service on behalf of the members of a Federation, or by +each OCM Provider that is a member of a Federation, at its _Directory +Endpoint_. See [Directory Service](#directory-service). ## Roles @@ -264,7 +281,7 @@ _Shares_, and acts as an API client to allow its users to access Remote Resources. It MAY provide its users with an _Address Book_ of _Contacts_ and the ability to accept _Invites_. -In Appendix D, an object model is presented as a non-normative guide for +In Appendix C, an object model is presented as a non-normative guide for implementers to understand the relationships between these terms. # General Flow @@ -404,13 +421,15 @@ free-text input where any OCM Server can be entered. This is especially useful if the Invite Sender is part of a federation of associated OCM Servers. In order to populate the list of associated OCM Servers, the Invite Sender's server MAY make use of a Directory Service, which is -expected to follow the specification detailed in Appendix C. +expected to follow the specification detailed in the +[Directory Service](#directory-service) section. Implementors that provide a WAYF Page SHOULD make the URL for the API endpoint of such a Directory Service configurable, allowing the OCM Server to be part of a network of associated OCM Servers. The configuration mechanism MAY allow an OCM Server to be part of multiple -networks, thus displaying a union of multiple lists in its WAYF Page. +Federations, thus displaying a union of multiple lists in its WAYF +Page. ### Invite Acceptance Response Details @@ -555,6 +574,362 @@ Notification Request, since the Invite Acceptance Request needs to contain an Invite Token that was previously uniquely generated at the Invite Sender OCM server. +# Directory Service + +## Federations and Directories + +A _Federation_ is a group of OCM Servers whose Administrators have +established mutual trust and agreed on common policies for +interaction. The membership of a Federation is exposed by a +_Directory Service_, and is typically used to populate a WAYF Page +(see [Invite Flow](#invite-flow)), to pre-populate an allowlist, or to +seed the registry of _Trusted Servers_. + +An OCM Server MAY be a member of multiple Federations. In that case, +its Directory Service exposes one document per Federation, and the +OCM Server uses the union of the respective lists for the purposes +above. Conversely, a Federation MAY include OCM Servers that are +themselves members of other Federations: membership is not exclusive, +and no transitivity is implied. In particular, the fact that a given +OCM Server is a member of two Federations does not, in itself, make +the members of one Federation trusted by the members of the other. + +The Directory Service is deliberately distributed and does not require +a central registry of Federations. Any group of OCM Servers can form +one. Two operating models are defined: + +* a __peer-announced__ model, specified in [Peer-announced + Directory](#peer-announced-directory), where each member of the + Federation publishes the membership it knows about and + propagates additions by means of the `OCM_SERVER_ADDED` Notification. + The model is eventually consistent, and trust is delegated to the + OCM Server Administrators, who agree to each addition. +* a __cryptographically guaranteed__ model, where the Federation is + managed as an MLS [RFC9420] group of OCM Servers as specified in + [OCM-MLS], so that the membership of the Federation is attested by + the MLS group state rather than by the individual configuration of + each member. See + [MLS-based Directory](#mls-based-directory). + +In both models, the membership is published in the same format at the +same endpoint, so that a consumer of a Directory Service does not need +to know which model is in use. + +Additionally, and for backwards compatibility with existing +deployments, a Federation MAY be published by a third-party Directory +Service on behalf of its members, as described in +[Third-party Directory Service](#third-party-directory-service). + +## Directory Endpoint + +An OCM Server that is a member of one or more Federations SHOULD +advertise a `directoryEndPoint` in its [OCM API +Discovery](#ocm-api-discovery) response, and expose at that URL, via +anonymous HTTPS GET, the Federations it is a member of, in the format +specified in [Directory Payload](#directory-payload). The presence of +the `directoryEndPoint` field is the only signal that an OCM Server +offers a Directory Service; no dedicated capability is defined. + +The response MUST be a JSON object carrying a single REQUIRED +`federation` property. Its value MUST be either a Federation object as +specified below, when the OCM Server is a member of exactly one +Federation, or a JSON array of Federation objects, one per Federation. +Consumers MUST accept both forms. + +The document is not signed. The membership it exposes is not +self-attesting, and a consumer MUST NOT treat it as an authorisation +to interact with the OCM Servers it lists: it is a proposal, whose +trust is established elsewhere. In the peer-announced model that is the +agreement of the OCM Server Administrators, each of whom approves +every member of their own Federation configuration (see [Peer-announced +Directory](#peer-announced-directory)); in the MLS-based model it is the +MLS group state, which is cryptographically verifiable by every member +(see [MLS-based Directory](#mls-based-directory)). In either case a +consumer MUST fetch the document over TLS, so that it is attributable +to the host it was fetched from. + +An OCM Server MUST NOT expose in its Directory Endpoint a Federation +whose membership it is not willing to disclose publicly. If the +membership of a Federation is confidential, its members MUST NOT +advertise a `directoryEndPoint` for it, and MUST exchange the +membership out of band or by means of [OCM-MLS]. + +## Directory Payload + +Each Federation object MUST adhere to the following format: + +* REQUIRED: `federationId` - a short, stable identifier of the + Federation, agreed out of band among its members. Members of the + same Federation MUST use the same value, as it is used to correlate + the documents published by the different members, and to identify the + Federation in an `OCM_SERVER_ADDED` or `OCM_SERVER_REMOVED` + Notification. It MUST consist of lowercase ASCII letters, digits, + and hyphens. +* REQUIRED: `name` - a human-readable name of the Federation. +* OPTIONAL: `mlsGroupId` - the identifier of the MLS group that manages + this Federation, when the cryptographically guaranteed model is in + use (see [MLS-based Directory](#mls-based-directory)). +* REQUIRED: `servers` - a JSON array of objects to describe the list + of OCM Servers that are members of the Federation, with the + following string fields: + - REQUIRED: `url` - an absolute URL identifying the + OCM Server. It MUST: + - include scheme: either `https://` or + (for testing purposes) `http://` + - include host (either a FQDN or an IP address) + - MAY include a non-default port + - MUST NOT include a base path (e.g., `/ocm`) + - MUST NOT include userinfo, query, or fragment + - REQUIRED: `displayName` - a human-readable name + for the OCM Server + +The publishing OCM Server SHOULD include itself in the `servers` +array. + +Example of a document published at the `directoryEndPoint` of a member +of a single Federation: + +~~~ +{ + "federation": { + "federationId": "sciencemesh", + "name": "The ScienceMesh Directory", + "servers": [ + { + "url": "https://ocm-server.example.org", + "displayName": "OCM Server 1" + }, + { + "url": "https://ocm-server.example.com:4443", + "displayName": "OCM Server 2" + }, + { + "url": "http://192.168.1.1:8080", + "displayName": "OCM Server 3" + } + ] + } +} +~~~ +{: type="json"} + +And of a member of two Federations: + +~~~ +{ + "federation": [ + { + "federationId": "sciencemesh", + "name": "The ScienceMesh Directory", + "servers": [ + { + "url": "https://ocm-server.example.org", + "displayName": "OCM Server 1" + } + ] + }, + { + "federationId": "eosc", + "name": "The EOSC Federation", + "mlsGroupId": "51dc30ddc473d43a6011e9ebba6ca770", + "servers": [ + { + "url": "https://ocm-server.example.com:4443", + "displayName": "OCM Server 2" + } + ] + } + ] +} +~~~ +{: type="json"} + +## Peer-announced Directory + +In the peer-announced model, each OCM Server holds its own Federation +configuration, and the trust anchor for every change of that +configuration is the agreement of its Administrator. Changes are +propagated by means of the `OCM_SERVER_ADDED` and +`OCM_SERVER_REMOVED` Notifications (see [Federation +Membership](#federation-membership)), such that the members of a +Federation eventually converge to a consistent membership. + +This model is sometimes informally described as gossip-based. This +document avoids that term: unlike an epidemic gossip protocol, an +announcement here concerns only the sender's own directory, is sent +only to a peer the sender's Administrator deliberately added, and is +acted upon only after the receiving Administrator agrees. + +Both Notifications carry the same, deliberately narrow meaning: an OCM +Server A sends one to an OCM Server B to inform B that A's directory +for a given Federation now contains B, respectively no longer contains +B. A never asserts anything about the presence of a third server: B +learns about the rest of the Federation by fetching A's Directory +Endpoint, not from the notification itself. This keeps every statement +on the wire attributable to the Administrator who made it. + +### Adding a Member + +An OCM Server A MAY add an OCM Server B to one of its Federations in +either of the following two cases: + +1. A received an Invite Acceptance Request from B at its + `/invite-accepted` endpoint (see [Invite Flow](#invite-flow)), A's + Administrator was notified of the new peer and agreed to include B + in the Federation. Note that in this case one of A's users has + already established an out-of-band relationship with one of B's + users, which gives A's Administrator a reason to trust B (see + [Security Advantages](#security-advantages)). +2. A's Administrator knows about B out of band and loads B into A's + Federation configuration. + +In both cases, A MUST send an `OCM_SERVER_ADDED` Notification to B, as +B is now contained in A's directory for that Federation. In the second +case, A MUST send it when the configuration is loaded for the first +time, and MUST NOT send it again for a member that is already part of +the Federation configuration, so that reloading or restarting does not +generate duplicate notifications. + +If B does not expose the `notifications` capability, or the +notification cannot be delivered, A MAY still keep B in its Federation +configuration, but the membership cannot converge through B: A SHOULD +report the condition to its Administrator, who is then expected to +establish the Federation membership with B out of band. + +### Processing an Addition + +Upon receiving an `OCM_SERVER_ADDED` Notification from an OCM Server +A, an OCM Server B SHOULD notify its own Administrator, and SHOULD NOT +change its Federation configuration before its Administrator agrees. +If B's Administrator agrees to join the Federation identified in the +notification, B SHOULD: + +1. fetch the current membership from A's Directory Endpoint, as + advertised in the `directoryEndPoint` field of A's Discovery + response, and select the Federation object whose `federationId` + matches the one in the notification; +2. add the members it does not know yet to its own configuration for + that Federation, including A itself; +3. send an `OCM_SERVER_ADDED` Notification for that Federation to each + of those members it did not previously know, and only to those, as + each of them is now contained in B's own directory. + +Step 3 is what makes the membership converge: a server that receives +an `OCM_SERVER_ADDED` for a Federation in whose directory it already +appears, from a peer it already knows, MUST respond with HTTP 201 and +MAY otherwise ignore the notification. Because a notification is only +ever sent to a peer that was not previously known, the propagation +terminates. + +If B's Administrator does not agree, B MUST NOT change its +configuration. B SHOULD still respond with HTTP 201 if the +notification was well-formed, as the response acknowledges the receipt +of the notification, not the acceptance of the Federation membership. +B MAY respond with HTTP 403 to signal that it does not wish to receive +further such notifications from A. + +### Removing a Member + +An OCM Server Administrator MAY remove a member from a Federation +configuration at any time, and does not need any other member's +agreement to do so. When an OCM Server A removes an OCM Server B from +its directory for a Federation, A MUST send an `OCM_SERVER_REMOVED` +Notification to B, informing B that A's directory for that Federation +no longer contains B. + +Upon receiving an `OCM_SERVER_REMOVED` Notification from A, an OCM +Server B SHOULD notify its own Administrator. As Federation +membership expresses mutual trust, B SHOULD remove A from its own +configuration for that Federation, so that the two directories do not +disagree; B's Administrator MAY nonetheless decide to keep A, for +instance while the reason for the removal is being clarified out of +band. + +B MUST NOT remove any other member on the strength of such a +notification, and MUST NOT propagate it: A only ever speaks about its +own directory. Consequently, when a Federation as a whole decides to +exclude a member, each remaining member's Administrator applies the +removal locally, and each removing OCM Server sends its own +`OCM_SERVER_REMOVED` to the excluded member. Until they have all done +so, a member that one Administrator considers untrustworthy may still +be listed by others: removal in this model converges only as fast as +the Administrators act on it, and is not enforceable. Federations that +require a consistent and enforceable removal of members are expected +to use the model described in the next section. + +Note that removing a member from a Federation is not equivalent to +withdrawing trust from it: an OCM Server MAY keep interacting with a +former co-member, for instance because their users established contact +through the [Invite Flow](#invite-flow). A Federation removal only +withdraws the membership, and any further consequence, such as +denylisting the peer or removing the Shares exchanged with it, is a +local policy decision. + +## MLS-based Directory + +In the cryptographically guaranteed model, the Federation is managed +as an MLS [RFC9420] group whose members are the OCM Servers of the +Federation, as specified in [OCM-MLS]. + +An OCM Server that participates in such a Federation MUST still +advertise a `directoryEndPoint` and publish the membership in the +format specified in [Directory Payload](#directory-payload), for the +benefit of consumers that only need the list of members, such as a +WAYF Page. In that case it MUST include the `mlsGroupId` field, and +the published list MUST reflect the membership of the group at the +current epoch. The published document remains informative: the +authoritative membership is the MLS group state, which every member +can verify cryptographically and which therefore needs no signature of +its own on the published document. + +The membership changes of such a Federation are carried by the `MLS_*` +Notifications registered by [OCM-MLS], which already provide the +transport for MLS group operations: an addition is an MLS Add Commit +and a removal an MLS Remove Commit, and both are enforceable on all +members at the resulting epoch. The `OCM_SERVER_ADDED` and +`OCM_SERVER_REMOVED` Notifications MAY still be used within such a +Federation to inform a prospective or departing member, and its +Administrator, before or after the corresponding MLS operations take +place, but they are not what establishes the membership. The +processing of the MLS messages themselves is specified in [OCM-MLS]. + +## Third-party Directory Service + +A third-party Directory Service is a back-end service used to federate +multiple OCM Servers and facilitate the Invite flow. It is expected to +expose, via anonymous HTTPS GET, a document that adheres to the format +specified in [Directory Payload](#directory-payload). + +In this arrangement, the members of the Federation delegate the +curation of the membership to the operator of the Directory Service, +which is trusted to only include audited servers. Members MAY +configure such a Directory Service in addition to the Federations they +maintain themselves, as one more source of the union described in +[Federations and Directories](#federations-and-directories). + +An OCM Server Administrator MAY likewise pre-populate a Federation +configuration with a list of servers assembled out of band, without +using any Directory Service at all. This is the same case already +covered by bullet 2 of [Adding a Member](#adding-a-member): the +curation of the membership is a one-time act of the Administrator +rather than a continuous one delegated to a third-party operator, but +in both this case and the third-party Directory Service case above, +the resulting members were not learned incrementally through the +convergence mechanism of [Peer-announced +Directory](#peer-announced-directory). + +For this reason, upon startup an OCM Server MUST send an +`OCM_SERVER_ADDED` Notification, for the relevant Federation, to every +member it learned of through a third-party Directory Service or an +out-of-band pre-populated list, the first time each such member +appears in its configuration; it MUST NOT send it again for a member +that is already known, so that restarting the OCM Server does not +generate duplicate notifications. This lets those members become +aware of the sending OCM Server and apply the processing described in +[Processing an Addition](#processing-an-addition), so that a +Federation entered through either of these two backward-compatible +routes still joins the peer-announced convergence. + # OCM API Discovery ## Introduction @@ -599,8 +974,8 @@ When OCM API Discovery can occur in preparation of a Share Creation Notification, the Sending Server takes on the 'Discovering Server' role and the Receiving Server plays the role of 'Discoverable Server'. For a navigation index of discovery fields, capabilities, and related -informative aids, see [Appendix E: Navigation -Index](#appendix-e-navigation-index). +informative aids, see [Appendix D: Navigation +Index](#appendix-d-navigation-index). ## Process @@ -762,6 +1137,14 @@ contain the following information about its OCM API: - `"must-invite"` - an invite MUST have been exchanged between the sender and the receiver before a Share Creation Notification can be sent +* OPTIONAL: directoryEndPoint (string) - URL of the Directory Endpoint + hosted by this OCM Server, where it exposes the Federations it is a + member of, as specified in [Directory + Service](#directory-service). The URL MUST use HTTPS and is + discovered from this field; it is not a fixed path in the OCM API. + As with the Discovery Process, implementations MAY fallback to HTTP + instead of HTTPS in testing setups. + Example: `"https://cloud.example.org/ocm/directory"`. * OPTIONAL: inviteAcceptDialog (string) - URL path of a web page where a user can accept an invite, when query parameters `"token"` and `"providerDomain"` are provided. Implementations that offer the @@ -975,6 +1358,12 @@ traffic. When signing is in play, the signer and verifier roles are: Sending Server SHOULD sign; the Receiving Server verifies. See [Notifications](#notifications) and [HTTP Message Signatures](#http-message-signatures). +* __Federation Membership Notification__ (`POST /notifications` with + `OCM_SERVER_ADDED` or `OCM_SERVER_REMOVED`) - the OCM Server whose + directory changed signs; the added or removed OCM Server verifies, + using the JWK Set discovered from the `senderDomain`. See + [Federation Membership](#federation-membership) and [HTTP Message + Signatures](#http-message-signatures). # Share Creation Notification @@ -1068,8 +1457,8 @@ described in [OCM-IP]. Receiving Server. Other values MAY be used provided they are registered in the "OCM Share Types" registry (see [IANA Considerations](#iana-considerations)); for example, [OCM-MLS] - registers the "federation" share type for a group of users that - spans multiple OCM Servers. + specifies the use of the "federation" share type for a group of + users that spans multiple OCM Servers. The Sending Server SHOULD only use a `shareType` that the Receiving Server advertises for the share's `resourceType` in its Discovery response, i.e. one listed in the `shareTypes` array of the matching @@ -1340,7 +1729,8 @@ notification that this happened. This optional endpoint is used to inform the other party about a change that concerns a previously known entity, such as a Resource or a -trusted Share type (e.g. a user). +trusted Share type (e.g. a user), or about a change of the membership +of a Federation, which concerns the OCM Servers themselves. A Server that intends to send a notification SHOULD make a HTTP POST request: @@ -1521,6 +1911,73 @@ Further, the `notification` object MUST include the following fields: * REQUIRED groupId (string) - identifier of the group to be removed from the target OCM Server. +## Federation Membership + +A notification MUST be sent by an OCM Server to inform a target OCM +Server that its directory for a given Federation now contains, or no +longer contains, that target OCM Server, as described in [Peer-announced +Directory](#peer-announced-directory). These notifications are +addressed to the OCM Server Administrator rather than to a user: the +recipient SHOULD notify its Administrator and SHOULD NOT alter its +Federation configuration without their agreement. + +For these cases, a notification payload is to be formed such that the +`resourceType` MUST be omitted, the `shareType` MUST be set to +`federation`, and the `notificationType` MUST be one of: + +- "OCM_SERVER_ADDED", to inform the target OCM Server that the + sender's directory for the given Federation now contains it. +- "OCM_SERVER_REMOVED", to inform the target OCM Server that the + sender's directory for the given Federation no longer contains it. + +Neither notification asserts anything about any other member of the +Federation: the recipient learns the rest of the membership from the +sender's Directory Endpoint. + +Further, the `notification` object MUST include the following fields: + +* OPTIONAL message (string) - an optional human-readable message that + describes the event, such as the reason why the target OCM Server + was added or removed, for the benefit of its Administrator. +* REQUIRED federation (object) - an object containing the details of + the Federation, including: + * REQUIRED federationId (string) - the identifier of the + Federation, matching the `federation.federationId` field of the + corresponding document published at the sender's Directory + Endpoint (see [Directory Payload](#directory-payload)). + * OPTIONAL name (string) - the human-readable name of the + Federation, for the benefit of the recipient's Administrator. + * REQUIRED url (string) - the absolute URL under which the target + OCM Server was added to, or removed from, the sender's directory + for that Federation, in the format specified for the `url` field + in [Directory Payload](#directory-payload). The target OCM + Server SHOULD verify that this URL identifies itself, and SHOULD + discard the notification otherwise. + * OPTIONAL directoryEndPoint (string) - the URL of the sender's + Directory Endpoint, as a hint. If omitted, the recipient MUST + obtain it from the `directoryEndPoint` field of the sender's + Discovery response; if the two values differ, the recipient MUST + use the discovered one. + * OPTIONAL mlsGroupId (string) - the identifier of the MLS group + that manages the Federation, when the model described in + [MLS-based Directory](#mls-based-directory) is in use. + +The recipient of either notification SHOULD respond with HTTP 201 if +the notification is well-formed, irrespective of whether its +Administrator agrees to the resulting change of its own configuration, +and MAY respond with HTTP 403 to signal that it does not wish to +receive further such notifications from the sender. As an +`OCM_SERVER_ADDED` notification establishes trust between servers that +may have had no prior relationship, it SHOULD NOT be used unless HTTP +Message Signatures are available on both sides. + +Within a Federation managed as an MLS group, these notifications MAY +be used to inform a prospective or departing member and its +Administrator, but they are not what changes the membership: the +`MLS_*` notifications registered by [OCM-MLS] carry the group +operations that do, as described in [MLS-based +Directory](#mls-based-directory). + # Resource Access @@ -1952,10 +2409,13 @@ 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). -This document registers only the "user" and "group" share types; other +field of a [Share Creation Notification](#share-creation-notification), +or in the "shareType" field of a [Notification](#notifications). Other specifications MAY register additional share types in this registry. -The "federation" share type, for example, is registered by [OCM-MLS]. +Concerning the "federation" share type, this document specifies its +mechanics for a Federation of OCM Servers, whereas the case of a group +of users that spans multiple OCM Servers acting as the Receiving Party +of a share is addressed by [OCM-MLS]. Registration Policy: Specification Required [RFC8126] @@ -1967,6 +2427,7 @@ The "federation" share type, for example, is registered by [OCM-MLS]. +============+===============+ | user | This document | | group | This document | + | federation | This document | +============+===============+ ~~~ @@ -2034,7 +2495,10 @@ Resource, in which case the "providerId" field is REQUIRED in the payload, or to a Recipient, i.e. to the shareType in a [Share Creation Notification](#share-creation-notification), in which case a corresponding identifier such as "userId" is REQUIRED in the -payload. +payload. For the "federation" shareType, the Recipient is the +Federation itself, and the "federation" object identifying it and the +OCM Server concerned is REQUIRED in the payload (see [Federation +Membership](#federation-membership)). Registration Policy: Specification Required [RFC8126] @@ -2052,6 +2516,8 @@ payload. | REQUEST_SHARE | Resource | This document | | USER_REMOVED | Recipient | This document | | GROUP_REMOVED | Recipient | This document | + | OCM_SERVER_ADDED | Recipient | This document | + | OCM_SERVER_REMOVED | Recipient | This document | +===========================+===========+===============+ ~~~ @@ -2128,10 +2594,60 @@ of the protocol that _can_ be used to assist operators in establishing trust. For instance, invite flow can be used to establish that users know and have out of band connections with other users on an OCM server. -Further more the Directory Service feature can be used to establish a -trusted federation, where a central authority can be trusted to -implement measures for auditing and adding only trusted servers into the -discovery service. +Further more the [Directory Service](#directory-service) feature can be +used to establish a trusted federation. In the third-party model, a +central authority can be trusted to implement measures for auditing and +adding only trusted servers into the directory; an Administrator who +instead pre-populates a Federation configuration out of band, as +described in [Third-party Directory +Service](#third-party-directory-service), plays that same role locally. +In the peer-announced model, there is no such central authority: trust +is delegated to the OCM Server Administrators, each of whom agrees to +every addition to their own Federation configuration. This has a +number of consequences that Administrators need to be aware of: + +* A member of a Federation can cause any other member to be presented + with a new peer, by adding that peer and letting the propagation + described in [Processing an Addition](#processing-an-addition) take + place. The human in the loop is what contains this: an + `OCM_SERVER_ADDED` Notification is a proposal, not an instruction, + and an Administrator that does not recognise a proposed peer is + expected to refuse it. Implementations MUST NOT apply such a + notification automatically. +* The `OCM_SERVER_ADDED` Notifications an OCM Server sends on startup + for members obtained from a third-party Directory Service or an + out-of-band pre-populated list (see [Third-party Directory + Service](#third-party-directory-service)) reach servers with which + no prior peer-announced exchange took place. A recipient has no way + to distinguish such a notification from one resulting from the + incremental convergence of [Peer-announced + Directory](#peer-announced-directory): its own Administrator's + agreement remains the only safeguard, as noted above. +* Membership is only eventually consistent. In particular, a removal + only ever states that the sender's own directory no longer contains + the recipient, and cannot be enforced on the other members: a server + that is no longer trusted by one Administrator may still be listed + by others until each of them acts on it (see [Removing a + Member](#removing-a-member)). +* The membership published at a Directory Endpoint is available to + anonymous clients, and thus discloses the peers of a Federation. + Federations whose membership is confidential are expected not to + publish it, as stated in [Directory + Endpoint](#directory-endpoint). +* An `OCM_SERVER_ADDED` Notification reaches a server with which no + trust relationship exists yet, so its signature can only be verified + against key material discovered from the `senderDomain`. This + attributes the notification to the sender's domain, and nothing more; + it is the Administrator's decision that establishes trust. +* Conversely, an unauthenticated or spoofed `OCM_SERVER_REMOVED` would + be an inexpensive way to have a member drop a legitimate peer. A + recipient MUST therefore verify the notification as any other, and + MUST apply it only to the sender's own membership. + +Federations that need membership to be consistent, enforceable, and +cryptographically verifiable are expected to use the MLS-based model +described in [MLS-based Directory](#mls-based-directory) and specified +in [OCM-MLS]. ### httpsig @@ -2208,9 +2724,6 @@ https://datatracker.ietf.org/html/rfc6749)", October 2012. Specifications and Registration Procedures ](https://datatracker.ietf.org/html/rfc6838)", January 2013. -[RFC7515] Jones, M., Bradley, J., Sakimura, N., "[JSON Web Signature -(JWS)](https://datatracker.ietf.org/doc/html/rfc7515)", May 2015. - [RFC7517] Jones, M., "[JSON Web Key (JWK)]( https://datatracker.ietf.org/doc/html/rfc7517)", May 2015. @@ -2271,6 +2784,10 @@ in Open Cloud Mesh using Messaging Layer Security](https://datatracker.ietf.org/doc/draft-ietf-ocm-mls-federated-groups/)", Work in Progress, Internet-Draft. +[RFC9420] Barnes, R., Beurdouche, B., Robert, R., Millican, J., +Omara, E. and Cohn-Gordon, K., "[The Messaging Layer Security (MLS) +Protocol](https://datatracker.ietf.org/doc/html/rfc9420)", July 2023. + [RFC8792] Watsen, K., Auerswald, E., Farrel, A., Wu, Q., "[Handling Long Lines in Content of Internet-Drafts and RFCs]( https://datatracker.ietf.org/doc/html/rfc8792)", June 2020. @@ -2431,57 +2948,7 @@ As an example, if the payload is about initiating a new share, the file owner has to be an account from the instance at the origin of the request. -# Appendix C: Directory Service - -A third-party Directory Service is a back-end service used to federate -multiple OCM Servers and facilitate the Invite flow. It is expected to -expose, via anonymous HTTPS GET, a signed JWS document [RFC7515], where -the signing key MUST be made available offline and the payload MUST -adhere to the following format: - -* REQUIRED: `federation` - a human-readable name for the list of OCM - Servers exposed by the Directory Service -* REQUIRED: `servers` - a JSON array of objects to describe the list - of OCM Servers with the following string fields: - - REQUIRED: `url` - an absolute URL identifying the - OCM Server. It MUST: - - include scheme: either `https://` or - (for testing purposes) `http://` - - include host (either a FQDN or an IP address) - - MAY include a non-default port - - MUST NOT include a base path (e.g., `/ocm`) - - MUST NOT include userinfo, query, or fragment - - REQUIRED: `displayName` - a human-readable name - for the OCM Server -Example: - -~~~ -{ - "payload": { - "federation": "The ScienceMesh Directory", - "servers": [ - { - "url": "https://ocm-server.example.org", - "displayName": "OCM Server 1" - }, - { - "url": "https://ocm-server.example.com:4443", - "displayName": "OCM Server 2" - }, - { - "url": "http://192.168.1.1:8080", - "displayName": "OCM Server 3" - } - ] - }, - "protected": {"alg": "ES256"}, - "signature": "..." -} -~~~ -{: type="json"} - - -# Appendix D: Object models +# Appendix C: Object models An implementor of OCM MAY choose any internal object model to represent an _Address Book_, a _Contact_, an _Invite_, a _Provider_, a _Share_, @@ -2626,6 +3093,7 @@ that section. | (OCM Server) | +-----------------------+ | - apiVersion | + | - directoryEndPoint | | - enabled | | - endPoint | | - inviteAcceptDialog | @@ -2685,6 +3153,8 @@ that section. * __apiVersion__: Version string of supported OCM API * __capabilities__: Optional features supported * __criteria__: Criteria for accepting a Share Creation Notification +* __directoryEndPoint__: URL where the Federations this OCM Server is a + member of are exposed * __enabled__: Boolean indicating if OCM service is active * __endPoint__: Base URI for OCM API endpoints * __provider__: Friendly branding name @@ -2837,7 +3307,7 @@ to model a few key properties. * __type__: Type of Resource (file, folder, calendar, etc.) -# Appendix E: Navigation Index +# Appendix D: Navigation Index This appendix is informative. It points to normative sections and informative aids; it introduces no new rules. @@ -2857,8 +3327,14 @@ informative aids; it introduces no new rules. `protocol.*.requirements[]` * __Signing__ - [HTTP Message Signatures](#http-message-signatures), [Signing Direction Index](#signing-direction-index) -* __Object models__ - [Appendix D: Object - models](#appendix-d-object-models) +* __Directory Service__ - [Directory Service](#directory-service); + the `directoryEndPoint` field is advertised in [OCM API + Discovery](#ocm-api-discovery) +* __Federation membership__ - propagated with `OCM_SERVER_ADDED` and + `OCM_SERVER_REMOVED`; see [Federation + Membership](#federation-membership) +* __Object models__ - [Appendix C: Object + models](#appendix-c-object-models) * __Informative diagrams__ - in the OCM-API repository under `diagrams/` # Changes @@ -2868,6 +3344,34 @@ version in the IETF datatracker. It is meant to ease the review process and it shall be removed when going to RFC last call. The complete changelog is updated in the OCM-API GitHub repository. +## Version 08 +* Promoted the Directory Service to a normative section following the + Invite Flow, and made it distributed: the membership of a Federation + is now published by each member at the `directoryEndPoint` advertised + in its Discovery response, in addition to the pre-existing + third-party Directory Service. Two operating models are defined: a + peer-announced, eventually consistent one, where trust is delegated + to the OCM Server Administrators, and a cryptographically guaranteed + one based on [OCM-MLS]. An OCM Server MAY be a member of multiple + Federations in both models. +* Simplified the Directory payload: the JWS envelope is gone, as trust + in the peer-announced model rests with the OCM Server Administrators + who approve every membership change, and the MLS-based model is + cryptographically guaranteed by construction. The `federation` + field is now an object carrying a stable `federationId` and a + human-readable `name`. +* Introduced the `OCM_SERVER_ADDED` and `OCM_SERVER_REMOVED` + notification types, with `shareType` set to `federation`, to + propagate Federation membership between OCM Servers, to be consumed + by the OCM Server Administrator. Each of them states only whether + the sender's directory now contains the recipient, so that every + assertion on the wire is attributable to the Administrator who made + it. +* Moved the registration of the `federation` share type from + [OCM-MLS] to this document, as it is now used to identify a group of + OCM Servers; [OCM-MLS] keeps specifying its use for federated groups + of users and the related share payloads. + ## Version 07 * Required the `keyid` signature parameter and that it matches the `kid` of the verification key in the signer's JWK Set. @@ -2896,9 +3400,8 @@ The complete changelog is updated in the OCM-API GitHub repository. wrapping. * Added informative aids: same-string note for `must-exchange-token`, Appendix D criteria label fix, [Signing Direction - Index](#signing-direction-index), [Appendix E: Navigation - Index](#appendix-e-navigation-index), and companion diagrams under - `diagrams/` in the OCM-API repository. + Index](#signing-direction-index), the Navigation Index appendix, + and companion diagrams under `diagrams/` in the OCM-API repository. * Rehaul of the Notification (formerly "Share Acceptance Notification") endpoint and payload, and adaptation of the IANA registries. The core notifications have now been fully spelled diff --git a/spec.yaml b/spec.yaml index ce47f06..388469c 100644 --- a/spec.yaml +++ b/spec.yaml @@ -516,6 +516,31 @@ components: invalid_client, invalid_grant, unauthorized_client, or unsupported_grant_type) example: https://cloud.example.org/ocm/token + directoryEndPoint: + type: string + format: uri + description: > + Optional URL of the Directory Endpoint hosted by this OCM Server, + where it exposes the Federations it is a member of, along with + their membership. The URL is discovered from this field; it is not + a fixed path in the OCM API. It MUST use https, though + implementations MAY fall back to HTTP in testing setups. The + presence of this field is the only signal that an OCM Server + offers a Directory Service; no dedicated capability is defined. + See the Directory schema for the payload, and the Directory + Service section of the OCM Internet-Draft for the normative + procedure, including the peer-announced propagation of the + membership by means of the `OCM_SERVER_ADDED` and + `OCM_SERVER_REMOVED` notifications. + + **HTTP Responses:** + - 200: `application/json` with a Directory object, whose + `federation` property carries either a single Federation object, + when this OCM Server is a member of exactly one Federation, or + an array of Federation objects, one per Federation. Consumers + MUST accept both forms. + - 404: This OCM Server does not expose any Federation. + example: https://cloud.example.org/ocm/directory inviteAcceptDialog: type: string description: > @@ -524,6 +549,100 @@ components: If for example `"/index.php/apps/sciencemesh/accept"` is specified here then a Where-Are-You-From page could redirect the end-user to `/index.php/apps/sciencemesh/accept?token=zi5kooKu3ivohr9a&providerDomain=example.com`. example: /index.php/apps/sciencemesh/accept + Directory: + type: object + description: > + The Federations an OCM Server is a member of, as exposed at the + `directoryEndPoint` advertised in the Discovery response, or by a + third-party Directory Service. The `federation` property carries a + single Federation object, when the OCM Server is a member of exactly + one Federation, or an array of Federation objects, one per + Federation: consumers MUST accept both forms. + + The document is not signed: in the peer-announced model the trust + rests with the OCM Server administrators, who approve every member of + their own federation configuration, whereas in the MLS-based model the + authoritative membership is the MLS group state, which is + cryptographically verifiable. It MUST be fetched over TLS, and a + consumer MUST NOT treat it as an authorisation to interact with the + OCM Servers it lists. + required: + - federation + properties: + federation: + oneOf: + - $ref: "#/components/schemas/Federation" + - type: array + items: + $ref: "#/components/schemas/Federation" + example: + federation: + federationId: sciencemesh + name: The ScienceMesh Directory + servers: + - url: https://ocm-server.example.org + displayName: OCM Server 1 + - url: https://ocm-server.example.com:4443 + displayName: OCM Server 2 + - url: http://192.168.1.1:8080 + displayName: OCM Server 3 + Federation: + type: object + description: > + One Federation of OCM Servers and its membership. + required: + - federationId + - name + - servers + properties: + federationId: + type: string + pattern: "^[a-z0-9-]+$" + description: > + A short, stable identifier of the Federation, agreed out of band + among its members. Members of the same Federation MUST use the + same value, as it is used to correlate the documents published by + the different members, and to identify the Federation in an + `OCM_SERVER_ADDED` or `OCM_SERVER_REMOVED` notification. + example: sciencemesh + name: + type: string + description: A human-readable name of the Federation. + example: The ScienceMesh Directory + mlsGroupId: + type: string + description: > + Optional identifier of the MLS group that manages this Federation, + when the cryptographically guaranteed model specified in the + OCM-MLS Internet-Draft is in use. In that case the authoritative + membership is the MLS group state at the current epoch, and this + document is informative. + example: 51dc30ddc473d43a6011e9ebba6ca770 + servers: + type: array + description: > + The OCM Servers that are members of this Federation. The + publishing OCM Server SHOULD include itself. + items: + type: object + required: + - url + - displayName + properties: + url: + type: string + format: uri + description: > + An absolute URL identifying the OCM Server. It MUST include + a scheme, either `https://` or (for testing purposes) + `http://`, and a host, either a FQDN or an IP address. It + MAY include a non-default port. It MUST NOT include a base + path (e.g. `/ocm`), nor userinfo, query or fragment. + example: https://ocm-server.example.org + displayName: + type: string + description: A human-readable name for the OCM Server. + example: OCM Server 1 NewShare: type: object required: @@ -998,6 +1117,11 @@ components: `providerId` of the underlying resource, and in case of `user`, `group`, or `federation` share types, it MUST contain at least the `userId`, `groupId`, or `mlsGroupId` of the underlying recipient, respectively. + For an `OCM_SERVER_ADDED` or `OCM_SERVER_REMOVED` notification, the + `federation` object MUST contain the `federationId` of the + Federation and the `url` of the OCM Server that the sender's + directory for that Federation now contains, respectively no longer + contains. example: legacyShareWasAccepted: notificationType: SHARE_ACCEPTED @@ -1023,6 +1147,27 @@ components: message: User is not a trusted contact any longer user: userId: alice@alice.example.org + ocmServerWasAdded: + notificationType: OCM_SERVER_ADDED + shareType: federation + senderDomain: ocm-server.example.org + notification: + message: Your OCM Server is now part of our federation + federation: + federationId: sciencemesh + name: The ScienceMesh Directory + url: https://cloud.example.org + directoryEndPoint: https://ocm-server.example.org/ocm/directory + ocmServerWasRemoved: + notificationType: OCM_SERVER_REMOVED + shareType: federation + senderDomain: ocm-server.example.org + notification: + message: Your OCM Server is no longer part of our federation + federation: + federationId: sciencemesh + name: The ScienceMesh Directory + url: https://cloud.example.org mlsWelcome: notificationType: MLS_WELCOME shareType: federation