Skip to content

Latest commit

 

History

History
 
 

gui-client

README.md

gui-client

This crate houses a GUI client for Linux and Windows.

Setup (Ubuntu)

To compile natively for x86_64 Linux:

  1. Install rustup
  2. Install pnpm
  3. sudo apt-get install at-spi2-core gcc libwebkit2gtk-4.0-dev libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev pkg-config xvfb

Setup (Windows)

To compile natively for x86_64 Windows:

  1. Install rustup
  2. Install pnpm

Recommended IDE Setup

(From Tauri's default README)

Building

Builds are best started from the frontend tool pnpm. This ensures typescript and css is compiled properly before bundling the application.

See the package.json script for more details as to what's going on under the hood.

# Builds a release exe
pnpm build

# Linux:
# The release exe, AppImage with bundled WebView, and deb package are up in the workspace.
stat ../target/release/firezone
stat ../target/release/bundle/appimage/*.AppImage
stat ../target/release/bundle/deb/*.deb

# Windows:
# The release exe and MSI installer should be up in the workspace.
# The exe can run without being installed
stat ../target/release/Firezone.exe
stat ../target/release/bundle/msi/Firezone_0.0.0_x64_en-US.msi

Running

From this dir:

# This will start the frontend tools in watch mode and then run `tauri dev`
pnpm dev

# You can call debug subcommands on the exe from this directory too
# e.g. this is equivalent to `cargo run -- debug hostname`
cargo tauri dev -- -- debug hostname

# The exe is up in the workspace
stat ../target/debug/Firezone.exe

The app's config and logs will be stored at C:\Users\$USER\AppData\Local\dev.firezone.client.

Platform support

Ubuntu 20.04 and newer is supported.

Tauri says it should work on Windows 10, Version 1803 and up. Older versions may work if you manually install WebView2

x86_64 architecture is supported at this time. See this issue for aarch64 support.

Threat model

We can split this to its own doc or generalize it to the whole project if needed.

This is prescriptive.

The Windows client app:

  • SHOULD protect against the device being stolen or tampered with, if Windows is locked the entire time, and if the incident is reported quick enough that the token can be revoked
  • Cannot protect against malicious / rogue users signed in to the application
  • Cannot protect against malware running with the same permissions as the user
  • Cannot protect against an attacker who has physical access to a device while Windows is unlocked

Where the client app does protect against attackers, "protect" is defined as:

  • It should be impractical to read or write the token, while Windows is locked
  • It should be impractical to change the advanced settings to point to a malicious server, while Windows is locked

Security as implemented

The Windows client's encrypted storage uses the keyring crate, which uses Windows' credential management API.

It's hard to find good documentation on how Windows encrypts these secrets, but as I understand it:

  • They are locked by a key derived from the Windows password, so if the password has enough entropy, and Windows is locked or shut down, the passwords are not trivial to exfiltrate
  • They are not readable by other users on the same computer, even when Windows is unlocked
  • They are readable by any process running as the same user, while Windows is unlocked.

To defend against malware running with user permissions, we'd need to somehow identify our app to Windows and tell Windows to store our token in such a way that un-signed apps cannot read it.

Here are some sources I found while researching:

There are at least 2 or 3 different crypto APIs in Windows mentioned in these pages, so not every comment applies to keyring. I think DPAPI is a different API from CredReadW which keyring uses: https://github.com/hwchen/keyring-rs/blob/1732b79aa31318f6dcbcc9f686ce5f054ffbb509/src/windows.rs#L204