A12

A12 is the network protocol Arcan clients that both arcan clients and arcan appls can use to communicate between devices and to find other arcan enabled devices.

Overview

A12 has a core protocol which covers the 'minimum viable' confidentiality, authenticity and integrity support cryptography. Each connection defines a static role as 'source', 'sink' or 'directory'. It has up to 256 unidirectional channels per connection, where one channel can transmit 1 stream of audio, video and binary data along with intermittent events.

The event model is shared with SHMIF, with an overloaded interpretation / use of the same events in directory mode.

Dependencies

• Cipher / CSPRNG: Chacha 8
• Checksum / HMAC / KDF: BLAKE3
• Asymmetric primitives: X25519, Ed25519
• Compression: Zstd, (optional) ffmpeg-h264

Implementations

libarcan-a12

This resides in src/a12 and contains the necessary state machine, encoding and decoding. It is statically linked into the other implementations.

afsrv_net

This tool is intended to be exclusively used from the appl being run by arcan. It is controlled through the net_ set of functions: net_open, net_discover, net_listen.

afsrv_encode, afsrv_remoting

This resides in src/frameserver/afsrv_encode and afsrv_remoting respectively. They are simplified clients that treats the channel connection as the 'vnc/remote framebuffer/ssh' kind of use cases where you have a main window ('desktop sharing') and auxilliary channels used for metadata (like clipboard/cut-paste) transfers.

arcan-net

This resides in src/a12/net and provides a CLI tool for both setting up directory servers, downloading / running appls, generating or running beacons. It is intended to be used in restricted builds where the rest of the full arcan stack might not be available or desirable.

support

src/frameservers/util contains a few helpers for connection setup and keystore management. The default keystore implementation, naive, is implemented here.

Discovery

There is a separate discovery provision of a12 using the petnames (tags) in the keystore combined with the set of known public keys to beacon and find other a12 capable devices on a IPv4 LAN broadcast or IPv6 multicast space.

The protocol is as follows: 1. Generate a 64-bit CSPRNG challenge, CHG. 2. Calculate H(CHG | Kpub1) .. H(CHG | KpubN) with Kpub coming from a set of public keys used in outbound commincation. 3. Calculate H(CHG | (set from 2), out=8). 4. Send packet on port 6680. 5. Wait 1 second. 6. Repeat 2,3,4 for (CHG+1).

For parsing/listening: 1. Collect and timestamp beacons until a CHG,CHG+1 pair is found, verify that the challenges are at least 1 second apart. 2. Calculate H(CHG, Kpub) over the set of public keys you know, save matches/petnames for any discovered. 3. Track (CHG, CHG+1) in a bloom filter like structure and ignore, to prevent replays. 4. (optionally) verify any matches that H(CHG+1, Kpub) is part of the second beacon in the same slot. 5. react on the now discovered keys.

This setup puts a higher cost in sending a beacon than verifying, it keeps traffic in the network low through the time-elapsed requirement.

Directory

When running arcan-net in "directory-mode" it acts as a special a12 server. It defines 6 new commands for the primary (0) channel:

1. LIST - (request) Retrieve (or subscribe) to the index of appls available to the authenticated user. Results will be provided as 'STATE'
2. STATE - (response) Learn about changes to the contents or availability of an appl.
3. DISCOVER - (response) Learn about new data sources arriving.
4. OPEN - (request) attempt to access (source or sink or linked directory). This may result in a direct connection (rendezvous/punch) or through a (tunnel). The tunnel form works like the normal a12 connection, but with a pre-set / fixed authentication secret and public key.
5. OPENED - (reply) inform if an OPEN request succeeded or not.
6. TUNDROP - (reply) inform that a previously opened connection in tunnel mode has lost its connection due to the other end terminating.

These are used to provide several other features:

• Acting as a server for loading/storing arcan appls.
• Acting as a friend-to-friend network for WAN unicast discovery.
• Acting as a messaging group for users of an appl.
• Acting as a shared store for users of an appl.
• Acting as a private state for for users of an appl.

Specific access to state and file resources are made just like alternate stream transfers on A12 channels - a BCHUNKSTATE or STORE/RESTORE event that follows the a new bstream being attached to the channel. The difference for directory mode is that some names are reserved:

• 'applname.debug' - used to submit a trace of a previous appl execution error.
• 'applname.server' - used to attach a server-side processing script in the slot for the applname.

A user with permission can live update an appl: arcan-net --push-appl /path/to/myappl my.directory.server (or with /path/to/myapp.server') would set that up. Clients running that appl actively will receive notification that it has changed, and MAY chose to state store, fetch the updated one and state restore. Another option in the event of a script error in the new version would be to send the error as .debug state and revert to the old one.

The appl is transmitted with a one-line key=value:key2=value2 like manifest, a name:size=... followed by n-bytes of contents. The manifest part is used to specify which frameserver permissions the appl expects running locally. Some, specifically 'terminal' is inherently dangerous as it would give much extended local system access to the appl code. This is useful (and necessary) for one's own desktop like contexts, but not when running from a partially trusted source.

The .server side scripting end is still being fleshed out, but aims to look like a much reduced subset of a regular Arcan appl.

Configuration

Currently, arcan-net is used through a mix of environment variables and command line switches. In tandem with server side appl script attachements, it will be possible to attach a .lua script with configuration parameters per key as part of the keystore or as a specific --directory my-config.lua. This is to make it organic to handle different compression parameters for different clients based on a priori knowledge, relevant when, for instance, considering passthrough of opaque-proprietary video compression.