Proposal for "openssl_encrypt"

[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."

Originally posted by @galaxiesFarApart in https://github.com/php/doc-en/issues/3738#issuecomment-2351541296

[cmb69]

I still think that in the context of symmetric encryption, "key" is more appropriate than "passphrase". I hope someone can clarify this.

[damianwadley]

Every definition of "passphrase" I can see talks about it in terms of human language words that function like a password;

• a sequence of words or other text... similar to a password in usage
• A passphrase is a memorized secret consisting of a sequence of words or other text
• a sequence of words, typically longer than a traditional password... usually consists of a combination of words that are easy to remember

In other words, no, it does not make sense to use the word "passphrase" in this context of things that are very much meant to be cryptographically secure.

What about "key"? Consider the following:

So "key" is the correct term and the docs should not use "passphrase".

[cmb69]

Then I'd go with "key" instead of "passphrase" for symmetric encryption. It seems to me that for asymetric encryption, the usage of "passphrase" is appropriate when referring to the passphrase which is used to unlock an SSH key, for example. So from quickly skimming openssl.stub.php, the only wrongly named parameters are those for openssl_encrypt() and openssl_decrypt(). However, since we cannot change the parameter name for BC reasons, I suggest to clarify this in the parameter description.

[bukka]

Except it's not key either because it's getting modified currently (padded with zeros or truncated). Although it's not passphrase either really but the name is there and changing that would be a BC break (named param) so I think we need to stick with passphrase. I added a note about KDF not being used and created a PR: https://github.com/php/doc-en/pull/3774