rsa: document deprecated RSA command line apps
[openssl.git] / doc / man1 / openssl-rsautl.pod.in
1 =pod
2 {- OpenSSL::safe::output_do_not_edit_headers(); -}
3
4 =head1 NAME
5
6 openssl-rsautl - RSA utility
7
8 =head1 SYNOPSIS
9
10 B<openssl> B<rsautl>
11 [B<-help>]
12 [B<-in> I<file>]
13 [B<-passin> I<arg>]
14 [B<-rev>]
15 [B<-out> I<file>]
16 [B<-inkey> I<file>]
17 [B<-keyform> B<DER>|B<PEM>|B<ENGINE>]
18 [B<-pubin>]
19 [B<-certin>]
20 [B<-sign>]
21 [B<-verify>]
22 [B<-encrypt>]
23 [B<-decrypt>]
24 [B<-pkcs>]
25 [B<-x931>]
26 [B<-oaep>]
27 [B<-ssl>]
28 [B<-raw>]
29 [B<-pkcs>]
30 [B<-ssl>]
31 [B<-raw>]
32 [B<-hexdump>]
33 [B<-asn1parse>]
34 {- $OpenSSL::safe::opt_engine_synopsis -}
35 {- $OpenSSL::safe::opt_r_synopsis -}
36
37 =for openssl ifdef engine
38
39 =head1 DESCRIPTION
40
41 This command has been deprecated.
42 The L<openssl-pkeyutl(1)> command should be used instead.
43
44 This command can be used to sign, verify, encrypt and decrypt
45 data using the RSA algorithm.
46
47 =head1 OPTIONS
48
49 =over 4
50
51 =item B<-help>
52
53 Print out a usage message.
54
55 =item B<-in> I<filename>
56
57 This specifies the input filename to read data from or standard input
58 if this option is not specified.
59
60 =item B<-passin> I<arg>
61
62 The passphrase used in the output file.
63 See see L<openssl(1)/Pass Phrase Options>.
64
65 =item B<-rev>
66
67 Reverse the order of the input.
68
69 =item B<-out> I<filename>
70
71 Specifies the output filename to write to or standard output by
72 default.
73
74 =item B<-inkey> I<file>
75
76 The input key file, by default it should be an RSA private key.
77
78 =item B<-keyform> B<DER>|B<PEM>|B<ENGINE>
79
80 The key format; the default is B<PEM>.
81 See L<openssl(1)/Format Options> for details.
82
83 =item B<-pubin>
84
85 The input file is an RSA public key.
86
87 =item B<-certin>
88
89 The input is a certificate containing an RSA public key.
90
91 =item B<-sign>
92
93 Sign the input data and output the signed result. This requires
94 an RSA private key.
95
96 =item B<-verify>
97
98 Verify the input data and output the recovered data.
99
100 =item B<-encrypt>
101
102 Encrypt the input data using an RSA public key.
103
104 =item B<-decrypt>
105
106 Decrypt the input data using an RSA private key.
107
108 =item B<-pkcs>, B<-oaep>, B<-x931> B<-ssl>, B<-raw>
109
110 The padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
111 ANSI X9.31,
112 special padding used in SSL v2 backwards compatible handshakes,
113 or no padding, respectively.
114 For signatures, only B<-pkcs> and B<-raw> can be used.
115
116 =item B<-hexdump>
117
118 Hex dump the output data.
119
120 =item B<-asn1parse>
121
122 Parse the ASN.1 output data, this is useful when combined with the
123 B<-verify> option.
124
125 {- $OpenSSL::safe::opt_engine_item -}
126
127 {- $OpenSSL::safe::opt_r_item -}
128
129 =back
130
131 =head1 NOTES
132
133 Since this command uses the RSA algorithm directly, it can only be
134 used to sign or verify small pieces of data.
135
136 =head1 EXAMPLES
137
138 Sign some data using a private key:
139
140  openssl rsautl -sign -in file -inkey key.pem -out sig
141
142 Recover the signed data
143
144  openssl rsautl -verify -in sig -inkey key.pem
145
146 Examine the raw signed data:
147
148  openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump
149
150  0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
151  0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
152  0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
153  0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
154  0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
155  0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
156  0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
157  0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world
158
159 The PKCS#1 block formatting is evident from this. If this was done using
160 encrypt and decrypt the block would have been of type 2 (the second byte)
161 and random padding data visible instead of the 0xff bytes.
162
163 It is possible to analyse the signature of certificates using this
164 utility in conjunction with L<openssl-asn1parse(1)>. Consider the self signed
165 example in F<certs/pca-cert.pem>. Running L<openssl-asn1parse(1)> as follows
166 yields:
167
168  openssl asn1parse -in pca-cert.pem
169
170     0:d=0  hl=4 l= 742 cons: SEQUENCE
171     4:d=1  hl=4 l= 591 cons:  SEQUENCE
172     8:d=2  hl=2 l=   3 cons:   cont [ 0 ]
173    10:d=3  hl=2 l=   1 prim:    INTEGER           :02
174    13:d=2  hl=2 l=   1 prim:   INTEGER           :00
175    16:d=2  hl=2 l=  13 cons:   SEQUENCE
176    18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption
177    29:d=3  hl=2 l=   0 prim:    NULL
178    31:d=2  hl=2 l=  92 cons:   SEQUENCE
179    33:d=3  hl=2 l=  11 cons:    SET
180    35:d=4  hl=2 l=   9 cons:     SEQUENCE
181    37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName
182    42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU
183   ....
184   599:d=1  hl=2 l=  13 cons:  SEQUENCE
185   601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption
186   612:d=2  hl=2 l=   0 prim:   NULL
187   614:d=1  hl=3 l= 129 prim:  BIT STRING
188
189
190 The final BIT STRING contains the actual signature. It can be extracted with:
191
192  openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
193
194 The certificate public key can be extracted with:
195
196  openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
197
198 The signature can be analysed with:
199
200  openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
201
202     0:d=0  hl=2 l=  32 cons: SEQUENCE
203     2:d=1  hl=2 l=  12 cons:  SEQUENCE
204     4:d=2  hl=2 l=   8 prim:   OBJECT            :md5
205    14:d=2  hl=2 l=   0 prim:   NULL
206    16:d=1  hl=2 l=  16 prim:  OCTET STRING
207       0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..
208
209 This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
210 the digest used was md5. The actual part of the certificate that was signed can
211 be extracted with:
212
213  openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
214
215 and its digest computed with:
216
217  openssl md5 -c tbs
218  MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
219
220 which it can be seen agrees with the recovered value above.
221
222 =head1 SEE ALSO
223
224 L<openssl(1)>,
225 L<openssl-pkeyutl(1)>,
226 L<openssl-dgst(1)>,
227 L<openssl-rsa(1)>,
228 L<openssl-genrsa(1)>
229
230 =head1 HISTORY
231
232 This command was deprecated in OpenSSL 3.0.
233
234 =head1 COPYRIGHT
235
236 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
237
238 Licensed under the Apache License 2.0 (the "License").  You may not use
239 this file except in compliance with the License.  You can obtain a copy
240 in the file LICENSE in the source distribution or at
241 L<https://www.openssl.org/source/license.html>.
242
243 =cut