polyphony-chat / stimmgabel

polyproto reference test implementation used for verifying other implementations of the protocol.

stimmgabel

Command-line utility implementation of polyproto, used for verifying other implementations of the protocol.

Motivation

Getting all aspects right when implementing a protocol can be difficult - especially when the protocol is new and does not have a lot of implementations to compare against. Stimmgabel (German for 'tuning fork') is a command-line utility to use as a verification tool for other implementations of polyproto.

Since this is a binary and not a library, it is fairly straightforward to use in various programming languages, by calling the binary with the desired arguments.

Installation

Download the latest release from the releases page. Alternatively, using the Rust tool chain, you can clone this repository and build the binary yourself.

After acquiring the binary, you can execute it from the command line:

stimmgabel --help

Interpreting the output

The program will exit with a status code of 0 if the verification was successful. Any other exit code indicates that there was an error during the verification process. The exit code is encoded as a bit flag, where the bits are set as follows:

Error	Bit flag
GARBLED_INPUT (Unreadable input)	1 << 0
INVALID_INPUT (Readable, but wrong input)	1 << 1
CONSTRAINT_VIOLATION (Validation criterion not met)	1 << 2
BAD_SIGNATURE (Signature does not match data)	1 << 3
BAD_PUBLIC_KEY (Public key does not match signature or public key is weak/bad)	1 << 4

Verifying a message

polyproto does not dictate a specific format for messages. For this verification implementation, the following format is used, when passing a message to be verified:

{
    "message": "Any string",
    "signature": "Base64 encoded signature",
    "public_key": "Base64 encoded public key of the sender"
}

Minifying the JSON is allowed, and the order of the keys is not important.

Cryptography and Safety

polyproto does not specify a signature algorithm. For two implementations to be compatible, they must offer an overlapping set of signature algorithms. Stimmgabel only supports ED25519, using the ed25519-dalek crate, as ED25519 is the currently recommended signature algorithm for polyproto.

Important

This repository's cryptography, including keys and algorithms, is strictly for testing purposes. It uses the ed25519-dalek crate to implement polyproto with ED25519 as a signature algorithm. Learn about the safety guarantees of the ed25519-dalek crate for more information. This software has not received a security audit. No guarantees about its safety can be made.