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