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