Getting started

So you want to start using SPHINX for handling your passwords. Great, Welcome!

First you need to decide if you want to host your own server (we call it oracle), or you want to use someone elses oracle. It's ok to use someone elses server, as we say the oracle can be hosted by your worst nightmare enemy, they will not learn anything about your passwords[1].

It is important to note, that if you want to use sphinx, your client needs to be able to connect to the oracle.

Installing the sphinx CLI client

If you are on debian or derivates a simple

% sudo apt install pwdsphinx

should suffice and you can skip over to the next section to configure the client. But before skipping you might also want to install these optional dependencies:

% apt install pinentry-gtk2 xdotool xinput

If you are not on debian derivates, you need to build two dependencies manually. Let's start with libsphinx:

% git clone https://github.com/stef/libsphinx
% cd libsphinx/src
% sudo apt install install python3 libsodium libsodium-dev
% sudo PREFIX=/usr make install

We also need libequihash:

% git clone https://github.com/stef/equihash
% cd equihash
% sudo PREFIX=/usr make install

And finally install the client itself:

% pip install pwdsphinx

Dependencies might also needed for some things:

% apt install pinentry-gtk2 xdotool xinput

(replace apt install and the package names with whatever equivalent your distro provides)

Configuring the sphinx CLI client

Create a config file ~/.sphinxrc and insert the correct address and port for the server (oracle) you are going to use:

[client]
address = your.sphinx-server.tld
port = 443
timeout = 3

Now you should be ready to initialize your sphinx client:

% sphinx init

This will create a file ~/.sphinx/masterkey, you should make a backup of this file, and if you intend to use sphinx on other devices sharing the same passwords on them, you must copy this file there as well. If you intend to use androsphinx our android sphinx client, you can also do:

sphinx qr key

And have this qr-code read by the androsphinx client to use the same config as you have setup here.

You should be ready to go:

echo -n "password" | sphinx create testuser testhost

This should give you a long very random password as output. You can now check if you get the same password back, but since echoing passwords on the command line is not very smart, let's try with a tool that comes with pwdsphinx: getpwd:

getpwd | sphinx get testuser testhost

This should pop up a password query window, where you should enter 'password' as the password, the response should be the long random password that was returned when you used the create command.

And you can now also try to delete this test password, as you surely don't want to litter around:

sphinx delete testuser testhost

You might wonder, why you don't need a password for deletion - that actually depends on the rwd_keys setting, read about that in the man page. However deletion does require that the masterkey in ~/.sphinx/ is actually correct.

Now if you do again (being lazy and not using getpwd):

echo -n "password" | sphinx get testuser testhost

You should get an error.

