Skip to main content

Crate iwlink

Crate iwlink 

Source
Expand description

IntelliWallet Link: the encrypted protocol between the IntelliWallet phone app and the IntelliWallet for Browser helper on a computer.

The helper advertises a Bluetooth Low Energy service; the phone connects to it and the two run a Noise handshake over GATT. Once the handshake is done, every message between them is a JSON Message sealed by the Noise transport. Bluetooth itself is treated as an open radio: nothing here relies on Bluetooth pairing or link-layer encryption.

The crate is deliberately free of platform code. It never touches Bluetooth, files, the Keychain or the clock: callers pass bytes and the current time in, and get bytes out. That is what lets the same code run in the phone app (through iwapp’s own Rust layer) and in the macOS helper, and what lets the tests control time.

§Layers, bottom up

Beside them, pairing encodes the QR code that starts a pairing, version negotiates the protocol version, and grant holds the timing rules both sides must agree on.

§Handshakes

  • Pairing, once per computer: Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s. The phone is the initiator. It learns the helper’s static key and a one-time pre-shared key from the QR code, so a helper that did not show that QR code cannot complete the handshake.
  • Reconnect, every later connection: Noise_KK_25519_ChaChaPoly_BLAKE2s. Both sides already hold each other’s static key from pairing.

Fresh ephemeral keys on both sides make every session unique, so a recorded session cannot be replayed into a new one.

§Example

use iwlink::{Handshake, HelperId, PairingOffer, StaticKeypair};

let now = 1_800_000_000;

// Helper: show a QR code.
let helper = StaticKeypair::generate()?;
let offer = PairingOffer::create(HelperId::generate()?, helper.public(), "Studio Mac", now)?;
let qr_text = offer.to_uri();

// Phone: scan it and start pairing.
let phone = StaticKeypair::generate()?;
let scanned = PairingOffer::parse(&qr_text)?;
let mut initiator = Handshake::pairing_initiator(&phone, &scanned, 1, now)?;
let mut responder = Handshake::pairing_responder(&helper, &offer.psk, 1)?;

let first = initiator.write(b"")?;
responder.read(&first)?;
let second = responder.write(b"")?;
initiator.read(&second)?;

let mut phone_side = initiator.finish()?;
let mut helper_side = responder.finish()?;
let sealed = phone_side.session.seal(b"hello")?;
assert_eq!(helper_side.session.open(&sealed)?.as_slice(), b"hello");

Re-exports§

pub use error::LinkError;
pub use error::Result;
pub use keys::PublicKey;
pub use keys::StaticKeypair;
pub use message::Message;
pub use noise::Established;
pub use noise::Handshake;
pub use noise::Session;
pub use pairing::HelperId;
pub use pairing::PairingOffer;
pub use version::VersionRange;

Modules§

error
Error type for the link protocol.
frame
Fragmenting sealed messages to fit Bluetooth writes.
grant
Timing rules for requests and grants.
keys
Static X25519 keys.
message
Protocol messages.
noise
Noise handshakes and the encrypted transport.
pairing
The pairing QR code, and the confirmation code both screens show.
version
Protocol versions.