Pear local sharing protocol

Pear is a local sharing application designed to be simple and painless. Initial goals are to be able to share URLs and small files across local devices with automatic discovery.

Protocol specification v.01

Version .01 of the pear protocol is relatively insecure. There's no in-built transport protection and minimal identity verification.

Identity

That said, this version of the spec does include the concept of identities. An identity is an RSA(?) key pair used to differentiate devices. It is a unique Device ID, generated from the RSA public key, and a Device Name for easy visual distinction.

I think the RSA key pair and identities and stuff will be pushed to a later version of the spec. I want to get a functional and very basic prototype first.

Data flow

The general overview of data flow with the pear protocol goes like this:

1. Origin device sends DISC broadcast: The origin device broadcasts a generic device discovery request using UDP.
2. Target devices reply with a DACK: All possible target devices reply to the origin device privately over TCP.
3. Origin device sends data to chosen target: The origin device sends data privately to the selected target device over a new TCP connection.

Pear message header

Pear signifier block - 4 bytes - 00 00 00 00

Protocol version - 2 bytes - 00 00

Payload type - 2 bytes - 00 00

Device ID - X bytes - 00 00 00 00

Signature - X bytes - 00 00 00 00

Device discovery

Discovering a device begins with a DISC broadcast. These broadcasts are public and simply request that every other pear capable device on the network respond with a private DACK message. Discovery request messages contain very basic information about the origin device but make no guarantees that it is capable of receiving data. To send data to a target it must have responded with either a DACK or IACK message.

DISC request

Pear header - 8 bytes - 00 00 00 00 ...

Payload - 0 bytes - ...

A DISC payload is ignored in this version of the spec. Later I want to be able to do some key sharing stuff that might make use of this.

DACK message payload

Pear header - 8 bytes - 00 00 00 00 ...

Device name length - 2 bytes - 00 00

Device name - X bytes - 00 00 00 00 ...

Devices that responded with a DACK might have gone stale, so to ensure they are still on line and able to receive data an origin device should send an IREQ request. This request is also a public broadcast, but rather than a general discovery request it specifically asks about the status of an individual device. If the target device is on line it should send back a private IACK message.

I'm not entirely sure I need this yet or not, we'll see. Theoretically a DISC could achieve the same results.

Data transfer

Data is transfered with a discrete TCP connection from origin device to target device. There are a few different types of data payloads. Pear can be used to transfer plaintext, web URLs, files, and notifications. Plaintext is exactly what it sounds like, just a raw byte array. URLs are specifically for sharing websites between devices. Files get downloaded to the target device, and notifications just alert the target device's user with the containing text. Target devices should also be able to refuse data messages depending on the payload type.

Plaintext data message

Pear header 8 bytes 00 00 00 00 ...

Bytes X bytes 00 00 00 00 ...

URL data message

Pear header 8 bytes 00 00 00 00 ...

URL X bytes 00 00 00 00 ...

File data message

Pear header 8 bytes 00 00 00 00 ...

Filename length 2 bytes 00 00

Filename X bytes 00 00 00 00 ...

File length 4 bytes 00 00 00 00

File content X bytes 00 00 00 00 ...

Notification data message

Pear header 8 bytes 00 00 00 00 ...

Notification text X bytes 00 00 00 00 ...

Future plans

One thing I want to implement eventually is restrictions on "who can discover this device". So far the three options I have are Everyone, Ask Me, and Only These. However, this requires persistent identities which I don't want to deal with yet. To start with in v.01 I'm just going to use the device name and not care much about persistent identities so that I can more easily get a working proof of concept that works.

I also would like ARP style tables that can be used to respond on behalf of a device maybe? Not sure why this is useful but it's at least something to keep in mind.