Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
REQ(1)				    OpenSSL				REQ(1)

NAME
       req - PKCS#10 certificate request and certificate generating utility.

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 file-
       name] [-[md5|sha1|md2|mdc2]] [-config filename] [-subj arg] [-x509]
       [-days n] [-set_serial n] [-asn1-kludge]	[-newhdr] [-extensions sec-
       tion] [-reqexts section]	[-utf8]	[-nameopt] [-batch] [-verbose] [-en-
       gine 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.

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 de-
	   fault format: it consists of	the DER	format base64 encoded with ad-
	   ditional header and footer lines.

       -outform	DER|PEM
	   This	specifies the output format, the options have the same meaning
	   as the -inform option.

       -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.

       -passin arg
	   the input file password source. For more information	about the for-
	   mat 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.

       -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 configura-
	   tion	file and any requested extensions.

	   If the -key option is not used it will generate a new RSA private
	   key using information specified in the configuration	file.

       -rand file(s)
	   a file or files containing random data used to seed the random num-
	   ber generator, or an	EGD socket (see	RAND_egd(3)).  Multiple	files
	   can be specified separated by a OS-dependent	character.  The	sepa-
	   rator is ; for MS-Windows, ,	for OpenVMS, and : for all others.

       -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:file-
	   name	generates a DSA	key using the parameters in the	file filename.

       -key filename
	   This	specifies the file to read the private key from. It also ac-
	   cepts PKCS#8	format private keys for	PEM format files.

       -keyform	PEM|DER
	   the format of the private key file specified	in the -key argument.
	   PEM is the default.

       -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.

       -nodes
	   if this option is specified then if a private key is	created	it
	   will	not be encrypted.

       -[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.

       -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.

       -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.

       -x509
	   this	option outputs a self signed certificate instead of a certifi-
	   cate	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 set_serial	option 0 will be used for the serial number.

       -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.

       -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 0x.  It is possible to use negative serial numbers but this is
	   not recommended.

       -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 config-
	   uration file, must be valid UTF8 strings.

       -nameopt	option
	   option which	determines how the subject or issuer names are dis-
	   played. The option argument can be a	single option or multiple op-
	   tions 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 at-
	   tributes 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.

       -verbose
	   print extra details about the operations being performed.

       -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 de-
       fault section is	searched too.

       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.

       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 over-
	   ridden by using the -newkey option.

       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.

       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.

       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.

       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.

       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 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 particular Net-
	   scape.

       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 at-
	   tributes 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 cur-
	   rently 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 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 req. An
       example of this kind of configuration file is contained in the EXAMPLES
       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 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 charac-
       ters 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	recog-
       nize the	same name occurring twice. To avoid this problem if the	field-
       Name contains some characters followed by a full	stop they will be ig-
       nored. 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 val-
       ues 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 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:

	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	       = test@email.address

	[ req_attributes ]
	challengePassword	       = A challenge password

NOTES
       The header and footer lines in the 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 -newhdr option but is	otherwise compatible.
       Either form is accepted transparently on	input.

       The certificate requests	generated by Xenroll with MSIE have extensions
       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 cer-
       tificates 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	in-
       cludes 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 ef-
       fectively 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 rep-
       resent accented characters in OpenSSL is	to use a BMPString: unfortu-
       nately 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.7d				  2005-02-25				REQ(1)

NAME | SYNOPSIS | DESCRIPTION | COMMAND OPTIONS | CONFIGURATION FILE FORMAT | DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT | EXAMPLES | NOTES | DIAGNOSTICS | ENVIRONMENT VARIABLES | BUGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=req&sektion=1&manpath=FreeBSD+6.4-RELEASE>

home | help