An unofficial, mostly Bitwarden-compatible API server written in Ruby (Sinatra and ActiveRecord)
1**This project is no longer being maintained. Please see
2[this issue](https://github.com/jcs/rubywarden/issues/122)
3for further information.**
4
5This project is not associated with the
6[Bitwarden](https://bitwarden.com/)
7project nor 8bit Solutions LLC.
8Do not contact Bitwarden for support with using this backend server
9(or at the very least, make it abundantly clear that you are using a 3rd party backend server).
10
11## Rubywarden
12
13A small, self-contained API server written in Ruby and Sinatra to provide a
14private backend for the open-source
15[Bitwarden apps](https://github.com/bitwarden).
16
17### Data
18
19All data is stored in a local SQLite database.
20This means you can easily run the server locally and have your data never
21leave your device, or run it on your own web server via Rack and some front-end
22HTTP server with TLS to support syncing across multiple devices.
23Backing up your data is as easy as copying the `db/production/production.sqlite3`
24file somewhere.
25
26All user data in the SQLite database is stored in an encrypted format the
27[same way](https://help.bitwarden.com/crypto.html)
28it is in the official Bitwarden backend, where the master password is never
29known by the server.
30For details on the format, consult the
31[documentation](https://github.com/jcs/rubywarden/blob/master/API.md).
32
33### API Documentation
34
35This project also contains independent
36[documentation for Bitwarden's API](https://github.com/jcs/rubywarden/blob/master/API.md)
37written as I work on this server, since there doesn't seem to be any
38documentation available other than the
39[.NET Bitwarden code](https://github.com/bitwarden/core)
40itself.
41
42### Deployment
43
44Automated deployment of Rubywarden is possible with 3rd party support:
45
46- [Ansible playbook](https://github.com/qbit/openbsd-rubywarden) for OpenBSD
47
48### Manual Setup
49
50Run `bundle install` at least once.
51
52In order to create the initial environment, it is recommended to create a new,
53unprivileged user on your system dedicated to running Rubywarden such as
54with `useradd`.
55This documentation will assume a user has been created named `_rubywarden`.
56
57In order to create the initial database and the required tables run:
58
59 mkdir db/production
60 sudo chown _rubywarden db/production
61 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec rake db:migrate
62
63To run via Rack on port 4567, as user `_rubywarden`:
64
65 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec rackup -p 4567 config.ru
66
67You'll probably want to run it once with signups enabled, to allow yourself
68to create an account:
69
70 sudo -u _rubywarden env RUBYWARDEN_ENV=production RUBYWARDEN_ALLOW_SIGNUPS=1 bundle exec rackup -p 4567 config.ru
71
72Once the server is running, the Bitwarden apps (such as the Firefox extension)
73can be configured to use your own Bitwarden server before login.
74For a local Rack instance, you can point it at `http://127.0.0.1:4567/`.
75
76To run the test suite:
77
78 bundle exec rake test
79
80### Changing URL Paths
81
82By default, Rubywarden is setup to use paths on a single hostname that the
83Bitwarden clients will default to so you do not have to specify separate API,
84Identity, and Icon URLs.
85
86If you are not deploying Rubywarden on its own hostname or want to alter the
87paths for any reason, you can override them with environment variables:
88
89- `RUBYWARDEN_ATTACHMENTS_URL` for the attachments URL - defaults to `/attachments`
90- `RUBYWARDEN_BASE_URL` for the API base - defaults to `/api`
91- `RUBYWARDEN_IDENTITY_BASE_URL` for the identity API base - defaults to
92 `/identity`
93- `RUBYWARDEN_ICONS_URL` for the icon URL - defaults to `/icons`
94
95For example, if you had a website `example.com` and wanted to host Rubywarden
96on a subdirectory called `/notbitwarden`, you would set the environment
97variables in your startup script:
98
99 sudo -u _rubywarden env RUBYWARDEN_ENV=production RUBYWARDEN_BASE_URL=/notbitwarden/api RUBYWARDEN_IDENTITY_BASE_URL=/notbitwarden/identity RUBYWARDEN_ICONS_URL=/notbitwarden/icons RUBYWARDEN_ATTACHMENTS_URL=/notbitwarden/attachments bundle exec rackup -p 4567 config.ru
100
101Then you can configure the Bitwarden clients with a single server URL of
102`https://example.com/notbitwarden`.
103
104### Updating
105
106To update your instance of Rubywarden, fetch the latest code:
107
108 cd /path/to/your/rubywarden
109 git pull --ff-only
110
111Run any database migrations:
112
113 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec rake db:migrate
114
115Restart your Rubywarden instance (via Rack, Unicorn, or however you have
116deployed it).
117
118### Changing Master Password
119
120Changing a user's master password must be done from the command line (as it
121requires interacting with the plaintext password, which the web API will never
122do).
123
124 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/change_master_password.rb -u you@example.com
125
126### 2-Factor Authentication
127
128The Bitwarden browser extensions and mobile apps support accounts that require
1292FA, by prompting you for the current code after successfully logging in.
130To activate Time-based One-Time Passwords (TOTP) on your account after you've
131signed up in the previous steps, run the `tools/activate_totp.rb` program on
132the server:
133
134 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/activate_totp.rb -u you@example.com
135
136You'll be shown a `data:` URL that has a PNG-encoded QR code, which you must
137copy and paste into a browser, then scan with your mobile TOTP authenticator
138apps (assuming it supports scanning from the camera).
139Once scanned, the activation program will ask you to enter the current TOTP
140being shown in the app for verification, and then save the TOTP secret to your
141account in the SQLite database.
142Your `security_stamp` will be reset, forcing a new login on any devices that
143are logged into your account.
144Those devices will now prompt for a TOTP code upon future logins.
145
146### Migrating From Other Password Managers
147
148This project inclues utilities that will import data exported from other
149password managers, convert it to its own data format, and then import it.
150
151#### 1Password
152
153Export everything from 1Password in its "1Password Interchange Format".
154It should create a directory with a `data.1pif` file (which is unencrypted, so
155be careful with it).
156Once you have created your initial user account through Rubywarden, run the
157conversion tool with your account e-mail address:
158
159 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/1password_import.rb -f /path/to/data.1pif -u you@example.com
160
161It will prompt you for the master password you already created, and then
162convert and import as many items as it can.
163
164This tool operates on the SQLite database directly (not through its REST API)
165so you can run it offline.
166
167#### Bitwarden (Official Apps)
168
169Export your bitwarden vault via the web interface or the browser plugin, which
170should prompt you to save a `bitwarden_export_<datestamp>.csv` file. Due to
171limitations of the exporter, neither cards nor identities will be exported,
172and any custom fields will lose their type (text, hidden, or boolean) and be
173simply exported as text.
174
175Once you have created your initial user account through Rubywarden, run the
176conversion tool with your account e-mail address:
177
178 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/bitwarden_import.rb -f /path/to/data.csv -u you@example.com
179
180It will prompt you for the master password you already created, and then
181convert and import as many items as it can.
182
183This tool operates on the SQLite database directly (not through its REST API)
184so you can run it offline.
185
186#### Keepass
187
188In order to use the Keepass converter, you will need to install the necessary
189dependency, using `bundle install --with keepass`.
190
191There is no need to export your Keepass-database - you can use it as is.
192
193Once you have created your initial user account through Rubywarden, run the
194conversion tool with your account e-mail address:
195
196 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/keepass_import.rb -f /path/to/data.kdbx -u you@example.com
197
198If your Keepass-database is secured using a keyfile, you can pass it using the `-k` parameter:
199
200 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/keepass_import.rb -f /path/to/data.kdbx -k /path/to/keyfile.key -u you@example.com
201
202It will prompt you for the master password you already created, and then
203convert and import as many items as it can.
204
205This tool operates on the SQLite database directly (not through its REST API)
206so you can run it offline.
207
208#### Lastpass
209
210Export everything from LastPass by going to your vault, "More Options",
211"Advanced" and then "Export".
212It will then export your details in a new browser window in CSV format, copy
213and paste this data into a file accessible from your Rubywarden installation.
214Unfortunately due to limitations in LastPass export the "extra fields" and
215"attachments" data in the LastPass vault will not be converted.
216
217Once you have created your initial user account through Rubywarden, run the
218conversion tool with your account e-mail address:
219
220 sudo -u _rubywarden env RUBYWARDEN_ENV=production bundle exec ruby tools/lastpass_import.rb -f /path/to/data.csv -u you@example.com
221
222It will prompt you for the master password you already created, and then
223convert and import as many items as it can.
224
225This tool operates on the SQLite database directly (not through its REST API)
226so you can run it offline.
227
228### Rubywarden License
229
230Copyright (c) 2017-2019 joshua stein `<jcs@jcs.org>`
231
232Permission to use, copy, modify, and distribute this software for any
233purpose with or without fee is hereby granted, provided that the above
234copyright notice and this permission notice appear in all copies.
235
236THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
237WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
238MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
239ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
240WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
241ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
242OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.