Skip to content

An agent that stores and provides cryptographic keys to Bitwarden clients.

License

Notifications You must be signed in to change notification settings

bitwarden/key-connector

Repository files navigation

DockerHub

Bitwarden Key Connector

The Bitwarden Key Connector is a self-hosted web application that stores and provides cryptographic keys to Bitwarden clients.

The Key Connector project is written in C# using .NET Core with ASP.NET Core. The codebase can be developed, built, run, and deployed cross-platform on Windows, macOS, and Linux distributions.

Deploy

The Bitwarden Key Connector can be deployed using the pre-built docker container available on DockerHub.

Configuration

A variety of configuration options are available for the Bitwarden Key Connector.

Bitwarden Server

By default, the Bitwarden server configuration points to the Bitwarden Cloud endpoints. If you are using a self-hosted Bitwarden installation, you will need to configure the web vault and identity server endpoints.

keyConnectorSettings__webVaultUri=https://bitwarden.company.com
keyConnectorSettings__identityServerUri=https://bitwarden.company.com/identity/

Database

A database persists encrypted keys for your users. The following databases are supported to be configured. Migrating from one database provider to another is not supported at this time.

JSON File (default)

keyConnectorSettings__database__provider=json
keyConnectorSettings__database__jsonFilePath={FilePath}

By default, the application stores the JSON file at the follow path: /etc/bitwarden/data.json.

Microsoft SQL Server

keyConnectorSettings__database__provider=sqlserver
keyConnectorSettings__database__sqlServerConnectionString={ConnectionString}

PostgreSQL

keyConnectorSettings__database__provider=postgresql
keyConnectorSettings__database__postgreSqlConnectionString={ConnectionString}

MySQL/MariaDB

keyConnectorSettings__database__provider=mysql
keyConnectorSettings__database__mySqlConnectionString={ConnectionString}

SQLite

keyConnectorSettings__database__provider=sqlite
keyConnectorSettings__database__sqliteConnectionString={ConnectionString}

MongoDB

keyConnectorSettings__database__provider=mongo
keyConnectorSettings__database__mongoConnectionString={ConnectionString}
keyConnectorSettings__database__mongoDatabaseName={DatabaseName}

RSA Key

The Bitwarden Key Connector uses a RSA key pair to protect user keys at rest. The RSA key pair should be a minimum of 2048 bits in length.

You must configure how the Bitwarden Key Connector accesses and utilizes your RSA key pair.

Certificate

An X509 certificate that contains the RSA key pair.

keyConnectorSettings__rsaKey__provider=certificate

See additional certificate configuration options below.

Azure Key Vault

You will need to create an Azure Active Directory application that has access to read from the associated Key Vault.

keyConnectorSettings__rsaKey__provider=azurekv
keyConnectorSettings__rsaKey__azureKeyvaultUri={URI}
keyConnectorSettings__rsaKey__azureKeyvaultKeyName={KeyName}
keyConnectorSettings__rsaKey__azureKeyvaultAdTenantId={ActiveDirectoryTenantId}
keyConnectorSettings__rsaKey__azureKeyvaultAdAppId={ActiveDirectoryAppId}
keyConnectorSettings__rsaKey__azureKeyvaultAdSecret={ActiveDirectorySecret}

Google Cloud Key Management

keyConnectorSettings__rsaKey__provider=gcpkms
keyConnectorSettings__rsaKey__googleCloudProjectId={ProjectId}
keyConnectorSettings__rsaKey__googleCloudLocationId={LocationId}
keyConnectorSettings__rsaKey__googleCloudKeyringId={KeyringId}
keyConnectorSettings__rsaKey__googleCloudKeyId={KeyId}
keyConnectorSettings__rsaKey__googleCloudKeyVersionId={KeyVersionId}

AWS Key Management Service

