pwdsphinx 2.0.4

SPHINX password protocol

SPHINX: A Password Store that Perfectly Hides from Itself (No Xaggeration)

SPHINX is a cryptographic password storage protocol that provides information-theoretic security. pwdsphinx is a Python wrapper around liboprf - a cryptographic password storage as described in https://eprint.iacr.org/2015/1099.

Unlike traditional password managers, SPHINX only stores random numbers unrelated to your actual passwords, ensuring the server learns nothing about them.

Key Features:

• 🔒 Information-theoretic security: Mathematically proven protection
• 🌐 Zero-trust architecture: Server knows nothing about your passwords
• 🚫 Offline bruteforce resistance: Your passwords are safe even if the server is compromised
• 🏠 Self-hostable: Run your own server or use someone else's
• 📱 Cross-platform: CLI, browser extensions, Android app, and X11 integration
• 🔑 Password generation: Creates strong passwords according to site requirements

Also on Radicle

To clone this repo on Radicle:

rad clone rad:z3rjK2hk7ckb1thexdsuyaM7e4FwS

Dependencies

Required Dependencies

• liboprf: An Oblivious Pseudo-Random Function (OPRF) is a cryptographic protocol where a client can evaluate a pseudo-random function on their input using a key held by a server, without the server learning the client's input or the function's output. liboprf implements OPRFs, which is used to enables SPHINX's zero-knowledge password storage.
• libequihash: This provides rate limiting proof-of-work with fast verification
• pysodium and pyoprf: Python cryptographic bindings. Both can be installed using either your OS package manager or pip.

Optional Dependencies

For browser extensions: If you also want to use the websphinx browser extension, you also need to install an X11 variant of pinentry from the GnuPG project.

# Install any one of these, using the equivalent of `apt-get` on your operating system:
apt-get install pinentry-qt        # For KDE/Qt environments
apt-get install pinentry-gtk2      # For older GNOME/GTK environments
apt-get install pinentry-gnome3    # For modern GNOME environments
apt-get install pinentry-fltk      # Lightweight option

For X11 integration:

• xdotool: Keyboard/mouse automation
• xinput: Input device control
• dmenu: Interactive menus

For extended storage: If you want to store other "secrets" that are longer than just 77 chars, you can install OPAQUE-Store:

• opaque-store: Encrypted file storage: pip3 install opaquestore
• OPAQUE-Store: OPAQUE protocol implementation, a dependency for OPAQUE-Store above.

Installation

pip3 install pwdsphinx

On Debian-based systems, you can also do:

sudo apt install pwdsphinx

Architecture

SPHINX uses a client-server architecture where:

Server (Oracle)

The server stores only cryptographic blobs that are useless without your master password. Even if compromised, your actual passwords remain secure.

Host your own server: See oracle(1) or the Server Installation Guide for how to configure your server.

Client

The client combines your master password with the server's response to regenerate your actual passwords deterministically.

Supported platforms:

• Command Line: Full-featured CLI client (see sphinx(1) for how to configure a client)
• Browser: Firefox and Chromium extensions with native messaging
• Desktop: X11 integration scripts for form filling
• Mobile: Android app (androsphinx)

Usage

SPHINX provides a complete lifecycle for password management:

Core Operations

• create: Generate new password for a site
• get: Retrieve existing password
• change: Update password (two-phase commit)
• commit: Activate changed password
• undo: Revert to previous password
• delete: Remove password record
• list: Show usernames for a site

Management Operations

• init: Initialize client with new master key. It also sets up browser extensions if ~/.mozilla or ~/.config/chromium directories are found.
• healthcheck: Test server connectivity
• qr: Export configuration as QR code

See sphinx(1) for detailed command syntax and examples.

OPAQUE-Store Client Integration

If you have OPAQUE-Store installed and configured correctly, you get a number of additional operations, which allow you to store traditionally encrypted blobs of information. For a gentle introduction on how this works using the OPAQUE protocol, have a look at this post: https://www.ctrlc.hu/~stef/blog/posts/How_to_recover_static_secrets_using_OPAQUE.html

The following operations will be available if OPAQUE-Store is setup correctly:

echo -n 'password' | sphinx store <keyid> file-to-store
echo -n 'password' | sphinx read <keyid>
echo -n 'password' | sphinx replace [force] <keyid> file-to-store
echo -n 'password' | sphinx edit [force] <keyid>
echo -n 'password' | sphinx changepwd [force] <keyid>
echo -n 'password' | sphinx erase [force] <keyid>
echo -n 'password' | sphinx recovery-tokens <keyid>
echo -n 'password' | sphinx unlock <keyid> <recovery-token>

See the OPAQUE-Store X11 integration documentation for more details on these operations and how the integration works with SPHINX.

Browser Integration

There is WebSphinx, our browser extension that provides seamless password filling. See the browser extension instructions on how to set it up on Firefox and Chrome/Chromium browsers

X11 Desktop Integration

SPHINX includes shell scripts for X11 desktop integration using dmenu, xdotool, xinput, and pinentry.

The main script dmenu-sphinx.sh provides interactive password filling with a dmenu interface. It stores hostname history in ~/.sphinx-hosts (link to /dev/null if you consider this sensitive).

The integration enables automatic form filling in X11 applications through keyboard automation for password entry. It works with pinentry for secure password input.

See contrib/README.md for setup examples and script combinations.

More documentation

For Users

• Getting Started Guide: Complete setup and usage tutorial
• Manual Pages: Detailed command reference
  • sphinx(1): Main client commands
  • oracle(1): Server configuration and management
  • getpwd(1): Secure password input utility

For Developers & Advanced Users

• X11 Integration: Desktop automation scripts
• OPAQUE-Store Integration: Encrypted file storage
• Contributing Scripts: Helper utilities and examples

Credits

This project was funded through the NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310.

This project was funded through the e-Commons Fund, a fund established by NLnet with financial support from the Netherlands Ministry of the Interior and Kingdom Relations.

Everlasting gratuity to asciimoo, dnet, jonathan and hugo for their contributions, patience, and support.