mirror of
https://github.com/jakeswenson/BitBetter.git
synced 2025-12-16 11:16:19 +00:00
* Initial work * Fix typo * Fix typo * Fix stupid issue * Add comments and fix minor issues * Add extra information * Add Linux script for generating keys * Add circleci * Add comments * Add extra option * Add missing permissions and empty script for now * Fix line endings * Add missing mount point * Simplify patch * Fix scripts * Reduce complexity * Fix circleci * Remove useless line * Move to src folder and improve image creation
This commit is contained in:
Michiel Hazelhof
GitHub
134
README.md
134
README.md
@@ -1,10 +1,10 @@
|
||||
# BitBetter
|
||||
|
||||
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.**
|
||||
BitBetter is is a tool to modify Bitwarden's core dll to allow you to generate your own individual and organisation licenses.
|
||||
|
||||
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!_
|
||||
_Beware! BitBetter does some semi janky stuff to rewrite the bitwarden core dll and allow the installation of a self signed certificate. Use at your own risk!_
|
||||
|
||||
Credit to https://github.com/h44z/BitBetter and https://github.com/jakeswenson/BitBetter
|
||||
|
||||
@@ -25,55 +25,70 @@ Credit to https://github.com/h44z/BitBetter and https://github.com/jakeswenson/B
|
||||
- [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).
|
||||
The following instructions are for unix-based systems (Linux, BSD, macOS) and Windows, just choose the correct script extension (.sh or .ps1 respectively).
|
||||
|
||||
## Dependencies
|
||||
Aside from docker, which you also need for Bitwarden, BitBetter requires the following:
|
||||
|
||||
* Bitwarden (tested with 1.47.1, might work on lower versions)
|
||||
* openssl (probably already installed on most Linux or WSL systems, any version should work)
|
||||
* openssl (probably already installed on most Linux or WSL systems, any version should work, on Windows it will be auto installed using winget)
|
||||
|
||||
## Setting up BitBetter
|
||||
With your dependencies installed, begin the installation of BitBetter by downloading it through Github or using the git command:
|
||||
|
||||
```bash
|
||||
```
|
||||
git clone https://github.com/jakeswenson/BitBetter.git
|
||||
```
|
||||
|
||||
## Building BitBetter
|
||||
|
||||
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.
|
||||
Now that you've set up your build environment, we need to specify which servers to start after the work is done.
|
||||
The scripts supports running and patching multi instances.
|
||||
|
||||
Edit the .servers/serverlist.txt file and fill in the missing values, they can be replaced with existing installation values.
|
||||
This file may be empty, but there will be no containers will be spun up automatically.
|
||||
|
||||
Now it is time to **run the main build script** to generate a modified version of the `bitwarden/self-host` docker image and the license generator.
|
||||
|
||||
From the BitBetter directory, simply run:
|
||||
```bash
|
||||
./build.sh
|
||||
```
|
||||
./build.[sh|ps1]
|
||||
```
|
||||
|
||||
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`.
|
||||
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/self-host` image called `bitwarden-patch`.
|
||||
|
||||
You may now simply create the file `/path/to/bwdata/docker/docker-compose.override.yml` with the following contents to utilize the modified images.
|
||||
Afterwards it will automatically generate the license generator and start all previously specified containers which are **now ready to accept self-issued licenses.**
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
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`.
|
||||
|
||||
> Replace `dockerComposePull`<br>with `#dockerComposePull`
|
||||
|
||||
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.**
|
||||
|
||||
---
|
||||
|
||||
## Updating Bitwarden and BitBetter
|
||||
|
||||
To update Bitwarden, the same `build.[sh|ps1]` script can be used. It will rebuild the BitBetter image and automatically update Bitwarden before doing so.
|
||||
|
||||
## Generating Signed Licenses
|
||||
|
||||
There is a tool included in the directory `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.
|
||||
|
||||
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/).
|
||||
|
||||
**The user must have a verified email address at the time of license import, otherwise Bitwarden will reject the license key. Nevertheless, the license key can be generated even before the user's email is verified.**
|
||||
|
||||
If you ran the build script, you can **simply run the license gen in interactive mode** from the `Bitbetter` directory and **follow the prompts to generate your license**.
|
||||
|
||||
```
|
||||
./licenseGen.[sh|ps1] interactive
|
||||
```
|
||||
|
||||
**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: Manually generating Certificate & Key
|
||||
|
||||
If you wish to generate your self-signed cert & key manually, you can run the following commands.
|
||||
Note that you should never have to do this yourself, but can also be triggered by running the generateKeys.[sh|ps1] script.
|
||||
|
||||
```bash
|
||||
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.cert -days 36500 -outform DER -passout pass:test
|
||||
@@ -81,69 +96,11 @@ 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
|
||||
```
|
||||
|
||||
> Note that the password here must be `test`.<sup>[1](#f1)</sup>
|
||||
> Note that the password here must be `test`.<sup>[2](#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`)
|
||||
|
||||
If you are updating from versions <= 1.46.2, you may need to run `update-bitwarden.sh` twice to complete the update process.
|
||||
|
||||
## Generating Signed Licenses
|
||||
|
||||
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>
|
||||
|
||||
```bash
|
||||
./build.sh
|
||||
```
|
||||
|
||||
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/).
|
||||
|
||||
**The user must have a verified email address at the time of license import, otherwise Bitwarden will reject the license key. Nevertheless, the license key can be generated even before the user's email is verified.**
|
||||
|
||||
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**.
|
||||
|
||||
```bash
|
||||
./src/licenseGen/run.sh interactive
|
||||
```
|
||||
|
||||
**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" "E-Mail" "User-GUID" ["Storage Space in GB"] ["Custom LicenseKey"]
|
||||
./src/licenseGen/run.sh /Absolute/Path/To/BitBetter/.keys/cert.pfx org "Name" "E-Mail" "Install-ID used to install the server" ["Storage Space in GB"] ["Custom LicenseKey"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
# FAQ: Questions you might have.
|
||||
|
||||
## Why build a license generator for open source software?
|
||||
@@ -161,7 +118,6 @@ UPDATE: Bitwarden now offers a cheap license called [Families Organization](http
|
||||
|
||||
# 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.
|
||||
<a name="#f1"><sup>1</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.
|
||||
|
||||
<a name="#f2"><sup>2</sup></a> If you wish to change this you'll need to change the value that `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.
|
||||
|
||||
Reference in New Issue
Block a user