Congrats, you just setup sphinx! Read up in the man pages (https://github.com/stef/pwdsphinx/tree/master/man) more about how to get the most out of sphinx.

Setting up a Firefox addon

First install the sphinx CLI client - see the section above on more info on that.

Then install the addon from the mozilla addons store: https://addons.mozilla.org/en-US/firefox/addon/websphinx/

The WebSphinx addon also requires the installation of a native messaging host - which is terminology and it really means backend.

Websphinx consists of two parts, the frontend which is the addon. And the backend which handles everything.

You can install the addon from the firefox addon store.

The WebSphinx addon requires the installation of a native messaging host - which is terminology and it really means backend.

You will need to install a graphical pinentry,

either sudo apt-get install pinentry-qt
or sudo apt-get install pinentry-gtk2
or sudo apt-get install pinentry-gnome3
or sudo apt-get install pinentry-fltk

(or anything equivalent to apt-get install on your OS)

And set the pinentry variant if it is not invoked with /usr/bin/pinentry in your sphinx config file in the websphinx section

Your sphinx config file can be in a couple of locations:

globally: /etc/sphinx/config
for your user: ~/.sphinxrc
or also:~/.config/sphinx/config
and always in the current directory.

To set the pinentry path, add or modify to have a section like this:

[websphinx]
pinentry=/usr/bin/pinentry-gtk-2

Native Messaging Host Manifest

Copy websphinx.json, depending on your browser to finish the installation:

Linux/BSD
- User only: ~/.mozilla/native-messaging-hosts/websphinx.json
- System-wide: /usr/{lib,lib64,share}/mozilla/native-messaging-hosts/websphinx.json
- MacOS: /Library/Application Support/Mozilla/NativeMessagingHosts/websphinx.json

You need to change %PATH% in websphinx.json so it refers to websphinx.py which came with pwdsphinx.

mkdir -p ~/.mozilla/native-messaging-hosts
curl -Lo ~/.mozilla/native-messaging-hosts/websphinx.json https://github.com/stef/websphinx-firefox/raw/master/websphinx.json

if you followed this guide, websphinx should be installed in /usr/bin and you should replace the %PATH% in ~/.mozilla/native-messaging-hosts/websphinx.json to /usr/bin so the file looks like this:

{
  "name": "websphinx",
  "description": "Host for communicating with pwdphinx",
  "path": "/usr/bin/websphinx",
  "type": "stdio",
  "allowed_extensions": [
    "sphinx@ctrlc.hu"
  ]
}

Final step

Restart your browser in which the addon is installed and enjoy.

Setting up a Chrome derivate addon (including ms edge, opera, brave, etc)

Websphinx consists of two parts, the frontend which is the addon. And the backend which handles everything.

First install the sphinx CLI client, see the above for more information on that.

WebSphinx is not in the Chrome Web Store, if you want to install the addon follow these steps (this applies to all Operating Systems):

Create a directory on your filesystem containing the files in the websphinx directory.
Start your browser if it is not running,
open chrome://extension in your browser,
enable Developer Mode,
Load Unpacked Extension and provide the directory created in step 1.,
If all went well, you should get a yellowyish sphinx button.

The WebSphinx addon requires the installation of a native messaging host - which is terminology and it really means backend.

You will need to install a graphical pinentry,

either sudo apt-get install pinentry-qt
or sudo apt-get install pinentry-gtk2
or sudo apt-get install pinentry-gnome3
or sudo apt-get install pinentry-fltk

(or anything equivalent to apt-get install on your OS)

And set the pinentry variant if it is not invoked with /usr/bin/pinentry in your sphinx config file in the websphinx section

Your sphinx config file can be in a couple of locations:

globally: /etc/sphinx/config
for your user: ~/.sphinxrc
or also:~/.config/sphinx/config
and always in the current directory.

To set the pinentry path, add or modify to have a section like this:

[websphinx]
pinentry=/usr/bin/pinentry-gtk-2

Native Messaging Host Manifest

Copy websphinx.json, depending on your browser to finish the installation:

Linux/BSD
- Per-user: ~/.config/{google-chrome,chromium}/NativeMessagingHosts/websphinx.json
- System: /etc/{opt/chrome,chromium}/native-messaging-hosts/websphinx.json
MacOS
- Per-user: ~/Library/Application Support/{Google/Chrome,Chromium}/NativeMessagingHosts/websphinx.json
- System-wide: /Library/{Google/Chrome,Chromium}/NativeMessagingHosts/websphinx.json

You need to change %PATH% in websphinx.json so it refers to websphinx.py which came with pwdsphinx.

Assuming you have chromium follow these steps (otherwise replace chromium with google-chrome, or even possibly opera?)

mkdir -p ~/.config/chromium/NativeMessagingHosts
curl -Lo ~/.config/chromium/NativeMessagingHosts/websphinx.json https://github.com/stef/websphinx-chrom/raw/master/websphinx.json

if you followed this guide, websphinx should be installed in /usr/bin and you should replace the %PATH% in ~/.config/chromium/NativeMessagingHosts/websphinx.json to /usr/bin so the file looks like this:

{
  "name": "websphinx",
  "description": "Host for communicating with Sphinx",
  "path": "/usr/bin/websphinx",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://ojbhlhidchjkmjmpeonendekpoacahni/"
  ]
}

Final step

Restart your browser in which the addon is installed and enjoy.

Hosting your own oracle

Great! You should host your own oracle, and make it available also to all your friends and family! The recommended way to do so is to dedicate cheap and small single-board-computer to this task, which does nothing else. An old Raspberry Pi 1 is enough, the oracle does not use much resources.

Installation

You need to install sphinx, either by using pip:

pip install pwdsphinx

or on Debian derivates:

apt install pwdsphinx

Getting a TLS certificate using nginx and letsencrypt

First you need to generate an account and a domain key:

openssl genrsa 4096 > account.key
openssl genrsa 4096 > domain.key

Then you neeed to create a certificate signing request (CSR) for your domains. For a single domain you can use:

