Module ECDH

Elliptic Curve Diffie-Hellman encryption (ECDH)

Asymmetric public/private key encryption technologies.

ECDH encryption functionalities are provided with all standard functions by this extension. It is possible to create keyring instances using the new() method:

keyring = 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-2018
  • License: GPLv3
  • Author: Denis "Jaromil" Roio, Enrico Zimuel

Global ECDH functions

new (curve)

Create a new ECDH encryption keyring using a specified curve or

ED25519 by default if omitted.

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:checkpub (key) Validate an ECDH public key.
keyring:session (keyring) Generate a Diffie-Hellman shared session key.
keyring:public (key) Imports or exports the public key from an ECDH keyring.
keyring:private (key) Imports or exports the private key from an ECDH keyring.
keyring:encrypt_weak_aes_cbc (key, message) AES encrypts a plaintext to a ciphtertext.
keyring:decrypt_weak_aes_cbc (key, ciphertext) AES decrypts a plaintext to a ciphtertext.
keyring:encrypt (key, message, iv, header) AES-GCM encrypt with Additional Data (AEAD) encrypts and authenticate a plaintext to a ciphtertext.
keyring:decrypt (key, message, iv, header) AES-GCM decrypt with Additional Data (AEAD) decrypts and authenticate a plaintext to a ciphtertext .
keyring:hash (string) Hash an octet into a new octet.
keyring:hmac (key, data, len) Compute the HMAC of a message using a key.
keyring:kdf2 (parameters, key, length) Key Derivation Function (KDF2).
keyring:pbkdf2 (key, salt, iterations, length) Password Based Key Derivation Function (PBKDF2).
keyring:random (int) Cryptographically Secure Random Number Generator (RNG).


Global ECDH functions

new (curve)
Create a new ECDH encryption keyring using a specified curve or

ED25519 by default if omitted.  The ECDH keyring created will
offer methods to interact with other keyrings.

Supported curves: ed25519, nist256, bn254cx, fp256bn

(curve)

Parameters:

  • curve [opt=ed25519] elliptic curve to be used

Returns:

    a new ECDH keyring

Usage:

    keyring = ECDH.new('ed25519')
    -- generate a keypair
    keyring:keygen()

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 if necessary. ()

Returns:

  1. OCTET public key
  2. OCTET private key
keyring:checkpub (key)
Validate an ECDH public key. Any octet can be a private key, but public keys aren't random and checking them is the only validation possible. (key)

Parameters:

  • key the input public key octet to be validated

Returns:

    true if public key is OK, or false if not.
keyring:session (keyring)
Generate a Diffie-Hellman shared session key. This function uses two keyrings to calculate a shared key, then process it through KDF2 to make it ready for use in keyring:encrypt. This is compliant with the IEEE-1363 Diffie-Hellman shared secret specification for asymmetric key encryption. (keyring)

Parameters:

  • keyring containing the public key to be used

Returns:

  1. octet KDF2 hashed session key ready for keyring:encrypt
  2. octet a big number result of mod(private,curve_order)*public

See also:

keyring:public (key)
Imports or exports the public key from an ECDH keyring. This method functions in two ways: without argument it returns the public key of a keyring, or if an octet argument is provided it imports it as public key inside the keyring, but it refuses to overwrite and returns an error if a public key is already present. (key)

Parameters:

  • key [opt] octet of a public key to be imported
keyring:private (key)
Imports or exports the private key from an ECDH keyring. This method functions in two ways: without argument it returns the private key of a keyring, or if an octet argument is provided it imports it as private key inside the keyring and generates a public key for it. If a private key is already present in the keyring it refuses to overwrite and returns an error. (key)

Parameters:

  • key [opt] octet of a private key to be imported
keyring:encrypt_weak_aes_cbc (key, message)
AES encrypts a plaintext to a ciphtertext. Function compatible with IEEE-1363 AES_CBC_IV0_ENCRYPT. Encrypts in CBC mode with a zero IV, pads necessary to create a full final block. This is weak encryption and keyring:encrypt should be preferred. (key, message)

Parameters:

  • key AES key octet
  • message input text in an octet

Returns:

    a new octet containing the output ciphertext
keyring:decrypt_weak_aes_cbc (key, ciphertext)
AES decrypts a plaintext to a ciphtertext. Function compabible with IEEE-1363 specification for AES CBC using IV set to zero. Decrypts a secret produced using keyring:encrypt_weak_aes_cbc in CBC mode. (key, ciphertext)

Parameters:

  • key AES key octet
  • ciphertext input ciphertext octet

Returns:

    a new octet containing the decrypted plain text, or false when failed
keyring:encrypt (key, message, iv, header)
AES-GCM encrypt with Additional Data (AEAD) encrypts and authenticate a plaintext to a ciphtertext. Function compatible with IEEE P802.1 specification. Errors out if encryption fails or authentication fails, else returns the secret ciphertext and a SHA256 of the header to checksum the integrity of the accompanying plaintext. (key, message, iv, h)

Parameters:

  • key AES key octet
  • message input text in an octet
  • iv initialization vector
  • header clear text, authenticated for integrity (checksum)

Returns:

  1. octet containing the output ciphertext
  2. octet containing the authentication tag (checksum)
keyring:decrypt (key, message, iv, header)
AES-GCM decrypt with Additional Data (AEAD) decrypts and authenticate a plaintext to a ciphtertext . Compatible with IEEE P802.1 specification. (key, ciphertext, iv, h, tag)

Parameters:

  • key AES key octet
  • message input text in an octet
  • iv initialization vector
  • header the additional data

Returns:

    a new octet containing the output ciphertext and the checksum
keyring:hash (string)
Hash an octet into a new octet. Use the keyring's hash function to hash an octet string and return a new one containing the hash of the string. (string)

Parameters:

  • string octet containing the data to be hashed

Returns:

    a new octet containing the hash of the data
keyring:hmac (key, data, len)
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, len)

Parameters:

  • key an octet containing the key to compute the HMAC
  • data an octet containing the message to compute the HMAC
  • len [opt=keyring->hash bytes] length of HMAC or default

Returns:

    a new octet containing the computer HMAC or false on failure
keyring:kdf2 (parameters, key, length)
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. (parameters, key, length)

Parameters:

  • parameters [opt=nil] octet of key derivation parameters (can be nil)
  • key octet of the key to be transformed
  • length [opt=key length] integer indicating the new length (default same as input key)

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:

keyring:random (int)
Cryptographically Secure Random Number Generator (RNG).

Returns a new octet filled with random bytes.

This method is initialised with a different seed for each keyring upon creation. It doesn't make any difference to use one keyring's RNG or another, but mixing them and making this behavior specific to different scripts helps randomness.

Cryptographic security is achieved by hashing the random numbers using this sequence: unguessable seed -> SHA -> PRNG internal state -> SHA -> random numbers. See this paper for a justification. (int)

Parameters:

  • int [opt=rsa->max] length of random material in bytes, defaults to maximum RSA size

Usage:

    ecdh = require'ecdh'
    ed25519 = ecdh.new('ed25519')
    -- generate a random octet (will be sized 2048/8 bytes)
    csrand = ed25519:random()
    -- print out the cryptographically secure random sequence in hex
    print(csrand:hex())
generated by LDoc 1.4.3 Last updated 2018-10-01 18:53:47
]==]