Docs Menu

CockroachDB Setup

Prerequisites
You’re familiar with the Email Key Manager, External Service, and Web Key Directory services.

This is an alternative database store replacement of Postgres for Email Key Manager (EKM), External Service (FES), and Web Key Directory (WKD).

CockroachDB database configurations

The example in the next section is for the Email Key Manager service. Change appropriately when creating the database store for other services. For Web Key Directory, db_ekm becomes db_wkd, and so on. This is a recommended naming convention, but you’re free to choose your own.

Typical configurations

Having a user with all the privileges is the recommended option for most deployment cases. CockroachDB super user is required to perform the following steps:

  1. Create the database with the CREATE DATABASE db_ekm; command.

  2. Create the user. When you use a TLS Client certificate-based authentication with the CREATE USER user_ekm; command. This is recommended for production deployments. Alternatively, for testing and evaluation, you may use password-based authentication: CREATE USER user_ekm PASSWORD '!CHANGE THIS!';.

  3. Adding database privileges to this user:

     GRANT SELECT, INSERT, DELETE, UPDATE, CREATE, DROP ON DATABASE db_ekm TO user_ekm;
 USE db_ekm;
 CREATE SCHEMA ekm;
 GRANT ALL ON SCHEMA ekm TO user_ekm;

EKM configurations

In the production setup process, you should allow the service to connect to the CockroachDB database for keys and metadata storage. Sensitive data stored in this database is further encrypted using the store encryption key feature.

Property Description
store.type Specifies we’re persisting into a database.
Example: DatabaseStore
store.database.vendor The database vendor.
Example: cockroach
store.cockroach.host A comma-separated list of CockroachDB database hostname(s) or IP address(es) with a fail-over mechanism. The connection driver will attempt once to connect to each of hosts in order until the connection succeeds. If none of the connections succeed, a standard connection exception will be thrown.
Example: 10.0.0.5 (single host) or 127.0.0.1,10.0.0.5 (multiple hosts, the port number must be the same for all hosts).
store.cockroach.port CockroachDB database port number.
Example: 5432
store.cockroach.database CockroachDB database name. You can choose any but the recommended names are db_ekm or db_wkd.
Example: db_ekm
store.cockroach.schema CockroachDB schema name. You can choose any but the recommended names are ekm or wkd.
Example: ekm
store.cockroach.connections
optional 		The maximum connection size that the database pool is allowed to reach. We recommend having 3 connections per CPU core.
Default value: 10
Example: 12
store.cockroach.connection.timeout.seconds
optional 		The maximum number of seconds that Email Key Manager will wait for a connection from the database pool
Default value: 5
Example: 10
store.cockroach.connection.idletimeout.seconds
optional 		The maximum number of seconds that a connection is allowed to be idle in the pool.
Default value: 600 (10 minutes).
Example: 600
store.cockroach.connection.maxlifetime.seconds
optional 		The maximum number of seconds of a connection in the pool. It should be slightly shorter than any database or infrastructure-imposed connection time limit.
Default value: 1740 (29 minutes)
Example: 1740
store.cockroach.update.schema
optional 		If schema should be created or updated when the service starts the default value is true.
Example: true
store.cockroach.username CockroachDB database username. You can use any. The recommended names are user_ekm or user_wkd.
Example: user_ekm
store.cockroach.auth.method CockroachDB user authentication mechanism, either password or cert for SSL-based authentication.
Example: password
store.cockroach.auth.password (for store.cockroach.auth.method=password) CockroachDB database user password.
Example: your_cockroachdb_pwd
store.cockroach.auth.cert (for store.cockroach.auth.method=cert) Path to the client SSL certificate in the PKCS#8 format.
Example: /path/to/client.crt
store.cockroach.auth.key (for store.cockroach.auth.method=cert) Path to the client SSL key in the PKCS#8 format.
Example: /path/to/client.key
store.cockroach.auth.ca (for store.cockroach.auth.method=cert) Path to a CA certificate in the PKCS#8 format that will be used to verify the identity of the CockroachDB database server.
Example: /path/to/ca.crt

Database store encryption (EKM only)

See the DB Store Encryption guide to enable and configure database store encryption for sensitive information (e.g. private keys).

Test connection

To test whether the service can communicate with the configured database, run:

java -jar flowcrypt-<service-name>.jar --test-store-connection

This command will connect to the data store and issue one search command to test that the connection between EKM and the database is well configured.

The successful output is:

INFO  com.flowcrypt.utils.Reflection - Registering DatabaseStore as Store implementation
INFO  c.f.keymanager.TestStoreConnection - initiating test
INFO  c.f.keymanager.TestStoreConnection - store session started successfully
INFO  c.f.keymanager.TestStoreConnection - testing store search command
INFO  c.f.keymanager.TestStoreConnection - round trip latency: 8ms
INFO  c.f.keymanager.TestStoreConnection - closing session
INFO  c.f.keymanager.TestStoreConnection - success
Content © FlowCrypt a.s.
Layout from Cockroach Labs,CC Attr 4.0, edited