1. Introduction

Muteswan is an experimental pseudo anonymous instant message system. It is pseudo anonymous in the sense that anonymity is enforced (with Tor) while message access is dependent upon face to face human trust relationships. The intention is to provide a simple messaging service that is reasonably protected from surveillance with encryption, yet also protects message sender and receiver identity. Muteswan adopts the notion of a "circle": a collection of individuals that share a single symmetric key. Users share their keys with other individuals face to face, in person using QR codes (2 dimensional bar codes). An Muteswan client in possession of a symmetric key can send and receive messages to other people who possess the same key.

The goal is that this framework is flexible enough to be used on the one hand as a private, secure communication platform and on the other hand as an information dissemination tool. For example, two individuals sharing a circle with no else enables private and trusted communication. In other cases, identity protection is paramount but access to the circle may be more widespread.

Muteswan uses Tor to anonymize messages sent to the server. Muteswan servers are hosted using Tor hidden nodes. A hidden service on the Tor network is accessible only to other Tor clients and the server does not know the identity of the request nor does the client know the identity of the hidden service serving the response. A very simple RESTful protocol is used to post, get and discover new messages. Messages are encrypted using AES and accessible by URL using a SHA1 hash of the UUID associated with the circle.

2. Intentions, Assumptions and Goals

This document is intended to be a technical and design reference. The background assumptions, project goals and potential uses of Muteswan are outside the scope of this document. However, it is difficult to continue without some overall frame to help contextualize the impetus and goals of the project.

Muteswan rests on a few operating assumptions and requirements:

  • Trust and identity do not need to be closely related. Circles of people who share a community of trust can manage that trust in person, face to face. Muteswan should facilitate this where it is possible.

  • Identity must always be protected. People need plausible deniability both as authors and readers.

  • Simple and secure: protocol must be designed such that success of any operation requires maximum anonymity. It should be impossible to use Muteswan in such a way that leaks your identity. The server should be as small and stateless as possible, without any logging features.

  • The user should always have control of her identity and risk.

The goal of the Muteswan project is to create an experimental communication tool that is embedded in the social and geographic space of its users. The dissemination of information and trust networks, though anonymous, may perhaps map more closely to real world social relations and thus provide some level of trust. This (perhaps limited) level of trust is augmented with anonymity of of message senders/receivers.

3. Protocol Overview

Muteswan is extremely simple. "Circles", or collective use of shared symmetric AES keys plus a server name, provide centralized access to message data. Possessing an appropriate AES key along with the name of the Tor hidden server enables access to the messages on a given circle.

A client/server protocol was built on top of HTTP using RESTful principles. Clients can:

  • get a single message,

  • discover the latest message,

  • or post a message.

The Muteswan server itself merely acts as a distribution point. It sends clients messages and saves messages that are posted to circles but it does not process or analyze any messages.


3.1. Components

The individual technical components described below. In some cases, more detail will be provided in later sections, but this section outlines the core operative components.

3.1.1. Circles

Circles are the only organizational unit in Muteswan. They are composed of three elements:

key: a string used for the AES key, e.g, dba4fe6ef22b494d
uuid: a RFC4122 UUID used in URL
server: a tor hidden service address, e.g., tckwndlytrphlpyo.onion
shortname: name of the circle, e.g., testsite

Circles are represented in text form with a + separating the name from the UUID, a $ separating the key and an @ delimiting the server:


Since Muteswan uses symmetric keys, accessing a circle simply involves knowing the key and the server. Consequently, the text representation of a circle should never be displayed and the key should be treated as any cryptographic secret. Muteswan circles are intended to be shared in person, typically via QR code. The circles should be trivial to communicate via QR code but there should be no reason to transfer them in another method. Of course, how people distribute circles is up to the members of the circle.


The AES key can be represented in two ways. A 16 character string, e.g., "dba4fe6ef22b494d", used as the AES key. This is the weakest key format but it is convenient and takes up the least amount of space.

A 256bit or 128bit AES key can be base 64 encoded. For example:

Entropy garden+e8b6be57-c34b-41f7-ae18-042589d8e93c$ChuTIyvKfBO7IJSxzikvJbX2AnFeQPV03yyyKoqPsgw=@tckwndlytrphlpyo.onion


If no UUID is present, for example: testsite+dba4fe6ef22b494d@tckwndlytrphlpyo.onion the client will hash the key to derive the URL used to GET new messages. This is another trade off between convenience and security. Including a UUID takes up more space but protects the secret better.

3.1.2. Tor client

Tor acts as a SOCKS proxy on the client node. Tor runs on many platforms, including mobile ones. All Muteswan clients need a running local Tor proxy in order to function.

3.1.3. Muteswan server

The Muteswan server is a simple HTTP server using RESTful principles. The server is essentially stateless: only POST and GET methods are implemented with the index fetch being the only operation that is not strictly uploading or downloading an actual file.

Since the server role is so narrow, it can implemented very minimally and reduce security risks. Also, it should be noted that a compromise of an Muteswan server could reveal other circles hosted on the hidden service but would not expose any identities.

Note Muteswan was intended to run as server behind a Tor hidden node, but it does not need to. A Tor hidden node allows anonymous hosting and reduces the risk of the Tor server.

3.1.4. Muteswan client

The Muteswan client queries the Muteswan server address to fetch message indexes, individual messages and to post messages. It provides the only interface to the user.

