Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.futurex.com/llms.txt

Use this file to discover all available pages before exploring further.

Refer to this section and the Bitwarden About Key Connector (bitwarden.com/help/about-key-connector/) and Deploy Key Connector (bitwarden.com/help/deploy-key-connector/) instructions for installation and configuration guidance. Perform the following steps to configure Bitwarden:
  1. Set up and Deploy Key Connector.
  2. Confirm endpoint values.
  3. Create database.
  4. Create and RSA key pair.
  5. Activate Key Connector.

​
Before you start

To get started using Key Connector for customer-managed encryption, review the following requirements. To use Key Connector, you must have the following components:
  • An Enterprise organization
  • A self-hosted Bitwarden server
  • An active SSO implementation
  • Enabled Single organization and Require single sign-on authentication policies
If your organization meets these requirements, including a team and infrastructure that supports key server management, contact Bitwarden so they can activate Key Connector.

​
Set up and deploy Key Connector

After you contact Bitwarden regarding Key Connector, they schedule a Key Connector discussion. Perform the following tasks to set up and deploy Key Connector:
  1. Obtain a new license file.
  2. Initialize Key Connector.
  3. Configure Key Connector.

​
Obtain a license file

After Bitwarden enables Key Connector for your organization, complete the following steps to obtain the new license:
1
Open the Bitwarden cloud web app and go to your organization Billing > Subscription screen in the Admin Console.
2
Scroll down and select [ Download License ].
3
When prompted, enter the installation ID used to install your self-hosted server and select [ Submit ]. If you don’t know your installation ID, retrieve it from ./bwdata/env/global.override.env.
You won’t need your license file immediately, but you must upload it to your self-hosted server later.

​
Initialize Key Connector

To prepare your Bitwarden server, perform the following steps to initialize Key Connector:
1
Save a backup of .bwdata/mssql. After you start using Key Connector, we recommend that you have access to a pre-Key Connector backup image in case you need it.
If you use an external MSSQL database, back up your database by following your usual procedure.
2
Update your self-hosted Bitwarden installation to retrieve the latest changes:
Text
./bitwarden.sh update
3
Edit the .bwdata/config.yml file and enable Key Connector by setting enable_key_connector to true.
Text
nano bwdata/config.yml
4
Rebuild your self-hosted Bitwarden installation:
Text
./bitwarden.sh rebuild
5
Update your self-hosted Bitwarden installation again to apply the changes:
Text
./bitwarden.sh update

​
Configure Key Connector

