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