It is also the only place where Muteswan keys are stored. The client is responsible for managing its own cryptographic stores. At a minimum, this requires storing key and server information locally.

3.1.5. QR codes

QR codes are used to transmit circle information to other users. Qrcodes were chosen because they provide a very flexible, convenient and most importantly they are "embedded in the physical world."

To transmit a circle to another user, a QR code needs to be generated using the full text description of a circle (shortname+key@server). The individual receiving the key scans the QR code and imports the circle information into their client.

3.1.6. Message Encryption

Muteswan uses standard AES CBC symmetric key cryptography. Every message is encrypted with the circle key before it is sent. It is posted to the server based on a SHA1 hash of the circle UUID. The AES cryptography provides protection from anyone who has access to the actual tor hidden service as well as a certain level of protection if an Muteswan server is compromised.

AES is currently used because it is secure and widely supported. The actual cryptographic algorithm is not material and perhaps changing out or selecting algorithms is a desirable feature.

Initial vector data is included in the message payload with the JSON key iv.


Muteswan uses a simple RESTful scheme on top of HTTP. Only GET and POST methods are used and their URLs are well defined.

JSON is used to encode the message formats. All messages must have a key name of "message" which contains the base64 encoded encrypted data. For example:


3.2.1. URL Scheme





POST msg



none, 200 response

GET msg



BASE64 encoded msg

GET msg range



BASE64 encoded msgs in JSON array

GET last message



JSON key lastMessage holds message id latest message

GET info



JSON key Name holds the name of the server. This info JSON may be extended in the future.

GET qrcode



Generates a QRCode of the hidden node for easy import to a phone

3.2.2. POST msg

To post a message to a circle, an Muteswan client uses the POST method with the SHA1 hash of the circle in the request URI. No other argument is allowed on the URI.

An example POST request:

POST /3db7814a7d0e23f66906fbfd087bbd8f523f7180 HTTP/1.1
Content-Length: 34
Host: tckwndlytrphlpyo.onion
Connection: Keep-Alive


If the container (usually a file system directory) does not exist (that is, no messages exist yet), than the container is created and the first message is given an id of 1.

The encrypted message content is BASE64 encoded AES encrypted data. The initial vector data used is stored in the JSON key "iv".

3.2.3. GET msg

Fetching a message is as simple as requesting the message id in the URI. For example, the request to fetch message 53 from the testsite circle would be:

GET /f573fe7d4a34186b00bcab2b38e52122afe04d83/53 HTTP/1.1
Host: tckwndlytrphlpyo.onion
Connection: Keep-Alive


3.2.4. GET msg range

Fetching a message range is also possible and reduces latency. For example, the request to fetch message 3 to 2 from the testsite circle would be:

GET /b975d0e342802b65b3703ff9cf3a378533d980b9/2-1 HTTP/1.1
Host: tckwndlytrphlpyo.onion
Connection: Keep-Alive

[{"content":{"iv":"OYt0ENQGejnFqcEboXQ6XA==","message":"1wt630PxKrE17BxTESl8Rg=="},"timestamp":"Sat, 13 Jul 2013 22:12:18 GMT","Id":2},{"content":{"iv":"5ypw/UYfGMSBUl2hoh2E4Q==","message":"uLqfL3S0G9R9FDn+ni1aPw=="},"timestamp":"Sat, 13 Jul 2013 22:12:08 GMT","Id":1}]

3.2.5. GET msg index

A list of all available messages can be accessed by issuing a GET request on the SHA1 hash alone:

GET /f573fe7d4a34186b00bcab2b38e52122afe04d83 HTTP/1.1
Host: tckwndlytrphlpyo.onion
Connection: Keep-Alive


The message index is sent to the client in the body of HTTP response with the JSON key lastMessage. Since all messages are sequential and immutable, it implies that message 1 through Last-Message are available.

3.2.6. GET info

Fetches the server metadata. Currently this provides the name of the server:

GET /info HTTP/1.1
Host: tckwndlytrphlpyo.onion
Connection: Keep-Alive

{"Name": "Sample Server"}

3.2.7. GET qrcode

Returns a PNG image of the server in the form of a QRCode. This is useful if you know the address of a Muteswan server and want to add it easily with a phone.

4. Implementations

There already exist a few implemented components. They are mostly reference implementations to proof-of-concept the project. Please keep in mind that all of the implementations below assumes a Tor SOCKS proxy server is running on localhost at port 9050.

Source is available at: http://muteswan.org/git

4.1. Muteswan server

A small Muteswan server implemented in Go(lang) is available with the option of file or MongoDB based backend storage.

It is simple to install and run.

4.2. Android client

An client for Google’s Android OS is functional at this point. This is the most useful client situation. Since Muteswan is an instant messaging service accessing the service on one’s phone is ideal.

The Android client leaves much to be desired in the realm of user interface, code quality and error reporting, but it does work at this early stage. It can currently perform all the envisioned operations:

  • Share circles as QR codes

  • Import circles and identities from QR codes

  • Create a new circle

  • Post message to a circle

  • Read messages from circles

  • A persistent Android service is available to check and download new messages at intervals.

The Android client depends on two other Android applications: Barcode Scanner and Orbot. Orbot is the official Tor port for Android. Barcode Scanner is used to offload QR code generation and scanning.

To try out the latest version of the Muteswan Android client: http://muteswan.org/