Subspace Relay #

This repo contains protobuf definitions for transferring RFID-related packets between processes, for example over MQTT.

This provides a general purpose framework for many sorts of use-cases involving connected readers and emulators, not just relaying a physical card to a physical reader over some distance. This enables patterns such as using a PCSC reader remotely over the internet to talk to a card or to write emulation code in a higher level language running on a computer that can interact with a physical reader.

There are two sides of the communication in Subspace Relay, the relay side which exposes a card/reader/etc, and a consumer that utilises it. Relays are designed to be simple and controlled by the consumer. Some patterns may involve a single consumer application connecting to multiple relays while others may only talk to one relay.

Some patterns possible with Subspace Relay:

• Talking to a card across the internet
• Relaying a locally connected card to a remote emulator or vice versa
• Relaying a remotely connected card to a remotely connected reader
• "Soft" emulation of a card running on a computer being used to test a physical reader

Subspace Relay over MQTT #

In theory messages can be sent over any protocol, in practice MQTT has been used to date but it could be easily substituted for any other protocol, ideally one with support for headers to enable request-response but this is not essential if concurrency is not used.

Identification and Encryption #

The relay implementations generate a random relay_id, currently as a lowercase UUIDv7 with dashes stripped but any securely generated random identifier would work. The relay_id is then passed through pbkdf to derive the MQTT topic names and encryption keys. This means that if someone can only see the traffic on the MQTT broker they are unable to decrypt the communication.

Go Library #

There is a Go library go-subspace-relay that leverages this protobuf schema to exchange messages over MQTT as well as some example applications that make use of the library.

• subspace-relay-pcsc exposes a PCSC-connected reader
• subspace-relay-acr1555ble exposes an ACS ACR1555 reader connected via BLE using the go-acr1555ble library for connectivity
• subspace-relay-cardhopper-emulate exposes a Proxmark3 running the hf_cardhopper standalone mode as a card emulator
• subspace-relay-pcsc-consumer-demo a demo consumer that can talk to eg subspace-relay-pcsc to exchange APDUs

Generated Protobuf Libraries Usage #

Use in other languages where there is not yet a higher level library, or if implementing Subspace Relay over a different transport you will need to use the generated protobuf libraries directly.

Go #

The Go package can be consumed directly from GitHub with the following import:

import subspacerelaypb "github.com/nvx/subspace-relay"

In theory the Buf SDK could be used as well, but the module path handling isn't great, so consuming from GitHub is the preferable option.

Dart #

Buf unfortunately does not host a fully featured Dart package repository so generated dart code will be published to pub.dev.

Other Languages #

Buf will automatically generate SDKs for supported languages from corresponding Buf repo https://buf.build/nvxx/subspace-relay You can also use this to import types into your own protobuf packages.

A full list of supported SDKs can be found at https://buf.build/nvxx/subspace-relay/sdks/main:protobuf

Python #

Full instructions on consuming Buf generated SDKs in Python can be found at https://buf.build/docs/bsr/generated-sdks/python/

TLDR use pip --extra-index-url https://buf.build/gen/python or add the following to your pip.conf

[global]
extra-index-url = https://buf.build/gen/python

Then you can add the dependency with the following:

pip install nvxx-subspace-relay-protocolbuffers-python

uv and poetry are also supported, see https://buf.build/nvxx/subspace-relay/sdks/main:protocolbuffers/python for details

C# #

Full instructions on consuming Buf generated SDKs in C# can be found at https://buf.build/docs/bsr/generated-sdks/nuget/

A copy-pastable version specific to this repo can be found at https://buf.build/nvxx/subspace-relay/sdks/main:protocolbuffers/csharp