diff options
Diffstat (limited to 'crypto/openssl/doc/apps/req.pod')
| -rw-r--r-- | crypto/openssl/doc/apps/req.pod | 611 |
1 files changed, 0 insertions, 611 deletions
diff --git a/crypto/openssl/doc/apps/req.pod b/crypto/openssl/doc/apps/req.pod deleted file mode 100644 index 82b565c..0000000 --- a/crypto/openssl/doc/apps/req.pod +++ /dev/null @@ -1,611 +0,0 @@ - -=pod - -=head1 NAME - -req - PKCS#10 certificate request and certificate generating utility. - -=head1 SYNOPSIS - -B<openssl> B<req> -[B<-inform PEM|DER>] -[B<-outform PEM|DER>] -[B<-in filename>] -[B<-passin arg>] -[B<-out filename>] -[B<-passout arg>] -[B<-text>] -[B<-pubkey>] -[B<-noout>] -[B<-verify>] -[B<-modulus>] -[B<-new>] -[B<-rand file(s)>] -[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<-subj arg>] -[B<-multivalue-rdn>] -[B<-x509>] -[B<-days n>] -[B<-set_serial n>] -[B<-asn1-kludge>] -[B<-newhdr>] -[B<-extensions section>] -[B<-reqexts section>] -[B<-utf8>] -[B<-nameopt>] -[B<-batch>] -[B<-verbose>] -[B<-engine id>] - -=head1 DESCRIPTION - -The B<req> 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<DER> option uses an ASN1 DER encoded -form compatible with the PKCS#10. The B<PEM> form is the default format: it -consists of the B<DER> 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 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)>. - -=item B<-out filename> - -This specifies the output filename to write to or standard output by -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)>. - -=item B<-text> - -prints out the certificate request in text form. - -=item B<-pubkey> - -outputs the public key. - -=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<-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. -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 -key. The argument takes one of two forms. B<rsa:nbits>, where -B<nbits> is the number of bits, generates an RSA key B<nbits> -in size. B<dsa:filename> generates a DSA key using the parameters -in the file B<filename>. - -=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<OPENSSL_CONF> environment variable. - -=item B<-subj arg> - -sets subject name for new request or supersedes the subject name -when processing a 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<-multivalue-rdn> - -this option causes the -subj argument to be interpreted with full -support for multivalued RDNs. Example: - -I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe> - -If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>. - -=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. Unless specified -using the B<set_serial> 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 -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<-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<-nameopt option> - -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. - -=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<-newhdr> - -Adds the word B<NEW> 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. - -=item B<-engine id> - -specifying an engine (by it's unique B<id> string) will cause B<req> -to attempt to obtain a functional reference to the specified engine, -thus initialising it if needed. The engine will then be set as the default -for all available algorithms. - -=back - -=head1 CONFIGURATION FILE FORMAT - -The configuration options are specified in the B<req> section of -the configuration file. As with all configuration files if no -value is specified in the specific section (i.e. B<req>) then -the initial unnamed or B<default> section is searched too. - -The options available are described in detail below. - -=over 4 - -=item B<input_password output_password> - -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<passin> and B<passout> override the -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. - -=item B<default_keyfile> - -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<oid_file> - -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. - -=item B<oid_section> - -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<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)>). -It is used for private key generation. - -=item B<encrypt_key> - -If this is set to B<no> then if a private key is generated it is -B<not> encrypted. This is equivalent to the B<-nodes> command line -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. - -=item B<string_mask> - -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 -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 -is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr> -option just uses PrintableStrings and T61Strings: certain software has -problems with BMPStrings and UTF8Strings: in particular Netscape. - -=item B<req_extensions> - -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<x509_extensions> - -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<prompt> - -if set to the value B<no> this disables prompting of certificate fields -and just takes values from the config file directly. It also changes the -expected format of the B<distinguished_name> and B<attributes> sections. - -=item B<utf8> - -if set to the value B<yes> 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<attributes> - -this specifies the section containing any request attributes: its format -is the same as B<distinguished_name>. 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<distinguished_name> - -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<prompt> option is set to B<no> then these sections -just consist of field names and values: for example, - - CN=My Name - OU=My Organization - emailAddress=someone@somewhere.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<req>. An example -of this kind of configuration file is contained in the B<EXAMPLES> section. - -Alternatively if the B<prompt> option is absent or not set to B<no> then 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 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, 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 -B<oid_section> 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<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 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<PEM> format are normally: - - -----BEGIN CERTIFICATE REQUEST----- - -----END CERTIFICATE REQUEST----- - -some software (some versions of Netscape certificate server) instead needs: - - -----BEGIN NEW CERTIFICATE REQUEST----- - -----END NEW CERTIFICATE REQUEST----- - -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<Xenroll> with MSIE have extensions -added. It includes the B<keyUsage> 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<SET OF> structure (the DER encoding of which is 0xa0 -0x00). If you just see: - - Attributes: - -then the B<SET OF> 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<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. - -=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 - -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)> - -=cut |
