diff --git a/IETF-RFC.md b/IETF-RFC.md index 2168f8b..e7e54af 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -74,7 +74,7 @@ thing. This is achieved by providing a protocol that abstracts away security and authentication details from the users to the servers acting on behalf of the users. Another important point of the protocol is the invitation mechanism that lets users connect over established human -relationships and uses those connections to establish contact between +relationships and use those connections to establish contact between their respective OCM servers. # Terms @@ -607,22 +607,23 @@ contain the following information about its OCM API: support at least `webdav`, any other combination of Resources and protocols is optional. Example: - `json + ```json { "webdav": "/remote/dav/ocm/", "webapp": "/app/ocm/", "talk": "/apps/spreed/api/" } - ` + ``` Fields: - webdav (string) - The top-level WebDAV [RFC4918] path at this endpoint. In order to access a Remote Resource, implementations - MAY use this path as a prefix, or as the full path (see sharing - examples). + SHOULD use this path as a prefix (see sharing examples). - webapp (string) - The top-level path for web apps at this - endpoint. This value is provided for documentation - purposes, and it SHOULD NOT be intended as a prefix - for share requests. + endpoint. In order to access a remote web app, implementations + SHOULD use this path as a prefix (see sharing examples). + - ssh (string) - The top-level address in the form `host:port` + of an endpoint that supports ssh and scp with a public/private + key based authentication. - Any additional protocol supported for this Resource type MAY be advertised here, where the value MAY correspond to a top-level URI to be used for that protocol. @@ -770,7 +771,8 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request * REQUIRED protocol (object) JSON object with specific options for each protocol. The supported protocols are: - `webdav`, to access the data - - `webapp`, to access remote web applications. + `webapp`, to access remote web applications - `ssh`, to access + the data via a public/private key pair. Other custom protocols might be added in the future. In case a single protocol is offered, there are three ways to specify this object: @@ -854,6 +856,46 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request - OPTIONAL sharedSecret (string) An optional secret to be used to access the remote web app, for example in the form of a bearer token. +* Protocol details for `ssh` MAY contain: + - OPTIONAL accessType (array of strings) - The type of access + being granted to the remote resource. If omitted, it defaults to + `['remote']`. A subset of: - `remote` signals the recipient that + the resource is available for remote access, e.g. via sshfs. + - `datatx` signals the recipient to transfer the resource + from the given URI via scp. The recipient MAY delegate a + third-party service to execute the data transfer on their behalf. + - REQUIRED uri (string) + The full address to be used for ssh or scp access, in the form + `username@host.fqdn:port/resource/path`, where the `username` is + chosen by the Sending Server and does not necessarily need to match + the recipient's OCM Address. Authentication is expected to take + place via public/private key: the Receiving Server MUST reply to + such a Share Creation Notification by sending back their public + key, for the Sender Server to authorize access to the Resource. + +## Response + +The Share Creation Notification Response SHOULD be a HTTP response: + +* in response to the Share Creation Notification Request +* using `application/json` as the `Content-Type` HTTP response header + +A 201 response status means the Share Creation Notification Request was +successful. In this case, the response body MUST contain a JSON +document representing an object with the following string fields: + - REQUIRED: `recipientDisplayName` - the Recipient's display name. + - OPTIONAL: `recipientPublicKey` - the Recipient's public key. + This property MUST be returned when the protocol of the incoming + share was `ssh`. +A 400 response status means some parameters were invalid or missing. +A 401 response status means the Sender cannot be authenticated as +a trusted service. +A 403 response status means the Sender is not authorized to create +shares. +A 501 response status means either the Receiver does not support +incoming external shares, or the share type or the resource type +are not supported. +A 503 response status means that the Receiver is temporary unavailable. ## Decision to Discard @@ -880,7 +922,7 @@ following hold true: * an initial check shows that the Resource cannot successfully be accessed through (any of) the protocol(s) listed -# Receiving Party Notification +## Receiving Party Notification If the Share Creation Notification is not discarded by the Receiving Server, they MAY notify the Receiving Party passively by adding the @@ -891,6 +933,7 @@ 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. + # Share Acceptance Notification In response to a Share Creation Notification, the Receiving Server MAY @@ -937,17 +980,6 @@ of the notification. Receiving Servers SHOULD decline notifications from Sending Servers without httpsig as it can't identify where the notification is coming from. -### Receiving Party Notification - -If the Share Creation Notification is not discarded by the Receiving -Server, they MAY notify the Receiving Party passively by adding the -Share to some inbox list, and MAY also notify them actively through for -instance a push notification or an email message. - -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. - # Resource Access To access the Resource, the Receiving Server MAY use multiple ways, diff --git a/spec.yaml b/spec.yaml index 352d011..90897e6 100644 --- a/spec.yaml +++ b/spec.yaml @@ -72,8 +72,14 @@ paths: properties: recipientDisplayName: type: string - description: display name of the recipient + description: > + Display name of the recipient example: John Doe + recipientPublicKey: + type: string + description: > + The public key of the recipient. This value MUST be provided + in case the Share Creation Notification includes the `ssh` protocol. "400": description: > Bad request due to invalid parameters, e.g. when `shareWith` is not @@ -83,26 +89,26 @@ paths: schema: $ref: "#/components/schemas/400" "401": - description: Client cannot be authenticated as a trusted service. + description: Sender cannot be authenticated as a trusted service. content: application/json: schema: $ref: "#/components/schemas/Error" "403": - description: Trusted service is not authorized to create shares. + description: Sender is not authorized to create shares. content: application/json: schema: $ref: "#/components/schemas/Error" "501": - description: The consumer doesn't support incoming external shares, the share + description: The Receiver doesn't support incoming external shares, the share type or the resource type is not supported. content: application/json: schema: $ref: "#/components/schemas/Error" "503": - description: The consumer is temporary unavailable (e.g. due to planned + description: The Receiver is temporary unavailable (e.g. due to planned maintenance). headers: Retry-After: @@ -388,6 +394,12 @@ components: The top-level path for web apps at this endpoint. In order to access a remote web app, implementations SHOULD use this path as a prefix (see sharing examples). + ssh: + type: string + description: > + The top-level address in the form `host:port` of an endpoint + that supports ssh and scp with a public/private key based + authentication. additionalProperties: type: string description: > @@ -688,7 +700,30 @@ components: in any URI. In a multi-protocol share scenario with WebDAV, the access requirements provided in the `webdav` part MUST apply for `webapp` accesses as well. - + ssh: + type: object + properties: + accessType: + type: array + description: > + The type of access being granted to the remote resource. + If omitted, it defaults to `['remote']`. + - `remote` signals the recipient that the resource is available + for remote access, e.g. via sshfs. + - `datatx` signals the recipient to transfer the resource from + the given URI via scp. The recipient MAY delegate a third-party + service to execute the data transfer on their behalf. + items: + type: string + enum: + - remote + - datatx + uri: + type: string + description: > + The full address to be used for ssh or scp access, in the form + `username@host.fqdn:port/resource/path`, where authentication is + expected to take place via public/private key. additionalProperties: type: object description: > @@ -724,6 +759,9 @@ components: uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01 sharedSecret: hfiuhworzwnur98d3wjiwhr viewMode: read + ssh: + accessType: ['datatx'] + uri: extuser@my-cloud-storage.org:/7c084226-d9a1-11e6-bf26-cec0c932ce01 NewNotification: type: object required: