reference/openssl/functions/openssl-csr-new.xml
f0d11929d41082d71dcf8338a18e04412c656fa0
...
...
@@ -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>bool</type></type><methodname>openssl_csr_new</methodname>
13
+
<methodparam><type>array</type><parameter>distinguished_names</parameter></methodparam>
14
+
<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type class="union"><type>OpenSSLAsymmetricKey</type><type>null</type></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,36 +27,42 @@
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
-
The Distinguished Name or subject fields to be used in the certificate.
33
+
The Distinguished Name or subject fields to be included in the
34
+
certificate. The <parameter>distinguished_names</parameter> is an
35
+
associative array where the keys represent the attribute names of
36
+
Distinguished Names and the values can either be strings (for single
37
+
value) or arrays (if multiple values need to be set).
34
38
</para>
35
39
</listitem>
36
40
</varlistentry>
37
41
<varlistentry>
38
-
<term><parameter>privkey</parameter></term>
42
+
<term><parameter>private_key</parameter></term>
39
43
<listitem>
40
44
<para>
41
-
<parameter>privkey</parameter> should be set to a private key that was
42
-
previously generated by <function>openssl_pkey_new</function> (or
43
-
otherwise obtained from the other openssl_pkey family of functions).
44
-
The corresponding public portion of the key will be used to sign the
45
-
CSR.
45
+
<parameter>private_key</parameter> should be set to a private key that
46
+
was previously generated by <function>openssl_pkey_new</function> (or
47
+
otherwise obtained from the other openssl_pkey family of functions), or
48
+
&null; variable. If its value is &null; variable, a new private key is
49
+
generated based on the supplied <parameter>options</parameter> and
50
+
assigned to supplied variable. The corresponding public portion of the
51
+
key will be used to sign the <acronym>CSR</acronym>.
46
52
</para>
47
53
</listitem>
48
54
</varlistentry>
49
55
<varlistentry>
50
-
<term><parameter>configargs</parameter></term>
56
+
<term><parameter>options</parameter></term>
51
57
<listitem>
52
58
<para>
53
59
By default, the information in your system <literal>openssl.conf</literal>
54
60
is used to initialize the request; you can specify a configuration file
55
-
section by setting the <literal>config_section_section</literal> key of
56
-
<parameter>configargs</parameter>. You can also specify an alternative
57
-
openssl configuration file by setting the value of the
61
+
section by setting the <literal>config_section_section</literal> key in
62
+
<parameter>options</parameter>. You can also specify an alternative
63
+
OpenSSL configuration file by setting the value of the
58
64
<literal>config</literal> key to the path of the file you want to use.
59
-
The following keys, if present in <parameter>configargs</parameter>
65
+
The following keys, if present in <parameter>options</parameter>
60
66
behave as their equivalents in the <literal>openssl.conf</literal>, as
61
67
listed in the table below.
62
68
<table>
...
...
@@ -64,7 +70,7 @@
64
70
<tgroup cols="3">
65
71
<thead>
66
72
<row>
67
-
<entry><parameter>configargs</parameter> key</entry>
73
+
<entry><parameter>options</parameter> key</entry>
68
74
<entry>type</entry>
69
75
<entry><literal>openssl.conf</literal> equivalent</entry>
70
76
<entry>description</entry>
...
...
@@ -88,18 +94,17 @@
88
94
<entry>req_extensions</entry>
89
95
<entry><type>string</type></entry>
90
96
<entry>req_extensions</entry>
91
-
<entry>Selects which extensions should be used when creating a CSR</entry>
97
+
<entry>Selects which extensions should be used when creating a <acronym>CSR</acronym></entry>
92
98
</row>
93
99
<row>
94
100
<entry>private_key_bits</entry>
95
-
<entry><type>integer</type></entry>
101
+
<entry><type>int</type></entry>
96
102
<entry>default_bits</entry>
97
-
<entry>Specifies how many bits should be used to generate a private
98
-
key</entry>
103
+
<entry>Specifies how many bits should be used to generate a private key</entry>
99
104
</row>
100
105
<row>
101
106
<entry>private_key_type</entry>
102
-
<entry><type>integer</type></entry>
107
+
<entry><type>int</type></entry>
103
108
<entry>none</entry>
104
109
<entry>Specifies the type of private key to create. This can be one
105
110
of <constant>OPENSSL_KEYTYPE_DSA</constant>,
...
...
@@ -111,13 +116,13 @@
111
116
</row>
112
117
<row>
113
118
<entry>encrypt_key</entry>
114
-
<entry><type>boolean</type></entry>
119
+
<entry><type>bool</type></entry>
115
120
<entry>encrypt_key</entry>
116
121
<entry>Should an exported key (with passphrase) be encrypted?</entry>
117
122
</row>
118
123
<row>
119
124
<entry>encrypt_key_cipher</entry>
120
-
<entry><type>integer</type></entry>
125
+
<entry><type>int</type></entry>
121
126
<entry>none</entry>
122
127
<entry>
123
128
One of <link linkend="openssl.ciphers">cipher constants</link>.
...
...
@@ -128,7 +133,7 @@
128
133
<entry><type>string</type></entry>
129
134
<entry>none</entry>
130
135
<entry>
131
-
PHP 7.1+, One of <function>openssl_get_curve_names</function>.
136
+
One of <function>openssl_get_curve_names</function>.
132
137
</entry>
133
138
</row>
134
139
<row>
...
...
@@ -146,13 +151,13 @@
146
151
</listitem>
147
152
</varlistentry>
148
153
<varlistentry>
149
-
<term><parameter>extraattribs</parameter></term>
154
+
<term><parameter>extra_attributes</parameter></term>
150
155
<listitem>
151
156
<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
155
-
converted to OIDs and applied to the relevant part of the request.
157
+
<parameter>extra_attributes</parameter> is used to specify additional
158
+
attributes for the <acronym>CSR</acronym>. It is an associative arrays
159
+
where the keys are converted to OIDs and applied as
160
+
<acronym>CSR</acronym> attributes.
156
161
</para>
157
162
</listitem>
158
163
</varlistentry>
...
...
@@ -163,10 +168,62 @@
163
168
<refsect1 role="returnvalues">
164
169
&reftitle.returnvalues;
165
170
<para>
166
-
Returns the CSR&return.falseforfailure;.
171
+
Returns the <acronym>CSR</acronym> on success, &true; if
172
+
<acronym>CSR</acronym> creation is successful but signing
173
+
fails&return.falseforfailure;.
167
174
</para>
168
175
</refsect1>
169
176

177
+
<refsect1 role="changelog">
178
+
&reftitle.changelog;
179
+
<informaltable>
180
+
<tgroup cols="2">
181
+
<thead>
182
+
<row>
183
+
<entry>&Version;</entry>
184
+
<entry>&Description;</entry>
185
+
</row>
186
+
</thead>
187
+
<tbody>
188
+
<row>
189
+
<entry>8.4.0</entry>
190
+
<entry>
191
+
The <parameter>distinguished_names</parameter> associative array now supports arrays as values,
192
+
allowing multiple values to be specified for a single attribute.
193
+
</entry>
194
+
</row>
195
+
<row>
196
+
<entry>8.4.0</entry>
197
+
<entry>
198
+
The <parameter>extra_attributes</parameter> parameter now correctly sets the CSR attributes,
199
+
rather than modifying the subject's Distinguished Name as it previously did incorrectly.
200
+
</entry>
201
+
</row>
202
+
<row>
203
+
<entry>8.0.0</entry>
204
+
<entry>
205
+
On success, this function returns an <classname>OpenSSLCertificateSigningRequest</classname> instance now;
206
+
previously, a &resource; of type <literal>OpenSSL X.509 CSR</literal> was returned.
207
+
</entry>
208
+
</row>
209
+
<row>
210
+
<entry>8.0.0</entry>
211
+
<entry>
212
+
<parameter>private_key</parameter> accepts an <classname>OpenSSLAsymmetricKey</classname> instance now;
213
+
previously, a &resource; of type <literal>OpenSSL key</literal> was accepted.
214
+
</entry>
215
+
</row>
216
+
<row>
217
+
<entry>7.1.0</entry>
218
+
<entry>
219
+
<parameter>options</parameter> now also supports <literal>curve_name</literal>.
220
+
</entry>
221
+
</row>
222
+
</tbody>
223
+
</tgroup>
224
+
</informaltable>
225
+
</refsect1>
226
+

170
227
<refsect1 role="examples">
171
228
&reftitle.examples;
172
229
<para>
...
...
@@ -215,18 +272,18 @@ while (($e = openssl_error_string()) !== false) {
215
272
</example>
216
273
217
274
<example>
218
-
<title>Creating a self-signed ECC certificate in PHP 7.1+</title>
275
+
<title>Creating a self-signed ECC certificate (as of PHP 7.1.0)</title>
219
276
<programlisting role="php">
220
277
<![CDATA[
221
278
<?php
222
279
$subject = array(
223
-
"commonName" => "docs.php.net",
280
+
"commonName" => "docs.php.net",
224
281
);
225
282

226
283
// Generate a new private (and public) key pair
227
284
$private_key = openssl_pkey_new(array(
228
-
"private_key_type" => OPENSSL_KEYTYPE_EC,
229
-
"curve_name" => 'prime256v1',
285
+
"private_key_type" => OPENSSL_KEYTYPE_EC,
286
+
"curve_name" => 'prime256v1',
230
287
));
231
288

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

257
314
</refentry>
258
-

259
315
<!-- Keep this comment at the end of the file
260
316
Local variables:
261
317
mode: sgml
262
318



Translation status