FlowCrypt Web Key Directory Server

version: 2024-02

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

Enterprise customers who use Email Key Manager (EKM) to manage their private keys typically need a way to expose matching them externally, so that senders from other organizations may send them encrypted messages easily.

The WKD Protocol

The Web Key Directory (WKD) is a method of retrieving public keys with a high level of trust because these public keys are retrieved directly from the domain where the recipient’s email account is hosted.

Many OpenPGP clients, including FlowCrypt, support looking up over this protocol.

Our WKD server only implements the Web Key Discovery mechanisms described in section 3 of the OpenPGP Web Key Directory draft. We don’t implement the Web Key Directory Update Protocol described in section 4. Instead, the FlowCrypt EKM synchronizes public keys to the WKD, which serves them publicly in a way that email clients can understand.

Distribution

FlowCrypt WKD Server is distributed as a zip file containing:

Filename	Description
`flowcrypt-wkd-server.jar`	Runnable Java JAR
`flowcrypt-wkd-server.properties`	Default config for EKM
`flowcrypt-wkd-server-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.

Deployment

The typical setup is as follows:

Product	Deployment
FlowCrypt WKD Server	Deployed in the DMZ with public access. Serves public keys externally.
FlowCrypt EKM	Deployed in the internal network. Serves private and public keys internally.

When serving large loads, WKD should be placed behind a caching Reverse Proxy. The cache expiration can be set depending on how quickly you need newly added keys or key updates to get published. The recommended cache validity is from 1 to 60 minutes.

The WKD needs information about public keys that are available on the EKM. For this, you can choose between Pull Sync and Push Sync.

General configuration

General configuration options are:

How to run the WKD

Start the WKD by running the java -jar flowcrypt-wkd-server.jar --config=flowcrypt-wkd-server.properties command.

By default, this will start the server at the http://localhost:32953 address. You can change this and other settings in the flowcrypt-wkd-server.properties file.

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/wkd-server/latest/technical-overview.html

######################################################
################ GENERAL - WKD #######################
######################################################

org.id=evaluation.org

api.hostname=0.0.0.0
# Users need to be able to access this server over the HTTPS 443 port:
#  - When using a Reverse Proxy for SSL termination, you can leave the port below as is (or choose any port you like)
#    and have the Reverse Proxy serve users at the 443 port.
#  - When not using a Reverse Proxy, you need to set the 443 port and enable HTTPS below.
api.port=32953
api.accept.hosts=localhost:32953
api.https.enabled=false
#api.https.key.file=flowcrypt-email-key-manager.p12
#api.https.key.password=password
api.cors.origins=*
api.error.format=id_only
api.openapi.enabled=false

# This is your primary email domain. If a WKD request does not specify a domain, this domain will be used as the default.
wkd.domain=yourdomain.org

###########################################################
################# PULL SYNC PARAMETERS ####################
###########################################################

# ----------- Uncomment to use Pull Sync -----------------

# (pull) An optional Truststore to override the default JRE Truststore and verify internal SSL certs.
#truststore.file=truststore-to-verify-kmip-server.p12
#truststore.password=password
#truststore.include.default=true

# (pull) WKD Server will live-fetch public keys from your EKM instance.
#store.type=LivePullFromEkmStore
## Typically, your EKM instance will be accessible only on an internal network, while WKD server is publicly accessible.
## This URL needs to be reachable from the WKD server.
#store.ekm.url=https://ekm.yourinternaldomain.org

###########################################################
################# PUSH SYNC PARAMETERS ####################
###########################################################

# ----------- Uncomment to use Push Sync -----------------

# (push) You can configure some instances to be read-only.
#wkd.push.readonly=false

# (push) Limit IPs that can use the PUSH endpoints (IPs of EKM instances, comma-separated. Empty means ALL IPs ARE ALLOWED).
#wkd.push.source.ips=

# (push) EKM authenticates itself with a self-issued JWT that EKM verifies against authentication public key.
#auth.service.pushsync.verification.key=

# (push) EKM will push public key updates to WKD, which stores it independently in a PostgreSQL database.
#store.type=DatabaseStore
#store.database.vendor=postgres
#store.postgres.host=localhost
#store.postgres.port=5432
#store.postgres.database=db_wkd
#store.postgres.schema=public
#store.postgres.update.schema=true
#store.postgres.username=user_wkd
#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

# (push) EKM will push public key updates to WKD, which stores it independently in a CockroachDB database.
#store.type=DatabaseStore
#store.database.vendor=cockroach
#store.cockroach.host=localhost
#store.cockroach.port=26257
#store.cockroach.database=db_wkd
#store.cockroach.schema=wkd
#store.cockroach.update.schema=true
#store.cockroach.username=user_wkd
#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

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

################################################
################### 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

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

# 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=

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

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