Regenerate the manual pages after the OpenSSL update to 0.9.7e.
[dragonfly.git] / secure / usr.bin / openssl / man / req.1
CommitLineData
8b0cefbb
JR
1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
984263bc 32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb
JR
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
984263bc 66.if n .na
8b0cefbb
JR
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "REQ 1"
132.TH REQ 1 "2004-12-18" "0.9.7e" "OpenSSL"
984263bc
MD
133.SH "NAME"
134req \- PKCS#10 certificate request and certificate generating utility.
135.SH "SYNOPSIS"
8b0cefbb
JR
136.IX Header "SYNOPSIS"
137\&\fBopenssl\fR \fBreq\fR
984263bc
MD
138[\fB\-inform PEM|DER\fR]
139[\fB\-outform PEM|DER\fR]
140[\fB\-in filename\fR]
141[\fB\-passin arg\fR]
142[\fB\-out filename\fR]
143[\fB\-passout arg\fR]
144[\fB\-text\fR]
145[\fB\-pubkey\fR]
146[\fB\-noout\fR]
147[\fB\-verify\fR]
148[\fB\-modulus\fR]
149[\fB\-new\fR]
e3cdf75b 150[\fB\-rand file(s)\fR]
984263bc
MD
151[\fB\-newkey rsa:bits\fR]
152[\fB\-newkey dsa:file\fR]
153[\fB\-nodes\fR]
154[\fB\-key filename\fR]
155[\fB\-keyform PEM|DER\fR]
156[\fB\-keyout filename\fR]
157[\fB\-[md5|sha1|md2|mdc2]\fR]
158[\fB\-config filename\fR]
159[\fB\-subj arg\fR]
160[\fB\-x509\fR]
161[\fB\-days n\fR]
162[\fB\-set_serial n\fR]
8b0cefbb 163[\fB\-asn1\-kludge\fR]
984263bc
MD
164[\fB\-newhdr\fR]
165[\fB\-extensions section\fR]
166[\fB\-reqexts section\fR]
167[\fB\-utf8\fR]
168[\fB\-nameopt\fR]
169[\fB\-batch\fR]
170[\fB\-verbose\fR]
171[\fB\-engine id\fR]
172.SH "DESCRIPTION"
8b0cefbb 173.IX Header "DESCRIPTION"
984263bc
MD
174The \fBreq\fR command primarily creates and processes certificate requests
175in PKCS#10 format. It can additionally create self signed certificates
176for use as root CAs for example.
177.SH "COMMAND OPTIONS"
8b0cefbb
JR
178.IX Header "COMMAND OPTIONS"
179.IP "\fB\-inform DER|PEM\fR" 4
180.IX Item "-inform DER|PEM"
984263bc 181This specifies the input format. The \fB\s-1DER\s0\fR option uses an \s-1ASN1\s0 \s-1DER\s0 encoded
8b0cefbb 182form compatible with the PKCS#10. The \fB\s-1PEM\s0\fR form is the default format: it
984263bc
MD
183consists of the \fB\s-1DER\s0\fR format base64 encoded with additional header and
184footer lines.
8b0cefbb
JR
185.IP "\fB\-outform DER|PEM\fR" 4
186.IX Item "-outform DER|PEM"
984263bc 187This specifies the output format, the options have the same meaning as the
8b0cefbb
JR
188\&\fB\-inform\fR option.
189.IP "\fB\-in filename\fR" 4
190.IX Item "-in filename"
984263bc
MD
191This specifies the input filename to read a request from or standard input
192if this option is not specified. A request is only read if the creation
193options (\fB\-new\fR and \fB\-newkey\fR) are not specified.
8b0cefbb
JR
194.IP "\fB\-passin arg\fR" 4
195.IX Item "-passin arg"
984263bc 196the input file password source. For more information about the format of \fBarg\fR
8b0cefbb
JR
197see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
198.IP "\fB\-out filename\fR" 4
199.IX Item "-out filename"
984263bc
MD
200This specifies the output filename to write to or standard output by
201default.
8b0cefbb
JR
202.IP "\fB\-passout arg\fR" 4
203.IX Item "-passout arg"
984263bc 204the output file password source. For more information about the format of \fBarg\fR
8b0cefbb
JR
205see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in \fIopenssl\fR\|(1).
206.IP "\fB\-text\fR" 4
207.IX Item "-text"
984263bc 208prints out the certificate request in text form.
8b0cefbb
JR
209.IP "\fB\-pubkey\fR" 4
210.IX Item "-pubkey"
984263bc 211outputs the public key.
8b0cefbb
JR
212.IP "\fB\-noout\fR" 4
213.IX Item "-noout"
984263bc 214this option prevents output of the encoded version of the request.
8b0cefbb
JR
215.IP "\fB\-modulus\fR" 4
216.IX Item "-modulus"
984263bc
MD
217this option prints out the value of the modulus of the public key
218contained in the request.
8b0cefbb
JR
219.IP "\fB\-verify\fR" 4
220.IX Item "-verify"
984263bc 221verifies the signature on the request.
8b0cefbb
JR
222.IP "\fB\-new\fR" 4
223.IX Item "-new"
984263bc
MD
224this option generates a new certificate request. It will prompt
225the user for the relevant field values. The actual fields
226prompted for and their maximum and minimum sizes are specified
227in the configuration file and any requested extensions.
228.Sp
229If the \fB\-key\fR option is not used it will generate a new \s-1RSA\s0 private
230key using information specified in the configuration file.
8b0cefbb
JR
231.IP "\fB\-rand file(s)\fR" 4
232.IX Item "-rand file(s)"
984263bc 233a file or files containing random data used to seed the random number
8b0cefbb
JR
234generator, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)).
235Multiple files can be specified separated by a OS-dependent character.
236The separator is \fB;\fR for MS\-Windows, \fB,\fR for OpenVMS, and \fB:\fR for
984263bc 237all others.
8b0cefbb
JR
238.IP "\fB\-newkey arg\fR" 4
239.IX Item "-newkey arg"
984263bc
MD
240this option creates a new certificate request and a new private
241key. The argument takes one of two forms. \fBrsa:nbits\fR, where
8b0cefbb 242\&\fBnbits\fR is the number of bits, generates an \s-1RSA\s0 key \fBnbits\fR
984263bc
MD
243in size. \fBdsa:filename\fR generates a \s-1DSA\s0 key using the parameters
244in the file \fBfilename\fR.
8b0cefbb
JR
245.IP "\fB\-key filename\fR" 4
246.IX Item "-key filename"
984263bc 247This specifies the file to read the private key from. It also
8b0cefbb
JR
248accepts PKCS#8 format private keys for \s-1PEM\s0 format files.
249.IP "\fB\-keyform PEM|DER\fR" 4
250.IX Item "-keyform PEM|DER"
984263bc
MD
251the format of the private key file specified in the \fB\-key\fR
252argument. \s-1PEM\s0 is the default.
8b0cefbb
JR
253.IP "\fB\-keyout filename\fR" 4
254.IX Item "-keyout filename"
984263bc
MD
255this gives the filename to write the newly created private key to.
256If this option is not specified then the filename present in the
257configuration file is used.
8b0cefbb
JR
258.IP "\fB\-nodes\fR" 4
259.IX Item "-nodes"
984263bc
MD
260if this option is specified then if a private key is created it
261will not be encrypted.
8b0cefbb
JR
262.IP "\fB\-[md5|sha1|md2|mdc2]\fR" 4
263.IX Item "-[md5|sha1|md2|mdc2]"
984263bc
MD
264this specifies the message digest to sign the request with. This
265overrides the digest algorithm specified in the configuration file.
266This option is ignored for \s-1DSA\s0 requests: they always use \s-1SHA1\s0.
8b0cefbb
JR
267.IP "\fB\-config filename\fR" 4
268.IX Item "-config filename"
984263bc
MD
269this allows an alternative configuration file to be specified,
270this overrides the compile time filename or any specified in
271the \fB\s-1OPENSSL_CONF\s0\fR environment variable.
8b0cefbb
JR
272.IP "\fB\-subj arg\fR" 4
273.IX Item "-subj arg"
984263bc
MD
274sets subject name for new request or supersedes the subject name
275when processing a request.
276The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR,
277characters may be escaped by \e (backslash), no spaces are skipped.
8b0cefbb
JR
278.IP "\fB\-x509\fR" 4
279.IX Item "-x509"
984263bc
MD
280this option outputs a self signed certificate instead of a certificate
281request. This is typically used to generate a test certificate or
282a self signed root \s-1CA\s0. The extensions added to the certificate
283(if any) are specified in the configuration file. Unless specified
284using the \fBset_serial\fR option \fB0\fR will be used for the serial
285number.
8b0cefbb
JR
286.IP "\fB\-days n\fR" 4
287.IX Item "-days n"
984263bc
MD
288when the \fB\-x509\fR option is being used this specifies the number of
289days to certify the certificate for. The default is 30 days.
8b0cefbb
JR
290.IP "\fB\-set_serial n\fR" 4
291.IX Item "-set_serial n"
984263bc
MD
292serial number to use when outputting a self signed certificate. This
293may be specified as a decimal value or a hex value if preceded by \fB0x\fR.
294It is possible to use negative serial numbers but this is not recommended.
8b0cefbb
JR
295.IP "\fB\-extensions section\fR" 4
296.IX Item "-extensions section"
297.PD 0
298.IP "\fB\-reqexts section\fR" 4
299.IX Item "-reqexts section"
300.PD
984263bc
MD
301these options specify alternative sections to include certificate
302extensions (if the \fB\-x509\fR option is present) or certificate
303request extensions. This allows several different sections to
304be used in the same configuration file to specify requests for
305a variety of purposes.
8b0cefbb
JR
306.IP "\fB\-utf8\fR" 4
307.IX Item "-utf8"
984263bc
MD
308this option causes field values to be interpreted as \s-1UTF8\s0 strings, by
309default they are interpreted as \s-1ASCII\s0. This means that the field
310values, whether prompted from a terminal or obtained from a
311configuration file, must be valid \s-1UTF8\s0 strings.
8b0cefbb
JR
312.IP "\fB\-nameopt option\fR" 4
313.IX Item "-nameopt option"
984263bc 314option which determines how the subject or issuer names are displayed. The
8b0cefbb 315\&\fBoption\fR argument can be a single option or multiple options separated by
984263bc 316commas. Alternatively the \fB\-nameopt\fR switch may be used more than once to
8b0cefbb
JR
317set multiple options. See the \fIx509\fR\|(1) manual page for details.
318.IP "\fB\-asn1\-kludge\fR" 4
319.IX Item "-asn1-kludge"
984263bc 320by default the \fBreq\fR command outputs certificate requests containing
8b0cefbb 321no attributes in the correct PKCS#10 format. However certain CAs will only
984263bc
MD
322accept requests containing no attributes in an invalid form: this
323option produces this invalid format.
324.Sp
8b0cefbb 325More precisely the \fBAttributes\fR in a PKCS#10 certificate request
984263bc
MD
326are defined as a \fB\s-1SET\s0 \s-1OF\s0 Attribute\fR. They are \fBnot \s-1OPTIONAL\s0\fR so
327if no attributes are present then they should be encoded as an
328empty \fB\s-1SET\s0 \s-1OF\s0\fR. The invalid form does not include the empty
8b0cefbb 329\&\fB\s-1SET\s0 \s-1OF\s0\fR whereas the correct form does.
984263bc
MD
330.Sp
331It should be noted that very few CAs still require the use of this option.
8b0cefbb
JR
332.IP "\fB\-newhdr\fR" 4
333.IX Item "-newhdr"
984263bc
MD
334Adds the word \fB\s-1NEW\s0\fR to the \s-1PEM\s0 file header and footer lines on the outputed
335request. Some software (Netscape certificate server) and some CAs need this.
8b0cefbb
JR
336.IP "\fB\-batch\fR" 4
337.IX Item "-batch"
984263bc 338non-interactive mode.
8b0cefbb
JR
339.IP "\fB\-verbose\fR" 4
340.IX Item "-verbose"
984263bc 341print extra details about the operations being performed.
8b0cefbb
JR
342.IP "\fB\-engine id\fR" 4
343.IX Item "-engine id"
984263bc
MD
344specifying an engine (by it's unique \fBid\fR string) will cause \fBreq\fR
345to attempt to obtain a functional reference to the specified engine,
346thus initialising it if needed. The engine will then be set as the default
347for all available algorithms.
348.SH "CONFIGURATION FILE FORMAT"
8b0cefbb 349.IX Header "CONFIGURATION FILE FORMAT"
984263bc
MD
350The configuration options are specified in the \fBreq\fR section of
351the configuration file. As with all configuration files if no
352value is specified in the specific section (i.e. \fBreq\fR) then
353the initial unnamed or \fBdefault\fR section is searched too.
354.PP
355The options available are described in detail below.
8b0cefbb
JR
356.IP "\fBinput_password output_password\fR" 4
357.IX Item "input_password output_password"
984263bc
MD
358The passwords for the input private key file (if present) and
359the output private key file (if one will be created). The
360command line options \fBpassin\fR and \fBpassout\fR override the
361configuration file values.
8b0cefbb
JR
362.IP "\fBdefault_bits\fR" 4
363.IX Item "default_bits"
984263bc
MD
364This specifies the default key size in bits. If not specified then
365512 is used. It is used if the \fB\-new\fR option is used. It can be
366overridden by using the \fB\-newkey\fR option.
8b0cefbb
JR
367.IP "\fBdefault_keyfile\fR" 4
368.IX Item "default_keyfile"
984263bc
MD
369This is the default filename to write a private key to. If not
370specified the key is written to standard output. This can be
371overridden by the \fB\-keyout\fR option.
8b0cefbb
JR
372.IP "\fBoid_file\fR" 4
373.IX Item "oid_file"
984263bc
MD
374This specifies a file containing additional \fB\s-1OBJECT\s0 \s-1IDENTIFIERS\s0\fR.
375Each line of the file should consist of the numerical form of the
376object identifier followed by white space then the short name followed
377by white space and finally the long name.
8b0cefbb
JR
378.IP "\fBoid_section\fR" 4
379.IX Item "oid_section"
984263bc
MD
380This specifies a section in the configuration file containing extra
381object identifiers. Each line should consist of the short name of the
382object identifier followed by \fB=\fR and the numerical form. The short
383and long names are the same when this option is used.
8b0cefbb
JR
384.IP "\fB\s-1RANDFILE\s0\fR" 4
385.IX Item "RANDFILE"
984263bc 386This specifies a filename in which random number seed information is
8b0cefbb 387placed and read from, or an \s-1EGD\s0 socket (see \fIRAND_egd\fR\|(3)).
984263bc 388It is used for private key generation.
8b0cefbb
JR
389.IP "\fBencrypt_key\fR" 4
390.IX Item "encrypt_key"
984263bc 391If this is set to \fBno\fR then if a private key is generated it is
8b0cefbb 392\&\fBnot\fR encrypted. This is equivalent to the \fB\-nodes\fR command line
984263bc 393option. For compatibility \fBencrypt_rsa_key\fR is an equivalent option.
8b0cefbb
JR
394.IP "\fBdefault_md\fR" 4
395.IX Item "default_md"
984263bc
MD
396This option specifies the digest algorithm to use. Possible values
397include \fBmd5 sha1 mdc2\fR. If not present then \s-1MD5\s0 is used. This
398option can be overridden on the command line.
8b0cefbb
JR
399.IP "\fBstring_mask\fR" 4
400.IX Item "string_mask"
984263bc
MD
401This option masks out the use of certain string types in certain
402fields. Most users will not need to change this option.
403.Sp
404It can be set to several values \fBdefault\fR which is also the default
405option uses PrintableStrings, T61Strings and BMPStrings if the
8b0cefbb 406\&\fBpkix\fR value is used then only PrintableStrings and BMPStrings will
984263bc 407be used. This follows the \s-1PKIX\s0 recommendation in \s-1RFC2459\s0. If the
8b0cefbb 408\&\fButf8only\fR option is used then only UTF8Strings will be used: this
984263bc
MD
409is the \s-1PKIX\s0 recommendation in \s-1RFC2459\s0 after 2003. Finally the \fBnombstr\fR
410option just uses PrintableStrings and T61Strings: certain software has
411problems with BMPStrings and UTF8Strings: in particular Netscape.
8b0cefbb
JR
412.IP "\fBreq_extensions\fR" 4
413.IX Item "req_extensions"
984263bc
MD
414this specifies the configuration file section containing a list of
415extensions to add to the certificate request. It can be overridden
416by the \fB\-reqexts\fR command line switch.
8b0cefbb
JR
417.IP "\fBx509_extensions\fR" 4
418.IX Item "x509_extensions"
984263bc
MD
419this specifies the configuration file section containing a list of
420extensions to add to certificate generated when the \fB\-x509\fR switch
421is used. It can be overridden by the \fB\-extensions\fR command line switch.
8b0cefbb
JR
422.IP "\fBprompt\fR" 4
423.IX Item "prompt"
984263bc
MD
424if set to the value \fBno\fR this disables prompting of certificate fields
425and just takes values from the config file directly. It also changes the
426expected format of the \fBdistinguished_name\fR and \fBattributes\fR sections.
8b0cefbb
JR
427.IP "\fButf8\fR" 4
428.IX Item "utf8"
984263bc
MD
429if set to the value \fByes\fR then field values to be interpreted as \s-1UTF8\s0
430strings, by default they are interpreted as \s-1ASCII\s0. This means that
431the field values, whether prompted from a terminal or obtained from a
432configuration file, must be valid \s-1UTF8\s0 strings.
8b0cefbb
JR
433.IP "\fBattributes\fR" 4
434.IX Item "attributes"
984263bc
MD
435this specifies the section containing any request attributes: its format
436is the same as \fBdistinguished_name\fR. Typically these may contain the
437challengePassword or unstructuredName types. They are currently ignored
438by OpenSSL's request signing utilities but some CAs might want them.
8b0cefbb
JR
439.IP "\fBdistinguished_name\fR" 4
440.IX Item "distinguished_name"
984263bc
MD
441This specifies the section containing the distinguished name fields to
442prompt for when generating a certificate or certificate request. The format
443is described in the next section.
444.SH "DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT"
8b0cefbb 445.IX Header "DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT"
984263bc
MD
446There are two separate formats for the distinguished name and attribute
447sections. If the \fBprompt\fR option is set to \fBno\fR then these sections
448just consist of field names and values: for example,
449.PP
450.Vb 3
451\& CN=My Name
452\& OU=My Organization
453\& emailAddress=someone@somewhere.org
454.Ve
8b0cefbb
JR
455.PP
456This allows external programs (e.g. \s-1GUI\s0 based) to generate a template file
984263bc 457with all the field names and values and just pass it to \fBreq\fR. An example
8b0cefbb 458of this kind of configuration file is contained in the \fB\s-1EXAMPLES\s0\fR section.
984263bc
MD
459.PP
460Alternatively if the \fBprompt\fR option is absent or not set to \fBno\fR then the
461file contains field prompting information. It consists of lines of the form:
462.PP
463.Vb 4
464\& fieldName="prompt"
465\& fieldName_default="default field value"
466\& fieldName_min= 2
467\& fieldName_max= 4
468.Ve
8b0cefbb
JR
469.PP
470\&\*(L"fieldName\*(R" is the field name being used, for example commonName (or \s-1CN\s0).
984263bc
MD
471The \*(L"prompt\*(R" string is used to ask the user to enter the relevant
472details. If the user enters nothing then the default value is used if no
473default value is present then the field is omitted. A field can
474still be omitted if a default value is present if the user just
8b0cefbb 475enters the '.' character.
984263bc
MD
476.PP
477The number of characters entered must be between the fieldName_min and
478fieldName_max limits: there may be additional restrictions based
479on the field being used (for example countryName can only ever be
480two characters long and must fit in a PrintableString).
481.PP
482Some fields (such as organizationName) can be used more than once
8b0cefbb 483in a \s-1DN\s0. This presents a problem because configuration files will
984263bc
MD
484not recognize the same name occurring twice. To avoid this problem
485if the fieldName contains some characters followed by a full stop
486they will be ignored. So for example a second organizationName can
487be input by calling it \*(L"1.organizationName\*(R".
488.PP
489The actual permitted field names are any object identifier short or
490long names. These are compiled into OpenSSL and include the usual
491values such as commonName, countryName, localityName, organizationName,
492organizationUnitName, stateOrProvinceName. Additionally emailAddress
493is include as well as name, surname, givenName initials and dnQualifier.
494.PP
495Additional object identifiers can be defined with the \fBoid_file\fR or
8b0cefbb 496\&\fBoid_section\fR options in the configuration file. Any additional fields
984263bc
MD
497will be treated as though they were a DirectoryString.
498.SH "EXAMPLES"
8b0cefbb 499.IX Header "EXAMPLES"
984263bc
MD
500Examine and verify certificate request:
501.PP
502.Vb 1
503\& openssl req -in req.pem -text -verify -noout
504.Ve
8b0cefbb 505.PP
984263bc
MD
506Create a private key and then generate a certificate request from it:
507.PP
508.Vb 2
509\& openssl genrsa -out key.pem 1024
510\& openssl req -new -key key.pem -out req.pem
511.Ve
8b0cefbb 512.PP
984263bc
MD
513The same but just using req:
514.PP
515.Vb 1
516\& openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
517.Ve
8b0cefbb 518.PP
984263bc
MD
519Generate a self signed root certificate:
520.PP
521.Vb 1
522\& openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
523.Ve
8b0cefbb 524.PP
984263bc
MD
525Example of a file pointed to by the \fBoid_file\fR option:
526.PP
527.Vb 2
528\& 1.2.3.4 shortName A longer Name
529\& 1.2.3.6 otherName Other longer Name
530.Ve
8b0cefbb 531.PP
984263bc
MD
532Example of a section pointed to by \fBoid_section\fR making use of variable
533expansion:
534.PP
535.Vb 2
536\& testoid1=1.2.3.5
537\& testoid2=${testoid1}.6
538.Ve
8b0cefbb 539.PP
984263bc
MD
540Sample configuration file prompting for field values:
541.PP
542.Vb 6
543\& [ req ]
544\& default_bits = 1024
545\& default_keyfile = privkey.pem
546\& distinguished_name = req_distinguished_name
547\& attributes = req_attributes
548\& x509_extensions = v3_ca
549.Ve
8b0cefbb 550.PP
984263bc
MD
551.Vb 1
552\& dirstring_type = nobmp
553.Ve
8b0cefbb 554.PP
984263bc
MD
555.Vb 5
556\& [ req_distinguished_name ]
557\& countryName = Country Name (2 letter code)
558\& countryName_default = AU
559\& countryName_min = 2
560\& countryName_max = 2
561.Ve
8b0cefbb 562.PP
984263bc
MD
563.Vb 1
564\& localityName = Locality Name (eg, city)
565.Ve
8b0cefbb 566.PP
984263bc
MD
567.Vb 1
568\& organizationalUnitName = Organizational Unit Name (eg, section)
569.Ve
8b0cefbb 570.PP
984263bc
MD
571.Vb 2
572\& commonName = Common Name (eg, YOUR name)
573\& commonName_max = 64
574.Ve
8b0cefbb 575.PP
984263bc
MD
576.Vb 2
577\& emailAddress = Email Address
578\& emailAddress_max = 40
579.Ve
8b0cefbb 580.PP
984263bc
MD
581.Vb 4
582\& [ req_attributes ]
583\& challengePassword = A challenge password
584\& challengePassword_min = 4
585\& challengePassword_max = 20
586.Ve
8b0cefbb 587.PP
984263bc
MD
588.Vb 1
589\& [ v3_ca ]
590.Ve
8b0cefbb 591.PP
984263bc
MD
592.Vb 3
593\& subjectKeyIdentifier=hash
594\& authorityKeyIdentifier=keyid:always,issuer:always
595\& basicConstraints = CA:true
596.Ve
8b0cefbb 597.PP
984263bc
MD
598Sample configuration containing all field values:
599.PP
600.Vb 1
601\& RANDFILE = $ENV::HOME/.rnd
602.Ve
8b0cefbb 603.PP
984263bc
MD
604.Vb 7
605\& [ req ]
606\& default_bits = 1024
607\& default_keyfile = keyfile.pem
608\& distinguished_name = req_distinguished_name
609\& attributes = req_attributes
610\& prompt = no
611\& output_password = mypass
612.Ve
8b0cefbb 613.PP
984263bc
MD
614.Vb 8
615\& [ req_distinguished_name ]
616\& C = GB
617\& ST = Test State or Province
618\& L = Test Locality
619\& O = Organization Name
620\& OU = Organizational Unit Name
621\& CN = Common Name
622\& emailAddress = test@email.address
623.Ve
8b0cefbb 624.PP
984263bc
MD
625.Vb 2
626\& [ req_attributes ]
627\& challengePassword = A challenge password
628.Ve
629.SH "NOTES"
8b0cefbb
JR
630.IX Header "NOTES"
631The header and footer lines in the \fB\s-1PEM\s0\fR format are normally:
984263bc
MD
632.PP
633.Vb 2
634\& -----BEGIN CERTIFICATE REQUEST-----
635\& -----END CERTIFICATE REQUEST-----
636.Ve
8b0cefbb 637.PP
984263bc
MD
638some software (some versions of Netscape certificate server) instead needs:
639.PP
640.Vb 2
641\& -----BEGIN NEW CERTIFICATE REQUEST-----
642\& -----END NEW CERTIFICATE REQUEST-----
643.Ve
8b0cefbb 644.PP
984263bc
MD
645which is produced with the \fB\-newhdr\fR option but is otherwise compatible.
646Either form is accepted transparently on input.
647.PP
8b0cefbb 648The certificate requests generated by \fBXenroll\fR with \s-1MSIE\s0 have extensions
984263bc
MD
649added. It includes the \fBkeyUsage\fR extension which determines the type of
650key (signature only or general purpose) and any additional OIDs entered
651by the script in an extendedKeyUsage extension.
652.SH "DIAGNOSTICS"
8b0cefbb 653.IX Header "DIAGNOSTICS"
984263bc
MD
654The following messages are frequently asked about:
655.PP
656.Vb 2
657\& Using configuration from /some/path/openssl.cnf
658\& Unable to load config info
659.Ve
8b0cefbb 660.PP
984263bc
MD
661This is followed some time later by...
662.PP
663.Vb 2
664\& unable to find 'distinguished_name' in config
665\& problems making Certificate Request
666.Ve
8b0cefbb 667.PP
984263bc
MD
668The first error message is the clue: it can't find the configuration
669file! Certain operations (like examining a certificate request) don't
670need a configuration file so its use isn't enforced. Generation of
671certificates or requests however does need a configuration file. This
672could be regarded as a bug.
673.PP
674Another puzzling message is this:
675.PP
676.Vb 2
677\& Attributes:
678\& a0:00
679.Ve
8b0cefbb 680.PP
984263bc 681this is displayed when no attributes are present and the request includes
8b0cefbb 682the correct empty \fB\s-1SET\s0 \s-1OF\s0\fR structure (the \s-1DER\s0 encoding of which is 0xa0
984263bc
MD
6830x00). If you just see:
684.PP
685.Vb 1
686\& Attributes:
687.Ve
8b0cefbb
JR
688.PP
689then the \fB\s-1SET\s0 \s-1OF\s0\fR is missing and the encoding is technically invalid (but
690it is tolerated). See the description of the command line option \fB\-asn1\-kludge\fR
984263bc
MD
691for more information.
692.SH "ENVIRONMENT VARIABLES"
8b0cefbb
JR
693.IX Header "ENVIRONMENT VARIABLES"
694The variable \fB\s-1OPENSSL_CONF\s0\fR if defined allows an alternative configuration
984263bc 695file location to be specified, it will be overridden by the \fB\-config\fR command
8b0cefbb 696line switch if it is present. For compatibility reasons the \fB\s-1SSLEAY_CONF\s0\fR
984263bc
MD
697environment variable serves the same purpose but its use is discouraged.
698.SH "BUGS"
8b0cefbb 699.IX Header "BUGS"
984263bc 700OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
8b0cefbb 701treats them as \s-1ISO\-8859\-1\s0 (Latin 1), Netscape and \s-1MSIE\s0 have similar behaviour.
984263bc
MD
702This can cause problems if you need characters that aren't available in
703PrintableStrings and you don't want to or can't use BMPStrings.
704.PP
705As a consequence of the T61String handling the only correct way to represent
706accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
707currently chokes on these. If you have to use accented characters with Netscape
8b0cefbb 708and \s-1MSIE\s0 then you currently need to use the invalid T61String form.
984263bc
MD
709.PP
710The current prompting is not very friendly. It doesn't allow you to confirm what
711you've just entered. Other things like extensions in certificate requests are
712statically defined in the configuration file. Some of these: like an email
713address in subjectAltName should be input by the user.
714.SH "SEE ALSO"
e3cdf75b 715.IX Header "SEE ALSO"
8b0cefbb
JR
716\&\fIx509\fR\|(1), \fIca\fR\|(1), \fIgenrsa\fR\|(1),
717\&\fIgendsa\fR\|(1), \fIconfig\fR\|(5)