REQ(1)                      OpenSSL                      REQ(1)





NAME
       req - PKCS#10 certificate request and certificate gener-
       ating 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
       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 certifi-
       cate 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 default format: it con-
           sists of the DER format base64 encoded with addi-
           tional 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 standard input if this option is not speci-
           fied. 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 format of arg see the PASS PHRASE ARGU-
           MENTS 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 informa-
           tion 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 configuration
           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 number generator, or an EGD socket (see
           RAND_egd(3)).  Multiple files can be specified sepa-
           rated 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.

       -key filename
           This specifies the file to read the private key
           from. It also accepts 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 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. 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 pos-
           sible 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 configu-
           ration file, must be valid UTF8 strings.

       -nameopt option
           option which determines how the subject or issuer
           names are displayed. The option argument can be a
           single option or multiple options separated by com-
           mas.  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 certifi-
           cate 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.

       -verbose
           print extra details about the operations being per-
           formed.

       -engine id
           specifying an engine (by it's unique id string) will
           cause req to attempt to obtain a functional refer-
           ence 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 sec-
       tion of the configuration file. As with all configura-
       tion files if no value is specified in the specific sec-
       tion (i.e. req) then the initial unnamed or default sec-
       tion 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 overridden 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 overridden 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 fol-
           lowed by white space then the short name followed 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 iden-
           tifier 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 gener-
           ated 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 over-
           ridden 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 recommen-
           dation in RFC2459 after 2003. Finally the nombstr
           option just uses PrintableStrings and T61Strings:
           certain software has problems with BMPStrings and
           UTF8Strings: in particular Netscape.

       req_extensions
           this specifies the configuration file section con-
           taining a list of extensions to add to the certifi-
           cate request. It can be overridden by the -reqexts
           command line switch.

       x509_extensions
           this specifies the configuration file section con-
           taining 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 sec-
           tions.

       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 val-
           ues, 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 distin-
           guished_name. Typically these may contain the chal-
           lengePassword or unstructuredName types. They are
           currently ignored by OpenSSL's request signing util-
           ities but some CAs might want them.

       distinguished_name
           This specifies the section containing the distin-
           guished 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 gener-
       ate a template file with all the field names and values
       and just pass it to req. An example of this kind of con-
       figuration 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 informa-
       tion. 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 con-
       figuration files will not recognize the same name occur-
       ring twice. To avoid this problem if the fieldName con-
       tains 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 identi-
       fier short or long names. These are compiled into
       OpenSSL and include the usual values such as commonName,
       countryName, localityName, organizationName, organiza-
       tionUnitName, 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:

        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 nor-
       mally:

        -----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 other-
       wise compatible.  Either form is accepted transparently
       on input.

       The certificate requests generated by Xenroll with MSIE
       have extensions added. It includes the keyUsage exten-
       sion 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 techni-
       cally invalid (but it is tolerated). See the description
       of the command line option -asn1-kludge for more infor-
       mation.

ENVIRONMENT VARIABLES
       The variable OPENSSL_CONF if defined allows an alterna-
       tive configuration file location to be specified, it
       will be overridden by the -config 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 characters that aren't avail-
       able in PrintableStrings and you don't want to or can't
       use BMPStrings.

       As a consequence of the T61String handling the only cor-
       rect 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 stat-
       ically 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.7c                     2003-01-30                    REQ(1)
