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