oracle(1)

📦
version 2.0.4 · 3 versions
, in nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 oracle(1) — server for the SPHINX password manager 💖

okay bestie, sit down, we're learning about oracle from the server for the SPHINX password manager manual, page oracle(1). it's giving ✨ very important ✨, no cap. 🫶

🌸 NAME 🌸

oracle — the server for the SPHINX password manager. yes girl, the server. main character energy fr. 👑

✨ SYNOPSIS ✨

oracle [init]

🦋 DESCRIPTION 🦋

okay so the whole point of the SPHINX protocol is that the server (we call it the oracle 💅) has to be somewhere other than where you actually type your password. like, literally the entire vibe depends on it. if it's sitting on the same machine where you're typing your lil secrets, it's not doing its job, bestie.

pwdsphinx ships with a server written in Python 3, and you can host it off-site from your usual desktop or your smartphone. super convenient, love that for you. 🍓

but heads up: for production deployments, zphinx-zerver is recommended over pwdsphinx. zphinx-zerver is a production-grade server implementation written in Zig, and it offers better reliability for hosting SPHINX services. so like, for the real deal, that's the one. 🔥

and getting the server going? literally the easiest thing ever:

oracle

that's it. it does not take any parameters. periodt. 🎀

⭐ CONFIGURATION ⭐

the server can be configured using any of these files, and bestie you have options:

  • /etc/sphinx/config
  • ~/.sphinxrc
  • ~/.config/sphinx/config
  • ./sphinx.cfg

these get parsed in the order listed above, which is so cute because it means global settings can be overridden by per-user settings, and those can be overridden by per-directory settings. layering, we love to see it. 🌈

the actual configuring happens by editing variables in the [server] section of the config file. let's go through them one by one, i got you:

  • address — determines on what address the server is listening. default is localhost: you might want to change that to a specific IP address. like, actually change it. 🙈
  • port — sets the port the server is listening on. default is 2355. another recommended port value is 443, which is allowed by most firewalls, while 2355 is not. so if your firewall is being a hater, you know what to do. 💀
  • ssl_key, ssl_cert — Required. these have no defaults, and they must be set to point at a traditional TLS certificate and secret key file. it's recommended to not use self-signed certs, but CA-signed certs that are recognized widely by browsers and other TLS clients when possible. trust issues with certs are so real. 😭
  • datadir — the data directory where all the device “secrets” are stored. defaults to data/ in the current directory. backup this directory regularly and securely, because the loss of this directory means users lose access to their passwords. like... forever. not a vibe. please back it up. 🫶
  • verbose — enables logging to standard output. for when you want to see everything. nosey queen behavior, valid. 👀
  • 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. so like, yes queen but be careful. ⚠️
  • 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. teamwork, honestly. ✨
  • 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. trio, iconic. 💅
  • rl_threshold — configures the number of failed attempts before increasing the difficulty level. miss thing does not play. 💅
  • 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. share the goods, bestie. 🎁

🧚 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. and the public key is also displayed as a Base64-encoded string on standard output. so you get it in two places, she's generous like that. 💖

👑 SECURITY CONSIDERATIONS 👑

listen, this part is important so put your phone down.

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. like, that's a real thing that could happen. 😭

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. so you adjust the rl_* parameters to make puzzles more difficult. and on devices with less than 1GB RAM, you can increase the difficulty enough that they cannot solve the puzzles. bye felicia. 💅

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.

twenty to forty seconds?? that's a whole tiktok. but it's for your safety bestie. 🧚

🐛 REPORTING BUGS 🐛

found a bug? not the vibe. go tell on them here:

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

💜 AUTHOR 💜

written by Stefan Marsiske. 🫡

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. no cap, they literally wrote the NO WARRANTY in all caps so you know they mean it. 💀

🦋 SEE ALSO 🦋

okay that's the whole page bestie!! it's from server for the SPHINX password manager, matching the oracle(1) manual, and this whole rundown was served to you by the oracle(1) page, dated 2024, source server for the SPHINX password manager. go forth and host your oracle somewhere that is NOT where you type your password. slay, stay safe, back up your datadir. 💖✨🎀🦋🌸💅🫶👑🌈⭐🍓🧚💜

📦 where this page comes from