Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / usr.bin / openssl / man / rsautl.1
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  | will give a
29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
32 .tr \(*W-|\(bv\*(Tr
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .if \nF \{\
56 .    de IX
57 .    tm Index:\\$1\t\\n%\t"\\$2"
58 ..
59 .    nr % 0
60 .    rr F
61 .\}
62 .\"
63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
65 .hy 0
66 .if n .na
67 .\"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
70 .    \" fudge factors for nroff and troff
71 .if n \{\
72 .    ds #H 0
73 .    ds #V .8m
74 .    ds #F .3m
75 .    ds #[ \f1
76 .    ds #] \fP
77 .\}
78 .if t \{\
79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80 .    ds #V .6m
81 .    ds #F 0
82 .    ds #[ \&
83 .    ds #] \&
84 .\}
85 .    \" simple accents for nroff and troff
86 .if n \{\
87 .    ds ' \&
88 .    ds ` \&
89 .    ds ^ \&
90 .    ds , \&
91 .    ds ~ ~
92 .    ds /
93 .\}
94 .if t \{\
95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101 .\}
102 .    \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 .    \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 .    \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
117 \{\
118 .    ds : e
119 .    ds 8 ss
120 .    ds o a
121 .    ds d- d\h'-1'\(ga
122 .    ds D- D\h'-1'\(hy
123 .    ds th \o'bp'
124 .    ds Th \o'LP'
125 .    ds ae ae
126 .    ds Ae AE
127 .\}
128 .rm #[ #] #H #V #F C
129 .\" ========================================================================
130 .\"
131 .IX Title "RSAUTL 1"
132 .TH RSAUTL 1 "2008-09-06" "0.9.8h" "OpenSSL"
133 .SH "NAME"
134 rsautl \- RSA utility
135 .SH "SYNOPSIS"
136 .IX Header "SYNOPSIS"
137 \&\fBopenssl\fR \fBrsautl\fR
138 [\fB\-in file\fR]
139 [\fB\-out file\fR]
140 [\fB\-inkey file\fR]
141 [\fB\-pubin\fR]
142 [\fB\-certin\fR]
143 [\fB\-sign\fR]
144 [\fB\-verify\fR]
145 [\fB\-encrypt\fR]
146 [\fB\-decrypt\fR]
147 [\fB\-pkcs\fR]
148 [\fB\-ssl\fR]
149 [\fB\-raw\fR]
150 [\fB\-hexdump\fR]
151 [\fB\-asn1parse\fR]
152 .SH "DESCRIPTION"
153 .IX Header "DESCRIPTION"
154 The \fBrsautl\fR command can be used to sign, verify, encrypt and decrypt
155 data using the \s-1RSA\s0 algorithm.
156 .SH "COMMAND OPTIONS"
157 .IX Header "COMMAND OPTIONS"
158 .IP "\fB\-in filename\fR" 4
159 .IX Item "-in filename"
160 This specifies the input filename to read data from or standard input
161 if this option is not specified.
162 .IP "\fB\-out filename\fR" 4
163 .IX Item "-out filename"
164 specifies the output filename to write to or standard output by
165 default.
166 .IP "\fB\-inkey file\fR" 4
167 .IX Item "-inkey file"
168 the input key file, by default it should be an \s-1RSA\s0 private key.
169 .IP "\fB\-pubin\fR" 4
170 .IX Item "-pubin"
171 the input file is an \s-1RSA\s0 public key. 
172 .IP "\fB\-certin\fR" 4
173 .IX Item "-certin"
174 the input is a certificate containing an \s-1RSA\s0 public key. 
175 .IP "\fB\-sign\fR" 4
176 .IX Item "-sign"
177 sign the input data and output the signed result. This requires
178 and \s-1RSA\s0 private key.
179 .IP "\fB\-verify\fR" 4
180 .IX Item "-verify"
181 verify the input data and output the recovered data.
182 .IP "\fB\-encrypt\fR" 4
183 .IX Item "-encrypt"
184 encrypt the input data using an \s-1RSA\s0 public key.
185 .IP "\fB\-decrypt\fR" 4
186 .IX Item "-decrypt"
187 decrypt the input data using an \s-1RSA\s0 private key.
188 .IP "\fB\-pkcs, \-oaep, \-ssl, \-raw\fR" 4
189 .IX Item "-pkcs, -oaep, -ssl, -raw"
190 the padding to use: PKCS#1 v1.5 (the default), PKCS#1 \s-1OAEP\s0,
191 special padding used in \s-1SSL\s0 v2 backwards compatible handshakes,
192 or no padding, respectively.
193 For signatures, only \fB\-pkcs\fR and \fB\-raw\fR can be used.
194 .IP "\fB\-hexdump\fR" 4
195 .IX Item "-hexdump"
196 hex dump the output data.
197 .IP "\fB\-asn1parse\fR" 4
198 .IX Item "-asn1parse"
199 asn1parse the output data, this is useful when combined with the
200 \&\fB\-verify\fR option.
201 .SH "NOTES"
202 .IX Header "NOTES"
203 \&\fBrsautl\fR because it uses the \s-1RSA\s0 algorithm directly can only be
204 used to sign or verify small pieces of data.
205 .SH "EXAMPLES"
206 .IX Header "EXAMPLES"
207 Sign some data using a private key:
208 .PP
209 .Vb 1
210 \& openssl rsautl -sign -in file -inkey key.pem -out sig
211 .Ve
212 .PP
213 Recover the signed data
214 .PP
215 .Vb 1
216 \& openssl rsautl -verify -in sig -inkey key.pem
217 .Ve
218 .PP
219 Examine the raw signed data:
220 .PP
221 .Vb 1
222 \& openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
223 .Ve
224 .PP
225 .Vb 8
226 \& 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
227 \& 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
228 \& 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
229 \& 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
230 \& 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
231 \& 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
232 \& 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
233 \& 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world
234 .Ve
235 .PP
236 The PKCS#1 block formatting is evident from this. If this was done using
237 encrypt and decrypt the block would have been of type 2 (the second byte)
238 and random padding data visible instead of the 0xff bytes.
239 .PP
240 It is possible to analyse the signature of certificates using this
241 utility in conjunction with \fBasn1parse\fR. Consider the self signed
242 example in certs/pca\-cert.pem . Running \fBasn1parse\fR as follows yields:
243 .PP
244 .Vb 1
245 \& openssl asn1parse -in pca-cert.pem
246 .Ve
247 .PP
248 .Vb 18
249 \&    0:d=0  hl=4 l= 742 cons: SEQUENCE          
250 \&    4:d=1  hl=4 l= 591 cons:  SEQUENCE          
251 \&    8:d=2  hl=2 l=   3 cons:   cont [ 0 ]        
252 \&   10:d=3  hl=2 l=   1 prim:    INTEGER           :02
253 \&   13:d=2  hl=2 l=   1 prim:   INTEGER           :00
254 \&   16:d=2  hl=2 l=  13 cons:   SEQUENCE          
255 \&   18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption
256 \&   29:d=3  hl=2 l=   0 prim:    NULL              
257 \&   31:d=2  hl=2 l=  92 cons:   SEQUENCE          
258 \&   33:d=3  hl=2 l=  11 cons:    SET               
259 \&   35:d=4  hl=2 l=   9 cons:     SEQUENCE          
260 \&   37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName
261 \&   42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU
262 \&  ....
263 \&  599:d=1  hl=2 l=  13 cons:  SEQUENCE          
264 \&  601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption
265 \&  612:d=2  hl=2 l=   0 prim:   NULL              
266 \&  614:d=1  hl=3 l= 129 prim:  BIT STRING
267 .Ve
268 .PP
269 The final \s-1BIT\s0 \s-1STRING\s0 contains the actual signature. It can be extracted with:
270 .PP
271 .Vb 1
272 \& openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
273 .Ve
274 .PP
275 The certificate public key can be extracted with:
276 .PP
277 .Vb 1
278 \& openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
279 .Ve
280 .PP
281 The signature can be analysed with:
282 .PP
283 .Vb 1
284 \& openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
285 .Ve
286 .PP
287 .Vb 6
288 \&    0:d=0  hl=2 l=  32 cons: SEQUENCE          
289 \&    2:d=1  hl=2 l=  12 cons:  SEQUENCE          
290 \&    4:d=2  hl=2 l=   8 prim:   OBJECT            :md5
291 \&   14:d=2  hl=2 l=   0 prim:   NULL              
292 \&   16:d=1  hl=2 l=  16 prim:  OCTET STRING      
293 \&      0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..
294 .Ve
295 .PP
296 This is the parsed version of an \s-1ASN1\s0 DigestInfo structure. It can be seen that
297 the digest used was md5. The actual part of the certificate that was signed can
298 be extracted with:
299 .PP
300 .Vb 1
301 \& openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
302 .Ve
303 .PP
304 and its digest computed with:
305 .PP
306 .Vb 2
307 \& openssl md5 -c tbs
308 \& MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
309 .Ve
310 .PP
311 which it can be seen agrees with the recovered value above.
312 .SH "SEE ALSO"
313 .IX Header "SEE ALSO"
314 \&\fIdgst\fR\|(1), \fIrsa\fR\|(1), \fIgenrsa\fR\|(1)