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