‚̧N00b's Programming Machine

    chattervox

    0.7.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    Chattervox

    Travis CI Build Image Coverage Status

    An AX.25 packet radio chat protocol with support for digital signatures and binary compression. Like IRC over radio waves ūüď°.

    Chattervox implements a minimal packet radio protocol on top of AX.25 that can be used with a terminal node controller (TNC) like Direwolf to transmit and receive digitally signed messages using audio frequency shift keying modulation (AFSK). In the United States, it's illegal to broadcast encrypted messages on amateur radio frequencies. Chattervox respects this law, while using elliptic curve cryptography and digital signatures to protect against message spoofing.

    With amateur packet radio anyone can pretend to be anyone else. With Chattervox, you can be sure you're chatting with the person you intend to. For more information, check out the FAQ or the discussion about chattervox on hackernews.

    UPDATE (March 6, 2019): Check out my slides from the Chattervox workshop at WOPR Summit.

    UPDATE (February 25, 2019): I've created a collection of example applications and use cases for the Chattervox protocol here. One example uses Chattervox to access a remote BASH shell on another machine and another shows how you can play Zork I over packet radio. PRs welcome!

    UPDATE (October 11, 2018): We've setup a public key registry at chattervox-keys. Once you've generated your public key you can post it there!

    Baofeng UV-5R Linux setup

    Prerequisites

    Chattervox requires a linux computer and a network or serial connection to a TNC to send and receive AX.25 packets. I recommend using Direwolf, a popular software TNC which can be run on the same computer hosting the chattervox application.

    You'll also need a radio and a cable to connect the microphone and speaker from the radio to your linux machine. I recommend the following equipment, especially if you're on a budget:

    • $24 Baofeng UV-5R 4-watt radio. This is the absolute best radio you can buy for that price.
    • $18 BTech APRS cable (3.5mm TRRS to 3.5mm and 2.5mm audio cable, usually for sale on Amazon)

    You can also make the cable yourself if you prefer. Check out this zine for instructions.

    Finally, to operate legally on amateur radio frequencies, you'll need an amateur radio license.

    Install Direwolf

    Linux

    Installing Direwolf on a Linux machine is easy! Just clone the repo, build the software, and install it on your system.

    # clone, build, and install the Direwolf TNC 
    git clone https://github.com/wb2osz/direwolf
    cd direwolf
    make
    sudo make install
    make install-conf

    MacOS

    If you are using MacOS, you can install Direwolf with Homebrew by following the instructions in this Gist (thanks for the edits @danc256).

    Windows

    Windows isn't currently supported, but will be soon!

    Download

    Binary downloads are available for Linux x64 and x86 architectures on the releases page.

    If you have npm, that is the preferred method of install as it allows for the easiest upgrade to the latest version. If you prefer to "build" it from Typescript source and run it as a Node.js app, you can do that as well.

    NPM

    npm install --cli -g chattervox@latest 

    Installing a node package globally may require sudo. If you get a permission denied error, try running the install command again with sudo npm ....

    Source

    # clone the repo 
    git clone https://github.com/brannondorsey/chattervox
    cd chattervox
     
    # download dependencies 
    npm install
     
    # transpile the src/*.ts typescript files to build/*.js 
    npm run build
     
    # run chattervox from source to opening the chat room 
    node build/main.js chat

    Binary Downloads

    Binary downloads are packaged via Pkg. Chattervox uses a native Node.js addon for serial port communication but Pkg does not yet support bundling .node bindings in their binaries. Therefore, the serialport.node file that comes with the download must live in the same folder as the chattervox binary. If you want to install chattervox globally on your machine you can maintain this relationship by placing chattervox in your PATH using a symlink, or copying both chattervox and serialport.node to /usr/local/bin or wherever your OS looks for programs.

    Usage

    # open the chat room 
    chattervox chat
     
    # send a packet from the command-line 
    chattervox send "this is a chattervox packet sent from the command-line."
     
    # receive *all* packets and print them to stdout 
    chattervox receive --allow-all
     
    # generate a new public/private key pair, and use it as your default signing key 
    chattervox genkey --make-signing
     
    # add a friend's public key to your keyring, so that chattervox can verify their messages 
    chattervox addkey KC3LZO 0489a1d94d700d6e45508d12a4eb9be93386b5b30feb2b4aa07836398781e3d444e04b54a6e01cf752e54ef423770c00a6
     
    # remove a friend's public key if it has become compromised  
    chattervox removekey KC3LZO 0489a1d94d700d6e45508d12a4eb9be93386b5b30feb2b4aa07836398781e3d444e04b54a6e01cf752e54ef423770c00a6
     
    # print all keys in your keyring 
    chattervox showkey
    usage: chattervox [-h] [-v] [--config CONFIG]
                      {chat,send,receive,showkey,addkey,removekey,genkey} ...
    
    An AX.25 packet radio chat protocol with support for digital signatures and 
    binary compression. Like IRC over radio waves ūüď°„Äį.
    
    Optional arguments:
      -h, --help            Show this help message and exit.
      -v, --version         Show program's version number and exit.
      --config CONFIG, -c CONFIG
                            Path to config file (default: /home/braxxox/.
                            chattervox/config.json)
    
    subcommands:
      {chat,send,receive,showkey,addkey,removekey,genkey}
    

    The Protocol

    The chattervox packet is primitive and straightforward. It contains a simple header, an optional ECDSA digital signature, and a message payload that can be in plaintext or compressed. As of packet version 1, the protocol is connectionless. There is only one type of packet and there is no mechanism for delivery confirmation (think of it like UDP). It is expected to be transported via AX.25 Unnumbered Information (UI) packets, which the chattervox program relies on for sender and recipient information, as no such fields exists in the packet itself to conserve space.

    The protocol may be amended in the future to add new features, however, its simplicity should not be seen as a weakness. The goal of chattervox is singular: Add cryptographic verifiability to text-based radio communication.

    For proposed changes to the protocol view the open RFCs.

    Chattervox Protocol v1 Packet

    Byte Offset # of Bits Name Value Description
    0x0000 16 Magic Header 0x7a39 A constant two-byte value used to identify chattervox packets.
    0x0002 8 Version Byte Number A protocol version number between 1-255.
    0x0003 6 Unused Flag Bits Null Reserved for future use.
    0x0003 1 Digital Signature Flag Bit A value of 1 indicates that the message contains a ECDSA digital signature.
    0x0003 1 Compression Flag Bit A value of 1 indicates that the message payload is compressed.
    [0x0004] [8] [Signature Length] Number The length in bytes of the digital signature. This field is only included if the Digital Signature Flag is set.
    [0x0004 or 0x0005] [0-2048] [Digital Signature] Bytes The ECDSA digital signature created using a SHA256 hash of the message contents and the sender's private key.
    0x0004-0x104 0-‚ąě Message Bytes The packet's UTF-8 message payload. If the Compression Flag is set the contents of this buffer is a raw DEFLATE buffer containing the UTF-8 message.

    [] indicates an optional field.

    TypeScript chattervox client

    This repository serves as the first implementation of the protocol. The chattervox command-line tool acts as a client to send and receive chattervox packets in combination with a TNC. This implementation creates a new ECDSA keypair the first time it's run and includes a digital signature for each message (so long as there remains a signingKey in ~/.chattervox/config.json). Each message is temporarily compressed by the client before it's sent in an attempt to measure the efficiency of the DEFLATE compression algorithm. If the compressed version is smaller than the uncompressed version, the compressed buffer is used as the message payload and the compression bit is set in the chattervox packet. If the plaintext version is smaller, no compression is used and the original message text is used as the payload.

    Beta Software

    Please understand that this software is in beta and I ask for your patience until development stabilizes. While I'm very excited to see that interest in the project is high, It's quite unexpected and I have spent very little time testing the software (aside from automated tests). If you have a problem, please submit a detailed issue and I'll have a look. I'll be writing a tutorial explaining how to get up and running with chattervox very soon.

    The protocol is subject to change, and there are several RFCs that indicate the direction it may take in the near future. Currently, there is no protection from replay attacks, so that's something we hope to fix soon!

    Install

    npm i chattervox

    DownloadsWeekly Downloads

    1

    Version

    0.7.0

    License

    GPL-3.0

    Unpacked Size

    217 kB

    Total Files

    50

    Last publish

    Collaborators

    • brannondorsey