Specifications

• Introduction
• Queries
  • inf
  • pbk
  • sig
  • uid
  • err
• Connection process

Introduction

A phoenix query is introduced by the character $, and has three different parts :

Example query : $iinf server_core:phoenix|server_version:0.0.1
This is sent by the hub on a new connection : it gives to the client informations about the hub he is connecting to

• The first letter (i) identifies the recipient of the query :

Letter	Meaning	Description
h	hub	a message intended to the hub only
i	info	sent by the hub to a client
b	broadcast	sent by a client to the hub to be broadcasted to all connected peers (depending on the query, it will be first analysed by the hub
d	direct	a message sent by a client to a specific client

• The three following letters (inf) identify the query

• Arguments for the query are made of key:value pairs seperated by a |. Keys are made of alphanumerical characters and _ only, and are case sensitive. Values can contain any utf-8 characters except |, $ and newline \n.

Queries

1. inf
2. pbk
3. sig
4. uid
5. err

inf

contexts : i

params :

• name : name of the hub
• description : description of the hub
• core : hub software
• version : software version

inf queries are intended to provide nodes with informations about the hub they are connecting to. It should be sent by the hub once the user opens a TCP connection.

pbk

contexts : i, b

params :

• public_key : a base32 encoded public key
• username [if sent by node]
• uid [if sent by node]

pbk queries are used to send node's and hub's public Keys

sig

contexts : h

params :

• username
• password

Note
parameters sent with a sig query should always be encrypted with hub's public_key

sig queries should be used by nodes to log in/sign in, giving a username and password.

If the username does not exist, the hub should register username and password, and send back a user id (see uid). Otherwise, if username already exists and password doesn't match, it should respond with an err query with the following description : 'you don't have permission to use this identity'

uid

contexts : i

params :

• uid : node's user id generated by the hub

err

contexts : i, d

params :

• code
• description

Connection process

+-------+                                 +-----+                                         
| node  |                                 | hub |                                         
+-------+                                 +-----+                                         
    |                                        |                                            
    | open TCP connection                    |                                            
    |--------------------------------------->|                                            
    |                                        |                                            
    |    $iinf name|description|version|core |                                            
    |           [informations about the hub] |                                            
    |<---------------------------------------|                                            
    |                                        |                                            
    |                       $ipbk public_key |                                            
    |                     [hub's public_key] |                                            
    |<---------------------------------------|                                            
    |                                        |                                            
    | $hsig username|password                |                                            
    | [encrypted, signing into the hub]      |                                            
    |--------------------------------------->|                                            
    |                                        |                                            
    |                                        | if username already exists, check password
    |                                        | otherwise register username and password   
    |                                        |  => generates/retrieves user id            
    |                                        |-------------------------------------------
    |                                        |                                          |
    |                                        |<------------------------------------------
    |                                        |                                            
    |                              $iuid uid |                                            
    |                           [node's uid] |                                            
    |<---------------------------------------|                                            
    |                                        |                                            
    | $bpbk uid|username|public_key          |                                            
    | [node's public_key]                    |                                            
    |--------------------------------------->|                                            
    |                                        |                                           
    ```