Ecc Chilkat2 Perl Reference Documentation
Chilkat2::Ecc
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.Ecc
Create elliptic-curve private keys for supported curves and use the
resulting key with Chilkat signing, verification, or key-agreement APIs.
Sign hashes or input data using an EC private key, producing ECDSA
signatures in the configured output format.
Verify ECDSA signatures using the matching EC public key and the original
hash or data.
Sign with an ECDSA certificate when the certificate has access to its
associated private key.
Compute an encoded shared secret from compatible EC private and public
keys for key-agreement workflows.
Use
For an extended overview, see
Ecc Class Overview.
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
ECDSA signing
ECDSA verification
Certificate-based signing
Shared-secret calculation
Signature format control
AsnFormat to control whether ECDSA signatures are
encoded as ASN.1/DER or as raw r || s values.
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.
Object Creation
use Chilkat2;
my $ecc = Chilkat2::Ecc->new;
# or set properties (and RaiseError) at creation:
# my $ecc = Chilkat2::Ecc->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/Ecc.pm file holds only this class's documentation (perldoc Chilkat2::Ecc).
Perl frees the object when its last reference goes (undef $ecc, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::Ecc';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::Ecc'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
AsnFormat
my $boolVal = $ecc->AsnFormat;
$ecc->AsnFormat($boolVal);
Controls the binary layout of ECDSA signatures created by this object. The default is 1.
| Value | Signature layout |
|---|---|
1 | ASN.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. |
0 | Raw format: fixed-width, unsigned big-endian r followed immediately by fixed-width s, commonly written r || s. |
r || s signatures.DebugLogFilePath
my $strVal = $ecc->DebugLogFilePath;
$ecc->DebugLogFilePath($strVal);
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.
LastErrorHtml
my $strVal = $ecc->LastErrorHtml;
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.
topLastErrorText
my $strVal = $ecc->LastErrorText;
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.
LastErrorXml
my $strVal = $ecc->LastErrorXml;
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.
topLastMethodSuccess
my $boolVal = $ecc->LastMethodSuccess;
$ecc->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 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.
VerboseLogging
my $boolVal = $ecc->VerboseLogging;
$ecc->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
my $strVal = $ecc->Version;
Methods
GenKey
# $prng is a Chilkat2::Prng
# $privKey is a Chilkat2::PrivateKey
# $success is true or false
my $success = $ecc->GenKey($curveName, $prng, $privKey);
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 1 on success and 0 on failure.
Supported curve names are:
| Curve name | Notes |
|---|---|
secp256r1 | Also known as P-256 and prime256v1. |
secp384r1 | Also known as P-384. |
secp521r1 | Also known as P-521. |
secp256k1 | Widely associated with Bitcoin and related systems. |
secp192r1, secp224r1 | Older, smaller SEC curves retained for compatibility. |
brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1 | Brainpool prime-field curves. |
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.$prng. Use a properly initialized cryptographic Prng.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKey2
# $encodedK is a string
# $encoding is a string
# $privKey is a Chilkat2::PrivateKey
# $success is true or false
my $success = $ecc->GenKey2($curveName, $encodedK, $encoding, $privKey);
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 1 on success and 0 on failure.
Supported curve names are:
| Curve name | Notes |
|---|---|
secp256r1 | Also known as P-256 and prime256v1. |
secp384r1 | Also known as P-384. |
secp521r1 | Also known as P-521. |
secp256k1 | Widely associated with Bitcoin and related systems. |
secp192r1, secp224r1 | Older, smaller SEC curves retained for compatibility. |
brainpoolP160r1, brainpoolP192r1, brainpoolP224r1, brainpoolP256r1, brainpoolP320r1, brainpoolP384r1, brainpoolP512r1 | Brainpool 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.GenKey to create a new random private key.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SharedSecretENC
# $pubKey is a Chilkat2::PublicKey
# $encoding is a string
# $str is a string or undef
my $str = $ecc->SharedSecretENC($privKey, $pubKey, $encoding);
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.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignBd
# $hashAlg is a string
# $encoding is a string
# $privKey is a Chilkat2::PrivateKey
# $prng is a Chilkat2::Prng
# $str is a string or undef
my $str = $ecc->SignBd($bdData, $hashAlg, $encoding, $privKey, $prng);
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.
$privKey.Prng. Reusing or predicting an ECDSA nonce can expose the private key.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignBdUsingCert
# $hashAlg is a string
# $encoding is a string
# $cert is a Chilkat2::Cert
# $str is a string or undef
my $str = $ecc->SignBdUsingCert($bdData, $hashAlg, $encoding, $cert);
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.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignHashENC
# $encoding is a string
# $privkey is a Chilkat2::PrivateKey
# $prng is a Chilkat2::Prng
# $str is a string or undef
my $str = $ecc->SignHashENC($encodedHash, $encoding, $privkey, $prng);
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 1, or raw r || s when 0.
$encodedHash must be the exact digest required by the protocol. The verifier must use the same digest bytes and the matching public key.Prng.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignHashUsingCert
# $encoding is a string
# $cert is a Chilkat2::Cert
# $str is a string or undef
my $str = $ecc->SignHashUsingCert($encodedHash, $encoding, $cert);
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.
$encodedHash must contain the final digest bytes expected by the receiving protocol. Use SignBdUsingCert when Chilkat should hash the source data before signing.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
VerifyBd
# $hashAlg is a string
# $encodedSig is a string
# $encoding is a string
# $pubkey is a Chilkat2::PublicKey
# $n is an integer
my $n = $ecc->VerifyBd($bdData, $hashAlg, $encodedSig, $encoding, $pubkey);
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.
| Return | Meaning |
|---|---|
1 | Valid signature. |
0 | Invalid signature. |
-1 | Operational failure; examine LastErrorText. |
VerifyHashENC
# $encodedSig is a string
# $encoding is a string
# $pubkey is a Chilkat2::PublicKey
# $n is an integer
my $n = $ecc->VerifyHashENC($encodedHash, $encodedSig, $encoding, $pubkey);
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.
| Return | Meaning |
|---|---|
1 | The signature is valid for the supplied digest and public key. |
0 | The method ran successfully, but the signature is not valid. |
-1 | The verification operation could not be completed because of malformed input, an unsuitable key, an unsupported encoding, or another error. Examine LastErrorText. |
$encodedHash.