SecurityTests/cspxutils/rsatool/README

   1                         RSA Sample Code Info
   2                                          last update 4/24/02 dmitch
   3
   4 Introduction
   5 ------------
   6 This directory contains a program which demonstrates how to
   7 write code associated with the RSA Public Key Cryptosystem using
   8 the CDSA API. One command-line executable program, called rsatool,
   9 currently resides here.
  10
  11 Building
  12 --------
  13
  14 See the README in the parent directory (CDSA_Examples) for
  15 information on building this program.
  16
  17 Running rsatool
  18 ---------------
  19
  20 Rsatool is a UNIX command-line program which operates on files.
  21 It can generate key pairs (storing them in files), encrypt a file
  22 (placing the result in another file), decrypt, sign a file (placing
  23 the signature in another file), and verify signatures.
  24
  25 Please note that this type of operation, in which private keys
  26 are stored in files which anyone can read, is certainly not
  27 recommended security procedure; the purpose of this tool is to
  28 demonstrate the use of the CDSA API.
  29
  30 To get a full list of rsatool's command-line options, just run it
  31 with no arguments:
  32
  33 localhost> rsatool
  34 usage: ./rsatool op [options]
  35   op:
  36      g  generate key pair
  37      e  encrypt
  38      d  decrypt
  39      s  sign
  40      v  verify
  41      S  SHA-1 digest
  42      M  MD5 digest
  43   options:
  44      k=keyfileBase keys are keyFileBase_pub.der, keyFileBase_priv.der)
  45      p=plainFile
  46      c=cipherFile
  47      s=sigfile
  48      b=keySizeInBits (default 512)
  49      w (swap key class)
  50      r (raw sign/verify)
  51      P (no padding)
  52      a=alg   d=DSA r=RSA, e=ECDSA, default = RSA
  53 localhost>
  54
  55
  56 Some examples:
  57 --------------
  58
  59 To perform any operations using RSA, one must first have a key pair.
  60 You generate them like so:
  61
  62 localhost> rsatool g k=mykey b=1024
  63 ...wrote 140 bytes to mykey_pub.der
  64 ...wrote 636 bytes to mykey_priv.der
  65 localhostl>
  66
  67 This generates a 1024-bit key pair, places the public key
  68 in mykey_pub.der, and the private key in mykey_priv.der.
  69
  70 Now, say you want to encrypt a file. You encrypt with a public key.
  71 So first we create a file to encrypt:
  72
  73 localhost:> cat > plaintext
  74 this is what we will encrypt
  75 localhostl>
  76
  77 Now we encrypt it, placing the result in ciphertext:
  78
  79 localhost> rsatool e k=mykey p=plaintext c=ciphertext
  80 ...wrote 128 bytes to ciphertext
  81 localhost>
  82
  83 The result looks like this:
  84
  85 localhost> hexdump ciphertext
  86 0000000 8272 4ff9 d7ab 8ff0 3dee 543d 3f36 3d89
  87 0000010 ef80 f958 3b4f 1be1 bde8 6557 c215 9728
  88 0000020 4262 0c6a b81b 5782 444d 225c db3e 17d7
  89 0000030 7079 d3af 7e1e c215 2b14 bf35 20f7 ed33
  90 0000040 f311 6258 fd85 6679 e0bb ae33 4b26 c1f8
  91 0000050 4f33 ac24 1972 e048 915c 8386 5fc3 7f56
  92 0000060 e7b3 9b4a ad6b a192 84c3 fa6e 25ba 91a0
  93 0000070 05ef fe42 ebba 0290 99b1 5cc9 5e36 7954
  94 0000080
  95 localhost>
  96
  97 We decrypt it like so:
  98
  99 localhost> rsatool d k=mykey p=recovered  c=ciphertext
 100 ...wrote 29 bytes to recovered
 101 localhost>
 102
 103 Yielding:
 104
 105 localhost> cat recovered
 106 this is what we will encrypt
 107 localhost>
 108
 109 To generate a digital signature, putting the signature in sigfile:
 110
 111 localhost> rsatool s k=mykey p=plaintext s=sigfile
 112 ...wrote 128 bytes to sigfile
 113 localhost>
 114
 115 To verify the signature:
 116
 117 localhost> rsatool v k=mykey p=plaintext s=sigfile
 118 ...signature verifies OK
 119 localhost>
 120
 121 Note what happens if we specify a file other than 'plaintext' to
 122 verify with plaintext's signature:
 123
 124 localhost> rsatool v k=mykey p=ciphertext s=sigfile
 125 CSSM_VerifyData: CSP_VERIFY_FAILED
 126 sigVerify: CSP_VERIFY_FAILED
 127 localhost>