Python Retroshare Interface Library

This library is written as pyrs, but pronounced papyrus. It provides a reference implementation of how to interface with retroshare from a client.

Using this library you can control your retroshare instance programatically in python. Some example usages might be:

• Create a web interface using Python/Django.
• Make a plugin to share documents.
• Extract Retroshare Forums, and turn them into an RSS Feed or Webpage.
• Create an Android Remote Control for Retroshare.
• Link with a Twitter client to allow posting to both.
• Anything is possible. Send me you suggestions - I'll post them here!

pyrs uses an SSH tunnel to connect to retroshare. This means it is generally safe to use over the internet. You can run the clients halfway across the world if you want.

Areas covered in this document:

• Installation
• Prerequisites
• Examples
• Help-out & TODO
• Retroshare
• Protocol Definition

Installation

This package has no install script yet. You can just copy the pyrs directory to your working directry. Help to create a setup.py would be much appreciated

Prerequisites

This library requires the following Python packages:

• Paramiko (SSH library)
• Protobuf (Google's serialisation library)

Example Usage

There are examples included with the code in the examples directory.

1) Setup retroshare-nogui with sshserver enabled.

2) Check out this repo

> git clone https://github.com/drbob/pyrs.git pyrs

2) copy examples base directory of pyrs packaage.

> cd pyrs
> cp ./examples/* ./

3) Create an auth.txt with your login details. eg.

pwd iverygoodandlongpassword
port 7022
user mylogin
host 127.0.0.1

4) run the tests

Setting up the Retroshare side of things is still not trivial. It is described in the build documents for retroshare-nogui.

Help-out & TODO

This library has just been created. Expect many improvements over the next couple of weeks. We are still designing the actual protobuf exchange protocol, until then sit tight!

• Help with Python Packaging. I've never created a python package before. Would love help with the setup.py and other bits.

• Example Code.

• Send me links to python code that uses pyrs.

• Use pyrs and retroshare in your projects!

What is Retroshare?

(Retroshare)[http://retroshare.sourceforge.net] is a secure friend-2-friend social network.

Protocol Definition

Protobuf serialisation does not identify Message Types or Message Size. So we need to have an encapsulation header system

These headers describe the actual message via a MsgId and MsgSize. Care must be taken to ensure these IDS are correct, as this is NOT enforced by protobuf, and will lead to incorrect deserialisation!

In Each .proto there is a list of MsgIds as an ENUM.

The protocol message format is as follows:

  [HEADER: 16 bytes: 4 x Network Order of uint32_t ] [ VARIABLE LENGTH BODY ] 
  [ MAGIC_CODE ] [ MSG_ID ] [ REQ_ID ] [ BODY_SIZE ] [ ....... BODY ....... ]
  MagicCode = 0x137f0001. will be incremented for new versions of the protocol.
  MsgID = Corresponds to the format of the Body.
  ReqID = Generated by Requester, Returned in Response, make sure its unique. (undefined behaviour for duplicates)
  BodySize = Byte Length of Body.

  The Body will consist of a protobuf encoded message.

Message Ids

In Each .proto there is a list of MsgIds as an ENUM.

0x00 XX XX xx	=> Reserved for libretroshare Requests. (XXXX - area, xx specific msg)
0x01 XX XX xx	=> Reserved for libretroshare Responses

eg. 0x00 (fa bc) [01] -> Request, 0x01 (fa bc) [01/02/03] -> responses

0x10 YY YY yy   => Extensions for project YY (16k), with sub commands yy (256)
0x11 YY YY yy