Repository files navigation

As of 9/18/23 this project is now deprecated and no longer maintained; we recommend using HashiCorp Vault as a more robust and actively supported alternative.

Keywhiz is a system for distributing and managing secrets.For more information, see thewebsite.

OurProtecting infrastructure secrets with Keywhiz blog post is worthreading, as it provides some useful context.

Keywhiz requires Java 11 and MySQL 5.7 or higher.

SeeCONTRIBUTING for details on submitting patches.

Build Keywhiz:

mvn install

Run Keywhiz:

java -jar server/target/keywhiz-server-*-shaded.jar [COMMAND] [OPTIONS]

Useful commands to get started aremigrate,add-user andserver. Use with--help for a list of all available commands. Use with[COMMAND] --help toget help on a particular command.

For example, to run Keywhiz with a mysql database in development mode:

SERVER_JAR="server/target/keywhiz-server-*-shaded.jar"KEYWHIZ_CONFIG="server/target/classes/keywhiz-development.yaml"# Initialize dev databasejava -jar $SERVER_JAR migrate $KEYWHIZ_CONFIG# Add an administrative userjava -jar $SERVER_JAR add-user $KEYWHIZ_CONFIG# Run serverjava -jar $SERVER_JAR server $KEYWHIZ_CONFIG

To connect to a running Keywhiz instance, you will need to use the CLI.

An example helper shell script that wraps the keywhiz-cli and sets some default parameters:

#!/bin/sh# Set the path to a compiled, shaded keywhiz-cli JAR fileKEYWHIZ_CLI_JAR="/path/to/keywhiz-cli-shaded.jar"KEYWHIZ_SERVER_URL="https://$(hostname):4444"# Use these flags if you want to specify a non-standard CA trust store.# Alternatively, in development and testing specify the --devTrustStore # flag to use the default truststore (DO NOT use this in production, as# the truststore is checked into Keywhiz' code).TRUSTSTORE="-Djavax.net.ssl.trustStore=/path/to/ca-bundle.jceks"TRUSTTYPE="-Djavax.net.ssl.trustStoreType=JCEKS"java "$TRUSTSTORE" "$TRUSTTYPE" -jar "$KEYWHIZ_CLI_JAR" -U "$KEYWHIZ_SERVER_URL" "$@"

Keywhiz usesjOOQ to talk to its database.

If you made changes to the database model and want to regenerate sources:

mvn install -pl model/ -Pgenerate-jooq-sources

We recommendIntelliJ IDEA for development.

To enable auto-completion, code navigation, etc., open thekeywhiz repository in IDEA,right clickpom.xml in the repository root, and select "Add as Maven Project".

Square also maintains a Keywhiz client implementation calledKeysync.

We ship aDockerfile for building a Docker container for Keywhiz.Please see the Dockerfile for extra instructions.

Keywhiz is under the Apache 2.0 license. See theLICENSE file for details.