How to use xx Network CLI
Introduction
xx Network is a privacy-focused, quantum-resistant "small messaging" network.
By "small messaging" I mean up to KB-sized messages, although it's possible to use larger messages as well. For example, xx Messenger supports small attachments (tens of KB).
xx CLI client is a reference client implementation for xx Network that at this time uses the older "broadcast module layer" approach.
Speakeasy (Haven) or Echoexx use a better approach (channels), but all of them use the xx Network SDK (xxDK).
xx CLI client repository has a read-me file that contains almost all the steps required to get started, but this post can still save you some time.
Build
At this time we need go1.21, but check the source to verify if this requirement changed.
These steps are for Linux. Check the repository's read-me file for other OS.
git clone https://git.xx.network/elixxir/cli-client && cd cli-client/
go mod vendor && go mod tidy
GOOS=linux GOARCH=amd64 go build -ldflags '-w -s' -o xx-client main.go
On ARM64 devices, use GOARCH=arm64 or omit GOARCH (it should be detected automatically).
Use xx CLI
Let's see how to use xx CLI client.
First user
Someone needs to create a broadcast (chat) first.
We can do that with --new, and give your broadcast a name and a description.
Setup procedure creates 2 files you need to know about:
- the first one is the broadcast definition file by default named $CHANNEL.xxchan (here,
test.xxchan) - the second is a private RSA key for the creator who is also channel admin. This one is by default named
$CHANNEL-privateKey.pem(here,test-privateKey.pem).
export NICK="my-Name"
./xx-client broadcast --new -o test.xxchan -n "test" -d "Some desc"
./xx-client broadcast --load -o test.xxchan -u $NICK --waitTimeout 120s
./xx-client.linux64 broadcast --load -o test.xxchan -u $NICK --waitTimeout 120s
# in case of timeouts try logLevel 1 or 2 with: --logLevel 1
test.xxchan is the broadcast definition file which enables another party to listen to this broadcast. Secure it if your broadcast is private.
The default wait timeout value wasn't enough, so I extended it with --waitTimeout.
The reason is lately some xx Network gateway nodes had difficulties (potentially due to government interference in some countries) which makes it harder to connect. There's a log file which you can tail from another terminal to see that.
If you want to use a self-supplied RSA key, use --key ${FILENAME} to specify the RSA private key file, such as --key ~/.ssh/id_rsa_xxcli.
Second user
The second user needs the broadcast definition file, as there's no way to establish chat without it.
Share the broadcast file through Signal or use some other secure sharing method. A chat is no more secure than the medium through which this file has been shared.
The second user would normally have another nickname (although they're really identified by their private key) and needs to only load the channel, not create it.
Here we'll create the RSA key manually before we start (as we don't need to create a channel). This also means you can reuse existing RSA key if you have it.
export NICK="AnotherGuy"
ssh-keygen -t rsa -f AnotherGuyKeyfile
# move your new private key to the default private key file name for the chat "test"
mv AnotherGuyKeyfile test-privateKey.pem
# test.xxchan is the configuration file obtained from the first party
./xx-client.linux64 broadcast --load -o test.xxchan -u $NICK --waitTimeout 120s
For each client we use a different terminal (or different client altogether). Different chats use different broadcast definition files.
And that is it!
There are minor console-related bugs, and you'll need to reconnect (simply CTRL+C and then restart) if you get disconnected.
Other details
There are other details that you can find from online help, or by inspecting the code.
Available Commands:
broadcast Create or join broadcast channels.
completion Generate the autocompletion script for the specified shell
generate Generates version and dependency information for the binary.
help Help about any command
version Print the version and dependency information for the binary.
Flags:
-c, --config string Path to YAML file with custom configuration..
-h, --help help for cli-client
-v, --logLevel int Verbosity level for log printing (2+ = Trace, 1 = Debug, 0 = Info).
-l, --logPath string File path to save log file to. (default "cli-client.log")
--ndf string Path to the network definition JSON file. By default, the prepacked NDF is used.
-p, --password string Password to the session file.
-s, --session string Sets the initial storage directory for client session data. (default "session")
--waitTimeout duration Duration to wait for messages to arrive. (default 15s)
Use cases
xx CLI client cannot communicate with Speakeasy or Echoexx - as noted earlier, these use different module of xxDK.
But it can be useful on its own. Some examples:
- secure & private DM or group chat client for headless and remote systems without X Window System - like IRC, but with fewer features and more secure and private
- share IT-related secrets such as passwords and .env files with yourself or colleagues: load channel file, start the client, send or receive secrets and then delete the entire directory on the temporary client
A bit more on this last use case. You should use encrypted boot volume or change the secret if it's critical, as it's not technically possible to shred/wipe a single file on an unencrypted flash disk. For this use case you need to be able to get out to the Internet which is often, but not always (e.g. LAN) possible.
There are CLI scripts for "secure" password sharing, but they rely on personal infrastructure (some server & DB which may or may not be secure), or 3rd party infrastructure which may or may not be more secure than xx Network (and often doesn't have open source code on both the server and client).
There's also Tailscale, but again - to be equally secure, you still have to encrypt your data before sending it and probably at-rest as well (considering that the client is "online" at all times). If you can make use of Tailscale for other things that's great, but if you need something quick - like when setting up some VMs in the cloud - xx CLI client could be good enough.
xx CLI client could also be modified for other purposes, for example as a low censorship-free broadcast tool without the need for Tor (which mony networks block in any case). Access to the xx Network gateways can also be blocked, but most jurisdictions and corporate firewalls haven't done it yet.
As of now, xx Network gateways retain client side-encrypted data for 21 days, after which it expires and may be found only on the clients (if they logged in and downloaded it before it expired). So, keep in mind that you may shred the local session file, channel file and private key to disable access locally, while chat data stored on xx Network gateways expires in weeks. What you cannot delete is the messages other clients received on their side without access to those clients.