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