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