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