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