1 | =pod
|
---|
2 | {- OpenSSL::safe::output_do_not_edit_headers(); -}
|
---|
3 |
|
---|
4 | =head1 NAME
|
---|
5 |
|
---|
6 | openssl-req - PKCS#10 certificate request and certificate generating command
|
---|
7 |
|
---|
8 | =head1 SYNOPSIS
|
---|
9 |
|
---|
10 | B<openssl> B<req>
|
---|
11 | [B<-help>]
|
---|
12 | [B<-inform> B<DER>|B<PEM>]
|
---|
13 | [B<-outform> B<DER>|B<PEM>]
|
---|
14 | [B<-in> I<filename>]
|
---|
15 | [B<-passin> I<arg>]
|
---|
16 | [B<-out> I<filename>]
|
---|
17 | [B<-passout> I<arg>]
|
---|
18 | [B<-text>]
|
---|
19 | [B<-pubkey>]
|
---|
20 | [B<-noout>]
|
---|
21 | [B<-verify>]
|
---|
22 | [B<-modulus>]
|
---|
23 | [B<-new>]
|
---|
24 | [B<-newkey> I<arg>]
|
---|
25 | [B<-pkeyopt> I<opt>:I<value>]
|
---|
26 | [B<-noenc>]
|
---|
27 | [B<-nodes>]
|
---|
28 | [B<-key> I<filename>|I<uri>]
|
---|
29 | [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
|
---|
30 | [B<-keyout> I<filename>]
|
---|
31 | [B<-keygen_engine> I<id>]
|
---|
32 | [B<-I<digest>>]
|
---|
33 | [B<-config> I<filename>]
|
---|
34 | [B<-section> I<name>]
|
---|
35 | [B<-x509>]
|
---|
36 | [B<-CA> I<filename>|I<uri>]
|
---|
37 | [B<-CAkey> I<filename>|I<uri>]
|
---|
38 | [B<-days> I<n>]
|
---|
39 | [B<-set_serial> I<n>]
|
---|
40 | [B<-newhdr>]
|
---|
41 | [B<-copy_extensions> I<arg>]
|
---|
42 | [B<-addext> I<ext>]
|
---|
43 | [B<-extensions> I<section>]
|
---|
44 | [B<-reqexts> I<section>]
|
---|
45 | [B<-precert>]
|
---|
46 | [B<-utf8>]
|
---|
47 | [B<-reqopt>]
|
---|
48 | [B<-subject>]
|
---|
49 | [B<-subj> I<arg>]
|
---|
50 | [B<-multivalue-rdn>]
|
---|
51 | [B<-sigopt> I<nm>:I<v>]
|
---|
52 | [B<-vfyopt> I<nm>:I<v>]
|
---|
53 | [B<-batch>]
|
---|
54 | [B<-verbose>]
|
---|
55 | {- $OpenSSL::safe::opt_name_synopsis -}
|
---|
56 | {- $OpenSSL::safe::opt_r_synopsis -}
|
---|
57 | {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
|
---|
58 |
|
---|
59 | =head1 DESCRIPTION
|
---|
60 |
|
---|
61 | This command primarily creates and processes certificate requests (CSRs)
|
---|
62 | in PKCS#10 format. It can additionally create self-signed certificates
|
---|
63 | for use as root CAs for example.
|
---|
64 |
|
---|
65 | =head1 OPTIONS
|
---|
66 |
|
---|
67 | =over 4
|
---|
68 |
|
---|
69 | =item B<-help>
|
---|
70 |
|
---|
71 | Print out a usage message.
|
---|
72 |
|
---|
73 | =item B<-inform> B<DER>|B<PEM>, B<-outform> B<DER>|B<PEM>
|
---|
74 |
|
---|
75 | The input and output formats; unspecified by default.
|
---|
76 | See L<openssl-format-options(1)> for details.
|
---|
77 |
|
---|
78 | The data is a PKCS#10 object.
|
---|
79 |
|
---|
80 | =item B<-in> I<filename>
|
---|
81 |
|
---|
82 | This specifies the input filename to read a request from.
|
---|
83 | This defaults to standard input unless B<-x509> or B<-CA> is specified.
|
---|
84 | A request is only read if the creation options
|
---|
85 | (B<-new> or B<-newkey> or B<-precert>) are not specified.
|
---|
86 |
|
---|
87 | =item B<-sigopt> I<nm>:I<v>
|
---|
88 |
|
---|
89 | Pass options to the signature algorithm during sign operations.
|
---|
90 | Names and values of these options are algorithm-specific.
|
---|
91 |
|
---|
92 | =item B<-vfyopt> I<nm>:I<v>
|
---|
93 |
|
---|
94 | Pass options to the signature algorithm during verify operations.
|
---|
95 | Names and values of these options are algorithm-specific.
|
---|
96 |
|
---|
97 | =begin comment
|
---|
98 |
|
---|
99 | Maybe it would be preferable to only have -opts instead of -sigopt and
|
---|
100 | -vfyopt? They are both present here to be compatible with L<openssl-ca(1)>,
|
---|
101 | which supports both options for good reasons.
|
---|
102 |
|
---|
103 | =end comment
|
---|
104 |
|
---|
105 | =item B<-passin> I<arg>
|
---|
106 |
|
---|
107 | The password source for private key and certificate input.
|
---|
108 | For more information about the format of B<arg>
|
---|
109 | see L<openssl-passphrase-options(1)>.
|
---|
110 |
|
---|
111 | =item B<-passout> I<arg>
|
---|
112 |
|
---|
113 | The password source for the output file.
|
---|
114 | For more information about the format of B<arg>
|
---|
115 | see L<openssl-passphrase-options(1)>.
|
---|
116 |
|
---|
117 | =item B<-out> I<filename>
|
---|
118 |
|
---|
119 | This specifies the output filename to write to or standard output by default.
|
---|
120 |
|
---|
121 | =item B<-text>
|
---|
122 |
|
---|
123 | Prints out the certificate request in text form.
|
---|
124 |
|
---|
125 | =item B<-subject>
|
---|
126 |
|
---|
127 | Prints out the certificate request subject
|
---|
128 | (or certificate subject if B<-x509> is in use).
|
---|
129 |
|
---|
130 | =item B<-pubkey>
|
---|
131 |
|
---|
132 | Prints out the public key.
|
---|
133 |
|
---|
134 | =item B<-noout>
|
---|
135 |
|
---|
136 | This option prevents output of the encoded version of the certificate request.
|
---|
137 |
|
---|
138 | =item B<-modulus>
|
---|
139 |
|
---|
140 | Prints out the value of the modulus of the public key contained in the request.
|
---|
141 |
|
---|
142 | =item B<-verify>
|
---|
143 |
|
---|
144 | Verifies the self-signature on the request.
|
---|
145 |
|
---|
146 | =item B<-new>
|
---|
147 |
|
---|
148 | This option generates a new certificate request. It will prompt
|
---|
149 | the user for the relevant field values. The actual fields
|
---|
150 | prompted for and their maximum and minimum sizes are specified
|
---|
151 | in the configuration file and any requested extensions.
|
---|
152 |
|
---|
153 | If the B<-key> option is not given it will generate a new private key
|
---|
154 | using information specified in the configuration file or given with
|
---|
155 | the B<-newkey> and B<-pkeyopt> options,
|
---|
156 | else by default an RSA key with 2048 bits length.
|
---|
157 |
|
---|
158 | =item B<-newkey> I<arg>
|
---|
159 |
|
---|
160 | This option is used to generate a new private key unless B<-key> is given.
|
---|
161 | It is subsequently used as if it was given using the B<-key> option.
|
---|
162 |
|
---|
163 | This option implies the B<-new> flag to create a new certificate request
|
---|
164 | or a new certificate in case B<-x509> is given.
|
---|
165 |
|
---|
166 | The argument takes one of several forms.
|
---|
167 |
|
---|
168 | [B<rsa:>]I<nbits> generates an RSA key I<nbits> in size.
|
---|
169 | If I<nbits> is omitted, i.e., B<-newkey> B<rsa> is specified,
|
---|
170 | the default key size specified in the configuration file
|
---|
171 | with the B<default_bits> option is used if present, else 2048.
|
---|
172 |
|
---|
173 | All other algorithms support the B<-newkey> I<algname>:I<file> form, where
|
---|
174 | I<file> is an algorithm parameter file, created with C<openssl genpkey -genparam>
|
---|
175 | or an X.509 certificate for a key with appropriate algorithm.
|
---|
176 |
|
---|
177 | B<param:>I<file> generates a key using the parameter file or certificate
|
---|
178 | I<file>, the algorithm is determined by the parameters.
|
---|
179 |
|
---|
180 | I<algname>[:I<file>] generates a key using the given algorithm I<algname>.
|
---|
181 | If a parameter file I<file> is given then the parameters specified there
|
---|
182 | are used, where the algorithm parameters must match I<algname>.
|
---|
183 | If algorithm parameters are not given,
|
---|
184 | any necessary parameters should be specified via the B<-pkeyopt> option.
|
---|
185 |
|
---|
186 | B<dsa:>I<filename> generates a DSA key using the parameters
|
---|
187 | in the file I<filename>. B<ec:>I<filename> generates EC key (usable both with
|
---|
188 | ECDSA or ECDH algorithms), B<gost2001:>I<filename> generates GOST R
|
---|
189 | 34.10-2001 key (requires B<gost> engine configured in the configuration
|
---|
190 | file). If just B<gost2001> is specified a parameter set should be
|
---|
191 | specified by B<-pkeyopt> I<paramset:X>
|
---|
192 |
|
---|
193 | =item B<-pkeyopt> I<opt>:I<value>
|
---|
194 |
|
---|
195 | Set the public key algorithm option I<opt> to I<value>. The precise set of
|
---|
196 | options supported depends on the public key algorithm used and its
|
---|
197 | implementation.
|
---|
198 | See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details.
|
---|
199 |
|
---|
200 | =item B<-key> I<filename>|I<uri>
|
---|
201 |
|
---|
202 | This option provides the private key for signing a new certificate or
|
---|
203 | certificate request.
|
---|
204 | Unless B<-in> is given, the corresponding public key is placed in
|
---|
205 | the new certificate or certificate request, resulting in a self-signature.
|
---|
206 |
|
---|
207 | For certificate signing this option is overridden by the B<-CA> option.
|
---|
208 |
|
---|
209 | This option also accepts PKCS#8 format private keys for PEM format files.
|
---|
210 |
|
---|
211 | =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
|
---|
212 |
|
---|
213 | The format of the private key; unspecified by default.
|
---|
214 | See L<openssl-format-options(1)> for details.
|
---|
215 |
|
---|
216 | =item B<-keyout> I<filename>
|
---|
217 |
|
---|
218 | This gives the filename to write any private key to that has been newly created
|
---|
219 | or read from B<-key>. If neither the B<-keyout> option nor the B<-key> option
|
---|
220 | are given then the filename specified in the configuration file with the
|
---|
221 | B<default_keyfile> option is used, if present. Thus, if you want to write the
|
---|
222 | private key and the B<-key> option is provided, you should provide the
|
---|
223 | B<-keyout> option explicitly. If a new key is generated and no filename is
|
---|
224 | specified the key is written to standard output.
|
---|
225 |
|
---|
226 | =item B<-noenc>
|
---|
227 |
|
---|
228 | If this option is specified then if a private key is created it
|
---|
229 | will not be encrypted.
|
---|
230 |
|
---|
231 | =item B<-nodes>
|
---|
232 |
|
---|
233 | This option is deprecated since OpenSSL 3.0; use B<-noenc> instead.
|
---|
234 |
|
---|
235 | =item B<-I<digest>>
|
---|
236 |
|
---|
237 | This specifies the message digest to sign the request.
|
---|
238 | Any digest supported by the OpenSSL B<dgst> command can be used.
|
---|
239 | This overrides the digest algorithm specified in
|
---|
240 | the configuration file.
|
---|
241 |
|
---|
242 | Some public key algorithms may override this choice. For instance, DSA
|
---|
243 | signatures always use SHA1, GOST R 34.10 signatures always use
|
---|
244 | GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest.
|
---|
245 |
|
---|
246 | =item B<-config> I<filename>
|
---|
247 |
|
---|
248 | This allows an alternative configuration file to be specified.
|
---|
249 | Optional; for a description of the default value,
|
---|
250 | see L<openssl(1)/COMMAND SUMMARY>.
|
---|
251 |
|
---|
252 | =item B<-section> I<name>
|
---|
253 |
|
---|
254 | Specifies the name of the section to use; the default is B<req>.
|
---|
255 |
|
---|
256 | =item B<-subj> I<arg>
|
---|
257 |
|
---|
258 | Sets subject name for new request or supersedes the subject name
|
---|
259 | when processing a certificate request.
|
---|
260 |
|
---|
261 | The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
|
---|
262 | Special characters may be escaped by C<\> (backslash), whitespace is retained.
|
---|
263 | Empty values are permitted, but the corresponding type will not be included
|
---|
264 | in the request.
|
---|
265 | Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
|
---|
266 | Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
|
---|
267 | between the AttributeValueAssertions (AVAs) that specify the members of the set.
|
---|
268 | Example:
|
---|
269 |
|
---|
270 | C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
|
---|
271 |
|
---|
272 | =item B<-multivalue-rdn>
|
---|
273 |
|
---|
274 | This option has been deprecated and has no effect.
|
---|
275 |
|
---|
276 | =item B<-x509>
|
---|
277 |
|
---|
278 | This option outputs a certificate instead of a certificate request.
|
---|
279 | This is typically used to generate test certificates.
|
---|
280 | It is implied by the B<-CA> option.
|
---|
281 |
|
---|
282 | This option implies the B<-new> flag if B<-in> is not given.
|
---|
283 |
|
---|
284 | If an existing request is specified with the B<-in> option, it is converted
|
---|
285 | to a certificate; otherwise a request is created from scratch.
|
---|
286 |
|
---|
287 | Unless specified using the B<-set_serial> option,
|
---|
288 | a large random number will be used for the serial number.
|
---|
289 |
|
---|
290 | Unless the B<-copy_extensions> option is used,
|
---|
291 | X.509 extensions are not copied from any provided request input file.
|
---|
292 |
|
---|
293 | X.509 extensions to be added can be specified in the configuration file
|
---|
294 | or using the B<-addext> option.
|
---|
295 |
|
---|
296 | =item B<-CA> I<filename>|I<uri>
|
---|
297 |
|
---|
298 | Specifies the "CA" certificate to be used for signing a new certificate
|
---|
299 | and implies use of B<-x509>.
|
---|
300 | When present, this behaves like a "micro CA" as follows:
|
---|
301 | The subject name of the "CA" certificate is placed as issuer name in the new
|
---|
302 | certificate, which is then signed using the "CA" key given as specified below.
|
---|
303 |
|
---|
304 | =item B<-CAkey> I<filename>|I<uri>
|
---|
305 |
|
---|
306 | Sets the "CA" private key to sign a certificate with.
|
---|
307 | The private key must match the public key of the certificate given with B<-CA>.
|
---|
308 | If this option is not provided then the key must be present in the B<-CA> input.
|
---|
309 |
|
---|
310 | =item B<-days> I<n>
|
---|
311 |
|
---|
312 | When B<-x509> is in use this specifies the number of
|
---|
313 | days to certify the certificate for, otherwise it is ignored. I<n> should
|
---|
314 | be a positive integer. The default is 30 days.
|
---|
315 |
|
---|
316 | =item B<-set_serial> I<n>
|
---|
317 |
|
---|
318 | Serial number to use when outputting a self-signed certificate.
|
---|
319 | This may be specified as a decimal value or a hex value if preceded by C<0x>.
|
---|
320 | If not given, a large random number will be used.
|
---|
321 |
|
---|
322 | =item B<-copy_extensions> I<arg>
|
---|
323 |
|
---|
324 | Determines how X.509 extensions in certificate requests should be handled
|
---|
325 | when B<-x509> is in use.
|
---|
326 | If I<arg> is B<none> or this option is not present then extensions are ignored.
|
---|
327 | If I<arg> is B<copy> or B<copyall> then
|
---|
328 | all extensions in the request are copied to the certificate.
|
---|
329 |
|
---|
330 | The main use of this option is to allow a certificate request to supply
|
---|
331 | values for certain extensions such as subjectAltName.
|
---|
332 |
|
---|
333 | =item B<-addext> I<ext>
|
---|
334 |
|
---|
335 | Add a specific extension to the certificate (if B<-x509> is in use)
|
---|
336 | or certificate request. The argument must have the form of
|
---|
337 | a key=value pair as it would appear in a config file.
|
---|
338 |
|
---|
339 | This option can be given multiple times.
|
---|
340 |
|
---|
341 | =item B<-extensions> I<section>
|
---|
342 |
|
---|
343 | =item B<-reqexts> I<section>
|
---|
344 |
|
---|
345 | These options specify alternative sections to include certificate
|
---|
346 | extensions (if B<-x509> is in use) or certificate request extensions.
|
---|
347 | This allows several different sections to
|
---|
348 | be used in the same configuration file to specify requests for
|
---|
349 | a variety of purposes.
|
---|
350 |
|
---|
351 | =item B<-precert>
|
---|
352 |
|
---|
353 | A poison extension will be added to the certificate, making it a
|
---|
354 | "pre-certificate" (see RFC6962). This can be submitted to Certificate
|
---|
355 | Transparency logs in order to obtain signed certificate timestamps (SCTs).
|
---|
356 | These SCTs can then be embedded into the pre-certificate as an extension, before
|
---|
357 | removing the poison and signing the certificate.
|
---|
358 |
|
---|
359 | This implies the B<-new> flag.
|
---|
360 |
|
---|
361 | =item B<-utf8>
|
---|
362 |
|
---|
363 | This option causes field values to be interpreted as UTF8 strings, by
|
---|
364 | default they are interpreted as ASCII. This means that the field
|
---|
365 | values, whether prompted from a terminal or obtained from a
|
---|
366 | configuration file, must be valid UTF8 strings.
|
---|
367 |
|
---|
368 | =item B<-reqopt> I<option>
|
---|
369 |
|
---|
370 | Customise the printing format used with B<-text>. The I<option> argument can be
|
---|
371 | a single option or multiple options separated by commas.
|
---|
372 |
|
---|
373 | See discussion of the B<-certopt> parameter in the L<openssl-x509(1)>
|
---|
374 | command.
|
---|
375 |
|
---|
376 | =item B<-newhdr>
|
---|
377 |
|
---|
378 | Adds the word B<NEW> to the PEM file header and footer lines on the outputted
|
---|
379 | request. Some software (Netscape certificate server) and some CAs need this.
|
---|
380 |
|
---|
381 | =item B<-batch>
|
---|
382 |
|
---|
383 | Non-interactive mode.
|
---|
384 |
|
---|
385 | =item B<-verbose>
|
---|
386 |
|
---|
387 | Print extra details about the operations being performed.
|
---|
388 |
|
---|
389 | =item B<-keygen_engine> I<id>
|
---|
390 |
|
---|
391 | Specifies an engine (by its unique I<id> string) which would be used
|
---|
392 | for key generation operations.
|
---|
393 |
|
---|
394 | {- $OpenSSL::safe::opt_name_item -}
|
---|
395 |
|
---|
396 | {- $OpenSSL::safe::opt_r_item -}
|
---|
397 |
|
---|
398 | {- $OpenSSL::safe::opt_engine_item -}
|
---|
399 |
|
---|
400 | {- $OpenSSL::safe::opt_provider_item -}
|
---|
401 |
|
---|
402 | =back
|
---|
403 |
|
---|
404 | =head1 CONFIGURATION FILE FORMAT
|
---|
405 |
|
---|
406 | The configuration options are specified in the B<req> section of
|
---|
407 | the configuration file. An alternate name be specified by using the
|
---|
408 | B<-section> option.
|
---|
409 | As with all configuration files, if no
|
---|
410 | value is specified in the specific section then
|
---|
411 | the initial unnamed or B<default> section is searched too.
|
---|
412 |
|
---|
413 | The options available are described in detail below.
|
---|
414 |
|
---|
415 | =over 4
|
---|
416 |
|
---|
417 | =item B<input_password>, B<output_password>
|
---|
418 |
|
---|
419 | The passwords for the input private key file (if present) and
|
---|
420 | the output private key file (if one will be created). The
|
---|
421 | command line options B<passin> and B<passout> override the
|
---|
422 | configuration file values.
|
---|
423 |
|
---|
424 | =item B<default_bits>
|
---|
425 |
|
---|
426 | Specifies the default key size in bits.
|
---|
427 |
|
---|
428 | This option is used in conjunction with the B<-new> option to generate
|
---|
429 | a new key. It can be overridden by specifying an explicit key size in
|
---|
430 | the B<-newkey> option. The smallest accepted key size is 512 bits. If
|
---|
431 | no key size is specified then 2048 bits is used.
|
---|
432 |
|
---|
433 | =item B<default_keyfile>
|
---|
434 |
|
---|
435 | This is the default filename to write a private key to. If not
|
---|
436 | specified the key is written to standard output. This can be
|
---|
437 | overridden by the B<-keyout> option.
|
---|
438 |
|
---|
439 | =item B<oid_file>
|
---|
440 |
|
---|
441 | This specifies a file containing additional B<OBJECT IDENTIFIERS>.
|
---|
442 | Each line of the file should consist of the numerical form of the
|
---|
443 | object identifier followed by whitespace then the short name followed
|
---|
444 | by whitespace and finally the long name.
|
---|
445 |
|
---|
446 | =item B<oid_section>
|
---|
447 |
|
---|
448 | This specifies a section in the configuration file containing extra
|
---|
449 | object identifiers. Each line should consist of the short name of the
|
---|
450 | object identifier followed by B<=> and the numerical form. The short
|
---|
451 | and long names are the same when this option is used.
|
---|
452 |
|
---|
453 | =item B<RANDFILE>
|
---|
454 |
|
---|
455 | At startup the specified file is loaded into the random number generator,
|
---|
456 | and at exit 256 bytes will be written to it.
|
---|
457 | It is used for private key generation.
|
---|
458 |
|
---|
459 | =item B<encrypt_key>
|
---|
460 |
|
---|
461 | If this is set to B<no> then if a private key is generated it is
|
---|
462 | B<not> encrypted. This is equivalent to the B<-noenc> command line
|
---|
463 | option. For compatibility B<encrypt_rsa_key> is an equivalent option.
|
---|
464 |
|
---|
465 | =item B<default_md>
|
---|
466 |
|
---|
467 | This option specifies the digest algorithm to use. Any digest supported by the
|
---|
468 | OpenSSL B<dgst> command can be used. This option can be overridden on the
|
---|
469 | command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
|
---|
470 | any digest that has been set.
|
---|
471 |
|
---|
472 | =item B<string_mask>
|
---|
473 |
|
---|
474 | This option masks out the use of certain string types in certain
|
---|
475 | fields. Most users will not need to change this option.
|
---|
476 |
|
---|
477 | It can be set to several values B<default> which is also the default
|
---|
478 | option uses PrintableStrings, T61Strings and BMPStrings if the
|
---|
479 | B<pkix> value is used then only PrintableStrings and BMPStrings will
|
---|
480 | be used. This follows the PKIX recommendation in RFC2459. If the
|
---|
481 | B<utf8only> option is used then only UTF8Strings will be used: this
|
---|
482 | is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
|
---|
483 | option just uses PrintableStrings and T61Strings: certain software has
|
---|
484 | problems with BMPStrings and UTF8Strings: in particular Netscape.
|
---|
485 |
|
---|
486 | =item B<req_extensions>
|
---|
487 |
|
---|
488 | This specifies the configuration file section containing a list of
|
---|
489 | extensions to add to the certificate request. It can be overridden
|
---|
490 | by the B<-reqexts> command line switch. See the
|
---|
491 | L<x509v3_config(5)> manual page for details of the
|
---|
492 | extension section format.
|
---|
493 |
|
---|
494 | =item B<x509_extensions>
|
---|
495 |
|
---|
496 | This specifies the configuration file section containing a list of
|
---|
497 | extensions to add to certificate generated when B<-x509> is in use.
|
---|
498 | It can be overridden by the B<-extensions> command line switch.
|
---|
499 |
|
---|
500 | =item B<prompt>
|
---|
501 |
|
---|
502 | If set to the value B<no> this disables prompting of certificate fields
|
---|
503 | and just takes values from the config file directly. It also changes the
|
---|
504 | expected format of the B<distinguished_name> and B<attributes> sections.
|
---|
505 |
|
---|
506 | =item B<utf8>
|
---|
507 |
|
---|
508 | If set to the value B<yes> then field values to be interpreted as UTF8
|
---|
509 | strings, by default they are interpreted as ASCII. This means that
|
---|
510 | the field values, whether prompted from a terminal or obtained from a
|
---|
511 | configuration file, must be valid UTF8 strings.
|
---|
512 |
|
---|
513 | =item B<attributes>
|
---|
514 |
|
---|
515 | This specifies the section containing any request attributes: its format
|
---|
516 | is the same as B<distinguished_name>. Typically these may contain the
|
---|
517 | challengePassword or unstructuredName types. They are currently ignored
|
---|
518 | by OpenSSL's request signing utilities but some CAs might want them.
|
---|
519 |
|
---|
520 | =item B<distinguished_name>
|
---|
521 |
|
---|
522 | This specifies the section containing the distinguished name fields to
|
---|
523 | prompt for when generating a certificate or certificate request. The format
|
---|
524 | is described in the next section.
|
---|
525 |
|
---|
526 | =back
|
---|
527 |
|
---|
528 | =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
|
---|
529 |
|
---|
530 | There are two separate formats for the distinguished name and attribute
|
---|
531 | sections. If the B<prompt> option is set to B<no> then these sections
|
---|
532 | just consist of field names and values: for example,
|
---|
533 |
|
---|
534 | CN=My Name
|
---|
535 | OU=My Organization
|
---|
536 | [email protected]
|
---|
537 |
|
---|
538 | This allows external programs (e.g. GUI based) to generate a template file with
|
---|
539 | all the field names and values and just pass it to this command. An example
|
---|
540 | of this kind of configuration file is contained in the B<EXAMPLES> section.
|
---|
541 |
|
---|
542 | Alternatively if the B<prompt> option is absent or not set to B<no> then the
|
---|
543 | file contains field prompting information. It consists of lines of the form:
|
---|
544 |
|
---|
545 | fieldName="prompt"
|
---|
546 | fieldName_default="default field value"
|
---|
547 | fieldName_min= 2
|
---|
548 | fieldName_max= 4
|
---|
549 |
|
---|
550 | "fieldName" is the field name being used, for example commonName (or CN).
|
---|
551 | The "prompt" string is used to ask the user to enter the relevant
|
---|
552 | details. If the user enters nothing then the default value is used if no
|
---|
553 | default value is present then the field is omitted. A field can
|
---|
554 | still be omitted if a default value is present if the user just
|
---|
555 | enters the '.' character.
|
---|
556 |
|
---|
557 | The number of characters entered must be between the fieldName_min and
|
---|
558 | fieldName_max limits: there may be additional restrictions based
|
---|
559 | on the field being used (for example countryName can only ever be
|
---|
560 | two characters long and must fit in a PrintableString).
|
---|
561 |
|
---|
562 | Some fields (such as organizationName) can be used more than once
|
---|
563 | in a DN. This presents a problem because configuration files will
|
---|
564 | not recognize the same name occurring twice. To avoid this problem
|
---|
565 | if the fieldName contains some characters followed by a full stop
|
---|
566 | they will be ignored. So for example a second organizationName can
|
---|
567 | be input by calling it "1.organizationName".
|
---|
568 |
|
---|
569 | The actual permitted field names are any object identifier short or
|
---|
570 | long names. These are compiled into OpenSSL and include the usual
|
---|
571 | values such as commonName, countryName, localityName, organizationName,
|
---|
572 | organizationalUnitName, stateOrProvinceName. Additionally emailAddress
|
---|
573 | is included as well as name, surname, givenName, initials, and dnQualifier.
|
---|
574 |
|
---|
575 | Additional object identifiers can be defined with the B<oid_file> or
|
---|
576 | B<oid_section> options in the configuration file. Any additional fields
|
---|
577 | will be treated as though they were a DirectoryString.
|
---|
578 |
|
---|
579 |
|
---|
580 | =head1 EXAMPLES
|
---|
581 |
|
---|
582 | Examine and verify certificate request:
|
---|
583 |
|
---|
584 | openssl req -in req.pem -text -verify -noout
|
---|
585 |
|
---|
586 | Create a private key and then generate a certificate request from it:
|
---|
587 |
|
---|
588 | openssl genrsa -out key.pem 2048
|
---|
589 | openssl req -new -key key.pem -out req.pem
|
---|
590 |
|
---|
591 | The same but just using req:
|
---|
592 |
|
---|
593 | openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
|
---|
594 |
|
---|
595 | Generate a self-signed root certificate:
|
---|
596 |
|
---|
597 | openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
|
---|
598 |
|
---|
599 | Create an SM2 private key and then generate a certificate request from it:
|
---|
600 |
|
---|
601 | openssl ecparam -genkey -name SM2 -out sm2.key
|
---|
602 | openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "distid:1234567812345678"
|
---|
603 |
|
---|
604 | Examine and verify an SM2 certificate request:
|
---|
605 |
|
---|
606 | openssl req -verify -in sm2.csr -sm3 -vfyopt "distid:1234567812345678"
|
---|
607 |
|
---|
608 | Example of a file pointed to by the B<oid_file> option:
|
---|
609 |
|
---|
610 | 1.2.3.4 shortName A longer Name
|
---|
611 | 1.2.3.6 otherName Other longer Name
|
---|
612 |
|
---|
613 | Example of a section pointed to by B<oid_section> making use of variable
|
---|
614 | expansion:
|
---|
615 |
|
---|
616 | testoid1=1.2.3.5
|
---|
617 | testoid2=${testoid1}.6
|
---|
618 |
|
---|
619 | Sample configuration file prompting for field values:
|
---|
620 |
|
---|
621 | [ req ]
|
---|
622 | default_bits = 2048
|
---|
623 | default_keyfile = privkey.pem
|
---|
624 | distinguished_name = req_distinguished_name
|
---|
625 | attributes = req_attributes
|
---|
626 | req_extensions = v3_ca
|
---|
627 |
|
---|
628 | dirstring_type = nobmp
|
---|
629 |
|
---|
630 | [ req_distinguished_name ]
|
---|
631 | countryName = Country Name (2 letter code)
|
---|
632 | countryName_default = AU
|
---|
633 | countryName_min = 2
|
---|
634 | countryName_max = 2
|
---|
635 |
|
---|
636 | localityName = Locality Name (eg, city)
|
---|
637 |
|
---|
638 | organizationalUnitName = Organizational Unit Name (eg, section)
|
---|
639 |
|
---|
640 | commonName = Common Name (eg, YOUR name)
|
---|
641 | commonName_max = 64
|
---|
642 |
|
---|
643 | emailAddress = Email Address
|
---|
644 | emailAddress_max = 40
|
---|
645 |
|
---|
646 | [ req_attributes ]
|
---|
647 | challengePassword = A challenge password
|
---|
648 | challengePassword_min = 4
|
---|
649 | challengePassword_max = 20
|
---|
650 |
|
---|
651 | [ v3_ca ]
|
---|
652 |
|
---|
653 | subjectKeyIdentifier=hash
|
---|
654 | authorityKeyIdentifier=keyid:always,issuer:always
|
---|
655 | basicConstraints = critical, CA:true
|
---|
656 |
|
---|
657 | Sample configuration containing all field values:
|
---|
658 |
|
---|
659 |
|
---|
660 | [ req ]
|
---|
661 | default_bits = 2048
|
---|
662 | default_keyfile = keyfile.pem
|
---|
663 | distinguished_name = req_distinguished_name
|
---|
664 | attributes = req_attributes
|
---|
665 | prompt = no
|
---|
666 | output_password = mypass
|
---|
667 |
|
---|
668 | [ req_distinguished_name ]
|
---|
669 | C = GB
|
---|
670 | ST = Test State or Province
|
---|
671 | L = Test Locality
|
---|
672 | O = Organization Name
|
---|
673 | OU = Organizational Unit Name
|
---|
674 | CN = Common Name
|
---|
675 | emailAddress = [email protected]
|
---|
676 |
|
---|
677 | [ req_attributes ]
|
---|
678 | challengePassword = A challenge password
|
---|
679 |
|
---|
680 | Example of giving the most common attributes (subject and extensions)
|
---|
681 | on the command line:
|
---|
682 |
|
---|
683 | openssl req -new -subj "/C=GB/CN=foo" \
|
---|
684 | -addext "subjectAltName = DNS:foo.co.uk" \
|
---|
685 | -addext "certificatePolicies = 1.2.3.4" \
|
---|
686 | -newkey rsa:2048 -keyout key.pem -out req.pem
|
---|
687 |
|
---|
688 |
|
---|
689 | =head1 NOTES
|
---|
690 |
|
---|
691 | The certificate requests generated by B<Xenroll> with MSIE have extensions
|
---|
692 | added. It includes the B<keyUsage> extension which determines the type of
|
---|
693 | key (signature only or general purpose) and any additional OIDs entered
|
---|
694 | by the script in an B<extendedKeyUsage> extension.
|
---|
695 |
|
---|
696 | =head1 DIAGNOSTICS
|
---|
697 |
|
---|
698 | The following messages are frequently asked about:
|
---|
699 |
|
---|
700 | Using configuration from /some/path/openssl.cnf
|
---|
701 | Unable to load config info
|
---|
702 |
|
---|
703 | This is followed some time later by:
|
---|
704 |
|
---|
705 | unable to find 'distinguished_name' in config
|
---|
706 | problems making Certificate Request
|
---|
707 |
|
---|
708 | The first error message is the clue: it can't find the configuration
|
---|
709 | file! Certain operations (like examining a certificate request) don't
|
---|
710 | need a configuration file so its use isn't enforced. Generation of
|
---|
711 | certificates or requests however does need a configuration file. This
|
---|
712 | could be regarded as a bug.
|
---|
713 |
|
---|
714 | Another puzzling message is this:
|
---|
715 |
|
---|
716 | Attributes:
|
---|
717 | a0:00
|
---|
718 |
|
---|
719 | this is displayed when no attributes are present and the request includes
|
---|
720 | the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
|
---|
721 | 0x00). If you just see:
|
---|
722 |
|
---|
723 | Attributes:
|
---|
724 |
|
---|
725 | then the B<SET OF> is missing and the encoding is technically invalid (but
|
---|
726 | it is tolerated). See the description of the command line option B<-asn1-kludge>
|
---|
727 | for more information.
|
---|
728 |
|
---|
729 | =head1 BUGS
|
---|
730 |
|
---|
731 | OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
|
---|
732 | treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
|
---|
733 | This can cause problems if you need characters that aren't available in
|
---|
734 | PrintableStrings and you don't want to or can't use BMPStrings.
|
---|
735 |
|
---|
736 | As a consequence of the T61String handling the only correct way to represent
|
---|
737 | accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
|
---|
738 | currently chokes on these. If you have to use accented characters with Netscape
|
---|
739 | and MSIE then you currently need to use the invalid T61String form.
|
---|
740 |
|
---|
741 | The current prompting is not very friendly. It doesn't allow you to confirm what
|
---|
742 | you've just entered. Other things like extensions in certificate requests are
|
---|
743 | statically defined in the configuration file. Some of these: like an email
|
---|
744 | address in subjectAltName should be input by the user.
|
---|
745 |
|
---|
746 | =head1 SEE ALSO
|
---|
747 |
|
---|
748 | L<openssl(1)>,
|
---|
749 | L<openssl-x509(1)>,
|
---|
750 | L<openssl-ca(1)>,
|
---|
751 | L<openssl-genrsa(1)>,
|
---|
752 | L<openssl-gendsa(1)>,
|
---|
753 | L<config(5)>,
|
---|
754 | L<x509v3_config(5)>
|
---|
755 |
|
---|
756 | =head1 HISTORY
|
---|
757 |
|
---|
758 | The B<-section> option was added in OpenSSL 3.0.0.
|
---|
759 |
|
---|
760 | The B<-multivalue-rdn> option has become obsolete in OpenSSL 3.0.0 and
|
---|
761 | has no effect.
|
---|
762 |
|
---|
763 | The B<-engine> option was deprecated in OpenSSL 3.0.
|
---|
764 | The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
|
---|
765 |
|
---|
766 | =head1 COPYRIGHT
|
---|
767 |
|
---|
768 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
|
---|
769 |
|
---|
770 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
---|
771 | this file except in compliance with the License. You can obtain a copy
|
---|
772 | in the file LICENSE in the source distribution or at
|
---|
773 | L<https://www.openssl.org/source/license.html>.
|
---|
774 |
|
---|
775 | =cut
|
---|