From 75c89eee66dee35e61be829c3034ff48f497b3fc Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Wed, 19 Nov 2025 12:39:20 +0100 Subject: [PATCH 1/6] Add functions, roles, and object models to draft This updates IETF-RFC.md with a significantly expanded conceptual framework for OCM. It introduces formal definitions of OCM functions, clarifies the roles of Sending and Receiving Servers, and adds detailed object models for Address Books, Contacts, Invites, Providers, Shares, Users, and Resources. The change reorganizes and expands terminology, adds diagrams to illustrate relationships, and alphabetizes and harmonizes defined terms. Legacy duplicated sections are removed or merged into the new structure. Signed-off-by: Micke Nordin --- IETF-RFC.md | 604 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 510 insertions(+), 94 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index be8baf12..9426e292 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -85,60 +85,443 @@ NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. -We define the following concepts, with some non-normative references to -related concepts from OAuth [RFC6749] and elsewhere: +## Functions -* __Resource__ - The piece of data or interaction to which access is - being granted, including but not limited to: a file or folder, a video - call, a contact, a printer queue, etc. -* __Remote Resource__ - A Resource provided by the Sending Server. -* __Shared Resource__ - A Resource shared by an OCM Server, becoming a - Remote Resource if accepted by the Invite Receiver OCM Server. -* __Share__ - A policy rule stating that certain actors have specific - access rights to a Resource; it MAY also refer to a record in a - database representing this rule. -* __Sending Party__ - A person or party who is authorized to create - Shares; similar to "Resource Owner" in OAuth [RFC6749], identified by - its OCM Address. -* __Receiving Party__ - A person, group or party who is granted access - to the Resource through the Share; similar to "Requesting Party / RqP" - in OAuth-UMA, identified by its OCM Address. -* __Share Creation Notification__ - A server-to-server request from the - sending server to the receiving server, notifying the receiving server - that a Share has been created. -* __Sending Server__ - The server that: - - holds the Resource ("file server" or "Entreprise File Sync and Share - (EFSS) server" role), - - provides access to it (by exposing at least one "API"), - - takes the decision to create the Share based on user interface - gestures from the Sending Party (the "Authorization Server" role in - OAuth [RFC6749]), - - takes the decision about authorizing attempts to access the Resource - (the "Resource Server" role in OAuth [RFC6749]), - - sends out Share Creation Notifications when appropriate (see below). -* __Receiving Server__ - The server that: - - receives Share Creation Notifications (see below), - - actively or passively notifies the receiving user or group of any - incoming Share Creation Notification, - - acts as an API client, allowing the receiving user to access the - Resource through an API (e.g., WebDAV [RFC4918]) of the sending - server. -* __Sending Gesture__ - A user interface interaction from the Sending - Party to the Sending Server, conveying the intention to create a - Share. -* __Share Creation__ - The addition of a Share to the database state of - the Sending Server, in response to a successful Sending Gesture or for - another reason. -* __Sharing User__ - A user providing access to a Resource through a - Share. -* __FQDN__ - Fully Qualified Domain Name, such as `"cloud.example.com"`. -* __OCM Server__ - A server that supports OCM. -* __OCM API Discovery__ - Process of evaluating properties of a Remote - Resource, after establishing contact with an OCM Server. -* __Discovering Server__ - A server that tries to obtain information in - OCM API Discovery. +Open Cloud Mesh defines distinct functions, it is not neccessary for an +implementation to provide all of them. In fact, it may be useful to +have separate implementations for different functions. + +### OCM Provider + +An OCM Provider is an entity that can take on the two _roles_ of a +_Sending Server_ and a _Receiving Server_. An OCM Provider MUST be a +_Discoverable Server_ and SHOULD be able to receive _Notifications_. + +### OCM Directory Service + +An OCM Directory Service is an entity that exposes information about a +_Federation_ of OCM Providers. + +## Roles + +Open Cloud Mesh defines two distinct roles that an OCM Provider MUST +take on: the _Sending Server_ role and the _Receiving Server_ role. + +### Sending Server + +A Sending Server is an OCM Provider that holds Resources and exposes +APIs to allow access to them. It allows its users to create _Shares_ +or _Invites_ to give other users access to those Resources. A Sending +Server MAY provide its users with the ability to generate _Invites_ to +establish contact with other users on other OCM Providers. When doing +so it MAY provide a _WAYF Page_ to facilitate the Invite Flow. The WAYF +page MAY be limited to a set of trusted OCM Providers, for instance +those in the same _Federation_. + + +### Receiving Server + +A Receiving Server is an OCM Provider that receives _Share_ Creation +Notifications from Sending Servers, notifies its users about incoming +_Shares_, and acts as an API client to allow its users to access Remote +Resources. It MAY provide it's users with an _Address Book_ of +_Contacts_ and the ability to accept _Invites_. + +## Object models + +An implementor of OCM MAY choose any internal object model to represent +an _Address Book_, a _Contact_, an _Invite_, a _Provider_, a _Share_, +and a _User_. However, the following diagrams are provided to clarify +the concepts and their relationships. + +### Address Book + +An _OCM Provider_ MAY offer its _Users_ 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. + +The Address Book entity maintains a collection of contacts for a user +within the OCM provider. It serves as the primary mechanism for managing +federated relationships between users across different OCM Servers. +_Contacts_ may be added to the Address Book through the Invite flow or +direct entry. It provides a convenient way for users to organize and +access their federated contacts, and MAY allow users to generate +_Invites_. + +``` ++-----------------+ +| Address Book | +| | +| - owner: User |--------+ +| - contacts: [] | | ++-----------------+ | + | | + | contains | generates + | 0..* | + v v ++-----------------+ +----------------+ +| Contact | | Invites | ++-----------------+ +----------------+ +``` +#### Properties + +* __owner__: Reference to the User who owns this address book +* __contacts__: Array of Contact objects stored in the address book + +#### Relationships + +* An Address Book belongs one or more Users. +* An Address Book contains zero or more Contacts. +* An Address Book MAY allow its owner to generate Invites. + +### Contact +A Contact represents a federated user relationship established through +the OCM protocol. Contacts are stored in _Address Books_ and may be +created through the Invite process or via direct entry. A Contact MAY +of course contain much more detailed information about the referenced +user. + +``` ++-----------------+ +| Contact | ++-----------------+ +| - addedDate | +| - email | +| - name | +| - ocmAddress | +| - trusted | ++-----------------+ + ^ + | referenced by + | ++-----------------+ +| Address Book | ++-----------------+ +``` +#### Properties + +* __addedDate__: Timestamp of when contact was added +* __email__: Contact email address (informational) +* __name__: Human-readable display name +* __ocmAddress__: Full OCM Address +* __trusted__: Indicates if contact has been added through the + Invite flow (trusted), via direct entry (untrusted) + or is blocked +* __userID__: The identifier of the contact at their OCM Server + +##### Contact States + +* __Blocked__: Contact blocked from sending Shares +* __Trusted__: Established through completed Invite flow +* __Untrusted__: Added directly without Invite verification + +#### Relationships + +* A Contact may be referenced by one or more Address Books. + +### Invite + +The Invite entity represents the bidirectional trust establishment +mechanism in OCM. It facilitates secure contact exchange between users +on different OCM Servers. + +``` ++-----------------+ +| Invite | ++-----------------+ +| - acceptedTime | +| - createdTime | +| - sender: User | +| - status | +| - token | ++-----------------+ + | + | generated by + v ++-----------------+ +| Address Book | ++-----------------+ + +``` +#### Properties + +* __acceptedTime__: Timestamp of invite acceptance (if accepted) +* __createdTime__: Timestamp of invite creation +* __sender__: Reference to the User who sent the Invite +* __status__: Current state (pending, accepted, expired, revoked) +* __token__: Unique, hard-to-guess string generated by Invite Sender + OCM Server + +##### Invite States + +* __Accepted__: Invite successfully accepted by Invite Receiver +* __Expired__: Invite no longer valid after a certain time +* __Pending__: Invite created but not yet accepted +* __Revoked__: Invite invalidated by Invite Sender before acceptance + +#### Relationships + +* An Invite is generated by an Address Book entry action. +* An Invite is associated with exactly one User as the sender. + +### Provider + +The Provider entity represents an OCM Server's capabilities and +configuration as discovered through the OCM API Discovery process. It +represents both the Sending Server and Receiving Server roles, and an +implementor might find it useful to have a Provider object model to +store the discovered information about federation peers or other remote +OCM Providers. + +``` + +-----------------------+ + | Provider | + | (OCM Server) | + +-----------------------+ + | - apiVersion | + | - enabled: bool | + | - endPoint | + | - inviteAcceptDialog | + | - provider | + | - publicKey | + | - tokenEndpoint | + +-----------------------+ + | + | exposes + | + +---------+---------+----------------------+ + | | | + v v v ++------------------+ +------------------+ +------------------+ +| ResourceTypes[] | | Capabilities[] | | Criteria[] | ++------------------+ +------------------+ +------------------+ +| - name | | - enforce-mfa | | - allowlist | +| - shareTypes[] | | - exchange-token | | - denylist | +| - protocols{} | | - invite-wayf | | - http-signatures| ++------------------+ | - invites | | - invite | + | | - webdav-uri | | - token-exchange | + | +------------------+ +------------------+ + | supports + v ++------------------+ +| Protocols | ++------------------+ +| - datatx | +| - webapp | +| - webdav | +| - ... | ++------------------+ +``` + +#### Properties + +* __apiVersion__: Version string of supported OCM API +* __capabilities__: Optional features supported +* __criteria__: Requirements for accepting Share Creation Notifications +* __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 + +### Share + +The Share entity represents a policy granting access to a _Resource_ +from a Sending Party to a Receiving Party. + + +``` ++-----------------+ +------------------+ +| Sending Party | | Receiving Party | ++-----------------+ +------------------+ + | | + | creates | accesses + v v ++------------------+ notification +------------------+ +| Share |-------------------->| Receiving Server | ++------------------+ +------------------+ +| - expiration | | +| - name | | mediates access to +| - owner | v +| - permissions[] | +------------------+ +| - protocol | | Resource (remote)| +| - providerId | +------------------+ +| - requirements[] | +| - resourceType | +| - sender | +| - shareType | +| - shareWith | +| - state | ++------------------+ + | + | governs access to + v ++-----------------+ +| Resource | ++-----------------+ +``` + +#### Properties + +* __expiration__: Optional expiration timestamp +* __name__: Human-readable name of the shared Resource +* __owner__: OCM Address of the Resource owner +* __permissions__: Array of granted permissions (read, write, share) +* __protocol__: Access protocol configuration (webdav, webapp, datatx) +* __providerId__: Unique identifier for the Share at the provider +* __requirements__: Array of access requirements (must-use-mfa, + must-exchange-token) +* __resourceType__: Type of resource (file, folder, calendar, etc.) +* __sender__: OCM Address of the party creating the Share +* __shareType__: Type of recipient (user, group, federation) +* __shareWith__: OCM Address of the Receiving Party +* __state__: Current state of the Share (accepted, pending, deleted) + +##### Share States + +* __Accepted__: Share accepted, Resource accessible +* __Deleted__: Share removed or expired +* __Pending__: Awaiting acceptance by Receiving Party + +#### Relationships + +* A Share is created by a User (local). +* A Share is received by a User (remote). +* A Share governs access to a Resource. + +### User + +The User entity represents the party in OCM who can send and receive +Shares and Invites and manage Contacts, and interact with Resources. + +``` + +-----------------------+ + | User | + +-----------------------+ + | - email | + | - name | + | - ocmAddress | + | - uid | + +-----------------------+ + | + +---------+---------+ + | | + | owns | participates in + v v + +------------------+ +------------------+ + | Address Book | | Shares | + +------------------+ +------------------+ + | - contacts[] | | - receiving[] | + +------------------+ | - sending[] | + | +------------------+ + | + | issues + v + +------------------+ + | Invites | + +------------------+ + | - sent[] | + +------------------+ +``` + +#### Properties + +* __email__: User's email address +* __name__: Human-readable display name +* __ocmAddress__: Full OCM Address +* __uid__: Unique identifier within the OCM Provider + +#### Relationships + +* A User owns one or more Address Book(s). +* A User issues zero or more Invites. +* A User participates in zero or more Shares as Sending or Receiving + Party. + +### Resource + +The Resource entity represents the data or service being shared between +OCM Providers. It is the target of Shares and is accessed by the +Receiving Party through the Sending Server's API. In general a Resource +is a much more complex entity, but for the purpose of OCM we only need +to model a few key properties. + +``` ++-----------------+ +| Resource | ++-----------------+ +| - location | +| - owner: User | +| - resourceID | +| - type | ++-----------------+ + ^ + | + | accessed via + | + v ++------------------+ +| Share | ++------------------+ +``` + +#### Properties + +* __location__: URI or path to access the Resource +* __owner__: Reference to the User who owns the Resource +* __resourceID__: Unique identifier of the Resource +* __type__: Type of Resource (file, folder, calendar, etc.) + + +## Defined Terms + +We define the following concepts (in alphabetical order), with some +non-normative references to related concepts from OAuth [RFC6749] and +elsewhere: + +* __Directory Service__ - A third-party service that exposes a list of + trusted OCM Servers. * __Discoverable Server__ - A server that tries to supply information in OCM API Discovery. +* __Federation__ - A group of OCM Providers that have established + mutual trust and agree on certain policies for interaction. A + Federation MAY be facilitated by a Directory Service. +* __FQDN__ - Fully Qualified Domain Name, such as `"cloud.example.com"`. +* __Invite Acceptance Gesture__ - Gesture from the Invite Receiver to + the Invite Receiver OCM Server, supplying the Invite Token as well as + the OCM Address of the Invite Sender, effectively allowlisting the + Invite Sender OCM Server for sending Share Creation Notifications to + the Invite Receiver OCM Server. +* __Invite Acceptance Response__ - HTTP response to the Invite + Acceptance Request. +* __Invite Acceptance Request__ - API call from the Invite Receiver OCM + Server to the Invite Sender OCM Server, supplying the Invite Token as + well as the OCM Address of the Invite Receiver, effectively + allowlisting the Invite Sender OCM Server for sending Share Creation + Notifications to the Invite Receiver OCM Server. +* __Invite Creation Gesture__ - Gesture from the Invite Sender to the + Invite Sender OCM Server, resulting in the creation of an Invite + Token. +* __Invite Message__ - Out-of-band message used to establish contact + between parties and servers in the Invite Flow, containing an Invite + Token (see below) and the Invite Sender's OCM Address. +* __Invite Receiver__ - The party receiving an Invite, identified by its + OCM Address. +* __Invite Receiver OCM Server__ - The server holding an address book + used by the Invite Receiver, to which details of the Invite Sender are + to be added. +* __Invite Sender__ - The party sending an Invite, identified by its + OCM Address. +* __Invite Sender OCM Server__ - The server holding an address book + used by the Invite Sender, to which details of the Invite Receiver are + to be added. +* __Invite String__ - A base64 encoded string containing an Invite Token + and the FQDN of an Invite Sender OCM Server joined by an `@`-sign. +* __Invite Token__ - A hard-to-guess string used in the Invite Flow, + generated by the Invite Sender OCM Server and linked uniquely to the + Invite Sender's OCM Address. * __OCM Address__ - identifies a user or group "at" an OCM Server. The OCM Address contains a server specific Party identifier, a host locating the OCM Server and an optional port. The OCM Address is not a @@ -166,41 +549,52 @@ characters. port via the Well-Known [RFC8615] path `/.well-known/ocm`. The OCM Address MUST NOT contain a path. +* __OCM API Discovery__ - Process of evaluating properties of a Remote + Resource, after establishing contact with an OCM Server. +* __OCM Server__ - A server that has the OCM Provider function. +* __Discovering Server__ - A server that tries to obtain information in + OCM API Discovery. * __OCM Notification__ - A message from the Receiving Server to the Sending Server or vice versa, using the OCM Notifications endpoint. -* __Invite Message__ - Out-of-band message used to establish contact - between parties and servers in the Invite Flow, containing an Invite - Token (see below) and the Invite Sender's OCM Address. -* __Invite Sender__ - The party sending an Invite, identified by its - OCM Address. -* __Invite Receiver__ - The party receiving an Invite, identified by its - OCM Address. -* __Invite Sender OCM Server__ - The server holding an address book - used by the Invite Sender, to which details of the Invite Receiver are - to be added. -* __Invite Receiver OCM Server__ - The server holding an address book - used by the Invite Receiver, to which details of the Invite Sender are - to be added. -* __Invite Token__ - A hard-to-guess string used in the Invite Flow, - generated by the Invite Sender OCM Server and linked uniquely to the - Invite Sender's OCM Address. -* __Invite String__ - A base64 encoded string containing an Invite Token - and the FQDN of an Invite Sender OCM Server joined by an `@`-sign. -* __Invite Creation Gesture__ - Gesture from the Invite Sender to the - Invite Sender OCM Server, resulting in the creation of an Invite - Token. -* __Invite Acceptance Gesture__ - Gesture from the Invite Receiver to - the Invite Receiver OCM Server, supplying the Invite Token as well as - the OCM Address of the Invite Sender, effectively allowlisting the - Invite Sender OCM Server for sending Share Creation Notifications to - the Invite Receiver OCM Server. -* __Invite Acceptance Request__ - API call from the Invite Receiver OCM - Server to the Invite Sender OCM Server, supplying the Invite Token as - well as the OCM Address of the Invite Receiver, effectively - allowlisting the Invite Sender OCM Server for sending Share Creation - Notifications to the Invite Receiver OCM Server. -* __Invite Acceptance Response__ - HTTP response to the Invite - Acceptance Request. +* __Receiving Party__ - A person, group or party who is granted access + to the Resource through the Share; similar to "Requesting Party / RqP" + in OAuth-UMA, identified by its OCM Address. +* __Receiving Server__ - The server that: + - receives Share Creation Notifications (see below), + - actively or passively notifies the receiving user or group of any + incoming Share Creation Notification, + - acts as an API client, allowing the receiving user to access the + Resource through an API (e.g., WebDAV [RFC4918]) of the sending + server. +* __Remote Resource__ - A Resource provided by the Sending Server. +* __Resource__ - The piece of data or interaction to which access is + being granted, including but not limited to: a file or folder, a video + call, a contact, a printer queue, etc. +* __Sending Gesture__ - A user interface interaction from the Sending + Party to the Sending Server, conveying the intention to create a + Share. +* __Sending Party__ - A person or party who is authorized to create + Shares; similar to "Resource Owner" in OAuth [RFC6749], identified by + its OCM Address. +* __Sending Server__ - The server that: + - holds the Resource ("file server" or "Entreprise File Sync and Share + (EFSS) server" role), + - provides access to it (by exposing at least one "API"), + - takes the decision to create the Share based on user interface + gestures from the Sending Party (the "Authorization Server" role in + OAuth [RFC6749]), + - takes the decision about authorizing attempts to access the Resource + (the "Resource Server" role in OAuth [RFC6749]), + - sends out Share Creation Notifications when appropriate (see below). +* __Share__ - A policy rule stating that certain actors have specific + access rights to a Resource; it MAY also refer to a record in a + database representing this rule. +* __Share Creation__ - The addition of a Share to the database state of + the Sending Server, in response to a successful Sending Gesture or for + another reason. +* __Share Creation Notification__ - A server-to-server request from the + sending server to the receiving server, notifying the receiving server + that a Share has been created. * __Share Name__ - A human-readable string, provided by the Sending Party or the Sending Server, to help the Receiving Party understand which Resource the Share grants access to. @@ -208,6 +602,10 @@ characters. Receiving Party on the modes of accessing the Resource. * __Share Requirements__ - Protocol-specific restrictions on the modes of accessing the Resource. +* __Shared Resource__ - A Resource shared by an OCM Server, becoming a + Remote Resource if accepted by the Invite Receiver OCM Server. +* __Sharing User__ - A user providing access to a Resource through a + Share. * __Trusted Server__ - An OCM Server that is considered trustworthy by another OCM Server, based on out-of-band information, federation membership or prior interactions, SHOULD be recorded in an internal @@ -218,8 +616,6 @@ characters. or supported capabilities. * __WAYF Page__ - A Where-Are-You-From page is a discovery service used to identify the OCM Server of an Invite Receiver. -* __Directory Service__ - A third-party service that exposes a list of - trusted OCM Servers. # General Flow @@ -256,14 +652,6 @@ 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. - ## Public Link Flow An interface for anonymously viewing a Resource on the Sending Server @@ -315,6 +703,34 @@ Share Creation Notification from an unknown Sending Party is received * the Invite Receiver OCM Server sends the Invite Acceptance Request to the Invite Sender OCM Server +``` +Invite Sender Invite Receiver +OCM Server OCM Server ++-------------+ +-------------+ +| Server | | Server | ++-------------+ +-------------+ + | | + | generates | processes + v ^ ++-------------+ Invite Message (OOB) +-------------+ +| Invite |--------------------------------->| Invite | +| Token | | Reception | ++-------------+ +-------------+ + | | + | | + v v ++-------------+ Invite Acceptance Request +-------------+ +| Contact |<---------------------------------| Accepting | +| Added | | Invite | ++-------------+ +-------------+ + | + v + +-------------+ + | Contact | + | Added | + +-------------+ +``` + ### Invite Acceptance Request Details Whereas the precise syntax of the Invite Message and the Invite From ff9e33f6b82fe12dcc13a0f7c5b0d0b9d7c8ea29 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Tue, 25 Nov 2025 12:25:02 +0100 Subject: [PATCH 2/6] Address feedback from @KrausMatthias --- IETF-RFC.md | 52 ++++++++++++++++------------------------------------ 1 file changed, 16 insertions(+), 36 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 9426e292..8fcc094c 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -111,12 +111,12 @@ take on: the _Sending Server_ role and the _Receiving Server_ role. A Sending Server is an OCM Provider that holds Resources and exposes APIs to allow access to them. It allows its users to create _Shares_ -or _Invites_ to give other users access to those Resources. A Sending -Server MAY provide its users with the ability to generate _Invites_ to -establish contact with other users on other OCM Providers. When doing -so it MAY provide a _WAYF Page_ to facilitate the Invite Flow. The WAYF -page MAY be limited to a set of trusted OCM Providers, for instance -those in the same _Federation_. +to give other users access to those Resources. A Sending Server MAY +provide its users with the ability to generate _Invites_ to establish +contact with other users on other OCM Providers. When doing so it MAY +provide a _WAYF Page_ to facilitate the Invite Flow. The WAYF page MAY +be limited to a set of trusted OCM Providers, for instance those in the +same _Federation_. ### Receiving Server @@ -139,8 +139,8 @@ the concepts and their relationships. An _OCM Provider_ MAY offer its _Users_ 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. +the Sending Server's database from the selection of the _Receiving +Party_ in preparation for Share Creation. The Address Book entity maintains a collection of contacts for a user within the OCM provider. It serves as the primary mechanism for managing @@ -181,7 +181,7 @@ A Contact represents a federated user relationship established through the OCM protocol. Contacts are stored in _Address Books_ and may be created through the Invite process or via direct entry. A Contact MAY of course contain much more detailed information about the referenced -user. +user such as if it was added via _Invites_ or direct entry. ``` +-----------------+ @@ -190,8 +190,8 @@ user. | - addedDate | | - email | | - name | -| - ocmAddress | -| - trusted | +| - provider | +| - userID | +-----------------+ ^ | referenced by @@ -205,17 +205,8 @@ user. * __addedDate__: Timestamp of when contact was added * __email__: Contact email address (informational) * __name__: Human-readable display name -* __ocmAddress__: Full OCM Address -* __trusted__: Indicates if contact has been added through the - Invite flow (trusted), via direct entry (untrusted) - or is blocked * __userID__: The identifier of the contact at their OCM Server - -##### Contact States - -* __Blocked__: Contact blocked from sending Shares -* __Trusted__: Established through completed Invite flow -* __Untrusted__: Added directly without Invite verification +* __provider__: The FQDN of the contact's OCM Server #### Relationships @@ -234,7 +225,6 @@ on different OCM Servers. | - acceptedTime | | - createdTime | | - sender: User | -| - status | | - token | +-----------------+ | @@ -250,17 +240,9 @@ on different OCM Servers. * __acceptedTime__: Timestamp of invite acceptance (if accepted) * __createdTime__: Timestamp of invite creation * __sender__: Reference to the User who sent the Invite -* __status__: Current state (pending, accepted, expired, revoked) * __token__: Unique, hard-to-guess string generated by Invite Sender OCM Server -##### Invite States - -* __Accepted__: Invite successfully accepted by Invite Receiver -* __Expired__: Invite no longer valid after a certain time -* __Pending__: Invite created but not yet accepted -* __Revoked__: Invite invalidated by Invite Sender before acceptance - #### Relationships * An Invite is generated by an Address Book entry action. @@ -344,11 +326,10 @@ from a Sending Party to a Receiving Party. +------------------+ +------------------+ | - expiration | | | - name | | mediates access to -| - owner | v -| - permissions[] | +------------------+ -| - protocol | | Resource (remote)| -| - providerId | +------------------+ -| - requirements[] | +| - owner | v +| - protocol | +------------------+ +| - providerId | | Resource (remote)| +| - requirements[] | +------------------+ | - resourceType | | - sender | | - shareType | @@ -368,7 +349,6 @@ from a Sending Party to a Receiving Party. * __expiration__: Optional expiration timestamp * __name__: Human-readable name of the shared Resource * __owner__: OCM Address of the Resource owner -* __permissions__: Array of granted permissions (read, write, share) * __protocol__: Access protocol configuration (webdav, webapp, datatx) * __providerId__: Unique identifier for the Share at the provider * __requirements__: Array of access requirements (must-use-mfa, From 4e4baf557988ad0a02ddea777ae8d74ed7ca01ea Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 12 Dec 2025 11:38:29 +0100 Subject: [PATCH 3/6] Remove sequence diagram better supplied elsewhere --- IETF-RFC.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 8fcc094c..ec17b1ea 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -683,33 +683,6 @@ Share Creation Notification from an unknown Sending Party is received * the Invite Receiver OCM Server sends the Invite Acceptance Request to the Invite Sender OCM Server -``` -Invite Sender Invite Receiver -OCM Server OCM Server -+-------------+ +-------------+ -| Server | | Server | -+-------------+ +-------------+ - | | - | generates | processes - v ^ -+-------------+ Invite Message (OOB) +-------------+ -| Invite |--------------------------------->| Invite | -| Token | | Reception | -+-------------+ +-------------+ - | | - | | - v v -+-------------+ Invite Acceptance Request +-------------+ -| Contact |<---------------------------------| Accepting | -| Added | | Invite | -+-------------+ +-------------+ - | - v - +-------------+ - | Contact | - | Added | - +-------------+ -``` ### Invite Acceptance Request Details From 327385b6d15aacc99ec8fbd4369a0319944ae4d0 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 12 Dec 2025 11:44:04 +0100 Subject: [PATCH 4/6] Move object model to appendix D --- IETF-RFC.md | 1080 ++++++++++++++++++++++++++------------------------- 1 file changed, 543 insertions(+), 537 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index ec17b1ea..cf489f3a 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -127,333 +127,6 @@ _Shares_, and acts as an API client to allow its users to access Remote Resources. It MAY provide it's users with an _Address Book_ of _Contacts_ and the ability to accept _Invites_. -## Object models - -An implementor of OCM MAY choose any internal object model to represent -an _Address Book_, a _Contact_, an _Invite_, a _Provider_, a _Share_, -and a _User_. However, the following diagrams are provided to clarify -the concepts and their relationships. - -### Address Book - -An _OCM Provider_ MAY offer its _Users_ 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. - -The Address Book entity maintains a collection of contacts for a user -within the OCM provider. It serves as the primary mechanism for managing -federated relationships between users across different OCM Servers. -_Contacts_ may be added to the Address Book through the Invite flow or -direct entry. It provides a convenient way for users to organize and -access their federated contacts, and MAY allow users to generate -_Invites_. - -``` -+-----------------+ -| Address Book | -| | -| - owner: User |--------+ -| - contacts: [] | | -+-----------------+ | - | | - | contains | generates - | 0..* | - v v -+-----------------+ +----------------+ -| Contact | | Invites | -+-----------------+ +----------------+ -``` -#### Properties - -* __owner__: Reference to the User who owns this address book -* __contacts__: Array of Contact objects stored in the address book - -#### Relationships - -* An Address Book belongs one or more Users. -* An Address Book contains zero or more Contacts. -* An Address Book MAY allow its owner to generate Invites. - -### Contact -A Contact represents a federated user relationship established through -the OCM protocol. Contacts are stored in _Address Books_ and may be -created through the Invite process or via direct entry. A Contact MAY -of course contain much more detailed information about the referenced -user such as if it was added via _Invites_ or direct entry. - -``` -+-----------------+ -| Contact | -+-----------------+ -| - addedDate | -| - email | -| - name | -| - provider | -| - userID | -+-----------------+ - ^ - | referenced by - | -+-----------------+ -| Address Book | -+-----------------+ -``` -#### Properties - -* __addedDate__: Timestamp of when contact was added -* __email__: Contact email address (informational) -* __name__: Human-readable display name -* __userID__: The identifier of the contact at their OCM Server -* __provider__: The FQDN of the contact's OCM Server - -#### Relationships - -* A Contact may be referenced by one or more Address Books. - -### Invite - -The Invite entity represents the bidirectional trust establishment -mechanism in OCM. It facilitates secure contact exchange between users -on different OCM Servers. - -``` -+-----------------+ -| Invite | -+-----------------+ -| - acceptedTime | -| - createdTime | -| - sender: User | -| - token | -+-----------------+ - | - | generated by - v -+-----------------+ -| Address Book | -+-----------------+ - -``` -#### Properties - -* __acceptedTime__: Timestamp of invite acceptance (if accepted) -* __createdTime__: Timestamp of invite creation -* __sender__: Reference to the User who sent the Invite -* __token__: Unique, hard-to-guess string generated by Invite Sender - OCM Server - -#### Relationships - -* An Invite is generated by an Address Book entry action. -* An Invite is associated with exactly one User as the sender. - -### Provider - -The Provider entity represents an OCM Server's capabilities and -configuration as discovered through the OCM API Discovery process. It -represents both the Sending Server and Receiving Server roles, and an -implementor might find it useful to have a Provider object model to -store the discovered information about federation peers or other remote -OCM Providers. - -``` - +-----------------------+ - | Provider | - | (OCM Server) | - +-----------------------+ - | - apiVersion | - | - enabled: bool | - | - endPoint | - | - inviteAcceptDialog | - | - provider | - | - publicKey | - | - tokenEndpoint | - +-----------------------+ - | - | exposes - | - +---------+---------+----------------------+ - | | | - v v v -+------------------+ +------------------+ +------------------+ -| ResourceTypes[] | | Capabilities[] | | Criteria[] | -+------------------+ +------------------+ +------------------+ -| - name | | - enforce-mfa | | - allowlist | -| - shareTypes[] | | - exchange-token | | - denylist | -| - protocols{} | | - invite-wayf | | - http-signatures| -+------------------+ | - invites | | - invite | - | | - webdav-uri | | - token-exchange | - | +------------------+ +------------------+ - | supports - v -+------------------+ -| Protocols | -+------------------+ -| - datatx | -| - webapp | -| - webdav | -| - ... | -+------------------+ -``` - -#### Properties - -* __apiVersion__: Version string of supported OCM API -* __capabilities__: Optional features supported -* __criteria__: Requirements for accepting Share Creation Notifications -* __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 - -### Share - -The Share entity represents a policy granting access to a _Resource_ -from a Sending Party to a Receiving Party. - - -``` -+-----------------+ +------------------+ -| Sending Party | | Receiving Party | -+-----------------+ +------------------+ - | | - | creates | accesses - v v -+------------------+ notification +------------------+ -| Share |-------------------->| Receiving Server | -+------------------+ +------------------+ -| - expiration | | -| - name | | mediates access to -| - owner | v -| - protocol | +------------------+ -| - providerId | | Resource (remote)| -| - requirements[] | +------------------+ -| - resourceType | -| - sender | -| - shareType | -| - shareWith | -| - state | -+------------------+ - | - | governs access to - v -+-----------------+ -| Resource | -+-----------------+ -``` - -#### Properties - -* __expiration__: Optional expiration timestamp -* __name__: Human-readable name of the shared Resource -* __owner__: OCM Address of the Resource owner -* __protocol__: Access protocol configuration (webdav, webapp, datatx) -* __providerId__: Unique identifier for the Share at the provider -* __requirements__: Array of access requirements (must-use-mfa, - must-exchange-token) -* __resourceType__: Type of resource (file, folder, calendar, etc.) -* __sender__: OCM Address of the party creating the Share -* __shareType__: Type of recipient (user, group, federation) -* __shareWith__: OCM Address of the Receiving Party -* __state__: Current state of the Share (accepted, pending, deleted) - -##### Share States - -* __Accepted__: Share accepted, Resource accessible -* __Deleted__: Share removed or expired -* __Pending__: Awaiting acceptance by Receiving Party - -#### Relationships - -* A Share is created by a User (local). -* A Share is received by a User (remote). -* A Share governs access to a Resource. - -### User - -The User entity represents the party in OCM who can send and receive -Shares and Invites and manage Contacts, and interact with Resources. - -``` - +-----------------------+ - | User | - +-----------------------+ - | - email | - | - name | - | - ocmAddress | - | - uid | - +-----------------------+ - | - +---------+---------+ - | | - | owns | participates in - v v - +------------------+ +------------------+ - | Address Book | | Shares | - +------------------+ +------------------+ - | - contacts[] | | - receiving[] | - +------------------+ | - sending[] | - | +------------------+ - | - | issues - v - +------------------+ - | Invites | - +------------------+ - | - sent[] | - +------------------+ -``` - -#### Properties - -* __email__: User's email address -* __name__: Human-readable display name -* __ocmAddress__: Full OCM Address -* __uid__: Unique identifier within the OCM Provider - -#### Relationships - -* A User owns one or more Address Book(s). -* A User issues zero or more Invites. -* A User participates in zero or more Shares as Sending or Receiving - Party. - -### Resource - -The Resource entity represents the data or service being shared between -OCM Providers. It is the target of Shares and is accessed by the -Receiving Party through the Sending Server's API. In general a Resource -is a much more complex entity, but for the purpose of OCM we only need -to model a few key properties. - -``` -+-----------------+ -| Resource | -+-----------------+ -| - location | -| - owner: User | -| - resourceID | -| - type | -+-----------------+ - ^ - | - | accessed via - | - v -+------------------+ -| Share | -+------------------+ -``` - -#### Properties - -* __location__: URI or path to access the Resource -* __owner__: Reference to the User who owns the Resource -* __resourceID__: Unique identifier of the Resource -* __type__: Type of Resource (file, folder, calendar, etc.) - ## Defined Terms @@ -557,8 +230,7 @@ characters. Shares; similar to "Resource Owner" in OAuth [RFC6749], identified by its OCM Address. * __Sending Server__ - The server that: - - holds the Resource ("file server" or "Entreprise File Sync and Share - (EFSS) server" role), + - holds the Resource for instance, a file server, - provides access to it (by exposing at least one "API"), - takes the decision to create the Share based on user interface gestures from the Sending Party (the "Authorization Server" role in @@ -597,6 +269,9 @@ characters. * __WAYF Page__ - A Where-Are-You-From page is a discovery service used to identify the OCM Server of an Invite Receiver. +In Appendix D, an object model is presented as a non-normative guide for +implementators to understand the relationships between these terms. + # General Flow The lifecycle of an Open Cloud Mesh Share starts with prerequisites such @@ -1498,270 +1173,601 @@ registry (using the template from [RFC5785]): Specification document(s): the present Draft, once in RFC form Related information: N/A -# Security Considerations +# Security Considerations + +## 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. + +### httpsig + +It is RECOMMENDED to use signed messages, "httpsig" [RFC9421], to +verify that an OCM server is the server you expect it to be, and SHOULD +be done unless you have a niche use case. + +## 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. + +## Code Flow + +All `{tokenEndPoint}` requests MUST be transmitted over HTTPS and +signed using HTTP Signatures. Bearer tokens MUST be treated as +confidential and never logged, persisted beyond their lifetime, or +transmitted over unsecured channels. + + + +# References + +## Normative References + +[RFC2119] Bradner, S. "[Key words for use in RFCs to Indicate +Requirement Levels](https://datatracker.ietf.org/doc/html/rfc2119)", +March 1997. + +[RFC4918] Dusseault, L. M. "[HTTP Extensions for Web Distributed +Authoring and Versioning](https://datatracker.ietf.org/html/rfc4918/)", +June 2007. + +[RFC8174] Leiba, B. "[Ambiguity of Uppercase vs Lowercase in RFC 2119 +Key Words](https://datatracker.ietf.org/html/rfc8174)", May 2017. + +[RFC9421] Backman, A., Richer, J. and Sporny, M. "[HTTP Message +Signatures](https://tools.ietf.org/html/rfc9421)", February 2024. + +[RFC3986] Berners-Lee, T., Fielding, R. and Masinter, L. +"[Uniform Resource Identifier (URI): Generic Syntax +](https://datatracker.ietf.org/doc/html/rfc3986)", January 2005 + +[RFC6749] Hardt, D. (ed), "[The OAuth 2.0 Authorization Framework]( +https://datatracker.ietf.org/html/rfc6749)", October 2012. + +[RFC8615] Nottingham, M. "[Well-Known Uniform Resource Identifiers +(URIs)](https://datatracker.ietf.org/doc/html/rfc8615)", May 2019 + + +# 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](https://sciencemesh.io) integration for the +[Invite](#invite-flow) 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", + "content-digest": "SHA-256=U7gNVUQiixe5BRbp4...", + "host": "hostname.of.the.recipient", + "Signature": "keyId=\"https://author.hostname/key\",algorithm= + \"rsa-sha256\",headers=\"content-length date digest host\", + signature=\"DzN12OCS1rsA[...]o0VmxjQooRo6HHabg==\"" + } +``` + +* '@request-target' (optional) contains the reached endpoint and + the used method, +* 'content-length' is the total length of the payload of the + request, +* 'date' is the date and time when the request has been + sent, +* 'content-digest' is a checksum of the payload of the + request, +* 'host' is the hostname of the recipient of the request (remote when + signing outgoing request, local on incoming request), +* 'Signature' contains the signature generated using the private key + and details on its generation: + - 'keyId' is a unique id, formatted as an url; hostname is used to + retrieve the public key via custom discovery + - 'algorithm' specify the algorithm used to generate signature + - 'headers' specify the properties used when generating the + signature + - 'signature' the signature of an array containing the properties + listed in 'headers'. Some properties like content-length, date, + content-digest, and host are mandatory to protect against + authenticity override. + +## 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) +``` + +## 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 +``` + +## 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. -## Trust +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. -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. +# Appendix C: Directory Service -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. +A third-party Directory Service is a back-end service used to federate +multiple OCM Servers and facilitate the Invite flow. It is expected to +expose, via anonymous HTTP GET, a JSON document with the following +format: -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. +* REQUIRED: `federation` - a human-readable name for the list of OCM + Servers exposed by the Directory Service +* REQUIRED: `servers` - a JSON array of objects to describe the list + of OCM Servers with the following string fields: + - REQUIRED: `url` - an absolute URL identifying the + OCM Server. It MUST: + - include scheme: either `https://` or + (for testing purposes) `http://` + - include host (either a FQDN or an IP address) + - MAY include a non-default port + - MUST NOT include a base path (e.g., `/ocm`) + - MUST NOT include userinfo, query, or fragment + - REQUIRED: `displayName` - a human-readable name + for the OCM Server + Example: -### httpsig +```json +{ + "federation": "The ScienceMesh Directory", + "servers": [ + { + "url": "https://ocm-server-1.example.org", + "displayName": "OCM Server 1" + }, + { + "url": "https://ocm-server-2.example.org:4443", + "displayName": "OCM Server 2" + }, + { + "url": "http://192.168.1.1:8080", + "displayName": "OCM Server 3" + } + ] +} +``` -It is RECOMMENDED to use signed messages, "httpsig" [RFC9421], to -verify that an OCM server is the server you expect it to be, and SHOULD -be done unless you have a niche use case. -## 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. +# Appendix D: Object models -## Code Flow +An implementor of OCM MAY choose any internal object model to represent +an _Address Book_, a _Contact_, an _Invite_, a _Provider_, a _Share_, +and a _User_. However, the following diagrams are provided to clarify +the concepts and their relationships, as a guide for implementors. -All `{tokenEndPoint}` requests MUST be transmitted over HTTPS and -signed using HTTP Signatures. Bearer tokens MUST be treated as -confidential and never logged, persisted beyond their lifetime, or -transmitted over unsecured channels. +## Address Book +An _OCM Provider_ MAY offer its _Users_ 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. +The Address Book entity maintains a collection of contacts for a user +within the OCM provider. It serves as the primary mechanism for managing +federated relationships between users across different OCM Servers. +_Contacts_ may be added to the Address Book through the Invite flow or +direct entry. It provides a convenient way for users to organize and +access their federated contacts, and MAY allow users to generate +_Invites_. -# References +``` ++-----------------+ +| Address Book | +| | +| - owner: User |--------+ +| - contacts: [] | | ++-----------------+ | + | | + | contains | generates + | 0..* | + v v ++-----------------+ +----------------+ +| Contact | | Invites | ++-----------------+ +----------------+ +``` +### Properties -## Normative References +* __owner__: Reference to the User who owns this address book +* __contacts__: Array of Contact objects stored in the address book -[RFC2119] Bradner, S. "[Key words for use in RFCs to Indicate -Requirement Levels](https://datatracker.ietf.org/doc/html/rfc2119)", -March 1997. +### Relationships -[RFC4918] Dusseault, L. M. "[HTTP Extensions for Web Distributed -Authoring and Versioning](https://datatracker.ietf.org/html/rfc4918/)", -June 2007. +* An Address Book belongs one or more Users. +* An Address Book contains zero or more Contacts. +* An Address Book MAY allow its owner to generate Invites. -[RFC8174] Leiba, B. "[Ambiguity of Uppercase vs Lowercase in RFC 2119 -Key Words](https://datatracker.ietf.org/html/rfc8174)", May 2017. +## Contact +A Contact represents a federated user relationship established through +the OCM protocol. Contacts are stored in _Address Books_ and may be +created through the Invite process or via direct entry. A Contact MAY +of course contain much more detailed information about the referenced +user such as if it was added via _Invites_ or direct entry. -[RFC9421] Backman, A., Richer, J. and Sporny, M. "[HTTP Message -Signatures](https://tools.ietf.org/html/rfc9421)", February 2024. +``` ++-----------------+ +| Contact | ++-----------------+ +| - addedDate | +| - email | +| - name | +| - provider | +| - userID | ++-----------------+ + ^ + | referenced by + | ++-----------------+ +| Address Book | ++-----------------+ +``` +### Properties -[RFC3986] Berners-Lee, T., Fielding, R. and Masinter, L. -"[Uniform Resource Identifier (URI): Generic Syntax -](https://datatracker.ietf.org/doc/html/rfc3986)", January 2005 +* __addedDate__: Timestamp of when contact was added +* __email__: Contact email address (informational) +* __name__: Human-readable display name +* __userID__: The identifier of the contact at their OCM Server +* __provider__: The FQDN of the contact's OCM Server -[RFC6749] Hardt, D. (ed), "[The OAuth 2.0 Authorization Framework]( -https://datatracker.ietf.org/html/rfc6749)", October 2012. +### Relationships -[RFC8615] Nottingham, M. "[Well-Known Uniform Resource Identifiers -(URIs)](https://datatracker.ietf.org/doc/html/rfc8615)", May 2019 +* A Contact may be referenced by one or more Address Books. +## Invite -# Appendix A: Multi-factor Authentication +The Invite entity represents the bidirectional trust establishment +mechanism in OCM. It facilitates secure contact exchange between users +on different OCM Servers. -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. +``` ++-----------------+ +| Invite | ++-----------------+ +| - acceptedTime | +| - createdTime | +| - sender: User | +| - token | ++-----------------+ + | + | generated by + v ++-----------------+ +| Address Book | ++-----------------+ -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](https://sciencemesh.io) integration for the -[Invite](#invite-flow) capability may be envisaged. +``` +### Properties -# Appendix B: Request Signing +* __acceptedTime__: Timestamp of invite acceptance (if accepted) +* __createdTime__: Timestamp of invite creation +* __sender__: Reference to the User who sent the Invite +* __token__: Unique, hard-to-guess string generated by Invite Sender + OCM Server -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. +### Relationships -Note: Signed requests prove the identity of the sender but do not -encrypt nor affect its payload. +* An Invite is generated by an Address Book entry action. +* An Invite is associated with exactly one User as the sender. -Here is an example of headers needed to sign a request. +## Provider + +The Provider entity represents an OCM Server's capabilities and +configuration as discovered through the OCM API Discovery process. It +represents both the Sending Server and Receiving Server roles, and an +implementor might find it useful to have a Provider object model to +store the discovered information about federation peers or other remote +OCM Providers. ``` - { - "@request-target": "post /path", - "content-length": 380, - "date": "Mon, 08 Jul 2024 14:16:20 GMT", - "content-digest": "SHA-256=U7gNVUQiixe5BRbp4...", - "host": "hostname.of.the.recipient", - "Signature": "keyId=\"https://author.hostname/key\",algorithm= - \"rsa-sha256\",headers=\"content-length date digest host\", - signature=\"DzN12OCS1rsA[...]o0VmxjQooRo6HHabg==\"" - } + +-----------------------+ + | Provider | + | (OCM Server) | + +-----------------------+ + | - apiVersion | + | - enabled: bool | + | - endPoint | + | - inviteAcceptDialog | + | - provider | + | - publicKey | + | - tokenEndpoint | + +-----------------------+ + | + | exposes + | + +---------+---------+----------------------+ + | | | + v v v ++------------------+ +------------------+ +------------------+ +| ResourceTypes[] | | Capabilities[] | | Criteria[] | ++------------------+ +------------------+ +------------------+ +| - name | | - enforce-mfa | | - allowlist | +| - shareTypes[] | | - exchange-token | | - denylist | +| - protocols{} | | - invite-wayf | | - http-signatures| ++------------------+ | - invites | | - invite | + | | - webdav-uri | | - token-exchange | + | +------------------+ +------------------+ + | supports + v ++------------------+ +| Protocols | ++------------------+ +| - datatx | +| - webapp | +| - webdav | +| - ... | ++------------------+ ``` -* '@request-target' (optional) contains the reached endpoint and - the used method, -* 'content-length' is the total length of the payload of the - request, -* 'date' is the date and time when the request has been - sent, -* 'content-digest' is a checksum of the payload of the - request, -* 'host' is the hostname of the recipient of the request (remote when - signing outgoing request, local on incoming request), -* 'Signature' contains the signature generated using the private key - and details on its generation: - - 'keyId' is a unique id, formatted as an url; hostname is used to - retrieve the public key via custom discovery - - 'algorithm' specify the algorithm used to generate signature - - 'headers' specify the properties used when generating the - signature - - 'signature' the signature of an array containing the properties - listed in 'headers'. Some properties like content-length, date, - content-digest, and host are mandatory to protect against - authenticity override. +### Properties -## How to generate the Signature for outgoing request +* __apiVersion__: Version string of supported OCM API +* __capabilities__: Optional features supported +* __criteria__: Requirements for accepting Share Creation Notifications +* __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 -After properties are set in the headers, the Signature is generated and -added to the list. +## Share + +The Share entity represents a policy granting access to a _Resource_ +from a Sending Party to a Receiving Party. -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', -} ++-----------------+ +------------------+ +| Sending Party | | Receiving Party | ++-----------------+ +------------------+ + | | + | creates | accesses + v v ++------------------+ notification +------------------+ +| Share |-------------------->| Receiving Server | ++------------------+ +------------------+ +| - expiration | | +| - name | | mediates access to +| - owner | v +| - protocol | +------------------+ +| - providerId | | Resource (remote)| +| - requirements[] | +------------------+ +| - resourceType | +| - sender | +| - shareType | +| - shareWith | +| - state | ++------------------+ + | + | governs access to + v ++-----------------+ +| Resource | ++-----------------+ +``` -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, -} +### Properties -headers['Signature'] = format_signature(signature) -``` +* __expiration__: Optional expiration timestamp +* __name__: Human-readable name of the shared Resource +* __owner__: OCM Address of the Resource owner +* __protocol__: Access protocol configuration (webdav, webapp, datatx) +* __providerId__: Unique identifier for the Share at the provider +* __requirements__: Array of access requirements (must-use-mfa, + must-exchange-token) +* __resourceType__: Type of resource (file, folder, calendar, etc.) +* __sender__: OCM Address of the party creating the Share +* __shareType__: Type of recipient (user, group, federation) +* __shareWith__: OCM Address of the Receiving Party +* __state__: Current state of the Share (accepted, pending, deleted) -## How to confirm Signature on incoming request +#### Share States -The first step would be to confirm the validity of each -properties: +* __Accepted__: Share accepted, Resource accessible +* __Deleted__: Share removed or expired +* __Pending__: Awaiting acceptance by Receiving Party -* `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. +### Relationships -Here is an example of how to verify the signature using the headers, -the signature and the public key: +* A Share is created by a User (local). +* A Share is received by a User (remote). +* A Share governs access to a Resource. -``` -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', -} +## User -signed = headers['Signature'] -verification_result = ssl_verify(concatenate_with_newlines(clear), - signed, public_key, 'sha256') +The User entity represents the party in OCM who can send and receive +Shares and Invites and manage Contacts, and interact with Resources. -if not verification_result then - raise InvalidSignatureException +``` + +-----------------------+ + | User | + +-----------------------+ + | - email | + | - name | + | - ocmAddress | + | - uid | + +-----------------------+ + | + +---------+---------+ + | | + | owns | participates in + v v + +------------------+ +------------------+ + | Address Book | | Shares | + +------------------+ +------------------+ + | - contacts[] | | - receiving[] | + +------------------+ | - sending[] | + | +------------------+ + | + | issues + v + +------------------+ + | Invites | + +------------------+ + | - sent[] | + +------------------+ ``` -## Validating the payload +### Properties -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. +* __email__: User's email address +* __name__: Human-readable display name +* __ocmAddress__: Full OCM Address +* __uid__: Unique identifier within the OCM Provider -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. +### Relationships -# Appendix C: Directory Service +* A User owns one or more Address Book(s). +* A User issues zero or more Invites. +* A User participates in zero or more Shares as Sending or Receiving + Party. -A third-party Directory Service is a back-end service used to federate -multiple OCM Servers and facilitate the Invite flow. It is expected to -expose, via anonymous HTTP GET, a JSON document with the following -format: +## Resource -* REQUIRED: `federation` - a human-readable name for the list of OCM - Servers exposed by the Directory Service -* REQUIRED: `servers` - a JSON array of objects to describe the list - of OCM Servers with the following string fields: - - REQUIRED: `url` - an absolute URL identifying the - OCM Server. It MUST: - - include scheme: either `https://` or - (for testing purposes) `http://` - - include host (either a FQDN or an IP address) - - MAY include a non-default port - - MUST NOT include a base path (e.g., `/ocm`) - - MUST NOT include userinfo, query, or fragment - - REQUIRED: `displayName` - a human-readable name - for the OCM Server - Example: +The Resource entity represents the data or service being shared between +OCM Providers. It is the target of Shares and is accessed by the +Receiving Party through the Sending Server's API. In general a Resource +is a much more complex entity, but for the purpose of OCM we only need +to model a few key properties. -```json -{ - "federation": "The ScienceMesh Directory", - "servers": [ - { - "url": "https://ocm-server-1.example.org", - "displayName": "OCM Server 1" - }, - { - "url": "https://ocm-server-2.example.org:4443", - "displayName": "OCM Server 2" - }, - { - "url": "http://192.168.1.1:8080", - "displayName": "OCM Server 3" - } - ] -} ``` ++-----------------+ +| Resource | ++-----------------+ +| - location | +| - owner: User | +| - resourceID | +| - type | ++-----------------+ + ^ + | + | accessed via + | + v ++------------------+ +| Share | ++------------------+ +``` + +### Properties + +* __location__: URI or path to access the Resource +* __owner__: Reference to the User who owns the Resource +* __resourceID__: Unique identifier of the Resource +* __type__: Type of Resource (file, folder, calendar, etc.) + + # Acknowledgements From 649d19846d90db5d060d2d9a6fee1bfa7d42d144 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Thu, 18 Dec 2025 12:59:11 +0100 Subject: [PATCH 5/6] Address feedback from Giuseppe Co-authored-by: Giuseppe Lo Presti --- IETF-RFC.md | 96 ++++++++++++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index cf489f3a..a2857e2c 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -87,14 +87,14 @@ they appear in all capitals, as shown here. ## Functions -Open Cloud Mesh defines distinct functions, it is not neccessary for an +Open Cloud Mesh defines distinct functions. It is not necessary for an implementation to provide all of them. In fact, it may be useful to have separate implementations for different functions. ### OCM Provider An OCM Provider is an entity that can take on the two _roles_ of a -_Sending Server_ and a _Receiving Server_. An OCM Provider MUST be a +_Sending Server_ and a _Receiving Server_. An OCM Provider MUST be a _Discoverable Server_ and SHOULD be able to receive _Notifications_. ### OCM Directory Service @@ -111,10 +111,10 @@ take on: the _Sending Server_ role and the _Receiving Server_ role. A Sending Server is an OCM Provider that holds Resources and exposes APIs to allow access to them. It allows its users to create _Shares_ -to give other users access to those Resources. A Sending Server MAY +to give other users access to those Resources. A Sending Server MAY provide its users with the ability to generate _Invites_ to establish -contact with other users on other OCM Providers. When doing so it MAY -provide a _WAYF Page_ to facilitate the Invite Flow. The WAYF page MAY +contact with other users on other OCM Providers. When doing so it MAY +provide a _WAYF Page_ to facilitate the Invite Flow. The WAYF page MAY be limited to a set of trusted OCM Providers, for instance those in the same _Federation_. @@ -124,7 +124,7 @@ same _Federation_. A Receiving Server is an OCM Provider that receives _Share_ Creation Notifications from Sending Servers, notifies its users about incoming _Shares_, and acts as an API client to allow its users to access Remote -Resources. It MAY provide it's users with an _Address Book_ of +Resources. It MAY provide its users with an _Address Book_ of _Contacts_ and the ability to accept _Invites_. @@ -139,7 +139,7 @@ elsewhere: * __Discoverable Server__ - A server that tries to supply information in OCM API Discovery. * __Federation__ - A group of OCM Providers that have established - mutual trust and agree on certain policies for interaction. A + mutual trust and agree on certain policies for interaction. A Federation MAY be facilitated by a Directory Service. * __FQDN__ - Fully Qualified Domain Name, such as `"cloud.example.com"`. * __Invite Acceptance Gesture__ - Gesture from the Invite Receiver to @@ -177,19 +177,19 @@ elsewhere: Invite Sender's OCM Address. * __OCM Address__ - identifies a user or group "at" an OCM Server. The OCM Address contains a server specific Party identifier, a host -locating the OCM Server and an optional port. The OCM Address is not a +locating the OCM Server and an optional port. The OCM Address is not a URI as it does not have scheme and the identifier may contain reserved characters. ocm-address = identifier "@" host [ ":" port] - 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 + 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`. - host is an IP literal encapsulated within square brackets, an IPv4 + host is an IP literal encapsulated within square brackets, an IPv4 address in dotted decimal form, or a registered name as described in [RFC3986]. @@ -198,8 +198,8 @@ characters. The optional port subcomponent can be used to specify a port to use for discovery (see Discovery Process). - The OCM Server MUST be discoverable at the given host and optional - port via the Well-Known [RFC8615] path `/.well-known/ocm`. The OCM + The OCM Server MUST be discoverable at the given host and optional + port via the Well-Known [RFC8615] path `/.well-known/ocm`. The OCM Address MUST NOT contain a path. * __OCM API Discovery__ - Process of evaluating properties of a Remote @@ -262,15 +262,15 @@ characters. another OCM Server, based on out-of-band information, federation membership or prior interactions, SHOULD be recorded in an internal registry of trusted servers, that SHOULD be updated over time based - on new information. The registry SHOULD include the FQDN of the - trusted server and the Public Key used for HTTP Signatures. It MAY + on new information. The registry SHOULD include the FQDN of the + trusted server and the Public Key used for HTTP Signatures. It MAY also include additional metadata such as the inviteAcceptDialog URL or supported capabilities. * __WAYF Page__ - A Where-Are-You-From page is a discovery service used to identify the OCM Server of an Invite Receiver. In Appendix D, an object model is presented as a non-normative guide for -implementators to understand the relationships between these terms. +implementers to understand the relationships between these terms. # General Flow @@ -476,11 +476,11 @@ time without notifying them. ### Invite format To accept an invite, two pieces of information are required: a `token` -and a `provider`. There are two recognized formats: +and a `provider`. There are two recognized formats: * **Invite string format:** A base64-encoded string containing the token and the provider’s FQDN, - joined by an `@` sign. Example: + joined by an `@` sign. Example: If the `token` is `a55a966e-15c1-4cb9-a39d-4e4c54399baf` and the `provider` is `my-cloud-storage.org`, the combined string is @@ -495,7 +495,7 @@ and a `provider`. There are two recognized formats: * **Link format:** If the inviting OCM Server supports a WAYF page, the invite may be - provided as a link with the token as a request parameter. Example: + provided as a link with the token as a request parameter. Example: `https://my-cloud-storage.org/wayf?token= a55a966e-15c1-4cb9-a39d-4e4c54399baf` @@ -611,7 +611,7 @@ Step 4: If not, try a HTTP GET with `https:///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 +Step 6: If not, fail. Implementations MAY fallback to HTTP instead of HTTPS in testing setups and retry steps 2-5, in particular when an optional port is given in the address. Step 7: The JSON response body is the data that was discovered. @@ -988,7 +988,7 @@ 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 +from Sending Servers without httpsig as it can't identify where the notification is coming from. ### Receiving Party Notification @@ -1076,7 +1076,7 @@ Date: Wed, 05 Nov 2025 14:00:00 GMT Content-Type: application/x-www-form-urlencoded Digest: SHA-256=ok6mQ3WZzKc8nb7s/Jt2yY1uK7d2n8Zq7dhl3Q0s1xk= Content-Length: 101 -Signature-Input: +Signature-Input: sig1=("@method" "@target-uri" "content-digest" "date"); \ created=1730815200; keyid="receiver.example.org#2025"; \ alg="rsa-sha256" @@ -1207,7 +1207,7 @@ Implementers SHOULD NOT use it and prefer short-lived tokens instead. ## Code Flow All `{tokenEndPoint}` requests MUST be transmitted over HTTPS and -signed using HTTP Signatures. Bearer tokens MUST be treated as +signed using HTTP Signatures. Bearer tokens MUST be treated as confidential and never logged, persisted beyond their lifetime, or transmitted over unsecured channels. @@ -1231,14 +1231,14 @@ Key Words](https://datatracker.ietf.org/html/rfc8174)", May 2017. [RFC9421] Backman, A., Richer, J. and Sporny, M. "[HTTP Message Signatures](https://tools.ietf.org/html/rfc9421)", February 2024. -[RFC3986] Berners-Lee, T., Fielding, R. and Masinter, L. +[RFC3986] Berners-Lee, T., Fielding, R. and Masinter, L. "[Uniform Resource Identifier (URI): Generic Syntax ](https://datatracker.ietf.org/doc/html/rfc3986)", January 2005 [RFC6749] Hardt, D. (ed), "[The OAuth 2.0 Authorization Framework]( https://datatracker.ietf.org/html/rfc6749)", October 2012. -[RFC8615] Nottingham, M. "[Well-Known Uniform Resource Identifiers +[RFC8615] Nottingham, M. "[Well-Known Uniform Resource Identifiers (URIs)](https://datatracker.ietf.org/doc/html/rfc8615)", May 2019 @@ -1444,7 +1444,7 @@ format: An implementor of OCM MAY choose any internal object model to represent an _Address Book_, a _Contact_, an _Invite_, a _Provider_, a _Share_, -and a _User_. However, the following diagrams are provided to clarify +and a _User_. The following diagrams are provided to clarify the concepts and their relationships, as a guide for implementors. ## Address Book @@ -1456,12 +1456,12 @@ the Sending Server's database from the selection of the _Receiving Party_ in preparation for Share Creation. The Address Book entity maintains a collection of contacts for a user -within the OCM provider. It serves as the primary mechanism for managing -federated relationships between users across different OCM Servers. -_Contacts_ may be added to the Address Book through the Invite flow or -direct entry. It provides a convenient way for users to organize and -access their federated contacts, and MAY allow users to generate -_Invites_. +within the OCM provider. It serves as the primary mechanism for +managing federated relationships between users across different OCM +Servers. _Contacts_ may be added to the Address Book through the Invite +flow or direct entry. It provides a convenient way for users to +organize and access their federated contacts, and MAY allow users to +generate _Invites_. ``` +-----------------+ @@ -1491,8 +1491,8 @@ _Invites_. ## Contact A Contact represents a federated user relationship established through -the OCM protocol. Contacts are stored in _Address Books_ and may be -created through the Invite process or via direct entry. A Contact MAY +the OCM protocol. Contacts are stored in _Address Books_ and may be +created through the Invite process or via direct entry. A Contact MAY of course contain much more detailed information about the referenced user such as if it was added via _Invites_ or direct entry. @@ -1528,7 +1528,7 @@ user such as if it was added via _Invites_ or direct entry. ## Invite The Invite entity represents the bidirectional trust establishment -mechanism in OCM. It facilitates secure contact exchange between users +mechanism in OCM. It facilitates secure contact exchange between users on different OCM Servers. ``` @@ -1564,7 +1564,7 @@ on different OCM Servers. ## Provider The Provider entity represents an OCM Server's capabilities and -configuration as discovered through the OCM API Discovery process. It +configuration as discovered through the OCM API Discovery process. It represents both the Sending Server and Receiving Server roles, and an implementor might find it useful to have a Provider object model to store the discovered information about federation peers or other remote @@ -1588,9 +1588,9 @@ OCM Providers. | +---------+---------+----------------------+ | | | - v v v -+------------------+ +------------------+ +------------------+ -| ResourceTypes[] | | Capabilities[] | | Criteria[] | + v v v ++------------------+ +------------------+ +------------------+ +| ResourceTypes[] | | Capabilities[] | | Criteria[] | +------------------+ +------------------+ +------------------+ | - name | | - enforce-mfa | | - allowlist | | - shareTypes[] | | - exchange-token | | - denylist | @@ -1598,9 +1598,9 @@ OCM Providers. +------------------+ | - invites | | - invite | | | - webdav-uri | | - token-exchange | | +------------------+ +------------------+ - | supports - v -+------------------+ + | supports + v ++------------------+ | Protocols | +------------------+ | - datatx | @@ -1634,10 +1634,10 @@ from a Sending Party to a Receiving Party. | | | creates | accesses v v -+------------------+ notification +------------------+ ++------------------+ notification +------------------+ | Share |-------------------->| Receiving Server | +------------------+ +------------------+ -| - expiration | | +| - expiration | | | - name | | mediates access to | - owner | v | - protocol | +------------------+ @@ -1736,8 +1736,8 @@ Shares and Invites and manage Contacts, and interact with Resources. ## Resource The Resource entity represents the data or service being shared between -OCM Providers. It is the target of Shares and is accessed by the -Receiving Party through the Sending Server's API. In general a Resource +OCM Providers. It is the target of Shares and is accessed by the +Receiving Party through the Sending Server's API. In general a Resource is a much more complex entity, but for the purpose of OCM we only need to model a few key properties. From 2a26d1aab197192686e7baf044de19de2b751fc0 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 19 Dec 2025 08:54:02 +0100 Subject: [PATCH 6/6] Add a direction for a share --- IETF-RFC.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index a2857e2c..f75e3ec2 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1637,12 +1637,13 @@ from a Sending Party to a Receiving Party. +------------------+ notification +------------------+ | Share |-------------------->| Receiving Server | +------------------+ +------------------+ -| - expiration | | -| - name | | mediates access to -| - owner | v -| - protocol | +------------------+ -| - providerId | | Resource (remote)| -| - requirements[] | +------------------+ +| - direction | | +| - expiration | | mediates access to +| - name | v +| - owner | +------------------+ +| - protocol | | Resource (remote)| +| - providerId | +------------------+ +| - requirements[] | | - resourceType | | - sender | | - shareType | @@ -1659,6 +1660,7 @@ from a Sending Party to a Receiving Party. ### Properties +* __direction__: Whether the Share is incoming or outgoing * __expiration__: Optional expiration timestamp * __name__: Human-readable name of the shared Resource * __owner__: OCM Address of the Resource owner