Import of old SSLeay release: SSLeay 0.8.1b
[openssl.git] / doc / req.1
1 The 'req' command is used to manipulate and deal with pkcs#10
2 certificate requests.
3
4 It's default mode of operation is to load a certificate and then
5 write it out again.
6
7 By default the 'req' is read from stdin in 'PEM' format.
8 The -inform option can be used to specify 'pem' format or 'der'
9 format.  PEM format is the base64 encoding of the DER format.
10
11 By default 'req' then writes the request back out. -outform can be used
12 to indicate the desired output format, be it 'pem' or 'der'.
13
14 To specify an input file, use the '-in' option and the '-out' option
15 can be used to specify the output file.
16
17 If you wish to perform a command and not output the certificate
18 request afterwards, use the '-noout' option.
19
20 When a certificate is loaded, it can be printed in a human readable
21 ascii format via the '-text' option.
22
23 To check that the signature on a certificate request is correct, use
24 the '-verify' option to make sure that the private key contained in the
25 certificate request corresponds to the signature.
26
27 Besides the default mode, there is also the 'generate a certificate
28 request' mode.  There are several flags that trigger this mode.
29
30 -new will generate a new RSA key (if required) and then prompts
31 the user for details for the certificate request.
32 -newkey has an argument that is the number of bits to make the new
33 key.  This function also triggers '-new'.
34
35 The '-new' option can have a key to use specified instead of having to
36 load one, '-key' is used to specify the file containg the key.
37 -keyform can be used to specify the format of the key.  Only
38 'pem' and 'der' formats are supported, later, 'netscape' format may be added.
39
40 Finally there is the '-x509' options which makes req output a self
41 signed x509 certificate instead of a certificate request.
42
43 Now as you may have noticed, there are lots of default options that
44 cannot be specified via the command line.  They are held in a 'template'
45 or 'configuration file'.  The -config option specifies which configuration
46 file to use.  See conf.doc for details on the syntax of this file.
47
48 The req command uses the 'req' section of the config file.
49
50 ---
51 # The following variables are defined.  For this example I will populate
52 # the various values
53 [ req ]
54 default_bits    = 512           # default number of bits to use.
55 default_keyfile = testkey.pem   # Where to write the generated keyfile
56                                 # if not specified.
57 distinguished_name= req_dn      # The section that contains the
58                                 # information about which 'object' we
59                                 # want to put in the DN.
60 attributes      = req_attr      # The objects we want for the
61                                 # attributes field.
62 encrypt_rsa_key = no            # Should we encrypt newly generated
63                                 # keys.  I strongly recommend 'yes'.
64
65 # The distinguished name section.  For the following entries, the
66 # object names must exist in the SSLeay header file objects.h.  If they
67 # do not, they will be silently ignored.  The entries have the following
68 # format.
69 # <object_name>         => string to prompt with
70 # <object_name>_default => default value for people
71 # <object_name>_value   => Automatically use this value for this field.
72 # <object_name>_min     => minimum number of characters for data (def. 0)
73 # <object_name>_max     => maximum number of characters for data (def. inf.)
74 # All of these entries are optional except for the first one.
75 [ req_dn ]
76 countryName                     = Country Name (2 letter code)
77 countryName_default             = AU
78
79 stateOrProvinceName             = State or Province Name (full name)
80 stateOrProvinceName_default     = Queensland
81
82 localityName                    = Locality Name (eg, city)
83
84 organizationName                = Organization Name (eg, company)
85 organizationName_default        = Mincom Pty Ltd
86
87 organizationalUnitName          = Organizational Unit Name (eg, section)
88 organizationalUnitName_default  = MTR
89
90 commonName                      = Common Name (eg, YOUR name)
91 commonName_max                  = 64
92
93 emailAddress                    = Email Address
94 emailAddress_max                = 40
95
96 # The next section is the attributes section.  This is exactly the
97 # same as for the previous section except that the resulting objects are
98 # put in the attributes field. 
99 [ req_attr ]
100 challengePassword               = A challenge password
101 challengePassword_min           = 4
102 challengePassword_max           = 20
103
104 unstructuredName                = An optional company name
105
106 ----
107 Also note that the order that attributes appear in this file is the
108 order they will be put into the distinguished name.
109
110 Once this request has been generated, it can be sent to a CA for
111 certifying.
112
113 ----
114 A few quick examples....
115
116 To generate a new request and a new key
117 req -new
118
119 To generate a new request and a 1058 bit key
120 req -newkey 1058
121
122 To generate a new request using a pre-existing key
123 req -new -key key.pem
124
125 To generate a self signed x509 certificate from a certificate
126 request using a supplied key, and we want to see the text form of the
127 output certificate (which we will put in the file selfSign.pem
128 req -x509 -in req.pem -key key.pem -text -out selfSign.pem
129
130 Verify that the signature is correct on a certificate request.
131 req -verify -in req.pem
132
133 Verify that the signature was made using a specified public key.
134 req -verify -in req.pem -key key.pem
135
136 Print the contents of a certificate request
137 req -text -in req.pem