Connectors

The private communications in Attesta are all based on the Connecctor paradigm.

The paradigm

To be able to send and to receive data the party needs to create or use a Connector. It is not possible to send anything to other partym no matter if it's party.id, email or any other information is known. Instead, it is necessary to create the Connector.

Creating connector needs to know other party searchable nick, confirmed searchable email or phone number. From any of these originating party generates nick and asks Attesta to create/find connector to it. If the connector exists, it will be used. If not, new one will be created. The process is shown in details in the diagram add party.

Not that while Connector is in wait state, it severely limits the size and the bandwidth from originator to the destination party to the limits just enough to send time to time the HELLO block.

Since other party accepts the connector, it could be used for communications, what means, to exchange procetced blkocks.

Connectors could be not noly P2P but also group connectors, wich share blocks to the members of the groups. There is no limit to the number of participants. But the logic is the same - even if the party is known from some group, the only way to communicate to it is to use existing connector, or create new private P2P connector to it.

Thre remote party receives hello block which should contain short invitation message and enought data of the originating party to help remote pary user to decide whether to accept connection.

User manually accepts the connection, and the clinet application calls connectors_accept(), otherwise it can leave the connector in wait state or even block it.

create p2p connector

Requires autentication. To create connector, calling party should known any of the published searchable tokens of the remote pary:

connectors_request( {nick_token:|email_tiken:|phone_token:} <binary-token> )
    -> { connector: <connector-block> | result: 'not_found }
  • nick_token: nick token to look for

return: connector block or result with error codenot_found (usually).

After creating the connector, requesting party must send an HELLO block to the remote party, which includes connectors_id, some message to be shown to the remote party's user, and own data (nick, userpic, whatever user decides to send). See send data below.

The connecting party must form HELLO block including connectors_id itself because the server can not sign the HELO request and receiving party therefore could not be sure that the invitation goes from the other party and not from somebody who gained access to the server database. This level of security does not compromise communications between parties even if the server itsef is compromised.

Client implementation should not use other types if handshake, instead, it is advised to extend HELLO block to carry all necessary information.

if two parties requet connections to each other, it will be accepted automatically without calling connectror_accept().

accept connector

Requires authentication.

connectors_accept(connectors_id: <string>)

returns: nothing. Throws errors if connector could not be accepted.

send data

requries authenticated used and the connectors_id.

connectors_deliver(connectors_id: <int>, data: <binary>[, expires_at: <datetime>])
    -> { item: <item_structure> }
  • connectors_id: valid id of the connector to which authenticated party has the right to write.

  • data: protected block with data to deliver

  • expires_at: optional block expiration time after which server and hopefully all clients remove all copies of this block.

returns: item structure for the just-created item, which can vbe used to synchronize sent items across all connected clients.