Skip to content

Protocol

Gawen Arab edited this page Sep 19, 2019 · 1 revision

Protocol

Alias is a decentralized protocol to implement data portability between services. It empowers the users to choose their own data storage they trust to store their (GDPR, CCPA, ...) data dumps from their services, and to choose its own "data bank" (an authorization server) to let third-parties access its data.

Third-parties implement an Alias client to request and receive the user's data. They can add a "Login with Alias" button on their website.

Overview

The Alias protocol is greatly inspired from the OAuth 2.0 protocol. Like it, the protocol happens between 5 parties:

  • An User, which owns data and is globally identified by an alias, formed like an email address. Its authentication is protected by a private key only known by themselves;
  • A Client, willing to access data of a user with their consent. The data to be sent are described by a list of scopes the client gives to the authorization server;
  • An Authorization server, acting as a trusted proxy between the client and the resource servers storing the user's data. It displays the client's contract to the user and wait for their approval;
  • An Resource server, storing the user's data.
  • An User-agent, being the user's front-end to interact with the client and their autorization server;

Like OAuth 2.0, the grant is represented by a token given to the client by the authorization server. Unlike common OAuth 2.0 implementation, the token is a value similar to a JSON Web Token signed with the user's private key, therefore prooving the consent of the user.

Because the protocol is decentralized, there is no client registration process. A contract, serialized as a JSON object, is generated by the client setting every data necessary for a authorization server to identity it, and what data the client is willing to access.

Grant flow

Grant client's access

For a client to request user's data, it must first creates a contract describing its intent. This contract is serialized as a JSON object, storing:

  • a list of metadata about the client (name, description, URL, redirection endpoints, ...), signed with its private key;
  • a list of scopes to describe the data needed by the user, under what legal base the scopes are, and a human description of how it will be used;
  • a list of human-readable legal information necessary to make the contract equivalent to a GDPR/CCPA contract.

When this contract is ready, it can be serialized with anychain and send as a GET argument to the authorization server's redirection endpoint (by default /alias/request/). The user-agent is redirected to the authorization server which will authenticate the user.

When authenticated, the user is then displayed a request window which describes the contract they are about to agree or deny. If certain scopes are opt-out, they may enable them.

If the user denies, the user-agent is redirected to the client's callback endpoint (defined in its contract) with the appropriate error (see OAuth2).

If the user agrees, the user creates a JSON object storing the contract and the agreed scopes, signs it with their private key. The authorization server is sent a signed copy, and the user-agent is redirected to the client's callback endpoint with the GET parameter code set to the just-signed object serialized with anychain.

This code is the "grant token", which proves the client has been granted by the user to access data described in the token.

Data transfer

Now the client has a grant token, it can request data from the authorization server.

To do so, it will perform a HTTP POST request to the authorization server's endpoint /alias/process with parameter code the grant token. The authorization server will respond to this request when the transfer has finished, or an error occured.

In the Alias protocol, the authorization server performs HTTP requests to the client to send the requested data. The data is pushed by the authorization server to the client.

The authorization will first calculate grant_hash, the root hash of the grant token with anychain. From this hash, the base endpoint where to push data for this grant can be generated as follow: /alias/push/%grant_hash%/. It performs a HTTP request PUT on this endpoint to notify the client a new transfer will happen and it must delete previous data received on this grant.

# Request
PUT /alias/push/%grant_hash%/

# Response
200 OK

Then, the authorization server will spawn the necessary processors to process the user's data. Multiple data archives might be generated, each of them uploaded separately to the client. To do so, it will perform multiple partial range PUT requests to the client to stream the file's data to the client.

# Request
PUT /alias/push/%grant_hash%/%filename%
Range: %start byte%-%end byte%
Content-Length: %length%

%data chunk%

#Response
206 Partial Range

A POST on the same endpoint will notify the client the file is finished and now immutable.

# Request
POST /alias/push/%grant_hash%/%filename%

# Response
200 OK

Finally, a final HTTP request POST on the grant upload endpoint /alias/push/%grant_hash%/ will notify the client the transfer of every files is now finished.

You can’t perform that action at this time.