doc/man1/openssl-req.pod.in

   1 =pod
   2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
   3
   4 =head1 NAME
   5
   6 openssl-req - PKCS#10 certificate request and certificate generating command
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<req>
  11 [B<-help>]
  12 [B<-inform> B<DER>|B<PEM>]
  13 [B<-outform> B<DER>|B<PEM>]
  14 [B<-in> I<filename>]
  15 [B<-passin> I<arg>]
  16 [B<-out> I<filename>]
  17 [B<-passout> I<arg>]
  18 [B<-text>]
  19 [B<-pubkey>]
  20 [B<-noout>]
  21 [B<-verify>]
  22 [B<-modulus>]
  23 [B<-new>]
  24 [B<-newkey> I<arg>]
  25 [B<-pkeyopt> I<opt>:I<value>]
  26 [B<-noenc>]
  27 [B<-nodes>]
  28 [B<-key> I<filename>|I<uri>]
  29 [B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>]
  30 [B<-keyout> I<filename>]
  31 [B<-keygen_engine> I<id>]
  32 [B<-I<digest>>]
  33 [B<-config> I<filename>]
  34 [B<-section> I<name>]
  35 [B<-x509>]
  36 [B<-x509v1>]
  37 [B<-CA> I<filename>|I<uri>]
  38 [B<-CAkey> I<filename>|I<uri>]
  39 [B<-not_before> I<date>]
  40 [B<-not_after> I<date>]
  41 [B<-days> I<n>]
  42 [B<-set_serial> I<n>]
  43 [B<-newhdr>]
  44 [B<-copy_extensions> I<arg>]
  45 [B<-extensions> I<section>]
  46 [B<-reqexts> I<section>]
  47 [B<-addext> I<ext>]
  48 [B<-precert>]
  49 [B<-utf8>]
  50 [B<-reqopt>]
  51 [B<-subject>]
  52 [B<-subj> I<arg>]
  53 [B<-multivalue-rdn>]
  54 [B<-sigopt> I<nm>:I<v>]
  55 [B<-vfyopt> I<nm>:I<v>]
  56 [B<-batch>]
  57 [B<-verbose>]
  58 [B<-quiet>]
  59 {- $OpenSSL::safe::opt_name_synopsis -}
  60 {- $OpenSSL::safe::opt_r_synopsis -}
  61 {- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -}
  62
  63 =head1 DESCRIPTION
  64
  65 This command primarily creates and processes certificate requests (CSRs)
  66 in PKCS#10 format. It can additionally create self-signed certificates
  67 for use as root CAs for example.
  68
  69 =head1 OPTIONS
  70
  71 =over 4
  72
  73 =item B<-help>
  74
  75 Print out a usage message.
  76
  77 =item B<-inform> B<DER>|B<PEM>
  78
  79 The CSR input file format to use; by default PEM is tried first.
  80 See L<openssl-format-options(1)> for details.
  81
  82 =item B<-outform> B<DER>|B<PEM>
  83
  84 The output format; unspecified by default.
  85 See L<openssl-format-options(1)> for details.
  86
  87 The data is a PKCS#10 object.
  88
  89 =item B<-in> I<filename>
  90
  91 This specifies the input filename to read a request from.
  92 This defaults to standard input unless B<-x509> or B<-CA> is specified.
  93 A request is only read if the creation options
  94 (B<-new> or B<-newkey> or B<-precert>) are not specified.
  95
  96 =item B<-sigopt> I<nm>:I<v>
  97
  98 Pass options to the signature algorithm during sign operations.
  99 Names and values of these options are algorithm-specific.
 100
 101 =item B<-vfyopt> I<nm>:I<v>
 102
 103 Pass options to the signature algorithm during verify operations.
 104 Names and values of these options are algorithm-specific.
 105
 106 =begin comment
 107
 108 Maybe it would be preferable to only have -opts instead of -sigopt and
 109 -vfyopt?  They are both present here to be compatible with L<openssl-ca(1)>,
 110 which supports both options for good reasons.
 111
 112 =end comment
 113
 114 =item B<-passin> I<arg>
 115
 116 The password source for private key and certificate input.
 117 For more information about the format of B<arg>
 118 see L<openssl-passphrase-options(1)>.
 119
 120 =item B<-passout> I<arg>
 121
 122 The password source for the output file.
 123 For more information about the format of B<arg>
 124 see L<openssl-passphrase-options(1)>.
 125
 126 =item B<-out> I<filename>
 127
 128 This specifies the output filename to write to or standard output by default.
 129
 130 =item B<-text>
 131
 132 Prints out the certificate request in text form.
 133
 134 =item B<-subject>
 135
 136 Prints out the certificate request subject
 137 (or certificate subject if B<-x509> is in use).
 138
 139 =item B<-pubkey>
 140
 141 Prints out the public key.
 142
 143 =item B<-noout>
 144
 145 This option prevents output of the encoded version of the certificate request.
 146
 147 =item B<-modulus>
 148
 149 Prints out the value of the modulus of the public key contained in the request.
 150
 151 =item B<-verify>
 152
 153 Verifies the self-signature on the request. If the verification fails,
 154 the program will immediately exit, i.e. further option processing
 155 (e.g. B<-text>) is skipped.
 156
 157 =item B<-new>
 158
 159 This option generates a new certificate request. It will prompt
 160 the user for the relevant field values. The actual fields
 161 prompted for and their maximum and minimum sizes are specified
 162 in the configuration file and any requested extensions.
 163
 164 If the B<-key> option is not given it will generate a new private key
 165 using information specified in the configuration file or given with
 166 the B<-newkey> and B<-pkeyopt> options,
 167 else by default an RSA key with 2048 bits length.
 168
 169 =item B<-newkey> I<arg>
 170
 171 This option is used to generate a new private key unless B<-key> is given.
 172 It is subsequently used as if it was given using the B<-key> option.
 173
 174 This option implies the B<-new> flag to create a new certificate request
 175 or a new certificate in case B<-x509> is used.
 176
 177 The argument takes one of several forms.
 178
 179 [B<rsa:>]I<nbits> generates an RSA key I<nbits> in size.
 180 If I<nbits> is omitted, i.e., B<-newkey> B<rsa> is specified,
 181 the default key size specified in the configuration file
 182 with the B<default_bits> option is used if present, else 2048.
 183
 184 All other algorithms support the B<-newkey> I<algname>:I<file> form, where
 185 I<file> is an algorithm parameter file, created with C<openssl genpkey -genparam>
 186 or an X.509 certificate for a key with appropriate algorithm.
 187
 188 B<param:>I<file> generates a key using the parameter file or certificate
 189 I<file>, the algorithm is determined by the parameters.
 190
 191 I<algname>[:I<file>] generates a key using the given algorithm I<algname>.
 192 If a parameter file I<file> is given then the parameters specified there
 193 are used, where the algorithm parameters must match I<algname>.
 194 If algorithm parameters are not given,
 195 any necessary parameters should be specified via the B<-pkeyopt> option.
 196
 197 B<dsa:>I<filename> generates a DSA key using the parameters
 198 in the file I<filename>. B<ec:>I<filename> generates EC key (usable both with
 199 ECDSA or ECDH algorithms), B<gost2001:>I<filename> generates GOST R
 200 34.10-2001 key (requires B<gost> engine configured in the configuration
 201 file). If just B<gost2001> is specified a parameter set should be
 202 specified by B<-pkeyopt> I<paramset:X>
 203
 204 =item B<-pkeyopt> I<opt>:I<value>
 205
 206 Set the public key algorithm option I<opt> to I<value>. The precise set of
 207 options supported depends on the public key algorithm used and its
 208 implementation.
 209 See L<openssl-genpkey(1)/KEY GENERATION OPTIONS> for more details.
 210
 211 =item B<-key> I<filename>|I<uri>
 212
 213 This option provides the private key for signing a new certificate or
 214 certificate request.
 215 Unless B<-in> is given, the corresponding public key is placed in
 216 the new certificate or certificate request, resulting in a self-signature.
 217
 218 For certificate signing this option is overridden by the B<-CA> option.
 219
 220 This option also accepts PKCS#8 format private keys for PEM format files.
 221
 222 =item B<-keyform> B<DER>|B<PEM>|B<P12>|B<ENGINE>
 223
 224 The format of the private key; unspecified by default.
 225 See L<openssl-format-options(1)> for details.
 226
 227 =item B<-keyout> I<filename>
 228
 229 This gives the filename to write any private key to that has been newly created
 230 or read from B<-key>.  If neither the B<-keyout> option nor the B<-key> option
 231 are given then the filename specified in the configuration file with the
 232 B<default_keyfile> option is used, if present.  Thus, if you want to write the
 233 private key and the B<-key> option is provided, you should provide the
 234 B<-keyout> option explicitly.  If a new key is generated and no filename is
 235 specified the key is written to standard output.
 236
 237 =item B<-noenc>
 238
 239 If this option is specified then if a private key is created it
 240 will not be encrypted.
 241
 242 =item B<-nodes>
 243
 244 This option is deprecated since OpenSSL 3.0; use B<-noenc> instead.
 245
 246 =item B<-I<digest>>
 247
 248 This specifies the message digest to sign the request.
 249 Any digest supported by the OpenSSL B<dgst> command can be used.
 250 This overrides the digest algorithm specified in
 251 the configuration file.
 252
 253 Some public key algorithms may override this choice. For instance, DSA
 254 signatures always use SHA1, GOST R 34.10 signatures always use
 255 GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest.
 256
 257 =item B<-config> I<filename>
 258
 259 This allows an alternative configuration file to be specified.
 260 Optional; for a description of the default value,
 261 see L<openssl(1)/COMMAND SUMMARY>.
 262
 263 =item B<-section> I<name>
 264
 265 Specifies the name of the section to use; the default is B<req>.
 266
 267 =item B<-subj> I<arg>
 268
 269 Sets subject name for new request or supersedes the subject name
 270 when processing a certificate request.
 271
 272 The arg must be formatted as C</type0=value0/type1=value1/type2=...>.
 273 Special characters may be escaped by C<\> (backslash), whitespace is retained.
 274 Empty values are permitted, but the corresponding type will not be included
 275 in the request.
 276 Giving a single C</> will lead to an empty sequence of RDNs (a NULL-DN).
 277 Multi-valued RDNs can be formed by placing a C<+> character instead of a C</>
 278 between the AttributeValueAssertions (AVAs) that specify the members of the set.
 279 Example:
 280
 281 C</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
 282
 283 =item B<-multivalue-rdn>
 284
 285 This option has been deprecated and has no effect.
 286
 287 =item B<-x509>
 288
 289 This option outputs a certificate instead of a certificate request.
 290 This is typically used to generate test certificates.
 291 It is implied by the B<-CA> option.
 292
 293 This option implies the B<-new> flag if B<-in> is not given.
 294
 295 If an existing request is specified with the B<-in> option, it is converted
 296 to a certificate; otherwise a request is created from scratch.
 297
 298 Unless specified using the B<-set_serial> option,
 299 a large random number will be used for the serial number.
 300
 301 Unless the B<-copy_extensions> option is used,
 302 X.509 extensions are not copied from any provided request input file.
 303
 304 X.509 extensions to be added can be specified in the configuration file,
 305 possibly using the B<-config> and B<-extensions> options,
 306 and/or using the B<-addext> option.
 307
 308 Unless B<-x509v1> is given, generated certificates bear X.509 version 3.
 309 Unless specified otherwise,
 310 key identifier extensions are included as described in L<x509v3_config(5)>.
 311
 312 =item B<-x509v1>
 313
 314 Request generation of certificates with X.509 version 1.
 315 This implies B<-x509>.
 316 If X.509 extensions are given, anyway X.509 version 3 is set.
 317
 318 =item B<-CA> I<filename>|I<uri>
 319
 320 Specifies the "CA" certificate to be used for signing a new certificate
 321 and implies use of B<-x509>.
 322 When present, this behaves like a "micro CA" as follows:
 323 The subject name of the "CA" certificate is placed as issuer name in the new
 324 certificate, which is then signed using the "CA" key given as specified below.
 325
 326 =item B<-CAkey> I<filename>|I<uri>
 327
 328 Sets the "CA" private key to sign a certificate with.
 329 The private key must match the public key of the certificate given with B<-CA>.
 330 If this option is not provided then the key must be present in the B<-CA> input.
 331
 332 =item B<-not_before> I<date>
 333
 334 When B<-x509> is in use this allows the start date to be explicitly set,
 335 otherwise it is ignored. The format of I<date> is YYMMDDHHMMSSZ (the
 336 same as an ASN1 UTCTime structure), or YYYYMMDDHHMMSSZ (the same as an
 337 ASN1 GeneralizedTime structure). In both formats, seconds SS and
 338 timezone Z must be present.
 339 Alternatively, you can also use "today".
 340
 341 =item B<-not_after> I<date>
 342
 343 When B<-x509> is in use this allows the expiry date to be explicitly
 344 set, otherwise it is ignored. The format of I<date> is YYMMDDHHMMSSZ
 345 (the same as an ASN1 UTCTime structure), or YYYYMMDDHHMMSSZ (the same as
 346 an ASN1 GeneralizedTime structure). In both formats, seconds SS and
 347 timezone Z must be present.
 348 Alternatively, you can also use "today".
 349
 350 This overrides the B<-days> option.
 351
 352 =item B<-days> I<n>
 353
 354 When B<-x509> is in use this specifies the number of days from today to
 355 certify the certificate for, otherwise it is ignored. I<n> should
 356 be a positive integer. The default is 30 days.
 357
 358 Regardless of the option B<-not_before>, the days are always counted from
 359 today.
 360 When used together with the option B<-not_after>, the explicit expiry
 361 date takes precedence.
 362
 363 =item B<-set_serial> I<n>
 364
 365 Serial number to use when outputting a self-signed certificate.
 366 This may be specified as a decimal value or a hex value if preceded by C<0x>.
 367 If not given, a large random number will be used.
 368
 369 =item B<-copy_extensions> I<arg>
 370
 371 Determines how X.509 extensions in certificate requests should be handled
 372 when B<-x509> is in use.
 373 If I<arg> is B<none> or this option is not present then extensions are ignored.
 374 If I<arg> is B<copy> or B<copyall> then
 375 all extensions in the request are copied to the certificate.
 376
 377 The main use of this option is to allow a certificate request to supply
 378 values for certain extensions such as subjectAltName.
 379
 380 =item B<-extensions> I<section>,
 381 B<-reqexts> I<section>
 382
 383 Can be used to override the name of the configuration file section
 384 from which X.509 extensions are included
 385 in the certificate (when B<-x509> is in use) or certificate request.
 386 This allows several different sections to be used in the same configuration
 387 file to specify requests for a variety of purposes.
 388
 389 =item B<-addext> I<ext>
 390
 391 Add a specific extension to the certificate (if B<-x509> is in use)
 392 or certificate request.  The argument must have the form of
 393 a C<key=value> pair as it would appear in a config file.
 394
 395 This option can be given multiple times.
 396
 397 =item B<-precert>
 398
 399 A poison extension will be added to the certificate, making it a
 400 "pre-certificate" (see RFC6962). This can be submitted to Certificate
 401 Transparency logs in order to obtain signed certificate timestamps (SCTs).
 402 These SCTs can then be embedded into the pre-certificate as an extension, before
 403 removing the poison and signing the certificate.
 404
 405 This implies the B<-new> flag.
 406
 407 =item B<-utf8>
 408
 409 This option causes field values to be interpreted as UTF8 strings, by
 410 default they are interpreted as ASCII. This means that the field
 411 values, whether prompted from a terminal or obtained from a
 412 configuration file, must be valid UTF8 strings.
 413
 414 =item B<-reqopt> I<option>
 415
 416 Customise the printing format used with B<-text>. The I<option> argument can be
 417 a single option or multiple options separated by commas.
 418
 419 See discussion of the  B<-certopt> parameter in the L<openssl-x509(1)>
 420 command.
 421
 422 =item B<-newhdr>
 423
 424 Adds the word B<NEW> to the PEM file header and footer lines on the outputted
 425 request. Some software (Netscape certificate server) and some CAs need this.
 426
 427 =item B<-batch>
 428
 429 Non-interactive mode.
 430
 431 =item B<-verbose>
 432
 433 Print extra details about the operations being performed.
 434
 435 =item B<-quiet>
 436
 437 Print fewer details about the operations being performed, which may be
 438 handy during batch scripts or pipelines (specifically "progress dots"
 439 during key generation are suppressed).
 440
 441 =item B<-keygen_engine> I<id>
 442
 443 Specifies an engine (by its unique I<id> string) which would be used
 444 for key generation operations.
 445
 446 {- $OpenSSL::safe::opt_name_item -}
 447
 448 {- $OpenSSL::safe::opt_r_item -}
 449
 450 {- $OpenSSL::safe::opt_engine_item -}
 451
 452 {- $OpenSSL::safe::opt_provider_item -}
 453
 454 =back
 455
 456 =head1 CONFIGURATION FILE FORMAT
 457
 458 The configuration options are specified in the B<req> section of
 459 the configuration file. An alternate name be specified by using the
 460 B<-section> option.
 461 As with all configuration files, if no
 462 value is specified in the specific section then
 463 the initial unnamed or B<default> section is searched too.
 464
 465 The options available are described in detail below.
 466
 467 =over 4
 468
 469 =item B<input_password>, B<output_password>
 470
 471 The passwords for the input private key file (if present) and
 472 the output private key file (if one will be created). The
 473 command line options B<passin> and B<passout> override the
 474 configuration file values.
 475
 476 =item B<default_bits>
 477
 478 Specifies the default key size in bits.
 479
 480 This option is used in conjunction with the B<-new> option to generate
 481 a new key. It can be overridden by specifying an explicit key size in
 482 the B<-newkey> option. The smallest accepted key size is 512 bits. If
 483 no key size is specified then 2048 bits is used.
 484
 485 =item B<default_keyfile>
 486
 487 This is the default filename to write a private key to. If not
 488 specified the key is written to standard output. This can be
 489 overridden by the B<-keyout> option.
 490
 491 =item B<oid_file>
 492
 493 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
 494 Each line of the file should consist of the numerical form of the
 495 object identifier followed by whitespace then the short name followed
 496 by whitespace and finally the long name.
 497
 498 =item B<oid_section>
 499
 500 This specifies a section in the configuration file containing extra
 501 object identifiers. Each line should consist of the short name of the
 502 object identifier followed by B<=> and the numerical form. The short
 503 and long names are the same when this option is used.
 504
 505 =item B<RANDFILE>
 506
 507 At startup the specified file is loaded into the random number generator,
 508 and at exit 256 bytes will be written to it.
 509 It is used for private key generation.
 510
 511 =item B<encrypt_key>
 512
 513 If this is set to B<no> then if a private key is generated it is
 514 B<not> encrypted. This is equivalent to the B<-noenc> command line
 515 option. For compatibility B<encrypt_rsa_key> is an equivalent option.
 516
 517 =item B<default_md>
 518
 519 This option specifies the digest algorithm to use. Any digest supported by the
 520 OpenSSL B<dgst> command can be used. This option can be overridden on the
 521 command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
 522 any digest that has been set.
 523
 524 =item B<string_mask>
 525
 526 This option masks out the use of certain string types in certain
 527 fields. Most users will not need to change this option. It can be set to
 528 several values:
 529
 530 =over 4
 531
 532 =item B<utf8only>
 533 - only UTF8Strings are used (this is the default value)
 534
 535 =item B<pkix>
 536 - any string type except T61Strings
 537
 538 =item B<nombstr>
 539 - any string type except BMPStrings and UTF8Strings
 540
 541 =item B<default>
 542 - any kind of string type
 543
 544 =back
 545
 546 Note that B<utf8only> is the PKIX recommendation in RFC2459 after 2003, and the
 547 default B<string_mask>; B<default> is not the default option. The B<nombstr>
 548 value is a workaround for some software that has problems with variable-sized
 549 BMPStrings and UTF8Strings.
 550
 551 =item B<req_extensions>
 552
 553 This specifies the configuration file section containing a list of
 554 extensions to add to the certificate request. It can be overridden
 555 by the B<-reqexts> command line switch. See the
 556 L<x509v3_config(5)> manual page for details of the
 557 extension section format.
 558
 559 =item B<x509_extensions>
 560
 561 This specifies the configuration file section containing a list of
 562 extensions to add to certificate generated when B<-x509> is in use.
 563 It can be overridden by the B<-extensions> command line switch.
 564
 565 =item B<prompt>
 566
 567 If set to the value B<no> this disables prompting of certificate fields
 568 and just takes values from the config file directly. It also changes the
 569 expected format of the B<distinguished_name> and B<attributes> sections.
 570
 571 =item B<utf8>
 572
 573 If set to the value B<yes> then field values to be interpreted as UTF8
 574 strings, by default they are interpreted as ASCII. This means that
 575 the field values, whether prompted from a terminal or obtained from a
 576 configuration file, must be valid UTF8 strings.
 577
 578 =item B<attributes>
 579
 580 This specifies the section containing any request attributes: its format
 581 is the same as B<distinguished_name>. Typically these may contain the
 582 challengePassword or unstructuredName types. They are currently ignored
 583 by OpenSSL's request signing utilities but some CAs might want them.
 584
 585 =item B<distinguished_name>
 586
 587 This specifies the section containing the distinguished name fields to
 588 prompt for when generating a certificate or certificate request. The format
 589 is described in the next section.
 590
 591 =back
 592
 593 =head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
 594
 595 There are two separate formats for the distinguished name and attribute
 596 sections. If the B<prompt> option is set to B<no> then these sections
 597 just consist of field names and values: for example,
 598
 599  CN=My Name
 600  OU=My Organization
 601  emailAddress=someone@somewhere.org
 602
 603 This allows external programs (e.g. GUI based) to generate a template file with
 604 all the field names and values and just pass it to this command. An example
 605 of this kind of configuration file is contained in the B<EXAMPLES> section.
 606
 607 Alternatively if the B<prompt> option is absent or not set to B<no> then the
 608 file contains field prompting information. It consists of lines of the form:
 609
 610  fieldName="prompt"
 611  fieldName_default="default field value"
 612  fieldName_min= 2
 613  fieldName_max= 4
 614
 615 "fieldName" is the field name being used, for example commonName (or CN).
 616 The "prompt" string is used to ask the user to enter the relevant
 617 details. If the user enters nothing then the default value is used if no
 618 default value is present then the field is omitted. A field can
 619 still be omitted if a default value is present if the user just
 620 enters the '.' character.
 621
 622 The number of characters entered must be between the fieldName_min and
 623 fieldName_max limits: there may be additional restrictions based
 624 on the field being used (for example countryName can only ever be
 625 two characters long and must fit in a PrintableString).
 626
 627 Some fields (such as organizationName) can be used more than once
 628 in a DN. This presents a problem because configuration files will
 629 not recognize the same name occurring twice. To avoid this problem
 630 if the fieldName contains some characters followed by a full stop
 631 they will be ignored. So for example a second organizationName can
 632 be input by calling it "1.organizationName".
 633
 634 The actual permitted field names are any object identifier short or
 635 long names. These are compiled into OpenSSL and include the usual
 636 values such as commonName, countryName, localityName, organizationName,
 637 organizationalUnitName, stateOrProvinceName. Additionally emailAddress
 638 is included as well as name, surname, givenName, initials, and dnQualifier.
 639
 640 Additional object identifiers can be defined with the B<oid_file> or
 641 B<oid_section> options in the configuration file. Any additional fields
 642 will be treated as though they were a DirectoryString.
 643
 644
 645 =head1 EXAMPLES
 646
 647 Examine and verify certificate request:
 648
 649  openssl req -in req.pem -text -verify -noout
 650
 651 Create a private key and then generate a certificate request from it:
 652
 653  openssl genrsa -out key.pem 2048
 654  openssl req -new -key key.pem -out req.pem
 655
 656 The same but just using req:
 657
 658  openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
 659
 660 Generate a self-signed root certificate:
 661
 662  openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
 663
 664 Create an SM2 private key and then generate a certificate request from it:
 665
 666  openssl ecparam -genkey -name SM2 -out sm2.key
 667  openssl req -new -key sm2.key -out sm2.csr -sm3 -sigopt "distid:1234567812345678"
 668
 669 Examine and verify an SM2 certificate request:
 670
 671  openssl req -verify -in sm2.csr -sm3 -vfyopt "distid:1234567812345678"
 672
 673 Example of a file pointed to by the B<oid_file> option:
 674
 675  1.2.3.4        shortName       A longer Name
 676  1.2.3.6        otherName       Other longer Name
 677
 678 Example of a section pointed to by B<oid_section> making use of variable
 679 expansion:
 680
 681  testoid1=1.2.3.5
 682  testoid2=${testoid1}.6
 683
 684 Sample configuration file prompting for field values:
 685
 686  [ req ]
 687  default_bits           = 2048
 688  default_keyfile        = privkey.pem
 689  distinguished_name     = req_distinguished_name
 690  attributes             = req_attributes
 691  req_extensions         = v3_ca
 692
 693  dirstring_type = nobmp
 694
 695  [ req_distinguished_name ]
 696  countryName                    = Country Name (2 letter code)
 697  countryName_default            = AU
 698  countryName_min                = 2
 699  countryName_max                = 2
 700
 701  localityName                   = Locality Name (eg, city)
 702
 703  organizationalUnitName         = Organizational Unit Name (eg, section)
 704
 705  commonName                     = Common Name (eg, YOUR name)
 706  commonName_max                 = 64
 707
 708  emailAddress                   = Email Address
 709  emailAddress_max               = 40
 710
 711  [ req_attributes ]
 712  challengePassword              = A challenge password
 713  challengePassword_min          = 4
 714  challengePassword_max          = 20
 715
 716  [ v3_ca ]
 717
 718  subjectKeyIdentifier=hash
 719  authorityKeyIdentifier=keyid:always,issuer:always
 720  basicConstraints = critical, CA:true
 721
 722 Sample configuration containing all field values:
 723
 724
 725  [ req ]
 726  default_bits           = 2048
 727  default_keyfile        = keyfile.pem
 728  distinguished_name     = req_distinguished_name
 729  attributes             = req_attributes
 730  prompt                 = no
 731  output_password        = mypass
 732
 733  [ req_distinguished_name ]
 734  C                      = GB
 735  ST                     = Test State or Province
 736  L                      = Test Locality
 737  O                      = Organization Name
 738  OU                     = Organizational Unit Name
 739  CN                     = Common Name
 740  emailAddress           = test@email.address
 741
 742  [ req_attributes ]
 743  challengePassword              = A challenge password
 744
 745 Example of giving the most common attributes (subject and extensions)
 746 on the command line:
 747
 748  openssl req -new -subj "/C=GB/CN=foo" \
 749                   -addext "subjectAltName = DNS:foo.co.uk" \
 750                   -addext "certificatePolicies = 1.2.3.4" \
 751                   -newkey rsa:2048 -keyout key.pem -out req.pem
 752
 753
 754 =head1 NOTES
 755
 756 The certificate requests generated by B<Xenroll> with MSIE have extensions
 757 added. It includes the B<keyUsage> extension which determines the type of
 758 key (signature only or general purpose) and any additional OIDs entered
 759 by the script in an B<extendedKeyUsage> extension.
 760
 761 =head1 DIAGNOSTICS
 762
 763 The following messages are frequently asked about:
 764
 765         Using configuration from /some/path/openssl.cnf
 766         Unable to load config info
 767
 768 This is followed some time later by:
 769
 770         unable to find 'distinguished_name' in config
 771         problems making Certificate Request
 772
 773 The first error message is the clue: it can't find the configuration
 774 file! Certain operations (like examining a certificate request) don't
 775 need a configuration file so its use isn't enforced. Generation of
 776 certificates or requests however does need a configuration file. This
 777 could be regarded as a bug.
 778
 779 Another puzzling message is this:
 780
 781         Attributes:
 782             a0:00
 783
 784 this is displayed when no attributes are present and the request includes
 785 the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
 786 0x00). If you just see:
 787
 788         Attributes:
 789
 790 then the B<SET OF> is missing and the encoding is technically invalid (but
 791 it is tolerated). See the description of the command line option B<-asn1-kludge>
 792 for more information.
 793
 794 =head1 BUGS
 795
 796 OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
 797 treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
 798 This can cause problems if you need characters that aren't available in
 799 PrintableStrings and you don't want to or can't use BMPStrings.
 800
 801 As a consequence of the T61String handling the only correct way to represent
 802 accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
 803 currently chokes on these. If you have to use accented characters with Netscape
 804 and MSIE then you currently need to use the invalid T61String form.
 805
 806 The current prompting is not very friendly. It doesn't allow you to confirm what
 807 you've just entered. Other things like extensions in certificate requests are
 808 statically defined in the configuration file. Some of these: like an email
 809 address in subjectAltName should be input by the user.
 810
 811 =head1 SEE ALSO
 812
 813 L<openssl(1)>,
 814 L<openssl-x509(1)>,
 815 L<openssl-ca(1)>,
 816 L<openssl-genrsa(1)>,
 817 L<openssl-gendsa(1)>,
 818 L<config(5)>,
 819 L<x509v3_config(5)>
 820
 821 =head1 HISTORY
 822
 823 The B<-section> option was added in OpenSSL 3.0.0.
 824
 825 The B<-multivalue-rdn> option has become obsolete in OpenSSL 3.0.0 and
 826 has no effect.
 827
 828 The B<-engine> option was deprecated in OpenSSL 3.0.
 829 The <-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead.
 830
 831 The B<-reqexts> option has been made an alias of B<-extensions> in OpenSSL 3.2.
 832
 833 Since OpenSSL 3.2,
 834 generated certificates bear X.509 version 3 unless B<-x509v1> is given,
 835 and key identifier extensions are included by default.
 836
 837 Since OpenSSL 3.3, the B<-verify> option will exit with 1 on failure.
 838
 839 =head1 COPYRIGHT
 840
 841 Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
 842
 843 Licensed under the Apache License 2.0 (the "License").  You may not use
 844 this file except in compliance with the License.  You can obtain a copy
 845 in the file LICENSE in the source distribution or at
 846 L<https://www.openssl.org/source/license.html>.
 847
 848 =cut