Open Cloud Mesh

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

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

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

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

3.5. Invite Flow

### Rationale Many methods for establishing contact allow unsolicited contact with the prospective Receiving Party whenever that party's OCM Address is known. The Invite Flow requires the Receiving Party to explicitly accept it before it can be used, which establishes bidirectional trust between the two parties involved.¶

OCM Servers MAY enforce a policy to only accept Shares between such trusted contacts, or MAY display a warning to the Receiving Party when a Share Creation Notification from an unknown Sending Party is received¶

4.1. 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 @ sign). Step 2: The Discovering Server SHOULD attempt OCM API discovery 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 8. 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 8. Step 6: If not, fail. Step 7: The JSON response body is the data that was discovered.¶

4.2. 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.1.0"¶

• 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, folder, calendar, contact, ...). Implementations MUST support file at a minimum. 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 MUST support at least webdav for file resources, 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 path at this endpoint. In order to access a remote shared 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 SHALL NOT be intended as a prefix for share requests.¶

    • datatx (string) - The top-level path to be used for data transfers. This value is provided for documentation purposes, and it SHALL NOT be intended as a prefix. In addition, implementations are expected to execute the transfer using WebDAV 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 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.¶

• 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 id (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-----\nMII...QDD\n-----END PUBLIC KEY-----\n"¶

5.1. Fields

• REQUIRED shareWith (string) Consumer specific identifier of the user, group or federation the provider wants to share the resource with. This is known in advance. Please note that the consumer service endpoint is known in advance as well, so this is no part of the request body. 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) - Provider specific identifier of the user who owns the resource. Example: "6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl"¶

• REQUIRED sender (string) - Provider specific identifier of the user that wants to share the resource. Please note that the requesting provider is being identified on a higher level, so the former remote property is not part of the request body. 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 indicated 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, folder, 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 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:¶

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

  • OPTIONAL uri (string) An URI to access the remote resource. The URI MAY be relative, in which case the prefix exposed by the /ocm-provider endpoint MUST be used, or it may be absolute (recommended). Additionally, the URI MAY include a secret hash in the path, in which case there MAY be no associated sharedSecret.¶

• Protocol details for webapp MAY contain:¶

  • REQUIRED uriTemplate (string) A templated URI to a client-browsable view of the shared resource, such that users may use the web applications available at the site. The URI MAY include a secret hash in the path. If the path includes a {relative-path-to-shared-resource} placeholder, implementations MAY replace it with the actual path to ease user interaction.¶

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

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

  • REQUIRED srcUri (string) An URI to access the remote resource. The URI MAY be relative, in which case the prefix exposed by the /ocm-provider endpoint MUST be used, or it may be absolute (recommended). Additionally, the URI MAY include a secret hash in the path.¶

  • OPTIONAL size (integer)¶

5.2. Decision to Discard

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

• 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 accessed through (any of) the protocol(s) listed¶

7.1. Fields

• REQUIRED notificationType (string) - in a Share Acceptance Notification it SHOULD 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¶

13.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 = {
    '(request-target)': 'post /path',
    'content-length': length_of(payload),
    'date': current_gmt_datetime(),  # Use a function to get the current GMT date as 'D, d M Y H:i:s T'
    '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; find its public key through OCM API discovery
    'algorithm': 'rsa-sha256',
    'headers': 'content-length date digest host',
    'signature': signed,
}

headers['Signature'] = format_signature(signature)

clear = {
    '(request-target)': 'post /path',
    'content-length': length_of(payload),
    'date': 'Mon, 08 Jul 2024 14:16:20 GMT',  # The date used in the verification process
    'digest': 'SHA-256=' + base64_encode(hash('sha256', utf8_encode(payload))),  # Recompute the 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

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