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