Open Cloud Mesh

4.1. Direct Entry

The simplest way for this is if the Receiving Party shares their OCM Address with the Sending Party through some out-of-band means, and the Sending Party enters this string into the user interface of the Sending Server, by means of typing or pasting into an HTML form, or clicking a link to a URL that includes the string in some form.¶

4.2. Address books

The Sending Server MAY offer the Sending Party an address book tool, where OCM Addresses can be stored over time in a labeled and/or searchable way. This decouples the act by which the OCM Address string is passed into the Sending Server's database from the selection of the Receiving Party in preparation for Share Creation.¶

4.3. Public Link Flow

An interface for anonymously viewing a Resource on the Sending Server MAY allow any internet user to type or paste an OCM address into an HTML form, as a Sending Gesture. This means that the Sending Party and the Receiving Party could be the same person, so contact between them does not need to be explicitly established.¶

4.4. Public Invite Flow

Similarly, an interface on the Sending Server MAY allow any internet user to type or paste an OCM address into an HTML form, as a Sending Gesture for a given Resource, without itself providing a way to access that particular Resource. A link to this interface could then for instance be shared on a mailing list, allowing all subscribers to effectively request access to the Resource by making a Sending Gesture to the Sending Server with their own OCM Address.¶

4.5. Invite Flow

5.1. Introduction

After establishing contact as discussed in the previous section, the Sharing User MAY send the Share Creation Gesture to the Sending Server. The Sharing User MUST provide the following information:¶

• Resource to be shared¶

• Protocol to be offered for access¶

• Sending Party's identifier¶

• Receiving Party's identifier¶

• Receiving Server FQDN¶

• OPTIONAL: Share Requirements¶

• OPTIONAL: Share Name¶

• OPTIONAL: Share Permissions¶

The next step is for the Sending Server to additionally discover:¶

• if the Receiving Server is trusted¶

• if the Receiving Server supports OCM¶

• if so, which version and with which optional functionality¶

• at which URL¶

• the public key the Receiving Server will use for HTTP Signatures (if any)¶

The Sending Server MAY first perform denylist and allowlist checks on the FQDN.¶

If a finite allowlist of Receiving Servers exists on the Sending Server side, then this list MAY already contain all necessary information.¶

If the FQDN passes the denylist and/or allowlist checks, but no details about its OCM API are known, the Sending Server can use the following process to try to fetch this information from the Receiving Server.¶

This process MAY be influenced by a VPN connection and/or IP allowlisting.¶

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'.¶

5.2. Process

At the start of the process, the Discovering Server has either an OCM Address, or just an FQDN from for instance the recipientProvider field of an Invite Acceptance Request.¶

Step 1: In case it has an OCM Address, it SHOULD first extract <fqdn> 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. Step 7: The JSON response body is the data that was discovered.¶

5.3. Fields

The JSON response body offered by the Discoverable Server SHOULD contain the following information about its OCM API:¶

• REQUIRED: enabled (boolean) - Whether the OCM service is enabled at this endpoint¶

• REQUIRED: apiVersion (string) - The OCM API version this endpoint supports. Example: "1.2.1"¶

• REQUIRED: endPoint (string) - The URI of the OCM API available at this endpoint. Example: "https://my-cloud-storage.org/ocm"¶

• OPTIONAL: provider (string) - A friendly branding name of this endpoint. Example: "MyCloudStorage"¶

