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-2019
  • License: AGPLv3
  • Author: Denis "Jaromil" Roio

Global ECDH functions

new (curve) Create a new ECDH encryption keyring using a specified curve ('BLS383' by default).

Class keyring

keyring:keygen () Generate an ECDH public/private key pair for a keyring

Keys generated are both returned and stored inside the keyring.

keyring:public (key) Imports a public key inside an ECDH keyring.
keyring:public () Returns X and Y coordinates of the public key inside an ECDH keyring.
keyring:private (key) Imports a private key inside an ECDH keyring.
keyring:sign (message) Elliptic Curve Digital Signature Algorithm (ECDSA) signing function.
keyring:verify (message, signature) Elliptic Curve Digital Signature Algorithm (ECDSA) verification function.
keyring:encrypt (keyring, message, header) Simple method for AES-GCM encryption with Additional Data (AEAD), compatible with IEEE P802.1 specification.
keyring:ciphertext Results of keyring:encrypt
keyring:decrypt (ciphertext) Simple method for AES-GCM decrypt with Additional Data (AEAD).
keyring:hmac (key, data) Compute the HMAC of a message using a key.
keyring:kdf2 (hash, key) Key Derivation Function (KDF2).
keyring:pbkdf2 (key, salt, iterations, length) Password Based Key Derivation Function (PBKDF2).


Global ECDH functions

new (curve)
Create a new ECDH encryption keyring using a specified curve ('BLS383' by default).

A keyring object will be returned implementing ECDH methods.

Supported curves: 'BLS383', 'ED25519', 'GOLDILOCKS', 'SECP256K1' (curve)

Parameters:

  • curve [opt=BLS383] name of elliptic curve to use

Returns:

    a new keyring

Usage:

    keyring = ECDH.new()
    -- generate a keypair
    keypair = keyring:keygen()
    I.print(keypair)
    [[{ public = oct[] .... ,
        private = oct[] .... }]]

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. They can also be retrieved later using the public and private methods. ()

Returns:

  1. OCTET public key
  2. OCTET private key
keyring:public (key)
Imports a public key inside an ECDH keyring.

This is a get/set method working both ways: without argument it returns the public key of a keyring, or if an OCTET argument is provided and is a valid public key it is imported.

If the keyring has a public key already, it will refuse to overwrite it and return an error. (key)

Parameters:

  • key [opt] octet of a public key to be imported
keyring:public ()
Returns X and Y coordinates of the public key inside an ECDH keyring. (key)

Returns:

  1. OCTET coordinate X of public key
  2. OCTET coordinate Y of public key
keyring:private (key)
Imports a private key inside an ECDH keyring.

This is a get/set method working both ways: without argument it returns the private key of a keyring, or if an OCTET argument is provided it is imported as private key inside the keyring and used to derivate its corresponding public key.

If the keyring contains already any key, it will refuse to overwrite them and return an error. (key)

Parameters:

  • key [opt] octet of a private key to be imported
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. (message)

Parameters:

  • message string or OCTET message to sign

Returns:

    table containing signature parameters octets (r,s)

Usage:

    ecdh = ECDH.keygen() -- generate keys or import them
    m = "Message to be signed"
    signature = ecdh:sign(m)
    assert( ecdh:verify(m,signature) )
keyring:verify (message, signature)
Elliptic Curve Digital Signature Algorithm (ECDSA) verification function. This method uses the public key iside 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. (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:encrypt (keyring, message, header)
Simple method for AES-GCM encryption with Additional Data (AEAD), compatible with IEEE P802.1 specification. Takes a keyring object for the public key and a table of parameters. Returns also a table with the cyphertext and a checksum that is accepted by decrypt. (keyring, message, header)

Parameters:

  • keyring recipient keyring containing the public key
  • message octet input text to be encrypted for secrecy
  • header octet input header authenticated for integrity

Returns:

    ciphertext
keyring:ciphertext
Results of keyring:encrypt

Usage:

    { text = "encrypted text",             -- OCTET
      checksum = "control checksum",       -- OCTET of 16 bytes
      iv = "random IV",                    -- OCTET of 16 bytes
      header = "clear text header",        -- OCTET often encoded JSON table
keyring:decrypt (ciphertext)
Simple method for AES-GCM decrypt with Additional Data (AEAD). Takes a table as returned by keyring:encrypt containing text, checksum, header, IV and the sender's pubkey. Returns an octet containing the decrypted message or error if any problem arises (invalid checksum etc.). Compatible with IEEE P802.1 specification. (ciphertext)

Parameters:

  • ciphertext table with text, checksum, iv, header and pubkey

Returns:

    octet containing the decrypted message
keyring:hmac (key, data)
Compute the HMAC of a message using a key. This method takes any data and any key material to comput an HMAC of the same length of the hash bytes of the keyring. (key, data)

Parameters:

  • key an octet containing the key to compute the HMAC
  • data an octet containing the message to compute the HMAC

Returns:

    a new octet containing the computed HMAC or false on failure
keyring:kdf2 (hash, key)
Key Derivation Function (KDF2). Key derivation is used to strengthen keys against bruteforcing: they impose a number of costly computations to be iterated on the key. This function generates a new key from an existing key applying an octet of key derivation parameters. (key)

Parameters:

  • hash initialized HASH or ECDH object
  • key octet of the key to be transformed

Returns:

    a new octet containing the derived key
keyring:pbkdf2 (key, salt, iterations, length)
Password Based Key Derivation Function (PBKDF2). This function generates a new key from an existing key applying a salt and number of iterations. (key, salt, iterations, length)

Parameters:

  • key octet of the key to be transformed
  • salt octet containing a salt to be used in transformation
  • iterations [opt=1000] number of iterations to be applied
  • length [opt=key length] integer indicating the new length (default same as input key)

Returns:

    a new octet containing the derived key

See also:

generated by LDoc 1.4.3 Last updated 2019-10-01 10:18:34
]==]