A live service duress prototype
Hacker News

A live service duress prototype

Secure file sharing

Secure file sharing: a Flask web app for sharing confidential files between users. Each file is encrypted at rest with its own AES-256-GCM key, kept only as copies encrypted to the public key of each person allowed to open it, checked with SHA-256 and an HMAC, and signed with an ECDSA key certified by a local CA.

  • Every file has its own AES-256-GCM key, stored only as copies encrypted with HPKE (X25519) for its owner and each person it is shared with: the server's own keys cannot open a stored file.
  • Files are signed with ECDSA P-256 keys certified by a local OpenSSL CA, with revocation and a signature proof that can be checked offline.
  • Uploads are checked by their content, not their name. Archives are accepted but marked Not checked for everyone they are shared with.
  • The database is encrypted with SQLCipher, and every file record is protected by an HMAC.
  • Argon2id passwords, server-side sessions, CSRF protection, rate limits, security headers and optional two-factor login.
  • Registering needs an invite code, and every username gets a random tag. Bans and a cleanup by inviter and time window undo what a stolen admin login let in.
  • A duress password that opens a cover vault of its own, kept apart by keys, and can wipe the rest.
  • The master key can also require a USB stick and a passphrase; pulling the stick locks the service.
  • A terminal console to run and manage the server.
  • A black-and-white interface in typewriter type, with an ASCII-art wordmark.

Installation

python -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
bin/vault-share install # the `vault-share` command, from any terminal
read -s -x CA_PASSPHRASE # fish; in bash: read -rs CA_PASSPHRASE && export CA_PASSPHRASE
pki/create_ca.sh
vault-share init-db
vault-share # the console; `vault-share serve` runs the server alone

read -s asks for the CA passphrase without showing it and without saving it in the shell history, which export CA_PASSPHRASE='...' would do. The console asks for it itself at startup when it is not set, and keeps it in memory only.

vault-share passes anything else to flask --app app, so vault-share keys status or vault-share admin grant 'bob#516850' work from any folder; vault-share install links the command into ~/.local/bin.

Then open http://127.0.0.1:5000 (the port can change, see "Server settings" below).

pki/create_ca.sh creates the local CA in instance/ca/ once; the app needs the same CA_PASSPHRASE every time it starts, to issue a certificate to each new user. Registering needs an invite code: make the first one with vault-share invite new (see below).

The page at /security, linked from every page's footer, tells users what this server stores and cannot read, what it records and for how long, which cookies it sets, and what its operator can do. Anyone can read it, logged in or not, and it stays up while the service is paused, since it needs neither the database nor the master key.

Uploads and signatures

Uploading asks for your password again: it unlocks your private key to sign the file. Each file's record carries an HMAC over all of its fields, from the owner and the hash to the name, the description and the signature, so a record edited in the database fails its check on the file page.

Each file page also offers a signature proof, a zip with the signature, the signer's certificate, the CA certificate and the OpenSSL commands that check the file without the app. They check the certificate as it was at the upload time, and name your copy FILE rather than using the file's name, which could hold shell syntax.

Every upload is checked before it is stored: its extension must be on the list, its content must really be that type (filetype reads the first bytes, so a program renamed .pdf is refused; text must be UTF-8, and JSON and TOML must be valid), and it must fit under the upload limit.

  • Documents: PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP
  • Images: PNG, JPG, GIF, WEBP, BMP, TIFF, HEIC
  • Audio: MP3, WAV, OGG, FLAC, M4A
  • Video: MP4, MOV, WEBM, MKV, AVI
  • Text: TXT, MD, CSV, JSON, TOML, YAML, INI, CFG, LOG

Archives (ZIP, 7Z, RAR, TAR, GZ, TGZ, BZ2, XZ) are accepted too: their signature is checked, so a program renamed .zip is refused, but not what they hold. They are marked Not checked, and the HMAC of the file's record covers that mark, so it cannot be dropped in the database. Everyone they are shared with sees a warning, and must tick "I understand" before downloading.

DOC, XLS, PPT and RTF (macros, embedded objects), and HTML, SVG, XML, scripts and programs (they run code when opened) are left out; share them inside an archive. A check tells what kind of file it is, not that it is harmless. The upload page explains all of this under "What happens".

Every visit to a file's page checks its record and signature, and every download checks the file itself. A record changed behind the app's back shows up at once:

Rate limits

At login, five wrong passwords for one username from one address block that pair for 15 minutes, and twenty from one address block the address; an IPv6 address counts as its whole /48 network, since one subscriber can switch among many.

A browser that logged in as someone keeps a signed cookie for a year that says so, holding a keyed digest rather than the name; browsers without it share fifty wrong tries an hour per username, wherever they come from, so many addresses together get about 1,200 guesses a day at one account instead of no limit at all. Wrong tries from somewhere else never lock the owner out of a browser they have logged in from before; during such an attack, a browser they never used has to wait for the hour to pass.

Once logged in, the password asked at upload, download, sharing, revoking, deleting and in the settings has a limit of its own, five wrong ones per account, which only that account's sessions can use up. Sharing with a username that does not exist counts too, ten an hour, since each one is a guess at someone's tag.

The counters live in memory (Flask-Limiter), so restarting the app clears them. A password check counts from the moment it starts, so requests sent at the same time cannot all slip under a limit: one that finds the limit filled by checks still running waits up to 10 seconds for them, and is refused only if they failed. Right passwords count too, sixty checks in 15 minutes per account, and at most four checks run at once: each one takes 64 MiB of memory.

Two-factor login

