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