From 686293caa6adf46f7836cf13c2b7e65adbcf1988 Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Tue, 19 May 2026 08:58:25 +0200 Subject: [PATCH] First pass to rename criteria in a more consistent way --- IETF-RFC.md | 58 +++++++++++++-------------- diagrams/code-flow-role-binding.md | 2 +- diagrams/receiver-discovery-policy.md | 4 +- diagrams/share-creation-preflight.md | 2 +- schemas/ocm-discovery.json | 2 +- spec.yaml | 8 ++-- 6 files changed, 38 insertions(+), 38 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 8cfe110..5bd434a 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -748,12 +748,12 @@ contain the following information about its OCM API: Share Creation Notification. As all Receiving Servers SHOULD require the use of TLS in API calls, it is not necessary to expose that as a criterium. - Example: `["http-request-signatures"]`. The array MAY include + Example: `["must-use-http-sig"]`. The array MAY include for instance: - - `"http-request-signatures"` - to indicate that API requests + - `"must-use-http-sig"` - to indicate that API requests without http signatures will be rejected. - - `"token-exchange"` - to indicate that when this OCM Server acts - as Receiving Server, it requires the code flow for all inbound + - `"must-exchange-token"` - to indicate that when this OCM Server + acts as Receiving Server, it requires the code flow for all inbound shares. Shares that do not include `must-exchange-token` in their `protocol.webdav.requirements` will be rejected. An OCM Server advertising this criterium MUST also expose the @@ -763,7 +763,7 @@ contain the following information about its OCM API: address - `"allowlist"` - unknown servers MAY be blocked based on their IP address - - `"invite"` - an invite MUST have been exchanged between the + - `"must-invite"` - an invite MUST have been exchanged between the sender and the receiver before a Share Creation Notification can be sent * DEPRECATED: publicKey (object) - Use public keys at @@ -797,16 +797,16 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request Before constructing the notification, the Sending Server MUST query the Receiving Server's OCM API Discovery endpoint. If the Receiving -Server advertises `token-exchange` in its `criteria` and the Sending -Server exposes the `exchange-token` capability with a `tokenEndPoint`, -the Sending Server MUST include `must-exchange-token` in -`protocol.webdav.requirements` and MUST NOT fall back to legacy +Server advertises `must-exchange-token` in its `criteria` and the +Sending Server exposes the `exchange-token` capability with a +`tokenEndPoint`, the Sending Server MUST include `must-exchange-token` +in `protocol.webdav.requirements` and MUST NOT fall back to legacy shared-secret access. If the Receiving Server advertises -`token-exchange` but the Sending Server does not expose the +`must-exchange-token` but the Sending Server does not expose the `exchange-token` capability or does not have a `tokenEndPoint`, the Sending Server MUST NOT create the share, as the Receiving Server would reject any notification that lacks the code-flow requirement. -If the Receiving Server does not advertise `token-exchange` in its +If the Receiving Server does not advertise `must-exchange-token` in its `criteria`, the Sending Server MAY still include `must-exchange-token` voluntarily. @@ -932,16 +932,16 @@ voluntarily. - OPTIONAL requirements (array of strings) - The requirements that the sharee MUST fulfill to access the Resource. A subset of: - - `must-use-mfa` requires the consumer to be MFA-authenticated. - This MAY be used if the recipient provider exposes the - `enforce-mfa` capability. - `must-exchange-token` requires the recipient to exchange the given `sharedSecret` via a signed HTTPS request to the Sending Server's {tokenEndPoint} [RFC6749]. This MAY be used if the Sending Server exposes the `exchange-token` capability and `tokenEndPoint`, and MUST be - included when the Receiving Server advertises `token-exchange` + included when the Receiving Server advertises `must-exchange-token` in criteria. + - `must-use-mfa` requires the consumer to be MFA-authenticated. + This MAY be used if the recipient provider exposes the + `enforce-mfa` capability. - OPTIONAL size (integer) The size of the resource to be transferred, useful especially in case of `datatx` access type. @@ -1284,17 +1284,17 @@ The following examples illustrate typical end-to-end outcomes: 1. Strict required code flow: Provider A acts as Sending Server and exposes the `exchange-token` capability with a `tokenEndPoint`. Provider B acts as Receiving Server and advertises both - `exchange-token` and `token-exchange`. After discovering B's - `token-exchange` criteria, A MUST include `must-exchange-token` in - `protocol.webdav.requirements`. B MUST exchange the + `exchange-token` and `must-exchange-token`. After discovering B's + `must-exchange-token` criteria, A MUST include `must-exchange-token` + in `protocol.webdav.requirements`. B MUST exchange the `sharedSecret` at A's `tokenEndPoint` and then use only the bearer token to access the Resource. 2. Optional exchange with fallback: Provider A acts as Sending Server and exposes the `exchange-token` capability with a `tokenEndPoint`. - Provider B does not advertise `token-exchange`, so A sends a share - without `must-exchange-token`. When B later accesses the Resource, - it MAY attempt the token exchange at A's `tokenEndPoint`, but if - that exchange fails it MUST fall back to the legacy + Provider B does not advertise `must-exchange-token`, so A sends a + share without `must-exchange-token`. When B later accesses the + Resource, it MAY attempt the token exchange at A's `tokenEndPoint`, + but if that exchange fails it MUST fall back to the legacy `sharedSecret`. 3. Legacy share to a code-flow-capable peer: Provider A does not expose the `exchange-token` capability. Provider B does expose @@ -1303,10 +1303,10 @@ The following examples illustrate typical end-to-end outcomes: A can only send a legacy share and B can only use legacy shared-secret access for that share. 4. Asymmetric role behavior: Provider A exposes `exchange-token` and - `token-exchange`, so it can require code flow for inbound shares - when it acts as Receiving Server. When A later acts as Sending - Server toward Provider B, and B does not advertise - `token-exchange`, A MAY omit `must-exchange-token`. B may then + `must-exchange-token`, so it can require code flow for inbound + shares when it acts as Receiving Server. When A later acts as + Sending Server toward Provider B, and B does not advertise + `must-exchange-token`, A MAY omit `must-exchange-token`. B may then attempt token exchange against A's `tokenEndPoint` or fall back to legacy access. A therefore accepts strict inbound shares while still choosing a legacy-compatible outbound share. @@ -1916,9 +1916,9 @@ that section. | +--------------------------+ | | - allowlist | | | - denylist | - | | - http-request-signatures| - | | - invite | - | | - token-exchange | + | | - must-use-http-sig | + | | - must-invite | + | | - must-exchange-token | | | - ... | | +--------------------------+ | diff --git a/diagrams/code-flow-role-binding.md b/diagrams/code-flow-role-binding.md index 87b2cf9..07c9f90 100644 --- a/diagrams/code-flow-role-binding.md +++ b/diagrams/code-flow-role-binding.md @@ -1,7 +1,7 @@ ```mermaid flowchart TD ET["exchange-token in discovery"] - TX["token-exchange in criteria"] + TX["must-exchange-token in criteria"] EP["tokenEndPoint in discovery"] MS["must-exchange-token on the share"] diff --git a/diagrams/receiver-discovery-policy.md b/diagrams/receiver-discovery-policy.md index 5a5b91c..6d95068 100644 --- a/diagrams/receiver-discovery-policy.md +++ b/diagrams/receiver-discovery-policy.md @@ -5,9 +5,9 @@ flowchart TD B -- "Yes" --> C["Advertise exchange-token"] C --> D{"Does it require code flow for all inbound shares"} - D -- "Yes" --> E["Advertise token-exchange in criteria"] + D -- "Yes" --> E["Advertise must-exchange-token in criteria"] E --> F["Reject inbound shares that omit must-exchange-token"] - D -- "No" --> G["Do not advertise token-exchange"] + D -- "No" --> G["Do not advertise must-exchange-token"] G --> H["Strict inbound shares may still be accepted share by share"] B -- "No" --> I["Do not advertise exchange-token"] diff --git a/diagrams/share-creation-preflight.md b/diagrams/share-creation-preflight.md index 1e060dc..f647422 100644 --- a/diagrams/share-creation-preflight.md +++ b/diagrams/share-creation-preflight.md @@ -2,7 +2,7 @@ flowchart TD A["Sending Server wants to create a share"] A --> B["Query Receiving Server discovery"] - B --> C{"Receiver advertises token-exchange"} + B --> C{"Receiver advertises must-exchange-token"} C -- "Yes" --> D{"Sender exposes exchange-token and tokenEndPoint"} D -- "Yes" --> E["Include must-exchange-token"] diff --git a/schemas/ocm-discovery.json b/schemas/ocm-discovery.json index 54a1578..ad0cfec 100644 --- a/schemas/ocm-discovery.json +++ b/schemas/ocm-discovery.json @@ -29,7 +29,7 @@ }, "criteria": { "type": "array", - "description": "Criteria values of 'http-request-signatures', 'token-exchange', 'denylist', 'allowlist', and 'invite' are defined in the draft", + "description": "Criteria values of 'http-request-signatures', 'must-exchange-token', 'denylist', 'allowlist', and 'invite' are defined in the draft", "items": { "type": "string" } diff --git a/spec.yaml b/spec.yaml index 09c399a..189d8e5 100644 --- a/spec.yaml +++ b/spec.yaml @@ -460,8 +460,8 @@ components: items: type: string enum: - - http-request-signatures - - token-exchange + - must-use-http-sig + - must-exchange-token - denylist - allowlist - invite @@ -709,7 +709,7 @@ components: for subsequent access [RFC6749]. This requirement MAY be used if the Sending Server exposes the `exchange-token` capability and `tokenEndPoint`, and MUST be included when the Receiving Server - advertises `token-exchange` in criteria. + advertises `must-exchange-token` in criteria. enum: - must-use-mfa - must-exchange-token @@ -806,7 +806,7 @@ components: permissions: - read requirements: - - mfa-enforced + - must-use-mfa webapp: uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01 sharedSecret: hfiuhworzwnur98d3wjiwhr