Chilkat.Dh Class Overview

Chilkat.Dh implements the Diffie-Hellman key exchange steps needed to establish a shared secret. It manages the Diffie-Hellman parameters P and G, can use known safe-prime groups, can generate new safe primes, creates the local public exchange value E, and computes the shared secret K from the other party’s exchange value.

What the Class Is Used For

Use Chilkat.Dh when two parties need to independently compute the same shared secret over an insecure channel. Each party uses the same Diffie-Hellman parameters P and G, creates an exchange value with CreateE, exchanges that value with the other party, and then calls FindK to compute the shared secret.

Choose DH Parameters Use a known safe-prime group, generate a new safe prime, or set explicit P and G values.
Create Exchange Value Call CreateE to generate the local public Diffie-Hellman exchange value.
Compute Shared Secret Call FindK using the other party’s E value to derive the shared secret.
Use Standard MODP Groups Use built-in Oakley / MODP groups from RFC 2409 and RFC 3526 with UseKnownPrime.

Typical Diffie-Hellman Workflow

  1. Create a Dh object on each side of the exchange.
  2. Configure the same P and G values on both sides. The easiest approach is UseKnownPrime with the same group index.
  3. Each side calls CreateE to generate its public exchange value.
  4. Exchange the E values with the other party.
  5. Each side calls FindK, passing the other party’s E.
  6. Both sides obtain the same shared secret K, returned as an SSH1-format bignum encoded as a hex string.
  7. Check LastErrorText after failures or unexpected behavior.
Important: Both parties must use the same P and G values. If the parameters differ, the shared secret will not match.

Core Concepts

Concept Meaning Important Members
P A large safe prime used as the Diffie-Hellman modulus. Chilkat returns it as a hex string representing a bignum in SSH1 format. P, SetPG, GenPG, UseKnownPrime
G The generator used with P. The value should be either 2 or 5. G, SetPG, GenPG
E The public exchange value created by one party and sent to the other party. CreateE
K The shared secret computed from the local private DH state and the other party’s E value. FindK
Known Safe Prime A predefined safe-prime MODP group from the listed RFC groups. UseKnownPrime
SSH1-Format Bignum The representation used by this class for P, E, and K when returned or passed as hex strings. P, CreateE, FindK, SetPG

Properties

Property Type Purpose Guidance
P string The safe large prime, returned as a hex string. The hex string represents a bignum in SSH1 format. Set it indirectly with UseKnownPrime, GenPG, or SetPG.
G int The generator. Should be either 2 or 5.
LastErrorText string Diagnostic text for the last method or property access. Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Choosing P and G

Approach Method When to Use Notes
Use built-in known group UseKnownPrime Best when both parties can agree on a standard group index. Sets both P and G to a known safe prime group.
Generate new parameters GenPG Use when a new random safe prime is required. Generating a new P is expensive in both time and CPU cycles. The reference notes that a prime should be 1024 or more bits.
Set explicit parameters SetPG Use when P and G are provided by a protocol or another party. P must be passed as an SSH1-format bignum encoded as a hex string. The method returns true only if P and G conform to Diffie-Hellman requirements.

Known Safe Prime Groups

UseKnownPrime sets P and G to a predefined safe-prime group. The documented groups all use generator 2.

Index Group Size Source
1 First Oakley Default Group 768-bit RFC 2409, Section 6.1
2 Second Oakley Group / 1024-bit MODP Group 1024-bit RFC 2409
3 1536-bit MODP Group 1536-bit RFC 3526, Section 2
4 14th Oakley Group / 2048-bit MODP Group 2048-bit RFC 3526
5 3072-bit MODP Group 3072-bit RFC 3526, Section 4
6 4096-bit MODP Group 4096-bit RFC 3526, Section 5
7 6144-bit MODP Group 6144-bit RFC 3526, Section 6
8 8192-bit MODP Group 8192-bit RFC 3526, Section 7
Practical note: Using a known group avoids the cost of generating a new safe prime and makes it easier for both parties to agree on the same parameters.

Exchange Methods

Step Method Input Output
1 CreateE numBits, which should be twice the desired shared-secret size in bits. Returns E as an SSH-format bignum encoded as a hex string.
2 FindK The other party’s E value. Returns the shared secret K as an SSH1-format bignum encoded as a hex string.
numBits guidance: The numBits argument to CreateE should be twice the size of the shared secret to be generated. For example, to create a 128-bit AES session key, use numBits = 256.

Method Summary

Method Purpose Important Details
UseKnownPrime Sets P and G to a known safe-prime group. Accepts group indexes 1 through 8.
GenPG Generates a large safe prime and generator. G should be 2 or 5. Prime generation is time- and CPU-expensive.
SetPG Sets explicit P and G values. P is an SSH1-format bignum encoded as a hex string. Returns true only when the parameters conform to DH requirements.
CreateE Generates the local public exchange value. Called before exchanging values with the other party.
FindK Computes the shared secret from the other party’s exchange value. Called after receiving the other party’s E.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Parameter setup fails SetPG, GenPG, LastErrorText Confirm P is in SSH1 bignum hex format and G is valid, typically 2 or 5.
Shared secrets do not match P, G, CreateE, FindK Confirm both parties used identical P and G values and that each side passed the other party’s E to FindK.
Prime generation is slow GenPG Generating a new safe prime is expensive. Consider using UseKnownPrime when a standard group is acceptable.
Unexpected shared-secret size CreateE The numBits argument should be twice the desired shared-secret size in bits.
Need operation details after failure LastErrorText Check diagnostic text after a failed or unexpected method call.

Common Pitfalls

Pitfall Better Approach
Using different P or G values on each side. Agree on the same known group index or explicitly share and verify the same parameters before exchanging E values.
Passing your own E value to FindK. Pass the other party’s E value to FindK.
Generating a new safe prime every time without need. Use UseKnownPrime when a standard group is acceptable and both parties can agree on it.
Using an unsupported generator value. Use G = 2 or G = 5.
Assuming returned values are raw binary bytes. P, E, and K are represented as SSH-format bignums encoded as hex strings.
Using the wrong numBits value in CreateE. Set numBits to twice the desired shared-secret bit length.

Best Practices

Recommendation Reason
Use UseKnownPrime when possible. It avoids the time and CPU cost of generating a new safe prime and provides standard groups both parties can identify by index.
Confirm both parties use identical parameters. Diffie-Hellman succeeds only when both parties use the same P and G.
Use the documented exchange order. Call CreateE, exchange E values, then call FindK with the other party’s value.
Use SetPG only with valid SSH1-format bignum hex input. SetPG validates whether the supplied parameters conform to Diffie-Hellman requirements.
Check LastErrorText after failures. It provides the most useful diagnostic detail for parameter generation, parameter validation, exchange-value creation, and shared-secret computation.

Summary

Chilkat.Dh is the Chilkat class for performing Diffie-Hellman shared-secret exchange. It lets applications choose or generate Diffie-Hellman parameters, create public exchange values, and compute the shared secret from the other party’s exchange value. The key methods are UseKnownPrime, GenPG, SetPG, CreateE, and FindK.

The most important practical guidance is to use the same P and G on both sides, prefer known prime groups when suitable, exchange the E values correctly, and remember that the returned values are SSH-format bignums encoded as hex strings.