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