Ecc Node.js Reference Documentation

Ecc

Current Version: 11.5.0
Requires Chilkat Bundle License

Chilkat.Ecc

Generate EC keys, create ECDSA signatures, verify signatures, and compute shared secrets.

Chilkat.Ecc is the Chilkat class for direct elliptic-curve cryptographic 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. It is used when an application needs explicit control over elliptic-curve keys, signatures, signature encoding, or key-agreement output.

Generate EC private keys

Create elliptic-curve private keys for supported curves and use the resulting key with Chilkat signing, verification, or key-agreement APIs.

ECDSA signing

Sign hashes or input data using an EC private key, producing ECDSA signatures in the configured output format.

ECDSA verification

Verify ECDSA signatures using the matching EC public key and the original hash or data.

Certificate-based signing

Sign with an ECDSA certificate when the certificate has access to its associated private key.

Shared-secret calculation

Compute an encoded shared secret from compatible EC private and public keys for key-agreement workflows.

Signature format control

Use AsnFormat to control whether ECDSA signatures are encoded as ASN.1/DER or as raw r || s values.

Common pattern: Generate or load an EC key, choose the required signature format with AsnFormat, then sign or verify using the method that matches the input form: hash, data, key, or certificate. For shared-secret workflows, compute the ECDH-style secret and pass the result through the key derivation or encoding step required by the protocol.

For an extended overview, see Ecc Class Overview.

Object Creation

var obj = new chilkat.Ecc();

Properties

AsnFormat
AsnFormat
· boolean
Introduced in version 9.5.0.97

Controls the binary layout of ECDSA signatures created by this object. The default is true.

ValueSignature layout
trueASN.1 DER: a SEQUENCE containing the two INTEGER values r and s. Its encoded length can vary because DER INTEGER values may require leading sign-padding bytes.
falseRaw format: fixed-width, unsigned big-endian r followed immediately by fixed-width s, commonly written r || s.
Signing versus verification: This property controls generated signatures. Chilkat verification methods automatically recognize both ASN.1 DER and raw r || s signatures.
Protocol compatibility: Neither format is universally interchangeable. Use the layout required by the receiving protocol or file format.

More Information and Examples
Create ECSDA Signature using Raw r and s Format (not ASN.1)
top
DebugLogFilePath
DebugLogFilePath
· string

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

  • A timeout property set to 0, indicating an infinite timeout.
  • A hang occurring within an event callback in the application code.
  • An internal bug in the Chilkat code causing the hang.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
LastErrorHtml
LastErrorHtml
· string, read-only

Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastErrorText
LastErrorText
· string, read-only

Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
LastErrorXml
· string, read-only

Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.

top
LastMethodSuccess
LastMethodSuccess
· boolean

Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
VerboseLogging
VerboseLogging
· boolean

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
Version
· string, read-only

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

GenKey
var status = GenKey(curveName, prng, privKey);
· Returns Boolean (true for success, false for failure).
· curveName String
· prng Prng
· privKey PrivateKey
Introduced in version 11.0.0

Generates a new elliptic-curve private key and stores it in privKey. curveName selects the named curve, and prng supplies the cryptographically secure random data used to choose the private scalar. Returns true on success and false on failure.

Supported curve names are:

Curve nameNotes
secp256r1Also known as P-256 and prime256v1.
secp384r1Also known as P-384.
secp521r1Also known as P-521.
secp256k1Widely associated with Bitcoin and related systems.
secp192r1, secp224r1Older, smaller SEC curves retained for compatibility.
brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1Brainpool prime-field curves.
Choose the curve required by the protocol: The curve name determines the key size, signature size, and interoperability. P-256, P-384, and P-521 are broadly standardized; secp256k1 is commonly required by Bitcoin-related systems. Older and smaller curves should generally be used only for compatibility with an existing format or peer.
Random generation matters: The security of the private key depends on the randomness supplied by prng. Use a properly initialized cryptographic Prng.

Returns true for success, false for failure.

top
GenKey2
var status = GenKey2(curveName, encodedK, encoding, privKey);
· Returns Boolean (true for success, false for failure).
· curveName String
· encodedK String
· encoding String
· privKey PrivateKey
Introduced in version 11.0.0

Constructs an elliptic-curve private key in privKey from a caller-supplied private scalar. curveName selects the named curve, encodedK contains the scalar, and encoding names its representation, such as hex, base64, or decimal. Returns true on success and false on failure.

Supported curve names are:

