reference/openssl/functions/openssl-dh-compute-key.xml
296d45da275cca752dd920738fd119e55fbbde97
...
...
@@ -1,22 +1,34 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="function.openssl-dh-compute-key" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>openssl_dh_compute_key</refname>
7
-
<refpurpose>Computes shared secret for public value of remote DH key and local DH key</refpurpose>
6
+
<refpurpose>Computes shared secret for public value of remote DH public key and local DH key</refpurpose>
8
7
</refnamediv>
9
8

10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
11
<methodsynopsis>
13
-
<type>string</type><methodname>openssl_dh_compute_key</methodname>
14
-
<methodparam><type>string</type><parameter>pub_key</parameter></methodparam>
15
-
<methodparam><type>resource</type><parameter>dh_key</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>openssl_dh_compute_key</methodname>
13
+
<methodparam><type>string</type><parameter>public_key</parameter></methodparam>
14
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>OpenSSLAsymmetricKey</type><parameter>private_key</parameter></methodparam>
16
15
</methodsynopsis>
17
-

18
-
&warn.undocumented.func;
19
-

16
+
<para>
17
+
The shared secret returned by <function>openssl_dh_compute_key</function> is
18
+
often used as an encryption key to secretly communicate with a remote party.
19
+
This is known as the Diffie-Hellman key exchange.
20
+
</para>
21
+
<caution>
22
+
<para>
23
+
It is important to use the same DH parameters for remote and local key pairs; otherwise, the
24
+
generated secret between the two parties will not match.
25
+
</para>
26
+
</caution>
27
+
<note>
28
+
<simpara>
29
+
ECDH is only supported as of PHP 8.1.0 <emphasis>and</emphasis> OpenSSL 3.0.0.
30
+
</simpara>
31
+
</note>
20
32
</refsect1>
21
33

22
34
<refsect1 role="parameters">
...
...
@@ -24,18 +36,18 @@
24
36
<para>
25
37
<variablelist>
26
38
<varlistentry>
27
-
<term><parameter>pub_key</parameter></term>
39
+
<term><parameter>public_key</parameter></term>
28
40
<listitem>
29
41
<para>
30
-
Public key
42
+
DH Public key of the remote party.
31
43
</para>
32
44
</listitem>
33
45
</varlistentry>
34
46
<varlistentry>
35
-
<term><parameter>dh_key</parameter></term>
47
+
<term><parameter>private_key</parameter></term>
36
48
<listitem>
37
49
<para>
38
-
DH key
50
+
A local DH private key, corresponding to the public key to be shared with the remote party.
39
51
</para>
40
52
</listitem>
41
53
</varlistentry>
...
...
@@ -46,12 +58,177 @@
46
58
<refsect1 role="returnvalues">
47
59
&reftitle.returnvalues;
48
60
<para>
49
-
Returns computed key on success&return.falseforfailure;.
61
+
Returns shared secret on success&return.falseforfailure;.
50
62
</para>
51
63
</refsect1>
52
64

53
-
</refentry>
65
+
<refsect1 role="changelog">
66
+
&reftitle.changelog;
67
+
<informaltable>
68
+
<tgroup cols="2">
69
+
<thead>
70
+
<row>
71
+
<entry>&Version;</entry>
72
+
<entry>&Description;</entry>
73
+
</row>
74
+
</thead>
75
+
<tbody>
76
+
<row>
77
+
<entry>8.0.0</entry>
78
+
<entry>
79
+
<parameter>private_key</parameter> accepts an <classname>OpenSSLAsymmetricKey</classname> now;
80
+
previously, a &resource; of type <literal>OpenSSL key</literal> was accepted.
81
+
</entry>
82
+
</row>
83
+
</tbody>
84
+
</tgroup>
85
+
</informaltable>
86
+
</refsect1>
87
+

