REQ(1) OpenSSL REQ(1)
NAME
req - PKCS#10
certificate request and certificate generating utility.
# 注释 ：req 是 PKCS#10 证书请求和证书生成工具
SYNOPSIS
openssl req
[-inform PEM│DER] [-outform PEM│DER] [-in filename] [-passin arg] [-out
filename] [-passout arg] [-text]
[-pubkey]
[-noout] [-verify]
[-modulus] [-new] [-rand file(s)] [-newkey rsa:bits] [-newkey dsa:file] [-nodes] [-key filename]
[-keyform PEM│DER] [-keyout
filename] [-[md5│sha1│md2│mdc2]] [-config
filename] [-subj arg] [-x509]
[-days n]
[-set_serial n]
[-asn1-kludge] [-newhdr] [-extensions section] [-reqexts section] [-utf8]
[-nameopt] [-batch]
[-verbose] [-engine id]
DESCRIPTION
The 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.
# 注释 ：req 命令主要是建立和处理证书请求（以 PKCS#10 格式的）。它可以建立
self-signed 证书，这样一个证书就是一个根证书
COMMAND OPTIONS
-inform DER│PEM
This specifies the input format. The DER option
uses an ASN1 DER
encoded form compatible with the PKCS#10. The PEM form
is the
default format: it consists of the DER format base64 encoded
with
additional header and footer lines.
# 注释 ：-inform 用于指定输入的类型是 DER 还是 PEM
-outform DER│PEM
This specifies the output
format, the options have the same mean-
ing as the -inform option.
# 注释 ：-outform 指定输出的格式。
# 补充 ：rsa 子命令也有类似的参数
-in filename
This specifies the input
filename to read a request from or stan-
dard input if this option is not
specified. A request is only read
if the creation options (-new and
-newkey) are not specified.
# 注释 ：-in 指定输入的文件名
-passin arg
the input file password source.
For more information about the
format of arg see the PASS PHRASE
ARGUMENTS section in openssl(1).
-out filename
This specifies the output
filename to write to or standard output
by default.
-passout arg
the output file password
source. For more information about the
format of arg see the PASS PHRASE
ARGUMENTS section in openssl(1).
-text
prints out the certificate request in
text form.
# 注释 ：-text 以文本格式打印打印证书请求内容
-pubkey
outputs the public key.
-noout
this option prevents output of the
encoded version of the request.
-modulus
this option prints out the value of
the modulus of the public key contained in the request.
-verify
verifies the signature on the
request.
-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 con-
figuration file and any requested extensions.
# 注释 ：-new
用于生成一个证书请求。它会提示用户关于一些字段的值。
# 你可以通过 /usr/share/ssl/openssl.cnf
来查看默认会询问那些字段，最大/小长度限制等
If the -key option is not used it will generate a new RSA
private
key using information specified in the configuration file.
# 注释 ：如果 -key 选项没有被指定，则会自动生成一个新的 private
key
-rand file(s)
a file or files containing
random data used to seed the random
number generator, or an EGD socket
(see RAND_egd(3)). Multiple
files can be specified separated by a
OS-dependent character. The
separator is ; for MS-Windows, , for
OpenVMS, and : for all oth-
ers.
-newkey arg
this option creates a new
certificate request and a new private
key. The argument takes one of two
forms. rsa:nbits, where nbits
is the number of bits, generates an RSA key
nbits in size.
dsa:filename generates a DSA key using the parameters in
the file
filename.
# 注释 ：-newkey 建立一个新的证书请求和一个新的 private key
。它的参数格式是 rsa:bits
# 或者 dsa:filename
-key filename
This specifies the file to
read the private key from. It also
accepts PKCS#8 format private keys for
PEM format files.
# 注释 ：-key 指定输入的 private key
-keyform PEM│DER
the format of the private
key file specified in the -key argument.
PEM is the default.
# 注释 ：-keyform 指定 -key 所指定的 key 的格式是 PEM 还是
DER，默认是 PEM
-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.
# 注释 ：-keyout 用于把新建立的私钥输出到指定文件
-nodes
if this option is specified then if a
private key is created it
will not be encrypted.
# 注释 ：-nodes 表示新建立的私钥不加密
-[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.
# 注释 ：-md5|sha1 用于指定使用那种数字摘要算法
-config filename
this allows an alternative
configuration file to be specified,
this overrides the compile time
filename or any specified in the
OPENSSL_CONF environment variable.
# 注释 ：-config 指定配置文件，默认是
/usr/share/ssl/openssl.cnf
-subj arg
sets subject name for new request
or supersedes the subject name
when processing a request. The arg must
be formatted as
/type0=value0/type1=value1/type2=..., characters may be
escaped by
\ (backslash), no spaces are skipped.
# 注释 ：-subj 给出证书的 Subject 字段的值。参数值的格式必须是
/=/type1=...
# 不允许有空格，但可以用 \ 来转义
-x509
this option outputs a self signed
certificate instead of a cer-
tificate request. This is typically used to
generate a test cer-
tificate or a self signed root CA. The extensions
added to the
certificate (if any) are specified in the configuration
file.
Unless specified using the set_serial option 0 will be used
for
the serial number.
# 注释 ：-x509
表示生成一个自签名的证书，而不是一个证书请求。
# 除非使用 -set_serial 选项，否则序列号为 0
-days n
when the -x509 option is being used
this specifies the number of
days to certify the certificate for. The
default is 30 days.
# 注释 ：-days 和 -x509 选项一起用，表示证书的有效期，默认是 30
天
# 补充 ：/usr/share/ssl/openssl.cnf 中规定为 365
天
-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 pre-
ceded by 0x. It is possible to use negative
serial numbers but
this is not recommended.
# 注释 ：-set_serial 和 -x509
一起使用，设置这个证书的编号，可以是10进制也可以是16进制的值（0x 开头）
# 可以使用负数的值，但不建议
-extensions section
-reqexts
section
these options specify alternative sections to include
certificate
extensions (if the -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.
# 注释 ：
-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.
# 注释 ：-utf8 表示字段的值作为 UTF8 编码解读，默认是 ASCII
编码。
-nameopt option
option which determines how
the subject or issuer names are dis-
played. The option argument can be a
single option or multiple
options separated by commas. Alternatively the
-nameopt switch
may be used more than once to set multiple options. See
the
x509(1) manual page for details.
-asn1-kludge
by default the 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 Attributes in a PKCS#10 certificate request
are
defined as a SET OF Attribute. They are not OPTIONAL so if no
attributes are present then they should be encoded as an empty SET
OF.
The invalid form does not include the empty SET OF whereas the
correct
form does.
It should be noted that very few CAs still require the use of
this
option.
-newhdr
Adds the word NEW to the PEM file
header and footer lines on the
outputed request. Some software (Netscape
certificate server) and
some CAs need this.
-batch
non-interactive mode.
# 注释 ：-batch 是非交互模式
-verbose
print extra details about the
operations being performed.
# 注释 ；-verbose 是冗余模式
-engine id
specifying an engine (by it’s
unique id string) will cause 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.
CONFIGURATION FILE FORMAT
The configuration options are specified in the req section of the con-
figuration file. As with all configuration files if no value is speci-
fied in the specific section (i.e. req) then the initial unnamed or
default section is searched too.
# 注释 ：req 命令的配置文件是 /usr/share/ssl/openssl.cnf
，每个选项都有自己的默认值
# 不过该文件只是被 req 命令所使用，象 rsa、genrsa
命令并不能使用该文件
The options available are described in detail below.
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 passin and
passout override the configuration file values.
# 注释 ：相当于 -passin 和 -passout 的默认值。
# 不过会被这两个选项所覆盖
default_bits
This specifies the default key
size in bits. If not specified then
512 is used. It is used if the -new
option is used. It can be
overridden by using the -newkey option.
# 注释 ：default_bits 是 private key
的默认长度。如果没有指定则默认为 512 bit 。
# 补充 ：在 rpm 格式的 openssl 中，该值为 1024
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 over-
ridden by the -keyout option.
# 注释 ：deafult_keyfile 指定默认的 private key
输出文件，而不是默认输入的 private key 文件。
# 默认的值是 stdout ，但可以被 -keyout 选项所覆盖
# 补充 ：在 rpm 格式的 openssl 中，该值为
privatekey.pem
oid_file
This specifies a file containing
additional 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 fol-
lowed by white space and finally the long name.
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 = and the
numerical
form. The short and long names are the same when this option
is
used.
RANDFILE
This specifies a filename in which
random number seed information
is placed and read from, or an EGD socket
(see RAND_egd(3)). It
is used for private key generation.
# 注释 ：RANDFILE 指定一个随机数种子源。
# 默认是 ：
RANDFILE = $dir/private/.rand
encrypt_key
If this is set to no then if a
private key is generated it is not
encrypted. This is equivalent to the
-nodes command line option.
For compatibility encrypt_rsa_key is an
equivalent option.
# 注释 ：encrypt_key 表示如果一个 private key
被生成，是否加密。no 则等于 -nodes ，
# 补充 ：rpm 格式的 openssl 中没有该选项
default_md
This option specifies the digest
algorithm to use. Possible values
include md5 sha1 mdc2. If not present
then MD5 is used. This
option can be overridden on the command
line.
# 注释 ：default_md 设置默认的消息摘要（Message
Digest）算法。可选的有 md5、sha1、mdc2
# 默认是 MD5 。
string_mask
This option masks out the use of
certain string types in certain
fields. Most users will not need to
change this option.
# 注释 ：该选项的默认值是 string_mask =
nombstr
It can be set to several values default which is also the
default
option uses PrintableStrings, T61Strings and BMPStrings if
the
pkix value is used then only PrintableStrings and BMPStrings
will
be used. This follows the PKIX recommendation in RFC2459. If
the
utf8only option is used then only UTF8Strings will be used:
this
is the PKIX recommendation in RFC2459 after 2003. Finally the
nombstr option just uses PrintableStrings and T61Strings: certain
software has problems with BMPStrings and UTF8Strings: in particu-
lar
Netscape.
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 -reqexts command line
switch.
x509_extensions
this specifies the
configuration file section containing a list of
extensions to add to
certificate generated when the -x509 switch
is used. It can be overridden
by the -extensions command line
switch.
prompt
if set to the value no this disables
prompting of certificate
fields and just takes values from the config
file directly. It
also changes the expected format of the
distinguished_name and
attributes sections.
utf8
if set to the value 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.
attributes
this specifies the section
containing any request attributes: its
format is the same as
distinguished_name. Typically these may con-
tain the challengePassword
or unstructuredName types. They are
currently ignored by OpenSSL’s
request signing utilities but some
CAs might want them.
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.
DISTINGUISHED NAME AND ATTRIBUTE SECTION
FORMAT
There are two separate formats for the
distinguished name and
attribute sections. If the prompt option is set
to no then these sec-
tions just consist of field names and values:
for example,
CN=My Name
OU=My Organization
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
req. An
example of this kind of configuration file is contained in the
EXAM-
PLES section.
Alternatively if the prompt option is absent or not set to 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
rele-
vant 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
rec-
ognize 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,
organization-
Name, organizationUnitName, stateOrProvinceName.
Additionally emailAd-
dress is include as well as name, surname,
givenName initials and
dnQualifier.
Additional object identifiers can be defined with the oid_file
or
oid_section options in the configuration file. Any additional
fields
will be treated as though they were a DirectoryString.
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:
# 注释 ：生成一个 PEM 格式的 CSR 文件，新建立一个 private key
，RSA 算法，1024 bit ，并把新生成的 private key 保存为文件 key.pem
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 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 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 =
[ req_attributes ]
challengePassword = A challenge
password
NOTES
The header and footer
lines in the PEM format are normally:
# 注释 ：下面是 PEM 格式的 CSR 文件的 header 和 footer
行
-----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 -newhdr option but is otherwise
compatible.
Either form is accepted transparently on input.
The certificate requests generated by Xenroll with MSIE have
exten-
sions added. It includes the 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.
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 SET OF structure (the DER encoding
of which
is 0xa0 0x00). If you just see:
Attributes:
then the SET OF is missing and the encoding is technically
invalid
(but it is tolerated). See the description of the command line
option
-asn1-kludge for more information.
ENVIRONMENT VARIABLES
The
variable OPENSSL_CONF if defined allows an alternative configura-
tion
file location to be specified, it will be overridden by the -con-
fig
command line switch if it is present. For compatibility reasons
the
SSLEAY_CONF environment variable serves the same purpose but its
use
is discouraged.
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 charac-
ters 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:
unfor-
tunately 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
cer-
tificate requests are statically defined in the configuration
file.
Some of these: like an email address in subjectAltName should be
input
by the user.
SEE ALSO
x509(1), ca(1), genrsa(1), gendsa(1), config(5)
0.9.7a 2003-01-30 REQ(1)
