Module ECDH
Elliptic Curve DiffieHellman 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 doublecolon 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 20172018
 License: GPLv3
 Author: Denis "Jaromil" Roio, Enrico Zimuel
Global ECDH functions
new (curve) 
Create a new ECDH encryption keyring using a specified curve or

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 DiffieHellman 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:sign (message)  Elliptic Curve Digital Signature Algorithm (ECDSA) signing function. 
keyring:verify (message, r, s)  Elliptic Curve Digital Signature Algorithm (ECDSA) verification function. 
keyring:aead_encrypt (key, message, iv, header)  AESGCM encrypt with Additional Data (AEAD) encrypts and authenticate a plaintext to a ciphtertext. 
keyring:aead_decrypt (key, message, iv, header)  AESGCM 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). 
Global ECDH functions
 new (curve)

Create a new ECDH encryption keyring using a specified curve or
BLS383 by default if omitted. The ECDH keyring created will offer methods to interact with other keyrings. Supported curves: BLS383, ED25519, GOLDILOCKS, SECP256K1 Please note curve selection is only supported in ECDH, while only BLS383 is supported for <a href="../modules/ECP.html#">ECP</a>/<a href="../modules/ECP2.html#">ECP2</a> arithmetics.
(curve)
Parameters:
 curve [opt=BLS383] elliptic curve to be used
Returns:

a new ECDH keyring
Usage:
keyring = ECDH.new()  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:
 OCTET public key
 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 DiffieHellman 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:aead_encrypt. This is
compliant with the IEEE1363 DiffieHellman shared secret
specification for asymmetric key encryption.
(keyring)
Parameters:
 keyring containing the public key to be used
Returns:
 octet KDF2 hashed session key ready for keyring:aead_encrypt
 octet a BIG number result of (private * public) % curve_order
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:sign (message)

Elliptic Curve Digital Signature Algorithm (ECDSA) signing
function. This method uses the private key inside a keyring to
sign a message, returning two parameters 'r' and 's' representing
the signature. The parameters can be used in keyring:verify.
(message)
Parameters:
 message string or OCTET message to sign
Returns:
 octet containing the first signature parameter (r)
 octet containing the second signature parameter (s)
Usage:
ecdh = ECDH.keygen()  generate keys or import them m = "Message to be signed" r,s = ecdh:sign(m) assert( ecdh:verify(m,r,s) )
 keyring:verify (message, r, s)

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,r,s)
Parameters:
 message the message whose signature has to be verified
 r the first signature parameter
 s the second signature paramter
Returns:

true if the signature is OK, or false if not.
See also:
 keyring:aead_encrypt (key, message, iv, header)

AESGCM 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, else
returns the secret ciphertext and a SHA256 of the header to
checksum the integrity of the accompanying plaintext, to be
compared with the one obtained by aead_decrypt.
(key, message, iv, h)
Parameters:
 key AES key octet (must be 8, 16, 32 or 64 bytes long)
 message input text in an octet
 iv initialization vector (can be random each time)
 header clear text, authenticated for integrity (checksum)
Returns:
 octet containing the output ciphertext
 octet containing the authentication tag (checksum)
 keyring:aead_decrypt (key, message, iv, header)

AESGCM decrypt with Additional Data (AEAD) decrypts and
authenticate a plaintext to a ciphtertext . Compatible with IEEE
P802.1 specification.
(key, ciphertext, iv, h)
Parameters:
 key AES key octet
 message input text in an octet
 iv initialization vector
 header the additional data
Returns:
 octet containing the output ciphertext
 octet containing the authentication tag (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
 parameters
[opt=nil] octet of key derivation parameters (can be
 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: