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
frame: splits a sealed message into Bluetooth-sized fragments and puts them back together.noise: the two handshakes (noise::Handshake) and the transport (noise::Session).message: the typed messages and their limits.
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.