doc/man1/rsautl.pod

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