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