reference/openssl/functions/openssl-csr-new.xml
497c40ac164d5873fd87f622dfdeb5206392b446
...
...
@@ -1,23 +1,23 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.openssl-csr-new">
3
+
<refentry xml:id="function.openssl-csr-new" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>openssl_csr_new</refname>
6
-
<refpurpose>Generates a CSR</refpurpose>
6
+
<refpurpose>Generates a <acronym>CSR</acronym></refpurpose>
7
7
</refnamediv>
8
8
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>mixed</type><methodname>openssl_csr_new</methodname>
13
-
<methodparam><type>array</type><parameter>dn</parameter></methodparam>
14
-
<methodparam><type>resource</type><parameter role="reference">privkey</parameter></methodparam>
15
-
<methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
16
-
<methodparam choice="opt"><type>array</type><parameter>extraattribs</parameter></methodparam>
12
+
<type class="union"><type>OpenSSLCertificateSigningRequest</type><type>false</type></type><methodname>openssl_csr_new</methodname>
13
+
<methodparam><type>array</type><parameter>distinguished_names</parameter></methodparam>
14
+
<methodparam><type>OpenSSLAsymmetricKey</type><parameter role="reference">private_key</parameter></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>extra_attributes</parameter><initializer>&null;</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
-
<function>openssl_csr_new</function> generates a new CSR (Certificate Signing Request)
20
-
based on the information provided by <parameter>dn</parameter>.
19
+
<function>openssl_csr_new</function> generates a new <acronym>CSR</acronym>
20
+
based on the information provided by <parameter>distinguished_names</parameter>.
21
21
</para>
22
22
&note.openssl.cnf;
23
23
</refsect1>
...
...
@@ -27,7 +27,7 @@
27
27
<para>
28
28
<variablelist>
29
29
<varlistentry>
30
-
<term><parameter>dn</parameter></term>
30
+
<term><parameter>distinguished_names</parameter></term>
31
31
<listitem>
32
32
<para>
33
33
The Distinguished Name or subject fields to be used in the certificate.
...
...
@@ -35,28 +35,28 @@
35
35
</listitem>
36
36
</varlistentry>
37
37
<varlistentry>
38
-
<term><parameter>privkey</parameter></term>
38
+
<term><parameter>private_key</parameter></term>
39
39
<listitem>
40
40
<para>
41
-
<parameter>privkey</parameter> should be set to a private key that was
41
+
<parameter>private_key</parameter> should be set to a private key that was
42
42
previously generated by <function>openssl_pkey_new</function> (or
43
43
otherwise obtained from the other openssl_pkey family of functions).
44
44
The corresponding public portion of the key will be used to sign the
45
-
CSR.
45
+
<acronym>CSR</acronym>.
46
46
</para>
47
47
</listitem>
48
48
</varlistentry>
49
49
<varlistentry>
50
-
<term><parameter>configargs</parameter></term>
50
+
<term><parameter>options</parameter></term>
51
51
<listitem>
52
52
<para>
53
53
By default, the information in your system <literal>openssl.conf</literal>
54
54
is used to initialize the request; you can specify a configuration file
55
55
section by setting the <literal>config_section_section</literal> key of
56
-
<parameter>configargs</parameter>. You can also specify an alternative
56
+
<parameter>options</parameter>. You can also specify an alternative
57
57
openssl configuration file by setting the value of the
58
58
<literal>config</literal> key to the path of the file you want to use.
59
-
The following keys, if present in <parameter>configargs</parameter>
59
+
The following keys, if present in <parameter>options</parameter>
60
60
behave as their equivalents in the <literal>openssl.conf</literal>, as
61
61
listed in the table below.
62
62
<table>
...
...
@@ -64,7 +64,7 @@
64
64
<tgroup cols="3">
65
65
<thead>
66
66
<row>
67
-
<entry><parameter>configargs</parameter> key</entry>
67
+
<entry><parameter>options</parameter> key</entry>
68
68
<entry>type</entry>
69
69
<entry><literal>openssl.conf</literal> equivalent</entry>
70
70
<entry>description</entry>
...
...
@@ -88,18 +88,18 @@
88
88
<entry>req_extensions</entry>
89
89
<entry><type>string</type></entry>
90
90
<entry>req_extensions</entry>
91
-
<entry>Selects which extensions should be used when creating a CSR</entry>
91
+
<entry>Selects which extensions should be used when creating a <acronym>CSR</acronym></entry>
92
92
</row>
93
93
<row>
94
94
<entry>private_key_bits</entry>
95
-
<entry><type>integer</type></entry>
95
+
<entry><type>int</type></entry>
96
96
<entry>default_bits</entry>
97
97
<entry>Specifies how many bits should be used to generate a private
98
98
key</entry>
99
99
</row>
100
100
<row>
101
101
<entry>private_key_type</entry>
102
-
<entry><type>integer</type></entry>
102
+
<entry><type>int</type></entry>
103
103
<entry>none</entry>
104
104
<entry>Specifies the type of private key to create. This can be one
105
105
of <constant>OPENSSL_KEYTYPE_DSA</constant>,
...
...
@@ -111,13 +111,13 @@
111
111
</row>
112
112
<row>
113
113
<entry>encrypt_key</entry>
114
-
<entry><type>boolean</type></entry>
114
+
<entry><type>bool</type></entry>
115
115
<entry>encrypt_key</entry>
116
116
<entry>Should an exported key (with passphrase) be encrypted?</entry>
117
117
</row>
118
118
<row>
119
119
<entry>encrypt_key_cipher</entry>
120
-
<entry><type>integer</type></entry>
120
+
<entry><type>int</type></entry>
121
121
<entry>none</entry>
122
122
<entry>
123
123
One of <link linkend="openssl.ciphers">cipher constants</link>.
...
...
@@ -128,7 +128,7 @@
128
128
<entry><type>string</type></entry>
129
129
<entry>none</entry>
130
130
<entry>
131
-
PHP 7.1+, One of <function>openssl_get_curve_names</function>.
131
+
One of <function>openssl_get_curve_names</function>.
132
132
</entry>
133
133
</row>
134
134
<row>
...
...
@@ -146,12 +146,12 @@
146
146
</listitem>
147
147
</varlistentry>
148
148
<varlistentry>
149
-
<term><parameter>extraattribs</parameter></term>
149
+
<term><parameter>extra_attributes</parameter></term>
150
150
<listitem>
151
151
<para>
152
-
<parameter>extraattribs</parameter> is used to specify additional
153
-
configuration options for the CSR. Both <parameter>dn</parameter> and
154
-
<parameter>extraattribs</parameter> are associative arrays whose keys are
152
+
<parameter>extra_attributes</parameter> is used to specify additional
153
+
configuration options for the <acronym>CSR</acronym>. Both <parameter>distinguished_names</parameter> and
154
+
<parameter>extra_attributes</parameter> are associative arrays whose keys are
155
155
converted to OIDs and applied to the relevant part of the request.
156
156
</para>
157
157
</listitem>
...
...
@@ -163,10 +163,46 @@
163
163
<refsect1 role="returnvalues">
164
164
&reftitle.returnvalues;
165
165
<para>
166
-
Returns the CSR&return.falseforfailure;.
166
+
Returns the <acronym>CSR</acronym>&return.falseforfailure;.
167
167
</para>
168
168
</refsect1>
169
169

