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; unspecified by default.
  77 See L<openssl-format-options(1)> for details.
  78
  79 =item B<-pubin>
  80
  81 The input file is an RSA public key.
  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 =item B<-hexdump>
 111
 112 Hex dump the output data.
 113
 114 =item B<-asn1parse>
 115
 116 Parse the ASN.1 output data, this is useful when combined with the
 117 B<-verify> option.
 118
 119 {- $OpenSSL::safe::opt_engine_item -}
 120
 121 {- $OpenSSL::safe::opt_r_item -}
 122
 123 {- $OpenSSL::safe::opt_provider_item -}
 124
 125 =back
 126
 127 =head1 NOTES
 128
 129 Since this command uses the RSA algorithm directly, it can only be
 130 used to sign or verify small pieces of data.
 131
 132 =head1 EXAMPLES
 133
 134 Examples equivalent to these can be found in the documentation for the
 135 non-deprecated L<openssl-pkeyutl(1)> command.
 136
 137 Sign some data using a private key:
 138
 139  openssl rsautl -sign -in file -inkey key.pem -out sig
 140
 141 Recover the signed data
 142
 143  openssl rsautl -verify -in sig -inkey key.pem
 144
 145 Examine the raw signed data:
 146
 147  openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump
 148
 149  0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 150  0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 151  0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 152  0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 153  0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 154  0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 155  0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 156  0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world
 157
 158 The PKCS#1 block formatting is evident from this. If this was done using
 159 encrypt and decrypt the block would have been of type 2 (the second byte)
 160 and random padding data visible instead of the 0xff bytes.
 161
 162 It is possible to analyse the signature of certificates using this
 163 command in conjunction with L<openssl-asn1parse(1)>. Consider the self signed
 164 example in F<certs/pca-cert.pem>. Running L<openssl-asn1parse(1)> as follows
 165 yields:
 166
 167  openssl asn1parse -in pca-cert.pem
 168
 169     0:d=0  hl=4 l= 742 cons: SEQUENCE
 170     4:d=1  hl=4 l= 591 cons:  SEQUENCE
 171     8:d=2  hl=2 l=   3 cons:   cont [ 0 ]
 172    10:d=3  hl=2 l=   1 prim:    INTEGER           :02
 173    13:d=2  hl=2 l=   1 prim:   INTEGER           :00
 174    16:d=2  hl=2 l=  13 cons:   SEQUENCE
 175    18:d=3  hl=2 l=   9 prim:    OBJECT            :md5WithRSAEncryption
 176    29:d=3  hl=2 l=   0 prim:    NULL
 177    31:d=2  hl=2 l=  92 cons:   SEQUENCE
 178    33:d=3  hl=2 l=  11 cons:    SET
 179    35:d=4  hl=2 l=   9 cons:     SEQUENCE
 180    37:d=5  hl=2 l=   3 prim:      OBJECT            :countryName
 181    42:d=5  hl=2 l=   2 prim:      PRINTABLESTRING   :AU
 182   ....
 183   599:d=1  hl=2 l=  13 cons:  SEQUENCE
 184   601:d=2  hl=2 l=   9 prim:   OBJECT            :md5WithRSAEncryption
 185   612:d=2  hl=2 l=   0 prim:   NULL
 186   614:d=1  hl=3 l= 129 prim:  BIT STRING
 187
 188
 189 The final BIT STRING contains the actual signature. It can be extracted with:
 190
 191  openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
 192
 193 The certificate public key can be extracted with:
 194
 195  openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
 196
 197 The signature can be analysed with:
 198
 199  openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
 200
 201     0:d=0  hl=2 l=  32 cons: SEQUENCE
 202     2:d=1  hl=2 l=  12 cons:  SEQUENCE
 203     4:d=2  hl=2 l=   8 prim:   OBJECT            :md5
 204    14:d=2  hl=2 l=   0 prim:   NULL
 205    16:d=1  hl=2 l=  16 prim:  OCTET STRING
 206       0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5   .F...Js.7...H%..
 207
 208 This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
 209 the digest used was md5. The actual part of the certificate that was signed can
 210 be extracted with:
 211
 212  openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
 213
 214 and its digest computed with:
 215
 216  openssl md5 -c tbs
 217  MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
 218
 219 which it can be seen agrees with the recovered value above.
 220
 221 =head1 SEE ALSO
 222
 223 L<openssl(1)>,
 224 L<openssl-pkeyutl(1)>,
 225 L<openssl-dgst(1)>,
 226 L<openssl-rsa(1)>,
 227 L<openssl-genrsa(1)>
 228
 229 =head1 HISTORY
 230
 231 This command was deprecated in OpenSSL 3.0.
 232
 233 The B<-engine> option was deprecated in OpenSSL 3.0.
 234
 235 =head1 COPYRIGHT
 236
 237 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
 238
 239 Licensed under the Apache License 2.0 (the "License").  You may not use
 240 this file except in compliance with the License.  You can obtain a copy
 241 in the file LICENSE in the source distribution or at
 242 L<https://www.openssl.org/source/license.html>.
 243
 244 =cut