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