crypto,doc: update language around key stretching

[bnoordhuis]

doc/api/crypto.md currently says this:

it is recommended that developers derive a key and IV on their own using crypto.pbkdf2()

That's only sound when the key+IV are used once. Using the same key+IV twice is undesirable in general and downright disastrous with counter mode ciphers:

1. identical plaintexts encrypt to the same ciphertext (usually not what you want)
2. leaks information about the initial plaintext block with CBC and CFB ciphers
3. completely destroys the security of CTR, GCM and OFB ciphers

It would be good to add some guidelines on how to safely create and store IVs. They should be unpredictable but don't need to be kept secret after encrypting. Are there exceptions to this rule?

Refs: indexzero/nconf#299

[tniessen]

[IVs] should be unpredictable but don't need to be kept secret after encrypting. Are there exceptions to this rule?

Not that I know of. One can think of a cipher E which uses an IV N as a parameterized algorithm whose only inputs are key and message (c = EN(k, m)), and in this case the IV need not be secret according to Kerckhoff's principle.

it is recommended that developers derive a key and IV on their own using crypto.pbkdf2()

It is not strictly necessary to use a KDF to produce the IV, and it is valid to reuse a key with different IVs to some extent.

[ryzokuken]

@bnoordhuis @tniessen could I pick this up? We could discuss the specifics of the addition.

[ryzokuken]

As per my understanding of IVs,

An initialization vector should be unpredictable; ideally, they will be cryptographically random. They do not have to be secret: IVs are typically just added to ciphertext messages in plaintext. It may sound contradictory that something has to be unpredictable, but doesn’t have to be secret; it’s important to remember that an attacker must not be able to predict ahead of time what a given IV will be.

Let me know if I'm missing something or if something's wrong with my understanding of IVs.

[bnoordhuis]

@ryzokuken Yes, that's correct.

[ryzokuken]

@bnoordhuis in that case, should I add this particular paragraph to the docs to make it explicit? I believe it sums the whole thing up.

[bnoordhuis]

Sounds good. As long as it doesn't insinuate that IV reuse is okay, like it currently does.

[ryzokuken]

@bnoordhuis Correct me if I'm wrong, but I think this only appears in the documentation for crypto.createDecipher and crypto.createCipher. Aren't they both deprecated anyway?

My point here being: if I add the paragraph, do I add it to crypto.createCipher or crypto.createCipheriv which is not deprecated, but doesn't have this exact text in its description anyway?

[bnoordhuis]

I'd add them to all four, yes.

Aren't they both deprecated anyway?

That's right.

[ryzokuken]

@bnoordhuis making a PR. That said, should I add the exact same text to all four functions?

[ryzokuken]

Oh, wait. createCipher and createDecipher don't actually take an IV as an argument. Do they still need it?

[ryzokuken]

I added the text to createCipheriv and createDecipheriv. If you think it's necessary, I'd add the same to the remaining two functions.