README
1 Diffie-Hellman Sample Code Info
2 last update 4/24/02 dmitch
3
4Introduction
5------------
6This directory contains a program which demonstrates how to
7write code performing Diffie-HEllman key generation and key exchange
8using the CDSA API. One command-line executable program, called dhTest,
9currently resides here.
10
11Building
12--------
13
14See the README in the parent directory (CDSA_Examples) for
15information on building this program.
16
17Running rsatool
18---------------
19
20DhTest is a UNIX command-line program which performs a the following
21sequence 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
38Run the program with the single 'h' command line argument for
39usage information.
40
41Two functions are of particular interest for the purposes of
42illustrating Diffie-Hellman operation. One, dhKeyGen(), performs
43D-H key pair generation, using optional existing D-H parameters
44and optionally returning D-H parameters if they were generated
45by this function (i.e., if they were not supplied to the function
46as input). D-H parameters are expressed at the CDSA API as an
47opaque blob in the form of a CSSM_DATA. The generation of D-H
48parameters is very time consuming - it takes about 90 seconds
49to calculate the parameters for 1024 bit D-H keys on an 800 MHz G4.
50Therefore any application which will be performing a number of key
51pair generations should establish a common set of D-H parameters
52to be shared between the two parties. Public disclosure of the
53D-H parameters does not compromise the security of D-H key exchange
54at all.
55
56The second function of interest is dhKeyExchange(), which takes as
57its input one private key (e.g., "myPrivate") and one public key
58blob in the form of a CSSM_DATA. That public key blob is obtained
59from the peer when performing D-H key exchange. The result of
60this function is a CSSM_KEY, derivedKey. This derived key is
61typically used to perform symmetric encryption. See the cryptTool
62example in this same package for illustration of symmetric
63encryption.
64