openssl req -new -sha256 -key domain.key -subj "/CN=yoursite.com" > domain.csr

If you have multiple domains (like www.yoursite.com and yoursite.com) and a new openssl, then:

openssl req -new -sha256 -key domain.key -subj "/" -addext "subjectAltName = DNS:yoursite.com, DNS:www.yoursite.com" > domain.csr

Or if you have an old openssl < 1.1.1:

openssl req -new -sha256 -key domain.key -subj "/" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS:yoursite.com,DNS:www.yoursite.com")) > domain.csr

Now you need nginx, and a challenges director it can serve:

apt install nginx
mkdir -p /var/www/challenges/

The configuration of nginx is the following:

# Example for nginx
server {
    listen 80;
    server_name yoursite.com www.yoursite.com;

    location /.well-known/acme-challenge/ {
        alias /var/www/challenges/;
        try_files $uri =404;
    }

    ...the rest of your config
}

And finally use acme-tiny to get our signed certificate

apt install acme-tiny
acme_tiny --account-key ./account.key --csr ./domain.csr --acme-dir /var/www/challenges/ > ./signed_chain.crt

Tada! you should have a file called signed_chain.crt which contains your cert, and the file domain.key which you generated at the beginning is your secret key for the oracle.

Configuration

When you have a TLS cert and key, you can start configuring the oracle. A full configuration file for the oracle looks as follows:

[server]
# the IP address the server is listening on
#address="127.0.0.1"

# the port on which the server is listening, use 443 if available, so that
# the oracle can be accessed from behind tight firewalls
#port=2355

# ssl key - no default must be specified
ssl_key="server.der"

# ssl cert - no default must be specified
ssl_cert="cert.pem"

# tcp connection timeouts, increase in case you have bad networks, with the
# caveat that this might lead to easier resource exhaustion - blocking all
# workers.
#timeout=3

# how many worker processes can run in parallel
# max_kids=5

# the root directory where all data is stored
#datadir= "/var/lib/sphinx"

# whether to produce some output on the console
#verbose=false

# decay ratelimit after rl_decay seconds
#rl_decay= 1800

# increase hardness after rl_threshold attempts if not decaying
#rl_threshold= 1

# when checking freshness of puzzle solution, allow this extra
# gracetime in addition to the hardness max solution time
#rl_gracetime=10

You need to set the address to whatever IP address you want the oracle to be listening on. And you should set the port if possible to 443, that will enable you to have always access to the oracle when you are on the go, since other ports might very well be firewalled, but port 443 is very-very rarely. You also need to set the ssl_key to the file domain.key , and the ssl_cert to the file signed_chain.crt both from the previous section "getting a tls cert..."

The rest of the config settings you don't have to touch. When done, simply run oracle, this will start the server in the foreground.

Use whatever your distro provides to daemonize and log the output of servers to have the server automatically started at reboot.

Congratulations! Now invite your friends (and enemies!) to use your instance :) You might also want to setup the whole thing as a tor hidden service, so you can protect the privacy of your users even better, but how to do so is left as an exercise to the dear reader.

[1] The only thing they can learn is the frequency how often you interact with a certain password, and which passwords belong to the same user and host, for example if you have an admin and a non-privileged account at the same host the oracle user could find out that these two are related. Also whoever is hosting the oracle can mount a denial-of-service against you by not responding or corrupting their answers. But your passwords would be safe, nevertheless. Even if their "database" leaks to the internet, or criminals.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GettingStarted.md

GettingStarted.md

Getting started

Installing the sphinx CLI client

Configuring the sphinx CLI client

Setting up a Firefox addon

Native Messaging Host Manifest

Final step

Setting up a Chrome derivate addon (including ms edge, opera, brave, etc)

Native Messaging Host Manifest

Final step

Hosting your own oracle

Installation

Getting a TLS certificate using nginx and letsencrypt

Configuration

Files

GettingStarted.md

Latest commit

History

GettingStarted.md

File metadata and controls

Getting started

Installing the sphinx CLI client

Configuring the sphinx CLI client

Setting up a Firefox addon

Native Messaging Host Manifest

Final step

Setting up a Chrome derivate addon (including ms edge, opera, brave, etc)

Native Messaging Host Manifest

Final step

Hosting your own oracle

Installation

Getting a TLS certificate using nginx and letsencrypt

Configuration