keyConnectorSettings__rsaKey__provider=awskms
keyConnectorSettings__rsaKey__awsAccessKeyId={AccessKeyId}
keyConnectorSettings__rsaKey__awsAccessKeySecret={AccessKeySecret}
keyConnectorSettings__rsaKey__awsRegion={RegionName}
keyConnectorSettings__rsaKey__awsKeyId={KeyId}

PKCS11

Use a physical HSM device with the PKCS11 provider.

keyConnectorSettings__rsaKey__provider=pkcs11
# Available providers: yubihsm, opensc
keyConnectorSettings__rsaKey__pkcs11Provider={Provider}
keyConnectorSettings__rsaKey__pkcs11SlotTokenSerialNumber={TokenSerialNumber}
# Available user types: user, so, context_specific
keyConnectorSettings__rsaKey__pkcs11LoginUserType={LoginUserType}
keyConnectorSettings__rsaKey__pkcs11LoginPin={LoginPIN}

# Locate the private key on the device via label *or* ID.
keyConnectorSettings__rsaKey__pkcs11PrivateKeyLabel={PrivateKeyLabel}
keyConnectorSettings__rsaKey__pkcs11PrivateKeyId={PrivateKeyId}

When using the PKCS11 provider to store your private key on an HSM device, the associated public key must be made available and configured as a certificate (see below).

Certificate

The RSA key pair can be provided via certificate configuration. The certificate should be made available as a PKCS12 .pfx file. Example:

openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout bwkc.key
  -out bwkc.crt -subj "/CN=Bitwarden Key Connector" -days 36500

openssl pkcs12 -export -out ./bwkc.pfx -inkey bwkc.key
  -in bwkc.crt -passout pass:{Password}

If using the PKCS11 RSA key provider, you will need to make a public key PKCS12 certificate available.

Filesystem (default)

keyConnectorSettings__certificate__provider=filesystem
keyConnectorSettings__certificate__filesystemPath={Path}
keyConnectorSettings__certificate__filesystemPassword={Password}

By default, the application looks for a certificate at the follow path: /etc/bitwarden/key.pfx.

OS Certificate Store

keyConnectorSettings__certificate__provider=store
keyConnectorSettings__certificate__storeThumbprint={Thumbprint}

Azure Blob Storage

keyConnectorSettings__certificate__provider=azurestorage
keyConnectorSettings__certificate__azureStorageConnectionString={ConnectionString}
keyConnectorSettings__certificate__azureStorageContainer={Container}
keyConnectorSettings__certificate__azureStorageFileName={FileName}
keyConnectorSettings__certificate__azureStorageFilePassword={FilePassword}

Azure Key Vault

You will need to create an Azure Active Directory application that has access to read from the associated Key Vault.

keyConnectorSettings__certificate__provider=azurekv
keyConnectorSettings__certificate__azureKeyvaultUri={URI}
keyConnectorSettings__certificate__azureKeyvaultCertificateName={CertificateName}
keyConnectorSettings__certificate__azureKeyvaultAdTenantId={ActiveDirectoryTenantId}
keyConnectorSettings__certificate__azureKeyvaultAdAppId={ActiveDirectoryAppId}
keyConnectorSettings__certificate__azureKeyvaultAdSecret={ActiveDirectorySecret}

HashiCorp Vault

keyConnectorSettings__certificate__provider=vault
keyConnectorSettings__certificate__vaultServerUri={ServerURI}
keyConnectorSettings__certificate__vaultToken={Token}
keyConnectorSettings__certificate__vaultSecretMountPoint={SecretMountPoint}
keyConnectorSettings__certificate__vaultSecretPath={SecretPath}
keyConnectorSettings__certificate__vaultSecretDataKey={SecretDataKey}
keyConnectorSettings__certificate__vaultSecretFilePassword={SecretFilePassword}

Developer Documentation

Please refer to the Key Connector section of the Contributing Documentation for build instructions, recommended tooling, code style tips, and lots of other great information to get you started.