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