Skip to content
This repository was archived by the owner on Dec 29, 2022. It is now read-only.

SERVER.md

Latest commit

 

History

History
96 lines (80 loc) · 5.09 KB

SERVER.md

File metadata and controls

96 lines (80 loc) · 5.09 KB

Svalbard server

A Svalbard server communicates with clients using two types of interfaces: a simple HTTP interface, that handles a variety of requests (see below), and one or more of secondary outbound interfaces, that allow the server sending messages to the clients, like in 2-factor authentication schemes (via e.g. SMS messages, or other instant messaging channels)

The HTTP interface of a server handles POST requests that enable storage, retrieval and deletion of shares. Each operation proceeds in two steps: first a short-lived token is requested, that enables the actual operation, then the token is used to execute the operation. The token is requested via the HTTP interface, and delivered via a secondary outbound channel. A request for a token must contain a request id which is not secret, but should be unique for each token request issued by a particular client during a session. The request id is echoed by the server together with the token, so that the client can identify various tokens delivered via secondary channels.

Here is a list of the requests that are being processed by the server, together with parameters that must be present as data of the corresponding POST request:

  • GET_STORAGE_TOKEN: sends via a secondary outbound channel a storage token that enables storage of a specified share The request must contain the following data:

    • request_id: an id of that particular request
    • owner_id_type: type of id, e.g. "SMS", "email", ...
    • owner_id: actual id, e.g. a phone number, e-mail address
    • secret_name: the name of the secret that the desired share belongs to

    The response to the request is purely informational: it either indicates that the token has been sent successfully (HTTP status: 200 OK), or informs about any errors that occurred (HTTP status: non-OK).

  • STORE_SHARE: stores a provided share for the specified user under a given label The request must contain the following data:

    • token: a retrieval token obtained by the client via a secondary channel
    • owner_id_type: type of id, e.g. "SMS", "email", ...
    • owner_id: actual id, e.g. a phone number, e-mail address
    • secret_name: the name of the secret that the share_value belongs to
    • share_value: the actual value of the share

    The response to the request is purely informational: it either indicates that the share has been stored successfully (HTTP status: 200 OK), or informs about any errors that occurred (HTTP status: non-OK).

  • GET_RETRIEVAL_TOKEN: sends via a secondary outbound channel a retrieval token that enables retrieval of a specified share The request must contain the following data:

    • request_id: an id of that particular request
    • owner_id_type: type of id, e.g. "SMS", "email", ...
    • owner_id: actual id, e.g. a phone number, e-mail address
    • secret_name: the name of the secret that the desired share belongs to

    The response to the request is purely informational: it either indicates that the token has been sent successfully (HTTP status: 200 OK), or informs about any errors that occurred (HTTP status: non-OK).

  • RETRIEVE_SHARE: returns an existing share, assuming the client provides the necessary retrieval token. The request must contain the following data:

    • token: a retrieval token obtained by the client via a secondary channel
    • owner_id_type: type of id, e.g. "SMS", "email", ...
    • owner_id: actual id, e.g. a phone number, e-mail address
    • secret_name: the name of the secret that the desired share belongs to

    The response to the request either contains the desired share value (HTTP status: 200 OK), or informs about any errors that occurred (HTTP status: non-OK).

  • GET_DELETION_TOKEN: sends via a secondary outbound channel a deletion token that enables deletion of a specified share The request must contain the following data:

    • request_id: an id of that particular request
    • owner_id_type: type of id, e.g. "SMS", "email", ...
    • owner_id: actual id, e.g. a phone number, e-mail address
    • secret_name: the name of the secret that the share to be deleted belongs to

    The response to the request is purely informational: it either indicates that the token has been sent successfully (HTTP status: 200 OK), or informs about any errors that occurred (HTTP status: non-OK).

  • DELETE_SHARE: deletes an existing share, assuming the client provides the necessary deletion token. The request must contain the following data:

    • token: a deletion token obtained by the client via a secondary channel
    • owner_id_type: type of id, e.g. "SMS", "email", ...
    • owner_id: actual id, e.g. a phone number, e-mail address
    • secret_name: the name of the secret that the share to be deleted belongs to

    The response to the request is purely informational: it either indicates that the share has been deleted successfully (HTTP status: 200 OK), or informs about any errors that occurred (HTTP status: non-OK).