commit cabbfe1221c3b704dbc43d53829719859e253dc2
parent dc7a41e4729fe3ff60e77fb5b0a00b0d574ab3a2
Author: Zack Newman <zack@philomathiclife.com>
Date: Tue, 26 Dec 2023 12:37:27 -0700
add readme
Diffstat:
| A | README.md | | | 68 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 68 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,68 @@
+# vw_small
+
+`vw_small` is a fork of [Vaultwarden](https://github.com/dani-garcia/vaultwarden) that focuses on security and OpenBSD-stable compatibility.
+
+## Why use this crate instead of Vaultwarden?
+
+Stricter validation and stronger adherence to RFCs and standards are performed in this crate in addition to safe arithmetic (i.e., overflow/underflow and
+truncation are coded against). Additionally, this crate does not cater to parties that are not familiar with the best practices of self-hosting. A password manager
+is something you want to do correctly; so if self-hosting is something you are new at, this crate is _not_ for you. Problems dealing with firewall rules, reverse proxy
+settings, X.509 certificates, backups, file permissions, etc. are unrelated to the job of a password manager.
+
+This crate has first-class support for OpenBSD-stable; and when compiled/installed with the `priv_sep` `feature`, it uses [`pledge(2)`](https://man.openbsd.org/amd64/pledge.2) and
+[`unveil(2)`](https://man.openbsd.org/amd64/unveil.2) to lock down the daemon.
+
+This crate does not support all of the features Vaultwarden supports. To some fewer features _is_ a feature. In particular, this crate assumes a small-scale environment; thus
+only SQLite is supported for the database, there is no HTTP(S) client, no SMTP client, no DNS resolver, no support for groups, no admin panel, no attachment support, no send support,
+no push notifications, and only WebAuthn and TOTP are supported for 2FA.
+
+This crate makes a better attempt and performing state-changing operations in an atomic fashion (e.g., instead of mutating two database tables in separate transactions allowing
+for the possibility the first change occurs without the second, both changes are done as a single transaction).
+
+## Config file
+
+The TOML config file must be located in the running directory and must be named `config.toml`. The
+format of this file must conform to the following:
+
+```bash
+database_max_conns=<1-255>
+database_timeout=<0-65535>
+db_connection_retries=<1-255>
+domain=<FQDN>
+ip=<IPv6_or_IPv4_address>
+password_iterations=<100000-4294967295>
+port=<0-65535>
+web_vault_enabled=<true/false>
+workers=<1-255>
+[tls]
+cert=<absolute_path_to_complete_X509_certificate>
+ciphers=<subset_of_ciphers_allowed_by_Rocket>
+key=<absolute_path_to_X509_private_key>
+prefer_server_cipher_order=<true/false>
+```
+
+The only required keys are `domain`, `ip`, `port`, `tls.cert`, and `tls.key`. For the remaining keys, the following are the values used when omitted:
+
+```bash
+database_max_conns=10
+database_timeout=30
+db_connection_retries=15
+password_iterations=600000
+web_vault_enabled=true
+workers=<number_of_CPU_cores>
+[tls]
+ciphers=["TLS_CHACHA20_POLY1305_SHA256","TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256","TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256","TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256","TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256","TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384","TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"]
+prefer_server_cipher_order=false
+```
+
+When `database_timeout` is `0`, there is no timeout; otherwise the value represents the maximum _seconds_ allowed for a database connection to be made.
+
+### Status
+
+This package will be actively maintained to stay in-sync with Vaultwarden and OpenBSD-stable.
+
+The crate is only tested on the `x86_64-unknown-linux-gnu` and `x86_64-unknown-openbsd` targets, but
+it should work on any [Tier 1 with Host Tools](https://doc.rust-lang.org/beta/rustc/platform-support.html)
+target.
+
+If/when a complete re-write occurs, a new crate will be maintained that has no relation to Vaultwarden.
