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<file...>]
  22 [B<-writerand> I<file>]
  23 [B<-pkcs>]
  24 [B<-ssl>]
  25 [B<-raw>]
  26 [B<-hexdump>]
  27 [B<-asn1parse>]
  28
  29 =for comment ifdef engine
  30
  31 =head1 DESCRIPTION
  32
  33 The B<rsautl> 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<file...>
  88
  89 A file or files containing random data used to seed the random number
  90 generator.
  91 Multiple files can be specified separated by an OS-dependent character.
  92 The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
  93 all others.
  94
  95 =item B<-writerand> I<file>
  96
  97 Writes random data to the specified I<file> upon exit.
  98 This can be used with a subsequent B<-rand> flag.
  99
 100 =item B<-pkcs, -oaep, -ssl, -raw>
 101
 102 The padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
 103 special padding used in SSL v2 backwards compatible handshakes,
 104 or no padding, respectively.
 105 For signatures, only B<-pkcs> and B<-raw> can be used.
 106
 107 =item B<-hexdump>
 108
 109 Hex dump the output data.
 110
 111 =item B<-asn1parse>
 112
 113 Parse the ASN.1 output data, this is useful when combined with the
 114 B<-verify> option.
 115
 116 =back
 117
 118 =head1 NOTES
 119
 120 B<rsautl> because it uses the RSA algorithm directly can only be
 121 used to sign or verify small pieces of data.
 122
 123 =head1 EXAMPLES
 124
 125 Sign some data using a private key:
 126
 127  openssl rsautl -sign -in file -inkey key.pem -out sig
 128
 129 Recover the signed data
 130
 131  openssl rsautl -verify -in sig -inkey key.pem
 132
 133 Examine the raw signed data:
 134
 135  openssl rsautl -verify -in sig -inkey key.pem -raw -hexdump
 136
 137  0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 138  0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 139  0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 140  0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 141  0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 142  0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 143  0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff   ................
 144  0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64   .....hello world
 145
 146 The PKCS#1 block formatting is evident from this. If this was done using
 147 encrypt and decrypt the block would have been of type 2 (the second byte)
 148 and random padding data visible instead of the 0xff bytes.
 149
 150 It is possible to analyse the signature of certificates using this
 151 utility in conjunction with B<asn1parse>. Consider the self signed
 152 example in certs/pca-cert.pem . Running B<asn1parse> as follows 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