CredHub manages credentials like passwords, certificates, certificate authorities, ssh keys, rsa keys and arbitrary values (strings and JSON blobs). CredHub provides a CLI and API to get, set, generate and securely store such credentials.
The Cloud Foundry team uses GitHub and accepts contributions via pull request.
Follow these steps to make a contribution to any of our open source repositories:
Set your name and email (these should match the information on your submitted CLA)
git config --global user.name "Firstname Lastname" git config --global user.email "[email protected]"
We strongly encourage people to report security vulnerabilities privately to our security team before disclosing them in a public forum.
Please note that the e-mail address below should only be used for reporting undisclosed security vulnerabilities in open source Cloud Foundry codebases and managing the process of fixing such vulnerabilities. We cannot accept regular bug reports or other security-related queries at this address.
The e-mail address to use to contact the CFF Security Team is [email protected]
Our public PGP key can be obtained from a public key server such as pgp.mit.edu. Its fingerprint is: 3FC8 9AF3 940B E270 CF25 E122 9965 0006 EF9D C642. More information can be found at cloudfoundry.org/security.
git checkout -b <my_new_branch>)
git push origin <my_new_branch>) and submit a pull request
We favor pull requests with very small, single commits with a single purpose. Your pull request is much more likely to be accepted if it is small and focused with a clear message that conveys the intent of your change.
The CredHub API can generate API documentation by running its test suite (via Spring Rest Docs). CredHub API Documentation can be generated as follows:
CredHub API documentation will be built as an html file in the CredHub backend gradle subproject build directory:
Launching in production directly using the
bootRun target is unsafe, as you will launch with a
dev profile, which has checked-in secret keys in
A dependency graph of project components (gradle subprojects) can be generated to better understand project organization. You will need graphviz installed on your system in order to generate the graph.
Configuration for the server is spread across the
application-dev.yml. This includes:
dev-keys intended for development use only.
application-dev-postgres.yml. For convenience, these per-database profiles include the
By default, CredHub launches with the
dev profiles enabled.
CredHub relies on the JDK to have uncrippled cryptographic capability -- in the Oracle JDK, this requires the slightly deceptively named "Unlimited Strength Jurisdiction Policy".
By default, OpenJDK ships with "Unlimited Strength". Our credhub-release uses OpenJDK, and so inherits the full-strength capability.
But the Oracle JDK is often installed on workstations and does not have the Unlimited Strength policy.
If you see an error like
java.security.InvalidKeyException: Illegal key size, you probably haven't installed the additional policy for the Oracle JDK. CredHub is trying to use 256-bit keys, but is being blocked by the default policy.
Oracle makes the Unlimited Strength policy available for separate download here.
Assuming you are on OS X, you can then run:
unzip ~/Downloads/jce_policy-8.zip -d /tmp sudo cp /tmp/UnlimitedJCEPolicyJDK8/*.jar "$(/usr/libexec/java_home)/jre/lib/security/"
You will need to restart CredHub locally for changes to take effect.
CredHub requires a UAA server to manage authentication.
application-dev.yml there are two relevant settings:
auth-server.url. This needs to point to a running UAA server (remote or BOSH-lite, it's up to you).
security.oauth2.resource.jwt.key-value. This is the public verification key, corresponding to a private JWT signing key held by your UAA server.
For convenience, the CredHub team runs a public UAA whose IP is in the default
application-dev.yml manifest. The password grant values are
password and the client credentials grant value are
secret. This public UAA is for local development usage only! You will need to skip SSL validation in order to use it.
In order to run CredHub against a UAA running on your local machine, do the following:
docker run -d --mount type=bind,source=$PWD/config/uaa.yml,target=/uaa/uaa.yml -p 127.0.0.1:8080:8080 pcfseceng/uaa:latest
H2 datasource configuration is in
Postgres datasource configuration is in
Before development, you'll need to create the target database.
Then to run in development mode with Postgres
MySQL datasource configuration is in
Log into your MySQL server and create databases
credhub_test with privileges granted to
mysql -u root create database credhub_test; create database credhub_dev;
If you're on a Mac using Homebrew and you run into a problem where you install MySQL and it isn't running (i.e.,
mysql -u root errors with a socket error), you may need to uninstall mysql, delete the
/usr/local/var/mysql directory (Warning: this will delete all local MySQL data!), and then reinstall MySQL.
Then to run in development mode with MySQL:
Testing with different databases requires you to set a system property with the profile corresponding to your desired database. For example, to test with H2, you'll need to run the tests with the
During development, it is helpful to set up different IntelliJ testing profiles that use the following VM Options:
-ea -Dspring.profiles.active=unit-test-h2for testing with H2
-ea -Dspring.profiles.active=unit-test-mysqlfor testing with MySQL
-ea -Dspring.profiles.active=unit-test-postgresfor testing with Postgres
After having pulled the credhub-cli repo, run
make, and then run the following command to target your locally running CredHub instance:
build/credhub login -s https://localhost:9000 -u credhub -p password --skip-tls-validation
First, be sure to pull and compile the credhub-cli, as described above.
Make sure your development server is running. When it starts up for the first time, it will create a server CA and server certificate for SSL, as well as a trusted client CA for testing mutual TLS authentication. These will be located in
src/test/resources relative to the
Pull credhub-acceptance-tests and run:
Assuming it works, that will generate some test client certificates for testing mutual TLS (in
certs/ in the acceptance test directory) and run the acceptance test suite against your locally running credhub server.
Find Security Bugs
Exclude filter filesand select config/findbugs/findbugs-filter.xml