Fix some of the command line password stuff. New function
[openssl.git] / doc / man / req.pod
index 8e4a451..0211530 100644 (file)
@@ -11,7 +11,11 @@ B<openssl> B<req>
 [B<-inform PEM|DER>]
 [B<-outform PEM|DER>]
 [B<-in filename>]
+[B<-passin password>]
+[B<-envpassin var>]
 [B<-out filename>]
+[B<-passout password>]
+[B<-envpassout var>]
 [B<-text>]
 [B<-noout>]
 [B<-verify>]
@@ -59,11 +63,29 @@ This specifies the input filename to read a request from or standard input
 if this option is not specified. A request is only read if the creation
 options (B<-new> and B<-newkey>) are not specified.
 
+=item B<-passin password>
+
+the input file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassin var>
+
+read the input file password from the environment variable B<var>.
+
 =item B<-out filename>
 
 This specifies the output filename to write to or standard output by
 default.
 
+=item B<-passout password>
+
+the output file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassout var>
+
+read the output file password from the environment variable B<var>.
+
 =item B<-text>
 
 prints out the certificate request in text form.
@@ -203,8 +225,8 @@ by white space and finally the long name.
 =item B<oid_section>
 
 This specifies a section in the configuration file containing extra
-object identifiers. Each line should consist of the numerical form
-of the object identifier followed by B<=> and its name. The short
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
 and long names are the same when this option is used.
 
 =item B<RANDFILE>
@@ -269,7 +291,7 @@ consists of lines of the form:
        fieldName_min= 2
        fieldName_max= 4
 
-"fieldName" is the field name being used, for example commonName.
+"fieldName" is the field name being used, for example commonName (or CN).
 The "prompt" string is used to ask the user to enter the relvant
 details. If the user enters nothing then the default value is used if no
 default value is present then the field is omitted. A field can
@@ -299,32 +321,89 @@ Additional object identifiers can be defined with the B<oid_file> or
 B<oid_section> options in the configuration file. Any additional fields
 will be treated as though they were a DirectoryString.
 
+=back
+
 =head1 EXAMPLES
 
 Examine and verify certificate request:
 
-openssl req -in req.pem -text -verify -noout
+ openssl req -in req.pem -text -verify -noout
 
 Create a private key and then generate a certificate request from it:
 
-openssl genrsa -out key.pem 1024
-openssl req -new -key key.pem -out req.pem
+ openssl genrsa -out key.pem 1024
+ 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:1024 -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:1024 -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
+
+Example of a section pointed to by B<oid_section> making use of variable
+expansion:
+
+ testoid1=1.2.3.5
+ testoid2=${testoid1}.6
+
+Sample configuration file:
+
+ [ req ]
+ default_bits          = 1024
+ default_keyfile       = privkey.pem
+ distinguished_name    = req_distinguished_name
+ attributes            = req_attributes
+ x509_extensions       = v3_ca
+
+ dirstring_type = nobmp
+
+ [ req_distinguished_name ]
+ countryName                   = Country Name (2 letter code)
+ countryName_default           = AU
+ countryName_min                       = 2
+ countryName_max                       = 2
+
+ localityName                  = Locality Name (eg, city)
+
+ organizationalUnitName                = Organizational Unit Name (eg, section)
+
+ commonName                    = Common Name (eg, YOUR name)
+ commonName_max                        = 64
+
+ emailAddress                  = Email Address
+ emailAddress_max              = 40
+
+ [ req_attributes ]
+ challengePassword             = A challenge password
+ challengePassword_min         = 4
+ challengePassword_max         = 20
+
+ [ v3_ca ]
+
+ subjectKeyIdentifier=hash
+ authorityKeyIdentifier=keyid:always,issuer:always
+ basicConstraints = CA:true
 
 =head1 NOTES
 
-The header and footer lines in the B<PEM> format contain the words
-B<BEGIN CERTIFICATE REQUEST> and B<END CERTIFICATE REQUEST> some software
-(for example some versions of Netscape certificate server) requires the
-words B<BEGIN NEW CERTIFICATE REQUEST> and B<END NEW CERTIFICATE REQUEST>
-instead.
+The header and footer lines in the B<PEM> format are respectively:
+
+ -----BEGIN CERTIFICATE REQUEST----
+ -----END CERTIFICATE REQUEST----
+
+some software (some versions of Netscape certificate server) instead needs:
+
+ -----BEGIN NEW CERTIFICATE REQUEST----
+ -----END NEW CERTIFICATE REQUEST----
+
+but is otherwise compatible. Either form is accepted on input.
 
 The certificate requests generated by B<Xenroll> with MSIE have extensions
 added. It includes the B<keyUsage> extension which determines the type of