How it's built

What Klenod relies on, how we check it, and what isn't done yet. Everything here can be checked in the source code.

Standard cryptography only

Klenod uses well-known primitives from Go's standard library and its maintained extension, golang.org/x/crypto. It invents none of its own.

  • XChaCha20-Poly1305 for everything stored: file contents, names, folders, tags and the library index. Tampering is detected when data is read.
  • Argon2id to turn your passphrase into a key. It makes three passes over 64 MiB of memory, which makes guessing slow.
  • HKDF-SHA256 for a separate key per file and per purpose.
  • Ed25519 signatures and X25519 key agreement for shares and contacts.
  • The operating system's secure random number generator, nothing else.

A documented format

How a library is laid out, encrypted and checked is written down in FORMAT.md, including the points that are still open. Files are stored in 4 MiB pieces, each sealed separately and bound to its library, file and position, so pieces can't be swapped, reordered or cut short without detection.

Tested for leaks

More than 350 automated tests run on every change, on macOS and Linux, with Go's race detector. Several exist only to catch leaks. They check that no plaintext reaches the disk or S3 storage, that a damaged library never produces decrypted files when restored, and that buffers holding decrypted data are wiped. Browser tests play real videos through the app.

A separate leak check runs the real Mac app in a throwaway macOS virtual machine. It fills a library with made-up files carrying random markers, then uses it like a person would: playing videos, viewing photos, on-device analysis, a second copy and an export. It searches the whole disk, Spotlight and the system log for the markers, while the library is open, after it quits and after a crash mid-playback, and checks every file the app wrote, even ones deleted again. It also pushes memory to swap while a video plays and searches the swap files, and plants known leaks to prove the search finds them. The check is in the source code.

Few dependencies

The command-line app is built from 22 Go modules, most from Go itself, Proton (for opening Proton Drive links) and AWS (for S3). The web interface has no npm dependencies. Its one bundled library, mpegts.js, plays older video formats.

Memory and your Mac

  • The library's key is kept in locked memory while it's open and wiped when it locks.
  • The decrypted pieces kept for smooth playback are in locked memory too, so macOS never writes them to swap.
  • The app's web view keeps nothing on disk, neither a media cache nor web storage.
  • The library locks when you're idle, when your Mac sleeps or locks its screen, and from any app with ⌃⌥⌘L.
  • The window is left out of screenshots, recordings and screen sharing unless you turn that off.

What the operating system does with the rest of memory, swap and crash reports is outside Klenod's control. macOS encrypts swap, and FileVault protects the rest of the disk. The unlock screen tells you when FileVault is off. The security overview lists where the limits are.

The network

Klenod connects only to the services whose links you open and the storage you choose. It has no analytics or crash reports, and there is no Klenod server or update check yet. Video conversion, the built-in player and the search helper run with network access turned off. The privacy page lists every connection.

Not done yet

  • Signed and notarized downloads. These come before the first release. Preview builds are unsigned.
  • Fuzz testing of the format and the link parsers.
  • Automatic checks for known vulnerabilities in dependencies.

Licences

The library format, the code that encrypts, stores, verifies, mirrors and restores a library, and the code that opens shared links from MEGA, Proton Drive and the other services are open source under the Mozilla Public License 2.0. That includes an open-source build of the klenod command-line tool, which opens, backs up, verifies and exports a library without the rest of Klenod. Everything else, meaning the Mac app, the library browser and player, sharing and search, is under the Business Source License 1.1. Anyone can read that code and build it for their own use. It may not be used to offer a product that competes with Klenod, paid or free. Each version becomes open source under Apache 2.0 two years after its release. The name Klenod is a trademark. Forks may use the code but not the name. Found a problem? Report it privately.