signing request

Author: ArtificialOwl

README.md

@@ -15,6 +15,7 @@ the [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (fka Swagger) specif
   * [Share Updating](#update)
   * [Resharing](#reshare)
   * [Invite](#invite)
+  * [Signing Request](#signing-request)
 
 * [Contributing](#contributing)
 
@@ -35,6 +36,8 @@ If a finite whitelist of receiver servers exists on the sender side, then this l
 
 When a sending server allows sharing to any internet-hosted receiving server, then discovery can happen from the sharee address, using the `/.well-known/ocm` (or `/ocm-provider`, for backwards compatibility) URL that receiving servers SHOULD provide according to this [specification](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1.well-known~1ocm/get).
 
+In the eventuality of a need to confirm the identity of an incoming request, the discovery data SHOULD contain a public key. Each incoming request that requires to origin from an authentified source must be signed in its headers using the related private key.
+
 To fill the gap between users knowning other peers' email addresses of the form `user@provider.org`, and the actual cloud storage endpoints being in the form `https://my-cloud-storage.provider.org`, a further discovery mechanism SHOULD be provided by implementations that wish to allow sending shares to any receiver, based on DNS `SRV` Service Records.
 
 * A provider SHOULD ensure that a `type=SRV` DNS query to `_ocm._tcp.provider.org` resolves to e.g. `service = 10 10 443 my-cloud-storage.provider.org`
@@ -44,7 +47,7 @@ To fill the gap between users knowning other peers' email addresses of the form
 To create a share, the sending server SHOULD make a HTTP POST request to the `/shares` endpoint of the receiving server ([docs](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1shares/post)).
 
 ### Share Acceptance
-In response to a share creation, the receiving server MAY send back a [notification](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1notifications/post) to the sending server, with  `notificationType` set to `"SHARE_ACCEPTED"` or `"SHARE_DECLINED"`. The sending server MAY expose this information to the end user. 
+In response to a share creation, the receiving server MAY send back a [notification](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org#/paths/~1notifications/post) to the sending server, with  `notificationType` set to `"SHARE_ACCEPTED"` or `"SHARE_DECLINED"`. The sending server MAY expose this information to the end user.
 
 ### Share Access
 To access a share, the receiving server MAY use multiple ways, depending on the received payload and on the `protocol.name` property:
@@ -87,6 +90,41 @@ If an OCM provider exposes the capability `/mfa-capable`, it indicates that it w
 Since there is no way to guarantee that the sharee OCM provider will actually enforce the MFA requirement, it is up to the sharer OCM provider to establish a trust with the OCM sharee provider such that it is reasonable to assume that the sharee OCM provider will honor the MFA requirement. This establishment of trust will inevitably be implementation dependent, and can be done for example using a pre approved allow list of trusted OCM providers. The procedure of establishing trust is out of scope for this specification: a mechanism similar to the [ScienceMesh](https://sciencemesh.io) integration for the [Invite](#invite) capability may be envisaged.
 
 
+### Signing request
+
+Signing request confirms the identity of the sender but does not encrypt nor affect its payload. A request can be signed by adding metadata to the headers and require a compatible discovery end point to broadcast the public key used to generate the signature.
+
+The concept is to add unique metadata and sign them using a private/public key pair.
+The location of the public key used to verify the signature will confirm the origin of the request.
+
+Signature does not affect the data of the request, it only adds headers to it:
+```
+ {
+     "(request-target)": "post /path",
+     "content-length": 380,
+     "date": "Mon, 08 Jul 2024 14:16:20 GMT",
+     "digest": "SHA-256=U7gNVUQiixe5BRbp4Tg0xCZMTcSWXXUZI2\\/xtHM40S0=",
+     "host": "hostname.of.the.recipient",
+     "Signature": "keyId=\"https://author.hostname/key\",algorithm=\"ras-sha256\",headers=\"content-length date digest host\",signature=\"DzN12OCS1rsA[...]o0VmxjQooRo6HHabg==\""
+ }
+```
+
+- 'content-length' is the total length of the payload of the request
+- 'date' is the datetime the request have been initiated
+- 'digest' is a checksum of the payload of the request
+- 'host' is the hostname of the recipient of the request (remote when signing outgoing request, local on incoming request)
+- 'Signature' contains the signature generated using the private key, and metadata:
+  * 'keyId' is a unique id, formatted as an url. hostname is used to retrieve the public key via custom discovery
+  * 'algorithm' define the algorithm used to generate signature
+  * 'headers' contains a list of element used during the generation of the signature
+  * 'signature' is the encrypted string, using local private key, of an array containing elements
+    listed in 'headers' and their value. Some elements (content-length date digest host) are mandatory
+    to ensure authenticity override protection.
+
+
+
+
+
 ## Changelog
 
 [Available here](CHANGELOG.md)

spec.yaml

@@ -357,6 +357,23 @@ definitions:
           enum: ["/notifications", "/invite-accepted", "/mfa-capable"]
         example:
           ["/invite-accepted"]
+      publicKey:
+        type: object
+        description: |
+          The signatory used to sign outgoing request to confirm its origin. The 
+          signatory is optional but it MUST contains `id` and `publicKeyPem`.
+        properties:
+          id:
+            type: string
+            description: |
+              unique id of the key in URI format. The hostname set the origin of the 
+              request and MUST be identical to the current discovery endpoint.
+            example: https://my-cloud-storage.org/ocm#signature
+          publicKeyPem:
+            type: string
+            description: |
+              PEM-encoded version of the public key.
+            example: "-----BEGIN PRIVATE KEY-----\nMII...QDD\n-----END PRIVATE KEY-----\n"
   NewShare:
     type: object
     required: