X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fapps%2Freq.pod;h=a891c3eeef76eb9fc0b79b5d7d48dffda2c91110;hb=bb9ad09e8ec91d1c3e9c571b4b5ba98980b5fa93;hp=eb840be87fe1126da90445fb29e88afeba6a7910;hpb=3aba132d61baeecffb9a6f8da7d0809352cbfb2d;p=oweals%2Fopenssl.git

diff --git a/doc/apps/req.pod b/doc/apps/req.pod
index eb840be87f..a891c3eeef 100644
--- a/doc/apps/req.pod
+++ b/doc/apps/req.pod
@@ -1,13 +1,13 @@
-
 =pod
 
 =head1 NAME
 
-req - PKCS#10 certificate request and certificate generating utility.
+req - PKCS#10 certificate request and certificate generating utility
 
 =head1 SYNOPSIS
 
 B<openssl> B<req>
+[B<-help>]
 [B<-inform PEM|DER>]
 [B<-outform PEM|DER>]
 [B<-in filename>]
@@ -30,13 +30,10 @@ B<openssl> B<req>
 [B<-keygen_engine id>]
 [B<-[digest]>]
 [B<-config filename>]
-[B<-subj arg>]
 [B<-multivalue-rdn>]
 [B<-x509>]
 [B<-days n>]
 [B<-set_serial n>]
-[B<-asn1-kludge>]
-[B<-no-asn1-kludge>]
 [B<-newhdr>]
 [B<-extensions section>]
 [B<-reqexts section>]
@@ -59,6 +56,10 @@ for use as root CAs for example.
 
 =over 4
 
+=item B<-help>
+
+Print out a usage message.
+
 =item B<-inform DER|PEM>
 
 This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -68,7 +69,7 @@ footer lines.
 
 =item B<-outform DER|PEM>
 
-This specifies the output format, the options have the same meaning as the 
+This specifies the output format, the options have the same meaning as the
 B<-inform> option.
 
 =item B<-in filename>
@@ -80,7 +81,7 @@ options (B<-new> and B<-newkey>) are not specified.
 =item B<-passin arg>
 
 the input file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 
 =item B<-out filename>
 
@@ -90,7 +91,7 @@ default.
 =item B<-passout arg>
 
 the output file password source. For more information about the format of B<arg>
-see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
+see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
 
 =item B<-text>
 
@@ -128,18 +129,11 @@ in the configuration file and any requested extensions.
 If the B<-key> option is not used it will generate a new RSA private
 key using information specified in the configuration file.
 
-=item B<-subj arg>
-
-Replaces subject field of input request with specified data and outputs
-modified request. The arg must be formatted as
-I</type0=value0/type1=value1/type2=...>,
-characters may be escaped by \ (backslash), no spaces are skipped.
-
 =item B<-rand file(s)>
 
 a file or files containing random data used to seed the random number
-generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
-Multiple files can be specified separated by a OS-dependent character.
+generator, or an EGD socket (see L<RAND_egd(3)>).
+Multiple files can be specified separated by an OS-dependent character.
 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
 all others.
 
@@ -153,7 +147,7 @@ the default key size, specified in the configuration file is used.
 
 All other algorithms support the B<-newkey alg:file> form, where file may be
 an algorithm parameter file, created by the B<genpkey -genparam> command
-or and X.509 certificate for a key with approriate algorithm.
+or and X.509 certificate for a key with appropriate algorithm.
 
 B<param:file> generates a key using the parameter file or certificate B<file>,
 the algorithm is determined by the parameters. B<algname:file> use algorithm
@@ -199,8 +193,9 @@ will not be encrypted.
 
 =item B<-[digest]>
 
-this specifies the message digest to sign the request with (such as
-B<-md5>, B<-sha1>). This overrides the digest algorithm specified in
+this specifies the message digest to sign the request.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+This overrides the digest algorithm specified in
 the configuration file.
 
 Some public key algorithms may override this choice. For instance, DSA
@@ -261,7 +256,7 @@ a variety of purposes.
 
 =item B<-utf8>
 
-this option causes field values to be interpreted as UTF8 strings, by 
+this option causes field values to be interpreted as UTF8 strings, by
 default they are interpreted as ASCII. This means that the field
 values, whether prompted from a terminal or obtained from a
 configuration file, must be valid UTF8 strings.
@@ -271,36 +266,16 @@ configuration file, must be valid UTF8 strings.
 option which determines how the subject or issuer names are displayed. The
 B<option> argument can be a single option or multiple options separated by
 commas.  Alternatively the B<-nameopt> switch may be used more than once to
