Clarify passphrase for openssl_encrypt and openssl_decrypt (#3774)

Author: bukka

reference/openssl/functions/openssl-decrypt.xml

@@ -19,7 +19,7 @@
    <methodparam choice="opt"><type>string</type><parameter>aad</parameter><initializer>""</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Takes a raw or base64 encoded string and decrypts it using a given method and key.
+   Takes a raw or base64 encoded string and decrypts it using a given method and passphrase.
   </para>
 
  </refsect1>
@@ -49,8 +49,17 @@
      <term><parameter>passphrase</parameter></term>
      <listitem>
       <para>
-       The key.
+       The passphrase. If the passphrase is shorter than expected, it is silently padded with
+       <literal>NUL</literal> characters; if the passphrase is longer than expected, it is
+       silently truncated.
       </para>
+      <caution>
+       <simpara>
+        There is no key derivation function used for <parameter>passphrase</parameter> as its name
+        might suggest. The only operation used is padding with <literal>NUL</literal> characters
+        or truncation if the length is different than expected.
+       </simpara>
+      </caution>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -68,7 +77,9 @@
      <term><parameter>iv</parameter></term>
      <listitem>
       <para>
-       A non-NULL Initialization Vector.
+       A non-&null; Initialization Vector. If the IV is shorter than expected, it is padded with
+       <literal>NUL</literal> characters and warning is emitted; if the passphrase is longer
+       than expected, it is truncated and warning is emitted.
       </para>
      </listitem>
     </varlistentry>

reference/openssl/functions/openssl-encrypt.xml

@@ -20,7 +20,7 @@
    <methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Encrypts given data with given method and key, returns a raw
+   Encrypts given data with given method and passphrase, returns a raw
    or base64 encoded string
   </para>
  </refsect1>
@@ -53,6 +53,13 @@
        <literal>NUL</literal> characters; if the passphrase is longer than expected, it is
        silently truncated.
       </para>
+      <caution>
+       <simpara>
+        There is no key derivation function used for <parameter>passphrase</parameter> as its name
+        might suggest. The only operation used is padding with <literal>NUL</literal> characters
+        or truncation if the length is different than expected.
+       </simpara>
+      </caution>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -70,7 +77,9 @@
      <term><parameter>iv</parameter></term>
      <listitem>
       <para>
-       A non-NULL Initialization Vector.
+       The passphrase. If the passphrase is shorter than expected, it is silently padded with
+       <literal>NUL</literal> characters; if the passphrase is longer than expected, it is
+       silently truncated.
       </para>
      </listitem>
     </varlistentry>