Merge from 1.0.0-stable branch.
[openssl.git] / doc / apps / rsautl.pod
1 =pod
2
3 =head1 NAME
4
5 rsautl - RSA utility
6
7 =head1 SYNOPSIS
8
9 B<openssl> B<rsautl>
10 [B<-in file>]
11 [B<-out file>]
12 [B<-inkey file>]
13 [B<-pubin>]
14 [B<-certin>]
15 [B<-sign>]
16 [B<-verify>]
17 [B<-encrypt>]
18 [B<-decrypt>]
19 [B<-pkcs>]
20 [B<-ssl>]
21 [B<-raw>]
22 [B<-hexdump>]
23 [B<-asn1parse>]
24
25 =head1 DESCRIPTION
26
27 The B<rsautl> command can be used to sign, verify, encrypt and decrypt
28 data using the RSA algorithm.
29
30 =head1 COMMAND OPTIONS
31
32 =over 4
33
34 =item B<-in filename>
35
36 This specifies the input filename to read data from or standard input
37 if this option is not specified.
38
39 =item B<-out filename>
40
41 specifies the output filename to write to or standard output by
42 default.
43
44 =item B<-inkey file>
45
46 the input key file, by default it should be an RSA private key.
47
48 =item B<-pubin>
49
50 the input file is an RSA public key. 
51
52 =item B<-certin>
53
54 the input is a certificate containing an RSA public key. 
55
56 =item B<-sign>
57
58 sign the input data and output the signed result. This requires
59 and RSA private key.
60
61 =item B<-verify>
62
63 verify the input data and output the recovered data.
64
65 =item B<-encrypt>
66
67 encrypt the input data using an RSA public key.
68
69 =item B<-decrypt>
70
71 decrypt the input data using an RSA private key.
72
73 =item B<-pkcs, -oaep, -ssl, -raw>
74
75 the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
76 special padding used in SSL v2 backwards compatible handshakes,
77 or no padding, respectively.
78 For signatures, only B<-pkcs> and B<-raw> can be used.
79
80 =item B<-hexdump>
81
82 hex dump the output data.
83
84 =item B<-asn1parse>
85
86 asn1parse the output data, this is useful when combined with the
87 B<-verify> option.
88
89 =back
90
91 =head1 NOTES
92
93 B<rsautl> because it uses the RSA algorithm directly can only be
94 used to sign or verify small pieces of data.
95
96 =head1 EXAMPLES
97
98 Sign some data using a private key:
99
100  openssl rsautl -sign -in file -inkey key.pem -out sig
101
102 Recover the signed data
103
104  openssl rsautl -verify -in sig -inkey key.pem
105
106 Examine the raw signed data:
107
108  openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
109
110  0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
111  0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
112  0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
113  0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
114  0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
115  0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
116  0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
117  0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world
118
119 The PKCS#1 block formatting is evident from this. If this was done using
120 encrypt and decrypt the block would have been of type 2 (the second byte)
121 and random padding data visible instead of the 0xff bytes.
122
123 It is possible to analyse the signature of certificates using this
124 utility in conjunction with B<asn1parse>. Consider the self signed
125 example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
126
127  openssl asn1parse -in pca-cert.pem
128
129     0:d=0  hl=4 l= 742 cons: SEQUENCE          
130     4:d=1  hl=4 l= 591 cons:  SEQUENCE          
131     8:d=2  hl=2 l=   3 cons:   cont [ 0 ]        
132    10:d=3  hl=2 l=   1 prim:    INTEGER           :02
133    13:d=2  hl=2 l=   1 prim:   INTEGER           :00
134    16:d=2  hl=2 l=  13 cons:   SEQUENCE          
135    18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption
136    29:d=3  hl=2 l=   0 prim:    NULL              
137    31:d=2  hl=2 l=  92 cons:   SEQUENCE          
138    33:d=3  hl=2 l=  11 cons:    SET               
139    35:d=4  hl=2 l=   9 cons:     SEQUENCE          
140    37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName
141    42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU
142   ....
143   599:d=1  hl=2 l=  13 cons:  SEQUENCE          
144   601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption
145   612:d=2  hl=2 l=   0 prim:   NULL              
146   614:d=1  hl=3 l= 129 prim:  BIT STRING        
147
148
149 The final BIT STRING contains the actual signature. It can be extracted with:
150
151  openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
152
153 The certificate public key can be extracted with:
154  
155  openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
156
157 The signature can be analysed with:
158
159  openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
160
161     0:d=0  hl=2 l=  32 cons: SEQUENCE          
162     2:d=1  hl=2 l=  12 cons:  SEQUENCE          
163     4:d=2  hl=2 l=   8 prim:   OBJECT            :md5
164    14:d=2  hl=2 l=   0 prim:   NULL              
165    16:d=1  hl=2 l=  16 prim:  OCTET STRING      
166       0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..
167
168 This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
169 the digest used was md5. The actual part of the certificate that was signed can
170 be extracted with:
171
172  openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
173
174 and its digest computed with:
175
176  openssl md5 -c tbs
177  MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
178
179 which it can be seen agrees with the recovered value above.
180
181 =head1 SEE ALSO
182
183 L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>