Development and test key material

Generating development and test key material

Development and test key material is NOT meant to be secret. They should NOT be used to protect real secrets.

This wiki page documents how development and test key material was created. Use localhost or 127.0.0.1 and they will work for you (in development or test environments).

Instructions assume you have openssl and keytool. Keytool is installed with the Java JDK (1.8.0+ required for pkcs12). Heavy use is also made of certstrap.

Although there are many formats, these instructions prefer PEM-encoded raw certificates, unencrypted raw keys, and PKCS12 keystores/truststores. PKCS12 is widely supported.

Generate a new CA

~ ./certstrap init --key-bits 2048 --years 30 --common-name "Keywhiz Test CA"

Creates out/Keywhiz Test CA.crt and out/Keywhiz Test CA.key. For Java, we also want a truststore file (out/Keywhiz_Test_CA.p12):

~ keytool -import -file 'out/Keywhiz Test CA.crt' -alias ca -storetype pkcs12 -storepass ponies -keystore out/Keywhiz_Test_CA.p12
~ cp out/Keywhiz_Test_CA.p12 dev_and_test_truststore.p12

Create client certificates

Keywhiz client certificates are expected to have a subject with CN=<client name>. There must also be a row in the clients tables to enable the client. For development seed data, some clients are already in the DB:

• 'CN=client' has access to some secrets
• 'CN=noSecretsClient' can authenticate but has no secrets

~ ./certstrap request-cert --common-name client
~ ./certstrap sign --years 30 --CA "Keywhiz Test CA" client
~ ./certstrap request-cert --common-name noSecretsClient
~ ./certstrap sign --years 30 --CA "Keywhiz Test CA" noSecretsClient

Create a server certificate

The server's certificate should contain a subject alternative name (SAN) entry for each host it represents. To be generally useful in development and test, this certificate will be valid for either localhost or 127.0.0.1.

~ ./certstrap request-cert --domain localhost --ip 127.0.0.1 --organizational-unit server
~ ./certstrap sign --years 30 --CA "Keywhiz Test CA" localhost

Certstrap will create out/localhost.crt and out/localhost.key but we want a keystore for Java. When prompted for a password, we used 'ponies' which is the keystore password in development and test configurations.

~ openssl pkcs12 -export -in out/localhost.crt -inkey out/localhost.key -out out/localhost.p12
~ cp out/localhost.p12 dev_and_test_keystore.p12

Base derivation key for encrypting secrets at rest

Assuming keywhiz-server has been packaged with mvn package, the following command will generate a new AES key suitable as a base derivation key. Add a -h argument to see possible options.

~ java -jar server/target/keywhiz-server-*-SNAPSHOT-shaded.jar gen-aes

Key used to encrypt cookie content

The following will generate a file to be used for cookieKey in the Keywhiz server configuration. It takes 32 random bytes and encodes them using base64.

~ head -c 32 /dev/urandom | base64 > cookiekey.base64