---
product: Chilkat
product_version: 11.7.0
language: xbase
language_label: Xbase++
class: Dh
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/xbase_DhRef.html
---
# Chilkat Dh — Xbase++ — v11.7.0

> Chilkat 11.7.0 · language=xbase · class=Dh
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Dh.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/xbase/guide.md`.

## Purpose

**Perform Diffie-Hellman shared-secret key exchange.**

`Chilkat.Dh` provides the core operations needed for Diffie-Hellman shared-secret exchange. It allows two parties to agree on a shared secret over an insecure channel by using common Diffie-Hellman parameters, generating public exchange values, and computing the same shared secret from the other party's public value.

**Choose known parameters**

Use `UseKnownPrime` when the application wants to use a predefined Diffie-Hellman prime group.

**Generate parameters**

Use `GenPG` to generate Diffie-Hellman parameters when custom prime and generator values are required.

**Set custom P and G**

Use `SetPG` when the prime and generator are already known or have been received from another party or protocol.

**Create the exchange value**

Use `CreateE` to create the public Diffie-Hellman value that is sent to the other party.

**Compute the shared secret**

Use `FindK` with the other party's public exchange value to compute the shared secret.

**Use the result carefully**

The shared secret is typically used as input to a key derivation step before being used for encryption or authentication.

**Common pattern:** Select or generate the Diffie-Hellman parameters, create your public exchange value with `CreateE`, exchange public values with the other party, then call `FindK` to compute the shared secret. The primary methods are `UseKnownPrime`, `GenPG`, `SetPG`, `CreateE`, and `FindK`.

For an extended overview, see [Dh Class Overview](https://www.chilkatsoft.com/dh_class_overview.asp).

## Object creation, unlocking and error handling

**Object Creation**

```xbase
LOCAL oDh
oDh := CreateObject("Chilkat.Dh")

// ... use oDh ...

oDh:destroy()
```

Xbase++ uses the Chilkat ActiveX through the automation object returned by `CreateObject()`; properties and methods are accessed with the send operator (`oHttp:ConnectTimeout := 30`, `oHttp:Download(cUrl, cPath)`), and `:destroy()` releases the object. Register the Chilkat ActiveX matching the bitness of your Xbase++ application. To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as `CreateObject("Chilkat.Dh.11")` for Chilkat v11.\*.\*.

Boolean properties, arguments and return values are integers in the ActiveX: pass `1` or `0`, and test a method's success with `== 1`. A method that fails to return an object returns `NIL`. Objects returned by methods (such as an `HttpResponse` or `JsonObject`) are automation objects too and should likewise be released with `:destroy()`. Methods and properties that pass or return raw byte arrays are not shown on this page; use the `BinData`-based alternatives (methods ending in *Bd*) or the base64 / hex string-encoded variants instead.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Xbase++.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `oDh:DebugLogFilePath // Character` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `oDh:LastErrorHtml // Character (read-only)` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `oDh:LastErrorText // Character (read-only)` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `oDh:LastErrorXml // Character (read-only)` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `oDh:LastMethodSuccess // Numeric` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `oDh:LastStringResult // Character (read-only)` | read-only | In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. |
| `LastStringResultLen` | `oDh:LastStringResultLen // Numeric (read-only)` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `oDh:VerboseLogging // Numeric` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `oDh:Version // Character (read-only)` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `G` | property, read-only | `oDh:G // Numeric (read-only)` |
| `P` | property, read-only | `oDh:P // Character (read-only)` |
| `CreateE` | method | `cResult := oDh:CreateE(nNumBits) // returns Character` |
| `FindK` | method | `cResult := oDh:FindK(cE) // returns Character` |
| `GenPG` | method | `nSuccess := oDh:GenPG(nNumBits, nG) // returns Numeric (1/0)` |
| `SetPG` | method | `nSuccess := oDh:SetPG(cP, nG) // returns Numeric (1/0)` |
| `UseKnownPrime` | method | `oDh:UseKnownPrime(nIndex)` |

## Properties

### Dh.G

