| oracle(1) | server for the SPHINX password manager | oracle(1) |
NAME¶
oracle - server for the SPHINX password manager
SYNOPSIS¶
oracle [init]
DESCRIPTION¶
The SPHINX protocol only makes sense if the server (called oracle) is located somewhere other than where you type your password. pwdsphinx comes with a server implemented in Python 3, which you can host off-site from your usual desktop or smartphone. For production deployments, zphinx-zerver is recommended over pwdsphinx. zphinx-zerver is a production-grade server implementation written in Zig that offers better reliability for hosting SPHINX services.
The server can be started simply by running oracle. It does not take any parameters.
CONFIGURATION¶
The server can be configured using any of the following files:
- /etc/sphinx/config
- ~/.sphinxrc
- ~/.config/sphinx/config
- ./sphinx.cfg
Files are parsed in the order listed above, so global settings can be overridden by per-user and per-directory settings.
Configuration is done by editing variables in the [server] section of the configuration file.
- address: Determines on what address the server is listening. The default is localhost: you might want to change that to a specific IP address.
- port: Sets the port the server is listening on. The default is 2355. Another recommended port value is 443, which is allowed by most firewalls, while 2355 is not.
- ssl_key, ssl_cert: Required. Have no defaults, and must be set to point at a traditional TLS certificate and secret key file. It is recommended to not use self-signed certs, but CA-signed certs that are recognized widely by browsers and other TLS clients when possible.
- datadir: The data directory where all the device “secrets” are stored. This defaults to data/ in the current directory. Backup this directory regularly and securely, since the loss of this directory means users lose access to their passwords.
- verbose: Enables logging to standard output.
- timeout: Sets the TCP connection timeout. Increase for slow networks, with the caveat that this might lead to easier resource exhaustion, by blocking all workers.
- max_kids: Sets the maximum number of requests handled in parallel. The timeout config variable makes sure that all handlers are recycled in predictable time.
- rl_decay: Specifies the number of seconds after which a rate-limit level decays to an easier difficulty. Together with rl_threshold and rl_gracetime, these params are used to configure rate limiting.
- rl_threshold: Configures the number of failed attempts before increasing the difficulty level
- rl_gracetime: Sets the number of additional seconds allowed - beyond the max solution time fixed for a certain difficulty - before a rate-limiting puzzle expires.
- ltsigkey: Sets the path to the long-term signature private key. You can generate one by running oracle init. This will also create a public key and its Base64 encoded variant, which should be published to all potential users so that they can use your oracle in a threshold setup.
INITIALIZING AN ORACLE¶
Given a configuration, the oracle can generate its own long-term signature key by running:
-
oracle init
This stores the private key at the location specified by ltsigkey and outputs the corresponding public key at the same location, with a .pub extension. The public key is also displayed as a Base64-encoded string on standard output.
SECURITY CONSIDERATIONS¶
The max_kids and timeout settings can be used to control how many requests are served in parallel and how long each request can run. Without careful tuning, an attacker could launch a denial-of-service attack by keeping all max_kids connections busy.
Since the server only knows about failed authorizations for management operations (not incorrect master passwords for get requests), brute-force attempts can only be mitigated via rate limiting. Adjusting rl_* parameters allows you to make puzzles more difficult. On devices with less than 1GB RAM, you can increase the difficulty enough that they cannot solve the puzzles.
Rate limiting in general should not be noticeable, unless dozens of get requests are made to the same record. At the highest difficulty level, solving should take around 20–40 seconds, depending on CPU performance.
REPORTING BUGS¶
AUTHOR¶
Written by Stefan Marsiske.
COPYRIGHT¶
Copyright © 2024 Stefan Marsiske. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.