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