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