Package com.chilkatsoft.chilkat2

Class Ecc

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Ecc
All Implemented Interfaces:
AutoCloseable
public class Ecc extends ChilkatObject
<section class="ecc-summary">

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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Ecc

      public Ecc()
      Creates a new Ecc object.

  • Method Details

    • getAsnFormat

      public boolean getAsnFormat()
      Controls the binary layout of ECDSA signatures created by this object. The default is true.

      Value Signature layout

      true 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.

      false Raw 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.

      Returns:
      the value of the AsnFormat property

    • setAsnFormat

      public void setAsnFormat​(boolean value)
      Sets the AsnFormat property; see getAsnFormat().
      Parameters:
      value - the new value

    • genKey

      public void genKey​(String curveName, Prng prng, PrivateKey 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 true on success and false 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.

      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.

      Parameters:
      curveName - the curveName argument (not null)
      prng - the prng argument (not null)
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • genKey2

      public void genKey2​(String curveName, String encodedK, String encoding, PrivateKey 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 true on success and false 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. 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(String, Prng, PrivateKey) to create a new random private key.

      Parameters:
      curveName - the curveName argument (not null)
      encodedK - the encodedK argument (not null)
      encoding - the encoding argument (not null)
      privKey - the privKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sharedSecretENC

      public String sharedSecretENC​(PrivateKey privKey, PublicKey pubKey, String 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.

      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.

      Parameters:
      privKey - the privKey argument (not null)
      pubKey - the pubKey argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signBd

      public String signBd​(BinData bdData, String hashAlg, String encoding, PrivateKey privKey, Prng 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 getAsnFormat(). 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.

      Parameters:
      bdData - the bdData argument (not null)
      hashAlg - the hashAlg argument (not null)
      encoding - the encoding argument (not null)
      privKey - the privKey argument (not null)
      prng - the prng argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signBdUsingCert

      public String signBdUsingCert​(BinData bdData, String hashAlg, String encoding, Cert 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 getAsnFormat().

      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.

      Parameters:
      bdData - the bdData argument (not null)
      hashAlg - the hashAlg argument (not null)
      encoding - the encoding argument (not null)
      cert - the cert argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signHashENC

      public String signHashENC​(String encodedHash, String encoding, PrivateKey privkey, Prng 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 getAsnFormat(): 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.

      Parameters:
      encodedHash - the encodedHash argument (not null)
      encoding - the encoding argument (not null)
      privkey - the privkey argument (not null)
      prng - the prng argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • signHashUsingCert

      public String signHashUsingCert​(String encodedHash, String encoding, Cert 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 getAsnFormat().

      No hashing is performed: encodedHash must contain the final digest bytes expected by the receiving protocol. Use signBdUsingCert(BinData, String, String, Cert) 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.

      Parameters:
      encodedHash - the encodedHash argument (not null)
      encoding - the encoding argument (not null)
      cert - the cert argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyBd

      public int verifyBd​(BinData bdData, String hashAlg, String encodedSig, String encoding, PublicKey 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.

      Exact-data requirement: A valid signature becomes invalid if any signed byte changes or if a different hash algorithm is selected.

      Parameters:
      bdData - the bdData argument (not null)
      hashAlg - the hashAlg argument (not null)
      encodedSig - the encodedSig argument (not null)
      encoding - the encoding argument (not null)
      pubkey - the pubkey argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • verifyHashENC

      public int verifyHashENC​(String encodedHash, String encodedSig, String encoding, PublicKey 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 getAsnFormat() 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.

      Digest-level verification: This method does not hash the original message. It verifies only the digest bytes supplied in encodedHash.

      Parameters:
      encodedHash - the encodedHash argument (not null)
      encodedSig - the encodedSig argument (not null)
      encoding - the encoding argument (not null)
      pubkey - the pubkey argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)