From cb61363db386b1182826cb1c9ed307808a46865c Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 13 Jun 2025 09:20:15 +0200 Subject: [PATCH 1/2] RequestShare: Introduce the notion of a share request --- IETF-RFC.md | 27 ++++++++++++++++++++++ spec.yaml | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) diff --git a/IETF-RFC.md b/IETF-RFC.md index a8d1dea..bbbcdf4 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1015,6 +1015,33 @@ They could give the Receiving Party the option to accept or reject the share, or add the share automatically and only send an informational notification that this happened. +# Request for a Share + +If the Receiving Party knows of a resource that has not yet +been shared, the Receiving Party MAY make an 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 +* using TLS +* using httpsig [RFC9421] + +## Fields + +* REQUIRED shareWith (string) + OCM Address of the user, group or federation that wants to + receive a share of the resource. + Example: "51dc30ddc473d43a6011e9ebba6ca770@geant.org" +* REQUIRED shareId (string) + A unique identifier for the resource. + Example: 1234567890abcdef + +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. + # Share Acceptance Notification diff --git a/spec.yaml b/spec.yaml index f1fa552..ba8ac0c 100644 --- a/spec.yaml +++ b/spec.yaml @@ -36,6 +36,54 @@ paths: application/json: schema: $ref: "#/components/schemas/Discovery" + /request-share: + post: + summary: Request access to a share + description: > + This endpoint is used to request access to a share. + The request MUST contain the share ID and the OCM address of the party + who wants to receive the share. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RequestShare" + description: The JSON object to request access to a share. + required: true + responses: + "201": + description: > + Consumer successfully received request. + "400": + description: > + Bad request due to invalid parameters, e.g. when `shareId` is missing. + content: + application/json: + schema: + $ref: "#/components/schemas/400" + "501": + description: The server doesn't support requesting shares. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "503": + description: The server is temporary unavailable (e.g. due to planned + maintenance). + headers: + Retry-After: + description: > + Indication for the client when the service could be requested + again in HTTP Date format as used by the Internet Message + Format [RFC5322] (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) or the + number of seconds (e.g. 3000 if you the service is expected to + be available again within 50 minutes). + schema: + type: string + content: + application/json: + schema: + $ref: "#/components/schemas/Error" /shares: post: summary: Share Creation Notification endpoint @@ -843,6 +891,22 @@ components: type: string description: Name of the Invite Sender. example: John Doe + RequestShare: + type: object + required: + - shareWith + - shareId + properties: + shareWith: + type: string + description: > + Consumer specific identifier of the user, group or federation that + wants to recive a share of the resource. + example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org + shareId: + type: string + description: A unique identifier for the resource. + example: 1234567890abcdef TokenRequest: type: object required: From 2169dc9b2539ee68e3a08ba125074f9c11714930 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Tue, 9 Sep 2025 11:14:11 +0200 Subject: [PATCH 2/2] Update IETF-RFC.md Co-authored-by: Giuseppe Lo Presti --- IETF-RFC.md | 3 +++ spec.yaml | 11 +++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index bbbcdf4..90660f2 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1030,6 +1030,9 @@ been shared, the Receiving Party MAY make an HTTP POST request ## Fields +* REQUIRED sender (string) + OCM Address of the user who will be requested to share + the resource. * REQUIRED shareWith (string) OCM Address of the user, group or federation that wants to receive a share of the resource. diff --git a/spec.yaml b/spec.yaml index ba8ac0c..d5d6e3c 100644 --- a/spec.yaml +++ b/spec.yaml @@ -894,14 +894,21 @@ components: RequestShare: type: object required: + - sender - shareWith - shareId properties: + sender: + type: string + description: > + OCM Address of the user who will be requested to share + the resource. + example: 527bd5b5d689e2c32ae974c6229ff785@apiwise.nl shareWith: type: string description: > - Consumer specific identifier of the user, group or federation that - wants to recive a share of the resource. + OCM Address of the user, group or federation that + wants to receive a share of the resource. example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org shareId: type: string