Two-factor login is optional, per user, from the "Two-factor" page: scan the QR code with an authenticator app such as Aegis or FreeOTP and confirm with a first code. Wrong codes count toward the same limit as wrong passwords, and each code works only once, even when two requests carry it at the same moment.

Turning it on also gives ten recovery codes, shown once in that page: each one logs in once instead of a code from the phone, and "New codes" replaces them. Someone who lost both the phone and the codes asks the operator, who can turn their two-factor login off with vault-share admin clear-totp ' ' or "Clear two-factor" in the console's Users tab.

Until it is confirmed, the new secret stays on the server with the session that asked for it: it never goes into the browser's cookie, and another session of the account cannot see it. An admin's new invite code is shown the same way, in the page that made it.

Duress password

The video below walks through the duress password on a test server: setting one, moving files to the cover files, and logging in with each password.

vault-share-duress-demo.mp4

A duress password, set from the "Duress" page, is the one to give if someone forces you to log in. It opens your cover files: a second vault that is real, where uploads, downloads, sharing and the settings all work, rather than an empty account that refuses things. What keeps your other files from it is keys, not hidden buttons.

Every account has a number of levels, each with its own X25519 key pair: the real password opens level 0, the duress password level 1, and each level after it, down to the account's last, opens with the duress password set from a session at the level above.

How many levels an account has is a secret: the server draws the number at registration, evenly from a range (16 to 47 by default, see "Server settings" below), seals it with the account's other levels, and shows it nowhere, on no page, log row or console screen. A duress password saved at the last level is kept like any other, answers "Saved" and does the same work, but opens nothing.

So counting how many nested duress passwords work before one fails tells a coercer nothing for a count inside the range: 20 can be the top of an account with 21 levels or level 1 of one with 22, and the even draw makes both alike.

A level's private key is locked under its password and also linked down from the level above, so a password opens its own level and the ones below it, never the one above. Each password typed costs one Argon2id run (9 passes over 64 MiB) with the account's salt, and every check and key of it comes from that run: a credential row keeps an HMAC of it, and the level's lock is made with a key derived from it. A login costs one run whatever it opens and however many levels there are.

The account's passwords share the salt, so one offline guess tests them all at once; the run, three times as strong as each of the three checks it replaced, pays for that. Every account has rows and key pairs for the largest number of levels, 47, whatever its own: one more key pair, after the account's last level and opened by no password, keeps that level's cover files.

Opening a session's keys always takes as many steps: after the real links down from its level, the rest go through a spare pair made at start-up, so a request at level 0 does the same work as one at the last level, on a short account as on a long one. Every session believes it is the top: it sees its own files, and the levels below it as its cover files, and every page looks the same at each level. A password asked inside a session is checked against that session's level only, so no form there can test another password.

The signing key hangs off level 46, which every password reaches, so files uploaded at any level carry the same certificate. The Duress page moves files between your own vault and the cover files, yours or shared with you: each move encrypts the key copy again to the other level's public key, so it asks for the password, and it is not logged.

Moves go one level at a time: a file a duress session moved further down shows among your cover files and opens, but only that session's level moves it back. A file shared again stays where its recipient keeps it, deeper if a duress window brings it down, so a share never takes a file out of the cover files. The page also shows when the cover files last changed, since an empty or stale cover vault looks wrong.

A duress login opens its level's window, which stays open until a login at a lower level number closes it. Meanwhile shares sent to the account arrive at that level, so whoever holds the duress session sees them arrive as on a real account, and files a duress session deletes are trashed instead of destroyed: hidden from everyone, recipients included, as if they were gone, and kept for the real owner. A file a duress session takes off its list is kept the same way, for the owner to put back. The real password deletes and dismisses for good.

The login that closes a window owes a review of what happened in it, and every login with that password goes to the review, its other sessions linking to it, until the owner says done: through a logout, a timeout or months away. The review shows the duress logins, what was done (with no invite code numbers), the files deleted, taken off the list, uploaded or shared with the account meanwhile, and the command the operator runs to revoke the certificate from the time the window opened, since whoever held the duress password could sign in the user's name.

Each of its actions says whether whoever holds the duress password will see it, and the quiet ones are the defaults:

  • A deleted file: a private copy is quiet. The file is decrypted with the reviewing session's keys and stored again as a new file of its own, with a new id, key, signature and record HMAC; the deleted one stays deleted and leaves the review of the session that copied it only (table copied). Restoring it for everyone is loud. A copy signs what it copies, so the list marks the files uploaded while the window was open, and once the certificate is revoked from the window's start, as the review advises, those no longer pass their checks and are not copied.
  • An uploaded file: a label is quiet, a chip on the reviewing session's own lists only (table labels). Deleting it is loud.
  • A file shared meanwhile: leaving it is quiet. Bringing it back to the reviewing session's own files is loud: to the duress vault it looks as if the sender stopped sharing it, which is safe only with an honest sender, whose name the list shows.
  • A file taken off the list: putting it back is quiet, as the duress vault still finds it removed.

The review also says plainly that whoever holds the duress password can log in with it again and will see what is shared from then on, and offers to keep it or to replace it, which is not quiet once the old one stops. Deleted and removed files are kept 30 days from when the review first shows them, so an owner who never logs in loses nothing; "Done" restores what is left, which is loud, or lets it go, which is quiet.

A duress session that closes the window of a level below its own gets the same review: every level looks like the top. A duress login is the silent alarm: its login row is written at its level, and the console shows it as duress. So does every admin session, at any level, for another account's duress logins and for its own account's logins at a level below its own; at the duress level itself it is a plain login. A duress admin session thus shows the alarms a real one would, other peo

Read on Hacker News ↗ ← Back to News

Comments

No comments yet. Start the discussion.