diff --git a/IETF-OCM-IP.xml b/IETF-OCM-IP.xml index 5bd8cb6..e0f4822 100644 --- a/IETF-OCM-IP.xml +++ b/IETF-OCM-IP.xml @@ -38,7 +38,7 @@ - + Applications and Real-Time diff --git a/IETF-OCM-MLS.xml b/IETF-OCM-MLS.xml index 1fe653c..bf1c358 100644 --- a/IETF-OCM-MLS.xml +++ b/IETF-OCM-MLS.xml @@ -38,7 +38,7 @@ - + Applications and Real-Time diff --git a/IETF-OCM.md b/IETF-OCM.md index b8f2e08..13f1a42 100644 --- a/IETF-OCM.md +++ b/IETF-OCM.md @@ -1,6 +1,6 @@ --- title: 'Open Cloud Mesh' -docname: draft-ietf-ocm-open-cloud-mesh-04 +docname: draft-ietf-ocm-open-cloud-mesh-05 category: std ipr: trust200902 diff --git a/IETF-OCM.xml b/IETF-OCM.xml index 6d3e078..ddc2a97 100644 --- a/IETF-OCM.xml +++ b/IETF-OCM.xml @@ -1,6 +1,6 @@ - + - + Open Cloud Mesh @@ -45,7 +45,7 @@ - + Applications and Real-Time @@ -225,7 +225,7 @@ 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@ocm.example.org. + 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]. @@ -720,15 +720,11 @@ from it (the part after the last @ sign). Step 2: The Discovering Server SHOULD attempt OCM API Discovery via a HTTP GET request to https://<fqdn>/.well-known/ocm. Step 3: If that results in a valid HTTP response with a valid JSON -response body within reasonable time, go to step 7. -Step 4: If not, try a HTTP GET with https://<fqdn>/ocm-provider as -the URL instead. -Step 5: If that results in a valid HTTP response with a valid JSON -response body within reasonable time, go to step 7. -Step 6: If not, fail. Implementations MAY fallback to HTTP instead -of HTTPS in testing setups and retry steps 2-5, in particular when +response body within reasonable time, go to step 5. +Step 4: If not, fail. Implementations MAY fallback to HTTP instead +of HTTPS in testing setups and retry steps 2-3, in particular when an optional port is given in the address. -Step 7: The JSON response body is the data that was discovered. +Step 5: The JSON response body is the data that was discovered.
Fields @@ -740,7 +736,7 @@ contain the following information about its OCM API: REQUIRED: enabled (boolean) - Whether the OCM service is enabled at this endpoint REQUIRED: apiVersion (string) - The OCM API version this endpoint -supports. Example: "1.3.0" +supports. Example: "1.4.0" REQUIRED: endPoint (string) - The URI of the OCM API available at this endpoint. Example: "https://cloud.example.org/ocm" OPTIONAL: provider (string) - A friendly branding name of this @@ -769,39 +765,66 @@ of Resources and protocols is optional. Example:
+The protocols object distinguishes a server's role for each +protocol: a property named after the protocol (e.g. webdav, +webapp, ssh) advertises support for acting as a Sending +Server, while a property suffixed with -receive (e.g. +webdav-receive, webapp-receive, ssh-receive) advertises +support for acting as a Receiving Server. Fields: - webdav (string) - The top-level WebDAV [RFC4918] path at this endpoint. In order to access a Remote Resource, implementations SHOULD use this path as a prefix (see sharing examples). -- webapp (string) - The top-level path for web apps at this - endpoint. In order to access a remote web app, implementations - SHOULD use this path as a prefix (see sharing examples). +- webdav-receive (object) - Advertised by implementations that + support receiving WebDAV shares. It contains a uri property + whose value MUST be either "absolute" or "relative", + signalling the URI format this endpoint accepts. Note that + older implementations MAY not support this property. +- webapp (object) - Advertised, as an empty object, by + implementations that support sending WebApp shares. +- webapp-receive (object) - Advertised by implementations that + support receiving WebApp shares. It contains a targets + array listing the ways this endpoint is able to present a + WebApp share to the user. A subset of: + - blank - the endpoint can open the URI in a top-level + browsing context, such as a new window or tab, or a full page + navigation in the current window. + - iframe - the endpoint can embed the URI in an iframe + within its own UI, when the Sending Server allows framing + by this receiver. - ssh (string) - The top-level address in the form host:port of an endpoint that supports ssh and scp with a public/private 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. + 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. OPTIONAL: capabilities (array of string) - The optional capabilities supported by this OCM Server. As implementations MUST accept Share Creation Notifications to be compliant, it is not necessary to expose that as a capability. -Example: ["exchange-token", "webdav-uri"]. The array MAY +Example: ["exchange-token", "protocol-object"]. The array MAY include one or more of the following items: "enforce-mfa" - to indicate that this OCM Server can apply a Sending Server's MFA requirements for a Share on their behalf. - "exchange-token" - to indicate that this OCM Server exposes a -[RFC6749]-compliant endpoint, which allows to exchange a secret -received in the protocol properties of a Share Creation Notification -for a short-lived bearer token. + "exchange-token" - to indicate that this OCM Server supports the +OCM code flow via an [RFC6749]-compliant token endpoint. When this +OCM Server acts as Sending Server, it hosts tokenEndPoint. When it +acts as Receiving Server, it can honor inbound shares that require +token exchange. "http-sig" - to indicate that this OCM Server supports [RFC9421] HTTP Message Signatures and advertises public keys in the format specified by [RFC7517] at the /.well-known/jwks.json @@ -814,9 +837,6 @@ to the more secure (and possibly required) invite flow. notifications to exchange updates on shares and invites. "invite-wayf" - to indicate that this OCM Server exposes a WAYF Page to facilitate the Invite flow. - "webdav-uri" - to indicate that this OCM Server can append a -relative URI to the path listed for WebDAV [RFC4918] in the -appropriate resourceTypes entry "protocol-object" - to indicate that this OCM Server can receive a Share Creation Notification whose protocol object contains one property per supported protocol instead of containing @@ -826,24 +846,27 @@ the standard name and options["http-request-signatures"]. The array MAY include +Example: ["must-use-http-sig"]. The array MAY include for instance: - "http-request-signatures" - to indicate that API requests + "must-use-http-sig" - to indicate that API requests without http signatures will be rejected. - "token-exchange" - to indicate that API requests without -token exchange will be rejected (see the Code Flow -section). + "must-exchange-token" - to indicate that when this OCM Server +acts as Receiving Server, it requires the code flow for all inbound +shares. Shares that do not include must-exchange-token in +the requirements of each protocol offered for access will be +rejected. An +OCM Server advertising this criterium MUST also expose the +exchange-token capability. See the Code Flow +section. "denylist" - some servers MAY be blocked based on their IP address "allowlist" - unknown servers MAY be blocked based on their IP address - "invite" - an invite MUST have been exchanged between the + "must-invite" - an invite MUST have been exchanged between the sender and the receiver before a Share Creation Notification can be sent - DEPRECATED: publicKey (object) - Use public keys at -/.well-known/jwks.json instead for RFC 9421 support. 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 @@ -852,8 +875,10 @@ enhance the UX of the Invite Flow. If for example "/index.php/apps/sciencemesh/accept" is specified here then a WAYF Page SHOULD redirect the end-user to /index.php/apps/sciencemesh/ accept?token=zi5kooKu3ivohr9a&providerDomain=cloud.example.org. - OPTIONAL: tokenEndPoint (string) - URL of the token endpoint where the -Sending Server can exchange a secret for a short-lived bearer token. + OPTIONAL: tokenEndPoint (string) - URL of the token endpoint hosted by +this OCM Server. When this OCM Server acts as Sending Server, the +Receiving Server POSTs here to exchange a sharedSecret for a +short-lived bearer token. Implementations that offer the "exchange-token" capability MUST provide this URL as well. Example: "https://cloud.example.org/ocm/token". @@ -874,6 +899,33 @@ with the fields as described below using httpsig [RFC9421] +Before constructing the notification, the Sending Server MUST query +the Receiving Server's OCM API Discovery endpoint. If the Receiving +Server advertises must-exchange-token in its criteria and the +Sending Server exposes the exchange-token capability with a +tokenEndPoint, the Sending Server MUST include must-exchange-token +in the requirements of each protocol offered for access and MUST NOT +fall back to legacy shared-secret access. If the Receiving +Server advertises must-exchange-token but the Sending Server does +not expose the exchange-token capability or does not have a +tokenEndPoint, the Sending Server MUST NOT create the share, +as the Receiving Server would reject any notification that lacks +the code-flow requirement. +If the Receiving Server does not advertise must-exchange-token in its +criteria, the Sending Server MAY still include must-exchange-token +voluntarily. + +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 +protocol.webapp.sharedSecret before presenting the WebApp to the +browser. If the Sending Server cannot offer this code flow, it MUST NOT +include protocol.webapp in the notification. A Sending Server MAY +serve Web apps either from the same hosting infrastructure or from +external servers in the same organization: to facilitate the integration +of external servers, the RECOMMENDED reference implementation is +described in [OCM-IP]. +
Fields @@ -882,7 +934,7 @@ 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. -Example: "51dc30ddc473d43a6011e9ebba6ca770@geant.org" +Example: "51dc30ddc473d43a6011e9ebba6ca770@cloud.example.org" REQUIRED name (string) Name of the Resource (file or folder). Example: "resource.txt" @@ -898,11 +950,11 @@ Example: 7c084226-d9a1-11e6-bf26-cec0c932ce01 REQUIRED owner (string) - OCM Address of the user who owns the Resource. -Example: "6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl" +Example: "6358b71804dfa8ab069cf05ed1b0ed2a@cloud.example.org" REQUIRED sender (string) - OCM Address of the user that wants to share the Resource. -Example: "527bd5b5d689e2c32ae974c6229ff785@apiwise.nl" +Example: "527bd5b5d689e2c32ae974c6229ff785@cloud.example.org" OPTIONAL ownerDisplayName (string) Display name of the owner of the Resource Example: "Dimitri" @@ -919,8 +971,9 @@ 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. Such exchange is out of -scope for this version of the this specification. +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. @@ -937,9 +990,11 @@ the resource represents a cached copy of a dataset that was made available for an efficient data transfer to the destination server. REQUIRED protocol (object) JSON object with specific options for each protocol. -The supported protocols are: - webdav, to access the data - -webapp, to access remote web applications - ssh, to access -the data via a public/private key pair. +The supported protocols are: + + webdav, to access the data via HTTP WebDAV. + 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. In case a single protocol is offered, there are three ways to specify this object: @@ -967,6 +1022,7 @@ format is deprecated. Warning: client implementers should be aware that v1.1+ servers MAY support both webdav and multi, but v1.0 servers MAY only support webdav. + Protocol details for webdav MAY contain: OPTIONAL accessTypes (array of strings) - The type of access @@ -984,10 +1040,13 @@ cache operations on the Sending Server. The recipient MAY delegate a third-party service to execute the data transfer on their behalf. REQUIRED uri (string) -A URI to access the Remote Resource. The URI -SHOULD be relative, in which case the prefix -exposed by the /.well-known/ocm endpoint MUST -be used. Absolute URIs are deprecated. +A URI to access the Remote Resource. The URI MAY be relative, +such as a key or a UUID, in which case the prefix exposed by the +/.well-known/ocm endpoint MUST be used to access the Resource, +or it MAY be absolute, including a hostname. In all cases, for a +folder Resource, the composed URI acts as the root path, such +that other files located within it MUST be accessible by +appending their relative path to that URI. REQUIRED sharedSecret (string) A secret to be used to access the Resource, such as a bearer token. To prevent leaking it in logs it @@ -1003,14 +1062,16 @@ The permissions granted to the sharee. A subset of: The requirements that the sharee MUST fulfill to access the Resource. A subset of: - must-use-mfa requires the consumer to be MFA-authenticated. -This MAY be used if the recipient provider exposes the -enforce-mfa capability. must-exchange-token requires the recipient to exchange the given sharedSecret via a signed HTTPS request to the Sending Server's {tokenEndPoint} [RFC6749]. +This MAY be used if the Sending Server exposes the +exchange-token capability and tokenEndPoint, and MUST be +included when the Receiving Server advertises must-exchange-token +in criteria. + must-use-mfa requires the consumer to be MFA-authenticated. This MAY be used if the recipient provider exposes the -exchange-token capability. +enforce-mfa capability. OPTIONAL size (integer) The size of the resource to be transferred, useful @@ -1019,22 +1080,70 @@ especially in case of datatx access type. Protocol details for webapp MAY contain: REQUIRED uri (string) -A URI to a client-browsable view of the Shared -Resource, such that users MAY use the web -applications available at the site. The URI SHOULD -be relative, in which case the prefix exposed by -the /.well-known/ocm endpoint MUST be used. -Absolute URIs are deprecated. - REQUIRED viewMode (string) -The permissions granted to the sharee. A subset of: +A URI to a client-browsable view of the Shared Resource, such +that users MAY use a web application available at the Sending +Server. The URI MUST be absolute, including a hostname. In +case the underlying Resource is a folder, the URI MUST act as a +root path, such that files located within the folder are made +accessible in the web app by appending their relative path to +the URI. + REQUIRED targets (array of strings) - How the recipient SHOULD +present the URI to the user. The targets array MUST NOT be +empty. A subset of: + + blank signals the recipient to open the URI in a top-level +browsing context chosen by the receiver, such as a new window or +tab, or a full page navigation in the current window. + iframe signals the recipient to embed the URI in an iframe +within its own UI, when the Sending Server allows framing by +this receiver. +A Sending Server MUST NOT offer a target that the recipient did +not advertise in its webapp-receive discovery property. + + REQUIRED permissions (array of strings) - +The permissions granted to the sharee. MUST NOT be empty. +A subset of: view allows access to the web app in view-only mode. read allows read and download access via the web app. write allows full editing rights via the web app. + share allows re-share rights on the Resource. This only +applies to web apps that provide a mechanism for re-sharing. - OPTIONAL sharedSecret (string) -An optional secret to be used to access the remote -web app, for example in the form of a bearer token. + REQUIRED requirements (array of strings) - +The requirements that the sharee MUST fulfill to +access the Resource. The requirements MUST at least include +must-exchange-token. If multiple protocols are present in the +share payload, the requirements for the different protocols MUST +agree. For example, if a webapp share is sent in the same payload +as a webdav share, both protocols MUST carry the same +requirements, and both requirement arrays MUST include +must-exchange-token. + REQUIRED sharedSecret (string) +A secret for accessing the remote web app. To give access to the +remote app, the receiver MUST first exchange this value at the +Sending Server's {tokenEndPoint} using the Code Flow, then perform +an HTTP POST request to the given uri with the resulting bearer +token in a form field named access_token (see +Resource Access). The shared secret MUST NOT +be exposed to the browser and MUST NOT appear in any URI. + OPTIONAL appName (string) +A human-friendly name of the web application, to be used in user +interfaces when referring to this Share. + OPTIONAL appIconHint (string) +A string in the form of a media type (MIME type) that describes the +share as a whole, primarily intended as a way for the receiving +server to select an appropriate local icon for the share. This is +display metadata and MUST NOT be interpreted as fetchable or +executable content. It does not need to appear in mediaTypes, but +SHOULD describe the primary shared resource. [RFC6838] + OPTIONAL mediaTypes (array of strings) +An array of media types (MIME types) the webapp server can handle. +This can be any media type entries from the IANA Media Type +registry. The receiver MAY use this as a hint for UI or routing +decisions, and MAY ignore values it does not understand. Unlike +appIconHint, this describes formats the webapp can open rather +than the share-level icon hint. [RFC6838] Protocol details for ssh MAY contain: @@ -1126,6 +1235,42 @@ instance a push notification or an email message. share, or add the share automatically and only send an informational 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 + + + to the /request-share path in the Sending Server's OCM API + using application/json as the Content-Type HTTP request +header + its request body containing a JSON document representing an +object with the fields as described below + using TLS + using httpsig [RFC9421] + + +
Fields + + + REQUIRED owner (string) +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. +Example: "51dc30ddc473d43a6011e9ebba6ca770@cloud.example.org" + REQUIRED share (string) +A unique identifier for the resource. +Example: 1234567890abcdef or https://cloud.example.org/files/data.txt + + +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. +
Share Acceptance Notification @@ -1146,7 +1291,7 @@ with the fields as described below using httpsig [RFC9421] -
Fields +
Fields REQUIRED notificationType (string) - in a Share Acceptance @@ -1206,9 +1351,9 @@ to use it, the following steps are to be followed. token for a short-lived bearer token, and only use that bearer token to access the Resource (See the Code Flow section). If the must-exchange-token requirement is not present - and the Discovery endpoint inspected at step 1. exposes the - token-exchange capability, the receiver MAY attempt to perform - the token exchange as above, but it MUST fall back to the following + and the discovery inspected at step 1 exposes the exchange-token + capability with a tokenEndPoint, the receiver MAY attempt the + token exchange as above, but it MUST fall back to the following steps should the process fail. 3.2. If it includes must-use-mfa, the Receiving Server MUST ensure that the Receiving Party has been authenticated with MFA, or prompt @@ -1230,6 +1375,35 @@ this access method, based on Basic Auth, is deprecated and may be removed in a future release of the Protocol. If a secret cannot be identified (e.g. because protocol.options is undefined), then the receiver SHOULD discard the share as invalid. + For the specific case where protocol.webapp is available and the +receiver wants to use it, the receiver MUST present the web app to +the user by opening protocol.webapp.uri using a target selected +from the intersection of protocol.webapp.targets and the targets +advertised in the receiver's webapp-receive discovery property. +If this intersection is empty, the receiver MUST treat the webapp +option as unusable for this Share. If the selected target is +blank, the receiver MAY use _blank or _top according to its +local presentation policy. The receiver MUST inspect +protocol.webapp.requirements: if it includes must-use-mfa, the +Receiving Server MUST ensure that the Receiving Party has been +authenticated with MFA, or prompt the consumer in order to elevate +their session, if applicable. The receiver MUST NOT place the +protocol.webapp.sharedSecret in the URI and MUST NOT expose it to +the browser. Instead, the receiver MUST first exchange it at the +Sending Server's {tokenEndPoint} using the Code Flow, then deliver +the resulting bearer token to the web app via an HTTP POST to +protocol.webapp.uri with the token carried in a form field named +access_token along with another form field named +expired_session_redirect_uri. The +expired_session_redirect_uri value MUST be an absolute HTTPS URI +controlled by the Receiving Server. The Sending WebApp MAY navigate +the browser to this URI when the posted session expires so that the +Receiving Server can restart access and obtain a fresh token; it +MUST NOT place the shared secret or access token in that URI. +Sending WebApps that do not support session refresh MAY ignore this +field. This is typically achieved with an auto-submitting +HTML form whose target attribute selects the chosen +presentation (e.g. an iframe name, _blank, or _top). In all cases, in case the Shared Resource is a folder and the Receiving @@ -1265,11 +1439,11 @@ Content-Type: application/x-www-form-urlencoded Digest: SHA-256=ok6mQ3WZzKc8nb7s/Jt2yY1uK7d2n8Zq7dhl3Q0s1xk= Content-Length: 101 Signature-Input: - sig1=("@method" "@target-uri" "content-digest" "date"); + ocm=("@method" "@target-uri" "content-digest" "date"); created=1730815200; keyid="receiver.example.org#key1"; - alg="rsa-sha256" -Signature: sig1=:bM2sV2a4oM8pWc4Q8r9Zb8bQ7a2vH1kR9xT0yJ3uE4wO5lV6bZ1cP + alg="ed25519" +Signature: ocm=:bM2sV2a4oM8pWc4Q8r9Zb8bQ7a2vH1kR9xT0yJ3uE4wO5lV6bZ1cP 2rN3qD4tR5hC=: grant_type=authorization_code& @@ -1323,6 +1497,67 @@ response with a JSON object containing an OAuth 2.0 error code Permitted error codes are invalid_request, invalid_client, invalid_grant, unauthorized_client and unsupported_grant_type. +
+
Decision Table + +The directional contract depends first on whether the share is strict. +For strict shares, the Receiving Server's advertised behavior determines +whether the Sending Server can require code flow. For non-strict +shares, the Sending Server's advertised behavior determines whether +token exchange is available in addition to legacy access. + + + If the Sending Server includes must-exchange-token in +protocol.webdav.requirements and the Receiving Server exposes the +exchange-token capability, strict token exchange is required +before the Resource is accessed. + If the Sending Server includes must-exchange-token and the +Receiving Server does not expose the exchange-token capability, +the Sending Server SHOULD NOT include that requirement, because the +Receiving Server may be unable to complete the exchange. + If the Sending Server omits must-exchange-token and exposes the +exchange-token capability with a tokenEndPoint, the Receiving +Server MAY attempt token exchange first and MUST fall back to legacy +shared-secret access if that exchange fails. + If the Sending Server omits must-exchange-token and does not +expose the exchange-token capability, only legacy shared-secret +access is available. + + +The following examples illustrate typical end-to-end outcomes: + + + Strict required code flow: Provider A acts as Sending Server and +exposes the exchange-token capability with a tokenEndPoint. +Provider B acts as Receiving Server and advertises both +exchange-token and must-exchange-token. After discovering B's +must-exchange-token criteria, A MUST include must-exchange-token +in protocol.webdav.requirements. B MUST exchange the +sharedSecret at A's tokenEndPoint and then use only the bearer +token to access the Resource. + Optional exchange with fallback: Provider A acts as Sending Server +and exposes the exchange-token capability with a tokenEndPoint. +Provider B does not advertise must-exchange-token, so A sends a +share without must-exchange-token. When B later accesses the +Resource, it MAY attempt the token exchange at A's tokenEndPoint, +but if that exchange fails it MUST fall back to the legacy +sharedSecret. + Legacy share to a code-flow-capable peer: Provider A does not +expose the exchange-token capability. Provider B does expose +exchange-token, so B is capable of honoring strict inbound shares +from other peers. Because A does not advertise a tokenEndPoint, +A can only send a legacy share and B can only use legacy +shared-secret access for that share. + Asymmetric role behavior: Provider A exposes exchange-token and +must-exchange-token, so it can require code flow for inbound +shares when it acts as Receiving Server. When A later acts as +Sending Server toward Provider B, and B does not advertise +must-exchange-token, A MAY omit must-exchange-token. B may then +attempt token exchange against A's tokenEndPoint or fall back to +legacy access. A therefore accepts strict inbound shares while +still choosing a legacy-compatible outbound share. + +
Share Deletion @@ -1364,7 +1599,7 @@ a Resource without an explicit grant from the Sending Server.
Well-Known URI for the Discovery The following value is to be registered in the "Well-Known URIs" -registry (using the template from [RFC5785]): +registry (using the template from [RFC8615]): URI suffix: ocm Change controller: IETF Specification document(s): the present Draft, once in RFC form @@ -1389,7 +1624,7 @@ registry (using the template from [RFC9553]): "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. + 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 @@ -1410,7 +1645,7 @@ registry (using the template from [RFC9553]): Change Controller: IETF Reference or Description: -A map of OCM addresses for a contact. The keys are arbitrary +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. @@ -1451,7 +1686,7 @@ Values" registry (using the template from [RFC9553]). There are several areas that are not covered by this specification. Most importantly we do not provide a way of establishing trust between servers, even though some features of the protocol rely on trust, such -as the mfa-enforced requirement. +as the must-use-mfa requirement. Trust needs to be established out of band, but there are some features of the protocol that can be used to assist operators in establishing @@ -1486,6 +1721,15 @@ confidential and never logged, persisted beyond their lifetime, or transmitted over unsecured channels.
+
+
Copying conditions + +The author(s) agree to grant third parties the irrevocable right to +copy, use and distribute the work, with or without modification, in +any medium, without royalty, provided that, unless separate permission +is granted, redistributed modified works do not contain misleading +author, version, name of work, or endorsement information. +
References @@ -1505,6 +1749,10 @@ June 2007. [RFC6749] Hardt, D. (ed), "The OAuth 2.0 Authorization Framework", October 2012. +[RFC6838] Freed, N., Klensin, J., Hansen, T. "Media Type +Specifications and Registration Procedures +", January 2013. + [RFC7515] Jones, M., Bradley, J., Sakimura, N., "JSON Web Signature (JWS)", May 2015. @@ -1522,9 +1770,24 @@ Key Words", May 2017. [RFC9421] Backman, A., Richer, J. and Sporny, M. "HTTP Message Signatures", February 2024. +[RFC9530] Polli, R., Marwood, D., "Digest Fields", February 2024. + [RFC9553] Stepanek, R., Loffredo, M., "JSContact: A JSON Representation of Contact Data, May 2024" +
+
Informative References + +[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 +Security", +Work in Progress, Internet-Draft. +
Appendix A: Multi-factor Authentication @@ -1532,10 +1795,10 @@ Representation of Contact Data, May 2024" If a Receiving Server exposes the capability enforce-mfa, it indicates that it will try and comply with a MFA requirement set on a Share. If the Sending Server trusts the Receiving Server, the Sending -Server MAY set the requirement mfa-enforced on a Share, which the +Server MAY set the requirement must-use-mfa on a Share, which the Receiving Server MUST honor. A compliant Receiving Server that signals that it is MFA-capable MUST NOT allow access to a Resource protected -with the mfa-enforced requirement, if the Receiving Party has not +with the must-use-mfa requirement, if the Receiving Party has not provided a second factor to establish their identity with greater confidence. @@ -1612,27 +1875,72 @@ breaks in @signature-params for display purposes only): "@method": POST "@target-uri": https://receiver.example.org/ocm/shares -"content-digest": sha-256=:[digest-value]=: -"@signature-params": ("@method" "@target-uri" "content-digest"); +"content-digest": sha-256=:[digest-value]: +"content-length": [body-length] +"date": [date] +"@signature-params": ("@method" "@target-uri" "content-digest" + "content-length" "date"); created=[timestamp]; keyid="sender.example.org#key1"; alg="ed25519" Sign this base using for example Ed25519 ([RFC8032]) to produce the -signature, then add headers (line breaks for display purposes only): +signature, using the ocm label, and then add headers (line breaks +for display purposes only): -Signature-Input: sig1=("@method" "@target-uri" "content-digest"); +Content-Digest: sha-256=:[digest-value]: +Content-Length: [body-length] +Date: [date] +Signature-Input: ocm=("@method" "@target-uri" "content-digest" + "content-length" "date"); created=[timestamp]; keyid="sender.example.org#key1"; alg="ed25519" -Signature: sig1=:[signature-value]=: +Signature: ocm=:[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. +
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: @@ -1640,6 +1948,8 @@ Signature: sig1=:[signature-value]=: 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 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 @@ -1698,11 +2008,11 @@ Example: "federation": "The ScienceMesh Directory", "servers": [ { - "url": "https://ocm-server-1.example.org", + "url": "https://ocm-server.example.org", "displayName": "OCM Server 1" }, { - "url": "https://ocm-server-2.example.org:4443", + "url": "https://ocm-server.example.com:4443", "displayName": "OCM Server 2" }, { @@ -1711,7 +2021,7 @@ Example: } ] }, - "protected": {"alg": "RS256"}, + "protected": {"alg": "ES256"}, "signature": "..." } ]]> @@ -1871,7 +2181,7 @@ implementor might find it useful to have a Provider object model to store the discovered information about federation peers or other remote OCM Providers. -The following diagram is illustrative and non-exhaustive. The single +The following diagram is illustrative and non-exhaustive. The single source of truth for Provider properties is the OCM API Discovery Fields section; for the box contents below, see the Properties subsection and the normative capability, criteria, and resource type definitions in @@ -1887,7 +2197,6 @@ that section. | - endPoint | | - inviteAcceptDialog | | - provider | - | - publicKey | | - tokenEndPoint | | - ... | +-----------------------+ @@ -1906,7 +2215,6 @@ that section. | - ... | | - invites | | +------------------+ | - notifications | | | | - protocol-object| | - | | - webdav-uri | | | | - ... | | | +------------------+ | | | @@ -1918,9 +2226,9 @@ that section. | +--------------------------+ | | - allowlist | | | - denylist | - | | - http-request-signatures| - | | - invite | - | | - token-exchange | + | | - must-use-http-sig | + | | - must-invite | + | | - must-exchange-token | | | - ... | | +--------------------------+ | @@ -1930,8 +2238,11 @@ that section. | Protocols | +------------------+ | - ssh | +| - ssh-receive | | - webapp | +| - webapp-receive | | - webdav | +| - webdav-receive | | - ... | +------------------+ ]]> @@ -1945,7 +2256,6 @@ that section. enabled: Boolean indicating if OCM service is active endPoint: Base URI for OCM API endpoints provider: Friendly branding name - publicKey: Optional public key for HTTP signatures resourceTypes: Array of supported resource types with protocols @@ -2125,6 +2435,30 @@ 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 05 + + Introduced a /request-share endpoint to request a user of an +OCM server to share a resource. + Refactored the webapp protocol to align it to the new security +standard, by means of POST requests and the Code Flow. + Introduced new <protocol>-receive protocols in the Discovery +endpoint, to signal the ability to receive an OCM share carrying +that protocol. + Introduced new Internet-Draft specifications to cover optional +parts of the protocol related to webapp integrations and federated +groups. + Renamed some requirements and criteria to improve consistency. + On a Share Creation Notification, made the sharedSecret +a required parameter for all protocol payloads that specify it. + Fixed all example URIs to use example.org across the spec. + Improved the JWKS-related text and fixed obsoleted references. + Removed the already deprecated /ocm-provider endpoint and the +draft-cavage public key advertisement in the OCM Discovery endpoint +as all known implementations have migrated to the recommended +alternatives. + + +
Version 04 Clarified that the diagrams in Appendix D are illustrative and @@ -2146,7 +2480,6 @@ not normative.
Version 01 - Introduced functions, roles, and object models to the specification. Added support for SSH as a share access method. @@ -2195,11 +2528,32 @@ Andreas Klotz, Matthias Knoll, Christian Kracher, Mario Lassnig, Claudius Laumanns, Anthony Leroy, Patrick Maier, Vladislav Makarenko, Anna Manou, Rita Meneses, Zheng Meyer-Zhao, Crystal Michelle Chua, Yoann Moulin, Daniel Müller, Frederik Müller, Rasmus Munk, -Michał Orzechowski, Jacek Pawel Kitowski, Iosif Peterfi, -Alessandro Petraro, Rene Ranger, Angelo Romasanta, David Rousse, -Carla Sauvanaud, Klaus Scheibenberger, Marcin Sieprawski, +Michał Orzechowski, Jacek Pawel Kitowski, Enrique Pérez Arnaud, Iosif +Peterfi, Alessandro Petraro, Rene Ranger, Angelo Romasanta, David +Rousse, Carla Sauvanaud, Klaus Scheibenberger, Marcin Sieprawski, Tilo Steiger, C.D. Tiwari, Alejandro Unger and Tom Wezepoel. +Work on this document has been partially funded over the years by +multiple projects and funding agencies: + + + The CS3MESH4EOSC project "Interactive and agile/responsive +sharing mesh of storage, data and applications for EOSC", whose key +result was Science Mesh, received funding from the +European Union's Horizon 2020 research and innovation programme under +Grant Agreement no. 863353. + NLnet through the NGI0 Core Fund, with +financial support from the European Commission's +Next Generation Internet programme under grant agreement +No. 101092990. + The EOSC Data Commons project "Services for inter- and +cross-disciplinary data discovery, access, sharing and reuse in the +EOSC Federation", received funding from the European Union under Grant +Agreement no. 101188179. + Sovereign Tech Agency through the Tech Fund, with +a specific project. + +
@@ -2217,576 +2571,691 @@ Tilo Steiger, C.D. Tiwari, Alejandro Unger and Tom Wezepoel.