diff --git a/docs/credhub-security-faq.md b/docs/credhub-security-faq.md index 625d25a93..8ced3857f 100644 --- a/docs/credhub-security-faq.md +++ b/docs/credhub-security-faq.md @@ -37,8 +37,7 @@ text password. Reviewers may inspect bosh manifest to confirm. Actually being able to fetch credentials and have a successful deployment of vm’s in the foundation. -## What cryptographic key management techniques and standards does the - product support? +## What cryptographic key management techniques and standards does the product support? AES 256 GCM is supported for encryption. NIST Special Publication 800-90A Revision 1, section 10.1 is used during HSM-based key @@ -51,16 +50,31 @@ TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ## How are Keys internally managed? If CredHub's third-party integration with a Luna SafeNet HSM is -enabled, then CredHub has no knowledge of key values. If CredHub is -started in internal encryption mode, CredHub deterministically -generates a site-specific AES256 key on startup. CredHub concatenates -a user-defined password from its configuration file with a -randomly-generated salt stored in its database and hashes the -resulting string to deterministically generate an AES256 key, which it -holds in memory for the lifetime of the server. +enabled, then CredHub has no knowledge of key values. -## How are privileged users prevented from compromising cryptographic - keys? +If CredHub is started in internal encryption mode: + +* If a new encryption key is provided, CredHub will generate a new + random salt string, and will store it in its database for the + future. +* If the encryption key had already been used before, CredHub will + fetch the associated salt from its database to reuse it. + +CredHub then calculates the AES256 key by concatenating the +user-provided encryption password from its configuration file with the +salt, and hashes the resulting string. This hash is then used as the +AES key, which CredHub will hold in memory. + +This design allows CredHub to have access to the AES key at all times, +without ever having to store it on disk. + +Passwords and salts cannot be rotated individually, and they are never +automatically rotated. If you want to rotate either or both of them, +you need to add a new key to CredHub's configuration, and CredHub will +start using that new password and a newly generated salt to create a +fresh AES key. + +## How are privileged users prevented from compromising cryptographic keys? Key material is handled by the platform operator. The CredHub service and the bosh director both provide accountability of operator actions @@ -74,8 +88,7 @@ Java JCA/JCE on top of Linux OS, /dev/urandom. We use HSM random for generation if available SHA1PRNG. For entropy source, Java JCA/JCE provider is used, but ultimately Linux OS /dev/urandom, or HSM. -## What are the symmetric cipher algorithms and modes of operation - supported? +## What are the symmetric cipher algorithms and modes of operation supported? CredHub internal provider implements: AES 256 GCM. @@ -87,8 +100,7 @@ RSA. 2048 as default modulus SHA256 -## What external key management hardware vendor products are - supported? +## What external key management hardware vendor products are supported? Luna Safenet HSM (AWS CloudHSM Classic)