reference/openssl/functions/openssl-encrypt.xml
7a016103e0d568448f5985dfd945092d69d5d59c
7a016103e0d568448f5985dfd945092d69d5d59c
...
...
@@ -10,9 +10,9 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type class="union"><type>string</type><type>false</type></type><methodname>openssl_encrypt</methodname>
13
-
<methodparam><type>string</type><parameter>data</parameter></methodparam>
13
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>data</parameter></methodparam>
14
14
<methodparam><type>string</type><parameter>cipher_algo</parameter></methodparam>
15
-
<methodparam><type>string</type><parameter>passphrase</parameter></methodparam>
15
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>passphrase</parameter></methodparam>
16
16
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
17
17
<methodparam choice="opt"><type>string</type><parameter>iv</parameter><initializer>""</initializer></methodparam>
18
18
<methodparam choice="opt"><type>string</type><parameter role="reference">tag</parameter><initializer>&null;</initializer></methodparam>
...
...
@@ -20,7 +20,7 @@
20
20
<methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>
21
21
</methodsynopsis>
22
22
<para>
23
-
Encrypts given data with given method and key, returns a raw
23
+
Encrypts given data with given method and passphrase, returns a raw
24
24
or base64 encoded string
25
25
</para>
26
26
</refsect1>
...
...
@@ -53,6 +53,13 @@
53
53
<literal>NUL</literal> characters; if the passphrase is longer than expected, it is
54
54
silently truncated.
55
55
</para>
56
+
<caution>
57
+
<simpara>
58
+
There is no key derivation function used for <parameter>passphrase</parameter> as its name
59
+
might suggest. The only operation used is padding with <literal>NUL</literal> characters
60
+
or truncation if the length is different than expected.
61
+
</simpara>
62
+
</caution>
56
63
</listitem>
57
64
</varlistentry>
58
65
<varlistentry>
...
...
@@ -60,8 +67,9 @@
60
67
<listitem>
61
68
<para>
62
69
<parameter>options</parameter> is a bitwise disjunction of the flags
63
-
<constant>OPENSSL_RAW_DATA</constant> and
64
-
<constant>OPENSSL_ZERO_PADDING</constant>.
70
+
<constant>OPENSSL_RAW_DATA</constant>, and
71
+
<constant>OPENSSL_ZERO_PADDING</constant>
72
+
or <constant>OPENSSL_DONT_ZERO_PAD_KEY</constant>.
65
73
</para>
66
74
</listitem>
67
75
</varlistentry>
...
...
@@ -69,7 +77,9 @@
69
77
<term><parameter>iv</parameter></term>
70
78
<listitem>
71
79
<para>
72
-
A non-NULL Initialization Vector.
80
+
A non-&null; Initialization Vector. If the IV is shorter than expected, it is padded with
81
+
<literal>NUL</literal> characters and warning is emitted; if the passphrase is longer
82
+
than expected, it is truncated and warning is emitted.
73
83
</para>
74
84
</listitem>
75
85
</varlistentry>
...
...
@@ -85,7 +95,7 @@
85
95
<term><parameter>aad</parameter></term>
86
96
<listitem>
87
97
<para>
88
-
Additional authentication data.
98
+
Additional authenticated data.
89
99
</para>
90
100
</listitem>
91
101
</varlistentry>
...
...
@@ -167,7 +177,7 @@ if (in_array($cipher, openssl_get_cipher_methods()))
167
177
</example>
168
178
169
179
<example>
170
-
<title>AES Authenticated Encryption example for PHP 5.6+</title>
180
+
<title>AES Authenticated Encryption example prior to PHP 7.1</title>
171
181
<programlisting role="php">
172
182
<![CDATA[
173
183
<?php
...
...
@@ -187,7 +197,7 @@ $hmac = substr($c, $ivlen, $sha2len=32);
187
197
$ciphertext_raw = substr($c, $ivlen+$sha2len);
188
198
$original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
189
199
$calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
190
-
if (hash_equals($hmac, $calcmac))//PHP 5.6+ timing attack safe comparison
200
+
if (hash_equals($hmac, $calcmac))// timing attack safe comparison
191
201
{
192
202
echo $original_plaintext."\n";
193
203
}
194
204