OCM-API

title: ‘Open Cloud Mesh’ docname: draft-lopresti-open-cloud-mesh-00 category: std

ipr: trust200902 area: Security keyword: Internet-Draft

stand_alone: yes

author:

— abstract

Open Cloud Mesh is a server federation protocol that is used to notify a Receiving Party that they have been granted access to some Resource. It has similarities with authorization flows such as OAuth, as well as with social internet protocols such as ActivityPub and email.

Open Cloud Mesh only handles the necessary interactions up to the point where the Receiving Party is informed that they were granted access to the Resource. The actual resource access is then left to protocols such as WebDAV and others.

— middle

Terms

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

We define the following concepts (with some non-normative references to related concepts from OAuth and elsewhere):

General Flow

The lifecycle of an Open Cloud Mesh Share starts with prerequisites such as establishing trust, establishing contact, and OCM API discovery.

Then the share creation involves the Sending Party making a Sending Gesture to the Sending Server, the Sending Server carrying out the actual Share Creation, and the Sending Server sending a Share Creation Notification to the Receiving Server.

After this, the Receiving Server MAY notify the Receiving Party and/or the Sending Server, and will act as an API client through which the Receiving Party can access the Resource. After that, the Share may be updated, deleted, and/or reshared.

Establishing Contact

Before the Sending Server can send a Share Creation Notification to the Receiving Server, it needs to establish the Receiving Party’s OCM Address (containing the Receiving Server’s FQDN, and the Receiving Party’s identifier), among other things. Some steps may preceed the Sending Gesture, allowing the Sending Party to establish (with some level of trust) the OCM Address of the Receiving Party. In other cases, establishing the OCM Address of the Receiving Party happens as part of the Sending Gesture.

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.

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.

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.

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.

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

Steps

Invite Acceptance Request Details

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:

The Invite Receiver OCM Server SHOULD apply its own policies for trusting the Invite Sender OCM Server before making the Invite Acceptance Request.

Since the Invite Flow does not require either Party to type or remember the userID, this string does not need to be human-memorable. Even if the Invite Receiver has a memorable username at the Invite Receiver OCM Server, this userID that forms part of their OCM Address does not need to match it.

Also, a different userID could be given out to each contact, to avoid correlation of identities.

Invite Acceptance Response Details

The Invite Acceptance Response SHOULD be a HTTP response:

A 200 response status means the Invite Acceptance Request was successful. A 400 response status means the Invite Token is invalid or does not exist. 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.

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 the Invite Sender’s username at their OCM Server.

Addition into address books

Following these step, both servers MAY display the name of the other party as a trusted or allowlisted contact, and enable selecting them as a Receiving Party. OCM Servers MAY enforce a policy to only accept Share Creation Notifications from such trusted contacts, or MAY display a warning to users when a Share Creation Notification from an unknown party is received.

Both servers MAY also allowlist each other as a server with which at least one of their users wishes to interact.

Note that Invites act symmetrically, so once contact has been established, both the Invite Sender and the Invite Receiver may take on either the Sending Party or the Receiving Party role in subsequent Share Creation events.

Both parties may delete the other party from their address book at any time without notifying them.

Security Advantages

It is important to underscore the value of the Invite in this scenario, as it provides four important security advantages. First of all, if the Receiving Server blocks Share Creation Notifications from Sending Parties who are not in the address book of the Receiving Party, then this protects the Receiving Party from receiving unsolicited Shares. An attacker could still send the Receiving Party an unsolicited Share, but they would first need to convince the Receiving Party through an out-of-band communication channel to accept their invite. In many use cases, the Receiving Party has had other forms of contact with the Sending Party (e.g. in-person or email back-and-forth). The out-of-band Invite Message thus leverages the filters and context which the Receiving Party may already benefit from in that out-of-band communication. For instance, a careful Receiving Party may choose to only accept Invites that reach them via a private or moderated messaging platform.

Second, when the Receiving Party accepts the Invite, the Receiving Server knows that the Sending Server they are about to interact with is trusted by the Sending Party, which in turn is trusted by the Receiving Party, which in turn is trusted by them. In other words, one of their users is requesting the allowlisting of a server they wish to interact with, in order to interact with a party they know out-of-band. This gives the Receiving Server reason to put more trust in the Sending Server than it would put into an arbitrary internet-hosted server.

Third, equivalently, the Sending Server knows it is essentially registering the Receiving Server as an API client at the request of the Receiving Party, to whom the right to request this has been traceably delegated by the Sending Party, which is one of its registered users.

Fourth, related to the second one, it removes the partial ‘open relay’ problem that exists when the Sending Server is allowed to include any Receiving Server FQDN in the Sending Gesture. Without the use of Invites, a Distributed Denial of Service attack could be organised if many internet users collude to flood a given OCM Server with Share Creation Notifications which will be hard to distinguish from legitimate requests without human interaction. An unsolicited (invalid) Invite Acceptance Request is much easier to filter out than an unsolicited (possibly valid, possibly invalid) Share Creation Notification Request, since the Invite Acceptance Request needs to contain an Invite Token that was previously uniquely generated at the Invite Sender OCM server.

OCM API Discovery

Introduction

After establishing contact as discussed in the previous section, the Sharing User can send the Share Creation Gesture to the Sending Server, providing the Sending Server with the following information:

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

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

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.

Fields

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

Share Creation Notification