To configure Key Connector, perform the following steps:
1
Download the tarball of the Linux PKCS #11 binaries from the Futurex Portal.
2
Copy the Linux PKCS #11 tar file to your Bitwarden server:
3
Extract the .tar file.
4
The extracted content of the .tar file is a single fxpkcs11 directory. This directory contains the following files and directories (only the files and folders relevant to the installation process are included in this list):
File name or directoryDescription
fxpkcs11.cfgPKCS #11 configuration file to use for HSM Integrations.
x86/This folder contains the module files for the 32-bit architecture.
x64/This folder contains the module files for the 64-bit architecture.
The x86 and x64 directories contain multiple directories named for the specific OpenSSL versions. These OpenSSL directories contain the PKCS #11 module files built with the respective OpenSSL versions.
You must use the OpenSSL 3.x binaries because that version is installed in the Bitwarden Key Connector container.
File nameDescription
configTestProgram to test the configuration and connection to the HSM.
libfxpkcs11.soPKCS #11 Library file.
PKCS11ManagerProgram to test the connection and manage the HSM through the PKCS #11 library.
5
Convert the PEM certificate created with FXCLI in the previous section to PFX format using OpenSSL:
Bash
openssl pkcs12 -export -nokeys -in Bitwarden-Cert.pem -out Bitwarden-Cert.pfx
Specify Futurex123 as the password for the PFX file.
6
Copy the following files to the /opt/bitwarden/bwdata/key-connector directory:
As previously noted above, you must use the OpenSSL 3.x binaries because that version is installed in the Bitwarden Key Connector container.
  • Bitwarden.pfx
  • PKI.p12 (the TLS client certificate created for the Futurex PKCS #11 library to mutually authenticate to the KMES Series 3.)
  • libfxpkcs11.so
  • fxpkcs11.cfg
  • PKCS11Manager
By putting these files in the /opt/bitwarden/bwdata/key-connector directory, the system bind-mounts them inside the bitwarden-key-connector container at /etc/bitwarden/key-connector.
7
Edit the .bwdata/env/key-connector.override.env file that came with the ./bitwarden.sh update you downloaded.Example key-connector.override.env:
Env
  keyConnectorSettings__webVaultUri=https://ec2-34-193-223-21.compute-1.amazonaws.com
  keyConnectorSettings__identityServerUri=http://identity:5000
  keyConnectorSettings__database__provider=json
  keyConnectorSettings__database__jsonFilePath=/etc/bitwarden/key-connector/data.json

  keyConnectorSettings__certificate__provider=filesystem
  keyConnectorSettings__certificate__filesystemPath=/etc/bitwarden/key-connector/Bitwarden.pfx
  keyConnectorSettings__certificate__filesystemPassword=Futurex123

  keyConnectorSettings__rsaKey__provider=pkcs11
  keyConnectorSettings__rsaKey__pkcs11LibraryPath=/etc/bitwarden/key-connector/libfxpkcs11.so
  FXPKCS11_CFG=/etc/bitwarden/key-connector/fxpkcs11.cfg
  keyConnectorSettings__rsaKey__pkcs11SlotTokenSerialNumber=3174612105
  keyConnectorSettings__rsaKey__pkcs11LoginUserType=user
  keyConnectorSettings__rsaKey__pkcs11LoginPin=EDY0DD29B2T82*fC0&@511h1m4D8
  keyConnectorSettings__rsaKey__pkcs11PrivateKeyLabel=Bitwarden
The FXPKCS11_CFG=/etc/bitwarden/key-connector/fxpkcs11.cfg enables the Futurex PKCS #11 module to find the configuration file at the non-default location (/etc). To determine the keyConnectorSettings__rsaKey__pkcs11SlotTokenSerialNumber value you must specify, run the PKCS11Manager utility against your KMES Series 3 and select option 1 (Print Library/Token Info). Set keyConnectorSettings__rsaKey__pkcs11LoginPin to the password value you configured for the Bitwarden identity.

​
Confirm endpoint values

The automated setup populates endpoint values based on your installation configuration. However, we recommend that you confirm the following values in key-connector.override.env are accurate for your setup:
Text
keyConnectorSettings__webVaultUri=https://your.bitwarden.domain.com
keyConnectorSettings__identityServerUri=http://identity:5000

​
Create database

Key Connector must access a database that stores encrypted user keys for your organization members. Create a secure database to store encrypted user keys and replace the default keyConnectorSettings__database__ values in key-connector.override.env with the values designated in the Required Values column for the chosen database.
The preceding example key-connector.override.env defines Local JSON, but we do not recommend this option except for testing. For production environments, Bitwarden recommends using one of the other supported database options (such as Microsoft SQL Server, PostgreSQL, MySQL/MariaDB, or MongoDB).

​
Create an RSA key pair

Key Connector uses an RSA key pair to protect user keys at rest. You must replace the default keyConnectorSettings__rsaKey__ and keyConnectorSettings__certificate__ values in key-connector.override.env with the values required to integrate with CryptoHub.
The RSA key pair must be at a minimum 2048 bits in length.
Key Connector directly accesses the CryptoHub-stored private key through the Futurex PKCS #11 module and the X.509 Certificate in the file system.

​
Activate Key Connector

Now that you configured Key Connector and have a Key Connector-enabled license complete the following steps:
1
Restart your self-hosted Bitwarden installation to apply the configuration changes:
Text
./bitwarden.sh restart
2
Log in to your self-hosted Bitwarden as an organization owner and go to the Admin Console Billing > Subscription screen.
3
Select [ Update license ] and upload the Key Connector-enabled license retrieved in an earlier step.
4
If you haven’t already, go to the Settings > Policies screen and enable the Single organization and Require single sign-on authentication policies, which are required to use Key Connector.
5
Go to the Settings > Single sign-on screen.
The next few steps assume that you already have an active login with SSO implementation using SAML 2.0 or OIDC. If you don’t, implement and test login with SSO before proceeding.
6
In the Member decryption options section, select Key Connector.
7
In the Key Connector URL input, enter the address where you are running Key Connector (by default, https://your.domain/key-connector) and select [ Test ] to ensure you can reach Key Connector.
8
Scroll to the bottom of the screen and select [ Save ].