Chilkat.EdDSA Class Overview

Chilkat.EdDSA provides Ed25519-based EdDSA operations for key generation, signing, signature verification, and shared-secret computation. It supports Ed25519, Ed25519ph, and Ed25519ctx, works with Chilkat PrivateKey, PublicKey, Prng, and BinData objects, and returns signatures or shared secrets in encoded string form.

What the Class Is Used For

Use Chilkat.EdDSA when an application needs to generate Ed25519 keys, sign binary data, verify Ed25519 signatures, or compute a shared secret from a private key and another party’s public key. The class is intentionally small and focused: configure the EdDSA variant, optionally set a context, provide the needed key object, and call the appropriate operation.

Generate Ed25519 Keys Use GenEd25519Key with a Prng and output PrivateKey object.
Sign Binary Data Use SignBdENC to sign BinData and return the signature as hex, base64, or another supported encoding.
Verify Signatures Use VerifyBdENC with the original BinData, encoded signature, encoding name, and Ed25519 public key.
Compute Shared Secrets Use SharedSecretENC with a private key and public key to compute an identical shared secret on both sides.

Typical Key Generation Workflow

  1. Create a Prng object.
  2. Create an empty PrivateKey object to receive the generated key.
  3. Create a EdDSA object.
  4. Call GenEd25519Key, passing the Prng and output PrivateKey.
  5. Use the generated private key for signing or derive/export the corresponding public key using the appropriate Chilkat key APIs.
  6. Check LastErrorText after failures or unexpected behavior.

Typical Signing Workflow

  1. Load or create the data to be signed in a BinData object.
  2. Load or generate an Ed25519 private key in a PrivateKey object.
  3. Set Algorithm to Ed25519, Ed25519ph, or Ed25519ctx. The default is Ed25519.
  4. For Ed25519ctx or Ed25519ph, set Context when context bytes are required.
  5. Call SignBdENC, passing the data, output encoding, and private key.
  6. Store or transmit the returned encoded signature.

Typical Verification Workflow

  1. Load the original signed data into a BinData object.
  2. Load the signer’s Ed25519 public key into a PublicKey object.
  3. Set Algorithm and Context to match the signing operation.
  4. Call VerifyBdENC, passing the data, encoded signature, encoding name, and public key.
  5. Treat a true result as a valid signature and a false result as failed verification or an error.
  6. Check LastErrorText when verification fails unexpectedly.

Core Concepts

Concept Meaning Important Members
EdDSA Edwards-curve Digital Signature Algorithm support centered on Ed25519 operations. Algorithm, SignBdENC, VerifyBdENC
Ed25519 The default EdDSA algorithm. Prior to Chilkat v9.5.0.91, this was the only EdDSA instance supported by this class. Algorithm
Ed25519ph An Ed25519 variant supported through the Algorithm property. Context bytes may be used. Algorithm, Context
Ed25519ctx An Ed25519 variant that uses context bytes supplied in hex string form. Algorithm, Context
Encoded Signature Signatures are returned or supplied as encoded strings, such as hex or base64. SignBdENC, VerifyBdENC
Shared Secret A secret value computed from one party’s private key and the other party’s public key. Both parties compute the same result. SharedSecretENC

Properties

Property Purpose Values / Guidance
Algorithm Selects the EdDSA algorithm variant. Can be Ed25519, Ed25519ph, or Ed25519ctx. Default is Ed25519. Introduced in Chilkat v9.5.0.91.
Context Context bytes used for Ed25519ctx or Ed25519ph. Set as a hex string. Use the same context for signing and verifying.
LastErrorText 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.

Algorithm Variants

Algorithm Context Usage Typical Setup
Ed25519 No context value is required by this class for the default Ed25519 mode. Leave Algorithm at its default value, or set it explicitly to Ed25519.
Ed25519ph Uses context bytes when a context is required. Set Algorithm = "Ed25519ph" and set Context as a hex string when applicable.
Ed25519ctx Uses context bytes supplied through Context. Set Algorithm = "Ed25519ctx" and set the Context hex string.
Consistency rule: Verification must use the same algorithm variant and context settings that were used when the signature was created.

Key and Signature Methods

Method Purpose Inputs Output / Result
GenEd25519Key Generates an Ed25519 private key. Prng and output PrivateKey. The generated key is created in the supplied PrivateKey object.
SignBdENC Signs the contents of a BinData object. BinData, output encoding, and PrivateKey. Returns the signature as an encoded string, such as hex or base64.
VerifyBdENC Verifies an encoded signature against BinData. BinData, encoded signature, encoding name, and PublicKey. Returns true when the signature verifies; otherwise returns false.
SharedSecretENC Computes a shared secret from a private key and public key. PrivateKey, PublicKey, and output encoding. Returns the shared secret bytes as an encoded string.

