Proposal to be more discrete in usage of "passphrase" and "key" in cryptograhic functions

[galaxiesFarApart]

Cryptographic functions (using openssl_encrypt for example) which have a syntax statement that defines a "passphase" attribute and later in the one-line explanation (of further on) uses "key" for the same attribute, can be misleading.

Proposal: never mix "passphrase" with "key"; use the same attribute/term wherever it will be used/referenced.

Reasoning:

1. a "passphrase" is generally a randomly selected set of bits, bytes, or characters from a select "dictionary".

2. "key", whilst sometimes synomynous with "passphrase", "nonce", et cetera, more generally refers to a algorithmic calculation output (eg; a "cryptographic key"), and may contain a specific structure that may not be just one line long.

3. When using a (real) cryptographic "key" in place where a "passphrase" is indicated may satisfy the general requirement for "initial/user data input". However, when not paying attention or understanding the difference between "randomly selected bits, numbers, characters" and a fixed structure "cryptographic key" may result in the structured key "header" becoming the predominant portion of the required "random initial (user) encrypting data". Take for instance a PEM formattted "key" (or a GnuPG "formatted key"). The proper methodolgy to generate the "Key" may be successful, but when supplying that "key" to a cryptographic function that expects a "stream of random 'bits'", one winds up with the situation illustrated here (the first N bytes are a fixed string, every time).

4. lastly, interchanging "passphrase" and "key" can lead to a misunderstanding as to how/where such "attribute" can/should be created.

[cmb69]

Proposal: never mix "passphrase" with "key"; use the same attribute/term wherever it will be used/referenced.

Agreed.

However, in the context of openssl_encrypt() it seems to me that $key is actually more suitable. Cf. https://wiki.openssl.org/index.php/EVP_Symmetric_Encryption_and_Decryption.

Mabye @bukka can clarify?

[galaxiesFarApart]

Proposal for "openssl_encrypt"

Change the initial function description:
"Encrypts given data with given method and key, returns a raw or base64 encoded string"
to
"Encrypts given data with given method and passphrase, returns a raw or base64 encoded string"

================================================

Proposal for "openssl_decrypt"

Change the initial function description:
"Takes a raw or base64 encoded string and decrypts it using a given method and key."
to
"Takes a raw or base64 encoded string and decrypts it using a given method and passphrase."

Change the Parameter definition of "passphrase":
"The key."
to
"The passphrase. If the passphrase is shorter than expected, it is silently padded with NUL characters; if the passphrase is longer than expected, it is silently truncated."

[bukka]

PR created in #3774 with some additions.