88
+
<refsect1 role="examples">
89
+
&reftitle.examples;
90
+
<para>
91
+
92
+
<example>
93
+
<title>Compute a shared secret</title>
94
+
<simpara>First generate a public/private DH keypair locally, and have
95
+
the remote party do the same. We need to use the <literal>openssl</literal>
96
+
command-line utility.</simpara>
97
+
<programlisting role="shell">
98
+
<![CDATA[
99
+
# generate private/public key keypair
100
+
openssl dhparam -out dhparam.pem 2048
101
+
openssl genpkey -paramfile dhparam.pem -out privatekey.pem
102
+

103
+
# extract public key only
104
+
openssl pkey -in privatekey.pem -pubout -out publickey.pem
105
+
]]>
106
+
</programlisting>
107
+
<simpara>
108
+
Next, send your public key to the remote party. Use the <literal>openssl
109
+
pkey</literal> command to view the public key you will be sent from
110
+
the remote party.</simpara>
111
+
<programlisting role="shell">
112
+
<![CDATA[
113
+
openssl pkey -pubin -in remotepublickey.pem -text -noout
114
+
]]>
115
+
</programlisting>
116
+
&example.outputs.similar;
117
+
<screen>
118
+
<![CDATA[
119
+
PKCS#3 DH Public-Key: (2048 bit)
120
+
public-key:
121
+
67:e5:e5:fa:e0:7b:0f:96:2c:dc:96:44:5f:50:02:
122
+
9e:8d:c2:6c:04:68:b0:d1:1d:75:66:fc:63:f5:e3:
123
+
42:30:b8:96:c1:45:cc:08:60:b4:21:3b:dd:ee:66:
124
+
88:db:77:d9:1e:11:89:d4:5c:f2:7a:f2:f1:fe:1c:
125
+
77:9d:6f:13:b8:b2:56:00:ef:cb:3b:60:79:74:02:
126
+
98:f5:f9:8e:3e:b5:62:08:de:ca:8c:c3:40:4a:80:
127
+
79:d5:43:06:17:a8:19:56:af:cc:95:5e:e2:32:2d:
128
+
d2:14:7b:76:5a:9a:f1:3c:76:76:35:cc:7b:c1:a5:
129
+
f4:39:e5:b6:ca:71:3f:7c:3f:97:e5:ab:86:c1:cd:
130
+
0e:e6:ee:04:c9:e6:2d:80:7e:59:c0:49:eb:b6:64:
131
+
4f:a8:f9:bb:a3:87:b3:3d:76:01:9e:2b:16:94:a4:
132
+
37:30:fb:35:e2:63:be:23:90:b9:ef:3f:46:46:04:
133
+
94:8f:60:79:7a:51:55:d6:1a:1d:f5:d9:7f:4a:3e:
134
+
aa:ac:b0:d0:82:cc:c2:e0:94:e0:54:c1:17:83:0b:
135
+
74:08:4d:5a:79:ae:ff:7f:1c:04:ab:23:39:4a:ae:
136
+
87:83:55:43:ab:7a:7c:04:9d:20:80:bb:af:5f:16:
137
+
a3:e3:20:b9:21:47:8c:f8:7f:a8:60:80:9e:61:77:
138
+
36
139
+
[...abbreviated...]
140
+
]]>
141
+
</screen>
142
+
<simpara>Use this public key as a parameter to <function>openssl_dh_compute_key</function>
143
+
in order to compute the shared secret.</simpara>
144
+
<programlisting role="php">
145
+
<![CDATA[
146
+
<?php
147
+
$remote_public_key = '67e5e5fae07b0f962cdc96445f50029e8dc26c0468b0d11d7566fc63f5e34230b896c145cc0860b4213bddee6688db77d91e1189d45cf27af2f1fe1c779d6f13b8b25600efcb3b6079740298f5f98e3eb56208deca8cc3404a8079d5430617a81956afcc955ee2322dd2147b765a9af13c767635cc7bc1a5f439e5b6ca713f7c3f97e5ab86c1cd0ee6ee04c9e62d807e59c049ebb6644fa8f9bba387b33d76019e2b1694a43730fb35e263be2390b9ef3f464604948f60797a5155d61a1df5d97f4a3eaaacb0d082ccc2e094e054c117830b74084d5a79aeff7f1c04ab23394aae87835543ab7a7c049d2080bbaf5f16a3e320b921478cf87fa860809e617736';
148
+

149
+
$local_priv_key = openssl_pkey_get_private('file://privatekey.pem');
54
150

151
+
$shared_secret = openssl_dh_compute_key(hex2bin($remote_public_key), $local_priv_key);
152
+
echo bin2hex($shared_secret)."\n";
153
+
?>
154
+
]]>
155
+
</programlisting>
156
+
</example>
157
+
</para>
158
+
<para>
159
+
<example>
160
+
<title>Generate a DH public/private keypair in php</title>
161
+
<simpara>First, generate the DH prime number</simpara>
162
+
<programlisting role="shell">
163
+
<![CDATA[
164
+
openssl dhparam -out dhparam.pem 2048
165
+
openssl dh -in dhparam.pem -noout -text
166
+
]]>
167
+
</programlisting>
168
+
&example.outputs.similar;
169
+
<screen>
170
+
<![CDATA[
171
+
PKCS#3 DH Parameters: (2048 bit)
172
+
prime:
173
+
00:a3:25:1e:73:3f:44:b9:2b:ee:f4:9d:9f:37:6a:
174
+
4b:fd:1d:bd:f4:af:da:c8:10:77:59:41:c6:5f:73:
175
+
d2:88:29:39:cd:1c:5f:c3:9f:0f:22:d2:9c:20:c1:
176
+
e4:c0:18:03:b8:b6:d8:da:ad:3b:39:a6:da:8e:fe:
177
+
12:30:e9:03:5d:22:ba:ef:18:d2:7b:69:f9:5b:cb:
178
+
78:c6:0c:8c:6b:f2:49:92:c2:49:e0:45:77:72:b3:
179
+
55:36:30:f2:40:17:89:18:50:03:fa:2d:54:7a:7f:
180
+
34:4c:73:32:b6:88:14:51:14:be:80:57:95:e6:a3:
181
+
f6:51:ff:17:47:4f:15:d6:0e:6c:47:53:72:2c:2a:
182
+
4c:21:cb:7d:f3:49:97:c9:47:5e:40:33:7b:99:52:
183
+
7e:7a:f3:52:27:80:de:1b:26:6b:40:bb:14:11:0b:
184
+
fb:e6:d8:2f:cf:a0:06:2f:96:b9:1c:0b:b4:cb:d3:
185
+
a6:62:9c:48:67:f6:81:f2:c6:ff:45:03:0a:9d:67:
186
+
9d:ce:27:d9:6b:48:5d:ca:fb:c2:5d:84:9b:8b:cb:
187
+
40:c7:a4:0c:8a:6e:f4:ab:ba:b6:10:c3:b8:25:4d:
188
+
cf:60:96:f4:db:e8:00:1c:58:47:7a:fb:51:86:d1:
189
+
22:d7:4e:94:31:7a:d5:da:3d:53:de:da:bb:64:8d:
190
+
62:6b
191
+
generator: 2 (0x2)
192
+
]]>
193
+
</screen>
194
+
<simpara>Prime and generator values ares passed as p and g into <function>openssl_pkey_new</function></simpara>
195
+
<programlisting role="php">
196
+
<![CDATA[
197
+
<?php
198
+
$configargs = array();
199
+
$configargs['p'] = hex2bin('00a3251e733f44b92beef49d9f376a4bfd1dbdf4afdac810775941c65f73d2882939cd1c5fc39f0f22d29c20c1e4c01803b8b6d8daad3b39a6da8efe1230e9035d22baef18d27b69f95bcb78c60c8c6bf24992c249e0457772b3553630f2401789185003fa2d547a7f344c7332b688145114be805795e6a3f651ff17474f15d60e6c4753722c2a4c21cb7df34997c9475e40337b99527e7af3522780de1b266b40bb14110bfbe6d82fcfa0062f96b91c0bb4cbd3a6629c4867f681f2c6ff45030a9d679dce27d96b485dcafbc25d849b8bcb40c7a40c8a6ef4abbab610c3b8254dcf6096f4dbe8001c58477afb5186d122d74e94317ad5da3d53dedabb648d626b');
200
+
$configargs['g'] = hex2bin('02');
201
+
$private_key = openssl_pkey_new(array('dh' => $configargs));
202
+
openssl_pkey_export_to_file($private_key,'privatekey.pem',$passphrase='y0urp@s5phr@se');
203
+

204
+
$details = openssl_pkey_get_details($private_key);
205
+
$local_pub_key = $details['dh']['pub_key'];
206
+
echo bin2hex($local_pub_key)."\n";//you can send your public key to the remote party
207
+

208
+
$details = openssl_pkey_get_details(openssl_pkey_get_public("file://remotepublickey.pem"));
209
+
$remote_public_key = $details['dh']['pub_key'];
210
+
$shared_secret = openssl_dh_compute_key($remote_public_key, $private_key);
211
+
echo bin2hex($shared_secret)."\n";
212
+
?>
213
+
]]>
214
+
</programlisting>
215
+
</example>
216
+
</para>
217
+
</refsect1>
218
+

219
+
<refsect1 role="seealso">
220
+
&reftitle.seealso;
221
+
<para>
222
+
<simplelist>
223
+
<member><function>openssl_pkey_new</function></member>
224
+
<member><function>openssl_pkey_get_details</function></member>
225
+
<member><function>openssl_pkey_get_private</function></member>
226
+
<member><function>openssl_pkey_get_public</function></member>
227
+
</simplelist>
228
+
</para>
229
+
</refsect1>
230
+
231
+
</refentry>
55
232
<!-- Keep this comment at the end of the file
56
233
Local variables:
57
234
mode: sgml
58
235



Translation status