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