Chilkat.Ecc Class Overview

Chilkat.Ecc provides elliptic-curve cryptography operations for generating EC private keys, computing shared secrets, creating ECDSA signatures, and verifying ECDSA signatures. It works with Chilkat PrivateKey, PublicKey, Cert, Prng, and BinData objects, and supports common NIST, secp256k1, and Brainpool curves.

What the Class Is Used For

Use Chilkat.Ecc when an application needs elliptic-curve key generation, ECDSA signing, ECDSA signature verification, or shared-secret computation between two parties using compatible EC keys. The class is intentionally focused: it does not manage certificates or key files directly, but instead operates with Chilkat key, certificate, random-number, and binary-data objects supplied by the application.

Generate EC Keys Generate private keys on supported curves such as secp256r1, secp384r1, secp521r1, and secp256k1.
Create ECDSA Signatures Sign hashes or data using an EC private key, PRNG, and selected output encoding.
Verify ECDSA Signatures Verify encoded signatures using the original hash or data and an EC public key.
Compute Shared Secrets Compute the same shared secret from one party’s private key and the other party’s public key, as long as both keys are on the same curve.

Typical Workflow

  1. Choose a curve name, such as secp256r1, secp384r1, or secp256k1.
  2. Generate or load a PrivateKey and corresponding PublicKey. Use GenKey for random key generation or GenKey2 for a fixed private value used in repeatable tests.
  3. For signing, choose whether signatures should be ASN.1/DER encoded or raw r || s format by setting AsnFormat.
  4. Sign data with SignBd or a precomputed hash with SignHashENC. Use the certificate-based variants when the EC private key is held by a certificate.
  5. Verify signatures with VerifyBd or VerifyHashENC.
  6. For shared-secret workflows, call SharedSecretENC with one party’s private key and the other party’s public key.
  7. Check LastErrorText after any failure or unexpected result.

Core Concepts

Concept Meaning Important Members
Curve Name Identifies the elliptic curve and therefore the key size and mathematical domain parameters. GenKey, GenKey2
ECDSA Private Key The private key used to create ECDSA signatures or compute a shared secret. PrivateKey, SignHashENC, SharedSecretENC
ECDSA Public Key The public key used to verify signatures or compute the matching shared secret from the other party’s private key. PublicKey, VerifyHashENC, SharedSecretENC
ECDSA Signature A signature containing two values, r and s. Chilkat can return it as ASN.1/DER or as raw concatenated bytes. AsnFormat, SignHashENC, VerifyHashENC
PRNG A pseudo-random number generator used for EC key generation and ECDSA signature creation. Prng, GenKey, SignHashENC
Shared Secret A byte sequence independently computed by two parties from one private key and the other party’s public key. SharedSecretENC

Core Properties

Property Purpose Guidance
AsnFormat Controls how ECDSA signatures are encoded. Default is true, meaning signatures are ASN.1/DER encoded. Set to false to return the raw concatenation of r and s.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Supported Curves

GenKey and GenKey2 accept the following curve names.

Curve Family Curve Names Notes
NIST / SEC prime curves secp256r1, secp384r1, secp521r1, secp192r1, secp224r1 secp256r1 is also known as P-256 and prime256v1. The documentation also identifies secp384r1 as P-384 and secp521r1 as P-521.
secp256k1 secp256k1 The curve used for Bitcoin.
Brainpool curves brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1 Brainpool curves are available when the application or protocol requires them.

Key Generation

Method Purpose When to Use
GenKey Generates a new ECDSA private key for the specified curve using a Prng as the random source. Use for normal key generation where the private key should be randomly generated.
GenKey2 Generates an ECDSA private key using a specified private value K. Typically used for testing when the same private key is needed to reproduce identical results from run to run.
Testing note: GenKey2 accepts the private value K as encoded text, with an encoding such as hex, base64, or decimal. For production key generation, use GenKey with a proper Prng.

ECDSA Signature Format

An ECDSA signature consists of two equal-sized values: r and s. AsnFormat determines how those values are returned and verified.

AsnFormat Signature Encoding Use When
true ASN.1 / DER sequence containing both r and s. Default behavior and common interoperable format for many cryptographic APIs and file formats.
false Raw concatenation of the byte array for r followed by the byte array for s. Use when a protocol or external system expects raw r || s signatures.
Default compatibility: AsnFormat defaults to true, preserving the ASN.1 signature format used by earlier Chilkat versions.

Signing Data

ECDSA signs hashes. The data-signing methods hash the supplied data using the requested hash algorithm, then sign the resulting hash.

Input Method Key Source
Data in BinData SignBd Uses a PrivateKey and Prng.
Data in BinData SignBdUsingCert Uses the private key of a Cert, assuming the certificate’s private key is ECDSA.
Precomputed encoded hash SignHashENC Uses a PrivateKey and Prng.
Precomputed encoded hash SignHashUsingCert Uses the private key associated with a Cert.
Supported data hash algorithms: SignBd and SignBdUsingCert support sha256, sha384, and sha512.

Verifying Signatures

