460 lines
15 KiB
Text
460 lines
15 KiB
Text
|
|
=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<-out filename>]
|
|
[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<-out filename>
|
|
|
|
This specifies the output filename to write to or standard output by
|
|
default.
|
|
|
|
=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 ignore 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 configuation 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<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
|
|
overriden 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
|
|
overriden 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_rsa_key|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.
|
|
|
|
=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<dirstring_type>
|
|
|
|
This option specifies which string types are permissible in a
|
|
B<DirectoryString>. 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<nobmp>
|
|
option just uses PrintableStrings and T61Strings: certain software has
|
|
problems with BMPStrings.
|
|
|
|
=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<attributes>
|
|
|
|
this specifies the section containing any request attributes: its format
|
|
is the same as B<distinguished_name> described below. Typically these
|
|
may contain the challengePassword or unstructuredName types. They are
|
|
currently ignored by OpenSSLs request signing utilities but some CAs might want
|
|
want them.
|
|
|
|
=item B<distinguished_name>
|
|
|
|
This specifies the section containing the distiguished name fields to
|
|
prompt for when generating a certificate or certificate request. This
|
|
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.
|
|
The "prompt" string is used to ask the user to enter the relvant
|
|
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 recognise 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.
|
|
|
|
=back
|
|
|
|
=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:
|
|
|
|
[ 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
|
|
|
|
=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
|
|
certficates 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 compatability reasons the B<SSLEAY_CONF>
|
|
environment variable serves the same purpose but its use is discouraged.
|
|
|
|
=head1 BUGS
|
|
|
|
OpenSSLs 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 exits if you get the strings
|
|
wrong and 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.
|
|
|
|
There should be a way to have a friendly front end (e.g. perl script or GUI)
|
|
handle all user input and then just feed a "template" file into B<req> which
|
|
then silently creates the request or certificate. This would also shift the
|
|
responsibility for handling such problems as internationalisation of characters
|
|
onto the front end: the template could then just expect valid UTF8 character
|
|
strings for example.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
x509(1), ca(1), genrsa(1), gendsa(1), config(5)
|
|
|
|
=cut
|