-set multiple options. See the L<x509(1)|x509(1)> manual page for details.
+set multiple options. See the L<x509(1)> manual page for details.
 
 =item B<-reqopt>
 
 customise the output format used with B<-text>. The B<option> argument can be
-a single option or multiple options separated by commas. 
+a single option or multiple options separated by commas.
 
-See discission of the  B<-certopt> parameter in the L<B<x509>|x509(1)>
+See discussion of the  B<-certopt> parameter in the L<x509(1)>
 command.
 
-
-=item B<-asn1-kludge>
-
-by default the B<req> command outputs certificate requests containing
-no attributes in the correct PKCS#10 format. However certain CAs will only
-accept requests containing no attributes in an invalid form: this
-option produces this invalid format.
-
-More precisely the B<Attributes> in a PKCS#10 certificate request
-are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
-if no attributes are present then they should be encoded as an
-empty B<SET OF>. The invalid form does not include the empty
-B<SET OF> whereas the correct form does.
-
-It should be noted that very few CAs still require the use of this option.
-
-=item B<-no-asn1-kludge>
-
-Reverses effect of B<-asn1-kludge>
-
 =item B<-newhdr>
 
 Adds the word B<NEW> to the PEM file header and footer lines on the outputted
@@ -348,9 +323,12 @@ configuration file values.
 
 =item B<default_bits>
 
-This specifies the default key size in bits. If not specified then
-512 is used. It is used if the B<-new> option is used. It can be
-overridden by using the B<-newkey> option.
+Specifies the default key size in bits.
+
+This option is used in conjunction with the B<-new> option to generate
+a new key. It can be overridden by specifying an explicit key size in
+the B<-newkey> option. The smallest accepted key size is 512 bits. If
+no key size is specified then 2048 bits is used.
 
 =item B<default_keyfile>
 
@@ -363,7 +341,7 @@ overridden by the B<-keyout> option.
 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
 Each line of the file should consist of the numerical form of the
 object identifier followed by white space then the short name followed
-by white space and finally the long name. 
+by white space and finally the long name.
 
 =item B<oid_section>
 
@@ -375,7 +353,7 @@ and long names are the same when this option is used.
 =item B<RANDFILE>
 
 This specifies a filename in which random number seed information is
-placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
+placed and read from, or an EGD socket (see L<RAND_egd(3)>).
 It is used for private key generation.
 
 =item B<encrypt_key>
@@ -386,9 +364,10 @@ option. For compatibility B<encrypt_rsa_key> is an equivalent option.
 
 =item B<default_md>
 
-This option specifies the digest algorithm to use. Possible values
-include B<md5 sha1 mdc2>. If not present then MD5 is used. This
-option can be overridden on the command line.
+This option specifies the digest algorithm to use.
+Any digest supported by the OpenSSL B<dgst> command can be used.
+If not present then MD5 is used.
+This option can be overridden on the command line.
 
 =item B<string_mask>
 
@@ -396,7 +375,7 @@ This option masks out the use of certain string types in certain
 fields. Most users will not need to change this option.
 
 It can be set to several values B<default> which is also the default
-option uses PrintableStrings, T61Strings and BMPStrings if the 
+option uses PrintableStrings, T61Strings and BMPStrings if the
 B<pkix> value is used then only PrintableStrings and BMPStrings will
 be used. This follows the PKIX recommendation in RFC2459. If the
 B<utf8only> option is used then only UTF8Strings will be used: this
@@ -408,8 +387,8 @@ problems with BMPStrings and UTF8Strings: in particular Netscape.
 
 this specifies the configuration file section containing a list of
 extensions to add to the certificate request. It can be overridden
-by the B<-reqexts> command line switch. See the 
-L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
+by the B<-reqexts> command line switch. See the
+L<x509v3_config(5)> manual page for details of the
 extension section format.
 
 =item B<x509_extensions>
@@ -490,7 +469,7 @@ be input by calling it "1.organizationName".
 The actual permitted field names are any object identifier short or
 long names. These are compiled into OpenSSL and include the usual
 values such as commonName, countryName, localityName, organizationName,
-organizationUnitName, stateOrProvinceName. Additionally emailAddress
+organizationalUnitName, stateOrProvinceName. Additionally emailAddress
 is include as well as name, surname, givenName initials and dnQualifier.
 
 Additional object identifiers can be defined with the B<oid_file> or
@@ -506,21 +485,21 @@ Examine and verify certificate request:
 
 Create a private key and then generate a certificate request from it:
 
- openssl genrsa -out key.pem 1024
+ openssl genrsa -out key.pem 2048
  openssl req -new -key key.pem -out req.pem
 
 The same but just using req:
 
- openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
+ openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
 
 Generate a self signed root certificate:
 
- openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
+ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
 
 Example of a file pointed to by the B<oid_file> option:
 
- 1.2.3.4	shortName	A longer Name
- 1.2.3.6	otherName	Other longer Name
+ 1.2.3.4        shortName       A longer Name
+ 1.2.3.6        otherName       Other longer Name
 
 Example of a section pointed to by B<oid_section> making use of variable
 expansion:
@@ -531,34 +510,34 @@ expansion:
 Sample configuration file prompting for field values:
 
  [ req ]
- default_bits		= 1024
- default_keyfile 	= privkey.pem
- distinguished_name	= req_distinguished_name
- attributes		= req_attributes
- req_extensions		= v3_ca
+ default_bits           = 2048
+ default_keyfile        = privkey.pem
+ distinguished_name     = req_distinguished_name
+ attributes             = req_attributes
+ req_extensions         = v3_ca
 
  dirstring_type = nobmp
 
  [ req_distinguished_name ]
- countryName			= Country Name (2 letter code)
- countryName_default		= AU
- countryName_min		= 2
- countryName_max		= 2
+ countryName                    = Country Name (2 letter code)
+ countryName_default            = AU
+ countryName_min                = 2
+ countryName_max                = 2
 
- localityName			= Locality Name (eg, city)
+ localityName                   = Locality Name (eg, city)
 
- organizationalUnitName		= Organizational Unit Name (eg, section)
+ organizationalUnitName         = Organizational Unit Name (eg, section)
 
- commonName			= Common Name (eg, YOUR name)
- commonName_max			= 64
+ commonName                     = Common Name (eg, YOUR name)
+ commonName_max                 = 64
 
- emailAddress			= Email Address
- emailAddress_max		= 40
+ emailAddress                   = Email Address
+ emailAddress_max               = 40
 
  [ req_attributes ]
- challengePassword		= A challenge password
- challengePassword_min		= 4
- challengePassword_max		= 20
+ challengePassword              = A challenge password
+ challengePassword_min          = 4
+ challengePassword_max          = 20
 
  [ v3_ca ]
 
@@ -569,27 +548,27 @@ Sample configuration file prompting for field values:
 Sample configuration containing all field values:
 
 
- RANDFILE		= $ENV::HOME/.rnd
+ RANDFILE               = $ENV::HOME/.rnd
 
  [ req ]
- default_bits		= 1024
- default_keyfile 	= keyfile.pem
- distinguished_name	= req_distinguished_name
- attributes		= req_attributes
- prompt			= no
- output_password	= mypass
+ default_bits           = 2048
+ default_keyfile        = keyfile.pem
+ distinguished_name     = req_distinguished_name
+ attributes             = req_attributes
+ prompt                 = no
+ output_password        = mypass
 
  [ req_distinguished_name ]
- C			= GB
- ST			= Test State or Province
- L			= Test Locality
- O			= Organization Name
- OU			= Organizational Unit Name
- CN			= Common Name
- emailAddress		= test@email.address
+ C                      = GB
+ ST                     = Test State or Province
+ L                      = Test Locality
+ O                      = Organization Name
+ OU                     = Organizational Unit Name
+ CN                     = Common Name
+ emailAddress           = test@email.address
 
  [ req_attributes ]
- challengePassword		= A challenge password
+ challengePassword              = A challenge password
 
 
 =head1 NOTES
@@ -616,13 +595,13 @@ by the script in an extendedKeyUsage extension.
 
 The following messages are frequently asked about:
 
-	Using configuration from /some/path/openssl.cnf
-	Unable to load config info
+        Using configuration from /some/path/openssl.cnf
+        Unable to load config info
 
 This is followed some time later by...
 
-	unable to find 'distinguished_name' in config
-	problems making Certificate Request
+        unable to find 'distinguished_name' in config
+        problems making Certificate Request
 
 The first error message is the clue: it can't find the configuration
 file! Certain operations (like examining a certificate request) don't
@@ -649,8 +628,7 @@ for more information.
 
 The variable B<OPENSSL_CONF> if defined allows an alternative configuration
 file location to be specified, it will be overridden by the B<-config> command
-line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
-environment variable serves the same purpose but its use is discouraged.
+line switch if it is present.
 
 =head1 BUGS
 
@@ -671,8 +649,17 @@ address in subjectAltName should be input by the user.
 
 =head1 SEE ALSO
 
-L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
-L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>,
-L<x509v3_config(5)|x509v3_config(5)> 
+L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
+L<gendsa(1)>, L<config(5)>,
+L<x509v3_config(5)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
 
 =cut