Curve nameNotes
secp256r1Also known as P-256 and prime256v1.
secp384r1Also known as P-384.
secp521r1Also known as P-521.
secp256k1Widely associated with Bitcoin and related systems.
secp192r1, secp224r1Older, smaller SEC curves retained for compatibility.
brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1Brainpool prime-field curves.
encodedK is the private key value: Despite the historical argument name, encodedK is the long-lived private scalar used to construct the key. It is not the temporary ECDSA signing nonce also commonly denoted by k. The value must be valid for the selected curve, unpredictable when used as a real key, and kept secret.
Typical use: Use this method to reproduce a known key for a test vector or to import a scalar supplied by another system. Use GenKey to create a new random private key.

Returns true for success, false for failure.

top
SharedSecretENC
var retStr = SharedSecretENC(privKey, pubKey, encoding);
· Returns a String.
· privKey PrivateKey
· pubKey PublicKey
· encoding String
Introduced in version 9.5.0.52

Computes an elliptic-curve Diffie-Hellman shared secret from the private key in privKey and the peer's public key in pubKey. encoding specifies how the resulting bytes are encoded in the returned string, such as hex or base64.

Two parties obtain the same result when each combines its own private key with the other party's corresponding public key. Both keys must use the same named curve and must be suitable EC keys.

Do not use the raw result directly as a long-term encryption key: A shared secret is normally passed through the key-derivation function required by the surrounding protocol, together with any required context, salt, or transcript information. Key agreement by itself also does not authenticate the peer; an unauthenticated exchange is vulnerable to a man-in-the-middle attack.
ECDH, not ECDSA: ECDSA is a signature algorithm. This method performs ECDH-style key agreement.

Returns null on failure

More Information and Examples
List of Supported Encodings (Base64, Hex, etc.)How to Generate an Elliptic Curve Shared Secret
top
SignBd
var retStr = SignBd(bdData, hashAlg, encoding, privKey, prng);
· Returns a String.
· bdData BinData
· hashAlg String
· encoding String
· privKey PrivateKey
· prng Prng
Introduced in version 9.5.0.85

Hashes the bytes currently contained in bdData and creates an ECDSA signature with the EC private key in privKey. hashAlg selects the hash algorithm and may be sha256, sha384, or sha512. encoding selects the textual encoding of the returned signature, such as hex or base64. prng supplies the random source used during ECDSA signature generation.

The signature's binary layout is controlled by AsnFormat. The contents of the BinData object are read but not modified.

Sign the exact bytes: Verification succeeds only when the verifier hashes the same byte sequence with the same hash algorithm and uses the public key corresponding to privKey.
Protect the signing nonce: Use a cryptographically secure Prng. Reusing or predicting an ECDSA nonce can expose the private key.

Returns null on failure

More Information and Examples
ECDSA Sign and Verify Data using Different Hash Algorithms
top
SignBdUsingCert
var retStr = SignBdUsingCert(bdData, hashAlg, encoding, cert);
· Returns a String.
· bdData BinData
· hashAlg String
· encoding String
· cert Cert
Introduced in version 9.5.0.91

Hashes the bytes in bdData and creates an ECDSA signature using the private key associated with the certificate in cert. hashAlg selects sha256, sha384, or sha512; encoding selects the textual encoding of the returned signature.

The certificate must contain an EC public key and must provide access to its corresponding private key. The private key may be embedded with the certificate or supplied through the platform or key-storage mechanism from which the certificate was loaded. Signature layout is controlled by AsnFormat.

Certificate versus key: The certificate identifies the public key and may describe the key owner, but signing requires actual access to the associated private key. A public-only certificate cannot sign.

Returns null on failure

top
SignHashENC
var retStr = SignHashENC(encodedHash, encoding, privkey, prng);
· Returns a String.
· encodedHash String
· encoding String
· privkey PrivateKey
· prng Prng
Introduced in version 9.5.0.52

Creates an ECDSA signature over a digest that has already been computed by the application. encodedHash contains the digest encoded using the binary encoding named by encoding, such as hex or base64. privkey supplies the EC private key, and prng supplies the random source used during signature generation.

The returned signature uses the same textual encoding named by encoding. Its binary layout is controlled by AsnFormat: ASN.1 DER when true, or raw r || s when false.

No hashing is performed: encodedHash must be the exact digest required by the protocol. The verifier must use the same digest bytes and the matching public key.
ECDSA nonce safety: Every signature requires a secret per-signature value. It must be generated securely and must never be reused with the same private key, because nonce reuse or predictability can reveal the private key. Supply a properly initialized cryptographic Prng.

Returns null on failure

More Information and Examples
List of Supported Encodings (Base64, Hex, etc.)ECDSA Sign Data and Verify Signature
top
SignHashUsingCert
var retStr = SignHashUsingCert(encodedHash, encoding, cert);
· Returns a String.
· encodedHash String
· encoding String
· cert Cert
Introduced in version 10.1.0

