doc/man1/openssl-rsautl.pod

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