reference/openssl/functions/openssl-encrypt.xml
9fc8bcc0836f56a98cf432c8f933e0d96c8d680a
9fc8bcc0836f56a98cf432c8f933e0d96c8d680a
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
4
3
<refentry xml:id="function.openssl-encrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>openssl_encrypt</refname>
...
...
@@ -10,20 +9,20 @@
10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
11
<methodsynopsis>
13
-
<type>string</type><methodname>openssl_encrypt</methodname>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>openssl_encrypt</methodname>
14
13
<methodparam><type>string</type><parameter>data</parameter></methodparam>
15
-
<methodparam><type>string</type><parameter>method</parameter></methodparam>
16
-
<methodparam><type>string</type><parameter>password</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>cipher_algo</parameter></methodparam>
15
+
<methodparam><type>string</type><parameter>passphrase</parameter></methodparam>
17
16
<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
18
17
<methodparam choice="opt"><type>string</type><parameter>iv</parameter><initializer>""</initializer></methodparam>
18
+
<methodparam choice="opt"><type>string</type><parameter role="reference">tag</parameter><initializer>&null;</initializer></methodparam>
19
+
<methodparam choice="opt"><type>string</type><parameter>aad</parameter><initializer>""</initializer></methodparam>
20
+
<methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>
19
21
</methodsynopsis>
20
22
<para>
21
23
Encrypts given data with given method and key, returns a raw
22
24
or base64 encoded string
23
25
</para>
24
-
25
-
&warn.undocumented.func;
26
-
27
26
</refsect1>
28
27
29
28
<refsect1 role="parameters">
...
...
@@ -34,12 +33,12 @@
34
33
<term><parameter>data</parameter></term>
35
34
<listitem>
36
35
<para>
37
-
The data.
36
+
The plaintext message data to be encrypted.
38
37
</para>
39
38
</listitem>
40
39
</varlistentry>
41
40
<varlistentry>
42
-
<term><parameter>method</parameter></term>
41
+
<term><parameter>cipher_algo</parameter></term>
43
42
<listitem>
44
43
<para>
45
44
The cipher method. For a list of available cipher methods, use <function>openssl_get_cipher_methods</function>.
...
...
@@ -47,10 +46,12 @@
47
46
</listitem>
48
47
</varlistentry>
49
48
<varlistentry>
50
-
<term><parameter>password</parameter></term>
49
+
<term><parameter>passphrase</parameter></term>
51
50
<listitem>
52
51
<para>
53
-
The password.
52
+
The passphrase. If the passphrase is shorter than expected, it is silently padded with
53
+
<literal>NUL</literal> characters; if the passphrase is longer than expected, it is
54
+
silently truncated.
54
55
</para>
55
56
</listitem>
56
57
</varlistentry>
...
...
@@ -58,8 +59,8 @@
58
59
<term><parameter>options</parameter></term>
59
60
<listitem>
60
61
<para>
61
-
<parameter>options</parameter> can be one of
62
-
<constant>OPENSSL_RAW_DATA</constant>,
62
+
<parameter>options</parameter> is a bitwise disjunction of the flags
63
+
<constant>OPENSSL_RAW_DATA</constant> and
63
64
<constant>OPENSSL_ZERO_PADDING</constant>.
64
65
</para>
65
66
</listitem>
...
...
@@ -72,6 +73,30 @@
72
73
</para>
73
74
</listitem>
74
75
</varlistentry>
76
+
<varlistentry>
77
+
<term><parameter>tag</parameter></term>
78
+
<listitem>
79
+
<para>
80
+
The authentication tag passed by reference when using AEAD cipher mode (GCM or CCM).
81
+
</para>
82
+
</listitem>
83
+
</varlistentry>
84
+
<varlistentry>
85
+
<term><parameter>aad</parameter></term>
86
+
<listitem>
87
+
<para>
88
+
Additional authenticated data.
89
+
</para>
90
+
</listitem>
91
+
</varlistentry>
92
+
<varlistentry>
93
+
<term><parameter>tag_length</parameter></term>
94
+
<listitem>
95
+
<para>
96
+
The length of the authentication <parameter>tag</parameter>. Its value can be between 4 and 16 for GCM mode.
97
+
</para>
98
+
</listitem>
99
+
</varlistentry>
75
100
</variablelist>
76
101
</para>
77
102
</refsect1>
...
...
@@ -87,7 +112,7 @@
87
112
&reftitle.errors;
88
113
<para>
89
114
Emits an <constant>E_WARNING</constant> level error if an unknown cipher
90
-
algorithm is passed in via the <parameter>method</parameter> parameter.
115
+
algorithm is passed in via the <parameter>cipher_algo</parameter> parameter.
91
116
</para>
92
117
<para>
93
118
Emits an <constant>E_WARNING</constant> level error if an empty value is passed
...
...
@@ -107,22 +132,74 @@
107
132
</thead>
108
133
<tbody>
109
134
<row>
110
-
<entry>5.3.3</entry>
111
-
<entry>
112
-
The <parameter>iv</parameter> parameter was added.
113
-
</entry>
114
-
</row>
115
-
<row>
116
-
<entry>5.4.0</entry>
117
-
<entry>
118
-
The <parameter>raw_output</parameter> was changed to <parameter>options</parameter>.
119
-
</entry>
135
+
<entry>7.1.0</entry>
136
+
<entry>The <parameter>tag</parameter>, <parameter>aad</parameter> and <parameter>tag_length</parameter> parameters were added.</entry>
120
137
</row>
121
138
</tbody>
122
139
</tgroup>
123
140
</informaltable>
124
141
</refsect1>
125
142
143
+
144
+
<refsect1 role="examples">
145
+
&reftitle.examples;
146
+
<para>
147
+
<example>
148
+
<title>AES Authenticated Encryption in GCM mode example for PHP 7.1+</title>
149
+
<programlisting role="php">
150
+
<![CDATA[
151
+
<?php
152
+
//$key should have been previously generated in a cryptographically safe way, like openssl_random_pseudo_bytes
153
+
$plaintext = "message to be encrypted";
154
+
$cipher = "aes-128-gcm";
155
+
if (in_array($cipher, openssl_get_cipher_methods()))
156
+
{
157
+
$ivlen = openssl_cipher_iv_length($cipher);
158
+
$iv = openssl_random_pseudo_bytes($ivlen);
159
+
$ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);
160
+
//store $cipher, $iv, and $tag for decryption later
161
+
$original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);
162
+
echo $original_plaintext."\n";
163
+
}
164
+
?>
165
+
]]>
166
+
</programlisting>
167
+
</example>
168
+
169
+
<example>
170
+
<title>AES Authenticated Encryption example prior to PHP 7.1</title>
171
+
<programlisting role="php">
172
+
<![CDATA[
173
+
<?php
174
+
//$key previously generated safely, ie: openssl_random_pseudo_bytes
175
+
$plaintext = "message to be encrypted";
176
+
$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
177
+
$iv = openssl_random_pseudo_bytes($ivlen);
178
+
$ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
179
+
$hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
180
+
$ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );
181
+
182
+
//decrypt later....
183
+
$c = base64_decode($ciphertext);
184
+
$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");
185
+
$iv = substr($c, 0, $ivlen);
186
+
$hmac = substr($c, $ivlen, $sha2len=32);
187
+
$ciphertext_raw = substr($c, $ivlen+$sha2len);
188
+
$original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);
189
+
$calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);
190
+
if (hash_equals($hmac, $calcmac))// timing attack safe comparison
191
+
{
192
+
echo $original_plaintext."\n";
193
+
}
194
+
?>
195
+
]]>
196
+
</programlisting>
197
+
</example>
198
+
199
+
</para>
200
+
</refsect1>
201
+
202
+
126
203
<refsect1 role="seealso">
127
204
&reftitle.seealso;
128
205
<para>
...
...
@@ -133,7 +210,6 @@
133
210
</refsect1>
134
211
135
212
</refentry>
136
-
137
213
<!-- Keep this comment at the end of the file
138
214
Local variables:
139
215
mode: sgml
140
216