Shared Secret Workflow

SharedSecretENC computes an encoded shared secret from a private key and another party’s public key. The reference describes the symmetric exchange pattern as follows:

Party Uses Computes
Alice Alice’s private key and Bob’s public key. SharedSecretENC(alicePrivateKey, bobPublicKey, encoding)
Bob Bob’s private key and Alice’s public key. SharedSecretENC(bobPrivateKey, alicePublicKey, encoding)
Expected result: Both calls produce the same shared secret, returned in the requested encoded form such as hex or base64.

Encoding Parameters

Where Encoding Is Used Method Meaning
Signature output SignBdENC The encoding argument controls how the signature bytes are returned, for example as hex or base64.
Signature input VerifyBdENC The encoding argument tells Chilkat how to decode the supplied encoded signature string.
Shared-secret output SharedSecretENC The encoding argument controls how the computed shared secret bytes are returned.
Context bytes Context Context bytes are supplied as a hex string for Ed25519ctx or Ed25519ph.
Spelling note: In the reference method signature for VerifyBdENC, the encoding parameter is spelled enocding. The parameter represents the signature encoding name.

Method Summary by Category

Category Methods / Properties Purpose
Algorithm configuration Algorithm, Context Select Ed25519, Ed25519ph, or Ed25519ctx, and provide context bytes when needed.
Key generation GenEd25519Key Generate an Ed25519 private key into a supplied PrivateKey object.
Signing SignBdENC Sign BinData and return the signature as an encoded string.
Verification VerifyBdENC Verify an encoded signature over BinData using a public key.
Shared secret SharedSecretENC Compute a shared secret from a private key and another party’s public key.
Diagnostics LastErrorText Read diagnostic information after failures or unexpected behavior.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Key generation fails GenEd25519Key, LastErrorText Confirm the Prng object is valid and the output PrivateKey object is supplied.
Signing fails SignBdENC, Algorithm, Context Confirm the data is loaded in BinData, the private key is an Ed25519 private key, and the algorithm/context settings are correct.
Verification fails VerifyBdENC, Algorithm, Context Confirm the original data, encoded signature, encoding name, public key, and algorithm/context settings match the signing operation.
Context-based signatures do not verify Context Use the same context hex string for signing and verification.
Encoded signature cannot be decoded SignBdENC, VerifyBdENC Use the same encoding name for verification that was used when the signature was produced, such as hex or base64.
Shared secrets do not match SharedSecretENC Confirm each party uses its own private key and the other party’s public key.
Need operation details after failure LastErrorText Check diagnostic text after a failed or unexpected method call.

Common Pitfalls

Pitfall Better Approach
Using a public key to sign. Use a PrivateKey with SignBdENC.
Using a private key to verify. Use a PublicKey with VerifyBdENC.
Changing Algorithm between signing and verification. Use the same algorithm variant for both operations.
Forgetting the context for Ed25519ctx or Ed25519ph. Set Context as a hex string consistently on both sides.
Verifying with the wrong signature encoding. Pass the correct encoding name to VerifyBdENC, matching the format of encodedSig.
Assuming the default algorithm includes a context. The default is Ed25519. Context is relevant for Ed25519ctx or Ed25519ph.
Expecting the shared secret to be raw bytes. SharedSecretENC returns the shared secret bytes as an encoded string according to the requested encoding.

Best Practices

Recommendation Reason
Leave Algorithm at Ed25519 unless a variant is required. Ed25519 is the default and simplest mode.
Use BinData for the exact bytes to sign or verify. Signing and verification operate over the contents of BinData.
Use explicit encodings such as hex or base64. Encoded signatures and shared secrets are easier to store, display, and transmit.
Keep signing and verification settings identical. The algorithm, context, data bytes, signature encoding, and key pair must all match for verification to succeed.
Use the shared-secret pattern exactly as intended. Each party uses its own private key and the other party’s public key to compute the same shared secret.
Check LastErrorText after failures. It provides the most useful diagnostic detail for key generation, signing, verification, shared-secret computation, key mismatch, and encoding problems.

Summary

Chilkat.EdDSA is the Chilkat class for Ed25519-based EdDSA operations. It can generate Ed25519 private keys, sign BinData, verify encoded signatures with public keys, and compute encoded shared secrets from private/public key pairs. The class supports Ed25519, Ed25519ph, and Ed25519ctx, with optional context bytes supplied as a hex string.

The most important practical guidance is to use the same algorithm and context for signing and verification, use the correct private or public key for each operation, keep the data bytes unchanged, and specify the correct encoding for signatures and shared secrets.