reference/openssl/functions/openssl-open.xml
730fd5c3dd1523bb9330762084ce016d4e58e946
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.openssl-open">
3
+
<refentry xml:id="function.openssl-open" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>openssl_open</refname>
6
6
<refpurpose>Open sealed data</refpurpose>
...
...
@@ -10,22 +10,21 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>bool</type><methodname>openssl_open</methodname>
13
-
<methodparam><type>string</type><parameter>sealed_data</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter role="reference">open_data</parameter></methodparam>
15
-
<methodparam><type>string</type><parameter>env_key</parameter></methodparam>
16
-
<methodparam><type>mixed</type><parameter>priv_key_id</parameter></methodparam>
17
-
<methodparam choice="opt"><type>string</type><parameter>method</parameter><initializer>"RC4"</initializer></methodparam>
18
-
<methodparam choice="opt"><type>string</type><parameter role="reference">iv</parameter></methodparam>
13
+
<methodparam><type>string</type><parameter>data</parameter></methodparam>
14
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter role="reference">output</parameter></methodparam>
15
+
<methodparam><type>string</type><parameter>encrypted_key</parameter></methodparam>
16
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type class="union"><type>OpenSSLAsymmetricKey</type><type>OpenSSLCertificate</type><type>array</type><type>string</type></type><parameter>private_key</parameter></methodparam>
17
+
<methodparam><type>string</type><parameter>cipher_algo</parameter></methodparam>
18
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>iv</parameter><initializer>&null;</initializer></methodparam>
19
19
</methodsynopsis>
20
20
<para>
21
-
<function>openssl_open</function> opens (decrypts)
22
-
<parameter>sealed_data</parameter> using the private key associated with
23
-
the key identifier <parameter>priv_key_id</parameter> and the envelope key
24
-
<parameter>env_key</parameter>, and fills
25
-
<parameter>open_data</parameter> with the decrypted data.
26
-
The envelope key is generated when the
27
-
data are sealed and can only be used by one specific private key. See
28
-
<function>openssl_seal</function> for more information.
21
+
<function>openssl_open</function> opens (decrypts) <parameter>data</parameter> using an envelope
22
+
key that is decrypted from <parameter>encrypted_key</parameter> using
23
+
<parameter>private_key</parameter>. The decryption is done using
24
+
<parameter>cipher_algo</parameter> and <parameter>iv</parameter>. The IV is required only if the
25
+
cipher method requires it. The function fills <parameter>output</parameter> with the decrypted
26
+
data. The envelope key is usually generated when the data are sealed using a public key that is
27
+
associated with the private key. See <function>openssl_seal</function> for more information.
29
28
</para>
30
29
</refsect1>
31
30

...
...
@@ -34,40 +33,49 @@
34
33
<para>
35
34
<variablelist>
36
35
<varlistentry>
37
-
<term><parameter>sealed_data</parameter></term>
36
+
<term><parameter>data</parameter></term>
38
37
<listitem>
39
38
<para>
39
+
The sealed data.
40
40
</para>
41
41
</listitem>
42
42
</varlistentry>
43
43
<varlistentry>
44
-
<term><parameter>open_data</parameter></term>
44
+
<term><parameter>output</parameter></term>
45
45
<listitem>
46
46
<para>
47
-
If the call is successful the opened data is returned in this
48
-
parameter.
47
+
If the call is successful the opened data is returned in this parameter.
49
48
</para>
50
49
</listitem>
51
50
</varlistentry>
52
51
<varlistentry>
53
-
<term><parameter>env_key</parameter></term>
52
+
<term><parameter>encrypted_key</parameter></term>
54
53
<listitem>
55
54
<para>
55
+
The encrypted symmetric key that can be decrypted using <parameter>private_key</parameter>.
56
56
</para>
57
57
</listitem>
58
58
</varlistentry>
59
59
<varlistentry>
60
-
<term><parameter>priv_key_id</parameter></term>
60
+
<term><parameter>private_key</parameter></term>
61
61
<listitem>
62
62
<para>
63
+
The private key used for decrypting <parameter>encrypted_key</parameter>.
63
64
</para>
64
65
</listitem>
65
66
</varlistentry>
66
67
<varlistentry>
67
-
<term><parameter>method</parameter></term>
68
+
<term><parameter>cipher_algo</parameter></term>
68
69
<listitem>
69
70
<para>
70
-
The cipher method.
71
+
The cipher method used for decryption of <parameter>data</parameter>.
72
+
<caution>
73
+
<simpara>
74
+
The default value for PHP versions prior to 8.0 is (<literal>'RC4'</literal>) which is
75
+
considered insecure. It is strongly recommended to explicitly specify a secure cipher
76
+
method.
77
+
</simpara>
78
+
</caution>
71
79
</para>
72
80
</listitem>
73
81
</varlistentry>
...
...
@@ -75,7 +83,9 @@
75
83
<term><parameter>iv</parameter></term>
76
84
<listitem>
77
85
<para>
78
-
The initialization vector.
86
+
The initialization vector used for decryption of <parameter>data</parameter>. It is required
87
+
if the cipher method requires IV. This can be found out by calling
88
+
<function>openssl_cipher_iv_length</function> with <parameter>cipher_algo</parameter>.
79
89
</para>
80
90
</listitem>
81
91
</varlistentry>
...
...
@@ -90,7 +100,7 @@
90
100
</para>
91
101
</refsect1>
92
102

