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