diff --git a/IETF-OCM-IP.md b/IETF-OCM-IP.md index fa4c067..e6bb81d 100644 --- a/IETF-OCM-IP.md +++ b/IETF-OCM-IP.md @@ -1,6 +1,6 @@ --- title: 'Open Cloud Mesh Integration Protocol' -docname: draft-nordin-ocm-integration-protocol-00 +docname: draft-nordin-ocm-integration-protocol-01 category: std ipr: trust200902 diff --git a/IETF-OCM-IP.xml b/IETF-OCM-IP.xml index e0f4822..f82ee88 100644 --- a/IETF-OCM-IP.xml +++ b/IETF-OCM-IP.xml @@ -1,6 +1,6 @@ - + - + Open Cloud Mesh Integration Protocol @@ -38,7 +38,7 @@ - + Applications and Real-Time @@ -128,13 +128,14 @@ Creation Notifications. The Protocol Server serves the actual Resource access protocol, authorizing requests by independently verifying the access tokens issued by the OCM Server. -Two properties of [OCM] make this delegation possible without sharing -secrets between the OCM Server and the Protocol Server: +Two properties of [OCM] make this delegation possible without +provisioning the Share's sharedSecret to the Protocol Server: - The OCM Server publishes its public keys at the Well-Known [RFC8615] -path /.well-known/jwks.json in JWK format [RFC7517], and signs its -server-to-server requests using HTTP Message Signatures [RFC9421]. + The OCM Server publishes its public keys as a JWK Set [RFC7517] at +the URL advertised in the jwksUri field of its OCM API Discovery +response, and signs its server-to-server requests using HTTP Message +Signatures [RFC9421]. The Code Flow lets the Receiving Server exchange the sharedSecret for an access token whose format [OCM] leaves entirely at the issuer's discretion. @@ -437,12 +438,12 @@ exchange for Resource access. Flow of [OCM] unless the Share uses Introspected Integration: the OCM Server MUST include must-exchange-token in the requirements of every protocol entry that a Protocol Server serves in Provisioned or -Self-Contained Integration. Legacy shared-secret access cannot be -verified by a Protocol Server on its own, because the long-lived secret -is deliberately never replicated to it; Introspected Integration exists -precisely to close this gap for Receiving Servers that cannot perform -the token exchange, at the cost of a per-request callback (see Token -Introspection and Security Considerations). +Self-Contained Integration. A Protocol Server cannot validate a legacy +sharedSecret on its own. Introspected Integration allows the Protocol +Server to receive that credential on the front channel and validate it +through a per-request callback to the OCM Server. After successful +introspection, the Protocol Server may also use the credential as +described in Security Considerations.
Note: Delegating the Token Endpoint @@ -456,8 +457,9 @@ of this document: The Token Server holds its own signing keypair, and the OCM Server -publishes the public key in its own /.well-known/jwks.json under a -kid in its own domain. The iss and kid rules of this document +publishes the public key in its own JWK Set, advertised via the +jwksUri field of its Discovery response, under a kid in its own +domain. The iss and kid rules of this document (see Token Issuance by the OCM Server) are then satisfied without any private key leaving the Token Server, and token verification by Receiving Servers and Protocol Servers is unchanged. @@ -539,8 +541,9 @@ typically by the operators of the two systems, and consists of at least: Server is responsible for, which integration mode(s) to use, and, for Provisioned Integration, the base URL of the Integration API of the Protocol Server (referred to as {integrationAPI} below). For -Introspected Integration, additionally the domain of the Protocol -Server, used to verify its introspection requests. +Introspected Integration, additionally the Protocol Server's JWKS URL +(referred to as {protocolServerJwksUri} below) and domain, used to +verify its introspection requests. On the Protocol Server: the domain(s) of the paired OCM Server(s) and the integration mode(s) permitted for each. The Protocol Server MUST maintain an allowlist of paired OCM Server domains, MUST reject @@ -554,12 +557,13 @@ the URL of the introspection endpoint (referred to as No shared secret is exchanged during pairing. All trust on the back channel derives from HTTP Message Signatures [RFC9421] made with the OCM Server's signatory key, verified against the keys the OCM Server -publishes at https://<domain>/.well-known/jwks.json [RFC7517], as -specified in [OCM]. All trust on the front channel derives from the JWT -signatures on the access tokens, verified against the same published -keys. Trust in introspection requests derives, symmetrically, from HTTP -Message Signatures made with the Protocol Server's key, published at the -Protocol Server's own /.well-known/jwks.json. +publishes at the URL advertised in the jwksUri field of its OCM API +Discovery response [RFC7517], as specified in [OCM]. All trust on the +front channel derives from the JWT signatures on the access tokens, +verified against the same published keys. Trust in introspection +requests derives, symmetrically, from HTTP Message Signatures made with +the Protocol Server's key, published at the JWKS URL exchanged during +pairing (see above). The Protocol Server consequently does not need a signing keypair of its own to implement this protocol, unless it uses Introspected Integration, @@ -587,7 +591,8 @@ label ocm, following the same rules as server-to-ser [OCM]: the signature MUST cover at least @method, @target-uri, content-digest, content-length and date, MUST include the created parameter, and MUST be made with an asymmetric algorithm using -a key advertised in the OCM Server's /.well-known/jwks.json. +a key advertised in the OCM Server's JWK Set, located via the jwksUri +field of its Discovery response. On receipt of an Integration API request, the Protocol Server: @@ -634,8 +639,10 @@ Receiving Server (see Lifecycle below), The request body is the Share Creation Notification object of [OCM] that the OCM Server intends to send to the Receiving Server, with one transformation applied: every sharedSecret field, in every protocol -entry, MUST be removed. The Protocol Server never receives, stores, or -needs any OCM secret. +entry, MUST be removed. The Integration API therefore never transfers a +sharedSecret to the Protocol Server. Introspected Integration is +different: a sharedSecret may reach the Protocol Server as a +front-channel credential, independently of provisioning. The fields used by the Protocol Server are thus: @@ -818,8 +825,9 @@ at this OCM Server. The request MUST be made over TLS and MUST be signed with an HTTP Message Signature [RFC9421] carrying the label ocm, with the same covered components and created rules as Integration API requests. The -keyid MUST identify a key in the Protocol Server's own JWKS, published -at https://<protocol-server-domain>/.well-known/jwks.json [RFC7517]. +keyid MUST identify a key in the Protocol Server's own JWKS, +published at the JWKS URL exchanged during pairing +({protocolServerJwksUri}) [RFC7517]. The introspection endpoint MUST verify that the keyid domain belongs to a paired Protocol Server and MUST verify the signature against that domain's JWKS before evaluating the credential; unauthenticated or @@ -873,8 +881,9 @@ format at the issuer's discretion. This document profiles that format. For every Share in Provisioned or Self-Contained Integration, the access_token MUST be a JWT conforming to the JWT Profile for OAuth 2.0 Access Tokens [RFC9068]. The JOSE header MUST include typ with the -value set to at+jwt and MUST include a kid parameter identifying the -OCM Server's signatory key advertised in /.well-known/jwks.json, and +value set to at+jwt and MUST include a kid parameter identifying +the OCM Server's signatory key, advertised in the JWK Set located via +the jwksUri field of its Discovery response, and MUST NOT use none as the alg. The JWT MUST be signed with the private key corresponding to that signatory key, allowing anyone with access to the corresponding public key, including a Protocol Server, to @@ -977,9 +986,10 @@ verification, validate the credential through Token Introspection instead: an active response supplies the fields (iss, sub, aud, exp, client_id, ocm_ip) used in steps 4 to 6, and steps 2 and 3 are skipped; an inactive response means the request is rejected. - Resolve the signing key: fetch (or use a cached copy of) the JWKS at -https://<iss-host>/.well-known/jwks.json and select the key matching -the token's kid header parameter. + Resolve the signing key: fetch (or use a cached copy of) the OCM +Server's Discovery document at https://<iss-host>/.well-known/ocm, +read its jwksUri field, fetch the JWK Set from that URL, and select +the key matching the token's kid header parameter. Verify the token signature and validity per [RFC9068]: the algorithm MUST be an asymmetric algorithm matching the key, MUST NOT be none, and the exp claim MUST be in the future. The claims iss, sub, @@ -1163,27 +1173,115 @@ one reason the two modes compose.
Security Considerations -
No Secret Replication +
Threat Model + +The threat model follows the Internet threat model described in +[RFC3552] and inherits the trust assumptions of [OCM]. It assumes that +the Sending and Receiving OCM Servers, paired Protocol Servers, and any +delegated Token Server have not been compromised and correctly enforce +the protocol and their local authorization policies. Their +administrative interfaces, host operating systems, private keys, +credentials, and underlying storage are part of the trusted endpoints. +Compromise of an endpoint or its trusted infrastructure is outside the +scope of this specification. + +An attacker is assumed to have extensive control of the communication +channel and may observe, block, replay, insert, modify, delay, or +reorder traffic. TLS, HTTP Message Signatures, JWT signatures, and +authenticated introspection provide the protections described in this +specification against such an attacker. + +An attacker may operate an OCM Server or Protocol Server of their own, +control a remote user, steal a bearer credential, or submit malformed +back-channel or front-channel requests. An unpaired server can make +assertions under its own identity, but must not thereby gain access to a +pairing, a Share Record, or a Resource. Implementations are expected to +verify pairing, authentication, identity binding, permissions, and +Resource scope independently. + +Pairing creates an explicit administrative trust relationship. A +paired OCM Server is trusted to provision authorized Shares, issue +tokens for valid grants, and provide truthful Share information. A +Protocol Server is part of the Sending Server's trusted computing base +for every protocol it serves and is trusted to enforce identity +bindings, permissions, and protocol restrictions. A delegated Token +Server is trusted with token-signing authority and with the Share and +identity information needed to issue credentials. + +Provisioned and Introspected Integration disclose the full Share +Creation Notification payload to the Protocol Server with every +sharedSecret removed. Depending on the Share, this can include the +sender, owner, Receiving Party, display names, Resource name and +description, Resource and Share types, protocol endpoints, permissions, +expiration, and extension metadata. Provisioned Integration transfers +this information over the signed back channel before Resource access +and normally stores it as a Share Record. Introspected Integration +transfers it through the additional introspection exchange and permits +the resulting response to be cached until its stated expiration. In +addition to the Share information returned by introspection, the +Protocol Server receives the presented sharedSecret itself and may use +or retain it as permitted under Secret Handling. + +Self-Contained Integration discloses slightly less information. The +JWT presented to the Protocol Server contains the ocm_ip claim with +the protocol details, providerId, Resource type, and selected optional +Share metadata, while the enclosing JWT claims identify the issuer, +owner, and Receiving Party. The same JWT form is used by Introspected +Integration, but Self-Contained Integration performs no additional +introspection request. The ocm_ip contents are visible to the +Protocol Server and to every other holder of the JWT, including a +Receiving Party's user agent for applicable protocols. + +Bearer tokens grant access to their holder until they expire or cease +to be accepted and therefore need to remain confidential. The +cryptographic mechanisms authenticate assertions and protect exchanges +in transit; they do not establish that Resource content is safe. + +The three modes make different availability and revocation trade-offs. +Provisioned Integration depends on delivery of lifecycle requests. +Self-Contained Integration cannot revoke an issued token before expiry. +Introspected Integration depends on availability of the introspection +endpoint and permits revocation only after cached positive responses +expire. No mode prevents a required OCM Server or Protocol Server from +selectively or completely denying service. -A central design goal of OCM-IP is that delegating protocol work does -not multiply the places where secrets live: +
+
Secret Handling + +Provisioned and Self-Contained Integration avoid transferring the +Share's sharedSecret to the Protocol Server. Introspected Integration +necessarily exposes the presented credential to the Protocol Server and +therefore has different secret-handling requirements: - The sharedSecret of a Share is never stored on the Protocol Server: -it is stripped from the provisioning payload and absent from the -ocm_ip claim. A compromise of the Protocol Server therefore does not -leak credentials that could be exchanged for tokens at the OCM Server's -tokenEndPoint. (In Introspected Integration the Receiving Server does -present the legacy secret on the front channel; the Protocol Server -forwards it for introspection but MUST NOT retain it beyond the -request.) + The Integration API strips every sharedSecret from the provisioning +payload, and the ocm_ip claim does not contain one. A Protocol Server +therefore receives no sharedSecret through either of those mechanisms. + In Introspected Integration, the Receiving Server may present a legacy +sharedSecret on the front channel. The Protocol Server MUST +successfully introspect the credential before relying on it. + After successful introspection, the Protocol Server MAY use the +presented sharedSecret to access another protocol entry of the same +Share when this is necessary to serve the requested protocol. For +example, a web application Protocol Server may use it to access a WebDAV +entry in the same multi-protocol Share, whether that entry is served by +another Protocol Server or by the OCM Server. + Such use MUST remain within the Resource, protocols, permissions, and +parties identified by the successful introspection response. The +credential MUST NOT be used for another Share or retained beyond the +period during which the introspection response may be relied upon. +Continued use after that period requires a new successful introspection. + A Protocol Server that retains a sharedSecret for this purpose MUST +protect it as a bearer credential. It MUST NOT place it in URLs or logs +and MUST delete it when it is no longer needed. No pairing secret exists; the back channel is authenticated by HTTP Message Signatures against published keys, the front channel by JWT signatures against the same keys, and introspection requests by HTTP Message Signatures against the Protocol Server's published keys. The Protocol Server holds no signing keys for this protocol, with two exceptions: a Protocol Server using Introspected Integration holds a -request-signing key, published at its own /.well-known/jwks.json, and +request-signing key, published at the JWKS URL exchanged during +pairing, and a delegated Token Server (sketched in the note on delegating the token endpoint) holds its own token-signing key, whose public part is published through the OCM Server's JWKS. @@ -1199,11 +1297,15 @@ consistent with the Code Flow considerations of [OCM]. Without the Code Flow, the only credential is the long-lived sharedSecret itself, which the Receiving Server presents directly on -the front channel. The Protocol Server cannot verify it on its own: the -secret is deliberately never replicated to it. A Protocol Server MUST -NOT accept any front-channel credential other than a verifiable access -token or a credential validated through Token Introspection (or, for -SSH, the public-key mechanism of [OCM]). +the front channel. The Protocol Server cannot validate it on its own. +A Protocol Server MUST NOT accept a front-channel credential other than +a verifiable access token or a credential validated through Token +Introspection, except for the SSH public-key mechanism of [OCM]. + +Successful introspection authorizes the Protocol Server to rely on the +credential until the exp horizon of the introspection response. This +includes using the credential for another protocol entry of the same +Share as described under Secret Handling. Introspected Integration therefore reintroduces, deliberately and only for compatibility, the per-request coupling to the OCM Server that the @@ -1227,8 +1329,9 @@ content to third parties. The allowlist is therefore REQUIRED, and an empty allowlist means the Integration API rejects all requests. The Protocol Server SHOULD apply resource limits per paired OCM Server -(number of Share Records, concurrent sessions, storage) so that a -misbehaving or compromised OCM Server cannot exhaust it. +(number of Share Records, concurrent sessions, storage) so that requests +from one pairing, including excessive requests caused by malfunction or +an unexpectedly large workload, cannot exhaust it. Conversely, the OCM Server places trust in the Protocol Server to enforce the permissions and identity bindings of this document. @@ -1309,6 +1412,23 @@ apply negative caching with a short lifetime so that a flood of invalid credentials does not translate into a flood of introspection traffic towards the OCM Server. +
+
Underlying Security Specifications + +This specification relies on the base Open Cloud Mesh protocol [OCM], +HTTP Message Signatures [RFC9421], JSON Web Keys and JWK Sets [RFC7517], +Digest Fields [RFC9530], JSON Web Tokens [RFC7519], OAuth 2.0 Token +Introspection [RFC7662], and the JWT Profile for OAuth 2.0 Access Tokens +[RFC9068]. All security considerations in those specifications apply +to implementations of OCM-IP. + +These specifications need to be considered together. A signature or +token is only as trustworthy as the provenance and protection of its +key, a signed Content-Digest provides content integrity only when both +the signature and digest are validated, and an active introspection +response grants authority only within the authenticated pairing and +until its stated expiration. +
IANA Considerations @@ -1382,6 +1502,11 @@ Signatures", February 2024.
Informative References +[RFC3552] Rescorla, E. and Korver, B. "Guidelines for Writing RFC Text +on Security +Considerations", BCP 72, +July 2003. + [RFC4918] Dusseault, L. M. "HTTP Extensions for Web Distributed Authoring and Versioning", June 2007. @@ -1410,16 +1535,16 @@ the Receiving Server. The body is the Share Creation Notification with every sharedSecret removed (line breaks in the signature headers for display purposes only): -
POST /services/ocm/shares HTTP/1.1 Host: hub.example.org Date: Wed, 10 Jun 2026 14:00:00 GMT Content-Type: application/json Content-Digest: sha-256=:hj3LWOIuryd4XbzFhoHa6YMUbhtzMdMT3e9Bxpu2Lm0=: Content-Length: 542 -Signature-Input: ocm=("@method" "@target-uri" "content-digest" -"content-length" "date"); created=1781186400; -keyid="cloud.example.org#key1"; alg="ed25519" +"@signature-params": ("@method" "@target-uri" "content-digest" \ + "content-length");created=1781186400;\ + keyid="cloud.example.org#key1";alg="ed25519";tag="ocm" Signature: ocm=:[signature-value]: { @@ -1445,7 +1570,7 @@ Signature: ocm=:[signature-value]: } } } -]]>
+ The Protocol Server stores the Share Record under (cloud.example.org, 7c084226-d9a1-11e6-bf26-cec0c932ce01) and responds: @@ -1506,9 +1631,9 @@ Content-Type: application/x-www-form-urlencoded access_token=eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJFZERTQSIs... ]]> -The Protocol Server verifies the JWT against -https://cloud.example.org/.well-known/jwks.json, looks up the Share -Record by (cloud.example.org, +The Protocol Server verifies the JWT against the JWK Set advertised +at the jwksUri of https://cloud.example.org/.well-known/ocm, looks +up the Share Record by (cloud.example.org, 7c084226-d9a1-11e6-bf26-cec0c932ce01), checks that alice@cloud.example.org equals the stored owner and that bob@receiver.example.org equals the stored shareWith, and then @@ -1591,9 +1716,10 @@ Authorization: Bearer eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJFZERTQSIs... Depth: 1 ]]> -The gateway verifies the JWT against -https://cloud.example.org/.well-known/jwks.json, finds no Share Record -for (cloud.example.org, receiver.example.org), confirms that +The gateway verifies the JWT against the JWK Set advertised at the +jwksUri of https://cloud.example.org/.well-known/ocm, finds no +Share Record for (cloud.example.org, receiver.example.org), +confirms that cloud.example.org is paired for Self-Contained Integration, and serves the PROPFIND read-only, scoped to the uri in the ocm_ip claim. @@ -1606,8 +1732,8 @@ Carol (carol@legacy.example.com). The Share Creatio a legacy [OCM] share: the webdav entry points at dav.example.org and carries a sharedSecret, with no must-exchange-token requirement. dav.example.org is paired with cloud.example.org for Introspected -Integration and holds a request-signing key published at -https://dav.example.org/.well-known/jwks.json. +Integration and holds a request-signing key published at the JWKS URL +exchanged during pairing (https://dav.example.org/jwks). The Receiving Server presents the secret directly, per the legacy resource access flow of [OCM]: @@ -1708,463 +1834,509 @@ through the Tech Fund diff --git a/IETF-OCM-MLS.md b/IETF-OCM-MLS.md index 7e4ab68..cfe2a04 100644 --- a/IETF-OCM-MLS.md +++ b/IETF-OCM-MLS.md @@ -2,7 +2,7 @@ title: >- Federated Groups in Open Cloud Mesh using Messaging Layer Security abbrev: "OCM MLS Federated Groups" -docname: draft-nordin-ocm-mls-federated-groups-01 +docname: draft-nordin-ocm-mls-federated-groups-02 category: std ipr: trust200902 diff --git a/IETF-OCM-MLS.xml b/IETF-OCM-MLS.xml index 2c05cd4..298878f 100644 --- a/IETF-OCM-MLS.xml +++ b/IETF-OCM-MLS.xml @@ -1,6 +1,6 @@ - + - + Federated Groups in Open Cloud Mesh using Messaging Layer Security @@ -38,7 +38,7 @@ - + Applications and Real-Time @@ -102,10 +102,12 @@ should not necessarily be taken to mean the user's file sync client. Implementations that do provide a native client application SHOULD perform cryptographic operations in the native client on the user's devices, rather than on the server, because this provides stronger -isolation of key material from the server. In either case the same MLS -client model applies. +isolation of key material from the server. A user participating from +multiple native devices MUST do so using an MLS Virtual Client as +specified in [ietf-mls-virtual-clients], with the devices acting as +Emulator Clients. In either case the same MLS client model applies. -Each user who is a member of a federated group has their own MLS leaf +Each user who is a member of a federated group has exactly one MLS leaf node, enabling individual users to be added and removed independently. The OCM Server can act as the MLS client on behalf of its users. For implementations where the primary interface is a web client, the OCM @@ -171,8 +173,8 @@ wrapped keys, is encoded using base64url (the URL- and filename-safe alphabet defined in [RFC4648], Section 5) with padding omitted. A decoder MUST accept such a value whether or not padding is present. -This document uses terminology from [OCM] and [RFC9420]. Additional -definitions: +This document uses terminology from [OCM], [RFC9420] and +[ietf-mls-virtual-clients]. Additional definitions: Group - A Receiving Party identified by an OCM Address whose @@ -187,6 +189,11 @@ of epochs in which each epoch depends on its predecessor." shared cryptographic state with other clients, defined by the cryptographic keys it holds. In this protocol an OCM Server can fulfill this role. + Virtual Client and Emulator Client - As defined in +[ietf-mls-virtual-clients]. When a user participates from multiple +devices, the user's single leaf in the federated group represents a +Virtual Client and the devices are its Emulator Clients. The federated +group is the Higher-level Group in that document. Member Server - An OCM server with one or more users who are members of a given Group, acting as MLS client on their behalf. Group Owner Server - The server currently arbitrating Commits for @@ -236,12 +243,15 @@ describes how those roles are fulfilled by OCM. The AS role is fulfilled by each user's home OCM server. Credentials in this protocol are MLS basic credentials ([RFC9420] Section 5.3) whose identity field is the UTF-8 encoded OCM Address of the user. Each user -has their own distinct signing key pair so that individual users can be -identified and addressed independently within the MLS group, for example -to add or remove a specific user. In web-client deployments the key -pair is generated and held by the OCM Server on the user's behalf. In -native client deployments the key pair is held on the user's device and -the server's role is limited to publishing the user's KeyPackages. +has their own distinct signing key material so that individual users can +be identified and addressed independently within the MLS group, for +example to add or remove a specific user. In web-client deployments the +signing key material is generated and held by the OCM Server on the +user's behalf. In native client deployments with one device it is held +on that device. With multiple devices, signing key material is managed +as specified for the Virtual Client in +[ietf-mls-virtual-clients], and the server's role is limited to +publishing the user's KeyPackages. A basic credential carries no verifiable binding of its own; the binding between a user's OCM Address and their signature key is attested by @@ -280,6 +290,10 @@ single Member Server (). endpoint of each recipient server, authenticated with HTTP Signatures [RFC9421]. +For a Virtual Client, the user's home server MUST deliver messages sent +to or by the Virtual Client to all of its Emulator Clients, as required +by [ietf-mls-virtual-clients] Section 5.1. + Commits are constructed and signed by admin clients, but only the Commit accepted by the Group Owner Server takes effect; competing Commits for the same epoch are discarded by their senders. Designating a single @@ -314,11 +328,26 @@ regardless. shared group key. The only MLS application messages used in this protocol carry wrapped file keys () and per-server transport credential updates (). - At least one MLS leaf per user. Each user who is a member of a -federated group has at least one MLS leaf node, enabling individual -users to be added and removed independently. In web-client deployments -the OCM Server manages a single leaf node per user on their behalf. In -native client deployments each user may have a leaf node per device. + Exactly one MLS leaf per user. Each user who is a member of a +federated group has exactly one MLS leaf node, enabling individual users +to be added and removed independently. In web-client deployments the +OCM Server manages that leaf on the user's behalf. A user participating +from multiple native devices MUST represent those devices by a single +Virtual Client leaf, with the devices acting as Emulator Clients in +accordance with [ietf-mls-virtual-clients]. A leaf per device, the +Simple Multi-client model defined by that document, MUST NOT be used. +Adding or removing a device MUST use the emulation-group management +procedures in [ietf-mls-virtual-clients] Section 6, not an Add or +Remove in the federated group. + + +Transitioning from a single device to multiple devices is an +implementation detail that does not affect the protocol. A native +client implementation is however RECOMMENDED to establish an emulation +group when enrolling the user's first device and represent the user as a +Virtual Client, even while that device is the only Emulator Client. + + The OCM Server is a MLS client. An OCM Server meets the MLS definition of a client. For web-client deployments this means key material is held server-side. For native client deployments @@ -379,10 +408,7 @@ with shareWith carrying the group's OCM Address. A is otherwise a standard OCM share, carrying every field REQUIRED by [OCM] including the protocol object. All new server-to-server messages use the existing /notifications endpoint with new -notificationType values. A single new field is added to the Share -Creation Notification: encryption (optional, present only for -encrypted resources), carrying all encryption-related parameters, -including the resourceId. +notificationType values.
@@ -395,7 +421,7 @@ its OCM discovery document at /.well-known/ocm:
/mls-key-packages?userId={userId} In native client deployments, the user's device generates KeyPackages and publishes them to the home server, which exposes them at the same -endpoint without interpreting them. +endpoint without interpreting them. For a user with multiple devices, +the Emulator Clients MUST create and coordinate the Virtual Client's +KeyPackages as specified in [ietf-mls-virtual-clients] Section 5.5.1 +before publishing them to the home server. Each KeyPackage contains an MLS Credential identifying the user by their OCM Address, signed by the user's own signing key pair. Users who @@ -557,10 +586,8 @@ the admin set while remaining a member: this is a GroupContextExtensions proposal only, and the resigning admin's own client MAY commit it. Removing an admin's membership is constrained by MLS: a Commit that removes its own committer is invalid ([RFC9420] Section 12.2). A Commit -that removes some but not all of an admin's leaves MAY be committed by -one of that admin's remaining clients, but a Commit that removes an -admin's last leaf is necessarily committed by an admin client of a -different admin. +that removes an admin's single leaf is therefore necessarily committed +by an admin client of a different admin.
Group OCM Address and Admin Set @@ -608,9 +635,8 @@ proposals MUST be explicitly approved by an admin, MUST be committed by an admin client, and MUST NOT change group_ocm_address. The admin set and the group membership are coupled: an entry in admins -is only meaningful while that admin has at least one leaf in the ratchet -tree. A Commit after whose application an admin would no longer have -any leaf in the ratchet tree MUST therefore also include a +is only meaningful while that admin's leaf is in the ratchet tree. A +Commit that removes an admin's leaf MUST therefore also include a GroupContextExtensions proposal deleting that admin from admins, and the Group Owner Server and all Member Servers MUST reject a Commit that would leave an entry in admins with no corresponding leaf in the tree. @@ -654,27 +680,27 @@ Failover proceeds as follows: first admin's leaf is stale. Takeover: the home server of the next admin in the admin set MAY begin arbitrating Commits. The first Commit it arbitrates SHOULD -cover Remove proposals evicting the stale first admin's leaves, together -with the GroupContextExtensions proposal deleting them from the admin -set required by , constructed by one of its own admin -clients. This makes the takeover permanent through the normal -succession rule. +cover a Remove proposal evicting the stale first admin's leaf, +together with the GroupContextExtensions proposal deleting that +admin from the admin set as required by , constructed +by one of its own admin clients. This makes the takeover permanent +through the normal succession rule. Conflict resolution: if a Member Server receives two different Commits for the same epoch from two arbiters, it MUST process the -one arbitrated by the server of the admin listed earlier in the admin -set and discard the other. +one arbitrated by the server of the admin listed earlier in the +admin set and discard the other. Hold-back: a Member Server that has observed the trigger conditions of step 1 SHOULD retain the previous epoch's group state when -processing a Commit, so that it can revert and reprocess the winning -Commit if conflict resolution later discards the one it processed first. -Retained state MUST be deleted after a bounded time, per [RFC9420] -Section 14; the security trade-off is discussed in Security -Considerations. +processing a Commit, so that it can revert and reprocess the +winning Commit if conflict resolution later discards the one it +processed first. Retained state MUST be deleted after a bounded +time, per [RFC9420] Section 14; the security trade-off is discussed +in Security Considerations. Rejoin: a Member Server that processed a discarded Commit and no longer holds the state needed to reprocess the winning Commit has drifted from the group. It recovers through the rejoin procedure -(). Wrapped FKs are re-wrapped and redistributed by their -sending servers in the new epoch as usual (). +(). Wrapped FKs are re-wrapped and redistributed by +their sending servers in the new epoch as usual (). Since an unavailable arbiter only pauses membership changes, while @@ -694,8 +720,8 @@ application/json and HTTP Signatures [RFC9421]. ([RFC9420] Section 6.2), and Application Messages as PrivateMessage objects ([RFC9420] Section 6.3). Handshake messages are sent in the clear at the MLS layer because the servers that route and arbitrate them -are required to track the public group state - the ratchet tree and -GroupContext - in order to derive membership for share routing, resolve +are required to track the public group state, i.e the ratchet tree and +GroupContext, in order to derive membership for share routing, resolve shares to local users, and verify that Commits are signed by admin clients; in native client deployments those servers do not hold the group's secrets. A recipient that holds the group's secrets MUST verify @@ -746,10 +772,14 @@ added user.
", - "userId": "bob@othercloud.example.org", - "content": "" + "federation": { + "mlsGroupId": "", + "userId": "bob@othercloud.example.org", + "content": "" + } } } ]]>
@@ -787,9 +817,13 @@ act on it.
", - "content": "" + "federation": { + "mlsGroupId": "", + "content": "" + } } } ]]>
@@ -816,10 +850,16 @@ data, per [RFC9420] Section 15.2.
", - "proposals": [""], - "content": "" + "federation": { + "mlsGroupId": "", + "proposals": [ + "" + ], + "content": "" + } } } ]]>
@@ -863,9 +903,13 @@ epoch ([RFC9420] Section 15).
", - "content": "" + "federation": { + "mlsGroupId": "", + "content": "" + } } } ]]>
@@ -905,16 +949,20 @@ by the KeyPackage endpoint.
", - "keyPackages": [ - { - "userId": "bob@othercloud.example.org", - "mediaType": "message/mls", - "encoding": "base64url", - "content": "" - } - ] + "federation": { + "mlsGroupId": "", + "keyPackages": [ + { + "userId": "bob@othercloud.example.org", + "mediaType": "message/mls", + "encoding": "base64url", + "content": "" + } + ] + } } } ]]>
@@ -964,22 +1012,26 @@ retransmission has been exhausted. The drifted server discards its MLS state for the group and generates a fresh KeyPackage for each of its users who are members -of the group. +of the group. A KeyPackage for a Virtual Client MUST be generated +and coordinated as specified in [ietf-mls-virtual-clients] +Section 5.5.1. It sends an MLS_REJOIN notification carrying those KeyPackages to the home server of every admin. The notification is authenticated -at the OCM layer with HTTP Signatures [RFC9421], the same trust anchor -that authenticates KeyPackage distribution itself, so a rejoin request -is exactly as trustworthy as a freshly fetched KeyPackage. +at the OCM layer with HTTP Signatures [RFC9421], the same trust +anchor that authenticates KeyPackage distribution itself, so a +rejoin request is exactly as trustworthy as a freshly fetched +KeyPackage. An admin client verifies that each KeyPackage's credential carries the OCM Address of a leaf currently in the ratchet tree, and that -the notification was signed by the server named in those OCM Addresses. -A rejoin MUST NOT admit a user without a leaf in the tree; it can only -replace existing members. +the notification was signed by the server named in those OCM +Addresses. A rejoin MUST NOT admit a user without a leaf in the +tree; it can only replace existing members. The admin client constructs a single Commit containing, by value, a Remove proposal for each stale leaf and an Add proposal for the corresponding fresh KeyPackage. This rejoin pair preserves the OCM -Address of every affected leaf and grants no new party access, so admin -clients SHOULD commit it automatically, per the policy in . +Address of every affected leaf and grants no new party access, so +admin clients SHOULD commit it automatically, per the policy in +. The Commit is arbitrated and broadcast as usual, and the drifted server receives one MLS_WELCOME per re-added user, restoring clean state from the Welcome's ratchet_tree extension. @@ -1097,14 +1149,14 @@ a given epoch. The resourceId used in the AEAD associated data MUST be a stable identifier for the underlying file, consistent across all groups it is shared with. It identifies the resource, not a particular version of -it. This ensures that the FK unwrapped by members of any group correctly -decrypts the same ciphertext. The providerId values in separate share -notifications, for the same resource, MUST differ, per the providerId -definition in [OCM], but the resourceId in the AEAD associated data -MUST be the same. This means that the providerId MUST NOT be reused -as resourceId. The sending server is responsible for maintaining this -stable resourceId and MUST send it in the encryption object of the -share payload (). +it or a specific share. This ensures that the FK unwrapped by members +of any group correctly decrypts the same ciphertext. The providerId +values in separate share notifications, for the same resource, MUST +differ, per the providerId definition in [OCM], but the resourceId +in the AEAD associated data MUST be the same. This means that the +providerId MUST NOT be reused as resourceId. The sending server is +responsible for maintaining this stable resourceId and MUST send it +in the encryption object of the share payload ().
File Key Wrapping @@ -1128,7 +1180,8 @@ acts on behalf of a user who is a member of that group: whose length is the key length of that algorithm. Encrypts the resource with FK using the content AEAD. Implementations supporting native client decryption of large files -SHOULD use a chunked AEAD construction to enable streaming decryption. +SHOULD use a chunked AEAD construction to enable streaming +decryption. Derives the current Group Key from the user's local MLS state. Wraps FK using the wrap AEAD:
} }, "encryption": { - "scheme": "ocm-mls-1", - "cipher": "AES-256-GCM", - "resourceId": "3a02538b-aa54-42f2-8853-a38996e211b1" + "resourceId": "3a02538b-aa54-42f2-8853-a38996e211b1", + "scheme": "ocm-mls", + "ocm-mls": { + "cipher": "AES-256-GCM" + } } } ]]>
-The encryption field is OPTIONAL. If absent, the resource is -unencrypted and the share follows the standard OCM flow without -modification. If present, it carries all encryption-related parameters: -scheme identifies the encryption scheme, for which this document -defines "ocm-mls-1"; resourceId is the stable resource identifier -described in ; and cipher (REQUIRED when encryption -is present) names the content AEAD that the resource is encrypted with +The encryption field is OPTIONAL as per [OCM] Share Creation +Notification specification. If absent, the resource is unencrypted. +If present, and the symmetric encryption available via OCM-MLS is to +be used, it MUST carry the encryption-related parameters according to +the [OCM] specification, where: +- resourceId is the stable resource identifier described in + +- scheme is to be set to "ocm-mls" +- cipher names the content AEAD that the resource is encrypted with (), one of the AEAD algorithms defined for HPKE ([RFC9180] Section 7.3): "AES-128-GCM", "AES-256-GCM", or "CHACHA20-POLY1305". The field signals that the FK is distributed via @@ -1623,7 +1680,7 @@ epoch information is carried in the share notification. Member Servers always hold the current wrapped FK for each (resourceId, groupId) pair and use their current Group Key to unwrap it at access time. -The Group Owner Server is not involved in the delivery of OCM share +The Group Owner Server is not involved in the delivery of OCM Share notifications. All other OCM notifications relating to a share, such as share updates and share deletions, are likewise sent directly from the sending server to each Member Server, referencing the share by its @@ -1697,11 +1754,10 @@ groups. In this transitive model, each home server is trusted to attest only its own users, and each admin client is trusted to have performed the -attestation check at introduction time. A malicious home server can -impersonate its own users - it is their Authentication Service - but it -cannot impersonate users of other servers, since it cannot produce an -authenticated KeyPackage delivery for an OCM Address whose host part it -does not serve. +attestation check at introduction time. The protocol does not +independently verify assertions made by a user's home server, because +that server is the Authentication Service for its users. Compromise of +that trusted server is outside the threat model. Users who require protection of their key material from their own server should choose a native client implementation where cryptographic @@ -1711,14 +1767,72 @@ operations occur on the user's device.
Security Considerations -Trust model. In web-client deployments, the OCM Server holds the -Group Key and can decrypt any resource shared with the group on behalf -of its users. This is consistent with the standard OCM Server trust -model, where users trust their server with their data, and with OCM's -existing approach of abstracting security to the server level. Native -client deployments provide stronger isolation, as the server does not -hold key material. Implementations SHOULD move toward native client -deployments over time. +
Threat Model + +The threat model follows the Internet threat model described in +[RFC3552] and inherits the trust assumptions of [OCM]. It assumes that +the OCM Servers participating in a group, including Member Servers, +Admin Servers, and the Group Owner Server, have not been compromised and +correctly enforce the protocol and their local authorization policies. +Their administrative interfaces, host operating systems, private keys, +credentials, and underlying storage are part of the trusted endpoints. +Compromise of an OCM Server or its trusted infrastructure is outside the +scope of this specification. + +An attacker is assumed to have extensive control of the communication +channel and may observe, block, replay, insert, modify, delay, or +reorder traffic. TLS, HTTP Message Signatures, and MLS provide the +protections described in this specification against such an attacker. + +An attacker may control a remote user, a current or former group member, +or an OCM Server of its own. It may send malformed messages, retain key +material it legitimately obtained while it was a member, disclose +plaintext or keys available to it, and attempt to cause inconsistent +group state or resource exhaustion. An attacker-controlled server can +make assertions under its own identity, but must not thereby gain +authority for users outside its administrative domain or admission to a +group without the required authorization. + +The distributed Delivery Service is not trusted to provide availability +or consistent delivery. It can delay, drop, reorder, selectively +deliver, or partition messages and can observe metadata deliberately +exposed by this protocol. It cannot derive group secrets or forge valid +MLS messages. The Group Owner Server is trusted to arbitrate Commits, +but its unavailability can stall epoch transitions until failover +completes. + +In web-client deployments, the trusted OCM Server acts as the MLS client +and holds MLS state, Group Keys, FKs, and plaintext on behalf of its +users. Native-client deployments move that cryptographic endpoint to +the user's device. Exposure of member key material and subsequent +recovery are considered according to the forward-secrecy and +post-compromise-security properties of [RFC9420]; full compromise of an +OCM Server remains outside scope. + +Every current group member is an authorized recipient of the group's +cryptographic material. MLS cannot prevent a member from retaining or +disclosing plaintext, Group Keys, or FKs that it legitimately receives. +A member with write access and the applicable FK can also create a +cryptographically valid arbitrary payload for a shared Resource. MLS +authenticates the member performing a protocol operation; it does not +establish that the member or supplied content is benign. + +This protocol deliberately accepts several deployment-dependent +trade-offs described below. Encryption is optional. Key-reuse mode +trades cryptographic revocation for operational efficiency and trust in +former Member Servers. Temporary retention of previous or forked epoch +state weakens forward secrecy for a bounded period. Public handshake +messages and distribution of the ratchet tree expose group membership +and membership changes to participating servers. The protocol does not +provide protection from complete or selective denial of service. + +Virtual Clients. All Emulator Clients of a Virtual Client hold the +secret state needed to act as that Virtual Client. Compromise of one +device therefore compromises the Virtual Client, and the devices must +fully trust one another. Implementations MUST follow the onboarding, +removal, state-transfer, key-deletion, nonce-protection, and ratchet +coordination requirements and security considerations of +[ietf-mls-virtual-clients]. FK rotation vs key-reuse. FK rotation provides cryptographic access revocation on member removal, independent of trust assumptions, and @@ -1726,10 +1840,10 @@ SHOULD also be performed periodically or when key compromise is suspected. In key-reuse mode the FK is unchanged and the ciphertext is not re-encrypted, so revocation is not cryptographic: it relies on trusting servers to discard all key material they are no longer entitled -to - superseded Group Keys, old wrapped FKs, and any cached unwrapped -FKs - after a Remove Commit. Key-reuse mode SHOULD only be used within -formal federations with governance agreements that enforce this -behaviour. +to after a Remove Commit. This includes superseded Group Keys, old +wrapped FKs, and any cached unwrapped FKs. Key-reuse mode SHOULD only +be used within formal federations with governance agreements that +enforce this behaviour. Two access-control layers. For an encrypted federation share, access is controlled at two independent layers: the per-server transport @@ -1769,25 +1883,24 @@ unwrapping once the re-wrapped FKs have arrived. Group Key retention window. Between processing a Commit and receiving the re-wrapped FKs for the new epoch (), a Member Server may retain the previous epoch's Group Key in order to keep -serving access requests. This retention slightly weakens forward -secrecy for the duration of the window: a server compromised during the -window exposes the previous epoch's Group Key in addition to the current -one. The window is bounded by the arrival of the re-wrapped FKs, and -Member Servers MUST delete the previous Group Key as soon as it is no -longer needed, or after a bounded time, whichever comes first. +serving access requests. This retention extends the lifetime of the +previous epoch's Group Key and therefore weakens forward secrecy for the +duration of the window. The window is bounded by the arrival of the +re-wrapped FKs, and Member Servers MUST delete the previous Group Key as +soon as it is no longer needed, or after a bounded time, whichever comes +first. Commit ordering. The Group Owner Server is the sole arbiter of Commits, eliminating conflicting Commits for the same epoch during -normal operation. A compromised or unavailable Group Owner Server can -stall epoch transitions, but it cannot decrypt resource content, and it -cannot cause the group to accept a Commit constructed by a non-admin -client, because every Member Server independently verifies the committer -against the admin set before processing a Commit (). The role -passes automatically to the next admin's server when the first admin -leaves the group (), and an unavailable arbiter is -eventually replaced through failover (), during which -conflicting Commits can briefly exist and are resolved -deterministically. +normal operation. An unavailable Group Owner Server can stall epoch +transitions, but the Delivery Service and network attackers cannot cause +the group to accept a Commit constructed by a non-admin client, because +every Member Server independently verifies the committer against the +admin set before processing a Commit (). The role passes +automatically to the next admin's server when the first admin leaves the +group (), and an unavailable arbiter is eventually replaced +through failover (), during which conflicting Commits can +briefly exist and are resolved deterministically. Forked-state retention. During a detected failover window, Member Servers retain the previous epoch's group state so that they can revert @@ -1798,13 +1911,12 @@ limited to servers that have observed the failover trigger. Rejoin. The rejoin procedure () lets a home server replace its own users' leaves with fresh KeyPackages on the strength of its HTTP -Signature alone, without per-request admin approval. This grants no new -capability: the home server is already the trust anchor for its own -users' KeyPackages and could substitute their keys at any time through -the ordinary KeyPackage endpoint. Because admin clients verify that a -rejoin only replaces leaves whose OCM Addresses name the requesting -server and that are already present in the ratchet tree, a rejoin can -never admit a new party. +Signature alone, without per-request admin approval. The procedure +relies on the home server's existing role as the Authentication Service +for its own users and therefore introduces no additional trust +assumption. Because admin clients verify that a rejoin only replaces +leaves whose OCM Addresses name the requesting server and that are +already present in the ratchet tree, a rejoin cannot admit a new party. Admin liveness and removal latency. A Remove proposal takes cryptographic effect only when an admin client commits it. Removing @@ -1852,15 +1964,20 @@ transport protection (TLS and HTTP Signatures [RFC9421]) prevents exposure to outside observers. Application Messages, which carry key material, are always encrypted as PrivateMessage. -Group membership privacy. The ratchet tree contains every member's -OCM Address and is held by every Member Server, so the full membership -of a group is visible to all servers that have a member in it. This is -inherent to the design - servers route shares and notifications using -exactly this information - but it sets the privacy baseline: federated -groups are not anonymous, and membership of a group is as visible to the -participating servers as membership of a shared folder. The tree is not -exposed to servers outside the group, and transport protection prevents -exposure to third parties. +Group membership and admin enumeration. The ratchet tree contains +the OCM Address of every group member, and the GroupContext contains the +group's admin set. This information forms part of the MLS group state +and its changes are conveyed in public handshake messages. Every group +member and every Member Server can therefore enumerate all members and +admins of the group and observe membership and admin-set changes over +time. This is an accepted privacy trade-off inherent to this design: +servers need the membership information to route shares and +notifications, resolve federation shares to local users, and enforce +admin policy. Federated groups do not provide anonymous membership or +hidden administrator roles. The information is not exposed by the +protocol to servers outside the group, although an authorized member or +Member Server can disclose it, and transport protection prevents +exposure to outside observers in transit. Admin set integrity. The admin set and the group's OCM Address are carried in the GroupContext (), so they are covered by the @@ -1890,6 +2007,24 @@ signed using HTTP Message Signatures [RFC9421] and SHOULD implement rate limiting and other access control methods on the /mls-key-packages endpoint to avoid user enumeration. +
+
Underlying Security Specifications + +This specification relies on the base Open Cloud Mesh protocol [OCM], +the Messaging Layer Security protocol [RFC9420], HTTP Message Signatures +[RFC9421], and JSON Web Keys and JWK Sets [RFC7517]. All security +considerations in those specifications apply to implementations of this +protocol. The security and privacy considerations of the MLS +architecture [RFC9750] also apply. + +Implementations using Virtual Clients additionally need to follow all +security considerations of [ietf-mls-virtual-clients], as required +above. Where this specification uses AEAD algorithms defined for HPKE, +the applicable algorithm and nonce-management considerations of +[RFC9180] apply, although this specification does not otherwise use the +HPKE construction. + +
IANA Considerations @@ -1918,19 +2053,18 @@ defined in [RFC9420] Section 17.3: The following notification types are to be registered in the "OCM Notification Types" registry defined in [OCM], within the "Open Cloud -Mesh (OCM) Parameters" group. All are group-scoped and therefore omit -the "providerId" field (see ): +Mesh (OCM) Parameters" group:
The following entry is to be registered in the "OCM Share Types" @@ -1963,6 +2097,19 @@ registrations do not modify the protocols' own registrations: +===============+============+=====================+===============+ ]]>
+The following entries are to be registered in the "OCM Encryption +Schemes" registry defined in [OCM], within the "Open Cloud Mesh (OCM) +Parameters" group: + +
+
Open Issues @@ -1997,6 +2144,14 @@ version in the IETF datatracker. It is meant to ease the review process and it shall be removed when going to RFC last call. The complete changelog is updated in the OCM-API GitHub repository. +
Version 02 + + Following the introduction of an encryption object for Shares in +Version 07 of [OCM] and a corresponding IANA Registry, this document +has been adapted and corresponding registry entries have been added. + + +
Version 01 Following the introduction of IANA Registries in Version 06 of [OCM], @@ -2015,6 +2170,11 @@ Cloud Mesh", Work in Progress, Internet-Draft. +[ietf-mls-virtual-clients] Alwen, J., Kohbrok, K., McMillion, B., +Mularczyk, M. and Robert, R. "MLS Virtual +Clients", +Work in Progress, Internet-Draft, draft-ietf-mls-virtual-clients-01. + [RFC2119] Bradner, S. "Key words for use in RFCs to Indicate Requirement Levels", March 1997. @@ -2044,6 +2204,11 @@ Signatures", February
Informative References +[RFC3552] Rescorla, E. and Korver, B. "Guidelines for Writing RFC Text +on Security +Considerations", BCP 72, +July 2003. + [RFC4918] Dusseault, L. M. "HTTP Extensions for Web Distributed Authoring and Versioning", June 2007. @@ -2080,676 +2245,721 @@ through the Tech Fund diff --git a/IETF-OCM.md b/IETF-OCM.md index c7fa7c2..16c62ff 100644 --- a/IETF-OCM.md +++ b/IETF-OCM.md @@ -1,6 +1,6 @@ --- title: 'Open Cloud Mesh' -docname: draft-ietf-ocm-open-cloud-mesh-06 +docname: draft-ietf-ocm-open-cloud-mesh-07 category: std ipr: trust200902 diff --git a/IETF-OCM.xml b/IETF-OCM.xml index a141f66..b39a122 100644 --- a/IETF-OCM.xml +++ b/IETF-OCM.xml @@ -1,6 +1,6 @@ - + - + Open Cloud Mesh @@ -45,7 +45,7 @@ - + Applications and Real-Time @@ -253,7 +253,8 @@ 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 +trusted server and the public keys (JWK Set [RFC7517]) used for +HTTP Message 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 @@ -645,8 +646,9 @@ The Sharing User MUST provide the following information: if the Receiving Server supports OCM if so, which version and with which optional functionality at which URL - the public key the Receiving Server will use for HTTP Signatures (if -any) + the public keys the Receiving Server will use for HTTP Message +Signatures (if any), published as a JWK Set at the URL given by the +jwksUri field The Sending Server MAY first perform denylist and allowlist checks on @@ -664,7 +666,10 @@ allowlisting. When OCM API Discovery can occur in preparation of a Share Creation Notification, the Sending Server takes on the 'Discovering Server' role -and the Receiving Server plays the role of 'Discoverable Server'. +and the Receiving Server plays the role of 'Discoverable Server'. +For a navigation index of discovery fields, capabilities, and related +informative aids, see Appendix E: Navigation +Index.
Process @@ -694,7 +699,7 @@ contain the following information about its OCM API: REQUIRED: enabled (boolean) - Whether the OCM service is enabled at this endpoint REQUIRED: apiVersion (string) - The OCM API version this endpoint -supports. Example: "1.4.0" +supports. Example: "1.5.0" REQUIRED: endPoint (string) - The URI of the OCM API available at this endpoint. Example: "https://cloud.example.org/ocm" OPTIONAL: provider (string) - A friendly branding name of this @@ -787,9 +792,9 @@ OCM Server acts as Sending Server, it hosts tokenEndPoint "http-sig" - to indicate that this OCM Server supports -[RFC9421] HTTP Message Signatures and advertises public keys in the -format specified by [RFC7517] at the /.well-known/jwks.json -endpoint for signature verification. +[RFC9421] HTTP Message Signatures and advertises the public keys +for signature verification, in the format specified by [RFC7517], +at the URL given by the jwksUri field. "invites" - to indicate the server would support acting as an Invite Sender or Invite Receiver OCM Server. This might be useful for suggesting to a user that existing contacts might be upgraded @@ -819,7 +824,11 @@ the requirements of each protocol offered for access will be rejected. An OCM Server advertising this criterium MUST also expose the exchange-token capability. See the Code Flow -section. +section. +Informative: The string must-exchange-token also appears in +protocol.*.requirements[] on outbound shares. The binding between +receiver criteria[] and sender requirements[] is defined in +Share Creation Notification. "denylist" - some servers MAY be blocked based on their IP address "allowlist" - unknown servers MAY be blocked based on their IP @@ -836,6 +845,15 @@ enhance the UX of the Invite Flow. If for example "/index.php/apps/sciencemesh/accept" is specified here then a WAYF Page SHOULD redirect the end-user to /index.php/apps/sciencemesh/ accept?token=zi5kooKu3ivohr9a&providerDomain=cloud.example.org. + OPTIONAL: jwksUri (string) - URL of a JWK Set document [RFC7517] +containing the public keys this OCM Server uses for HTTP Message +Signatures. The URL MUST use HTTPS and is discovered from this field. +It MAY refer to a different host, not necessarily to the same OCM +Server; it is not a fixed path in the OCM API. Implementations that +advertise the "http-sig" capability MUST provide this URL as well. +As with the Discovery Process, implementations MAY fallback to HTTP +instead of HTTPS in testing setups. +Example: "https://cloud.example.org/ocm/jwks". OPTIONAL: tokenEndPoint (string) - URL of the token endpoint hosted by this OCM Server. When this OCM Server acts as Sending Server, the Receiving Server POSTs here to exchange a sharedSecret for a @@ -854,9 +872,10 @@ described in the respective sections. This section specifies the normative requirements for producing and verifying those signatures. Appendix B contains a complete example. -Public keys for signature verification are published in the format -specified by [RFC7517] at the signer's /.well-known/jwks.json -endpoint, if the http-sig capability is included in the +Public keys for signature verification are distributed as follows: +an OCM Server that advertises the http-sig capability MUST +publish its public keys as a JWK Set [RFC7517] at the URL +advertised in the jwksUri field of its Discovery response.
Applicability @@ -902,12 +921,19 @@ components: "content-length" - message size -The Signature-Input parameters MUST include created. Freshness and -replay protection are anchored on created (see Verification -Requirements). +The signature parameters MUST include created and keyid. +Freshness is anchored on created (see Verification Requirements); +created bounds how long a captured signature stays acceptable, but +does not by itself detect replay within that window (see Section +7.2.2 of [RFC9421]). The keyid value MUST be equal to the +kid value of the corresponding key in the signer's JWK Set (see +Keys and Algorithms). -A signed request SHOULD additionally cover the date component when a -Date header is present. +The Date header is deliberately not covered by the signature: +intermediaries sometimes rewrite it (see Section 6.6.1 of [RFC9110]), +which would make signatures fragile, and the created signature +parameter already conveys the message's creation time (see +Section 7.2.4 of [RFC9421]). The content-digest component binds the request body to the signature, protecting it against modification in transit. Its value MUST use a @@ -924,18 +950,58 @@ of the signature base and is therefore integrity-protected. tag="ocm". The signature label MAY be any value; it is not significant to OCM processing. -The signature MUST use an asymmetric algorithm from the IANA "HTTP -Signature Algorithms" registry [IANA-SIG-ALG]; ed25519 [RFC8032] is -RECOMMENDED. A symmetric algorithm, such as the HMAC-based -hmac-sha256, MUST NOT be used, as the Receiving Server would not be -able to verify the signature without prior access to the shared secret. +The signature algorithm is determined by the signing key material; +see Keys and Algorithms. + +
+
Keys and Algorithms + +Each key published in the signer's JWK Set MUST include the kid +and alg parameters [RFC7517]. The JWK alg value MUST identify +an asymmetric signature algorithm registered in the IANA "JSON Web +Signature and Encryption Algorithms" registry [RFC7518], and SHOULD +be a fully-specified algorithm [RFC9864]; Ed25519 ([RFC8032], +[RFC9864]) is RECOMMENDED. + +The signature algorithm is derived from the key material rather +than declared by the message: signers and verifiers MUST determine +the algorithm from the alg parameter of the JWK identified by the +keyid signature parameter, and apply it to the signature base as +specified in Section 3.3.7 of [RFC9421]. + +This way, implementations are neither restricted to the algorithms +listed in the IANA "HTTP Signature Algorithms" registry +(Section 6.2 of [RFC9421]), nor is an update to this document +needed as new algorithms, for example post-quantum ones, are +registered for JOSE: as noted in that section, an application is +free to use any algorithm provided the signer and verifier can +agree on it in a secure and deterministic fashion, and the JWK +alg parameter provides that agreement. + +The JWS algorithm none and symmetric MAC algorithms, such as +HS256, MUST NOT be used: the former provides no protection, while +the latter would require the verifier to have prior access to a +shared secret. + +The alg signature parameter is OPTIONAL: the algorithm is always +determined by the JWK, as described above. Note that this +parameter takes its values from a different registry than the JWK +alg value. If the parameter is present, the algorithm it names +in the IANA "HTTP Signature Algorithms" registry [IANA-SIG-ALG] +MUST denote the same algorithm as the JWK alg value, for +example, ed25519 for a JWK with alg Ed25519, and verifiers +MUST reject the signature otherwise +(see Section 7 of [RFC9421] on algorithm confusion and substitution +attacks). When the JWK algorithm has no counterpart in that +registry, the alg signature parameter MUST be omitted.
Verification Requirements Verifiers MUST reject signatures that omit any of the mandatory -components listed under Signing Requirements or the created -parameter, and MUST reject signatures whose created value is more +components listed under Signing Requirements or the created or +keyid parameters, and MUST reject signatures whose created value +is more than a small implementation-defined skew tolerance in the future, or older than the verifier's freshness window. @@ -943,6 +1009,13 @@ older than the verifier's freshness window. every recognised digest match the body; a single match alongside a recognised mismatch MUST be treated as an integrity failure. +Verifiers MUST reject a signature if the signer's JWK Set contains +no key whose kid equals the keyid parameter, if the JWK +identified by keyid does not carry an acceptable alg value (see +Keys and Algorithms), or if an alg +signature parameter is present and does not correspond to the +algorithm derived from that JWK. + Verifiers MUST identify the OCM signature by its tag="ocm" parameter, examining the parameters of each member of the Signature-Input field and disregarding the dictionary labels. @@ -955,6 +1028,46 @@ discretion, or rejected when the receiver advertises proxy-attached signatures) but verifiers MUST NOT process them as part of OCM signature processing. +After successful signature verification, the verifier SHOULD confirm +that the payload is consistent with the signer, i.e. that the +actions implied by the payload were initiated on behalf of the +origin of the request. + +
+
Signing Direction Index + +This subsection is informative. HTTP Message Signatures apply only +when the peer advertises the http-sig capability; a +must-use-http-sig criterion makes signing mandatory for inbound +traffic. When signing is in play, the signer and verifier roles are: + + + Share Creation Notification (POST /shares) - the Sending +Server signs; the Receiving Server verifies. See +Share Creation Notification, +Decision to Discard, and HTTP Message +Signatures. + Token Request (POST {tokenEndPoint}) - the Receiving Server +signs; the Sending Server verifies. See Token +Request, Token Response, and +HTTP Message Signatures. + Invite Acceptance (POST /invite-accepted) - the Invite Receiver +signs; the Invite Sender verifies. See Invite Flow +and HTTP Message Signatures. + Request for a Share (POST /request-share) - the Requesting +Server signs; the Requested Server verifies. See Request for a +Share and HTTP Message +Signatures. + Share Acceptance Notification (POST /notifications) - the +Receiving Server signs; the Sending Server verifies. See Share +Acceptance Notification and HTTP +Message Signatures. + Sender-initiated Notification (POST /notifications) - the +Sending Server SHOULD sign; the Receiving Server verifies. See +Share Acceptance Notification and +HTTP Message Signatures. + +
Share Creation Notification @@ -1072,6 +1185,29 @@ of UTC time since Unix epoch. If omitted, it is assumed that the share does not expire. A sender server MAY use it to signal that the resource represents a cached copy of a dataset that was made available for an efficient data transfer to the destination server. + OPTIONAL encryption (object) +Optional JSON object with encryption information for the share. If +omitted, it is assumed that the resource is not encrypted. For +encrypted resources, the actual key material is to be exchanged out +of band, and this object MUST include: + + REQUIRED resourceId (string) - a unique identifier of the +underlying resource. + REQUIRED scheme (string) - an identifier of the encryption scheme +used to encrypt the resource, such as "ocm-pgp". Registered values +are listed in the "OCM Encryption Schemes" registry (see +IANA Considerations). + REQUIRED {schemeObject} (object) - an object keyed with the given +scheme, containing the details of the encryption used. +For the "ocm-gpg" scheme, it MUST contain: + + fingerprints (array of strings) - one or more fingerprints of +the public keys used to encrypt the resource. +For the "ocm-mls" scheme, it MUST contain: + cipher (string) - the encryption algorithm used to encrypt the +resource as in [RFC9180] Section 7.3. + + REQUIRED protocol (object) JSON object with specific options for each protocol. The supported protocols are: @@ -1093,7 +1229,7 @@ and put the protocol details in a field carrying the name of the protocol. Option 3: Set the name field to multi, and put the protocol details in a field carrying the name of the protocol. -Option 1 using the options field is now deprecated. +Option 1 using the options field is deprecated. Implementations are encouraged to transition to the new optional properties defined below, such that this field may be removed in a future major version of the spec. @@ -1106,7 +1242,7 @@ Otherwise, at least webdav is expected to be supported, and its options MAY be given in the opaque options payload for compatibility with v1.0 implementations (see examples). Note though that this -format is deprecated. +format is deprecated. Warning: client implementers should be aware that v1.1+ servers MAY support both webdav and multi, but v1.0 servers MAY only support webdav. @@ -1290,16 +1426,21 @@ A 503 response status means that the Receiver is temporary unavailable. 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 - the HTTP Signature is missing - the HTTP Signature is not valid - no keypair is trusted or discoverable from the FQDN part of the -sender field in the request body - the keypair used to generate the HTTP Signature doesn't match the one -trusted or discoverable from the FQDN part of the sender field -in the request body + the HTTP Message Signature is missing but the Sending Server +advertises the http-sig capability in the Discovery response +obtained from the FQDN part of the sender field in the request +body + the Sending Server advertises the http-sig capability but its +Discovery response carries no jwksUri + the HTTP Message Signature is missing + the HTTP Message Signature is not valid (see HTTP Message +Signatures) + no trusted JWK Set can be obtained for the FQDN part of the +sender field in the request body, via the jwksUri field of its +Discovery response + that JWK Set contains no key whose kid equals the keyid +signature parameter (see HTTP Message +Signatures) the Sending Server is denylisted the Sending Server is not allowlisted the Sending Party is not trusted by the Receiving Party (e.g., no @@ -1325,105 +1466,200 @@ notification that this happened.
-
Request for a Share +
Notifications + +This optional endpoint is used to inform the other party about a change +that concerns a previously known entity, such as a Resource or a +trusted Share type (e.g. a user). -If the Receiving Party knows of a resource that has not yet -been shared, the Receiving Party MAY request that it be shared. -Such a Request for a Share MUST be an HTTP POST request +A Server that intends to send a notification SHOULD make a HTTP POST +request: - to the /request-share path in the Sending Server's OCM API - using application/json as the Content-Type HTTP request -header - its request body containing a JSON document representing an -object with the fields as described below + to the /notifications path in the Receiving Server's OCM API + using application/json as the Content-Type HTTP request header + its request body containing a JSON document representing an object +with the fields as described below using TLS + using httpsig [RFC9421] -When HTTP Message Signatures are available, the Request for a Share -MUST be signed and verified as described in HTTP Message -Signatures. As requesting access to a -restricted resource relies on authenticating the requester, -implementations SHOULD NOT use this feature unless signing is -available. -
Fields - REQUIRED owner (string) -OCM Address of the user who will be requested to share the resource. - REQUIRED shareWith (string) -OCM Address of the user or group that wants to receive a share of -the resource. -Example: "51dc30ddc473d43a6011e9ebba6ca770@cloud.example.org" - REQUIRED share (string) -A unique identifier for the resource. -Example: 1234567890abcdef or https://cloud.example.org/files/data.txt + REQUIRED notificationType (string) - it MUST be one of the +registered values listed in the "OCM Notification Types" +registry (see IANA Considerations). + REQUIRED senderDomain (string) - the FQDN of the sender. A Receiving +Server SHOULD use this information to verify the HTTP message +signature on the request, and it SHOULD also use it to validate the +underlying share or resource the notification is about. + OPTIONAL resourceType (string) - the type of the resource this +notification is about (e.g., file). + OPTIONAL shareType (string) - the type of recipient this notification +is about (e.g., user). + OPTIONAL providerId (string) - the identifier assigned by the +Sending Server to the underlying share, if applicable. This +field is deprecated and SHOULD NOT be used. + OPTIONAL notification (object) - optional additional parameters, +depending on the notification and the resource type. -Any HTTP Signature on the Request for a Share is verified as described -in HTTP Message Signatures before the -Sending Server acts on it. - -After receiving a request for a Share, the Sending Party MAY -send a Share Creation Notification to the Receiving Party -using the OCM address in the shareWith field. +A Notification payload MUST include either the resourceType or the +shareType, or both when relevant. Multiple Notification types are +defined for different purposes, and additional types MAY be defined +by implementers and registered in the "OCM Notification Types" IANA +Registry. For each notification type, a specific format MAY be defined +for the optional notification object. In the sections below, the base +Notification types are detailed along with their specific payload.
-
-
Share Acceptance Notification - -In response to a Share Creation Notification, the Receiving Server MAY -discover the OCM API of the Sending Server, starting from the <fqdn> -part of the sender field in the Share Creation Notification. - -If the OCM API of the Sending Server is successfully discovered, the -Receiving Server MAY make a HTTP POST request - - - to the /notifications path in the Sending Server's OCM API - using application/json as the Content-Type HTTP request header - its request body containing a JSON document representing an object -with the fields as described below - using TLS - using httpsig [RFC9421] - +
Share Acceptance and Updating + +A notification MAY be sent by a recipient to let the provider know that +the recipient accepted or declined a share, in response to a Share +Creation Notification. Similarly, it MAY be sent by a provider to let +the recipient know that the provider updated or removed a given share, +such that the recipient MAY clean it up from its database. In all such +cases, the resourceType MUST match the resourceType of the +underlying share (e.g., file), the shareType MAY be omitted but if +present it MUST match the shareType of the underlying share, and the +notificationType MUST be one of: +- "SHARE_ACCEPTED", to inform about the acceptance of a share. +- "SHARE_DECLINED", to inform that a share was not accepted. +- "SHARE_UNSHARED", to inform the Receiving Server that the share + was removed and is not accessible any longer. +- "SHARE_CHANGE_PERMISSION", to inform the Receiving Server that + the permissions of a share were updated. +Further, the notification object MUST include the following fields: +* OPTIONAL message (string) - an optional human-readable message that + describes the event. +* REQUIRED file (object) - an object containing the details of the + event, including: + * REQUIRED providerId (string) - the unique identifier assigned + by the Sending Server to the underlying share in a previous Share + Creation Notification. + * OPTIONAL permissions (array of strings) - The permissions granted + to the sharee, in case they have changed in the context of a + SHARE_CHANGE_PERMISSION notification. The allowed values match + the permissions values specified in the webdav protocol of a + Share Creation Notification. + +The same notifications identically apply to resources of type folder. +For other resources with a different resourceType attribute, a +Sending Server MAY implement the same notifications, provided that +they get registered in the related IANA Registry. Note that the +Sending Server MAY at any time revoke access to a Resource (effectively +undoing or deleting the Share) without notifying the Receiving Server. -
Fields +
+
Resharing and Request to Share + +The "REQUEST_RESHARE" notification type MAY be used by the Receiving +Server to ask the Sending Server to share a given, previously shared +Resource, with another third Receiving Party. The Sending Server MAY +discard this request, e.g. in case the third party is not trusted, or +the share was originally granted without a share permission. If +the Sending Server accepts the request, it MUST create a new share to +the third party: in this case, all necessary exchanges and access +requests MUST take place between the third party and the Sending +Server, without further including the Receiving Server in the process. + +For a "REQUEST_RESHARE" notification, the resourceType MUST match the +resourceType of the original share (e.g., file, folder, ...), the +shareType MAY be omitted but if present it MUST match the shareType +of the original share, and the the notification object MUST include +the following fields: +* OPTIONAL message (string) - an optional human-readable message that + describes the request. +* REQUIRED file (object) - an object containing the details of the + request, including: + * REQUIRED providerId (string) - the unique identifier assigned + by the Sending Server to the underlying share in a previous Share + Creation Notification. + * REQUIRED shareWith (string) - the OCM Address of the third party + the underlying share should be reshared with. + * OPTIONAL permissions (array of strings) - The permissions to be + granted to the third party. The allowed values match the + permissions values specified in the webdav protocol of a + Share Creation Notification. + +The Receiving Server SHOULD receive a response whether the reshare +request was fulfilled or not. In any case, a Receiving Server MUST +NOT directly reshare a Resource, even when a share permission was +granted, and MUST always send a "REQUEST_RESHARE" Notification +to the Sending Server. + +Similarly, the "REQUEST_SHARE" notification type MAY be used by a +given Recipient OCM Server, to ask a remote OCM Server to share and +grant access to a Resource, previously made known to the Recipient +Server out of band. In this case, the resourceType MUST match the +resourceType of the Resource in question (e.g., file, folder, +...), the shareType MUST be omitted, and the notification object +MUST include the following fields: - REQUIRED notificationType (string) - in a Share Acceptance -Notification it MUST be one of: + OPTIONAL message (string) - an optional human-readable message that +describes the request. + REQUIRED file (object) - an object containing the details of the +request, including: - 'SHARE_ACCEPTED' - 'SHARE_DECLINED' -Registered values are listed in the "OCM Notification Types" -registry (see IANA Considerations). + REQUIRED owner (string) - OCM Address of the user who will be +requested to share the resource. + REQUIRED shareWith (string) - OCM Address of the recipient that +wishes to receive a share of the resource. +Example: "51dc30ddc473d43a6011e9ebba6ca770@cloud.example.org" + REQUIRED shareId (string) - A unique identifier for the resource. +Example: https://cloud.example.org/files/data.txt or +1234567890abcdef. + REQUIRED permissions (array of strings) - The permissions to be +granted to the requesting party. The allowed values match the +permissions values specified in the webdav protocol of a +Share Creation Notification. - REQUIRED providerId (string) - copied from the Share Creation -Notification for the Share this notification is about - OPTIONAL resourceType (string) - copied from the Share Creation -Notification for the Share this notification is about - OPTIONAL notification (object) - optional additional parameters, -depending on the notification and the resource type -For example, a notification MAY be sent by a recipient to let the -provider know that the recipient declined a share. In this case, the -provider site MAY mark the share as declined for its user(s). -Similarly, it MAY be sent by a provider to let the recipient know that -the provider removed a given share, such that the recipient MAY clean -it up from its database. A notification MAY also be sent to let a -recipient know that the provider removed that recipient from the list -of trusted users, along with any related share. The recipient MAY -reciprocally remove that provider from the list of trusted users, along -with any related share. +The remote OCM Server MAY choose to fulfill the request, according +to its trust policies: in that case, it MUST respond with HTTP 201 +to the caller, and asynchronously ask for permission to the owner +user. If the owner agrees, it MUST send a +Share Creation Notification including +the shareWith user as recipient, whereas if the owner disagrees, +it MUST send back a "SHARE_DECLINED" notification. The remote OCM +Server MAY also decline such request because of its policies, without +even informing the owner: in this case, it MUST respond to the +"REQUEST_SHARE" notification with an appropriate HTTP response type +such as HTTP 404. -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 -notification is coming from. +
+
Recipient Removal + +A notification MAY be sent to inform a target OCM Server that a share +recipient (e.g. a user or group) was removed from the list of trusted +users, following a previous successful Invitation, or otherwise left +the system. That recipient may have been previously known to the +target server because of existing shares whose shareType matched it. +The recipient of such notification MAY reciprocally remove that +recipient from the list of trusted users, along with any related +shares. + +For these cases, a notification payload is to be formed such that the +resourceType MUST be omitted, the shareType is set to the affected +shareType being removed, such as user or group, and the +notificationType MUST be one of: +- "USER_REMOVED", to inform about a single user that was removed or + marked as not trusted. +- "GROUP_REMOVED", to inform about a removed group. +Further, the notification object MUST include the following fields: +* OPTIONAL message (string) - an optional human-readable message that + describes the event. +* REQUIRED user or group (object) - an object containing the details + of the recipient to be removed. In case of user, it MUST include: + * REQUIRED userId (string) - OCM Address of the user to be removed + from the target OCM Server. + Whereas in case of group, it MUST include: + * REQUIRED groupId (string) - identifier of the group to be removed + from the target OCM Server.
@@ -1528,28 +1764,24 @@ No user interaction or redirect is involved. [RFC6749] request to the Sending Server’s {tokenEndPoint} as discovered in the OCM provider metadata, following section 4.4.2 of [RFC6749]. The request payload MUST be in x-www-form-urlencoded form, as shown -in the following example (with line breaks in the Signature headers -for display purposes only): +in the following example: +NOTE: '\' line wrapping per RFC 8792 + POST {tokenEndPoint} HTTP/1.1 Host: cloud.example.org -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: - sig1=("@method" "@target-uri" "content-digest" "date"); - created=1730815200; - keyid="receiver.example.org#key1"; - alg="ed25519"; - tag="ocm" -Signature: sig1=:bM2sV2a4oM8pWc4Q8r9Zb8bQ7a2vH1kR9xT0yJ3uE4wO5lV6bZ1cP - 2rN3qD4tR5hC=: - -grant_type=authorization_code& -client_id=receiver.example.org& -code=my_secret_code +Content-Digest: sha-256=:81kCnlO5UY/mZ8UgpxBWnq18GY3WhzJnDjOTvSvjbhw=: +Content-Length: 80 +Signature-Input: sig1=("@method" "@target-uri" "content-digest" \ + "content-length");created=1730815200;\ + keyid="receiver.example.org#key1";alg="ed25519";tag="ocm" +Signature: sig1=:bM2sV2a4oM8pWc4Q8r9Zb8bQ7a2vH1kR9xT0yJ3uE4wO5lV6bZ\ + 1cP2rN3qD4tR5hC=: + +grant_type=authorization_code&client_id=receiver.example.org&code=\ + my_secret_code The request MUST be signed using an HTTP Message Signature @@ -1660,40 +1892,6 @@ still choosing a legacy-compatible outbound share.
-
-
Share Deletion - -A "SHARE_ACCEPTED" notification followed by a "SHARE_UNSHARED" -notification is equivalent to a "SHARE_DECLINED" notification. - -Note that the Sending Server MAY at any time revoke access to a -Resource (effectively undoing or deleting the Share) without notifying -the Receiving Server. - -
-
Share Updating - -Some implementations have experimented with a -"RESHARE_CHANGE_PERMISSION"notification, but the payload and side -effects such a notification may have are out of scope of this version -of this specification. -The Receiving Party sending such a notification has no way of knowing -if the Sending Party understood and processed the reshare request -or not. - -
-
Resharing - -The "REQUEST_RESHARE" and "RESHARE_UNDO" notification types MAY be -used by the Receiving Server to persuade the Sending Server to share the -same Resource with another Receiving Party. -The details of the payload and side effects such a notification may -have are out of scope of this version of this specification. -Note that the Receiving Party sending such a notification has no way of -knowing if the Sending Party understood and processed the reshare -request or not. In all cases, the Receiving Server MUST NOT reshare -a Resource without an explicit grant from the Sending Server. -
IANA Considerations @@ -1886,7 +2084,6 @@ policy for each registry in this group is "Specification Required" is documented in a stable, publicly available specification and that it does not duplicate an existing entry. -
OCM Resource Types Registry IANA is requested to create the "OCM Resource Types" registry in the @@ -2028,33 +2225,100 @@ interoperable way, they can do so using this very mechanism. the "Open Cloud Mesh (OCM) Parameters" group. This registry records the values that MAY appear in the "notificationType" field of an OCM notification sent to the "/notifications" endpoint (see -Share Acceptance Notification). +). -The "Scope" field indicates whether the notification refers to a Share, -in which case the "providerId" field is REQUIRED, or to a Group. The -"Status" field is one of "active" or "experimental". +The "Scope" field indicates whether the notification refers to a +Resource, in which case the "providerId" field is REQUIRED in the +payload, or to a Recipient, i.e. to the shareType in a +Share Creation Notification, in which +case a corresponding identifier such as "userId" is REQUIRED in the +payload. Registration Policy: Specification Required [RFC8126] Initial Contents:
+
+
OCM Encryption Schemes Registry + +IANA is requested to create the "OCM Encryption Schemes" registry in +the "Open Cloud Mesh (OCM) Parameters" group. This registry records +the values that MAY appear in the "encryption.scheme" field of a +Share Creation Notification. + +Registration Policy: Specification Required [RFC8126] + +Initial Contents: + +
+ +
Security Considerations +
Threat Model + +The threat model follows the Internet threat model described in +[RFC3552]. It assumes that the Sending Server and Receiving Server +participating in an OCM exchange have not been compromised. Their +administrative interfaces, host operating systems, private keys, +credentials, and underlying storage are part of the trusted endpoints. +Compromise of either endpoint or its trusted infrastructure is outside +the scope of this specification. + +An attacker is assumed to have extensive control of the communication +channel and may observe, block, replay, insert, or modify traffic. TLS +and, where used, HTTP Message Signatures provide the protections +described in this specification against such a network attacker. + +An attacker may operate an OCM Server of their own, control a remote +user, send malformed or deceptive protocol messages, or steal bearer +credentials. An attacker-controlled server can make arbitrary +assertions under its own identity, but must not thereby gain authority +for users or Resources outside its administrative domain. +Implementations are expected to authenticate peers where required, +enforce local authorization policies, validate protocol inputs, and +protect credentials. + +Trust in one OCM Server does not imply trust in every OCM Server. A +TLS and HTTP Message Signatures permit attribution to the server +controlling the relevant credentials, but do not establish that its +assertions are truthful or that supplied content is safe. Resource +names, descriptions, URIs, metadata, and Resource contents received from +another server remain untrusted input and need to be handled according +to local security policy. + +A malicious or unavailable peer can refuse to deliver notifications or +Resources and can attempt to exhaust network, processing, or storage +capacity. The protocol cannot guarantee availability when a necessary +peer refuses service. Implementations should nevertheless apply +appropriate timeouts, request and response size limits, rate limits, +quotas, and concurrency limits to contain such failures. + +
Trust There are several areas that are not covered by this specification. @@ -2092,10 +2356,24 @@ 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. As with the Discovery Process, +implementations MAY fallback to HTTP instead of HTTPS in testing +setups. Bearer tokens MUST be treated as confidential and never logged, persisted beyond their lifetime, or transmitted over unsecured channels. +
+
Underlying Security Specifications + +This specification relies on HTTP Message Signatures [RFC9421], JSON +Web Keys and JWK Sets [RFC7517], and Digest Fields [RFC9530]. All +security considerations in those specifications apply to +implementations of OCM. Implementers need to consider those +specifications together: a message signature is only as trustworthy as +the provenance and protection of its verification key, and signing a +Content-Digest field provides content integrity only when both the +signature and digest are correctly validated. +
Copying conditions @@ -2142,6 +2420,8 @@ Specifications and Registration Procedures [RFC7517] Jones, M., "JSON Web Key (JWK)", May 2015. +[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", May 2015. + [RFC8032] Josefsson, S., Liusvaara, I., "Edwards-Curve Digital Signature Algorithm (EdDSA)", January 2017. @@ -2154,6 +2434,10 @@ Key Words", May 2017. [RFC8615] Nottingham, M. "Well-Known Uniform Resource Identifiers (URIs)", May 2019 +[RFC9110] Fielding, R., Nottingham, M. and Reschke, J. "HTTP +Semantics", +June 2022. + [RFC9421] Backman, A., Richer, J. and Sporny, M. "HTTP Message Signatures", February 2024. @@ -2162,9 +2446,23 @@ Signatures", February 2024. [RFC9553] Stepanek, R., Loffredo, M., "JSContact: A JSON Representation of Contact Data, May 2024" +[RFC9864] Jones, M., Steele, O., "Fully-Specified Algorithms for +JSON Object Signing and Encryption (JOSE) and CBOR Object Signing +and Encryption (COSE)", +October 2025. + +[RFC9180] Barnes, R., Bhargavan, K., Lipp, B. and Wood, C. A. "Hybrid +Public Key Encryption", +February 2022. +
Informative References +[RFC3552] Rescorla, E. and Korver, B. "Guidelines for Writing RFC Text +on Security +Considerations", BCP 72, +July 2003. + [OCM-IP] Nordin, M., Lo Presti, G., and Baghbani, M. "Open Cloud Mesh Integration Protocol", @@ -2175,6 +2473,9 @@ in Open Cloud Mesh using Messaging Layer Security", Work in Progress, Internet-Draft. +[RFC8792] Watsen, K., Auerswald, E., Farrel, A., Wu, Q., "Handling +Long Lines in Content of Internet-Drafts and RFCs", June 2020. +
Appendix A: Multi-factor Authentication @@ -2203,12 +2504,15 @@ out of scope for this specification: a mechanism similar to the
Appendix B: JWKS and HTTP Signature Examples -
JWKS Endpoint +This appendix is informative. + +
Published JWK Set -An OCM Server that advertises the http-sig capability MUST expose its -public keys at /.well-known/jwks.json in the format specified by -[RFC7517]. Here is an example response from -https://sender.example.org/.well-known/jwks.json: +An OCM Server that advertises the http-sig capability publishes +its public keys, in the format specified by [RFC7517], at the URL +advertised in the jwksUri field of its Discovery response (see +HTTP Message Signatures). Here is +an example response from https://sender.example.org/ocm/jwks:
/.well-known/jwks.json in the format { "kty": "OKP", "crv": "Ed25519", + "alg": "Ed25519", "kid": "sender.example.org#key1", - "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" + "x": "AzeStPAdQ-vbi6bJVxcQjBPF2I7fDZdfDZ_XZ3J4Azs" } ] } @@ -2231,9 +2536,9 @@ public keys at /.well-known/jwks.json in the format POST /ocm/shares HTTP/1.1 Host: receiver.example.org -Date: Fri, 16 Jan 2026 13:37:00 GMT Content-Type: application/json -Content-Digest: sha-256=:LkpHyFOVbBDPxc7YbHDOWNzAv88qWuVfLNf4TUf9Uo8=: +Content-Digest: sha-256=:/Uz47cfD1HOdMTIqcWjd84iMLQ4gVJdC7ZFACf1ViqU=: +Content-Length: 521 { "shareWith": "marie@receiver.example.org", @@ -2256,46 +2561,40 @@ Content-Digest: sha-256=:LkpHyFOVbBDPxc7YbHDOWNzAv88qWuVfLNf4TUf9Uo8=: } -The signature base is constructed according to [RFC9421] (with line -breaks in @signature-params for display purposes only): +The signature base is constructed according to [RFC9421]: +NOTE: '\' line wrapping per RFC 8792 + "@method": POST "@target-uri": https://receiver.example.org/ocm/shares -"content-digest": sha-256=:[digest-value]: -"content-length": [body-length] -"date": [date] -"@signature-params": ("@method" "@target-uri" "content-digest" - "content-length" "date"); - created=[timestamp]; - keyid="sender.example.org#key1"; - alg="ed25519"; - tag="ocm" +"content-digest": sha-256=:/Uz47cfD1HOdMTIqcWjd84iMLQ4gVJdC7ZFACf1ViqU=: +"content-length": 521 +"@signature-params": ("@method" "@target-uri" "content-digest" \ + "content-length");created=1785060500;\ + keyid="sender.example.org#key1";alg="ed25519";tag="ocm" Sign this base using for example Ed25519 ([RFC8032]) to produce the -signature, and then add headers (line breaks for display purposes -only). Note that the dictionary label (sig1 below) is arbitrary; the -signature is marked as belonging to OCM by its tag="ocm" parameter, -which is part of the signature base above: +signature, and then add headers. Note that the dictionary label +(sig1 below) is arbitrary; the signature is marked as belonging +to OCM by its tag="ocm" parameter, which is part of the signature +base above: -Content-Digest: sha-256=:[digest-value]: -Content-Length: [body-length] -Date: [date] -Signature-Input: sig1=("@method" "@target-uri" "content-digest" - "content-length" "date"); - created=[timestamp]; - keyid="sender.example.org#key1"; - alg="ed25519"; - tag="ocm" -Signature: sig1=:[signature-value]=: +NOTE: '\' line wrapping per RFC 8792 + +Content-Digest: sha-256=:/Uz47cfD1HOdMTIqcWjd84iMLQ4gVJdC7ZFACf1ViqU=: +Content-Length: 521 +Signature-Input: sig1=("@method" "@target-uri" "content-digest" \ + "content-length");created=1785060500;\ + keyid="sender.example.org#key1";alg="ed25519";tag="ocm" +Signature: sig1=:Epax4XFqvbrrDzQUAaNl+uECasEKbArgz8AlEkXspvYX2fSkQFlC\ + kaXImZnYU898C2t0IdmbFhjR8bkN0hZgCg==: -The covered components, the created parameter, the single ocm -tag, and the prohibition on symmetric algorithms shown here are -normative; see HTTP Message Signatures for -the full requirements. +See HTTP Message Signatures for the +normative requirements illustrated by this example.
Verifying a Signature (Receiver) @@ -2307,8 +2606,13 @@ illustrates the procedure to verify an incoming signed request: Extract the provider domain from the sender field in the request body - Fetch the public key from -https://<provider-domain>/.well-known/jwks.json + Fetch the Discovery response from +https://<provider-domain>/.well-known/ocm and read its +jwksUri field. If the Sending Server advertises the http-sig +capability but no jwksUri is present, the receiver can discard +the notification, as described in Decision to +Discard + Fetch the public keys from the URL given by jwksUri Locate the unique signature carrying the tag="ocm" parameter in the Signature-Input header, disregarding its dictionary label (here sig1) @@ -2316,17 +2620,19 @@ the Signature-Input header, disregarding its diction matching the kid value in the [RFC7517] response Reconstruct the signature base from the request using the components listed in Signature-Input as specified in [RFC9421] - Verify the signature using the appropriate algorithm -(e.g., Ed25519 [RFC8032]) + Verify the signature using the algorithm derived from the alg +value of that JWK (e.g., Ed25519 [RFC8032]), as described under +Keys and Algorithms in +HTTP Message Signatures
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. +Following the validation of the signature, the host also confirms +the validity of the payload, as specified under Verification +Requirements in +HTTP Message Signatures. 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 @@ -2614,7 +2920,7 @@ that section. apiVersion: Version string of supported OCM API capabilities: Optional features supported - criteria: Requirements for accepting Share Creation Notifications + criteria: Criteria for accepting a Share Creation Notification enabled: Boolean indicating if OCM service is active endPoint: Base URI for OCM API endpoints provider: Friendly branding name @@ -2789,6 +3095,33 @@ to model a few key properties.
+
+
Appendix E: Navigation Index + +This appendix is informative. It points to normative sections and +informative aids; it introduces no new rules. + + + Discovery fields - OCM API Discovery, + + Capabilities - advertised in capabilities[]; see OCM API +Discovery + Criteria - advertised in criteria[] as inbound admission gates; +see OCM API Discovery + Per-share requirements - in protocol.*.requirements[]; see +Share Creation Notification + Per-share protocol shape - in protocol.* fields; see Share +Creation Notification + Same-string note - must-exchange-token in OCM API +Discovery criteria and in share +protocol.*.requirements[] + Signing - HTTP Message Signatures, +Signing Direction Index + Object models - Appendix D: Object +models + Informative diagrams - in the OCM-API repository under diagrams/ + +
Changes @@ -2797,6 +3130,48 @@ version in the IETF datatracker. It is meant to ease the review process and it shall be removed when going to RFC last call. The complete changelog is updated in the OCM-API GitHub repository. +
Version 07 + + Required the keyid signature parameter and that it matches the +kid of the verification key in the signer's JWK Set. + The HTTP Message Signature algorithm is now derived from the JWK +identified by keyid, per Section 3.3.7 of [RFC9421], instead of +being restricted to the "HTTP Signature Algorithms" registry; the +alg signature parameter is optional and checked for consistency. + Replaced the unregistered /.well-known/jwks.json endpoint with a +jwksUri field in the Discovery response, from which the location +of the JWK Set for HTTP Message Signatures is discovered. + The Date header is no longer covered by signatures: freshness is +anchored on the created signature parameter (see Section 7.2.4 +of [RFC9421]). + Clarified that created bounds the lifetime of a captured +signature but does not by itself detect replay within that window +(see Section 7.2.2 of [RFC9421]). + jwksUri and {tokenEndPoint} transport: HTTPS remains mandatory, +with the same HTTP fallback allowance for testing setups that the +Discovery Process has; dropped the HTTPS-only schema pattern from +spec.yaml accordingly. + Appendix B now defers the missing-jwksUri case to Decision to +Discard instead of stating a stronger +requirement in an informative section. + Updated the signature examples: replaced the legacy Digest header +with Content-Digest [RFC9530] and applied [RFC8792] line +wrapping. + Added informative aids: same-string note for must-exchange-token, +Appendix D criteria label fix, Signing Direction +Index, Appendix E: Navigation +Index, and companion diagrams under +diagrams/ in the OCM-API repository. + Rehaul of the Notification (formerly "Share Acceptance +Notification") endpoint and payload, and adaptation of the IANA +registries. The core notifications have now been fully spelled +out, clarifying their scope. + Introduced an encryption optional object in the Share Creation +Notification payload, and defined a corresponding Encryption Schemes +OCM IANA Registry. + + +
Version 06 Introduced IANA Registries for resource types, protocols, share @@ -2894,8 +3269,8 @@ Peter Szegedi, Ron Trompert, Benedikt Wegmann and Jonathan Xu. We would also like to thank Ishank Arora, Gianmaria Del Monte, Jörn Friedrich Dreyer, Richard Freitag, Hugo González Labrador, Matthias Kraus, Maxence Lange, Lovisa Lugnegård, Thibault Meunier, -Sandro Mesterheide, Antoon Prins and Björn Schießle for their direct -contributions to the specification. +Sandro Mesterheide, Antoon Prins, Justin Richer and Björn Schießle 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, @@ -2952,786 +3327,908 @@ a specific projec