[15529] | 1 | |
---|
| 2 | =pod |
---|
| 3 | |
---|
| 4 | =head1 NAME |
---|
| 5 | |
---|
[18441] | 6 | req - PKCS#10 certificate request and certificate generating utility. |
---|
[15529] | 7 | |
---|
| 8 | =head1 SYNOPSIS |
---|
| 9 | |
---|
| 10 | B<openssl> B<req> |
---|
| 11 | [B<-inform PEM|DER>] |
---|
| 12 | [B<-outform PEM|DER>] |
---|
| 13 | [B<-in filename>] |
---|
| 14 | [B<-passin arg>] |
---|
| 15 | [B<-out filename>] |
---|
| 16 | [B<-passout arg>] |
---|
| 17 | [B<-text>] |
---|
[18441] | 18 | [B<-pubkey>] |
---|
[15529] | 19 | [B<-noout>] |
---|
| 20 | [B<-verify>] |
---|
| 21 | [B<-modulus>] |
---|
| 22 | [B<-new>] |
---|
| 23 | [B<-rand file(s)>] |
---|
| 24 | [B<-newkey rsa:bits>] |
---|
| 25 | [B<-newkey dsa:file>] |
---|
| 26 | [B<-nodes>] |
---|
| 27 | [B<-key filename>] |
---|
| 28 | [B<-keyform PEM|DER>] |
---|
| 29 | [B<-keyout filename>] |
---|
| 30 | [B<-[md5|sha1|md2|mdc2]>] |
---|
| 31 | [B<-config filename>] |
---|
[18441] | 32 | [B<-subj arg>] |
---|
[15529] | 33 | [B<-x509>] |
---|
| 34 | [B<-days n>] |
---|
[18441] | 35 | [B<-set_serial n>] |
---|
[15529] | 36 | [B<-asn1-kludge>] |
---|
| 37 | [B<-newhdr>] |
---|
| 38 | [B<-extensions section>] |
---|
| 39 | [B<-reqexts section>] |
---|
[18441] | 40 | [B<-utf8>] |
---|
| 41 | [B<-nameopt>] |
---|
| 42 | [B<-batch>] |
---|
| 43 | [B<-verbose>] |
---|
[15529] | 44 | |
---|
| 45 | =head1 DESCRIPTION |
---|
| 46 | |
---|
| 47 | The B<req> command primarily creates and processes certificate requests |
---|
| 48 | in PKCS#10 format. It can additionally create self signed certificates |
---|
| 49 | for use as root CAs for example. |
---|
| 50 | |
---|
| 51 | =head1 COMMAND OPTIONS |
---|
| 52 | |
---|
| 53 | =over 4 |
---|
| 54 | |
---|
| 55 | =item B<-inform DER|PEM> |
---|
| 56 | |
---|
| 57 | This specifies the input format. The B<DER> option uses an ASN1 DER encoded |
---|
| 58 | form compatible with the PKCS#10. The B<PEM> form is the default format: it |
---|
| 59 | consists of the B<DER> format base64 encoded with additional header and |
---|
| 60 | footer lines. |
---|
| 61 | |
---|
| 62 | =item B<-outform DER|PEM> |
---|
| 63 | |
---|
| 64 | This specifies the output format, the options have the same meaning as the |
---|
| 65 | B<-inform> option. |
---|
| 66 | |
---|
| 67 | =item B<-in filename> |
---|
| 68 | |
---|
| 69 | This specifies the input filename to read a request from or standard input |
---|
| 70 | if this option is not specified. A request is only read if the creation |
---|
| 71 | options (B<-new> and B<-newkey>) are not specified. |
---|
| 72 | |
---|
| 73 | =item B<-passin arg> |
---|
| 74 | |
---|
| 75 | the input file password source. For more information about the format of B<arg> |
---|
| 76 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. |
---|
| 77 | |
---|
| 78 | =item B<-out filename> |
---|
| 79 | |
---|
| 80 | This specifies the output filename to write to or standard output by |
---|
| 81 | default. |
---|
| 82 | |
---|
| 83 | =item B<-passout arg> |
---|
| 84 | |
---|
| 85 | the output file password source. For more information about the format of B<arg> |
---|
| 86 | see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. |
---|
| 87 | |
---|
| 88 | =item B<-text> |
---|
| 89 | |
---|
| 90 | prints out the certificate request in text form. |
---|
| 91 | |
---|
[18441] | 92 | =item B<-pubkey> |
---|
| 93 | |
---|
| 94 | outputs the public key. |
---|
| 95 | |
---|
[15529] | 96 | =item B<-noout> |
---|
| 97 | |
---|
| 98 | this option prevents output of the encoded version of the request. |
---|
| 99 | |
---|
| 100 | =item B<-modulus> |
---|
| 101 | |
---|
| 102 | this option prints out the value of the modulus of the public key |
---|
| 103 | contained in the request. |
---|
| 104 | |
---|
| 105 | =item B<-verify> |
---|
| 106 | |
---|
| 107 | verifies the signature on the request. |
---|
| 108 | |
---|
| 109 | =item B<-new> |
---|
| 110 | |
---|
| 111 | this option generates a new certificate request. It will prompt |
---|
| 112 | the user for the relevant field values. The actual fields |
---|
| 113 | prompted for and their maximum and minimum sizes are specified |
---|
| 114 | in the configuration file and any requested extensions. |
---|
| 115 | |
---|
| 116 | If the B<-key> option is not used it will generate a new RSA private |
---|
| 117 | key using information specified in the configuration file. |
---|
| 118 | |
---|
| 119 | =item B<-rand file(s)> |
---|
| 120 | |
---|
| 121 | a file or files containing random data used to seed the random number |
---|
| 122 | generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). |
---|
| 123 | Multiple files can be specified separated by a OS-dependent character. |
---|
| 124 | The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for |
---|
| 125 | all others. |
---|
| 126 | |
---|
| 127 | =item B<-newkey arg> |
---|
| 128 | |
---|
| 129 | this option creates a new certificate request and a new private |
---|
| 130 | key. The argument takes one of two forms. B<rsa:nbits>, where |
---|
| 131 | B<nbits> is the number of bits, generates an RSA key B<nbits> |
---|
| 132 | in size. B<dsa:filename> generates a DSA key using the parameters |
---|
| 133 | in the file B<filename>. |
---|
| 134 | |
---|
| 135 | =item B<-key filename> |
---|
| 136 | |
---|
| 137 | This specifies the file to read the private key from. It also |
---|
| 138 | accepts PKCS#8 format private keys for PEM format files. |
---|
| 139 | |
---|
| 140 | =item B<-keyform PEM|DER> |
---|
| 141 | |
---|
| 142 | the format of the private key file specified in the B<-key> |
---|
| 143 | argument. PEM is the default. |
---|
| 144 | |
---|
| 145 | =item B<-keyout filename> |
---|
| 146 | |
---|
| 147 | this gives the filename to write the newly created private key to. |
---|
| 148 | If this option is not specified then the filename present in the |
---|
| 149 | configuration file is used. |
---|
| 150 | |
---|
| 151 | =item B<-nodes> |
---|
| 152 | |
---|
| 153 | if this option is specified then if a private key is created it |
---|
| 154 | will not be encrypted. |
---|
| 155 | |
---|
| 156 | =item B<-[md5|sha1|md2|mdc2]> |
---|
| 157 | |
---|
| 158 | this specifies the message digest to sign the request with. This |
---|
| 159 | overrides the digest algorithm specified in the configuration file. |
---|
| 160 | This option is ignored for DSA requests: they always use SHA1. |
---|
| 161 | |
---|
| 162 | =item B<-config filename> |
---|
| 163 | |
---|
| 164 | this allows an alternative configuration file to be specified, |
---|
| 165 | this overrides the compile time filename or any specified in |
---|
| 166 | the B<OPENSSL_CONF> environment variable. |
---|
| 167 | |
---|
[18441] | 168 | =item B<-subj arg> |
---|
| 169 | |
---|
| 170 | sets subject name for new request or supersedes the subject name |
---|
| 171 | when processing a request. |
---|
| 172 | The arg must be formatted as I</type0=value0/type1=value1/type2=...>, |
---|
| 173 | characters may be escaped by \ (backslash), no spaces are skipped. |
---|
| 174 | |
---|
[15529] | 175 | =item B<-x509> |
---|
| 176 | |
---|
| 177 | this option outputs a self signed certificate instead of a certificate |
---|
| 178 | request. This is typically used to generate a test certificate or |
---|
| 179 | a self signed root CA. The extensions added to the certificate |
---|
[18441] | 180 | (if any) are specified in the configuration file. Unless specified |
---|
| 181 | using the B<set_serial> option B<0> will be used for the serial |
---|
| 182 | number. |
---|
[15529] | 183 | |
---|
| 184 | =item B<-days n> |
---|
| 185 | |
---|
| 186 | when the B<-x509> option is being used this specifies the number of |
---|
| 187 | days to certify the certificate for. The default is 30 days. |
---|
| 188 | |
---|
[18441] | 189 | =item B<-set_serial n> |
---|
| 190 | |
---|
| 191 | serial number to use when outputting a self signed certificate. This |
---|
| 192 | may be specified as a decimal value or a hex value if preceded by B<0x>. |
---|
| 193 | It is possible to use negative serial numbers but this is not recommended. |
---|
| 194 | |
---|
[15529] | 195 | =item B<-extensions section> |
---|
| 196 | |
---|
| 197 | =item B<-reqexts section> |
---|
| 198 | |
---|
| 199 | these options specify alternative sections to include certificate |
---|
| 200 | extensions (if the B<-x509> option is present) or certificate |
---|
| 201 | request extensions. This allows several different sections to |
---|
| 202 | be used in the same configuration file to specify requests for |
---|
| 203 | a variety of purposes. |
---|
| 204 | |
---|
[18441] | 205 | =item B<-utf8> |
---|
| 206 | |
---|
| 207 | this option causes field values to be interpreted as UTF8 strings, by |
---|
| 208 | default they are interpreted as ASCII. This means that the field |
---|
| 209 | values, whether prompted from a terminal or obtained from a |
---|
| 210 | configuration file, must be valid UTF8 strings. |
---|
| 211 | |
---|
| 212 | =item B<-nameopt option> |
---|
| 213 | |
---|
| 214 | option which determines how the subject or issuer names are displayed. The |
---|
| 215 | B<option> argument can be a single option or multiple options separated by |
---|
| 216 | commas. Alternatively the B<-nameopt> switch may be used more than once to |
---|
| 217 | set multiple options. See the L<x509(1)|x509(1)> manual page for details. |
---|
| 218 | |
---|
[15529] | 219 | =item B<-asn1-kludge> |
---|
| 220 | |
---|
| 221 | by default the B<req> command outputs certificate requests containing |
---|
| 222 | no attributes in the correct PKCS#10 format. However certain CAs will only |
---|
| 223 | accept requests containing no attributes in an invalid form: this |
---|
| 224 | option produces this invalid format. |
---|
| 225 | |
---|
| 226 | More precisely the B<Attributes> in a PKCS#10 certificate request |
---|
| 227 | are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so |
---|
| 228 | if no attributes are present then they should be encoded as an |
---|
| 229 | empty B<SET OF>. The invalid form does not include the empty |
---|
| 230 | B<SET OF> whereas the correct form does. |
---|
| 231 | |
---|
| 232 | It should be noted that very few CAs still require the use of this option. |
---|
| 233 | |
---|
| 234 | =item B<-newhdr> |
---|
| 235 | |
---|
| 236 | Adds the word B<NEW> to the PEM file header and footer lines on the outputed |
---|
| 237 | request. Some software (Netscape certificate server) and some CAs need this. |
---|
| 238 | |
---|
[18441] | 239 | =item B<-batch> |
---|
| 240 | |
---|
| 241 | non-interactive mode. |
---|
| 242 | |
---|
| 243 | =item B<-verbose> |
---|
| 244 | |
---|
| 245 | print extra details about the operations being performed. |
---|
| 246 | |
---|
[15529] | 247 | =back |
---|
| 248 | |
---|
| 249 | =head1 CONFIGURATION FILE FORMAT |
---|
| 250 | |
---|
| 251 | The configuration options are specified in the B<req> section of |
---|
| 252 | the configuration file. As with all configuration files if no |
---|
| 253 | value is specified in the specific section (i.e. B<req>) then |
---|
| 254 | the initial unnamed or B<default> section is searched too. |
---|
| 255 | |
---|
| 256 | The options available are described in detail below. |
---|
| 257 | |
---|
| 258 | =over 4 |
---|
| 259 | |
---|
| 260 | =item B<input_password output_password> |
---|
| 261 | |
---|
| 262 | The passwords for the input private key file (if present) and |
---|
| 263 | the output private key file (if one will be created). The |
---|
| 264 | command line options B<passin> and B<passout> override the |
---|
| 265 | configuration file values. |
---|
| 266 | |
---|
| 267 | =item B<default_bits> |
---|
| 268 | |
---|
| 269 | This specifies the default key size in bits. If not specified then |
---|
| 270 | 512 is used. It is used if the B<-new> option is used. It can be |
---|
| 271 | overridden by using the B<-newkey> option. |
---|
| 272 | |
---|
| 273 | =item B<default_keyfile> |
---|
| 274 | |
---|
| 275 | This is the default filename to write a private key to. If not |
---|
| 276 | specified the key is written to standard output. This can be |
---|
| 277 | overridden by the B<-keyout> option. |
---|
| 278 | |
---|
| 279 | =item B<oid_file> |
---|
| 280 | |
---|
| 281 | This specifies a file containing additional B<OBJECT IDENTIFIERS>. |
---|
| 282 | Each line of the file should consist of the numerical form of the |
---|
| 283 | object identifier followed by white space then the short name followed |
---|
| 284 | by white space and finally the long name. |
---|
| 285 | |
---|
| 286 | =item B<oid_section> |
---|
| 287 | |
---|
| 288 | This specifies a section in the configuration file containing extra |
---|
| 289 | object identifiers. Each line should consist of the short name of the |
---|
| 290 | object identifier followed by B<=> and the numerical form. The short |
---|
| 291 | and long names are the same when this option is used. |
---|
| 292 | |
---|
| 293 | =item B<RANDFILE> |
---|
| 294 | |
---|
| 295 | This specifies a filename in which random number seed information is |
---|
| 296 | placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). |
---|
| 297 | It is used for private key generation. |
---|
| 298 | |
---|
| 299 | =item B<encrypt_key> |
---|
| 300 | |
---|
| 301 | If this is set to B<no> then if a private key is generated it is |
---|
| 302 | B<not> encrypted. This is equivalent to the B<-nodes> command line |
---|
| 303 | option. For compatibility B<encrypt_rsa_key> is an equivalent option. |
---|
| 304 | |
---|
| 305 | =item B<default_md> |
---|
| 306 | |
---|
| 307 | This option specifies the digest algorithm to use. Possible values |
---|
| 308 | include B<md5 sha1 mdc2>. If not present then MD5 is used. This |
---|
| 309 | option can be overridden on the command line. |
---|
| 310 | |
---|
| 311 | =item B<string_mask> |
---|
| 312 | |
---|
| 313 | This option masks out the use of certain string types in certain |
---|
| 314 | fields. Most users will not need to change this option. |
---|
| 315 | |
---|
| 316 | It can be set to several values B<default> which is also the default |
---|
| 317 | option uses PrintableStrings, T61Strings and BMPStrings if the |
---|
| 318 | B<pkix> value is used then only PrintableStrings and BMPStrings will |
---|
| 319 | be used. This follows the PKIX recommendation in RFC2459. If the |
---|
| 320 | B<utf8only> option is used then only UTF8Strings will be used: this |
---|
| 321 | is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> |
---|
| 322 | option just uses PrintableStrings and T61Strings: certain software has |
---|
| 323 | problems with BMPStrings and UTF8Strings: in particular Netscape. |
---|
| 324 | |
---|
| 325 | =item B<req_extensions> |
---|
| 326 | |
---|
| 327 | this specifies the configuration file section containing a list of |
---|
| 328 | extensions to add to the certificate request. It can be overridden |
---|
| 329 | by the B<-reqexts> command line switch. |
---|
| 330 | |
---|
| 331 | =item B<x509_extensions> |
---|
| 332 | |
---|
| 333 | this specifies the configuration file section containing a list of |
---|
| 334 | extensions to add to certificate generated when the B<-x509> switch |
---|
| 335 | is used. It can be overridden by the B<-extensions> command line switch. |
---|
| 336 | |
---|
| 337 | =item B<prompt> |
---|
| 338 | |
---|
| 339 | if set to the value B<no> this disables prompting of certificate fields |
---|
| 340 | and just takes values from the config file directly. It also changes the |
---|
| 341 | expected format of the B<distinguished_name> and B<attributes> sections. |
---|
| 342 | |
---|
[18441] | 343 | =item B<utf8> |
---|
| 344 | |
---|
| 345 | if set to the value B<yes> then field values to be interpreted as UTF8 |
---|
| 346 | strings, by default they are interpreted as ASCII. This means that |
---|
| 347 | the field values, whether prompted from a terminal or obtained from a |
---|
| 348 | configuration file, must be valid UTF8 strings. |
---|
| 349 | |
---|
[15529] | 350 | =item B<attributes> |
---|
| 351 | |
---|
| 352 | this specifies the section containing any request attributes: its format |
---|
| 353 | is the same as B<distinguished_name>. Typically these may contain the |
---|
| 354 | challengePassword or unstructuredName types. They are currently ignored |
---|
| 355 | by OpenSSL's request signing utilities but some CAs might want them. |
---|
| 356 | |
---|
| 357 | =item B<distinguished_name> |
---|
| 358 | |
---|
| 359 | This specifies the section containing the distinguished name fields to |
---|
| 360 | prompt for when generating a certificate or certificate request. The format |
---|
| 361 | is described in the next section. |
---|
| 362 | |
---|
| 363 | =back |
---|
| 364 | |
---|
| 365 | =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT |
---|
| 366 | |
---|
| 367 | There are two separate formats for the distinguished name and attribute |
---|
| 368 | sections. If the B<prompt> option is set to B<no> then these sections |
---|
| 369 | just consist of field names and values: for example, |
---|
| 370 | |
---|
| 371 | CN=My Name |
---|
| 372 | OU=My Organization |
---|
| 373 | emailAddress=someone@somewhere.org |
---|
| 374 | |
---|
| 375 | This allows external programs (e.g. GUI based) to generate a template file |
---|
| 376 | with all the field names and values and just pass it to B<req>. An example |
---|
| 377 | of this kind of configuration file is contained in the B<EXAMPLES> section. |
---|
| 378 | |
---|
| 379 | Alternatively if the B<prompt> option is absent or not set to B<no> then the |
---|
| 380 | file contains field prompting information. It consists of lines of the form: |
---|
| 381 | |
---|
| 382 | fieldName="prompt" |
---|
| 383 | fieldName_default="default field value" |
---|
| 384 | fieldName_min= 2 |
---|
| 385 | fieldName_max= 4 |
---|
| 386 | |
---|
| 387 | "fieldName" is the field name being used, for example commonName (or CN). |
---|
| 388 | The "prompt" string is used to ask the user to enter the relevant |
---|
| 389 | details. If the user enters nothing then the default value is used if no |
---|
| 390 | default value is present then the field is omitted. A field can |
---|
| 391 | still be omitted if a default value is present if the user just |
---|
| 392 | enters the '.' character. |
---|
| 393 | |
---|
| 394 | The number of characters entered must be between the fieldName_min and |
---|
| 395 | fieldName_max limits: there may be additional restrictions based |
---|
| 396 | on the field being used (for example countryName can only ever be |
---|
| 397 | two characters long and must fit in a PrintableString). |
---|
| 398 | |
---|
| 399 | Some fields (such as organizationName) can be used more than once |
---|
| 400 | in a DN. This presents a problem because configuration files will |
---|
| 401 | not recognize the same name occurring twice. To avoid this problem |
---|
| 402 | if the fieldName contains some characters followed by a full stop |
---|
| 403 | they will be ignored. So for example a second organizationName can |
---|
| 404 | be input by calling it "1.organizationName". |
---|
| 405 | |
---|
| 406 | The actual permitted field names are any object identifier short or |
---|
| 407 | long names. These are compiled into OpenSSL and include the usual |
---|
| 408 | values such as commonName, countryName, localityName, organizationName, |
---|
| 409 | organizationUnitName, stateOrPrivinceName. Additionally emailAddress |
---|
| 410 | is include as well as name, surname, givenName initials and dnQualifier. |
---|
| 411 | |
---|
| 412 | Additional object identifiers can be defined with the B<oid_file> or |
---|
| 413 | B<oid_section> options in the configuration file. Any additional fields |
---|
| 414 | will be treated as though they were a DirectoryString. |
---|
| 415 | |
---|
| 416 | |
---|
| 417 | =head1 EXAMPLES |
---|
| 418 | |
---|
| 419 | Examine and verify certificate request: |
---|
| 420 | |
---|
| 421 | openssl req -in req.pem -text -verify -noout |
---|
| 422 | |
---|
| 423 | Create a private key and then generate a certificate request from it: |
---|
| 424 | |
---|
| 425 | openssl genrsa -out key.pem 1024 |
---|
| 426 | openssl req -new -key key.pem -out req.pem |
---|
| 427 | |
---|
| 428 | The same but just using req: |
---|
| 429 | |
---|
| 430 | openssl req -newkey rsa:1024 -keyout key.pem -out req.pem |
---|
| 431 | |
---|
| 432 | Generate a self signed root certificate: |
---|
| 433 | |
---|
| 434 | openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem |
---|
| 435 | |
---|
| 436 | Example of a file pointed to by the B<oid_file> option: |
---|
| 437 | |
---|
| 438 | 1.2.3.4 shortName A longer Name |
---|
| 439 | 1.2.3.6 otherName Other longer Name |
---|
| 440 | |
---|
| 441 | Example of a section pointed to by B<oid_section> making use of variable |
---|
| 442 | expansion: |
---|
| 443 | |
---|
| 444 | testoid1=1.2.3.5 |
---|
| 445 | testoid2=${testoid1}.6 |
---|
| 446 | |
---|
| 447 | Sample configuration file prompting for field values: |
---|
| 448 | |
---|
| 449 | [ req ] |
---|
| 450 | default_bits = 1024 |
---|
| 451 | default_keyfile = privkey.pem |
---|
| 452 | distinguished_name = req_distinguished_name |
---|
| 453 | attributes = req_attributes |
---|
| 454 | x509_extensions = v3_ca |
---|
| 455 | |
---|
| 456 | dirstring_type = nobmp |
---|
| 457 | |
---|
| 458 | [ req_distinguished_name ] |
---|
| 459 | countryName = Country Name (2 letter code) |
---|
| 460 | countryName_default = AU |
---|
| 461 | countryName_min = 2 |
---|
| 462 | countryName_max = 2 |
---|
| 463 | |
---|
| 464 | localityName = Locality Name (eg, city) |
---|
| 465 | |
---|
| 466 | organizationalUnitName = Organizational Unit Name (eg, section) |
---|
| 467 | |
---|
| 468 | commonName = Common Name (eg, YOUR name) |
---|
| 469 | commonName_max = 64 |
---|
| 470 | |
---|
| 471 | emailAddress = Email Address |
---|
| 472 | emailAddress_max = 40 |
---|
| 473 | |
---|
| 474 | [ req_attributes ] |
---|
| 475 | challengePassword = A challenge password |
---|
| 476 | challengePassword_min = 4 |
---|
| 477 | challengePassword_max = 20 |
---|
| 478 | |
---|
| 479 | [ v3_ca ] |
---|
| 480 | |
---|
| 481 | subjectKeyIdentifier=hash |
---|
| 482 | authorityKeyIdentifier=keyid:always,issuer:always |
---|
| 483 | basicConstraints = CA:true |
---|
| 484 | |
---|
| 485 | Sample configuration containing all field values: |
---|
| 486 | |
---|
| 487 | |
---|
| 488 | RANDFILE = $ENV::HOME/.rnd |
---|
| 489 | |
---|
| 490 | [ req ] |
---|
| 491 | default_bits = 1024 |
---|
| 492 | default_keyfile = keyfile.pem |
---|
| 493 | distinguished_name = req_distinguished_name |
---|
| 494 | attributes = req_attributes |
---|
| 495 | prompt = no |
---|
| 496 | output_password = mypass |
---|
| 497 | |
---|
| 498 | [ req_distinguished_name ] |
---|
| 499 | C = GB |
---|
| 500 | ST = Test State or Province |
---|
| 501 | L = Test Locality |
---|
| 502 | O = Organization Name |
---|
| 503 | OU = Organizational Unit Name |
---|
| 504 | CN = Common Name |
---|
| 505 | emailAddress = test@email.address |
---|
| 506 | |
---|
| 507 | [ req_attributes ] |
---|
| 508 | challengePassword = A challenge password |
---|
| 509 | |
---|
| 510 | |
---|
| 511 | =head1 NOTES |
---|
| 512 | |
---|
| 513 | The header and footer lines in the B<PEM> format are normally: |
---|
| 514 | |
---|
[18441] | 515 | -----BEGIN CERTIFICATE REQUEST----- |
---|
| 516 | -----END CERTIFICATE REQUEST----- |
---|
[15529] | 517 | |
---|
| 518 | some software (some versions of Netscape certificate server) instead needs: |
---|
| 519 | |
---|
[18441] | 520 | -----BEGIN NEW CERTIFICATE REQUEST----- |
---|
| 521 | -----END NEW CERTIFICATE REQUEST----- |
---|
[15529] | 522 | |
---|
| 523 | which is produced with the B<-newhdr> option but is otherwise compatible. |
---|
| 524 | Either form is accepted transparently on input. |
---|
| 525 | |
---|
| 526 | The certificate requests generated by B<Xenroll> with MSIE have extensions |
---|
| 527 | added. It includes the B<keyUsage> extension which determines the type of |
---|
| 528 | key (signature only or general purpose) and any additional OIDs entered |
---|
| 529 | by the script in an extendedKeyUsage extension. |
---|
| 530 | |
---|
| 531 | =head1 DIAGNOSTICS |
---|
| 532 | |
---|
| 533 | The following messages are frequently asked about: |
---|
| 534 | |
---|
| 535 | Using configuration from /some/path/openssl.cnf |
---|
| 536 | Unable to load config info |
---|
| 537 | |
---|
| 538 | This is followed some time later by... |
---|
| 539 | |
---|
| 540 | unable to find 'distinguished_name' in config |
---|
| 541 | problems making Certificate Request |
---|
| 542 | |
---|
| 543 | The first error message is the clue: it can't find the configuration |
---|
| 544 | file! Certain operations (like examining a certificate request) don't |
---|
| 545 | need a configuration file so its use isn't enforced. Generation of |
---|
| 546 | certificates or requests however does need a configuration file. This |
---|
| 547 | could be regarded as a bug. |
---|
| 548 | |
---|
| 549 | Another puzzling message is this: |
---|
| 550 | |
---|
| 551 | Attributes: |
---|
| 552 | a0:00 |
---|
| 553 | |
---|
| 554 | this is displayed when no attributes are present and the request includes |
---|
| 555 | the correct empty B<SET OF> structure (the DER encoding of which is 0xa0 |
---|
| 556 | 0x00). If you just see: |
---|
| 557 | |
---|
| 558 | Attributes: |
---|
| 559 | |
---|
| 560 | then the B<SET OF> is missing and the encoding is technically invalid (but |
---|
| 561 | it is tolerated). See the description of the command line option B<-asn1-kludge> |
---|
| 562 | for more information. |
---|
| 563 | |
---|
| 564 | =head1 ENVIRONMENT VARIABLES |
---|
| 565 | |
---|
| 566 | The variable B<OPENSSL_CONF> if defined allows an alternative configuration |
---|
| 567 | file location to be specified, it will be overridden by the B<-config> command |
---|
| 568 | line switch if it is present. For compatibility reasons the B<SSLEAY_CONF> |
---|
| 569 | environment variable serves the same purpose but its use is discouraged. |
---|
| 570 | |
---|
| 571 | =head1 BUGS |
---|
| 572 | |
---|
| 573 | OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively |
---|
| 574 | treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. |
---|
| 575 | This can cause problems if you need characters that aren't available in |
---|
| 576 | PrintableStrings and you don't want to or can't use BMPStrings. |
---|
| 577 | |
---|
| 578 | As a consequence of the T61String handling the only correct way to represent |
---|
| 579 | accented characters in OpenSSL is to use a BMPString: unfortunately Netscape |
---|
| 580 | currently chokes on these. If you have to use accented characters with Netscape |
---|
| 581 | and MSIE then you currently need to use the invalid T61String form. |
---|
| 582 | |
---|
| 583 | The current prompting is not very friendly. It doesn't allow you to confirm what |
---|
| 584 | you've just entered. Other things like extensions in certificate requests are |
---|
| 585 | statically defined in the configuration file. Some of these: like an email |
---|
| 586 | address in subjectAltName should be input by the user. |
---|
| 587 | |
---|
| 588 | =head1 SEE ALSO |
---|
| 589 | |
---|
| 590 | L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>, |
---|
| 591 | L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)> |
---|
| 592 | |
---|
| 593 | =cut |
---|