netsoul
Version:
netsoul protocol library
516 lines (345 loc) • 17.9 kB
Plain Text
Sp�cification (non officielle) du protocole Netsoul
Par Patrick MARIE <mycroft@virgaria.org>
Derni�re modification: 20031029
/*
* ----------------------------------------------------------------------------
* "THE BEER-WARE LICENSE" (Revision 42):
* <mycroft@virgaria.org> wrote this file. As long as you retain this notice
* you can do whatever you want with this stuff. If we meet some day, and you
* think this stuff is worth it, you can buy me a beer in return. Patrick MARIE
* ----------------------------------------------------------------------------
*/
Ce papier est munie d'une structure qui me semble la meilleure pour la
r�daction de celle ci (lire: j'�cris cela comme je le sens).
Il d�crit ce que j'ai pu apprendre en lisant les diff�rentes sources des
clients, et en reproduisant diff�rentes parties du protocole.
Pour ceux qui ne le savent pas, Epita/Epitech sont deux �coles d'informatique
en France, situe au Kremlin bicetre (sud ouest de Paris).
(liens: http://www.epita.fr/ ; http://www.epitech.net/)
Je ne suis pour ma part aucunement affili� de pr�s ou de loin � ces �coles,
r�digeant cette documentation pour informer les utilisateurs.
I. Sommaire
* I. Sommaire
* II. Pr�sentation
* III. Phase d'authentification
* IV. Commandes
* V. Messages serveur
* VI. Annexes
II. Pr�sentation
Les informations pr�sentes dans ce papier feront s�rement l'objet de
modifications ind�pendantes de ma volont�. Sera ind�pendante de ma volont�
�galement la mise � jour de ce texte, car je ne serai certainement pas
motiv� pour continuer de chercher ce que les mainteneurs principaux
de Netsoul-Epita (voir ci dessous) feront comme modifications dans le
futur. Les informations sont actuelles � la date de derni�re mise � jour
de ce texte.
Au moment ou j'�cris ces lignes, le seul serveur Netsoul-Epita
(Netsoul-Epita nommant le nom du protocole netsoul dans Epita) se situe
sur le port TCP 4242 et � l'adresse "ns-server.epita.fr" (163.5.255.80)
(et en interne dans Epita, 10.42.1.59)
Les commandes envoy�es et re�ues sont toujours termin�es par '\n'.
Certaines commandes envoy�es par le client peuvent recevoir des "accus�s de
r�ception", d'autres non. Tout cela sera notifi� au bon moment.
Notations: Les messages re�us et envoy�s �tant au format texte ascii, il
est facile de repr�senter dans ce texte plusieurs exemples.
Les lignes envoy�es seront dans ce document pr�c�d�es d'un 'client: ';
Les lignes re�ues seront pr�c�d�es d'un 'server: '.
Bien entendu, ces 'client: ' et 'server: ' ne font pas partis de la
communication sur le r�seau.
Par exemple:
-- capture 1 --
client: test
-- fin capture 1 --
correspondra en C �:
...
#define TEST_MESSAGE "test\n"
...
write(sock, TEST_MESSAGE, strlen(TEST_MESSAGE));
...
Pour les exemples "longs", on rajoutera des balises '-- capture X --' et
'-- fin capture X --' pour d�limiter ces exemples.
III. Phase d'authentification
1/ Premier cas: utilisateur externe au PIE.
-- capture 1 --
client: telnet ns-server.epita.fr 4242
client: Connected to 163.5.255.80.
client: Escape character is '^]'.
server: salut 27 2fb93c1e8020c71ccf99f6555f70e56f 195.220.50.8 45686 1036068977
-- fin capture 1 --
Le premier message d'authentification est de ce format:
salut <num�ro de socket> <hash md5 al�atoire> <host client> <port client> <timestamp server>
Le num�ro de socket est invariablement un unsigned int;
la cha�ne md5 un unsigned char d'une longueur de 32 octets ('\0' final non
compris);
l'host client est une ip lisible, donc au maximum d'une longueur de 15 octets;
('\0' final non compris);
le port client est un unsigned short;
le timestamp est un time_t.
Le hash md5 al�atoire, l'host client et le port client vont servir �
construire la cha�ne d'authentification � envoyer par le client.
Avant cela, le client doit demander l'autorisation de s'authentifier, et
en donner la m�thode.
client: auth_ag ext_user none none
server: rep 002 -- cmd end
A partir de ce moment, le client doit envoyer la commande 'ext_user_log',
de ce format la:
client: ext_user_log mycroft b2177622c14612a9b0e725b9c317026f none location
server: rep 002 -- cmd end
Les param�tres sont de ce format:
ext_user_log <login user> <cha�ne md5 de r�ponse> <user data> <user location>
Le login user n'est que le login utilisateur, sur le PIE;
La cha�ne md5 de r�ponse est telle que:
MD5("<hash md5 al�atoire>-<host client>/<port client><pass socks>")
Exemple:
...
/* Les arguments sont r�cup�r�es des commandes pr�c�dentes */
sprintf(buffer, "%s-%s/%i%s", hashauth, client_host, client_port, password);
/* Primitive MD5 issue de la libcrypto (openssl) */
MD5(buffer, strlen(buffer), pass);
/* MD5 renvoie des donn�es sous format binaires, on rend la cha�ne
'lisible' */
str = malloc(sizeof(char) * (MD5_DIGEST_LENGTH * 2 + 1));
memset(str, 0, (MD5_DIGEST_LENGTH * 2 + 1));
for (i = 0; i < MD5_DIGEST_LENGTH; i ++)
sprintf(str + (2 * i), "%02x", pass[i]);
...
Le champs 'user data' et 'user location' permettent de d�finir deux valeurs,
en g�n�ral le client utilise et la version, et la location du client (dans
le PIE, la salle, le rang et le num�ro de station)
Ces deux champs doivent �tre dans le format des urls, c'est � dire pour
faire passer "toto tutu lala" il faudra envoyer "toto%20tutu%20%lala"
Ces deux champs sont de longueur maximum de 64 caract�res.
Exemple:
client: ext_user_log mycroft c5b38c5022d9e1af23cfb89630010f03 paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20 nsc%20roulez
server: rep 002 -- cmd end
Au moment o� l'ext_user_log est envoy� et confirm�, l'utilisateur est loggu�
dans le r�seau netsoul et peut envoyer des commandes.
On associera deux commandes � la phase de connexion pour un utilisateur
externe au PIE: "attach" et le changement de status.
'attach' permet aux utilisateurs externes de lib�rer l'acc�s � d'autres
daemons interne � epita tels que les news.
client: attach
server: rep 002 -- cmd end
En final, � la connexion, le status utilisateur est 'connexion'. Le client
doit changer ce status. (voir plus loin.)
client: state actif:1067437282
Le serveur ne renvoie rien suite � la commande 'state'.
2/ Second cas: utilisateur interne au PIE.
Un utilisateur du PIE, c'est � dire l'ensemble des machines dans le parc
informatique d'epita n'a pas � subir cette phase d'authentification, comme
elle a �t� �tablie par la connexion de l'utilisateur sur le r�seau.
Afin de r�cup�rer la connexion, l'utilisateur doit r�cup�rer les variables
d'environnement $NS_USER_LINK afin de connaitre le num�ro de la socket unix,
qui sera:
...
int sock;
struct sockaddr_un sua;
sock = socket (PF_LOCAL, SOCK_STREAM, 0);
sprintf(path, "%s/.ns/%s", getenv("HOME"), getenv("NS_USER_LINK"));
strcpy(sua.sun_path, path);
connect (sock, (struct sockaddr *)&sua, sizeof(sua));
...
IV. Commandes
Ces commandes existent pour les clients internes et externes au PIE.
D'une mani�re g�n�rale, les commandes utilisateurs doivent �tre pr�c�d�e
d'un 'user_cmd' quand on est � l'ext�rieur du PIE, et d'un 'cmd' quand on
est � l'int�rieur du PIE.
Exemple:
Si l'on veut envoyer un message � 'rn' (voir section IV. 2/ ), on utilisera:
- de l'ext�rieur:
client: user_cmd msg_user rn msg test
- de l'int�rieur (sur la socket unix):
client: cmd msg_user rn msg test
1/ state
Les clients (utilisateur) netsoul se voient attribu�s d'un status de la
connexion.
Bien que n'importe quel status semble �tre accept� par le serveur, il est
pr�f�rable d'en utiliser qu'un de ceux ci:
* actif
-> Vous �tes sur votre station de travail, pr�s � �tre joint si n�cessaire;
* away
-> Vous n'�tes pas sur votre station de travail;
* connection
-> Vous n'avez pas chang� le status par d�faut suivant la connexion;
* idle
-> Vous �tes sur votre station, mais n'avez pas montr� signe de vie;
* lock
-> Vous avez lock� votre station;
* server
-> Le client est sur un serveur d'applications;
* none
-> Vous ne d�sirez pas utiliser le status.
Avec cela, il faut envoyer le timestamp de changement d'�tat, sous ce format:
state <new status>:<timestamp>
Exemples d'utilisation:
client: state actif:1036142854
state away:1036142860
D'une mani�re g�n�rale, les commandes utilisateur
A l'externe du PIE, cette commande peut aussi etre envoy�e de cette forme:
client: user_cmd state <new status>
Exemples d'utilisation:
client: user_cmd state none
client: user_cmd state actif
Voir �galement la section "Messages serveur".
2/ msg
Comme jabber ou yahoo, il est possible de faire de "l'instant messaging"
avec Netsoul.
On peut envoyer des messages � toutes les personnes loggu�s � netsoul.
L'envoie de message � des personnes non loggu�s est autoris�e, mais les
messages ne sont pas conserv�s par le serveur (donc perdus).
Exemple, pour un utilisateur externe puis interne:
client: user_cmd msg_user rn msg bonjours
client: cmd msg_user rn msg bonjours
Format:
(cmd|user_cmd) msg_user <login / liste login> msg <message>
login / liste login contient soit un login (Exemple: 'rn');
soit une liste de login (Exemple: '{rn,jumpy,:42}'), ou, entre accolades
et s�pares par des ',', on peut mettre soit des login soit des num�ros de
sockets (prefixees alors de ':').
Cette notion de liste de login est �galement utilis�e pour d'autre
commandes.
message: le message doit �tre du m�me format que "user data" et "location",
en 'url encoded'.
Exemple:
client: user_cmd msg_user {mycroft,:1049} msg Salut%2C%20ca%20vas%20%3F
Voir �galement la section "Messages serveur".
3/ list_users
list_users permet de r�cup�rer la liste des clients loggues sur netsoul.
Il peut viser un login en particulier ou plusieurs via une liste de login
(d�crit dans la section IV. 2/)
Format:
list_users <login / liste login>
Exemple:
-- capture 1 --
client: list_users rn
server: 1419 rn 163.5.42.42 1067515354 1067516102 1 3 NetBsd_wse bocal_r1p1 wheel actif:1067516103 -
server: rep 002 -- cmd end
-- fin capture 1 --
-- capture 2 --
client: list_users dontexist
server: rep 002 -- cmd end
-- fin capture 2 --
-- capture 3 --
client: list_users {:1419,benoit_e}
server: 184 benoit_e 10.252.42.53 1067515906 1067516521 3 1 ~ kernel ept_2002 serveur:1067515855 bnsd-0.1
server: 1419 rn 163.5.42.42 1067515354 1067516718 1 3 NetBsd_wse bocal_r1p1 wheel actif:1067516719 -
server: rep 002 -- cmd end
-- fin capture 3 --
Voir la section IV. 2/ pour la description de 'login / liste login'.
Voir �galement la section "Messages serveur".
4/ watch_log_user
watch_log_user permet de mettre en place, sur le serveur, une liste de
login/connexion pour lesquelles on veut etre avertis des login/logout/
changements de status... (comme icq, aim, ...)
Format:
(cmd|user_cmd) watch_log_user <login / liste login>
Exemple:
client: user_cmd watch_log_user {rn,benoit_e}
Voir la section IV. 2/ pour la description de 'login / liste login'.
Voir �galement la section "Messages serveur".
5/ who
who permet d'avoir des informations sur un/des utilisateur(s) loggues
(moyen de substitution � list_users).
Format:
(cmd|user_cmd) who <login / list login>
Exemple:
-- capture --
client: raw user_cmd who {rn,mycroft}
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | who 525 mycroft 195.220.50.8 106751826 5 1067518791 3 1 ~ paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20 ext actif:1067518387 nsc%20roulez
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | who 1419 rn 163.5.42.42 1067515354 1067518532 1 3 NetBsd_wse bocal_r1p1 wheel actif:1067518039 -
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | who 118 mycroft 212.129.36.164 1067500202 1067518681 3 1 ~ appart%40madrid ext actif:1067500221 bns%2D0%2E9%2E2%20%5B%20bNetSoul%20rocks%20%5D
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | who rep 002 -- cmd end
-- fin capture --
Voir la section IV. 2/ pour la description de 'login / liste login'.
Voir �galement la section "Messages serveur".
6/ exit
Un client peut envoyer � tout moment la commande 'exit' afin de se delogguer
du serveur.
V. Messages serveur
1/ Changement de status d'un utilisateur
Le client netsoul recevra tout les messages login, logout et state d'un
utilisateur qu'il aura mis dans sa "watch_log" list.
Exemple:
client: user_cmd watch_log_user {mycroft}
[...]
server: user_cmd 91:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | login
server: user_cmd 91:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | state actif:1067518230
server: user_cmd 91:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | state away:1067518242
server: user_cmd 91:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | logout
[...]
Voici le format d'une notification:
user_cmd <socket>:user:<trust level>:<login>@<user host>:<workstation type>:<location>:<groupe> | <command> <command extension>
socket: unsigned int, repr�sentant le num�ro de la socket du client qui
vient d'envoyer le message;
trust level: 1/3 hors du PIE (en externe, donc), 3/1 en interne;
login: login de l'utilisateur du client qui envoie le message;
user host: adresse ip du client;
workstation type: type de la machine (seulement pour le PIE, ex: NetBsd_wse);
location: champs location de l'utilisateur (en url encoded);
command: soit login (pour indiquer que l'utilisateur vient de se logguer),
logout (l'utilisateur vient de se delogguer),
state (l'utilisateur vient de changer de status).
2/ R�ception d'un message
La r�ception d'un message est similaire au changement d'un status (V. 1/);
Est juste diff�rent la commande, qui sera 'msg':
Exemple:
client: user_cmd msg_user {mycroft} msg test
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | msg test
Le message est url-encoded, et ne peut contenir plus de 256 caract�res
(apr�s encodage.)
De plus, on pourra recevoir les notifications pour les mails:
server: user_cmd 0:mail:9/9:_deamon:: | new_mail -f mycroft@virgaria.org %28test%20email%29
La commande est 'new_mail'; Cette commande est suivie de -f, puis de l'email
source du message et finalement du titre du mail en url-encoded.
3/ R�ception d'une r�ponse � la commande list_users
client: list_users franco_l
server: 1043 franco_l 213.142.23.186 1067500237 1067520661 3 1 ~ rhs%2Ese epita_2003 actif:1067500198 42
server: rep 002 -- cmd end
Le format du message re�u est de la forme:
<socket> <login> <user host> <login timestamp> <last status change timestamp> <trust level low> <trust level high> <workstation type> <location> <group> <status> <user data>
socket: unsigned int, repr�sentant le num�ro de la socket du client qui
vient d'envoyer le message;
user host: adresse ip du client;
login timestamp: heure de connexion du client sur netsoul
last status change timestamp: heure du dernier changement d'etat;
trust level low/high: correspondent au 1/3 et 3/1 pour les machines dans le
PIE et hors du PIE;
workstation type: type de la machine;
location: champs location de l'utilisateur (en url encoded);
group: groupe de l'utilisateur;
status: status de l'utilisateur;
user date: champs userdata de l'utilisateur (en url encoded).
4/ R�ception d'une r�ponse � la commande who
Suite � la commande who, le client re�oit au moins une ligne comprenant,
sous la forme d'un message de changement de status (V. 1/), mais ayant comme
commande 'who' le message 'rep 002 -- cmd end'.
client: user_cmd who {rn}
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | who 1419 rn 163.5.42.42 1067515354 1067522535 1 3 NetBsd_wse bocal_r1p1 wheel idle:1067522086 -
server: user_cmd 525:user:1/3:mycroft@195.220.50.8:~:paul%2Dsud%2Easso%2Eups%2Dtlse%2Efr%20:ext | who rep 002 -- cmd end
Le format de la partie avant le '|' est d�crit dans la section V. I/
Le format de la partie apr�s le '|' est le suivant:
| who <socket> <login> <user host> <login timestamp> <last change timestamp> <trust level low> <trust level high> <workstation type> <location> <group> <status> <user data>
Le message re�u apr�s le 'who' �tant du m�me format que celui renvoy� par la
commande 'list_users', le format n'en sera pas re d�crit ici. cf section V. 3/
5/ R�ception d'un 'ping'
Le serveur netsoul envoit r�gulierement des 'ping' afin de voir si le
client est encore connect�. Il associe cela � un nombre qui correspond au
nombre de seconde que le serveur attend apr�s un message du client avant de
le d�connecter.
Le client peut r�pondre, par exemple, la m�me ligne envoy�e.
Exemple:
server: ping 600
client: ping 600
VI. Annexes
1/ A faire
* tenter une connexion ext � l'int�rieur du PIE; il me semble que le
'protocole' d'auth etait une fois de plus diff�rent. (cf m�thode csecret)
* voir les diff�rentes gestions des "cmd", "user_cmd", ... � l'int�rieur
du PIE.
* extensions des clients:
06:33 !!! Not yet handled: [user_cmd 95:user:1/3:asega_a@10.253.4.11:~:%5co_:ept3 | dotnetSoul_UserCancelledTyping null ]
06:33 !!! Not yet handled: [user_cmd 95:user:1/3:asega_a@10.253.4.11:~:%5co_:ept3 | dotnetSoul_UserTyping null ]
06:33 !!! Not yet handled: [user_cmd 95:user:1/3:asega_a@10.253.4.11:~:%5co_:ept3 | dotnetSoul_UserCancelledTyping null ]
* r�cup�rer les clients en commande, et voir les fonctions.
2/ Exemple de connexion 'complet'
3/ Change Log