-
-=pod
-
-=head1 NAME
-
-req - PKCS#10 certificate and certificate generating utility.
-
-=head1 SYNOPSIS
-
-B<openssl> B<req>
-[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<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 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<var>.
-
-=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<var>.
-
-=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<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<-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<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.
-
-=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>, B<envpassin>, B<passout> and
-B<envpassout> 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. 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<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@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<req>. An example
-of this kind of configuration files is contained in the B<EXAMPLES> section.
-
-Alternatively if the B<prompt> option is absent or not set to B<no> 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<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 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<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
-
-x509(1), ca(1), genrsa(1), gendsa(1), config(5)
-
-=cut
projects / openssl.git / blobdiff