FlowCrypt Email Key Manager

version: 2024-03

Prerequisites
You’re familiar with all the Enterprise Server services.

Enterprise customers may deploy the Email Key Manager (EKM) on their own premises to centrally manage the private and public keys of their users. This central management enables user setup automation, reduces the chance of user error, and increases usability.

The database-level encryption isn’t required as we encrypt private keys with AES-256 individually before storing them in the database and decrypting them upon retrieval. The database encryption key for this encrypt/decrypt is retrieved over KMIP or PKCS#11 from your existing Hardware Security Module (HSM) or Key Management System (KMS).

The EKM REST JSON API is accessed by FlowCrypt Email Encryption client apps, internally within your network.

Requirements

You need to ensure all the requirements described in the Enterprise Server Deployment Requirements guide, plus the following:

Type	Requirement
Database	PostgreSQL or CockroachDB for production. H2 for testing & evaluation. Optionally protected by KMIP or PKCS#11.
Network	EKM must be accessible on an internal URL from client devices, with a TLS certificate trusted by the client. The instance shouldn’t be accessible from the public internet, but it needs limited external access to the internet to fetch Google JWK for user authentication.

Distribution and deployment

FlowCrypt Email Key Manager is distributed as a zip file containing:

Filename	Description
`flowcrypt-email-key-manager.jar`	Runnable Java JAR
`flowcrypt-email-key-manager.properties`	Default config for EKM
`flowcrypt-email-key-manager-docs.md`	Documentation
`LICENSE.txt`	License file (proprietary software)

For deployment, install OpenJDK 17, unpack all files in a folder, and edit the properties file before running.

The EKM is meant to serve keys internally on your LAN. To serve public keys externally, you can use the FlowCrypt WKD Server, deployed as a separate service.

Running the application

Start the EKM by running the java -jar flowcrypt-email-key-manager.jar command.

The default command is to start the server at the localhost:32356 address. Other commands:

Command	Description
`--version`	Print application version.
`--help`	Print application help.
`--gen-jwk=service-pushsync`	Generate JWK for authentication between WKD and EKM. See FlowCrypt WKD Server
`--create-db-encryption-key`	Create an encryption key for the database and either print it out or store it in KMIP. See the KMIP configuration guide.
`--test-store-connection`	Test the connection to your store, such as PostgreSQL, or your HSM/KMS.
`--gen-private-keys=<file.csv>`	Pre-generate private keys for your users. Supply a CSV file with one user per line of the following format: `john.doe@corp.co,John Doe`. The file must be in UTF-8 encoding if Non-ASCII characters are present.

Command line options:

Argument	Default	Description
`--config=<cfg.properties>`	`flowcrypt-email-key-manager.properties`	Config file path or an HTTP(S) URL

Configuration

The sample configuration file appropriate for your software version will come distributed along with the jar file. It consists of several sections: Common, Auth, Store, Store Encryption, Keygen, Logger, and ACL. Each of these sections is described either in one of the following links or on this page below:

Configuration: Auth and ACL

Service authentication properties specific to EKM:

See Authentication and ACL for users and admins.

Property	Description
`auth.service.orchestrator.enabled`	Set to `true` or `false` to enable/disable the use of the orchestrator service from EAP to EKM.
`auth.service.orchestrator.verification.key`	EKM orchestrator verification key. If enabled, generate this using the EAP `--gen-jwk service-orchestrator` command.
`auth.service.push-sync.signing.key`	See WKD Server.

What’s next? Navigate to the Enterprise Admin Panel (EAP) UI page to learn how you can use Enterprise Server functionality, and visit the Technical Configurations section to become familiar with the different configuration options for Enterprise Server services.

Sample config file

# https://flowcrypt.com/docs/technical/email-key-manager/latest/technical-overview.html

######################################################
################ GENERAL - EKM #######################
######################################################

org.id=evaluation.org

api.hostname=0.0.0.0
api.port=32356
api.accept.hosts=localhost:32356
api.https.enabled=false
#api.https.key.file=flowcrypt-ekm-https-cert.p12
#api.https.key.password=password
api.cors.origins=chrome-extension://bnjglocicdkmhmoohhfkfkbbkejdhdgc,chrome-extension://mefaeofbcclcomcaicpalminolcngokk,moz-extension://39553fca-76d4-4791-bf00-b4dfede6fd45
api.error.format=id_only
api.accept.client.keypairs=true
api.openapi.enabled=false

# For WKD Push Sync (optional)
#wkd.url=

# For "--gen-private-keys". The possible values are: curve25519 | rsa4096 | rsa3072 | rsa2048.
keygen.algo=curve25519
keygen.key.pair.expiration.days=365
keygen.rotation.set.superseded.key.pair.expiration.days=60

# The Truststore is optional and can be useful when you want to override the default JRE Truststore in the following cases:
#   - You are using WKD Push Sync and WKD uses an HTTPS cert signed by an internal CA.
#   - You wish to verify a KMIP server.
# This Truststore file then has to contain means to verify these certificates (e.g. a root CA cert).
#truststore.file=truststore-to-verify-kmip-server.p12
#truststore.password=password
#truststore.include.default=true