Input Method Return Value
Data in BinData VerifyBd Same return convention as hash verification: valid, invalid, or failure.
Precomputed encoded hash and encoded signature VerifyHashENC Returns 1 for a valid signature, 0 for an invalid signature, and -1 for any other failure.
Encoding requirement: For VerifyHashENC, both the hash and signature should be encoded using the encoding specified by the encoding argument, such as base64 or hex.

Shared Secret Computation

SharedSecretENC computes a shared secret using one party’s private key and the other party’s public key. Both sides can compute the same result by exchanging public keys.

Party Inputs Result
Alice Alice’s private key + Bob’s public key. Encoded shared-secret bytes.
Bob Bob’s private key + Alice’s public key. The same encoded shared-secret bytes.
Curve requirement: The private and public keys passed to SharedSecretENC must be on the same curve.

Encoding Choices

Where Encoding Is Used Argument Examples
Private value for deterministic test key generation encoding in GenKey2 hex, base64, decimal
Encoded shared secret output encoding in SharedSecretENC hex, base64, or another supported text encoding.
Encoded hashes and signatures encoding in SignHashENC and VerifyHashENC The hash and signature use the same encoding argument.
Encoded signature from data-signing methods encoding in SignBd and SignBdUsingCert Controls the encoded signature string returned by the method.

Certificate-Based Signing

Method Purpose Requirement
SignBdUsingCert Signs data from a BinData object using the private key of a certificate. The certificate must have an ECDSA private key available.
SignHashUsingCert Signs a precomputed encoded hash using the private key associated with a certificate. The certificate must have an ECDSA private key available.
Why use a certificate? Certificate-based signing is useful when the private key is associated with a certificate and may be managed outside the application, such as by the operating system, smart card, token, or keychain.

Method Summary

Category Methods Purpose
Key generation GenKey, GenKey2 Generate EC private keys on supported curves.
Shared secret SharedSecretENC Compute an encoded shared secret from a private key and public key on the same curve.
Sign data SignBd, SignBdUsingCert Hash and sign data contained in BinData.
Sign precomputed hash SignHashENC, SignHashUsingCert Sign an encoded hash and return an encoded signature.
Verify data signature VerifyBd Hash data in BinData and verify the encoded signature.
Verify precomputed hash signature VerifyHashENC Verify an encoded ECDSA signature against an encoded hash.

Diagnostics and Troubleshooting

Problem Area Member What to Check
General failure LastErrorText Check after failed key generation, shared-secret computation, signing, or verification.
Unsupported or misspelled curve GenKey, GenKey2 Confirm the curve name exactly matches one of the supported names.
Shared secret does not match SharedSecretENC Confirm both parties use keys from the same curve and exchange the correct public keys.
Signature format mismatch AsnFormat Confirm whether the other system expects ASN.1/DER signatures or raw r || s signatures.
Verification returns invalid VerifyHashENC, VerifyBd Confirm the public key, hash algorithm, signature encoding, and original data or hash are exactly the same values used when signing.
Certificate signing fails SignBdUsingCert, SignHashUsingCert Confirm the certificate has an available ECDSA private key.

Common Pitfalls

Pitfall Better Approach
Using keys from different curves for shared-secret computation. Ensure both the private key and public key passed to SharedSecretENC are on the same curve.
Verifying an ASN.1 signature as raw r || s, or the reverse. Set AsnFormat to match the signature format expected by the other system.
Using GenKey2 for production randomness. Use GenKey with a Prng for normal private-key generation. Reserve GenKey2 for repeatable tests.
Signing data with one hash algorithm and verifying with another. Keep the hash algorithm consistent, such as sha256, sha384, or sha512.
Assuming verification returns only true or false. VerifyHashENC returns 1 for valid, 0 for invalid, and -1 for another failure.
Using a certificate whose private key is not ECDSA. Use SignBdUsingCert or SignHashUsingCert only with a certificate that has an ECDSA private key.

Best Practices

Recommendation Reason
Use GenKey with a proper Prng for new keys. ECDSA private keys require secure randomness in normal production use.
Choose the curve required by the protocol or interoperability target. Both parties must use compatible curve parameters, especially for shared secret computation.
Keep AsnFormat at the default unless raw signatures are required. ASN.1/DER is the default and preserves earlier Chilkat behavior.
Use sha256 or stronger hashes for new data-signing workflows. The data-signing methods support SHA256, SHA384, and SHA512.
Use certificate-based signing when the private key is managed externally. SignBdUsingCert and SignHashUsingCert allow signing through a certificate’s ECDSA private key.
Use explicit encodings for hashes, signatures, private values, and shared secrets. Passing hex, base64, or another encoding explicitly avoids ambiguity.
Check LastErrorText after failures. It provides the most useful diagnostic detail for curve selection, key generation, signing, verification, certificate use, and shared-secret operations.

Summary

Chilkat.Ecc is the Chilkat class for direct elliptic-curve operations. It can generate EC private keys, sign hashes or data using ECDSA, verify ECDSA signatures, sign through ECDSA certificates, and compute encoded shared secrets from compatible EC key pairs. The key configuration point is AsnFormat, which controls whether signatures use ASN.1/DER encoding or raw r || s format.

For most signing workflows, use a secure Prng, choose a supported curve such as secp256r1 or the curve required by the protocol, sign with SHA256 or stronger, and keep AsnFormat at its default unless the other system explicitly requires raw signatures.