Keeping the offline device offline

How AirWallet keeps the signer off the network on each platform, what each lock covers, how to check it, and how to set up the device.

The offline signer is only as safe as its isolation. AirWallet refuses the network in its own code on every platform. Where the operating system offers a lock, AirWallet switches that on too. The rest is up to you: a device that never goes online again.

#Two ways to run an offline signer

You can set up the regular AirWallet as an offline signer. Choose Offline signer on its first screen, or later in Settings → This phone: everyday wallet… (or This computer) → Use this phone as the offline signer….

AirWallet Offline is a separate, hardened build. Its locks are on from the first start, and it cannot be switched to the everyday mode. Use it when you want the strongest guarantee, especially on Android.

If you switch a signer that holds keys back to the everyday mode, AirWallet warns you first, because the keys stop being air-gapped. The button then reads Go online anyway. The safer path is to keep that device as the signer and use another one every day.

#How each lock works

The desktop apps have 2 parts. A Python back end stores your data and is the only part that could reach the network. A window shows the screens, and the wallet's own code runs in that window's web page. The operating-system locks below apply to the Python back end and everything it starts. The window is held back separately: its page may connect only to the back end on the same computer (its Content-Security-Policy says connect-src 'self'), and it cannot navigate away from that page.

#Inside AirWallet, on every computer

In offline mode, the back end refuses every request the page asks it to make. Its Python also refuses the network at a lower level. AirWallet replaces Python's connect, connect_ex, sendto, sendmsg and bind with versions that allow only localhost and loopback addresses, and blocks name lookups such as getaddrinfo. It deletes every *_proxy environment variable and turns off Python's proxy discovery. Without that, a proxy app on the same computer, such as Clash, Surge or Tor, could carry a request out.

This layer works even where no operating-system lock is available.

#macOS

The back end starts itself again inside sandbox-exec, with a profile that:

• denies every outgoing connection except to localhost and local sockets
• denies the system's name lookup service (mDNSResponder)
• denies opening web addresses or other apps

Everything the back end starts inherits the sandbox. If this Mac cannot load the profile, the app keeps only its Python lock, and Settings says "Enforced inside its Python".

#Linux

The back end installs a kernel filter (seccomp) once its local server is listening. No admin rights are needed. The filter makes socket() fail with "permission denied" for every kind of socket except local ones (Unix and netlink), and it blocks io_uring, which could open sockets around the filter. Everything the back end starts afterwards inherits it.

The filter is built for x86-64 and 64-bit ARM. On any other processor, the app keeps only its Python lock, and Settings says so.

On Linux, the window starts before the filter, so the filter does not cover it. In offline mode the window sends every request except the computer's own to a dead-end proxy.

#Windows

Windows has no lock a program can switch on for itself. AirWallet Offline comes with Block network (admin).cmd:

1. Right-click Block network (admin).cmd in the app's folder.
2. Choose Run as administrator.

It adds 2 Windows Firewall rules, named "AirWallet offline", that block the folder's python.exe and pythonw.exe from the network. The one-file .exe unpacks into a new folder under %LOCALAPPDATA%\AirWallet for each version, and the file is in that folder. Run it again after you move the folder or update the app, because the rule names the exact path. Settings → This computer shows whether the rule is in force.

The firewall rule covers Python only. The window (WebView2) is held back by its page's policy and by a dead-end proxy.

#Android

AirWallet Offline's manifest has no internet permission, so Android refuses the whole app every network connection, with Wi-Fi on or off. It asks only for the camera at runtime. In every Android build, the web view is also told not to load anything from the network (setBlockNetworkLoads).

The regular app in offline signer mode refuses connections in its own code only. For a lock Android enforces, install AirWallet Offline on the signer phone.

#Chrome extension

The AirWallet Offline extension has no permission to reach any website, and its pages' policy says connect-src 'none'. Chrome enforces both. It opens in a tab, where the camera works, so it can turn a Chromebook into the signer: turning on Developer mode in chrome://extensions is all it needs.

#Check it yourself

On the offline device:

1. Open Settings → This phone: offline signer… (or This computer, or This browser). The page is called Offline: the proof, and it says which lock is in force.
2. Select Try to connect. AirWallet tries 2 ways out to https://airwallet.tech/: through the app's back end, and through the page itself. Both must say refused.

If either says CONNECTED, do not keep keys on that device until it is fixed. Tell us through Help → Report a problem.

#Set up the device

The app's locks stop AirWallet from connecting. These steps keep the rest of the device quiet too.

1. Pick a spare device that you will use only for AirWallet. Old phones are fine. See Platforms and compatibility.
2. While it is still online, do any updates it needs. On Android 7 to 9, update Chrome first. Then install AirWallet Offline, or AirWallet as an offline signer, and nothing else.
3. Take it offline for good. Turn on airplane mode, turn off Wi-Fi and Bluetooth, take out the SIM card, and forget saved Wi-Fi networks.
4. Turn on the app lock in Settings → App lock.
5. Check it with Try to connect, as above.

Then pair it with your everyday wallet: see Set up an offline signer. From then on, only QR codes go between your devices. To install an update, carry the file over by USB cable or SD card, with airplane mode still on. See Updates, downloads and outside code.