SPHINX password storage – OPAQUE-Store Integration

1. OPAQUE-Store Integration

OPAQUE-Store is a simple protocol that allows anyone to store encrypted blobs of information online, with only a password needed to retrieve the information. Like the name suggests, it uses the OPAQUE protocol to securely store and retrieve files.

OPAQUE-Store extends SPHINX's capabilities by adding secure file storage functionality. While SPHINX excels at generating strong, unique passwords, OPAQUE-Store allows you to encrypt and store arbitrary files using those SPHINX-generated passwords. This combination provides both password management and secure file storage.

1.1. Prerequisites and Setup

To integrate SPHINX with OPAQUE-Store, you need the following:

OPAQUE-Store installed and configured (see the GitHub repository)
Proper configuration file setup (see opaque-stored.cfg(5) manual page)
At least one OPAQUE-Store server running and accessible

For detailed setup instructions, visit the OPAQUE-Store documentation for server setup and client configuration.

1.2. How SPHINX Strengthens OPAQUE-Store

The integration works by using SPHINX as a password strengthening layer before OPAQUE-Store operations. When you perform any OPAQUE-Store operation, SPHINX first executes a get operation using your input password. The resulting strong, cryptographically-derived password becomes the input for the OPAQUE protocol.

This approach provides several security benefits. Your actual passwords become computationally impossible to brute-force offline, as they are derived through SPHINX's cryptographic operations. However, online brute-force attacks are still possible through the SPHINX service itself.

OPAQUE-Store adds an additional layer of protection by detecting incorrect passwords and locking records after a configurable number of failed attempts. This does not apply to the operator of an OPAQUE server, who can circumvent the locking of records.

1.3. Security Considerations

⚠️ Warning: Do not allow one entity control enough of your SPHINX and OPAQUE-Store servers

Every OPAQUE-Store operation needs a password on standard input. This password is run through SPHINX, and the output password is used in the OPAQUE protocol as the input password. If one party operates both services, they can potentially perform offline brute-force attacks against your master password by combining data from both systems.

For single-server deployments, ensure your SPHINX and OPAQUE-Store servers are operated by different, independent entities. For threshold deployments, verify that no single party controls enough oracles/servers to meet the threshold requirement on both systems.

1.4. Available Operations

Once properly configured, SPHINX provides these additional commands for OPAQUE-Store integration:

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>

These commands are explained in detail below.

1.5. OPAQUE-Store CLI Parameters

KeyId

Every OPAQUE-Store operation requires a keyid parameter that identifies your stored record in OPAQUE-Store. The client does not use this keyid directly. Instead, it combines your keyid with the configuration value id_salt (defined in the OPAQUE-Store configuration file) and the OPAQUE-Store server name, then hashes this combination to create the actual record identifier sent to the server.

This design has important implications for backup and recovery. If you lose or change your id_salt configuration value or modify the server name in your configuration, all your existing record identifiers will become inaccessible. Therefore, it is essential to make a backup of your configuration file containing these values.

Note: The id_salt value doesn't have to be secret, though doing so provides an additional layer of security through obscurity.
Forced Operations

When using SPHINX in a threshold configuration, certain operations (replace, edit, changepwd, and erase) require all configured servers to participate successfully. This is to avoid situations where the records on temporarily unavailable servers remain unchanged and later possibly lead to corruption. If you are sure that server unavailability won't cause issues, you can use the force parameter. This reduces the number of servers successfully participating to the minimum value of your `threshold` configuration setting.

1.6. OPAQUE-Store File Storage Operations

Store an Encrypted Blob
```
getpwd | sphinx store <keyid> file-to-store
```
This operation encrypts and uploads your specified file, file-to-store, to the OPAQUE-Store server. The file is encrypted using a key derived from SPHINX.

Note: This command also generates and displays a recovery token, which you should save securely. Recovery tokens allow you to regain access if your record becomes locked due to too many failed authentication attempts.
Retrieve an Encrypted Blob
```
getpwd | sphinx read <keyid>
```
This operation retrieves and decrypts your previously stored file, outputting the contents to standard output.
Overwrite an Existing Blob
```
getpwd | sphinx replace [force] <keyid> file-to-store
```
This operation overwrites an existing stored file with a new encrypted file, file-to-store. This only works if a file is already stored under the specified keyid.

In threshold configurations, all servers must participate unless you specify the force parameter, which allows the operation to proceed with only threshold-minimum participation.
Edit a Blob
```
getpwd | sphinx edit [force] <keyid>
```
This operation fetches the file stored at keyid, opens it in your configured editor (specified by the EDITOR environment variable), and automatically stores the changes and saved file back on the same keyid, thereby overwriting the original.
Change your password on blob
```
getpwd | sphinx changepwd [force] <keyid>
```
The changepwd operation does a full change of passwords and keys. Even if you don't change your own password that you provide to getpwd, SPHINX changes its own key. This changes the output password which will be used for the password in OPAQUE-Store. This results in new and fresh encryption keys and re-encryption of your stored file with the new key.
Delete a Stored Blob
```
getpwd | sphinx erase [force] <keyid>
```
This operation permanently deletes the stored blob referenced by the keyid.
Get a Recovery Token
```
getpwd | sphinx recovery-tokens <keyid>
```
If your record is not locked, this operation generates an additional recovery token. Recovery tokens are essential for regaining access if your record becomes locked due to many failed authentication attempts.
Unlock a Locked Blob
```
getpwd | sphinx unlock <keyid> <recovery-token>
```
When your record becomes locked due to too many failed authentication attempts (you could forget your password or someone is online brute-forcing your record), use this operation with a valid recovery token to restore access. The operation automatically retrieves your stored file upon successful unlock, unless you provide an incorrect password, which may lock the record again.