cc85cc4b21ad8851556ed92437583c784edae97c
[openssl.git] / doc / man1 / openssl-rsautl.pod
1 =pod
2
3 =head1 NAME
4
5 openssl-rsautl - RSA utility
6
7 =head1 SYNOPSIS
8
9 B<openssl> B<rsautl>
10 [B<-help>]
11 [B<-in> I<file>]
12 [B<-out> I<file>]
13 [B<-inkey> I<file>]
14 [B<-keyform> B<DER>|B<PEM>|B<ENGINE>]
15 [B<-pubin>]
16 [B<-certin>]
17 [B<-sign>]
18 [B<-verify>]
19 [B<-encrypt>]
20 [B<-decrypt>]
21 [B<-rand> I<files>]
22 [B<-writerand> I<file>]
23 [B<-pkcs>]
24 [B<-ssl>]
25 [B<-raw>]
26 [B<-hexdump>]
27 [B<-asn1parse>]
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<-rand> I<files>, B<-writerand> I<file>
89
90 See L<openssl(1)/Random State Options> for more information.
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 =back
109
110 =head1 NOTES
111
112 Since this command uses the RSA algorithm directly, it can only be
113 used to sign or verify small pieces of data.
114
115 =head1 EXAMPLES
116
117 Sign some data using a private key:
118
119  openssl rsautl -sign -in file -inkey key.pem -out sig
120
121 Recover the signed data
122
123  openssl rsautl -verify -in sig -inkey key.pem
124
125 Examine the raw signed data:
126
127  openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump
128
129  0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
130  0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
131  0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
132  0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
133  0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
134  0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
135  0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
136  0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world
137
138 The PKCS#1 block formatting is evident from this. If this was done using
139 encrypt and decrypt the block would have been of type 2 (the second byte)
140 and random padding data visible instead of the 0xff bytes.
141
142 It is possible to analyse the signature of certificates using this
143 utility in conjunction with L<openssl-asn1parse(1)>. Consider the self signed
144 example in F<certs/pca-cert.pem>. Running L<openssl-asn1parse(1)> as follows
145 yields:
146
147  openssl asn1parse -in pca-cert.pem
148
149     0:d=0  hl=4 l= 742 cons: SEQUENCE
150     4:d=1  hl=4 l= 591 cons:  SEQUENCE
151     8:d=2  hl=2 l=   3 cons:   cont [ 0 ]
152    10:d=3  hl=2 l=   1 prim:    INTEGER           :02
153    13:d=2  hl=2 l=   1 prim:   INTEGER           :00
154    16:d=2  hl=2 l=  13 cons:   SEQUENCE
155    18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption
156    29:d=3  hl=2 l=   0 prim:    NULL
157    31:d=2  hl=2 l=  92 cons:   SEQUENCE
158    33:d=3  hl=2 l=  11 cons:    SET
159    35:d=4  hl=2 l=   9 cons:     SEQUENCE
160    37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName
161    42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU
162   ....
163   599:d=1  hl=2 l=  13 cons:  SEQUENCE
164   601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption
165   612:d=2  hl=2 l=   0 prim:   NULL
166   614:d=1  hl=3 l= 129 prim:  BIT STRING
167
168
169 The final BIT STRING contains the actual signature. It can be extracted with:
170
171  openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
172
173 The certificate public key can be extracted with:
174
175  openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
176
177 The signature can be analysed with:
178
179  openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
180
181     0:d=0  hl=2 l=  32 cons: SEQUENCE
182     2:d=1  hl=2 l=  12 cons:  SEQUENCE
183     4:d=2  hl=2 l=   8 prim:   OBJECT            :md5
184    14:d=2  hl=2 l=   0 prim:   NULL
185    16:d=1  hl=2 l=  16 prim:  OCTET STRING
186       0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..
187
188 This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
189 the digest used was md5. The actual part of the certificate that was signed can
190 be extracted with:
191
192  openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
193
194 and its digest computed with:
195
196  openssl md5 -c tbs
197  MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
198
199 which it can be seen agrees with the recovered value above.
200
201 =head1 SEE ALSO
202
203 L<openssl(1)>,
204 L<openssl-dgst(1)>,
205 L<openssl-rsa(1)>,
206 L<openssl-genrsa(1)>
207
208 =head1 COPYRIGHT
209
210 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
211
212 Licensed under the Apache License 2.0 (the "License").  You may not use
213 this file except in compliance with the License.  You can obtain a copy
214 in the file LICENSE in the source distribution or at
215 L<https://www.openssl.org/source/license.html>.
216
217 =cut