Module ECDH

Elliptic Curve Diffie-Hellman encryption (ECDH)

Asymmetric public/private key encryption technologies.

ECDH encryption and ECDSA signing functionalities are provided by this module. New keyring instances are instantiated by calling the new() method, keys can be imported using the

Alice = ECDH.new() Bob = ECDH.new()

One can create more keyrings in the same script and call them with meaningful variable names to help making code more understandable. Each keyring instance offers methods prefixed with a double-colon that operate on arguments as well keys contained by the keyring: this way scripting can focus on the identities represented by each keyring, giving them names as 'Alice' or 'Bob'.

Info:

  • Copyright: Dyne.org foundation 2017-2020
  • License: AGPLv3
  • Author: Denis "Jaromil" Roio

Class keyring

keyring:keygen () Generate an ECDH public/private key pair for a keyring
keyring:pubgen () Generate an ECDH public key from a secret key
keyring:xy () Returns X and Y coordinates of a public key
keyring:sign (message) Elliptic Curve Digital Signature Algorithm (ECDSA) signing function.
keyring:sign_deterministic (message, sha) Elliptic Curve Digital Signature Algorithm (ECDSA) signing function with deterministic generation of k (see RFC6979 https://www.rfc-editor.org/rfc/rfc6979).
keyring.sk Sign a message directly, without taking the hash (the input in an hashed message that is it is already hashed)
keyring:verify (message, signature) Elliptic Curve Digital Signature Algorithm (ECDSA) verification function.
keyring:verify_deterministic (message, signature, sha) Elliptic Curve Digital Signature Algorithm (ECDSA) verification function.
keyring:order () Order of the curve underlying the ECDH implementation
keyring:prime () Modulus of the curve underlying the ECDH implementation
keyring:cofactor () Cofactor of the curve underlying the ECDH implementation
keyring.x Elliptic Curve Digital Signature Algorithm (ECDSA) recovery function.


Class keyring

Instance Methods
keyring:keygen ()
Generate an ECDH public/private key pair for a keyring Keys generated are both returned and stored inside the keyring table as public and private properties. ()

Returns:

  1. OCTET public key
  2. OCTET private key
keyring:pubgen ()
Generate an ECDH public key from a secret key Public key is returned. ()

Returns:

    OCTET public key
keyring:xy ()
Returns X and Y coordinates of a public key (public_key)

Returns:

  1. OCTET coordinate X of public key
  2. OCTET coordinate Y of public key
keyring:sign (message)
Elliptic Curve Digital Signature Algorithm (ECDSA) signing function. This method uses the private key inside a keyring to sign a message, returning a signature to be used in keyring:verify. (kp.private, message)

Parameters:

  • message string or OCTET message to sign

Returns:

    table containing signature parameters octets (r,s)

Usage:

    kp = ECDH.keygen() -- generate keys or import them
m = "Message to be signed"
signature = ECDH.sign(kp.private, m)
assert( ECDH.verify(kp.public, m, signature) )
keyring:sign_deterministic (message, sha)
Elliptic Curve Digital Signature Algorithm (ECDSA) signing function with deterministic generation of k (see RFC6979 https://www.rfc-editor.org/rfc/rfc6979). This method uses the private key inside a keyring to sign a message, returning a signature to be used in keyring:verify_deterministic. (kp.private, message, sha)

Parameters:

  • message string or OCTET message to sign
  • sha int length in bytes of the digest of the SHA function

Returns:

    table containing signature parameters octets and k (r,s,k)

Usage:

    kp = ECDH.keygen() -- generate keys or import them
m = "Message to be signed"
sha = 32 -- This is SHA256. Also 48 = SHA384 or 64 = SHA512 may be used.
signature = ECDH.sign_deterministic(kp.private, m, sha)
assert( ECDH.verify_determinitsic(kp.public, m, signature, sha) )
keyring.sk
Sign a message directly, without taking the hash (the input in an hashed message that is it is already hashed)
  • sk private key
  • m hashed message
  • n size of the message
  • k ephemeral private key (not mandatory)
keyring:verify (message, signature)
Elliptic Curve Digital Signature Algorithm (ECDSA) verification function. This method uses the public key inside a keyring to verify a message, returning true or false. The signature parameters are returned as 'r' and 's' in this same order by keyring:sign. (kp.public, message,signature)

Parameters:

  • message the message whose signature has to be verified
  • signature the signature table returned by keyring:sign

Returns:

    true if the signature is OK, or false if not.

See also:

keyring:verify_deterministic (message, signature, sha)
Elliptic Curve Digital Signature Algorithm (ECDSA) verification function. The main difference between ecdhdsaverify and this function is that here we also consider the input parameter sha int. This method uses the public key inside a keyring to verify a message, returning true or false. The signature parameters are returned as 'r' and 's' in this same order by keyring:sign_deterministic. (kp.public, message, signature, sha)

Parameters:

  • message the message whose signature has to be verified
  • signature the signature table returned by keyring:sign_deterministic
  • sha int length in bytes of the digest of the SHA function

Returns:

    true if the signature is OK, or false if not.

See also:

keyring:order ()
Order of the curve underlying the ECDH implementation ()

Returns:

    BIG with the order
keyring:prime ()
Modulus of the curve underlying the ECDH implementation ()

Returns:

    BIG with the modulus
keyring:cofactor ()
Cofactor of the curve underlying the ECDH implementation ()

Returns:

    int with the cofactor
keyring.x
Elliptic Curve Digital Signature Algorithm (ECDSA) recovery function. This method is intended to be used over all the possible point (x,y) that create the ephemeral public key of the signature, i.e. x can be equal to r+j*n where j is in [0,..,h] (h cofactor of the curve), n is the order of the curve and r is the first component of the signature. While y is uniquely identified by its parity. This method, if it exists, will output a public key Q for which (r, s) is a valid signature on the hashed message m.
  • x the x coordinate of the ephemeral public key
  • y_parity parity of y coordinate of the ephemeral public key
  • m hashed message
  • sig the signature (r,s)
generated by LDoc 1.5.0 Last updated 2025-03-25 10:43:18