From 05543b5b8af809629be11bc5c48929bec243c8e1 Mon Sep 17 00:00:00 2001 From: Jeff Alyanak Date: Sat, 11 May 2019 15:45:03 -0400 Subject: [PATCH 1/6] 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. --- .keys/Empty.txt | 1 - .keys/generate-keys.sh | 15 +++++++++++++++ README.md | 4 ++-- 3 files changed, 17 insertions(+), 3 deletions(-) delete mode 100644 .keys/Empty.txt create mode 100755 .keys/generate-keys.sh diff --git a/.keys/Empty.txt b/.keys/Empty.txt deleted file mode 100644 index 031e408..0000000 --- a/.keys/Empty.txt +++ /dev/null @@ -1 +0,0 @@ -Need an empty folder diff --git a/.keys/generate-keys.sh b/.keys/generate-keys.sh new file mode 100755 index 0000000..7e91e67 --- /dev/null +++ b/.keys/generate-keys.sh @@ -0,0 +1,15 @@ +#!/bin/sh + +# Check for openssl +command -v openssl >/dev/null 2>&1 || { echo >&2 "openssl required but not found. Aborting."; exit 1; } + +# Remove any existing key files +[ ! -e cert.pem ] || rm cert.pem +[ ! -e key.pem ] || rm key.pem +[ ! -e cert.cert ] || rm cert.cert +[ ! -e cert.pfx ] || rm cert.pfx + +# Generate new keys +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 diff --git a/README.md b/README.md index 346749e..282dcd4 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,9 @@ If you want to be able to sign your own licenses obviously you'll have to replac ### Signing licesnses -There is a tool included to generate a license (see `src/liceseGen/`) +To sign your own license you first need to generate your own singing cert using the `.keys/generate-keys.sh` script. Running this script will prompt you to enter some information about your new certificate, you may leave these at the defaults or set them to your preference. The script will then create a pkcs12 file (.pfx) containing your new key/cert. -generate a PFX above using a password of `test` and then build the tool using: +There is a tool included to generate a license (see `src/liceseGen/`), build it using: ```bash ./src/licenseGen/build.sh From 11821080261d85822f6d14a7243dfe64b83dcfc8 Mon Sep 17 00:00:00 2001 From: Jeff Alyanak Date: Fri, 17 May 2019 14:15:38 -0400 Subject: [PATCH 2/6] 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. --- README.md | 91 +++++++++++++++++++++++++++++++++++++++--------- ReadMeInstall | 95 --------------------------------------------------- 2 files changed, 74 insertions(+), 112 deletions(-) delete mode 100644 ReadMeInstall diff --git a/README.md b/README.md index 346749e..24b9688 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,99 @@ # BitBetter -This project is a tool to modify bitwardens core dll to allow me to self license. -Beware this does janky IL magic to rewrite the bitwarden core dll and install my self signed certificate. +BitBetter is is a tool to modify bitwardens 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. -Yes, there still are quite a few things that need to be fixed. Updates and Organization Buiness Name is hardcoded to Bitbetter, are the first to things to fix.. Better handling of the User-GUID comes to mind too. +_Beware! BitBetter does janky IL magic to rewrite the bitwarden core dll and install a self signed certificate. Use at your own risk!_ Credit to https://github.com/h44z/BitBetter and https://github.com/jakeswenson/BitBetter -## Building +# Table of Contents +1. [Getting Started](#gettingstarted) + + [Pre-requisites](#prereq) + + [Setting up BitBetter](#setup) + + [Building BitBetter](#building) + + [Generating Signed Licenses](#generating) +2. [FAQ](#faq) +3. [Footnotes](#footnotes) -To build your own `bitwarden/api` image run +# 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). + +## Pre-requisites +Aside from docker, which you also need for Bitwarden, BitBetter requires the following: + +* openssl (probably already installed on most Linux or WSL systems) +* dotnet-sdk-2.1 (install instructions can be found [here](https://dotnet.microsoft.com/download/linux-package-manager/rhel/sdk-2.1.604)) + +## Setting up BitBetter +With your pre-requisites installed, begin the installation of BitBetter by downloading it through Github or using the git command: + +```bash +git clone https://github.com/online-stuff/BitBetter.git +``` + +First, we need to add the correct version of Newtonsoft.Json to the license generator and the BitBetter docker directories. + +```bash +cd BitBetter/src/licenseGen/ +dotnet add package Newtonsoft.Json --version 11.0.0 + +cd ../bitBetter +dotnet add package Newtonsoft.Json --version 11.0.0 +``` + +Next, we need to generate the self-signed certificate we will use to sign any licenses we generate. + +```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 +``` + +Note that the password here must be `test`.[1](#f1) + +## Building BitBetter + +Now that you've generated your own own self-signed certificate, you can run the main `BitBetter/build.sh` script to generate a modified version of the `bitwarden/api` docker image. + +From the BitBetter directory, simply run: ```bash ./build.sh ``` -replace anywhere `bitwarden/api` is used with `bitbetter/api` and give it a go. no promises +This will create a modified version of the official `bitwarden/api` called `bitbetter/api`. You may now simply edit your bitwarden docker-compose.yml to utilize the modified image. -## Issuing your own licenses +Edit your `/path/to/bwdata/docker/docker-compose.yml`. -The repo is setup to replace the licesning signing cert in bitwarden.core with your own personal self signed cert (`cert.pfx`) -If you want to be able to sign your own licenses obviously you'll have to replace it with your own self signed cert. +> Replace `image: bitwarden/api:x.xx.x`
with `image: bitbetter/api` +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`. -### Signing licesnses +> Replace `dockerComposePull`
with `#dockerComposePull` -There is a tool included to generate a license (see `src/liceseGen/`) +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. -generate a PFX above using a password of `test` and then build the tool using: +## 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.[2](#f2) ```bash -./src/licenseGen/build.sh +./build.sh ``` -This tool build ontop of the bitbetter/api container image so make sure you've built that above using the root `./build.sh` script. +Now, from the `BitBetter/src/licenseGen` directory, you can run the tool to generate licenses. -After that you can run the tool using: +You'll need to get a user's GUID in order to generate an invididual license and 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/). ```bash -cd ~/BitBetter/src/licenseGen ./run.sh ~/BitBetter/.keys/cert.pfx user "Name" "EMail" "User-GUID" ./run.sh ~/BitBetter/.keys/cert.pfx org "Name" "EMail" "Install-ID used to install the server" ``` -# Questions (you might have?) +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! + +# FAQ: Questions (you might have?) I'll work on updates in the next couple weeks, right now, I just wanted something to start with. @@ -59,3 +110,9 @@ Thanks, good idea. And I did. Currently they're not focused on solving this issu To be clear i'm totally happy to give them my money. Offer a perpetual server license, and i'd pay for it. Let me license the server, period. Allow an orginzation to have Premium for all users.. 500 seats, let the 500 users in the orginzation have the Premium features too. I'm still in the testing/evaluating phase. If I am hosting the server/data, let me license the server, period. How many licenses does one user need to have... + +# Footnotes + +1 If you wish to change this you'll need to change the value that `src/licenseGen/Program.cs` uses for it's `GenerateUserLicense` and `GenerateOrgLicense` calls, but this is really unnecessary as this certificate does not represent any type of security issue. + +2This tool build ontop of the `bitbetter/api` container image so make sure you've built that above using the root `./build.sh` script. \ No newline at end of file diff --git a/ReadMeInstall b/ReadMeInstall deleted file mode 100644 index ff8b2c1..0000000 --- a/ReadMeInstall +++ /dev/null @@ -1,95 +0,0 @@ -These are the commands I used (and a few of my notes) for a minimal Debian Stretch install.. -Software Selection - "SSH server" and 'standard system utilities" only - - - -sudo apt-get update -sudo apt-get install vim vim-doc vim-scripts wget curl git -sudo apt-get dist-upgrade -sudo reboot - ----The next few lines I setup my server authentication and other misc profile settings you can skip until sudo apt-get - -ssh-keygen - -echo "ssh-rsa AA...1Q== " >> .ssh/authorized_keys - -echo ":set mouse=" >> .vimrc -echo "set nocompatible" >> .vimrc - -vi .bashrc - -sudo visudo ---- tom ALL=(ALL) NOPASSWD:ALL - -sudo vi /etc/ssh/sshd_config - Enable 'PermitRootLogin prohibit-password' and 'PasswordAuthentication no' - -sudo apt-get update -sudo apt install apt-transport-https ca-certificates curl gnupg2 software-properties-common -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - -sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" -sudo apt update -apt-cache policy docker-ce -sudo apt install docker-ce -sudo systemctl status docker -sudo usermod -aG docker ${USER} -exit - -id -nG -docker version -docker info -docker run hello-world - -sudo curl -L --fail https://github.com/docker/compose/releases/download/1.23.1/run.sh -o /usr/local/bin/docker-compose -sudo chmod +x /usr/local/bin/docker-compose - -wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.asc.gpg -sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/ -wget -q https://packages.microsoft.com/config/debian/9/prod.list -sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list -sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.asc.gpg -sudo chown root:root /etc/apt/sources.list.d/microsoft-prod.list - -curl -s -o bitwarden.sh https://raw.githubusercontent.com/bitwarden/core/master/scripts/bitwarden.sh && sudo chmod u+x bitwarden.sh -./bitwarden.sh install - -sudo apt-get update -sudo apt-get install dotnet-sdk-2.1 - -git clone https://github.com/online-stuff/BitBetter.git - -cd BitBetter/src/licenseGen/ -dotnet add package Newtonsoft.Json --version 11.0.0 - -cd ~/BitBetter/src/bitBetter -dotnet add package Newtonsoft.Json --version 11.0.0 - -cd ~/BitBetter/.keys -rm * - -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 - - -cd ~/BitBetter -./build.sh - -cd src/licenseGen/ -./build.sh - -cd ~ - -vi ~/bwdata/docker/docker-compose.yml - Change image: bitwarden/api:1.26.0 to image: bitbetter/api -vi ~/bwdata/env/global.override.env - Enter mail__smtp relay settings -vi ~/bwdata/scripts/run.sh - function restart() { dockerComposePull to #dockerComposePull - -./bitwarden start - -----Server should be up and running.. Create a user account - -cd ~/BitBetter/src/licenseGen/ -./build.sh -./run.sh ~/BitBetter/.keys/cert.pfx user "Name" "EMail" "User-GUID" - Get User-GUID from the admin portal of the BitWarden server - -./run.sh ~/BitBetter/.keys/cert.pfx org "Name" "EMail" "Install-ID used to install the server from bitwarden.com/host" From 8e6429d5339c57b1af9a62efed904e957cf1e993 Mon Sep 17 00:00:00 2001 From: Jeff Alyanak Date: Wed, 29 May 2019 14:05:08 -0400 Subject: [PATCH 3/6] 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. --- README.md | 4 ++-- src/licenseGen/licenseGen.csproj | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 58551ad..1514f9b 100644 --- a/README.md +++ b/README.md @@ -35,10 +35,10 @@ First, we need to add the correct version of Newtonsoft.Json to the license gene ```bash cd BitBetter/src/licenseGen/ -dotnet add package Newtonsoft.Json --version 11.0.0 +dotnet add package Newtonsoft.Json --version 12.0.1 cd ../bitBetter -dotnet add package Newtonsoft.Json --version 11.0.0 +dotnet add package Newtonsoft.Json --version 12.0.1 ``` Next, we need to generate the self-signed certificate we will use to sign any licenses we generate. diff --git a/src/licenseGen/licenseGen.csproj b/src/licenseGen/licenseGen.csproj index a24ae32..73abe54 100644 --- a/src/licenseGen/licenseGen.csproj +++ b/src/licenseGen/licenseGen.csproj @@ -7,7 +7,7 @@ - + From fcc22a7d7aa897e0b67809e0233bcb8afc76fcc4 Mon Sep 17 00:00:00 2001 From: captainhook <16797541+captainhook@users.noreply.github.com> Date: Mon, 4 Mar 2024 21:43:42 +0000 Subject: [PATCH 4/6] update licenseGen.csproj to match latest --- src/licenseGen/licenseGen.csproj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/licenseGen/licenseGen.csproj b/src/licenseGen/licenseGen.csproj index 73abe54..f3fd1a5 100644 --- a/src/licenseGen/licenseGen.csproj +++ b/src/licenseGen/licenseGen.csproj @@ -2,12 +2,12 @@ Exe - netcoreapp2.0 + netcoreapp8.0 - + From c6c4232f46dfc489e65e3bc50a1c33d24f8ceb77 Mon Sep 17 00:00:00 2001 From: captainhook <16797541+captainhook@users.noreply.github.com> Date: Mon, 4 Mar 2024 21:43:54 +0000 Subject: [PATCH 5/6] update README --- README.md | 139 +++++++++++++++++------------------------------------- 1 file changed, 44 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 1514f9b..8121b67 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,73 @@ # BitBetter - -BitBetter is is a tool to modify bitwardens 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 IL magic to rewrite the bitwarden core dll and install a self signed certificate. Use at your own risk!_ - -Credit to https://github.com/h44z/BitBetter and https://github.com/jakeswenson/BitBetter - -# Table of Contents -1. [Getting Started](#gettingstarted) - + [Pre-requisites](#prereq) - + [Setting up BitBetter](#setup) - + [Building BitBetter](#building) - + [Generating Signed Licenses](#generating) -2. [FAQ](#faq) -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). - -## Pre-requisites -Aside from docker, which you also need for Bitwarden, BitBetter requires the following: - -* openssl (probably already installed on most Linux or WSL systems) -* dotnet-sdk-2.1 (install instructions can be found [here](https://dotnet.microsoft.com/download/linux-package-manager/rhel/sdk-2.1.604)) - -## Setting up BitBetter -With your pre-requisites installed, begin the installation of BitBetter by downloading it through Github or using the git command: - -```bash -git clone https://github.com/online-stuff/BitBetter.git +./update-bitwarden.sh param1 param2 param3 ``` +`param1`: The path to the directory containing your bwdata directory -First, we need to add the correct version of Newtonsoft.Json to the license generator and the BitBetter docker directories. +`param2`: If you want the docker-compose file to be overwritten (either `y` or `n`) -```bash -cd BitBetter/src/licenseGen/ -dotnet add package Newtonsoft.Json --version 12.0.1 +`param3`: If you want the bitbetter images to be rebuild (either `y` or `n`) -cd ../bitBetter -dotnet add package Newtonsoft.Json --version 12.0.1 -``` +If you are updating from versions <= 1.46.2, you may need to run `update-bitwarden.sh` twice to complete the update process. -Next, we need to generate the self-signed certificate we will use to sign any licenses we generate. - -To sign your own license you first need to generate your own signing cert using the `.keys/generate-keys.sh` script. - -Running this script will prompt you to enter some information about your new certificate, you may leave these at the defaults or set them to your preference. The script will then create a pkcs12 file (.pfx) containing your new key/cert. - -You may also choose to do this manually via 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 -``` - -Note that the password here must be `test`.[1](#f1) - -## Building BitBetter - -Now that you've generated your own own self-signed certificate, you can run the main `BitBetter/build.sh` script to generate a modified version of the `bitwarden/api` docker image. - -From the BitBetter directory, simply run: -```bash -./build.sh -``` - -This will create a modified version of the official `bitwarden/api` called `bitbetter/api`. You may now simply edit your bitwarden docker-compose.yml to utilize the modified image. - -Edit your `/path/to/bwdata/docker/docker-compose.yml`. - -> Replace `image: bitwarden/api:x.xx.x`
with `image: bitbetter/api` - -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`
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. - -## Generating Signed Licenses +## 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.[2](#f2) +First, from the `BitBetter/src/licenseGen` directory, **build the license generator**.[2](#f2) ```bash ./build.sh ``` -Now, from the `BitBetter/src/licenseGen` directory, you can run the tool to generate licenses. +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/). -You'll need to get a user's GUID in order to generate an invididual license and 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 -./run.sh ~/BitBetter/.keys/cert.pfx user "Name" "EMail" "User-GUID" -./run.sh ~/BitBetter/.keys/cert.pfx org "Name" "EMail" "Install-ID used to install the server" +./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! +**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!** -# FAQ: Questions (you might have?) +--- -I'll work on updates in the next couple weeks, right now, I just wanted something to start with. +### Note: Alternative Ways to Generate License -## But why? Its open source? +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. -Yes, bitwarden is great. If I didn't care about it i wouldn't be doing this. -I was bothered that if i want to host bitwarden myself, at my house, -for my family to use (with the ability to share access) I would still have to pay a monthly ENTERPRISE organization fee. -To host it myself. And maintain it myself. Basically WTH was bitwarden doing that I was paying them for? +```bash +./src/licenseGen/run.sh /Absolute/Path/To/BitBetter/.keys/cert.pfx interactive +``` -## You should have reached out to bitwarden +Additional, instead of interactive mode, you can also pass the parameters directly to the command as follows. -Thanks, good idea. And I did. Currently they're not focused on solving this issue - yet. -To be clear i'm totally happy to give them my money. Offer a perpetual server license, and i'd pay for it. Let me license the server, period. Allow an orginzation to have Premium for all users.. 500 seats, let the 500 users in the orginzation have the Premium features too. +```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"] +``` -I'm still in the testing/evaluating phase. If I am hosting the server/data, let me license the server, period. How many licenses does one user need to have... +--- -# Footnotes -1 If you wish to change this you'll need to change the value that `src/licenseGen/Program.cs` uses for it's `GenerateUserLicense` and `GenerateOrgLicense` calls, but this is really unnecessary as this certificate does not represent any type of security issue. +# FAQ: Questions you might have. -2This tool build ontop of the `bitbetter/api` container image so make sure you've built that above using the root `./build.sh` script. \ No newline at end of file +## Why build a license generator for open source software? + +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 on their own infrastructure, for their family to use, and with the ability to share access, they should still pay the fee charged by the software publishers. + +Such use cases may not require enterprise level support and unfortunately Bitwarden doesn't have any method for receiving donations - therefore we recommend you purchasing the relevant licenses for your use directly from Bitwarden: https://bitwarden.com/pricing/. + +## Shouldn't you have reached out to Bitwarden to ask them for alternative licensing structures? + +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 to be critical ones and believe they should be available to users who do not require an enterprise 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. + +UPDATE: Bitwarden now offers a cheap license called [Families Organization](https://bitwarden.com/pricing/) that provides premium features and the ability to self-host Bitwarden for six persons. Please use this option as it is the correct and supported method by Bitwarden. + + +# Footnotes + +1 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. + +2This tool builds on top of the `bitbetter/api` container image so make sure you've built that above using the root `./build.sh` script. From 0b170fd0d89edea83032c7a44bea637ee26e49fb Mon Sep 17 00:00:00 2001 From: captainhook <16797541+captainhook@users.noreply.github.com> Date: Mon, 4 Mar 2024 21:50:21 +0000 Subject: [PATCH 6/6] correct readme --- README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 98 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 8121b67..5736094 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,96 @@ # BitBetter + +BitBetter is a tool to allow you to generate your own individual and organisation licenses. **You must have an existing installation of Bitwarden for BitBetter to modify.** + +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!_ + +Credit to https://github.com/h44z/BitBetter and https://github.com/jakeswenson/BitBetter + +# Table of Contents +- [BitBetter](#bitbetter) +- [Table of Contents](#table-of-contents) +- [Getting Started](#getting-started) + - [Dependencies](#dependencies) + - [Setting up BitBetter](#setting-up-bitbetter) + - [Building BitBetter](#building-bitbetter) + - [Note: Manually generating Certificate & Key](#note-manually-generating-certificate--key) + - [Updating Bitwarden and BitBetter](#updating-bitwarden-and-bitbetter) + - [Generating Signed Licenses](#generating-signed-licenses) + - [Note: Alternative Ways to Generate License](#note-alternative-ways-to-generate-license) +- [FAQ: Questions you might have.](#faq-questions-you-might-have) + - [Why build a license generator for open source software?](#why-build-a-license-generator-for-open-source-software) + - [Shouldn't you have reached out to Bitwarden to ask them for alternative licensing structures?](#shouldnt-you-have-reached-out-to-bitwarden-to-ask-them-for-alternative-licensing-structures) +- [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://learn.microsoft.com/en-us/windows/wsl/install). + +## Dependencies +Aside from Docker, which you also need for Bitwarden, BitBetter requires the following: + +* Bitwarden - https://bitwarden.com/help/install-on-premise-linux/ +* 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 +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. + +From the BitBetter directory, simply run: +```bash +./build.sh +``` + +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. + +```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`
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.** + +--- +### 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 +``` + +> Note that the password here must be `test`.[1](#f1) + +--- + +## 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 @@ -13,6 +105,7 @@ If you are updating from versions <= 1.46.2, you may need to run `update-bitward 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**.[2](#f2) ```bash @@ -55,15 +148,15 @@ Additional, instead of interactive mode, you can also pass the parameters direct ## Why build a license generator for open source software? -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 on their own infrastructure, for their family to use, and with the ability to share access, they should still pay the fee charged by the software publishers. +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 and 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. -Such use cases may not require enterprise level support and unfortunately Bitwarden doesn't have any method for receiving donations - therefore we recommend you purchasing the relevant licenses for your use directly from Bitwarden: https://bitwarden.com/pricing/. +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. ## Shouldn't you have reached out to Bitwarden to ask them for alternative licensing structures? -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 to be critical ones and believe they should be available to users who do not require an enterprise 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. +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. -UPDATE: Bitwarden now offers a cheap license called [Families Organization](https://bitwarden.com/pricing/) that provides premium features and the ability to self-host Bitwarden for six persons. Please use this option as it is the correct and supported method by Bitwarden. +UPDATE: Bitwarden now offers a cheap license called [Families Organization](https://bitwarden.com/pricing/) that provides premium features and the ability to self-host Bitwarden for six persons. # Footnotes @@ -71,3 +164,4 @@ UPDATE: Bitwarden now offers a cheap license called [Families Organization](http 1 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. 2This tool builds on top of the `bitbetter/api` container image so make sure you've built that above using the root `./build.sh` script. +