https://github.com/bitwarden/key-connector
An agent that stores and provides cryptographic keys to Bitwarden clients.
https://github.com/bitwarden/key-connector
Last synced: 5 months ago
JSON representation
An agent that stores and provides cryptographic keys to Bitwarden clients.
- Host: GitHub
- URL: https://github.com/bitwarden/key-connector
- Owner: bitwarden
- License: other
- Created: 2021-08-10T18:39:27.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-13T18:32:31.000Z (about 1 year ago)
- Last Synced: 2024-12-16T13:35:07.996Z (about 1 year ago)
- Language: C#
- Homepage:
- Size: 291 KB
- Stars: 34
- Watchers: 20
- Forks: 27
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 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
[ghcr.io](https://github.com/bitwarden/self-host/pkgs/container/key-connector).
## 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](https://contributing.bitwarden.com/getting-started/enterprise/key-connector) of the [Contributing Documentation](https://contributing.bitwarden.com/) for build instructions, recommended tooling, code style tips, and lots of other great information to get you started.