X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fapps%2Freq.pod;h=0ba9a0074fe5d984f2117052ed4a45ceb6371e32;hp=f5cb441b92fba14f7ac4ddecdc23c2cb665c67e7;hb=1fc6d41bf662a8e441226b73ad36d8fa24aaa51d;hpb=a3fe382e2d2d794c598921cd39117581a2a8941b diff --git a/doc/apps/req.pod b/doc/apps/req.pod index f5cb441b92..0ba9a0074f 100644 --- a/doc/apps/req.pod +++ b/doc/apps/req.pod @@ -3,7 +3,7 @@ =head1 NAME -req - PKCS#10 certificate and certificate generating utility. +req - PKCS#10 certificate request and certificate generating utility. =head1 SYNOPSIS @@ -19,6 +19,7 @@ B B [B<-verify>] [B<-modulus>] [B<-new>] +[B<-rand file(s)>] [B<-newkey rsa:bits>] [B<-newkey dsa:file>] [B<-nodes>] @@ -27,11 +28,17 @@ B B [B<-keyout filename>] [B<-[md5|sha1|md2|mdc2]>] [B<-config filename>] +[B<-subj arg>] [B<-x509>] [B<-days n>] -[B<-noasn1-kludge>] +[B<-set_serial n>] +[B<-asn1-kludge>] +[B<-newhdr>] [B<-extensions section>] [B<-reqexts section>] +[B<-utf8>] +[B<-batch>] +[B<-verbose>] =head1 DESCRIPTION @@ -103,6 +110,14 @@ 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<-rand file(s)> + +a file or files containing random data used to seed the random number +generator, or an EGD socket (see L). +Multiple files can be specified separated by a OS-dependent character. +The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for +all others. + =item B<-newkey arg> this option creates a new certificate request and a new private @@ -144,19 +159,33 @@ this allows an alternative configuration file to be specified, this overrides the compile time filename or any specified in the B environment variable. +=item B<-subj arg> + +sets subject name for new request or supersedes the subject name +when processing a request. + =item B<-x509> this option outputs a self signed certificate instead of a certificate request. This is typically used to generate a test certificate or a self signed root CA. The extensions added to the certificate -(if any) are specified in the configuration file. +(if any) are specified in the configuration file. Unless specified +using the B option B<0> will be used for the serial +number. =item B<-days n> when the B<-x509> option is being used this specifies the number of days to certify the certificate for. The default is 30 days. +=item B<-set_serial n> + +serial number to use when outputting a self signed certificate. This +may be specified as a decimal value or a hex value if preceded by B<0x>. +It is possible to use negative serial numbers but this is not recommended. + =item B<-extensions section> + =item B<-reqexts section> these options specify alternative sections to include certificate @@ -165,6 +194,13 @@ request extensions. This allows several different sections to be used in the same configuration file to specify requests for a variety of purposes. +=item B<-utf8> + +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. + =item B<-asn1-kludge> by default the B command outputs certificate requests containing @@ -180,6 +216,19 @@ B whereas the correct form does. It should be noted that very few CAs still require the use of this option. +=item B<-newhdr> + +Adds the word B to the PEM file header and footer lines on the outputed +request. Some software (Netscape certificate server) and some CAs need this. + +=item B<-batch> + +non-interactive mode. + +=item B<-verbose> + +print extra details about the operations being performed. + =back =head1 CONFIGURATION FILE FORMAT @@ -229,7 +278,8 @@ and long names are the same when this option is used. =item B This specifies a filename in which random number seed information is -placed and read from. It is used for private key generation. +placed and read from, or an EGD socket (see L). +It is used for private key generation. =item B @@ -275,6 +325,13 @@ if set to the value B this disables prompting of certificate fields and just takes values from the config file directly. It also changes the expected format of the B and B sections. +=item B + +if set to the value B then 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. + =item B this specifies the section containing any request attributes: its format @@ -302,9 +359,9 @@ just consist of field names and values: for example, This allows external programs (e.g. GUI based) to generate a template file with all the field names and values and just pass it to B. An example -of this kind of configuration files is contained in the B section. +of this kind of configuration file is contained in the B section. -Alternatively if the B option is absent or not set to B the the +Alternatively if the B option is absent or not set to B then the file contains field prompting information. It consists of lines of the form: fieldName="prompt" @@ -327,7 +384,7 @@ two characters long and must fit in a PrintableString). Some fields (such as organizationName) can be used more than once in a DN. This presents a problem because configuration files will not recognize the same name occurring twice. To avoid this problem -if the fieldName contains an some characters followed by a full stop +if the fieldName contains some characters followed by a full stop they will be ignored. So for example a second organizationName can be input by calling it "1.organizationName". @@ -335,8 +392,7 @@ 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, stateOrPrivinceName. Additionally emailAddress -is include as well as name, surname, givenName initials and dnQualifier -are supported. +is include as well as name, surname, givenName initials and dnQualifier. Additional object identifiers can be defined with the B or B options in the configuration file. Any additional fields @@ -439,7 +495,7 @@ Sample configuration containing all field values: =head1 NOTES -The header and footer lines in the B format are respectively: +The header and footer lines in the B format are normally: -----BEGIN CERTIFICATE REQUEST---- -----END CERTIFICATE REQUEST---- @@ -449,7 +505,8 @@ 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. +which is produced with the B<-newhdr> option but is otherwise compatible. +Either form is accepted transparently on input. The certificate requests generated by B with MSIE have extensions added. It includes the B extension which determines the type of