`Chilkat 11.7.0 · xbase · Dh · G · property · read-only`

```xbase
oDh:G  // Numeric (read-only)
```

Returns the current Diffie-Hellman generator, `g`. The generator is the small public integer used with the prime modulus `p` in the modular exponentiation operations that create the public exchange value and shared secret.

For this class, `g` is expected to be `2` or `5`. Its value is established by `UseKnownPrime`, `GenPG`, or `SetPG`.

**Public parameter:** The generator is not secret. Both parties must use exactly the same `p` and `g` values for the exchange.

### Dh.P

`Chilkat 11.7.0 · xbase · Dh · P · property · read-only`

```xbase
oDh:P  // Character (read-only)
```

Returns the current Diffie-Hellman prime modulus, `p`, as a hex-encoded SSH1-format bignum. The value is established by `UseKnownPrime`, `GenPG`, or `SetPG`.

The modulus is a *safe prime*: `p = 2q + 1`, where `q` is also prime. Safe-prime groups are commonly used for finite-field Diffie-Hellman because their subgroup structure is well understood.

**Encoding note:** The returned string is the hexadecimal encoding of an SSH1 bignum, which includes the SSH1 bit-length prefix. It is not simply the conventional hexadecimal representation of the integer `p`.

**Public parameter:** The prime modulus is not secret and may be transmitted to the other party. Both parties must use the same `p` and `g`.

## Methods

### Dh.CreateE

`Chilkat 11.7.0 · xbase · Dh · CreateE · method`

```xbase
cResult := oDh:CreateE(nNumBits)  // returns Character
```

Creates this party's public Diffie-Hellman exchange value, conventionally written as `E = gx mod p`. Before calling this method, initialize the common Diffie-Hellman parameters by calling `UseKnownPrime`, `GenPG`, or `SetPG`.

`numBits` (`numBits`) controls the size of the randomly generated private exponent retained internally by this `Dh` object. Chilkat recommends setting it to twice the desired strength of the symmetric key that will ultimately be derived. For example, use `256` when the protocol will derive a 128-bit key.

The returned `E` value is a hex-encoded SSH1-format bignum. It is public and is sent to the other party. The size of the eventual shared-secret integer is determined primarily by `p`; `numBits` does not make the returned shared secret a fixed-length symmetric key.

**Object state:** Call `FindK` on this same `Dh` object after receiving the other party's exchange value. `CreateE` stores the corresponding private value internally, and `FindK` needs it to compute the shared secret. Use a separate `Dh` object for each party and generate a fresh exchange value for each session.

**Authentication required:** Basic Diffie-Hellman does not authenticate either party and is vulnerable to a man-in-the-middle attack. The surrounding protocol must authenticate the exchanged parameters and public values.

For language bindings where a string return cannot directly communicate failure, check `LastMethodSuccess`. If it is `FALSE`, inspect `LastErrorText`.

Returns `NIL` on failure

### Dh.FindK

`Chilkat 11.7.0 · xbase · Dh · FindK · method`

```xbase
cResult := oDh:FindK(cE)  // returns Character
```

Computes the Diffie-Hellman shared secret from the other party's public exchange value. `E` is the peer's `E` value, encoded as the hexadecimal representation of an SSH1-format bignum.

This method must be called on the same `Dh` object that previously called `CreateE`. Both parties must also be using the same `p` and `g` parameters. Internally, the method computes `K = Ex mod p`, where `x` is the private value generated by `CreateE`.

The result is the shared-secret integer `K`, returned as a hex-encoded SSH1-format bignum. When the exchange is performed correctly, both parties compute the same value.

**Do not use the returned text directly as an encryption key:** It is an encoded bignum, not a uniformly formatted symmetric key. Feed the shared-secret value into the key-derivation procedure required by the protocol, together with any required transcript, salt, labels, or context. Do not invent an ad hoc conversion when interoperability or cryptographic security matters.

**Key agreement is not authentication:** Matching shared secrets do not by themselves prove the identity of the peer. Authenticate the exchange to prevent man-in-the-middle attacks.