93
-
<refsect1 role="changelog"><!-- {{{ -->
103
+
<refsect1 role="changelog">
94
104
&reftitle.changelog;
95
105
<informaltable>
96
106
<tgroup cols="2">
...
...
@@ -102,21 +112,24 @@
102
112
</thead>
103
113
<tbody>
104
114
<row>
105
-
<entry>7.0.0</entry>
115
+
<entry>8.0.0</entry>
106
116
<entry>
107
-
The <parameter>iv</parameter> has been added.
117
+
<parameter>private_key</parameter> accepts an <classname>OpenSSLAsymmetricKey</classname>
118
+
or <classname>OpenSSLCertificate</classname> instance now;
119
+
previously, a &resource; of type <literal>OpenSSL key</literal> or <literal>OpenSSL X.509 CSR</literal>
120
+
was accepted.
108
121
</entry>
109
122
</row>
110
123
<row>
111
-
<entry>5.3.0</entry>
124
+
<entry>8.0.0</entry>
112
125
<entry>
113
-
The <parameter>method</parameter> has been added.
126
+
<parameter>cipher_algo</parameter> is no longer an optional parameter.
114
127
</entry>
115
128
</row>
116
129
</tbody>
117
130
</tgroup>
118
131
</informaltable>
119
-
</refsect1><!-- }}} -->
132
+
</refsect1>
120
133

121
134
<refsect1 role="examples">
122
135
&reftitle.examples;
...
...
@@ -126,24 +139,20 @@
126
139
<programlisting role="php">
127
140
<![CDATA[
128
141
<?php
129
-
// $sealed and $env_key are assumed to contain the sealed data
130
-
// and our envelope key, both given to us by the sealer.
131
142

132
-
// fetch private key from file and ready it
133
-
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
134
-
$priv_key = fread($fp, 8192);
135
-
fclose($fp);
136
-
$pkeyid = openssl_get_privatekey($priv_key);
143
+
// $sealed, $env_key and $iv are assumed to contain the sealed data, our
144
+
// envelope key and IV. All given to us by the sealer.
145
+

146
+
// Fetch private key from file located in private_key.pem
147
+
$pkey = openssl_get_privatekey("file://private_key.pem");
137
148

138
-
// decrypt the data and store it in $open
139
-
if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
140
-
echo "here is the opened data: ", $open;
149
+
// Decrypt the data and store it in $open
150
+
if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
151
+
echo "Here is the opened data: ", $open;
141
152
} else {
142
-
echo "failed to open data";
153
+
echo "Failed to open data";
143
154
}
144
155

145
-
// free the private key from memory
146
-
openssl_free_key($pkeyid);
147
156
?>
148
157
]]>
149
158
</programlisting>
...
...
@@ -161,7 +170,6 @@ openssl_free_key($pkeyid);
161
170
</refsect1>
162
171

163
172
</refentry>
164
-

165
173
<!-- Keep this comment at the end of the file
166
174
Local variables:
167
175
mode: sgml
168
176



Translation status