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