Ubuntu Manpage: sphinx - command-line client for the SPHINX password manager

NAME

       sphinx - command-line client for the SPHINX password manager

SYNOPSIS

       sphinx init

       echo “password” | sphinx create <user> <site> [<u><l><d><s>] [<size>] [<symbols>] [<target password>]

       echo “password” | sphinx get <user> <site>

       echo  -e  “oldpassword”  | sphinx change <user> <site> [<u><l><d><s>] [<size>] [<symbols>] [<target pass‐
       word>]

       [ echo “password” | ] sphinx commit <user> <site>

       [ echo “password” | ] sphinx undo <user> <site>

       [ echo “password” | ] sphinx delete <user> <site>

       sphinx list <site>

       sphinx qr [<svg>] [<key>]

DESCRIPTION

SPHINX – password Store that Perfectly Hides from Itself (No Xaggeration) – is an information-theoreti‐
cally secure cryptographic password storage protocol with strong security guarantees, as described in the
2015 paper “Device-Enhanced Password Protocols with Optimal Online-Offline Protection” by Jarecki, Kraw‐
czyk, Shirvanian, and Saxena (https://ia.cr/2015/1099).

sphinx is the command-line client for the SPHINX protocol, it provides access to all operations over the
life-cycle of a password: init, create, get, change, undo, commit, delete. Additionally it provides also
operations that make this more user-friendly: listing of users associated with a host and export of the
configuration using a qr code.

In general if any operation requires a master(input) password, it is expected on standard input, and any
resulting account (output) password is printed to standard output.

INITIALIZING A CLIENT
sphinx init

This creates a new master key for the client, which is used to address records on the sphinx server and
authorize management operations on those records.

You should back up and encrypt this master key.

If you want to use sphinx on a different device you want to copy this master key also there. For copying
this (and other settigns) to the android client androsphinx we have the qr operation, see below.

CREATE PASSWORD
Creating a new password for a site is easy, pass your “master” password on standard input to the client,
and provide parameters like in this example:

echo -n 'my master password' | sphinx create username example.com ulsd 0 ' !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'

The parameters to the client are

• Your master password on standard input. Since the master password is not used to encrypt anything, you
can actually use different “master” passwords for different user/site combinations.

• create for the operation, then

• username for the username on

• the site example.com then

• the password constraints, see sections PASSWORD RULES and PREDETERMINED PASSWORDS for more info

If the command runs successfully - the resulting new high-entropy password according to the given rules
is printed to the console.

GET PASSWORD
Getting a password from the sphinx oracle works by running the following command:

echo -n 'my master password' | sphinx get username example.com

You supply your master password on standard input, provide the get operation as the first parameter, your
username as the 2nd and the site as the 3rd parameter. The resulting password is returned on standard
output.

CHANGE PASSWORD
You might want to (or are forced to regularly) change your password, this is easy while you can keep your
master password the unchanged (or you can change it too, if you want). The command is this:

echo -en 'my master password\nnew masterpassword' | sphinx change username example.com 'ulsd' 0 ' !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~'

You supply your current master password on standard input, and separated by a new-line you also provide
the new master password. The new master password can be the same as the old, but can also be a new pass‐
word if you want to change also the master password.

You provide the change operation as the first parameter to the client, your username as the 2nd and the
site as the 3rd parameter. You also can provide similar password generation rule parameters that were
also used to create the original password, in case your account has new password rules and you want/have
to accomodate them. For more information see the PASSWORD RULES and PREDETERMINED PASSWORDS sections be‐
low.

Your new new password is returned on standard output.

COMMITTING A CHANGED PASSWORD
After changing the password, you will still get the old password when running the get operation. To
switch to use the new password you have to commit the changes with

echo -n 'my master password' | sphinx commit username example.com

Depending on your rwd_keys configuration setting, you might have to provide your master password on stan‐
dard input to this operation.

If all goes well, there is no output expected.

UNDOING A PASSWORD COMMIT
If you somehow messed up and have to go back to use the old password, you can undo committing your pass‐
word using:

echo -n 'my master password' | sphinx undo username example.com

Depending on your rwd_keys configuration setting, you might have to provide your master password on stan‐
dard input to this operation.

If all goes well, there is no output expected.

DELETING PASSWORDS
In case you want to delete a password, you can do using the following command:

echo -n "my master password" | sphinx delete username example.com

You provide the delete operation as the first parameter to the client, your username as the 2nd and the
site as the 3rd parameter. This command does not provide anything on standard output in case everything
goes well.

Depending on your rwd_keys configuration setting, you might have to provide your master password on stan‐
dard input to this operation.

QR CODE CONFIG
In case you want to use phone with the same sphinx server, you need to export your config to the phone
via a QR code.

sphinx qr

Will display a QR code containing only public information - like the server host and port, and whether
you use rwd_keys. This is mostly useful if you want to share your setup with a friend or family.

If you want to connect your own phone to the setup used with pwdsphinx, you also need to export your
client secret in the QR code:

sphinx qr key

This contains your client secret, and you should keep this QR code confidential. Make sure there is no
cameras making copies of this while this QR code is displayed on your screen.

If for whatever reason you want to display the QR code as an SVG, just append the svg keyword to the end
of the sphinx qr command.

PASSWORD RULES
When creating or changing passwords you can specify rules limiting the size and characters allowed in the
output password. This is specified as follows:

The letters ulsd stand in order for the following character classes: - u upper-case letters, - l lower-
case letters, - s symbols and - d for digits.

The s is a short-cut to allow all of the symbols, if you are limited by the server which symbols to use,
you can specify the allowed symbols explicitly. Currently these are the symbols supported (note the
leading space char):

!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

Be careful, if you specify these on the command-line you’ll have to escape the quotes you use for enclos‐
ing this list and possibly the backslash char that is also part of this list. In the create username ex‐
ample above the symbols are correctly escaped, in case you need to copy/paste them.

For examples how to use these see the section “CREATE PASSWORD” or “CHANGE PASSWORD”.

DEFAULT RULES
If you do not provide password rules, they will be defaulting to `ulsd' and length as long as possible.

PREDETERMINED OUTPUT PASSWORDS
In case for some reason you cannot use random passwords with your account, or you want to store a “pass‐
word” that you cannot change, like a PIN code for example, or a passphrase shared with your colleagues,
you can specify a maximuxm 38 characte long password, that will be generated by the SPHINX client for
you. In that case the command line looks like this (note the same syntax also works for the change oper‐
ation)

echo -n 'my master password' | sphinx create username example.com "correct_battery-horse#staple"

In this case you cannot specify neither the accepted character classes, nor the size, nor symbols, these
will be deducted from the predetermined password itself.

CONFIGURATION

       The client can be configured by any of the following files:

       • /etc/sphinx/config

       • ~/.sphinxrc

       • ~/.config/sphinx/config

       • ./sphinx.cfg

       Files are parsed in this order, this means global settings can be overridden by per-user and per-directo‐
       ry settings.

       The  client can be configured changing the settings in the [client] section of the config file.  The host
       and port should match what you set in the oracle(1) server.

       The datadir (default: ~/.sphinx) variable holds the location for your client parameters.  Particularly it
       contains a masterkey which is used to derive secrets.  The master key - if not available -  is  generated
       by issuing an init command.  You should back up and encrypt this master key.

       rwd_keys toggles if the master password is required for authentication of management operations.

       The oracle is oblivious to this setting, this is purely a client-side toggle, in theory it is possible to
       have different settings for different “records” on the oracle.

       validate_password Stores a check digit of 5 bits in on the oracle, this helps to notice most typos of the
       master password, while decreasing security slightly.

SECURITY CONSIDERATIONS

You should back up and encrypt your master key.

The rwd_keys configuration setting, if set to False protects against offline master password bruteforce
attacks - which is also a security guarantee of the original SPHINX protocol.

The drawback is that for known (host,username) pairs the according record can be changed/deleted by an
attacker if the clients masterkey is available to them. However neither the master nor the account pass‐
word can leak this way. This is merely a denial-of-service attack vector. If rwd_keys is set to True,
then this eliminates the denial-of-service vector, but also negates the offline-bruteforce guarantee of
the SPHINX protocol. This setting is really a compromise between availability of account passwords ver‐
sus the confidentiality of your master password.

The validate_password configuration setting if enabled, decreases security slightly (by 5 bits). In gen‐
eral it should be safe to enable.

In this man page we are using echo only for demonstration, you should use something like this instead (or
even directly getpwd(1) from the contrib directory if you are not interested in customizing):

echo GETPIN | pinentry | grep '^D' | cut -c3- | sphinx create username example.com ulsd 0

Using pinentry you can go fancy and do double password input, and even have something checking password
quality for you, check it out, it’s quite versatile.

REPORTING BUGS

       https://github.com/stef/pwdsphinx/issues/

AUTHOR

       Written by Stefan Marsiske.

COPYRIGHT

       Copyright  ©  2023  Stefan Marsiske.  License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licens‐
       es/gpl.html>.  This is free software: you are free to change and redistribute it.  There is NO  WARRANTY,
       to the extent permitted by law.

NAME

SYNOPSIS

DESCRIPTION

CONFIGURATION

SECURITY CONSIDERATIONS

REPORTING BUGS

AUTHOR

COPYRIGHT

SEE ALSO