From dd46d58f65bd3a342bbcd8586680942be643fc7d Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Fri, 21 Jan 2000 02:17:04 +0000 Subject: Change the 'man' directory to 'apps'. Yes I wish cvs could rename too :-( --- doc/apps/req.pod | 530 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 530 insertions(+) create mode 100644 doc/apps/req.pod (limited to 'doc/apps/req.pod') diff --git a/doc/apps/req.pod b/doc/apps/req.pod new file mode 100644 index 0000000000..e836f187ac --- /dev/null +++ b/doc/apps/req.pod @@ -0,0 +1,530 @@ + +=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 -- cgit v1.2.3