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