diff options
Diffstat (limited to 'openssl/doc/apps/req.pod')
| -rw-r--r-- | openssl/doc/apps/req.pod | 611 |
1 files changed, 611 insertions, 0 deletions
diff --git a/openssl/doc/apps/req.pod b/openssl/doc/apps/req.pod new file mode 100644 index 000000000..82b565c9d --- /dev/null +++ b/openssl/doc/apps/req.pod @@ -0,0 +1,611 @@ + +=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 |