Module P256

P256

P-256 (also known as secp256r1 or prime256v1) is one of the most widely used elliptic curves in modern cryptography.

It is defined by the National Institute of Standards and Technology (NIST) and is part of the Suite B cryptographic standards. P-256 is based on elliptic curve cryptography (ECC), which provides strong security with relatively small key sizes, making it efficient for a wide range of applications. It operates over a finite field of 256 bits, providing a balance between security and performance.

ES256 is a cryptographic algorithm used for digital signatures. It is part of the Elliptic Curve Digital Signature Algorithm (ECDSA) and is based on the P-256 elliptic curve (also known as secp256r1 or prime256v1). ES256 is widely used in modern cryptography, particularly in JSON Web Tokens (JWTs) and secure communication protocols.

To work with this module, we define P256 by loading the es256 library using the require function:

P256 = require('es256').

Once the module is loaded, you can access its functions using the P256.function() syntax.

Global P256 Functions

keygen () Generate a P-256 elliptic curve key pair (a private key and a public key).
pubgen (sk) Generate a P-256 public key from a given private key.
pubcheck (pk) Validate whether a given P-256 public key is valid.
sign (sk, m, k) Sign a message using the P-256 elliptic curve digital signature algorithm (ECDSA).
verify (pk, m, sig) Verify an ECDSA signature using the P-256 elliptic curve.
public_xy (pk) Extract the x and y coordinates from a P-256 public key.
compress_public_key (pk) Compress a P-256 public key.


Global P256 Functions

keygen ()

Generate a P-256 elliptic curve key pair (a private key and a public key).
However it only returns the private key. A key pair consists of:

-a private key (secret scalar, a large random number).
-a public key (a point on the elliptic curve derived from the private key).

Returns:

    the secret key value

Usage:

    --generate a random private key and print it in hex
P256 = require('es256')
print(P256.keygen():hex())
--print for example: a43f787303d65596a708cee586cbad7f3e17c0a2d513ccb653f4c1ad6f37600e
pubgen (sk)
Generate a P-256 public key from a given private key.

Parameters:

  • sk the secret key

Returns:

    the public key value

Usage:

    --generate a private key that will be the input of P256.pubgen()
P256 = require('es256')
print(P256.pubgen(P256.keygen()):hex())
--the print in hexadecimal will be a random value of 64 bytes, for example
--print: 138380d70b0d492b8edf5c10ef9fa0c7c77287cbe92115270f75057a4dae3e86d264a5d0e13d215c3bc630357592f15e629f84de07c11df6663bb9b03d1e1912
pubcheck (pk)
Validate whether a given P-256 public key is valid. It takes a public key as input, checks its validity using the p256_validate_pubkey function. It takes a 64-byte uncompressed public key as input (the public key is represented as a concatenation of the x and y coordinates of the elliptic curve point), decodes it into elliptic curve coordinates, and checks if the coordinates represent a valid point on the P-256 curve.

Parameters:

  • pk the public key passed as an octet

Returns:

    true if pk is valid, false otherwise

Usage:

    P256 = require('es256')
--create secret key
sk = P256.keygen()
--create public key
pk = P256.pubgen(sk)
if (P256.pubcheck(pk)) then print("public key is valid")
else print("public key is invalid")
end
--print: public key is valid
sign (sk, m, k)
Sign a message using the P-256 elliptic curve digital signature algorithm (ECDSA). It takes a private key, a message, and an optional ephemeral key as inputs, computes the signature, and returns the signature to Lua. It computes the signature using the p256_ecdsa_sign function.

Parameters:

  • sk the private key (32 bytes)
  • m the message to be signed
  • k ephemeral key (optional)

Returns:

    the signature

Usage:

    P256 = require('es256')
--generate the secret and the public keys
sk = P256.keygen()
pk = P256.pubgen(sk)
--give a message to sign
m = O.from_str([[
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.]])
--sign the message
sig = P256.sign(sk,m)
verify (pk, m, sig)
Verify an ECDSA signature using the P-256 elliptic curve. It takes a public key, a message, and a signature as inputs, hashes the message, and verifies the signature against the public key and message hash. It uses the p256_ecdsa_verify function.

Parameters:

  • pk the public key (64 bytes)
  • m the message that was signed
  • sig a 64 bytes ECDSA signature

Returns:

    a boolean value

Usage:

    --from sign, check if the signature is valid
if (P256.verify(pk, m, sig)) then print("valid signature")
else print("invalid signature")
end
--print: valid signature
public_xy (pk)
Extract the x and y coordinates from a P-256 public key.
It takes a 64-byte uncompressed public key as input, splits it into its x and y coordinates, and returns them to Lua.

Parameters:

  • pk the public key as an octet

Returns:

  1. the x coordinate of the public key
  2. the y coordinate of the public key

Usage:

    P256 = require('es256')
--generate private and public keys
sk = P256.keygen()
pk = P256.pubgen(sk)
--find x and y coordinates for the public key
x, y = P256.public_xy(pk)
compress_public_key (pk)
Compress a P-256 public key.
It takes a 64-byte uncompressed public key as input, compresses it into a 33-byte compressed format, and returns the compressed key to Lua. It uses the p256_compress_publickey function.

Parameters:

  • pk the public key passed as an octet

Returns:

    the compressed public key

Usage:

    P256 = require('es256')
--generate public and private keys
sk = P256.keygen()
pk = P256.pubgen(sk)
--create the compressed public key
pk_comp = P256.compress_public_key(pk)
--print the length of the compress public key
print(pk_comp:__len())
--print: 33
generated by LDoc 1.5.0 Last updated 2025-03-25 10:43:18