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