@ -1,23 +1,23 @@
@@ -1,23 +1,23 @@
< a href = "https://hub.docker.com/r/bitwarden/crypto-agent " target = "_blank" >
< img src = "https://img.shields.io/docker/pulls/bitwarden/crypto-agent .svg" alt = "DockerHub" / >
< a href = "https://hub.docker.com/r/bitwarden/key-connector " target = "_blank" >
< img src = "https://img.shields.io/docker/pulls/bitwarden/key-connector .svg" alt = "DockerHub" / >
< / a >
# Bitwarden Crypto Agent
# Bitwarden Key Connector
The Bitwarden Crypto Agent is a self-hosted web application that stores and provides cryptographic keys to Bitwarden
The Bitwarden Key Connector is a self-hosted web application that stores and provides cryptographic keys to Bitwarden
clients.
The Crypto Agent project is written in C# using .NET Core with ASP.NET Core. The codebase can be developed, built, run,
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 Crypto Agent can be deployed using the pre-built docker container available on
[DockerHub ](https://hub.docker.com/r/bitwarden/crypto-agent ).
The Bitwarden Key Connector can be deployed using the pre-built docker container available on
[DockerHub ](https://hub.docker.com/r/bitwarden/key-connector ).
## Configuration
A variety of configuration options are available for the Bitwarden Crypto Agent .
A variety of configuration options are available for the Bitwarden Key Connector .
### Bitwarden Server
@ -25,8 +25,8 @@ By default, the Bitwarden server configuration points to the Bitwarden Cloud end
@@ -25,8 +25,8 @@ By default, the Bitwarden server configuration points to the Bitwarden Cloud end
self-hosted Bitwarden installation, you will need to configure the web vault and identity server endpoints.
```
cryptoAgent Settings__webVaultUri=https://bitwarden.company.com
cryptoAgent Settings__identityServerUri=https://bitwarden.company.com/identity/
keyConnector Settings__webVaultUri=https://bitwarden.company.com
keyConnector Settings__identityServerUri=https://bitwarden.company.com/identity/
```
### Database
@ -37,8 +37,8 @@ from one database provider to another is not supported at this time.
@@ -37,8 +37,8 @@ from one database provider to another is not supported at this time.
**JSON File (default)**
```
cryptoAgent Settings__database__provider=json
cryptoAgent Settings__database__jsonFilePath={FilePath}
keyConnector Settings__database__provider=json
keyConnector Settings__database__jsonFilePath={FilePath}
```
By default, the application stores the JSON file at the follow path: `/etc/bitwarden/data.json` .
@ -46,52 +46,52 @@ By default, the application stores the JSON file at the follow path: `/etc/bitwa
@@ -46,52 +46,52 @@ By default, the application stores the JSON file at the follow path: `/etc/bitwa
**Microsoft SQL Server**
```
cryptoAgent Settings__database__provider=sqlserver
cryptoAgent Settings__database__sqlServerConnectionString={ConnectionString}
keyConnector Settings__database__provider=sqlserver
keyConnector Settings__database__sqlServerConnectionString={ConnectionString}
```
**PostgreSQL**
```
cryptoAgent Settings__database__provider=postgresql
cryptoAgent Settings__database__postgreSqlConnectionString={ConnectionString}
keyConnector Settings__database__provider=postgresql
keyConnector Settings__database__postgreSqlConnectionString={ConnectionString}
```
**MySQL/MariaDB**
```
cryptoAgent Settings__database__provider=mysql
cryptoAgent Settings__database__mySqlConnectionString={ConnectionString}
keyConnector Settings__database__provider=mysql
keyConnector Settings__database__mySqlConnectionString={ConnectionString}
```
**SQLite**
```
cryptoAgent Settings__database__provider=sqlite
cryptoAgent Settings__database__sqliteConnectionString={ConnectionString}
keyConnector Settings__database__provider=sqlite
keyConnector Settings__database__sqliteConnectionString={ConnectionString}
```
**MongoDB**
```
cryptoAgent Settings__database__provider=mongo
cryptoAgent Settings__database__mongoConnectionString={ConnectionString}
cryptoAgent Settings__database__mongoDatabaseName={DatabaseName}
keyConnector Settings__database__provider=mongo
keyConnector Settings__database__mongoConnectionString={ConnectionString}
keyConnector Settings__database__mongoDatabaseName={DatabaseName}
```
### RSA Key
The Bitwarden Crypto Agent uses a RSA key pair to protect user keys at rest. The RSA key pair should be a minimum of
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 Crypto Agent accesses and utilizes your RSA key pair.
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.
```
cryptoAgent Settings__rsaKey__provider=certificate
keyConnector Settings__rsaKey__provider=certificate
```
*See additional certificate configuration options below.*
@ -101,33 +101,33 @@ cryptoAgentSettings__rsaKey__provider=certificate
@@ -101,33 +101,33 @@ cryptoAgentSettings__rsaKey__provider=certificate
You will need to create an Azure Active Directory application that has access to read from the associated Key Vault.
```
cryptoAgent Settings__rsaKey__provider=azurekv
cryptoAgent Settings__rsaKey__azureKeyvaultUri={URI}
cryptoAgent Settings__rsaKey__azureKeyvaultKeyName={KeyName}
cryptoAgent Settings__rsaKey__azureKeyvaultAdTenantId={ActiveDirectoryTenantId}
cryptoAgent Settings__rsaKey__azureKeyvaultAdAppId={ActiveDirectoryAppId}
cryptoAgent Settings__rsaKey__azureKeyvaultAdSecret={ActiveDirectorySecret}
keyConnector Settings__rsaKey__provider=azurekv
keyConnector Settings__rsaKey__azureKeyvaultUri={URI}
keyConnector Settings__rsaKey__azureKeyvaultKeyName={KeyName}
keyConnector Settings__rsaKey__azureKeyvaultAdTenantId={ActiveDirectoryTenantId}
keyConnector Settings__rsaKey__azureKeyvaultAdAppId={ActiveDirectoryAppId}
keyConnector Settings__rsaKey__azureKeyvaultAdSecret={ActiveDirectorySecret}
```
**Google Cloud Key Management**
```
cryptoAgent Settings__rsaKey__provider=gcpkms
cryptoAgent Settings__rsaKey__googleCloudProjectId={ProjectId}
cryptoAgent Settings__rsaKey__googleCloudLocationId={LocationId}
cryptoAgent Settings__rsaKey__googleCloudKeyringId={KeyringId}
cryptoAgent Settings__rsaKey__googleCloudKeyId={KeyId}
cryptoAgent Settings__rsaKey__googleCloudKeyVersionId={KeyVersionId}
keyConnector Settings__rsaKey__provider=gcpkms
keyConnector Settings__rsaKey__googleCloudProjectId={ProjectId}
keyConnector Settings__rsaKey__googleCloudLocationId={LocationId}
keyConnector Settings__rsaKey__googleCloudKeyringId={KeyringId}
keyConnector Settings__rsaKey__googleCloudKeyId={KeyId}
keyConnector Settings__rsaKey__googleCloudKeyVersionId={KeyVersionId}
```
**AWS Key Management Service**
```
cryptoAgent Settings__rsaKey__provider=awskms
cryptoAgent Settings__rsaKey__awsAccessKeyId={AccessKeyId}
cryptoAgent Settings__rsaKey__awsAccessKeySecret={AccessKeySecret}
cryptoAgent Settings__rsaKey__awsRegion={RegionName}
cryptoAgent Settings__rsaKey__awsKeyId={KeyId}
keyConnector Settings__rsaKey__provider=awskms
keyConnector Settings__rsaKey__awsAccessKeyId={AccessKeyId}
keyConnector Settings__rsaKey__awsAccessKeySecret={AccessKeySecret}
keyConnector Settings__rsaKey__awsRegion={RegionName}
keyConnector Settings__rsaKey__awsKeyId={KeyId}
```
**PKCS11**
@ -135,17 +135,17 @@ cryptoAgentSettings__rsaKey__awsKeyId={KeyId}
@@ -135,17 +135,17 @@ cryptoAgentSettings__rsaKey__awsKeyId={KeyId}
Use a physical HSM device with the PKCS11 provider.
```
cryptoAgent Settings__rsaKey__provider=pkcs11
keyConnector Settings__rsaKey__provider=pkcs11
# Available providers: yubihsm, opensc
cryptoAgent Settings__rsaKey__pkcs11Provider={Provider}
cryptoAgent Settings__rsaKey__pkcs11SlotTokenSerialNumber={TokenSerialNumber}
keyConnector Settings__rsaKey__pkcs11Provider={Provider}
keyConnector Settings__rsaKey__pkcs11SlotTokenSerialNumber={TokenSerialNumber}
# Available user types: user, so, context_specific
cryptoAgent Settings__rsaKey__pkcs11LoginUserType={LoginUserType}
cryptoAgent Settings__rsaKey__pkcs11LoginPin={LoginPIN}
keyConnector Settings__rsaKey__pkcs11LoginUserType={LoginUserType}
keyConnector Settings__rsaKey__pkcs11LoginPin={LoginPIN}
# Locate the private key on the device via label *or* ID.
cryptoAgent Settings__rsaKey__pkcs11PrivateKeyLabel={PrivateKeyLabel}
cryptoAgent Settings__rsaKey__pkcs11PrivateKeyId={PrivateKeyId}
keyConnector Settings__rsaKey__pkcs11PrivateKeyLabel={PrivateKeyLabel}
keyConnector Settings__rsaKey__pkcs11PrivateKeyId={PrivateKeyId}
```
*When using the PKCS11 provider to store your private key on an HSM device, the associated public key must be made
@ -169,9 +169,9 @@ If using the PKCS11 RSA key provider, you will need to make a public key PKCS12
@@ -169,9 +169,9 @@ If using the PKCS11 RSA key provider, you will need to make a public key PKCS12
**Filesystem (default)**
```
cryptoAgent Settings__certificate__provider=filesystem
cryptoAgent Settings__certificate__filesystemPath={Path}
cryptoAgent Settings__certificate__filesystemPassword={Password}
keyConnector Settings__certificate__provider=filesystem
keyConnector Settings__certificate__filesystemPath={Path}
keyConnector Settings__certificate__filesystemPassword={Password}
```
By default, the application looks for a certificate at the follow path: `/etc/bitwarden/key.pfx` .
@ -179,18 +179,18 @@ By default, the application looks for a certificate at the follow path: `/etc/bi
@@ -179,18 +179,18 @@ By default, the application looks for a certificate at the follow path: `/etc/bi
**OS Certificate Store**
```
cryptoAgent Settings__certificate__provider=store
cryptoAgent Settings__certificate__storeThumbprint={Thumbprint}
keyConnector Settings__certificate__provider=store
keyConnector Settings__certificate__storeThumbprint={Thumbprint}
```
**Azure Blob Storage**
```
cryptoAgent Settings__certificate__provider=azurestorage
cryptoAgent Settings__certificate__azureStorageConnectionString={ConnectionString}
cryptoAgent Settings__certificate__azureStorageContainer={Container}
cryptoAgent Settings__certificate__azureStorageFileName={FileName}
cryptoAgent Settings__certificate__azureStorageFilePassword={FilePassword}
keyConnector Settings__certificate__provider=azurestorage
keyConnector Settings__certificate__azureStorageConnectionString={ConnectionString}
keyConnector Settings__certificate__azureStorageContainer={Container}
keyConnector Settings__certificate__azureStorageFileName={FileName}
keyConnector Settings__certificate__azureStorageFilePassword={FilePassword}
```
**Azure Key Vault**
@ -198,24 +198,24 @@ cryptoAgentSettings__certificate__azureStorageFilePassword={FilePassword}
@@ -198,24 +198,24 @@ cryptoAgentSettings__certificate__azureStorageFilePassword={FilePassword}
You will need to create an Azure Active Directory application that has access to read from the associated Key Vault.
```
cryptoAgent Settings__certificate__provider=azurekv
cryptoAgent Settings__certificate__azureKeyvaultUri={URI}
cryptoAgent Settings__certificate__azureKeyvaultCertificateName={CertificateName}
cryptoAgent Settings__certificate__azureKeyvaultAdTenantId={ActiveDirectoryTenantId}
cryptoAgent Settings__certificate__azureKeyvaultAdAppId={ActiveDirectoryAppId}
cryptoAgent Settings__certificate__azureKeyvaultAdSecret={ActiveDirectorySecret}
keyConnector Settings__certificate__provider=azurekv
keyConnector Settings__certificate__azureKeyvaultUri={URI}
keyConnector Settings__certificate__azureKeyvaultCertificateName={CertificateName}
keyConnector Settings__certificate__azureKeyvaultAdTenantId={ActiveDirectoryTenantId}
keyConnector Settings__certificate__azureKeyvaultAdAppId={ActiveDirectoryAppId}
keyConnector Settings__certificate__azureKeyvaultAdSecret={ActiveDirectorySecret}
```
**HashiCorp Vault**
```
cryptoAgent Settings__certificate__provider=vault
cryptoAgent Settings__certificate__vaultServerUri={ServerURI}
cryptoAgent Settings__certificate__vaultToken={Token}
cryptoAgent Settings__certificate__vaultSecretMountPoint={SecretMountPoint}
cryptoAgent Settings__certificate__vaultSecretPath={SecretPath}
cryptoAgent Settings__certificate__vaultSecretDataKey={SecretDataKey}
cryptoAgent Settings__certificate__vaultSecretFilePassword={SecretFilePassword}
keyConnector Settings__certificate__provider=vault
keyConnector Settings__certificate__vaultServerUri={ServerURI}
keyConnector Settings__certificate__vaultToken={Token}
keyConnector Settings__certificate__vaultSecretMountPoint={SecretMountPoint}
keyConnector Settings__certificate__vaultSecretPath={SecretPath}
keyConnector Settings__certificate__vaultSecretDataKey={SecretDataKey}
keyConnector Settings__certificate__vaultSecretFilePassword={SecretFilePassword}
```
## Build/Run
@ -239,7 +239,7 @@ MacOS requires updated SSL libraries, otherwise you will receive the error "No u
@@ -239,7 +239,7 @@ MacOS requires updated SSL libraries, otherwise you will receive the error "No u
```bash
echo 'DYLD_LIBRARY_PATH="/usr/local/opt/openssl@1.1/lib"' >> ~/.zshrc
```
4. If you are running the Crypto Agent from a terminal, restart your terminal to make sure the updated `.zshrc` settings are applied
4. If you are running the Key Connector from a terminal, restart your terminal to make sure the updated `.zshrc` settings are applied
### Recommended Development Tooling