revomatico/keywhiz repository overview

⁠Keywhiz

Keywhiz is a system for distributing and managing secrets. For more information, see the website⁠.

Our Protecting infrastructure secrets with Keywhiz⁠ blog post is worth reading, as it provides some useful context.

⁠Develop

See CONTRIBUTING⁠ for details on submitting patches.

Build keywhiz:

# Build keywhiz for H2
mvn install -P h2

# Build keywhiz for MySQL
mvn install -P mysql

Run Keywhiz:

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

Useful commands to get started are migrate, add-user and server. Use with --help for a list of all available commands. Use with [COMMAND] --help to get help on a particular command.

For example, to run Keywhiz with an H2 database in development mode:

SERVER_JAR="server/target/keywhiz-server-*-shaded.jar"
KEYWHIZ_CONFIG="server/target/classes/keywhiz-development.yaml.h2"

# Initialize dev database (H2)
java -jar $SERVER_JAR migrate $KEYWHIZ_CONFIG

# Add an administrative user
java -jar $SERVER_JAR add-user $KEYWHIZ_CONFIG

# Run server
java -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 file
KEYWHIZ_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
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 uses jOOQ⁠ 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 recommend IntelliJ IDEA⁠ for development.

⁠Clients & API

Swagger API documentation⁠

Client implementations maintained by Square:

• Keywhiz-FS⁠: a FUSE driver for exposing Keywhiz secrets as a filesystem. In maintenance mode.
• Keysync⁠: next-generation replacement for Keywhiz-FS based on tmpfs instead of FUSE.

⁠Docker

We ship a Dockerfile⁠ for building a Docker container for keywhiz. Please see the Dockerfile for extra instructions.

⁠License

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