Creates an ECDSA signature over a digest that has already been computed. encodedHash contains the digest encoded using the binary encoding named by encoding. cert supplies a certificate whose public key is EC and whose associated private key is accessible for signing.

The returned signature uses the same textual encoding named by encoding. Its binary layout is controlled by AsnFormat.

No hashing is performed: encodedHash must contain the final digest bytes expected by the receiving protocol. Use SignBdUsingCert when Chilkat should hash the source data before signing.
Private-key requirement: A certificate containing only a public key is not sufficient. The associated EC private key must be present and usable.

Returns null on failure

top
VerifyBd
var retInt = VerifyBd(bdData, hashAlg, encodedSig, encoding, pubkey);
· Returns a Number.
· bdData BinData
· hashAlg String
· encodedSig String
· encoding String
· pubkey PublicKey
Introduced in version 9.5.0.85

Hashes the bytes in bdData using the algorithm named by hashAlg and verifies the ECDSA signature in encodedSig with the EC public key in pubkey. encoding identifies the textual encoding of the signature, such as hex or base64. Supported hash algorithms are sha256, sha384, and sha512.

Chilkat automatically recognizes ASN.1 DER and raw r || s signature layouts.

ReturnMeaning
1Valid signature.
0Invalid signature.
-1Operational failure; examine LastErrorText.
Exact-data requirement: A valid signature becomes invalid if any signed byte changes or if a different hash algorithm is selected.
More Information and Examples
ECDSA Sign and Verify Data using Different Hash Algorithms
top
VerifyHashENC
var retInt = VerifyHashENC(encodedHash, encodedSig, encoding, pubkey);
· Returns a Number.
· encodedHash String
· encodedSig String
· encoding String
· pubkey PublicKey
Introduced in version 9.5.0.52

Verifies an ECDSA signature over a digest that was computed by the application. encodedHash is the encoded digest, encodedSig is the encoded signature, encoding names the binary encoding used by both strings, and pubkey supplies the matching EC public key.

Chilkat automatically recognizes both supported ECDSA signature layouts: ASN.1 DER and fixed-width raw r || s. The AsnFormat property therefore does not need to match the signature being verified.

ReturnMeaning
1The signature is valid for the supplied digest and public key.
0The method ran successfully, but the signature is not valid.
-1The verification operation could not be completed because of malformed input, an unsuitable key, an unsupported encoding, or another error. Examine LastErrorText.
Digest-level verification: This method does not hash the original message. It verifies only the digest bytes supplied in encodedHash.
More Information and Examples
List of Supported Encodings (Base64, Hex, etc.)ECDSA Sign Data and Verify Signature
top

Deprecated

GenEccKey
var ret_privateKey = GenEccKey(curveName, prng);
· Returns a PrivateKey
· curveName String
· prng Prng
Introduced in version 9.5.0.52
This method is deprecated and replaced by GenKey

Deprecated. Use GenKey for new code.

Generates an elliptic-curve private key on the named curve specified by curveName. prng supplies the cryptographically secure random data used to choose the private scalar. On success, the returned PrivateKey contains the new EC key; a null or empty result indicates failure.

EC key terminology: The generated object is an EC private key. The same underlying key type may be used with ECDSA signatures or with compatible elliptic-curve key-agreement operations; “ECDSA key” is common shorthand but is not a distinct key encoding.

See GenKey for the supported curve names.

Returns null on failure

More Information and Examples
Generate an ECC KeyGenerate Brainpool EC Keys (BP256R1, BP384R1, BP512R1, ...)
top
GenEccKey2
var ret_privateKey = GenEccKey2(curveName, encodedK, encoding);
· Returns a PrivateKey
· curveName String
· encodedK String
· encoding String
Introduced in version 9.5.0.55
This method is deprecated and replaced by GenKey2

Deprecated. Use GenKey2 for new code.

Constructs an elliptic-curve private key on the curve named by curveName from the encoded private scalar in encodedK. encoding names the representation of encodedK, such as hex, base64, or decimal. On success, the returned PrivateKey contains the reconstructed key.

Historical argument name: Although encodedK is named encodedK, it supplies the key's private scalar. It is not the temporary per-signature ECDSA nonce commonly written as k. The scalar must be valid for the selected curve and must remain secret.

This method is primarily useful for test vectors or for reconstructing a key from known private-key material. See GenKey2 for the supported curve names.

Returns null on failure

More Information and Examples
Generate ECC Keys using Specified Values for K
top