X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman%2Freq.pod;fp=doc%2Fman%2Freq.pod;h=0000000000000000000000000000000000000000;hp=e836f187acebb1cf587b54b0ad91030191319e03;hb=dd46d58f65bd3a342bbcd8586680942be643fc7d;hpb=e7f97e2d22e386df60c8da63277727a931bf22b7 diff --git a/doc/man/req.pod b/doc/man/req.pod deleted file mode 100644 index e836f187ac..0000000000 --- a/doc/man/req.pod +++ /dev/null @@ -1,530 +0,0 @@ - -=pod - -=head1 NAME - -req - PKCS#10 certificate and certificate generating utility. - -=head1 SYNOPSIS - -B B -[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>] -[B<-modulus>] -[B<-new>] -[B<-newkey rsa:bits>] -[B<-newkey dsa:file>] -[B<-nodes>] -[B<-key filename>] -[B<-keyform PEM|DER>] -[B<-keyout filename>] -[B<-[md5|sha1|md2|mdc2]>] -[B<-config filename>] -[B<-x509>] -[B<-days n>] -[B<-noasn1-kludge>] -[B<-extensions section>] -[B<-reqexts section>] - -=head1 DESCRIPTION - -The B command primarily creates and processes certificate requests -in PKCS#10 format. It can additionally create self signed certificates -for use as root CAs for example. - -=head1 COMMAND OPTIONS - -=over 4 - -=item B<-inform DER|PEM> - -This specifies the input format. The B option uses an ASN1 DER encoded -form compatible with the PKCS#10. The B form is the default format: it -consists of the B format base64 encoded with additional header and -footer lines. - -=item B<-outform DER|PEM> - -This specifies the output format, the options have the same meaning as the -B<-inform> option. - -=item B<-in filename> - -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. - -=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. - -=item B<-text> - -prints out the certificate request in text form. - -=item B<-noout> - -this option prevents output of the encoded version of the request. - -=item B<-modulus> - -this option prints out the value of the modulus of the public key -contained in the request. - -=item B<-verify> - -verifies the signature on the request. - -=item B<-new> - -this option generates a new certificate request. It will prompt -the user for the relevant field values. The actual fields -prompted for and their maximum and minimum sizes are specified -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<-newkey arg> - -this option creates a new certificate request and a new private -key. The argument takes one of two forms. B, where -B is the number of bits, generates an RSA key B -in size. B generates a DSA key using the parameters -in the file B. - -=item B<-key filename> - -This specifies the file to read the private key from. It also -accepts PKCS#8 format private keys for PEM format files. - -=item B<-keyform PEM|DER> - -the format of the private key file specified in the B<-key> -argument. PEM is the default. - -=item B<-keyout filename> - -this gives the filename to write the newly created private key to. -If this option is not specified then the filename present in the -configuration file is used. - -=item B<-nodes> - -if this option is specified then if a private key is created it -will not be encrypted. - -=item B<-[md5|sha1|md2|mdc2]> - -this specifies the message digest to sign the request with. This -overrides the digest algorithm specified in the configuration file. -This option is ignored for DSA requests: they always use SHA1. - -=item B<-config filename> - -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<-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. - -=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<-extensions section> -=item B<-reqexts section> - -these options specify alternative sections to include certificate -extensions (if the B<-x509> option is present) or certificate -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<-asn1-kludge> - -by default the B 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 in a PKCS#10 certificate request -are defined as a B. They are B so -if no attributes are present then they should be encoded as an -empty B. The invalid form does not include the empty -B whereas the correct form does. - -It should be noted that very few CAs still require the use of this option. - -=back - -=head1 CONFIGURATION FILE FORMAT - -The configuration options are specified in the B section of -the configuration file. As with all configuration files if no -value is specified in the specific section (i.e. B) then -the initial unnamed or B section is searched too. - -The options available are described in detail below. - -=over 4 - -=item B - -The passwords for the input private key file (if present) and -the output private key file (if one will be created). The -command line options B, B, B and -B override the configuration file values. - -=item B - -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. - -=item B - -This is the default filename to write a private key to. If not -specified the key is written to standard output. This can be -overridden by the B<-keyout> option. - -=item B - -This specifies a file containing additional B. -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. - -=item B - -This specifies a section in the configuration file containing extra -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 - -This specifies a filename in which random number seed information is -placed and read from. It is used for private key generation. - -=item B - -If this is set to B then if a private key is generated it is -B encrypted. This is equivalent to the B<-nodes> command line -option. For compatibility B is an equivalent option. - -=item B - -This option specifies the digest algorithm to use. Possible values -include B. If not present then MD5 is used. This -option can be overridden on the command line. - -=item B - -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 which is also the default -option uses PrintableStrings, T61Strings and BMPStrings if the -B value is used then only PrintableStrings and BMPStrings will -be used. This follows the PKIX recommendation in RFC2459. If the -B option is used then only UTF8Strings will be used: this -is the PKIX recommendation in RFC2459 after 2003. Finally the B -option just uses PrintableStrings and T61Strings: certain software has -problems with BMPStrings and UTF8Strings: in particular Netscape. - -=item B - -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. - -=item B - -this specifies the configuration file section containing a list of -extensions to add to certificate generated when the B<-x509> switch -is used. It can be overridden by the B<-extensions> command line switch. - -=item B - -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 - -this specifies the section containing any request attributes: its format -is the same as B. Typically these may contain the -challengePassword or unstructuredName types. They are currently ignored -by OpenSSL's request signing utilities but some CAs might want them. - -=item B - -This specifies the section containing the distinguished name fields to -prompt for when generating a certificate or certificate request. The format -is described in the next section. - -=back - -=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT - -There are two separate formats for the distinguished name and attribute -sections. If the B option is set to B then these sections -just consist of field names and values: for example, - - CN=My Name - OU=My Organization - emailAddress=someone@somehere.org - -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. - -Alternatively if the B option is absent or not set to B the the -file contains field prompting information. It consists of lines of the form: - - fieldName="prompt" - fieldName_default="default field value" - fieldName_min= 2 - fieldName_max= 4 - -"fieldName" is the field name being used, for example commonName (or CN). -The "prompt" string is used to ask the user to enter the relevant -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 -still be omitted if a default value is present if the user just -enters the '.' character. - -The number of characters entered must be between the fieldName_min and -fieldName_max limits: there may be additional restrictions based -on the field being used (for example countryName can only ever be -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 -they will be ignored. So for example a second organizationName can -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, stateOrPrivinceName. Additionally emailAddress -is include as well as name, surname, givenName initials and dnQualifier -are supported. - -Additional object identifiers can be defined with the B or -B options in the configuration file. Any additional fields -will be treated as though they were a DirectoryString. - - -=head1 EXAMPLES - -Examine and verify certificate request: - - 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 - -The same but just using req: - - 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 - -Example of a file pointed to by the B 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 making use of variable -expansion: - - testoid1=1.2.3.5 - testoid2=${testoid1}.6 - -Sample configuration file prompting for field values: - - [ 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 - -Sample configuration containing all field values: - - - 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 - - [ 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 - - [ req_attributes ] - challengePassword = A challenge password - - -=head1 NOTES - -The header and footer lines in the B 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 with MSIE have extensions -added. It includes the B extension which determines the type of -key (signature only or general purpose) and any additional OIDs entered -by the script in an extendedKeyUsage extension. - -=head1 DIAGNOSTICS - -The following messages are frequently asked about: - - 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 - -The first error message is the clue: it can't find the configuration -file! Certain operations (like examining a certificate request) don't -need a configuration file so its use isn't enforced. Generation of -certificates or requests however does need a configuration file. This -could be regarded as a bug. - -Another puzzling message is this: - - Attributes: - a0:00 - -this is displayed when no attributes are present and the request includes -the correct empty B structure (the DER encoding of which is 0xa0 -0x00). If you just see: - - Attributes: - -then the B is missing and the encoding is technically invalid (but -it is tolerated). See the description of the command line option B<-asn1-kludge> -for more information. - -=head1 ENVIRONMENT VARIABLES - -The variable B 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 -environment variable serves the same purpose but its use is discouraged. - -=head1 BUGS - -OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively -treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour. -This can cause problems if you need characters that aren't available in -PrintableStrings and you don't want to or can't use BMPStrings. - -As a consequence of the T61String handling the only correct way to represent -accented characters in OpenSSL is to use a BMPString: unfortunately Netscape -currently chokes on these. If you have to use accented characters with Netscape -and MSIE then you currently need to use the invalid T61String form. - -The current prompting is not very friendly. It doesn't allow you to confirm what -you've just entered. Other things like extensions in certificate requests are -statically defined in the configuration file. Some of these: like an email -address in subjectAltName should be input by the user. - -=head1 SEE ALSO - -x509(1), ca(1), genrsa(1), gendsa(1), config(5) - -=cut