Skip to main content

12. Recording encryption

For fleet admins

This chapter is for whoever owns the cloud account and holds the keys. Field operators don't need it and can skip ahead.

A device can have a team's recording key bound to it. Once bound, every recording is already ciphertext at the moment it is written to the SD card — if the card is pulled, the device is lost, or it changes hands mid-way, whoever holds the card can't read a single frame without the key.

The key stays with the administrator. The people carrying the device can neither see nor change it; the phone app only shows one status, "encrypted / not encrypted", and offers no switch. That is deliberate: the device in the field is itself one of the things to protect against.

What changes once enabled​

  • File names, part sizes and the directory layout stay the same — still .mcap.
  • File contents become ciphertext. A tool without the key fails with an error instead of reading corrupt data.
  • read_mcap supports random access without decrypting the whole file first, at roughly unencrypted speed. For Foxglove playback and seeking, first create a plaintext copy with visio-decrypt.
  • Frame rate, duration and upload are unaffected.
  • session.json fills recording_key_fingerprint (16 hex characters; empty when unencrypted), that says "these files open with this key". It is only the key's fingerprint, not the key itself, and can travel with the files.

Two ways to enable​

Requires visio-schema 0.9.1+. The standalone visio-display bundle opens the console when launched. For visio-settings-qr and visio-decrypt, install "visio_schema-0.9.1.tar.gz[display,qr]" with pip; see Engineering integration.

Start the local console of visio-display on a computer:

visio-display --serve

Connect the device, then use the Keys area of the page to set, rotate or clear the key, and to see which key the device is currently using. The key is saved into your local keychain before it is written to the device, so you can never end up with "the device is encrypted but the admin has no key".

With a settings QR (for factory batches and remote teams)​

The administrator generates a QR code on their own computer; the collector scans it with the app's Scan settings (see 8. Scan-to-Configure). The key inside the code is wrapped so that device firmware can decrypt it; the key cannot be read from the QR or a screenshot. To restrict it to specific devices, pass --device.

# Generate a new key (back this file up; it is also saved in the local keychain)
visio-settings-qr keygen --out recording.key

# First provisioning: optional settings are prompted; Enter skips them. Default output: settings_qr.png
visio-settings-qr qr --recording-key-file recording.key --first-provision

To replace a key later, also pass the key currently in use (--old-recording-key-file); to stop encrypting, use --clear-recording-key, which likewise needs the current key. A code can be limited to specific devices (--device) or given an expiry (--expires-in).

Reading encrypted recordings​

Once the key is in your local keychain, day-to-day use is exactly like unencrypted recordings — you don't have to pass it each time:

# Open visio-display --serve, choose an encrypted file, and paste its 64-character hex key.
# After validation the key is saved in the keychain.

# 1) Or pass a key file for local Rerun playback (pip installation required)
visio-display --mcap-in ego_0000.mcap --key-file recording.key --rerun

# 2) Or keep it in the keychain file (indexed by fingerprint; several teams' keys can coexist)
#    ~/.config/visio/recording-keys.json

# 3) For tools that can't take a key (e.g. Foxglove Studio), write a plaintext copy
visio-decrypt ego_0000.mcap ego_0000_plain.mcap
A lost key means the data is gone for good

Encrypted recordings have no back door, and GI Labs cannot recover them for you. Back the key file up in at least two places, kept apart from the devices.

Under the hood​

Key handling checklist​

  • Generate the key on an administrator's machine, never on a phone or a field laptop.
  • Back it up in two places (for example a password manager and an offline copy), separate from the devices and from the SD cards.
  • Rotate with --old-recording-key-file rather than clearing and re-provisioning; old recordings keep their old fingerprint, so keep retired keys until every recording made with them has been decrypted or archived.
  • The fingerprint in session.json is safe to share; it lets a colleague find the right key in their keychain without exposing anything.
  • When a device leaves the fleet, clear the key (--clear-recording-key) before handing it over.

Engineering details​

Reading encrypted files from Python and from the visio-display bundles, the keychain file format, and how random access works are in 7.6 Reading encrypted recordings. Recording encryption is available on EGO1GS firmware 1.1.3+ and EGO1 firmware 1.1.6 — see 11. Firmware release notes.