• REQUIRED: resourceTypes (array) - A list of all resource types this server supports in both the Sending Server role and the Receiving Server role, with their access protocols. Each item in this list SHOULD itself be an object containing the following fields:¶

  • name (string) - A supported resource type (file, 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.¶

  • shareTypes (array of string) - The supported recipient share types. MUST contain "user" at a minimum, plus optionally "group" and "federation". Example: ["user"]¶

  • protocols (object) - The supported protocols for accessing Shared Resources of this type. Implementations that offer file Resources MUST support at least webdav, any other combination of Resources and protocols is optional. Example: json { "webdav": "/remote/dav/ocm/", "webapp": "/app/ocm/", "talk": "/apps/spreed/api/" } Fields:¶

    • webdav (string) - The top-level WebDAV [RFC4918] path at this endpoint. In order to access a Remote Resource, implementations MAY use this path as a prefix, or as the full path (see sharing examples).¶

    • webapp (string) - The top-level path for web apps at this endpoint. This value is provided for documentation purposes, and it SHOULD NOT be intended as a prefix for share requests.¶

    • datatx (string) - The top-level path used for data transfers. This value is provided for documentation purposes, and it SHOULD NOT be intended as a prefix. In addition, implementations are expected to execute the transfer using WebDAV [RFC4918] as the wire protocol.¶

    • 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.¶

• 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: ["receive-code", "webdav-uri"]. The array MAY include for instance: _ "enforce-mfa" - to indicate that this OCM Server can apply a Sending Server's MFA requirements for a Share on their behalf. _ "webdav-uri" - to indicate that this OCM Server can append a relative URI to the path listed for WebDAV [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 the standard name and options properties. _ "invites" - to indicate the server would support acting as an Invite Sender or Invite Receiver OCM Server. This might be useful for suggesting to a user that existing contacts might be upgraded to the more secure (and possibly required) invite flow. _ "receive-code" - to indicate that this OCM Server can receive a code as part of a Share Creation Notification, and exchange it for a bearer token at the Sending Server's /token API endpoint. _ "invite-wayf" - to indicate that this OCM Server exposes a WAYF Page to facilitate the Invite flow.¶

• OPTIONAL: criteria (array of string) - The criteria for accepting a Share Creation Notification. As all Receiving Servers SHOULD require the use of TLS in API calls, it is not necessary to expose that as a criterium. Example: ["http-request-signatures", "code"]. The array MAY include for instance: _ "http-request-signatures" - to indicate that API requests without http signatures will be rejected. _ "code" - to indicate that API requests without code will be rejected (i.e. the sharedSecret in the protocol details will be ignored). _ "denylist" - some servers MAY be blocked based on their IP address _ "allowlist" - unknown servers MAY be blocked based on their IP address * "invite" - an invite MUST have been exchanged between the sender and the receiver before a Share Creation Notification can be sent¶

• OPTIONAL: publicKey (object) - The signatory used to sign outgoing request to confirm its origin. The signatory is optional, but if present, it MUST contain two string fields, id and publicKeyPem. properties:¶

  • REQUIRED keyId (string) unique id of the key in URI format. The hostname set the origin of the request and MUST be identical to the current discovery endpoint. Example: https://my-cloud-storage.org/ocm#signature¶

  • REQUIRED publicKeyPem (string) - PEM-encoded version of the public key. Example: "----BEGIN PUBLIC KEY----\n...\n----END PUBLIC KEY----\n"¶

• 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 "invites" capability SHOULD provide this URL as well in order to 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=example.com.¶

6.1. Fields

• 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. Example: "51dc30ddc473d43a6011e9ebba6ca770@geant.org"¶

• REQUIRED name (string) Name of the Resource (file or folder). Example: "resource.txt"¶

• OPTIONAL description (string) Optional description of the Resource (file or folder). Example: "This is the Open API Specification file (in YAML format) of the Open Cloud Mesh API."¶

• REQUIRED providerId (string) Identifier to identify the Shared Resource at the provider side. This is unique per provider such that if the same Resource is shared twice, this providerId will not be repeated. Example: 7c084226-d9a1-11e6-bf26-cec0c932ce01¶

• REQUIRED owner (string) - OCM Address of the user who owns the Resource. Example: "6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl"¶

• REQUIRED sender (string) - OCM Address of the user that wants to share the Resource. Example: "527bd5b5d689e2c32ae974c6229ff785@apiwise.nl"¶

• OPTIONAL ownerDisplayName (string) Display name of the owner of the Resource Example: "Dimitri"¶

• OPTIONAL senderDisplayName (string) 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 Servers, or a group of users that is spread out over various servers, including at least one user at the Receiving Server.¶

• REQUIRED resourceType (string) Resource type (file, calendar, contact, ...)¶

• 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 share does not expire.¶

• OPTIONAL code (string) A nonce to be exchanged for a (potentially short-lived) bearer token at the Sending Server's /token endpoint.¶

• 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 - datatx, to transfer the data to the remote endpoint.¶

      Other custom protocols might be added in the future.
  
      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,
      and put the protocol details in a field named `options`.
      Option 2: Set the `name` field to the name of the protocol,
      and put the protocol details in a field carrying the name of
      the protocol.
      Option 3: Set the `name` field to `multi`, and put the
      protocol details in a field carrying the name of the protocol.
  
            Option 1 using the `options` field is now deprecated.
            Implementations are encouraged to transition to the new
            optional properties defined below, such that this field
            may be removed in a future major version of the spec.
  
      When specifying more than one protocol as different ways to
      access the Share, the `name` field needs to be set to `multi`.
  

  ¶

If multi is given, one or more protocol endpoints are expected to be defined according to the optional properties specified below. Otherwise, at least webdav is expected to be supported, and its options MAY be given in the opaque options payload for compatibility with v1.0 implementations (see examples). Note though that this 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:¶

  • 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.¶

  • OPTIONAL sharedSecret (string) - REQUIRED if no code field is given for the Share as a whole (see above). An optional secret to be used to access the Resource, such as a bearer token. To prevent leaking it in logs it MUST NOT appear in any URI.¶

  • OPTIONAL permissions (array of strings) - The permissions granted to the sharee. A subset of: - read allows read-only access including download of a copy. - write allows create, update, and delete rights on the Resource. - share allows re-share rights on the Resource.¶

  • OPTIONAL requirements (array of strings) - The requirements that the sharee MUST fulfill to access the Resource. A subset of: - mfa-enforced requires the consumer to be MFA-authenticated. This MAY be used if the recipient provider exposes the enforce-mfa capability. - use-code requires the consumer to exchange the given code via a signed HTTPS request. This MAY be used if the recipient provider exposes the receive-code capability.¶

• 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: - 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.¶

  • OPTIONAL sharedSecret (string) An optional secret to be used to access the remote web app, for example in the form of a bearer token.¶

• Protocol details for datatx MAY contain:¶

  • REQUIRED srcUri (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.¶

  • OPTIONAL sharedSecret (string) An optional secret to be used to access the Resource, for example in the form of a bearer token. To prevent leaking it in logs it MUST NOT appear in any URI.¶

  • OPTIONAL size (integer) The size of the file to be transferred from the sending server.¶

6.2. Decision to Discard

The Receiving Server MAY discard the notification if any of the following hold true:¶

• the HTTP Signature is missing but the Sending Server does expose a keypair discoverable from the FQDN part of the sender field in the request body¶

• the HTTP Signature is missing¶

• the HTTP Signature is not valid¶

• no keypair is trusted or discoverable from the FQDN part of the sender field in the request body¶

• the keypair used to generate the HTTP Signature doesn't match the one trusted or discoverable from the FQDN part of the sender field in the request body¶

• the Sending Server is denylisted¶

• the Sending Server is not allowlisted¶

• the Sending Party is not trusted by the Receiving Party (e.g., no Invite was exchanged and/or the Sending Party's OCM Address does not appear in the Receiving Party's address book)¶

• the Receiving Server is unable to act as an API client for (any of) the protocol(s) listed for accessing the Resource¶

• an initial check shows that the Resource cannot successfully be accessed through (any of) the protocol(s) listed¶

8.1. Fields

• REQUIRED notificationType (string) - in a Share Acceptance Notification it MUST be one of:¶

  • 'SHARE_ACCEPTED'¶

  • 'SHARE_DECLINED'¶

• REQUIRED providerId (string) - copied from the Share Creation Notification for the Share this notification is about¶

• OPTIONAL resourceType (string) - copied from the Share Creation Notification for the Share this notification is about¶

• OPTIONAL notification (object) - optional additional parameters, depending on the notification and the resource type¶

For example, a notification MAY be sent by a recipient to let the provider know that the recipient declined a share. In this case, the provider site MAY mark the share as declined for its user(s). Similarly, it MAY be sent by a provider to let the recipient know that the provider removed a given share, such that the recipient MAY clean it up from its database. A notification MAY also be sent to let a recipient know that the provider removed that recipient from the list of trusted users, along with any related share. The recipient MAY reciprocally remove that provider from the list of trusted users, along with any related share.¶

Notifications from Sending Server to Receiving Server SHOULD use httpsig [RFC9421] so the Receiving Server can authenticate the origin of the notification. Receiving Servers SHOULD decline notifications from Sending Servers without httpsig as it can't identify where the notification is coming from.¶

14.1. Trust

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.¶

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 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.¶

14.2. Legacy shared secrets

The legacy format of an OCM Share Notification with shared secrets is only provided for backwards compatibility with existing implementations. Implementers SHOULD NOT use it and prefer short-lived tokens instead.¶

15.1. Normative References

[RFC2119] Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels", March 1997.¶

[RFC4918] Dusseault, L. M. "HTTP Extensions for Web Distributed Authoring and Versioning", June 2007.¶

[RFC8174] Leiba, B. "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", May 2017.¶

[RFC9421] Backman, A., Richer, J. and Sporny, M. "HTTP Message Signatures", February 2024.¶

15.2. Informative References

[RFC6749] Hardt, D. (ed), "The OAuth 2.0 Authorization Framework", October 2012.¶

17.1. How to generate the Signature for outgoing request

After properties are set in the headers, the Signature is generated and added to the list.¶

This is a pseudo-code example for generating the Signature header for outgoing requests:¶

``` headers = { 'content-length': length_of(payload), # Use a function to get the current GMT date as 'D, d M Y H:i:s T' 'date': current_gmt_datetime(), 'content-digest': 'SHA-256=' + base64_encode(hash('sha256', utf8_encode(payload))), 'host': 'recipient-fqdn', }¶

signed = ssl_sign(concatenate_with_newlines(headers), private_key, 'sha256') signature = { 'keyId': 'sender.fqdn', # The sending server's FQDN 'algorithm': 'rsa-sha256', 'headers': 'content-length date content-digest host', 'signature': signed, }¶

headers['Signature'] = format_signature(signature) ```¶

17.2. How to confirm Signature on incoming request

The first step would be to confirm the validity of each properties:¶

• content-length and content-digest can be regenerated and compared from the payload of the request,¶

• a maximum TTL MUST be applied to date and current timestamp,¶

• regarding data contained in the Signature header:¶

  • using keyId to get the public key from remote signatory,¶

  • headers is used to generate the clear version of the signature and MUST contain at least content-length, date, content-digest and host,¶

  • signature is the encrypted version of the signature.¶

Here is an example of how to verify the signature using the headers, the signature and the public key:¶

``` clear = { 'content-length': length_of(payload), 'date': 'Mon, 08 Jul 2024 14:16:20 GMT', 'content-digest': 'SHA-256=' + base64_encode(hash('sha256', utf8_encode(payload))), # Recompute digest for verification 'host': 'sender-fqdn', }¶

signed = headers['Signature'] verification_result = ssl_verify(concatenate_with_newlines(clear), signed, public_key, 'sha256')¶

if not verification_result then raise InvalidSignatureException ```¶

17.3. Validating the payload

Following the validation of the signature, the host SHOULD also confirm the validity of the payload, that is ensuring that the actions implied in the payload actually initiated on behalf of the source of the request.¶

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.¶