KeyWhisper

Inspired by my project https://hackaday.io/project/202196-macro-keypad-controlled-by-sound, this project use the principle of sending data by sound

Send your passwords by sound. KeyWhisper is a small password manager whose vault stays on your computer. To use a password on another device, you don't type or copy it — you play a short sound from a web page, and KeyWhisper hears it, rebuilds the password locally, and puts it on your clipboard (or types it for you). The password itself never travels; only a harmless key fragment does.

Built on top of an audio modem (data over sound, FSK) that lives in the same project.

Install

pip install -r requirements.txt

# Graphical interface:
sudo apt install python3-tk
# Clipboard / auto-typing (install what matches your session):
sudo apt install xclip xdotool        # X11
sudo apt install wl-clipboard         # Wayland

Start here

python3 start.py

On the very first run KeyWhisper walks you through everything:

1. Language — English (default) or French. Remembered for next time (changeable later in ⚙ Settings).

2. First-time setup (only if you have no vault yet). It explains and asks for the three parts of your master key:

   • masterKeyPart1 — a secret stored on this computer. One click generates a random 128-bit one.
   • masterKeyPart2 — a short secret you remember (≥ 6 characters). This is the piece that travels by sound.
   • PIN — at least 4 characters, asked when you open the vault.

   Your master key is masterKeyPart1 + masterKeyPart2 + PIN. No single part is enough on its own, so a sound recording alone can never unlock your passwords.

After that, KeyWhisper opens its main window and you're ready to go.

Everyday use

On your computer (the receiver): open KeyWhisper and let it listen.

On your phone or another device (the sender): open the web page web/sendKey.html in a browser. available here as well : https://oktoapp.com/KeyWhisper

• Enter your masterKeyPart2 once (top of the page).
• Search or pick the site you want.
• Press Emit — hold it near your computer's microphone.

Your computer hears the site name and the key fragment, rebuilds the real password from your local vault, and copies it to your clipboard (or types it, if you turned that on). Serve sendKey.html over https or localhost to enable the optional one-time masking of your key fragment (see Security below).

Managing your vault

Everything is in the main window:

• Add / remove passwords — unlock the vault with your PIN (and masterKeyPart2).
• Copy a password to the clipboard.
• Change your PIN or masterKeyPart2.
• Generator — create strong passwords, even without a stored entry.
• Export site names — a plain list of your sites (no passwords) you can import into sendKey.html so it knows your sites on another device.
• Settings — pick the sound protocol, choose the output (clipboard or typing), switch language, or show the debug log.

Security

• Your vault is encrypted with PBKDF2-HMAC-SHA256 (200 000 iterations) and AES-256. Wrong PIN or wrong key? You get no error and zero passwords — it never reveals whether a guess was close.
• Only masterKeyPart2 ever leaves your computer, and only by sound. It's one factor of three — useless without masterKeyPart1 (on your PC) and your PIN.
• Optionally, masterKeyPart2 is hidden in transit by a one-time temporal mask SHA-256(secret + time-window) that changes every 120 seconds (needs https/localhost on the sender). The receiver detects masked vs. clear automatically.

Advanced launchers — apps/

For finer control, run a single piece directly:

Command	What it does
python3 apps/coffre_gui.py	The graphical interface alone (skips first-run setup).
python3 apps/coffre_ecoute.py	Listen for a key by sound, from the command line (--protocol, --type, --pin…).
python3 apps/coffre_admin.py add|get|remove|list|export …	Manage the vault from the command line.
python3 apps/modem_recepteur.py	Debug modem receiver (multi-protocol, GUI + self-tests).
python3 apps/test_presse_papier.py	Clipboard diagnostics.

The sender is always the web page web/sendKey.html. web/keypass.html manages the vault in a browser; web/emetteur_multimode.html is the modem test bench.

Project layout

start.py      main entry point (first-run wizard + GUI)
apps/         granular launchers
lib/          internal code — do not run directly
                config, audio_stream, dsp, protocol, pipeline (3-thread pipeline)
                first_run (setup wizard), keypass, readKey, readKey_gui, recepteur
                protocols/  (ook, ook3, fsk2/4/16, fsk16x2, fsk16x3, am4, multitone)
lang/         en.json, fr.json  (all UI text)
web/          HTML pages + crypto-js.min.js

Your data stays at the project root: keypass_db.txt (encrypted vault) and readkey.conf (masterKeyPart1 + temporal secret + language). Keep both private.