To create a share, the sending server SHOULD make a HTTP POST request

Fields

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.

Decision to Discard

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

Receiving Party Notification

If the Share Creation Notification is not discarded by the Receiving Server, they MAY notify the Receiving Party passively by adding the Share to some inbox list, and MAY also notify them actively through for instance a push notification or an email message.

They could give the Receiving Party the option to accept or reject the share, or add the share automatically and only send an informational notification that this happened.

Share Acceptance Notification

In response to a Share Creation Notification, the Receiving Server MAY discover the OCM API of the Sending Server, starting from the <fqdn> part of the sender field in the Share Creation Notification.

If the OCM API of the Sending Server is successfully discovered, the Receiving Server MAY make a HTTP POST request

Fields

Receiving Party Notification

If the Share Creation Notification is not discarded by the Receiving Server, they MAY notify the Receiving Party passively by adding the Share to some inbox list, and MAY also notify them actively through for instance a push notification or an email message.

They could give the Receiving Party the option to accept or reject the Share, or add the Share automatically and only send an informational notification that this happened.

Resource Access

To access the Resource, the Receiving Server MAY use multiple ways, depending on the body of the Share Creation Notification. The procedure is as follows:

  1. A root path <sender-ocm-path> MUST be obtained by querying the Discovery endpoint at the Sending Server and getting resourceTypes[0].protocols.webdav.
  2. If code is not empty, the receiver SHOULD make a signed POST request to the /token path inside the Sending Server’s OCM API, to exchange the code for a short-lived bearer token, and then use that bearer token to access the Resource.
  3. If protocol.name = webdav, the receiver SHOULD inspect the protocol.options property. If it contains a sharedSecret, as in the legacy example, then the receiver SHOULD make a HTTP PROPFIND request to https://<sharedSecret>:@<sender-host><sender-ocm-path>. Note that this access method, based on Basic Auth, is deprecated and may be removed in a future release of the Protocol.
  4. Otherwise, if protocol.name = multi, the receiver MUST inspect the protocol.webdav.uri property: if it’s a complete URI, the receiver MUST make a HTTP PROPFIND request against it to access the remote resource. If it only contains an identifier <key>, the receiver MUST make a HTTP PROPFIND request to https://<sender-host><sender-ocm-path>/<key> in order to access the remote resource. Additionally, the receiver MUST pass an Authorization: bearer header with either the short-lived bearer token obtained in step 2, if applicable, or the protocol.webdav.sharedSecret value.

In all cases, in case the Shared Resource is a folder and the Receiving Server accesses a resource within that shared folder, it SHOULD append its relative path to that URL. In other words, the Sending Server SHOULD support requests to URLs such as https://<sender-host><sender-ocm-path>/path/to/resource.txt.

Additionally, if protocol.<protocolname>.requirements includes mfa-enforced, the Receiving Server MUST ensure that the Receiving Party has been authenticated with MFA, or prompt the consmer in order to elevate their session, if applicable.

Share Deletion

A "SHARE_ACCEPTED" notification followed by a "SHARE_UNSHARED" notification is equivalent to a "SHARE_DECLINED" notification.

Note that the Sending Server MAY at any time revoke access to a Resource (effectively undoing or deleting the Share) without notifying the Receiving Server.

Share Updating

Some implementations have experimented with a "RESHARE_CHANGE_PERMISSION"notification, but the payload and side effects such a notification may have are out of scope of this version of this specification. The Receiving Party sending such a notification has no way of knowing if the Sending Party understood and processed the reshare request or not.

Resharing

The "REQUEST_RESHARE" and "RESHARE_UNDO" notification types MAY be used by the Receiving Server to persuade the Sending Server to share the same Resource with another Receiving Party. The details of the payload and side effects such a notification may have are out of scope of this version of this specification. Note that the Receiving Party sending such a notification has no way of knowing if the Sending Party understood and processed the reshare request or not.

Appendix A: Multi Factor Authentication

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 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 provided a second factor to establish their identity with greater confidence.

Since there is no way to guarantee that the Receiving Server will actually enforce the MFA requirement, it is up to the Sending Server to establish a trust with the Receiving Server such that it is reasonable to assume that the Receiving Server will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted Receiving Servers. The procedure of establishing trust is out of scope for this specification: a mechanism similar to the ScienceMesh integration for the Invite capability may be envisaged.

Appendix B: Request Signing

A request is signed by adding the signature in the headers. The sender also needs to expose the public key used to generate the signature. The receiver can then validate the signature and therefore the origin of the request. To help debugging, it is recommended to also add all properties used in the signature as headers, even if they can easily be re-generated from the payload.

Note: Signed requests prove the identity of the sender but do not encrypt nor affect its payload.

Here is an example of headers needed to sign a request.

  {
    "(request-target)": "post /path",
    "content-length": 380,
    "date": "Mon, 08 Jul 2024 14:16:20 GMT",
    "digest": "SHA-256=U7gNVUQiixe5BRbp4Tg0xCZMTcSWXXUZI2\\/xtHM40S0=",
    "host": "hostname.of.the.recipient",
    "Signature": "keyId=\"https://author.hostname/key\",algorithm=\"rsa-sha256\",headers=\"content-length date digest host\",signature=\"DzN12OCS1rsA[...]o0VmxjQooRo6HHabg==\""
  }

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)

How to confirm Signature on incoming request

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

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

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

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.

— back