For language bindings where a string return cannot directly communicate failure, check `LastMethodSuccess`. If it is `FALSE`, inspect `LastErrorText`.

Returns `NIL` on failure

### Dh.GenPG

`Chilkat 11.7.0 · xbase · Dh · GenPG · method`

```xbase
nSuccess := oDh:GenPG(nNumBits, nG)  // returns Numeric (1/0)
```

Generates new finite-field Diffie-Hellman parameters and stores them in this object. `numBits` specifies the size of the safe prime `p` in bits, and `G` specifies the generator `g`, which should be `2` or `5`.

On success, the generated values are available through the `P` and `G` properties. The prime generation and validation process is computationally expensive, especially for large groups.

**Prefer standardized groups:** Most applications should use `UseKnownPrime` or parameters mandated by the surrounding protocol instead of generating a new group. Standardized groups improve interoperability and avoid the cost and risk of custom parameter generation.

**Modern key sizes:** The legacy 768-, 1024-, and 1536-bit MODP groups are not appropriate for new designs. Use at least a 2048-bit standardized group when compatibility requires finite-field DH; a 3072-bit group is commonly selected when approximately 128-bit classical security is required.

Returns `TRUE` if the parameters were generated successfully; otherwise returns `FALSE`. Check `LastErrorText` for failure details.

Returns 1 for success, 0 for failure.

### Dh.SetPG

`Chilkat 11.7.0 · xbase · Dh · SetPG · method`

```xbase
nSuccess := oDh:SetPG(cP, nG)  // returns Numeric (1/0)
```

Sets explicit finite-field Diffie-Hellman parameters for this object. `p` is the prime modulus `p`, supplied as a hex-encoded SSH1-format bignum, and `g` is the generator `g`, normally `2` or `5`.

The method validates that the supplied values satisfy the requirements expected by this Diffie-Hellman implementation. It returns `TRUE` if the parameters are accepted; otherwise it returns `FALSE`.

**Encoding requirement:** `p` is not ordinary integer hex. It must contain the hexadecimal encoding of the SSH1 bignum representation, including its bit-length prefix. The `P` property of another Chilkat `Dh` object is already in the required form.

**Interoperability:** Both parties must use exactly the same `p` and `g`. These values are public, but untrusted or nonstandard parameters should not be accepted unless the protocol explicitly permits them and their origin is authenticated.

Returns 1 for success, 0 for failure.

### Dh.UseKnownPrime

`Chilkat 11.7.0 · xbase · Dh · UseKnownPrime · method`

```xbase
oDh:UseKnownPrime(nIndex)
```

Selects one of eight built-in safe-prime MODP groups and sets the object's `P` and `G` properties. `index` is a Chilkat selector from `1` through `8`; it is **not** the IKE group number.

| `index` | MODP group | Prime bits | Definition | G |
| :--- | :--- | :--- | :--- | :--- |
| `1` | Group 1 | 768 | RFC 2409, section 6.1 | `2` |
| `2` | Group 2 | 1024 | RFC 2409, section 6.2 | `2` |
| `3` | Group 5 | 1536 | RFC 3526, section 2 | `2` |
| `4` | Group 14 | 2048 | RFC 3526, section 3 | `2` |
| `5` | Group 15 | 3072 | RFC 3526, section 4 | `2` |
| `6` | Group 16 | 4096 | RFC 3526, section 5 | `2` |
| `7` | Group 17 | 6144 | RFC 3526, section 6 | `2` |
| `8` | Group 18 | 8192 | RFC 3526, section 7 | `2` |

**Security guidance:** Selectors `1`, `2`, and `3` are legacy groups and should not be chosen for new systems. Selector `4` is the 2048-bit group 14; selector `5` is the 3072-bit group 15 and is commonly used when approximately 128-bit classical security is required. Always use the group required by the protocol or the communicating peer.

**Performance:** Larger groups require more CPU time and produce larger public values. Choose a group based on the required security level and interoperability requirements, rather than automatically selecting the largest group.

