diff --git a/IETF-OCM-MLS.md b/IETF-OCM-MLS.md index 941d82a..cc0f50c 100644 --- a/IETF-OCM-MLS.md +++ b/IETF-OCM-MLS.md @@ -2,7 +2,7 @@ title: >- Federated Groups in Open Cloud Mesh using Messaging Layer Security abbrev: "OCM MLS Federated Groups" -docname: draft-nordin-ocm-mls-federated-groups-00 +docname: draft-nordin-ocm-mls-federated-groups-01 category: std ipr: trust200902 diff --git a/IETF-OCM-MLS.xml b/IETF-OCM-MLS.xml index bf1c358..2c05cd4 100644 --- a/IETF-OCM-MLS.xml +++ b/IETF-OCM-MLS.xml @@ -12,7 +12,7 @@ ]> - + Federated Groups in Open Cloud Mesh using Messaging Layer Security @@ -38,7 +38,7 @@ - + Applications and Real-Time @@ -78,9 +78,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. 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. @@ -165,6 +165,12 @@ depending on their policy and the nature of the shared data. [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. +Unless stated otherwise, every base64 encoded value this document, +including MLS wire-format messages, KeyPackages, group_id values, and +wrapped keys, is encoded using base64url (the URL- and filename-safe +alphabet defined in [RFC4648], Section 5) with padding omitted. A +decoder MUST accept such a value whether or not padding is present. + This document uses terminology from [OCM] and [RFC9420]. Additional definitions: @@ -430,8 +436,8 @@ GET /mls-key-packages?userId={userId} "keyPackages": [ { "mediaType": "message/mls", - "encoding": "base64", - "content": "" + "encoding": "base64url", + "content": "" } ] } @@ -708,7 +714,7 @@ that requirement: providerId is REQUIRED only for no that refer to a Share, and the MLS notification types omit it. All MLS-specific parameters are carried inside the notification object that [OCM] provides for type-specific parameters. The mlsGroupId -field carries the base64-encoded MLS group_id as advisory routing +field carries the base64url-encoded MLS group_id as advisory routing information, used to dispatch the message to the right group state without parsing the MLS message; the authoritative group_id is the one inside the MLS message itself, and a mismatch between the two MUST be @@ -741,9 +747,9 @@ added user. { "notificationType": "MLS_WELCOME", "notification": { - "mlsGroupId": "", + "mlsGroupId": "", "userId": "bob@othercloud.example.org", - "content": "" + "content": "" } } ]]> @@ -782,8 +788,8 @@ act on it. { "notificationType": "MLS_PROPOSAL", "notification": { - "mlsGroupId": "", - "content": "" + "mlsGroupId": "", + "content": "" } } ]]> @@ -811,9 +817,9 @@ data, per [RFC9420] Section 15.2. { "notificationType": "MLS_COMMIT", "notification": { - "mlsGroupId": "", - "proposals": [""], - "content": "" + "mlsGroupId": "", + "proposals": [""], + "content": "" } } ]]> @@ -858,8 +864,8 @@ epoch ([RFC9420] Section 15). { "notificationType": "MLS_APPLICATION", "notification": { - "mlsGroupId": "", - "content": "" + "mlsGroupId": "", + "content": "" } } ]]> @@ -900,13 +906,13 @@ by the KeyPackage endpoint. { "notificationType": "MLS_REJOIN", "notification": { - "mlsGroupId": "", + "mlsGroupId": "", "keyPackages": [ { "userId": "bob@othercloud.example.org", "mediaType": "message/mls", - "encoding": "base64", - "content": "" + "encoding": "base64url", + "content": "" } ] } @@ -1223,7 +1229,7 @@ array, and MAY also carry a credentials array (" + "wrappedKey": "" } ] } @@ -1910,6 +1916,53 @@ defined in [RFC9420] Section 17.3: 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 ): + +
+ +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: + +
+ +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 ). These +registrations do not modify the protocols' own registrations: + +
+
Open Issues @@ -1936,6 +1989,22 @@ Commits can no longer be applied. The proposed OCM Journaling mechanism can be useful in this context. +
+
Changes + +This section collects the changes with respect to the previous +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 01 + + Following the introduction of IANA Registries in Version 06 of [OCM], +all registry entries related to the federation share type have been +introduced in this document. + + +
References @@ -1950,6 +2019,10 @@ Work in Progress, Internet-Draft. Requirement Levels", March 1997. +[RFC4648] Josefsson, S. "The Base16, Base32, and Base64 Data +Encodings", October +2006. + [RFC7517] Jones, M., "JSON Web Key (JWK)", May 2015. @@ -2007,658 +2080,676 @@ through the Tech Fund diff --git a/IETF-OCM.md b/IETF-OCM.md index e8e31e9..17aed8d 100644 --- a/IETF-OCM.md +++ b/IETF-OCM.md @@ -1,6 +1,6 @@ --- title: 'Open Cloud Mesh' -docname: draft-ietf-ocm-open-cloud-mesh-05 +docname: draft-ietf-ocm-open-cloud-mesh-06 category: std ipr: trust200902 diff --git a/IETF-OCM.xml b/IETF-OCM.xml index ddc2a97..a141f66 100644 --- a/IETF-OCM.xml +++ b/IETF-OCM.xml @@ -12,7 +12,7 @@ ]> - + Open Cloud Mesh @@ -45,7 +45,7 @@ - + Applications and Real-Time @@ -120,77 +120,26 @@ they appear in all capitals, as shown here. related concepts from OAuth [RFC6749] and elsewhere: - Resource - The piece of data or interaction to which access is -being granted, including but not limited to: a file or folder, a video -call, a contact, a printer queue, etc. - Remote Resource - A Resource provided by the Sending Server. - Shared Resource - A Resource shared by an OCM Server, becoming a -Remote Resource if accepted by the Invite Receiver OCM Server. - Share - A policy rule stating that certain actors have specific -access rights to a Resource; it MAY also refer to a record in a -database representing this rule. - Sending Party - A person or party who is authorized to create -Shares; similar to "Resource Owner" in OAuth [RFC6749], identified by -its OCM Address. - 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. - Share Creation Notification - A server-to-server request from the -sending server to the receiving server, notifying the receiving server -that a Share has been created. - Sending Server - The server that: - - holds the Resource ("file server" or "Entreprise File Sync and Share -(EFSS) server" role), - provides access to it (by exposing at least one "API"), - takes the decision to create the Share based on user interface -gestures from the Sending Party (the "Authorization Server" role in -OAuth [RFC6749]), - takes the decision about authorizing attempts to access the Resource -(the "Resource Server" role in OAuth [RFC6749]), - sends out Share Creation Notifications when appropriate (see below). - - Receiving Server - The server that: - - receives Share Creation Notifications (see below), - actively or passively notifies the receiving user or group of any -incoming Share Creation Notification, - acts as an API client, allowing the receiving user to access the -Resource through an API (e.g., WebDAV [RFC4918]) of the sending -server. - - Sending Gesture - A user interface interaction from the Sending -Party to the Sending Server, conveying the intention to create a -Share. - Share Creation - The addition of a Share to the database state of -the Sending Server, in response to a successful Sending Gesture or for -another reason. - Sharing User - A user providing access to a Resource through a -Share. - FQDN - Fully Qualified Domain Name, such as "cloud.example.org". - OCM Server - A server that supports OCM. - OCM API Discovery - Process of evaluating properties of a Remote -Resource, after establishing contact with an OCM Server. - Discovering Server - A server that tries to obtain information in -OCM API Discovery. Discoverable Server - A server that tries to supply information in +OCM API Discovery. + 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. - FQDN - Fully Qualified Domain Name, such as "cloud.example.com". + 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 the OCM Address of the Invite Sender, effectively allowlisting the Invite Sender OCM Server for sending Share Creation Notifications to the Invite Receiver OCM Server. - Invite Acceptance Response - HTTP response to the Invite -Acceptance Request. Invite Acceptance Request - API call from the Invite Receiver OCM Server to the Invite Sender OCM Server, supplying the Invite Token as well as the OCM Address of the Invite Receiver, effectively allowlisting the Invite Sender OCM Server for sending Share Creation Notifications to the Invite Receiver OCM Server. + Invite Acceptance Response - HTTP response to the Invite +Acceptance Request. Invite Creation Gesture - Gesture from the Invite Sender to the Invite Sender OCM Server, resulting in the creation of an Invite Token. @@ -207,44 +156,44 @@ OCM Address. Invite Sender OCM Server - The server holding an address book used by the Invite Sender, to which details of the Invite Receiver are to be added. - Invite String - A base64 encoded string containing an Invite Token -and the FQDN of an Invite Sender OCM Server joined by an @-sign. + Invite String - An Invite Token and the FQDN of an Invite Sender +OCM Server joined by an @-sign, then encoded using base64url (the +URL- and filename-safe alphabet defined in [RFC4648], Section 5) with +padding omitted. Invite Token - A hard-to-guess string used in the Invite Flow, generated by the Invite Sender OCM Server and linked uniquely to the Invite Sender's OCM Address. OCM Address - identifies a user or group "at" an OCM Server. The OCM Address contains a server specific Party identifier, a host -locating the OCM Server and an optional port. The OCM Address is not a -URI as it does not have scheme and the identifier may contain reserved -characters. +locating the OCM Server and an optional port. The OCM Address is not +a URI as it does not have scheme and the identifier may contain +reserved characters:
-The identifier is an opaque, case-sensitive UTF-8 string. It is - separated from the host by the last "@" in the OCM Address. It is - possible to have multiple @-signs in a OCM-address, e.g. when an - email address is the local part of the address like - nomen.nescio@example.org@cloud.example.org. -host is an IP literal encapsulated within square brackets, an IPv4 - address in dotted decimal form, or a registered name as described in - [RFC3986]. +"identifier" is an opaque, case-sensitive UTF-8 string. It is +separated from the host by the last "@" in the OCM Address. It is +possible to have multiple @-signs in a OCM-address, e.g. when an +email address is the local part of the address like +nomen.nescio@example.org@cloud.example.org. +"host" is an IP literal encapsulated within square brackets, an IPv4 +address in dotted decimal form, or a registered name as described in +[RFC3986]:
The optional port subcomponent can be used to specify a port to use - for discovery (see Discovery Process). +for discovery (see Discovery Process). The OCM Server MUST be discoverable at the given host and optional - port via the Well-Known [RFC8615] path /.well-known/ocm. The OCM - Address MUST NOT contain a path. +port via the Well-Known [RFC8615] path /.well-known/ocm. The OCM +Address MUST NOT contain a path. OCM API Discovery - Process of evaluating properties of a Remote Resource, after establishing contact with an OCM Server. - OCM Server - A server that has the OCM Provider function. - Discovering Server - A server that tries to obtain information in -OCM API Discovery. 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. 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. @@ -269,7 +218,8 @@ Shares; similar to "Resource Owner" in OAuth [RFC6749], identified by its OCM Address. Sending Server - The server that: - holds the Resource for instance, a file server, + holds the Resource ("file server" or "Entreprise File Sync and Share +(EFSS) server" role), provides access to it (by exposing at least one "API"), takes the decision to create the Share based on user interface gestures from the Sending Party (the "Authorization Server" role in @@ -299,13 +249,13 @@ Remote Resource if accepted by the Invite Receiver OCM Server. Sharing User - A user providing access to a Resource through a Share. Trusted Server - An OCM Server that is considered trustworthy by - another OCM Server, based on out-of-band information, federation - membership or prior interactions, SHOULD be recorded in an internal - registry of trusted servers, that SHOULD be updated over time based - on new information. The registry SHOULD include the FQDN of the - trusted server and the Public Key used for HTTP Signatures. It MAY - also include additional metadata such as the inviteAcceptDialog URL - or supported capabilities. +another OCM Server, based on out-of-band information, federation +membership or prior interactions, SHOULD be recorded in an internal +registry of trusted servers, that SHOULD be updated over time based +on new information. The registry SHOULD include the FQDN of the +trusted server and the Public Key used for HTTP Signatures. It MAY +also include additional metadata such as the inviteAcceptDialog URL +or supported capabilities. WAYF Page - A Where-Are-You-From page is a discovery service used to identify the OCM Server of an Invite Receiver. @@ -459,7 +409,7 @@ the Invite Sender OCM Server Whereas the precise syntax of the Invite Message and the Invite Acceptance Gesture will differ between implementations, the Invite -Acceptance Request SHOULD be a HTTP POST request: +Acceptance Request MUST be a HTTP POST request: to the /invite-accepted path in the Invite Sender OCM Server's OCM @@ -482,9 +432,14 @@ OCM Server. suggestion for display in the Invite Sender's address book using TLS - using httpsig [RFC9421] +When HTTP Message Signatures are available, the Invite Acceptance +Request MUST be signed and verified as described in HTTP Message +Signatures. As the Invite flow establishes +the trust that later exchanges rely on, implementations SHOULD NOT use +it unless signing is available. + The Invite Receiver OCM Server SHOULD apply its own policies for trusting the Invite Sender OCM Server before making the Invite Acceptance Request. @@ -541,10 +496,11 @@ A 403 response status means the Invite Receiver OCM Server is not trusted to accept this Invite. A 409 response status means the Invite was already accepted. -The Invite Sender OCM Server SHOULD verify the HTTP Signature on the -Invite Acceptance Request and apply its own policies for trusting the -Invite Receiver OCM Server before processing the Invite Acceptance -Request and sending the Invite Acceptance Response. +Before processing the Invite Acceptance Request and sending the Invite +Acceptance Response, the Invite Sender OCM Server SHOULD apply its own +policies for trusting the Invite Receiver OCM Server. Any HTTP +Signature on the request is verified as described in HTTP Message +Signatures. As with the userID in the Invite Acceptance Request, the one in the Response also doesn't need to be human-memorable, doesn't need to match @@ -587,17 +543,19 @@ and a provider. There are two recognized formats: Invite string format: -A base64-encoded string containing the token and the provider’s FQDN, -joined by an @ sign. Example: +The token and the provider’s FQDN, joined by an @ sign and then +encoded using base64url (the URL- and filename-safe alphabet defined +in [RFC4648], Section 5) with padding omitted. Example: If the token is a55a966e-15c1-4cb9-a39d-4e4c54399baf and the provider is cloud.example.org, the combined string is a55a966e-15c1-4cb9-a39d-4e4c54399baf@cloud.example.org, -which when base64-encoded becomes -YTU1YTk2NmUtMTVjMS00Y2I5LWEzOWQtNGU0YzU0Mzk5YmFmQG15LWNsb3VkLXN0b -3JhZ2Uub3Jn. -When parsing an invite string, implementors must base64-decode it, -then split on the last @ sign, taking care to allow multiple @ -characters in the token part. +which when base64url-encoded becomes +YTU1YTk2NmUtMTVjMS00Y2I5LWEzOWQtNGU0YzU0Mzk5YmFmQGNsb3VkLmV4YW1wbGUu +b3Jn. +When parsing an invite string, implementors MUST base64url-decode it +(accepting the string whether or not padding is present), then split +on the last @ sign, taking care to allow multiple @ characters in +the token part. Link format: If the inviting OCM Server supports a WAYF page, the invite may be provided as a link with the token as a request parameter. Example: @@ -746,17 +704,18 @@ server supports in both the Sending Server role and the Receiving Server role, with their access protocols. Each item in this list MUST itself be an object containing the following fields: - name (string) - A supported resource type (file, calendar, -contact, ...). -Implementations MUST offer support for at least one -resource type, where file is the commonly supported -one. Each resource type is identified by its name: -the list MUST NOT contain more than one resource type -object per given name. + name (string) - A supported resource type, such as file, calendar, +contact, etc. Implementations MUST offer support for at least one +resource type: file is the commonly supported one, and +other values are to be registered in the "OCM Resource Types" +registry (see IANA Considerations). +Each resource type is identified by its name: the list MUST NOT +contain more than one resource type object per given name. shareTypes (array of string) - The supported recipient share types. MUST contain -"user" at a minimum, plus optionally "group" and -"federation". +"user" at a minimum, plus optionally "group" or any +other value registered in the "OCM Share Types" registry +(see IANA Considerations). Example: ["user"] protocols (object) - The supported protocols for accessing Shared Resources of this type. Implementations that offer file @@ -804,11 +763,13 @@ Fields: key based authentication. - ssh-receive (object) - Advertised, as an empty object, by implementations that support receiving SSH shares. -- Any additional protocol supported for this Resource type MAY be - advertised here, where the value MAY correspond to - a top-level URI to be used for that protocol. Similarly, - additional receiving capabilities for custom protocols SHOULD - be advertised using a -receive suffixed property. +- Any additional protocol supported for this Resource type SHOULD be + advertised here, where the value MAY correspond to a top-level + URI to be used for that protocol. Similarly, additional receiving + capabilities for custom protocols SHOULD be advertised using a + -receive suffixed property. Additional protocols are to be + registered in the "OCM Protocols" registry (see + IANA Considerations). OPTIONAL: capabilities (array of string) - The optional capabilities supported by this OCM Server. @@ -884,6 +845,116 @@ provide this URL as well. Example: "https://cloud.example.org/ocm/token". +
+ +
HTTP Message Signatures + +A number of OCM API requests are signed "using httpsig [RFC9421]", as +described in the respective sections. This section specifies the +normative requirements for producing and verifying those signatures. +Appendix B contains a complete example. + +Public keys for signature verification are published in the format +specified by [RFC7517] at the signer's /.well-known/jwks.json +endpoint, if the http-sig capability is included in the +Discovery response. + +
Applicability + +Support for HTTP Message Signatures is negotiated through the +http-sig capability in the Discovery response. +The following rules let deployments adopt signing incrementally while +remaining interoperable: + + + A Server that implements HTTP Message Signatures MUST use them when +interacting with another Server that advertises the http-sig +capability. + Such a Server MAY nonetheless continue to interact, without signing, +with a Server that does not advertise the http-sig capability, for +backwards compatibility. + A Server that implements HTTP Message Signatures MUST verify any +signature present on a request it receives, as specified below. + A Server MAY accept an unsigned request from a Server that does not +advertise the http-sig capability; a Server that advertises the +must-use-http-sig criterion MUST reject unsigned requests. + A Server that does not implement HTTP Message Signatures operates +without them. + + +Because the Invite Acceptance +Request and Request for a +Share establish the trust that later exchanges +rely on, implementations SHOULD NOT use those features unless HTTP +Message Signatures are available. + +
+
Signing Requirements + +A signed request MUST cover at least the following Signature-Input +components: + + + "@method" - HTTP method + "@target-uri" - full request URI (scheme, authority, + path, query) + "content-digest" - [RFC9530] digest of the body + "content-length" - message size + + +The Signature-Input parameters MUST include created. Freshness and +replay protection are anchored on created (see Verification +Requirements). + +A signed request SHOULD additionally cover the date component when a +Date header is present. + +The content-digest component binds the request body to the signature, +protecting it against modification in transit. Its value MUST use a +hash algorithm from the IANA "Hash Algorithms for HTTP Digest Fields" +registry [IANA-DIGEST-ALG]; implementations MUST support sha-256. + +A request signed in the context of OCM MUST carry the signature +parameter tag="ocm" (see Section 2.3 of [RFC9421]). Unlike the +signature label, which is a dictionary key that is not covered by the +signature and MAY be rewritten in transit, the tag parameter is part +of the signature base and is therefore integrity-protected. + +A request MUST include one and only one signature carrying +tag="ocm". The signature label MAY be any value; it is not +significant to OCM processing. + +The signature MUST use an asymmetric algorithm from the IANA "HTTP +Signature Algorithms" registry [IANA-SIG-ALG]; ed25519 [RFC8032] is +RECOMMENDED. A symmetric algorithm, such as the HMAC-based +hmac-sha256, MUST NOT be used, as the Receiving Server would not be +able to verify the signature without prior access to the shared secret. + +
+
Verification Requirements + +Verifiers MUST reject signatures that omit any of the mandatory +components listed under Signing Requirements or the created +parameter, and MUST reject signatures whose created value is more +than a small implementation-defined skew tolerance in the future, or +older than the verifier's freshness window. + +A Content-Digest header value carrying multiple algorithms MUST have +every recognised digest match the body; a single match alongside a +recognised mismatch MUST be treated as an integrity failure. + +Verifiers MUST identify the OCM signature by its tag="ocm" +parameter, examining the parameters of each member of the +Signature-Input field and disregarding the dictionary labels. +Verifiers MUST verify only that signature. If more than one signature +carries tag="ocm", the entire message MUST be rejected. A request +that carries no signature with tag="ocm" is unsigned and is handled +as described in Applicability (accepted only at the receiver's +discretion, or rejected when the receiver advertises +must-use-http-sig). Signatures without tag="ocm" MAY coexist (e.g. +proxy-attached signatures) but verifiers MUST NOT process them as part +of OCM signature processing. +
Share Creation Notification @@ -915,6 +986,20 @@ If the Receiving Server does not advertise must-exchange-tok criteria, the Sending Server MAY still include must-exchange-token voluntarily. +The Sending Server SHOULD 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 +SHOULD 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). +For backwards compatibility reasons, the Sending Server MAY still send +a share with the file, user, webdav combination if the Receiving +server does not advertise it, as it MAY be assumed to be supported. + 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 @@ -930,10 +1015,9 @@ described in [OCM-IP]. REQUIRED shareWith (string) -OCM Address of the user, group or federation the provider -wants to share the Resource with. This MUST be known -in advance, either via a previous Invitation or through -other means. +OCM Address of the user or group the provider wants to share the +Resource with. This MUST be known in advance, either via a previous +Invitation or through other means. Example: "51dc30ddc473d43a6011e9ebba6ca770@cloud.example.org" REQUIRED name (string) Name of the Resource (file or folder). @@ -962,26 +1046,26 @@ Example: "Dimitri" Display name of the user that wants to share the Resource Example: "John Doe" REQUIRED shareType (string) -SHOULD have a value of "user", "group", or "federation", to -indicate that the first part of the shareWith OCM Address refers -to a Receiving Party who is a single user of the Receiving Server, -a group of users at the Receiving Server, or a group of users that -spans multiple OCM Servers belonging to a federation as exposed by -a Directory Service, including at least one user at the Receiving -Server. -In the federation case, OCM Servers MAY resolve the actual -recipients by either querying external AAI systems, or exchanging -the groups' metadata between themselves. For the latter, the -RECOMMENDED implementation is based on the MLS protocol and it is -described in [OCM-MLS]. -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. +SHOULD have a value of "user" or "group", to indicate that the first +part of the shareWith OCM Address refers to a Receiving Party who +is a single user of the Receiving Server, or a group of users at the +Receiving Server. Other values MAY be used provided they are +registered in the "OCM Share Types" registry (see +IANA Considerations); for example, [OCM-MLS] +registers 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 +resourceTypes entry (see +Share Creation Notification). 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. +by the Receiving Server. +Registered values are listed in the "OCM Resource Types" registry +(see 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 @@ -996,6 +1080,10 @@ The supported protocols are: 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). 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, @@ -1240,7 +1328,8 @@ notification that this happened.
Request for a Share If the Receiving Party knows of a resource that has not yet -been shared, the Receiving Party MAY make an HTTP POST request +been shared, the Receiving Party MAY request that it be shared. +Such a Request for a Share MUST be an HTTP POST request to the /request-share path in the Sending Server's OCM API @@ -1249,24 +1338,33 @@ header its request body containing a JSON document representing an object with the fields as described below using TLS - using httpsig [RFC9421] +When HTTP Message Signatures are available, the Request for a Share +MUST be signed and verified as described in HTTP Message +Signatures. As requesting access to a +restricted resource relies on authenticating the requester, +implementations SHOULD NOT use this feature unless signing is +available. +
Fields REQUIRED owner (string) -OCM Address of the user who will be requested to share -the resource. +OCM Address of the user who will be requested to share the resource. REQUIRED shareWith (string) -OCM Address of the user, group or federation that wants to -receive a share of the resource. +OCM Address of the user or group that wants to receive a share of +the resource. Example: "51dc30ddc473d43a6011e9ebba6ca770@cloud.example.org" REQUIRED share (string) A unique identifier for the resource. Example: 1234567890abcdef or https://cloud.example.org/files/data.txt +Any HTTP Signature on the Request for a Share is verified as described +in HTTP Message Signatures before the +Sending Server acts on it. + After receiving a request for a Share, the Sending Party MAY send a Share Creation Notification to the Receiving Party using the OCM address in the shareWith field. @@ -1298,7 +1396,9 @@ with the fields as described below Notification it MUST be one of: 'SHARE_ACCEPTED' - 'SHARE_DECLINED' + 'SHARE_DECLINED' +Registered values are listed in the "OCM Notification Types" +registry (see IANA Considerations). REQUIRED providerId (string) - copied from the Share Creation Notification for the Share this notification is about @@ -1439,11 +1539,12 @@ Content-Type: application/x-www-form-urlencoded Digest: SHA-256=ok6mQ3WZzKc8nb7s/Jt2yY1uK7d2n8Zq7dhl3Q0s1xk= Content-Length: 101 Signature-Input: - ocm=("@method" "@target-uri" "content-digest" "date"); + sig1=("@method" "@target-uri" "content-digest" "date"); created=1730815200; keyid="receiver.example.org#key1"; - alg="ed25519" -Signature: ocm=:bM2sV2a4oM8pWc4Q8r9Zb8bQ7a2vH1kR9xT0yJ3uE4wO5lV6bZ1cP + alg="ed25519"; + tag="ocm" +Signature: sig1=:bM2sV2a4oM8pWc4Q8r9Zb8bQ7a2vH1kR9xT0yJ3uE4wO5lV6bZ1cP 2rN3qD4tR5hC=: grant_type=authorization_code& @@ -1596,74 +1697,170 @@ a Resource without an explicit grant from the Sending Server.
IANA Considerations +[RFC Editor: please replace all occurrences of "RFC XXXX" with the +RFC number assigned to this document and remove this note.] +
Well-Known URI for the Discovery The following value is to be registered in the "Well-Known URIs" -registry (using the template from [RFC8615]): - URI suffix: ocm - Change controller: IETF - Specification document(s): the present Draft, once in RFC form - Related information: N/A +registry (using the template from [RFC8615]): + +
+
URI suffix:
+
+ ocm +
+
Change controller:
+
+ IETF +
+
Specification document(s):
+
+ RFC XXXX (this document) +
+
Status:
+
+ permanent +
+
Related information:
+
+ N/A +
+
JSContact Types Registry The following entry is to be registered in the "JSContact Types" -registry (using the template from [RFC9553]): - Type Name: ocmAddress - Intended Usage: common - Since Version: 1.0 - Until Version: N/A - Change Controller: IETF - Reference or Description: - -An object representing an OCM address. The object contains: +registry (using the template from [RFC9553]): + +
+
Type Name:
+
+ ocmAddress +
+
Intended Usage:
+
+ common +
+
Since Version:
+
+ 1.0 +
+
Until Version:
+
+ N/A +
+
Change Controller:
+
+ IETF +
+
Reference or Description:
+
+ An object representing an OCM address. The object contains: + + + + "address" (String, required): The OCM federated address in +format "user@provider" where provider is the FQDN of an +OCM-capable server. + "trusted" (Boolean, optional): Whether shares from this address +are automatically accepted. Default: false. + "source" (String, optional): How this address was established. +See "JSContact Enum Values" registry for allowed values. + "label" (String, optional): Human-readable label for this +address. + -
+ See RFC XXXX, . +
+
JSContact Properties Registry The following entry is to be registered in the "JSContact Properties" -registry (using the template from [RFC9553]): - Property Name: ietf.org:ocmAddresses - Property Type: String[ocmAddress] - Property Context: Card - Intended Usage: common - Since Version: 1.0 - Until Version: N/A - Change Controller: IETF - Reference or Description: - -A map of OCM addresses for a contact. The keys are arbitrary - identifiers (e.g., "primary", "work") and the values are ocmAddress - objects as defined in the JSContact Types Registry. +registry (using the template from [RFC9553]): + +
+
Property Name:
+
+ ietf.org:ocmAddresses +
+
Property Type:
+
+ String[ocmAddress] +
+
Property Context:
+
+ Card +
+
Intended Usage:
+
+ common +
+
Since Version:
+
+ 1.0 +
+
Until Version:
+
+ N/A +
+
Change Controller:
+
+ IETF +
+
Reference or Description:
+
+ A map of OCM addresses for a contact. The keys are arbitrary +identifiers (e.g., "primary", "work") and the values are +ocmAddress objects as defined in the JSContact Types Registry. +See RFC XXXX, . +
+
JSContact Enum Values Registry -The following entries are to be registered in the "JSContact Enum -Values" registry (using the template from [RFC9553]). - Property Name: ietf.org:ocmAddresses/source - Context: Card - Since Version: 1.0 - Until Version: N/A - Change Controller: IETF - Reference or Description: - -Values indicating how an OCM address was established. - -Initial Contents: +The following entry is to be registered in the "JSContact Enum +Values" registry (using the template from [RFC9553]): + +
+
Property Name:
+
+ ietf.org:ocmAddresses/source +
+
Context:
+
+ Card +
+
Since Version:
+
+ 1.0 +
+
Until Version:
+
+ N/A +
+
Change Controller:
+
+ IETF +
+
Reference or Description:
+
+ Values indicating how an OCM address was established. See +RFC XXXX, . +
+
+ +
JSContact Enum Values Subregistry + +IANA will create a subregistry for "ietf.org:ocmAddresses/source" +(Context: Card) in accordance with [RFC9553], Section 3.7.2. All +entries in the initial contents below have a Since Version of 1.0, +no Until Version, and IETF as the Change Controller. Initial +contents:
+
+
+
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 and in the +"name" field of each entry in the "resourceTypes" array advertised by +the OCM API Discovery endpoint. + +Registration Policy: Specification Required [RFC8126] + +Initial Contents: + +
+ +
+
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 endpoint or in the +"protocol" object of a +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 registry. + +Registration Policy: Specification Required [RFC8126] + +Initial Contents: + +
+ +
+
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 endpoint or in the "shareType" +field of a Share Creation Notification. +This document registers only the "user" and "group" share types; other +specifications MAY register additional share types in this registry. +The "federation" share type, for example, is registered by [OCM-MLS]. + +Registration Policy: Specification Required [RFC8126] + +Initial Contents: + +
+ +
+
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 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 correspond. +However, in other cases beyond 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. + +Registration Policy: Specification Required [RFC8126] + +Initial Contents: + +
+ +
+
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). + +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: + +
+
Security Considerations @@ -1702,7 +2076,9 @@ discovery service. It is RECOMMENDED to use signed messages, "httpsig" [RFC9421], to verify that an OCM server is the server you expect it to be, and SHOULD -be done unless you have a niche use case. +be done unless you have a niche use case. Where signatures are used, +they MUST follow the requirements in +HTTP Message Signatures.
@@ -1735,6 +2111,10 @@ author, version, name of work, or endorsement information.
Normative References +[IANA-DIGEST-ALG] IANA, "Hash Algorithms for HTTP Digest Fields". + +[IANA-SIG-ALG] IANA, "HTTP Signature Algorithms". + [RFC2119] Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels", March 1997. @@ -1743,6 +2123,10 @@ March 1997. "Uniform Resource Identifier (URI): Generic Syntax ", January 2005 +[RFC4648] Josefsson, S. "The Base16, Base32, and Base64 Data +Encodings", October +2006. + [RFC4918] Dusseault, L. M. "HTTP Extensions for Web Distributed Authoring and Versioning", June 2007. @@ -1761,6 +2145,9 @@ Specifications and Registration Procedures [RFC8032] Josefsson, S., Liusvaara, I., "Edwards-Curve Digital Signature Algorithm (EdDSA)", January 2017. +[RFC8126] Cotton, M., Leiba, B. and Narten, T. "Guidelines for +Writing an IANA Considerations Section in RFCs", June 2017. + [RFC8174] Leiba, B. "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", May 2017. @@ -1778,13 +2165,13 @@ Representation of Contact Data, May 2024"
Informative References -[OCM-IP] Nordin, M., Lo Presti, G., and Baghbani, M. "Open -Cloud Mesh Integration +[OCM-IP] Nordin, M., Lo Presti, G., and Baghbani, M. "Open Cloud Mesh +Integration Protocol", Work in Progress, Internet-Draft. -[OCM-MLS] Nordin, M., Lo Presti, G., and Baghbani, M. "Federated -Groups in Open Cloud Mesh using Messaging Layer +[OCM-MLS] Nordin, M., Lo Presti, G., and Baghbani, M. "Federated Groups +in Open Cloud Mesh using Messaging Layer Security", Work in Progress, Internet-Draft. @@ -1882,74 +2269,49 @@ breaks in @signature-params for display purposes only): "content-length" "date"); created=[timestamp]; keyid="sender.example.org#key1"; - alg="ed25519" + alg="ed25519"; + tag="ocm" Sign this base using for example Ed25519 ([RFC8032]) to produce the -signature, using the ocm label, and then add headers (line breaks -for display purposes only): +signature, and then add headers (line breaks for display purposes +only). Note that the dictionary label (sig1 below) is arbitrary; the +signature is marked as belonging to OCM by its tag="ocm" parameter, +which is part of the signature base above: Content-Digest: sha-256=:[digest-value]: Content-Length: [body-length] Date: [date] -Signature-Input: ocm=("@method" "@target-uri" "content-digest" +Signature-Input: sig1=("@method" "@target-uri" "content-digest" "content-length" "date"); created=[timestamp]; keyid="sender.example.org#key1"; - alg="ed25519" -Signature: ocm=:[signature-value]=: + alg="ed25519"; + tag="ocm" +Signature: sig1=:[signature-value]=: -A signed request MUST cover at least the following Signature-Input -components: - - - "@method" - HTTP method - "@target-uri" - full request URI (scheme, authority, - path, query) - "content-digest" - [RFC9530] digest of the body - "content-length" - bound message size - "date" - bound clock time - - -The Signature-Input parameters MUST include created. Verifiers MUST -reject signatures that omit any of the above components or the created -parameter, and MUST reject signatures whose created value is more than -a small implementation-defined skew tolerance in the future, or older -than the verifier's freshness window. - -A Content-Digest header value carrying multiple algorithms MUST have -every recognised digest match the body; a single match alongside a -recognised mismatch MUST be treated as an integrity failure. - -A request signed in the context of OCM MUST include one and only one -signature with the label ocm in its Signature and Signature-Input -headers. - -A symmetric signing algorithm MUST NOT be used to sign the -request, as the Receiving Server would not be able to verify the -signature without having access to the shared secret in advance. +The covered components, the created parameter, the single ocm +tag, and the prohibition on symmetric algorithms shown here are +normative; see HTTP Message Signatures for +the full requirements.
Verifying a Signature (Receiver) -Verifiers MUST locate the ocm-labeled entry and verify only that one. -If multiple ocm signatures are present, the entire message MUST be -rejected. Verifiers MUST reject requests for which no ocm-labeled entry -is present. Other labels MAY coexist (e.g. proxy-attached signatures) -but verifiers MUST NOT process them as part of OCM signature -processing. - -To verify an incoming signed request: +The normative verification requirements are specified in +HTTP Message Signatures. The following +illustrates the procedure to verify an incoming signed request: Extract the provider domain from the sender field in the request body Fetch the public key from https://<provider-domain>/.well-known/jwks.json - Locate the unique signature with the label ocm in the -Signature-Input header + Locate the unique signature carrying the tag="ocm" parameter in +the Signature-Input header, disregarding its dictionary label +(here sig1) Extract keyid from Signature-Input header and find the key matching the kid value in the [RFC7517] response Reconstruct the signature base from the request using the @@ -2308,7 +2670,7 @@ from a Sending Party to a Receiving Party. must-exchange-token) resourceType: Type of resource (file, folder, calendar, etc.) sender: OCM Address of the party creating the Share - shareType: Type of recipient (user, group, federation) + shareType: Type of recipient (user, group, etc.) shareWith: OCM Address of the Receiving Party state: Current state of the Share (accepted, pending, deleted) @@ -2435,6 +2797,25 @@ 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 06 + + Introduced IANA Registries for resource types, protocols, share +types, and share payloads, and populated them with all relevant +values defined in this document. + Moved the federation share type definition along with the +corresponding share payload description to the [OCM-MLS] Draft. + Improved the http-sig related text, and promoted it from an +appendix to a normative section. In addition, made the use of +http-sig a MUST for implementations that offer it as capability. + Sorted the Terms and removed duplicates. + Addressed the IANA early review: added the Status field to the +Well-Known URI registration, added section references to the +JSContact registrations, moved the creation of the JSContact enum +values subregistry to a dedicated subsection, and reformatted the +registration templates so each field renders on its own line. + + +
Version 05 Introduced a /request-share endpoint to request a user of an @@ -2512,9 +2893,9 @@ Peter Szegedi, Ron Trompert, Benedikt Wegmann and Jonathan Xu. We would also like to thank Ishank Arora, Gianmaria Del Monte, Jörn Friedrich Dreyer, Richard Freitag, Hugo González Labrador, -Matthias Kraus, Maxence Lange, Lovisa Lugnegård, Sandro Mesterheide, -Antoon Prins and Björn Schießle for their direct contributions -to the specification. +Matthias Kraus, Maxence Lange, Lovisa Lugnegård, Thibault Meunier, +Sandro Mesterheide, Antoon Prins and Björn Schießle for their direct +contributions to the specification. Over the years many more people have been involved in the development of OCM. We would like to thank all of them for their contributions, @@ -2571,691 +2952,786 @@ a specific projec