From 7c6c1717af52a6c8e64b43073abdda6d3b629ac7 Mon Sep 17 00:00:00 2001 From: Matthias Kraus Date: Fri, 8 Aug 2025 15:38:12 +0200 Subject: [PATCH 1/5] Identify values which are an OCM Address Clarify which values are OCM Addresses, so implementers know which can be used for discovery. --- IETF-RFC.md | 29 ++++++++++++++++------------- spec.yaml | 6 +++--- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index cb8da98d..951cdc31 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -66,10 +66,11 @@ call, a contact, a printer queue, etc. access to a Resource. Also: 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) +Shares (similar to "Resource Owner" in OAuth), identified by it's +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) +in OAuth-UMA), identified by it'S OCM Address * __Sending Server__ - the server that: * holds the Resource ("file server" or "Entreprise File Sync and Share (EFSS) server" role), @@ -112,8 +113,10 @@ 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 -* __Invite Receiver__ - the party receiving an Invite +* __Invite Sender__ - the party sending an Invite, identified by it's +OCM Address +* __Invite Receiver__ - the party receiving an Invite, identified by +it's 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 @@ -577,7 +580,7 @@ with the fields as described below ## Fields * REQUIRED shareWith (string) - Consumer specific identifier of the user, group or federation + OCM Address of the user, group or federation the provider wants to share the resource with. This is known in advance. Please note that the consumer service endpoint is known in advance as well, so this is no part of the request @@ -597,11 +600,11 @@ with the fields as described below repeated. Example: 7c084226-d9a1-11e6-bf26-cec0c932ce01 * REQUIRED owner (string) - - Provider specific identifier of the user who owns the + OCM Address of the user who owns the resource. Example: "6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl" * REQUIRED sender (string) - - Provider specific identifier of the user that wants to share + OCM Address of the user that wants to share the resource. Please note that the requesting provider is being identified on a higher level, so the former `remote` property is not part of the request body. @@ -738,15 +741,15 @@ The Receiving Server MAY discard the notification if any of the following hold true: * the HTTP Signature is missing but the Sending Server does expose a -keypair discoverable from the FQDN part of the `sender` field in the -request body +keypair discoverable from the FQDN part of the `sender` OCM Address in +the request body * the HTTP Signature is missing * the HTTP Signature is not valid * no keypair is trusted or discoverable from the FQDN part of the -`sender` field in the request body +`sender` OCM Address in the request body * the keypair used to generate the HTTP Signature doesn't match the one -trusted or discoverable from the FQDN part of the `sender` field in the -request body +trusted or discoverable from the FQDN part of the `sender` OCM Address in +the request body * the Sending Server is denylisted * the Sending Server is not allowlisted * the Sending Party is not trusted by the Receiving Party (e.g. no @@ -770,7 +773,7 @@ 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 `` -part of the `sender` field in the Share Creation Notification. +part of the `sender` OCM Address 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 diff --git a/spec.yaml b/spec.yaml index 7d14b836..2944ac11 100644 --- a/spec.yaml +++ b/spec.yaml @@ -489,7 +489,7 @@ components: shareWith: type: string description: > - Consumer specific identifier of the user, group or federation the + OCM Address of the user, group or federation the provider wants to share the resource with. This is known in advance. Please note that the consumer service endpoint is known in advance @@ -515,12 +515,12 @@ components: example: 7c084226-d9a1-11e6-bf26-cec0c932ce01 owner: description: | - Provider specific identifier of the user who owns the resource. + OCM Address of the user who owns the resource. type: string example: 6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl sender: description: | - Provider specific identifier of the user that wants to share the + OCM Address of the user that wants to share the resource. Please note that the requesting provider is being identified on a higher level, so the former `remote` property is not part of the request body. From 2a4841caf55c42a49b3cda16c4d7cdc7b832c9b9 Mon Sep 17 00:00:00 2001 From: Matthias Kraus Date: Mon, 18 Aug 2025 09:49:56 +0200 Subject: [PATCH 2/5] Fix it's to its --- IETF-RFC.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 951cdc31..9ae9d61e 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -66,11 +66,11 @@ call, a contact, a printer queue, etc. access to a Resource. Also: 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), identified by it's +Shares (similar to "Resource Owner" in OAuth), 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 it'S OCM Address +in OAuth-UMA), identified by its OCM Address * __Sending Server__ - the server that: * holds the Resource ("file server" or "Entreprise File Sync and Share (EFSS) server" role), @@ -113,10 +113,10 @@ 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 it's +* __Invite Sender__ - the party sending an Invite, identified by its OCM Address * __Invite Receiver__ - the party receiving an Invite, identified by -it's OCM Address +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 From 02fe057747ff2def345a2df068ffaff418e8df80 Mon Sep 17 00:00:00 2001 From: Matthias Kraus Date: Mon, 18 Aug 2025 10:00:17 +0200 Subject: [PATCH 3/5] Fix line length to 72 chars --- IETF-RFC.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 9ae9d61e..552d481e 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -748,8 +748,8 @@ the request body * no keypair is trusted or discoverable from the FQDN part of the `sender` OCM Address in the request body * the keypair used to generate the HTTP Signature doesn't match the one -trusted or discoverable from the FQDN part of the `sender` OCM Address in -the request body +trusted or discoverable from the FQDN part of the `sender` OCM Address +in the request body * the Sending Server is denylisted * the Sending Server is not allowlisted * the Sending Party is not trusted by the Receiving Party (e.g. no From 4ded84d93fb17ce585a101a3fd9a29cbff0c0423 Mon Sep 17 00:00:00 2001 From: Matthias Kraus Date: Mon, 18 Aug 2025 10:05:24 +0200 Subject: [PATCH 4/5] Revert OCM Address mentions where previously 'field' was used --- IETF-RFC.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 552d481e..bc79d1ca 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -741,14 +741,14 @@ The Receiving Server MAY discard the notification if any of the following hold true: * the HTTP Signature is missing but the Sending Server does expose a -keypair discoverable from the FQDN part of the `sender` OCM Address in -the request body +keypair discoverable from the FQDN part of the `sender` field in the +request body * the HTTP Signature is missing * the HTTP Signature is not valid * no keypair is trusted or discoverable from the FQDN part of the -`sender` OCM Address in the request body +`sender` field in the request body * the keypair used to generate the HTTP Signature doesn't match the one -trusted or discoverable from the FQDN part of the `sender` OCM Address +trusted or discoverable from the FQDN part of the `sender` field in the request body * the Sending Server is denylisted * the Sending Server is not allowlisted @@ -773,7 +773,7 @@ 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 `` -part of the `sender` OCM Address in the Share Creation Notification. +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 From 539a63e02a651b5504559b62a26a94d553f507bb Mon Sep 17 00:00:00 2001 From: Matthias Kraus Date: Tue, 19 Aug 2025 19:49:07 +0200 Subject: [PATCH 5/5] Add Matthias Kraus to Acknowledgements --- IETF-RFC.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index bc79d1ca..dac668a9 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1125,8 +1125,8 @@ Ron Trompert, Benedikt Wegmann and Johnatan Xu. We would also like to thank Ishank Arora, Gianmaria Del Monte, Jörn Friedrich Dreyer, Hugo González Labrador, Maxence Lange, -Lovisa Lugnegård, Sandro Mesterheide, Antoon Prins and Björn Schießle -for their direct contributions to the specification. +Lovisa Lugnegård, Sandro Mesterheide, Antoon Prins, Björn Schießle +and Matthias Kraus for their direct contributions to the specification. Over the years many more people have been involved in the development of OCM. We would like to thank all of them for their contributions,