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