################################################
############## AUTHENTICATION ##################
################################################

# Set to true/false to enable/disable the use of the Orchestrator service from EAP to EKM.
auth.service.orchestrator.enabled=
# If enabled, you should generate this using the EAP "--gen-jwk service-orchestrator" command.
auth.service.orchestrator.verification.key=

# Do not change this end-user auth. It must correspond to the authentication used by the FlowCrypt client software.
auth.enduser.type=OidcAuthenticator
auth.enduser.idps=google
auth.enduser.google.issuer=https://accounts.google.com
auth.enduser.google.jwks=https://www.googleapis.com/oauth2/v3/certs

# Copy this from the EAP "auth.admin" section.
auth.admin.type=OidcAuthenticator
auth.admin.idps=default
auth.admin.default.issuer=
#auth.admin.default.jwks=
auth.admin.default.audience=

# For WKD Push Sync (optional). Generate a pair using the "--gen-jwk=service-pushsync" command.
#auth.service.pushsync.signing.key=

################################################
##################### ACL ######################
################################################

acl.type=SimpleAcl
# The email addresses of administrator accounts, comma-separated.
acl.simple.admins=

###########################################################
################### DATABASE STORE ########################
###########################################################

### PostgreSQL - recommended ###
store.type=DatabaseStore
store.database.vendor=postgres
store.postgres.host=localhost
store.postgres.port=5432
store.postgres.database=db_ekm
store.postgres.schema=public
store.postgres.update.schema=true
store.postgres.username=user_ekm
store.postgres.connections=10
store.postgres.connection.timeout.seconds=5
store.postgres.connection.idletimeout.seconds=600
store.postgres.connection.maxlifetime.seconds=1740
#store.postgres.auth.method=password|cert
#store.postgres.auth.password=your_postgres_pwd
#store.postgres.auth.cert=/path/to/client.crt
#store.postgres.auth.key=/path/to/client.key
#store.postgres.auth.ca=/path/to/ca.crt

### CockroachDB - recommended ###
#store.type=DatabaseStore
#store.database.vendor=cockroach
#store.cockroach.host=localhost
#store.cockroach.port=26257
#store.cockroach.database=db_ekm
#store.cockroach.schema=ekm
#store.cockroach.update.schema=true
#store.cockroach.username=user_ekm
#store.cockroach.connections=10
#store.cockroach.connection.timeout.seconds=5
#store.cockroach.connection.idletimeout.seconds=600
#store.cockroach.connection.maxlifetime.seconds=1740
#store.cockroach.auth.method=password|cert
#store.cockroach.auth.password=your_cockroachdb_pwd
#store.cockroach.auth.cert=/path/to/client.crt
#store.cockroach.auth.key=/path/to/client.key
#store.cockroach.auth.ca=/path/to/ca.crt

### H2 database - recommended ###
#store.type=DatabaseStore
#store.database.vendor=h2
#store.h2.database.path=./data/ekm_h2
#store.h2.connections=10
#store.h2.entire.database.encrypted=false
#store.h2.entire.database.encryption.password=
#store.h2.update.schema=true

###########################################################
################### STORE ENCRYPTION ######################
###########################################################

store.encryption.enable=true
# First, set the source below:
store.encryption.key.source=properties|stdin|kmip|pkcs11
# After, run "--create-db-encryption-key".

# Uncomment if store.encryption.key.source=properties.
# The DB encryption key set in the properties file directly.
#store.encryption.key.value=

# Uncomment if store.encryption.key.source=kmip.
# The DB encryption key retrieved over the KMIP protocol (e.g. Gemalto Safenet KeySecure or any compatible KMS).
# Remember to also set "truststore.file" above if the KMIP server uses certs with custom CA.
#store.kmip.hostname=localhost
#store.kmip.port=5696
#store.kmip.key.file=localhost.p12
#store.kmip.key.password=password
# The following identifier returned by "--create-db-encryption-key".
#store.kmip.encryption.key.identifier=
# This property is only used when creating a DB encryption key in KMIP and is optional.
# The default value is "flowcrypt-email-km-db-encryption-key".
#store.kmip.encryption.key.name=flowcrypt-email-km-db-encryption-key

# Uncomment if store.encryption.key.source=pkcs11.
# The DB encryption key retrieved over the PKCS#11 protocol (Fortanix SDKMS, Equinix SmartKey, or any compatible HSM).
#store.pkcs11.module=./vendor-pkcs11.so
#store.pkcs11.pin=file://vendor-pkcs11.cfg

################################################
################### LOGGER #####################
################################################

# A comma-separated list. The possible values are: StdoutLogger | FileLogger | StackdriverLogger | SplunkHttpLogger.
logger.types=StdoutLogger
# The possible values are: trace | debug | info | warn | error.
logger.default.level=info
#logger.stdout.include.datetime=true
#logger.file.folder=/var/logs
#logger.file.history.size=14
#logger.file.history.compression=false
#logger.file.include.datetime=true
#logger.stackdriver.credentials.file=/etc/google/auth/application_default_credentials.json
#logger.splunk.url=https://splunk-instance:8088
#logger.splunk.token=327bfa46-...
#logger.splunk.disable.certificate.validation=true