Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix: confusing phrasing #639

Merged
merged 6 commits into from
Jan 12, 2024
Merged

Fix: confusing phrasing #639

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c3398c5
Fix: confusing phrasing
bruce-ricard Nov 28, 2023
fbf55d5
feature: split topics
bruce-ricard Nov 29, 2023
ed26a9d
fix: confusing sentences
bruce-ricard Nov 29, 2023
c023c9e
formatting
bruce-ricard Nov 29, 2023
9413837
feature: key rotation
bruce-ricard Nov 29, 2023
ca13236
fix: line breaks that break the heading markup
swalchemist Jan 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 27 additions & 15 deletions docs/credhub-security-faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this say "If a new encryption password is provided"? Is it a password or a key? Same for the bullet below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, I struggled to phrase this. It's a bit annoying, because the credhub-release spec talks about encryption keys. But what it expects, in the case of internal keys, is only the password.

So mathematically, an encryption key and the password used to generate it, are the same thing. There's a one to one mapping between keys and passwords.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. So the spec gives most of the details about the key, just not the salt. But we can talk about individual properties of that section of the spec, like encryption_password.

I'm not sure what happens if the user edits the encryption_key_name property.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could probably be simplified. What people most likely care about is the the salt that can't be rotated by itself. This already explains that the salt will be changed when the password is changed. Maybe -

The password and salt are never automatically rotated. Also, the salt cannot be rotated by itself without changing the password.

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
Expand All @@ -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.

Expand All @@ -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)

Expand Down