SecurityTests/cspxutils/dhTest/README

   1                                           Diffie-Hellman 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 performing Diffie-HEllman key generation and key exchange
   8 using the CDSA API. One command-line executable program, called dhTest,
   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 DhTest is a UNIX command-line program which performs a the following
  21 sequence a specified number of times:
  22
  23    1. generate a D-H key pair, optionally using D-H parameters
  24           stored in a file. Call this key pair "myPublic" and
  25           "myPrivate".
  26    2. Optionally store the D-H parameters generated in step 1
  27           in a file.
  28    3. Generate another D-H key pair using the same D-H parameters
  29       as used (or generated) in step 1. Call this key pair
  30           "theirPublic" and "theirPrivate".
  31    4. Perform a D-H key exchange operations using myPrivate and
  32       theirPublic, resulting in symmetric key myDerive.
  33    5. Perform a D-H key exchange operations using myPublic and
  34       theirPrivate, resulting in symmetric key theirDerive.
  35    6. Ensure that the key bits in myDerive and theirDerive
  36       are identical.
  37
  38 Run the program with the single 'h' command line argument for
  39 usage information.
  40
  41 Two functions are of particular interest for the purposes of
  42 illustrating Diffie-Hellman operation. One, dhKeyGen(), performs
  43 D-H key pair generation, using optional existing D-H parameters
  44 and optionally returning D-H parameters if they were generated
  45 by this function (i.e., if they were not supplied to the function
  46 as input). D-H parameters are expressed at the CDSA API as an
  47 opaque blob in the form of a CSSM_DATA. The generation of D-H
  48 parameters is very time consuming - it takes about 90 seconds
  49 to calculate the parameters for 1024 bit D-H keys on an 800 MHz G4.
  50 Therefore any application which will be performing a number of key
  51 pair generations should establish a common set of D-H parameters
  52 to be shared between the two parties. Public disclosure of the
  53 D-H parameters does not compromise the security of D-H key exchange
  54 at all.
  55
  56 The second function of interest is dhKeyExchange(), which takes as
  57 its input one private key (e.g., "myPrivate") and one public key
  58 blob in the form of a CSSM_DATA. That public key blob is obtained
  59 from the peer when performing D-H key exchange. The result of
  60 this function is a CSSM_KEY, derivedKey. This derived key is
  61 typically used to perform symmetric encryption. See the cryptTool
  62 example in this same package for illustration of symmetric
  63 encryption.