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