1
0
mirror of https://github.com/jakeswenson/BitBetter.git synced 2023-10-10 13:36:57 +02:00
BitBetter/README.md

155 lines
7.7 KiB
Markdown
Raw Normal View History

2017-10-19 19:19:24 +02:00
# BitBetter
2017-10-29 20:51:53 +01:00
BitBetter is is a tool to modify Bitwarden's core dll to allow you to generate your own individual and organisation licenses. **You must have an existing installation of Bitwarden for BitBetter to modify.**
2017-10-19 19:19:24 +02:00
Please see the FAQ below for details on why this software was created.
_Beware! BitBetter does janky stuff to rewrite the bitwarden core dll and allow the installation of a self signed certificate. Use at your own risk!_
2018-11-22 06:03:21 +01:00
Credit to https://github.com/h44z/BitBetter and https://github.com/jakeswenson/BitBetter
2018-11-22 07:36:46 +01:00
# Table of Contents
1. [Getting Started](#getting-started)
+ [Dependencies](#dependencies)
+ [Setting up BitBetter](#setting-up-bitbetter)
+ [Building BitBetter](#building-bitbetter)
+ [Updating Bitwarden and BitBetter](#updating-bitwarden-and-bitbetter)
+ [Generating Signed Licenses](#generating-signed-licenses)
2. [FAQ](#faq-questions-you-might-have-)
3. [Footnotes](#footnotes)
# Getting Started
The following instructions are for unix-based systems (Linux, BSD, macOS), it is possible to use a Windows systems assuming you are able to enable and install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
## Dependencies
Aside from docker, which you also need for Bitwarden, BitBetter requires the following:
* Bitwarden (tested with 1.37.0, might work on lower versions)
* openssl (probably already installed on most Linux or WSL systems, any version should work)
## Setting up BitBetter
With your dependencies installed, begin the installation of BitBetter by downloading it through Github or using the git command:
```bash
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
git clone https://github.com/jakeswenson/BitBetter.git
```
## Building BitBetter
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
Now that you've set up your build environment, you can **run the main build script** to generate a modified version of the `bitwarden/api` and `bitwarden/identity` docker images.
From the BitBetter directory, simply run:
2017-10-19 23:50:28 +02:00
```bash
2017-10-29 20:51:53 +01:00
./build.sh
2017-10-19 23:50:28 +02:00
```
This will create a new self-signed certificate in the `.keys` directory if one does not already exist and then create a modified version of the official `bitwarden/api` called `bitbetter/api` and a modified version of the `bitwarden/identity` called `bitbetter/identity`.
You may now simply create the file `/path/to/bwdata/docker/docker-compose.override.yml` with the following contents to utilize the modified images.
2017-10-19 23:50:28 +02:00
```yaml
version: '3'
2017-10-19 23:50:28 +02:00
services:
api:
image: bitbetter/api
identity:
image: bitbetter/identity
```
You'll also want to edit the `/path/to/bwdata/scripts/run.sh` file. In the `function restart()` block, comment out the call to `dockerComposePull`.
2017-10-19 23:50:28 +02:00
> Replace `dockerComposePull`<br>with `#dockerComposePull`
2017-10-29 20:51:53 +01:00
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
You can now start or restart Bitwarden as normal and the modified api will be used. **It is now ready to accept self-issued licenses.**
2017-10-19 23:57:03 +02:00
---
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
### Note: Manually generating Certificate & Key
If you wish to generate your self-signed cert & key manually, you can run the following commands.
```bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.cert -days 36500 -outform DER -passout pass:test
openssl x509 -inform DER -in cert.cert -out cert.pem
openssl pkcs12 -export -out cert.pfx -inkey key.pem -in cert.pem -passin pass:test -passout pass:test
```
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
> Note that the password here must be `test`.<sup>[1](#f1)</sup>
---
## Updating Bitwarden and BitBetter
To update Bitwarden, the provided `update-bitwarden.sh` script can be used. It will rebuild the BitBetter images and automatically update Bitwarden afterwards. Docker pull errors can be ignored for api and identity images.
You can either run this script without providing any parameters in interactive mode (`./update-bitwarden.sh`) or by setting the parameters as follows, to run the script in non-interactive mode:
```bash
./update-bitwarden.sh param1 param2 param3
```
`param1`: The path to the directory containing your bwdata directory
`param2`: If you want the docker-compose file to be overwritten (either `y` or `n`)
`param3`: If you want the bitbetter images to be rebuild (either `y` or `n`)
## Generating Signed Licenses
2017-10-29 20:51:53 +01:00
There is a tool included in the directory `src/licenseGen/` that will generate new individual and organization licenses. These licenses will be accepted by the modified Bitwarden because they will be signed by the certificate you generated in earlier steps.
First, from the `BitBetter/src/licenseGen` directory, **build the license generator**.<sup>[2](#f2)</sup>
2017-10-29 20:51:53 +01:00
```bash
./build.sh
2017-10-29 20:51:53 +01:00
```
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
In order to run the tool and generate a license you'll need to get a **user's GUID** in order to generate an **invididual license** or the server's **install ID** to generate an **Organization license**. These can be retrieved most easily through the Bitwarden [Admin Portal](https://help.bitwarden.com/article/admin-portal/).
2017-10-29 20:51:53 +01:00
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
If you generated your keys in the default `BitBetter/.keys` directory, you can **simply run the license gen in interactive mode** from the `Bitbetter` directory and **follow the prompts to generate your license**.
2017-10-29 20:51:53 +01:00
```bash
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
./src/licenseGen/run.sh interactive
2017-10-29 20:51:53 +01:00
```
2017-10-19 23:57:03 +02:00
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
**The license generator will spit out a JSON-formatted license which can then be used within the Bitwarden web front-end to license your user or org!**
---
### Note: Alternative Ways to Generate License
If you wish to run the license gen from a directory aside from the root `BitBetter` one, you'll have to provide the absolute path to your cert.pfx.
```bash
./src/licenseGen/run.sh /Absolute/Path/To/BitBetter/.keys/cert.pfx interactive
```
Additional, instead of interactive mode, you can also pass the parameters directly to the command as follows.
```bash
./src/licenseGen/run.sh /Absolute/Path/To/BitBetter/.keys/cert.pfx user "Name" "EMail" "User-GUID" "Additional Storage in GB(max 32767)"
./src/licenseGen/run.sh /Absolute/Path/To/BitBetter/.keys/cert.pfx org "Name" "EMail" "Install-ID used to install the server" "Additional Storage in GB(max 32767)" "Org Name"
License Generator Interactive Mode (#23) * Added a Key Generating script To make the keygen process a bit easier I've added a `generate-keys.sh` script that can be found in the `.keys` directory. It will generate the key & cert and bundle them into the required pkcs#12 file. I've updated the readme to include instructions on the script. * Generate bitbetter/identiry container with modified Core.dll Added the generation of a second modified container, bitbetter/identity, which contains the modified dll. Fixes #12. This works on my testing environment but has not gone through extensive testing. I'd recommend a review and cleanup of this commit before it is merged into the develop or master branches. * Updated Docs I've taken the steps written out by @online-stuff and consolidated/organized them into the README. This closes #13. In a future update it might be worth adding a docs/ directory and breaking the readme into several docs that link to one another. * Updated build.sh Build now checks for and creates missing .keys directories. * Added subj to allow for non-interactive use. * Generate keys on build. * Circle-ci needs to gen keys to test build * Generate keys if they don't exist. Don't overwrite if keys already exist. * Generate keys online in the .keys directory * Updated README.md * Added initial interactive options * Functional implementation of licensegen interactive mode. * Bumped Newtonson.Json version Never versions of the dotnet-sdk have issues with older Newtonsoft versions. 12.0.1 seems to satisfy the widest variety of sdk versions. * Removing old readme * Removed Duplicate Section * Fixed typo This fixes and closes issue #24.
2019-06-05 20:19:39 +02:00
```
---
# FAQ: Questions you might have.
2018-11-22 05:37:36 +01:00
## Why build a license generator for open source software?
2017-10-19 19:19:24 +02:00
We agree that Bitwarden is great. If we didn't care about it then we wouldn't be doing this. We believe that if a user wants to host Bitwarden themselves, in their house, for their family to use amd with the ability to share access, they would still have to pay a **monthly** enterprise organization fee. When hosting and maintaining the software yourself there is no need to pay for the level of service that an enterprise customer needs.
2017-10-19 19:19:24 +02:00
Unfortunately, Bitwarden doesn't seem to have any method for receiving donations so we recommend making a one-time donation to your open source project of choice for each BitBetter license you generate if you can afford to do so.
2017-10-19 19:19:24 +02:00
## Shouldn't you have reached out to Bitwarden to ask them for alternative licensing structures?
2017-10-19 19:19:24 +02:00
In the past we have done so but they were not focused on the type of customer that would want a one-time license and would be happy to sacrifice customer service. We believe the features that are currently behind this subscription paywall to be critical ones and believe they should be available to users who can't afford an enterprise payment structure. We'd even be happy to see a move towards a Gitlab-like model where premium features are rolled out *first* to the enterprise subscribers before being added to the fully free version.
# Footnotes
<a name="#f1"><sup>1</sup></a> If you wish to change this you'll need to change the value that `src/licenseGen/Program.cs` uses for its `GenerateUserLicense` and `GenerateOrgLicense` calls. Remember, this is really unnecessary as this certificate does not represent any type of security-related certificate.
<a name="#f2"><sup>2</sup></a>This tool builds on top of the `bitbetter/api` container image so make sure you've built that above using the root `./build.sh` script.