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