Document EVP_BytesToKey a bit better

This is a generalized PBKDF1. Also you shouldn't use it unless you want
PBKDF1.

Change-Id: I05313aa775123503391e66697810fda8538d74f7
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/75628
Reviewed-by: Bob Beck <bbe@google.com>
Commit-Queue: David Benjamin <davidben@google.com>
Auto-Submit: David Benjamin <davidben@google.com>
Commit-Queue: Bob Beck <bbe@google.com>

include/openssl/cipher.h

diff --git a/include/openssl/cipher.h b/include/openssl/cipher.h
index ad0f139..a7ca77d 100644
--- a/include/openssl/cipher.h
+++ b/include/openssl/cipher.h
@@ -274,11 +274,25 @@
 // Key derivation.
 
 // EVP_BytesToKey generates a key and IV for the cipher |type| by iterating
-// |md| |count| times using |data| and |salt|. On entry, the |key| and |iv|
-// buffers must have enough space to hold a key and IV for |type|. It returns
-// the length of the key on success or zero on error.
+// |md| |count| times using |data| and an optional |salt|, writing the result to
+// |key| and |iv|. If not NULL, the |key| and |iv| buffers must have enough
+// space to hold a key and IV for |type|, as returned by |EVP_CIPHER_key_length|
+// and |EVP_CIPHER_iv_length|. This function returns the length of the key
+// (without the IV) on success or zero on error.
+//
+// If |salt| is NULL, the empty string is used as the salt. Salt lengths other
+// than 0 and 8 are not supported by this function. Either of |key| or |iv| may
+// be NULL to skip that output.
+//
+// When the total data derived is less than the size of |md|, this function
+// implements PBKDF1 from RFC 8018. Otherwise, it generalizes PBKDF1 by
+// computing prepending the previous output to |data| and re-running PBKDF1 for
+// further output.
+//
+// This function is provided for compatibility with legacy uses of PBKDF1. New
+// applications should use a more modern algorithm, such as |EVP_PBE_scrypt|.
 OPENSSL_EXPORT int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md,
-                                  const uint8_t *salt, const uint8_t *data,
+                                  const uint8_t salt[8], const uint8_t *data,
                                   size_t data_len, unsigned count, uint8_t *key,
                                   uint8_t *iv);