170
+
<refsect1 role="changelog">
171
+
&reftitle.changelog;
172
+
<informaltable>
173
+
<tgroup cols="2">
174
+
<thead>
175
+
<row>
176
+
<entry>&Version;</entry>
177
+
<entry>&Description;</entry>
178
+
</row>
179
+
</thead>
180
+
<tbody>
181
+
<row>
182
+
<entry>8.0.0</entry>
183
+
<entry>
184
+
On success, this function returns an <classname>OpenSSLCertificateSigningRequest</classname> instance now;
185
+
previously, a &resource; of type <literal>OpenSSL X.509 CSR</literal> was returned.
186
+
</entry>
187
+
</row>
188
+
<row>
189
+
<entry>8.0.0</entry>
190
+
<entry>
191
+
<parameter>private_key</parameter> accepts an <classname>OpenSSLAsymmetricKey</classname> instance now;
192
+
previously, a &resource; of type <literal>OpenSSL key</literal> was accepted.
193
+
</entry>
194
+
</row>
195
+
<row>
196
+
<entry>7.1.0</entry>
197
+
<entry>
198
+
<parameter>options</parameter> now also supports <literal>curve_name</literal>.
199
+
</entry>
200
+
</row>
201
+
</tbody>
202
+
</tgroup>
203
+
</informaltable>
204
+
</refsect1>
205
+

170
206
<refsect1 role="examples">
171
207
&reftitle.examples;
172
208
<para>
...
...
@@ -215,18 +251,18 @@ while (($e = openssl_error_string()) !== false) {
215
251
</example>
216
252
217
253
<example>
218
-
<title>Creating a self-signed ECC certificate in PHP 7.1+</title>
254
+
<title>Creating a self-signed ECC certificate (as of PHP 7.1.0)</title>
219
255
<programlisting role="php">
220
256
<![CDATA[
221
257
<?php
222
258
$subject = array(
223
-
"commonName" => "docs.php.net",
259
+
"commonName" => "docs.php.net",
224
260
);
225
261

226
262
// Generate a new private (and public) key pair
227
263
$private_key = openssl_pkey_new(array(
228
-
"private_key_type" => OPENSSL_KEYTYPE_EC,
229
-
"curve_name" => 'prime256v1',
264
+
"private_key_type" => OPENSSL_KEYTYPE_EC,
265
+
"curve_name" => 'prime256v1',
230
266
));
231
267

232
268
// Generate a certificate signing request
...
...
@@ -255,7 +291,6 @@ openssl_pkey_export_to_file($private_key, 'ecc-private.key');
255
291
</refsect1>
256
292

257
293
</refentry>
258
-

259
294
<!-- Keep this comment at the end of the file
260
295
Local variables:
261
296
mode: sgml
262
297