doc/man1/openssl-rsautl.pod.in

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