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