Update docs

ed25519.lua

@@ -1,5 +1,8 @@
 --- The Ed25519 signature scheme.
 --
+-- **Note:** This library is provided for compatibility and provides no side
+-- channel resistance by itself.
+--
 -- @module ed25519
 --
 
@@ -228,6 +231,11 @@ end
 
 local mod = {}
 
+--- Computes a public key from a secret key.
+--
+-- @tparam string sk A random 32-byte secret key.
+-- @treturn string The matching 32-byte public key.
+--
 function mod.publicKey(sk)
     expect(1, sk, "string")
     assert(#sk == 32, "secret key length must be 32")
@@ -238,6 +246,13 @@ function mod.publicKey(sk)
     return encode(scale(mulG(fq.bits(x))))
 end
 
+--- Signs a message.
+--
+-- @tparam string sk The signer's secret key.
+-- @tparam string pk The signer's public key.
+-- @tparam string msg The message to be signed.
+-- @treturn string The 64-byte signature on the message.
+--
 function mod.sign(sk, pk, msg)
     expect(1, sk, "string")
     assert(#sk == 32, "secret key length must be 32")
@@ -264,6 +279,13 @@ function mod.sign(sk, pk, msg)
     return rStr .. sStr
 end
 
+--- Verifies a signature on a message.
+--
+-- @tparam string pk The signer's public key.
+-- @tparam string msg The signed message.
+-- @tparam string sig The signature.
+-- @treturn boolean Whether the signature is valid or not.
+--
 function mod.verify(pk, msg, sig)
     expect(1, pk, "string")
     assert(#pk == 32, "public key length must be 32")

internal/fp.lua

@@ -1,4 +1,4 @@
---- Arithmetic on Curve25519's base field.
+--- Arithmetic on Curve25519's base field (unstable, for internal use only).
 --
 -- @module internal.fp
 --

internal/fq.lua

@@ -1,4 +1,4 @@
---- Arithmetic on Curve25519's scalar field.
+--- Arithmetic on Curve25519's scalar field (unstable, for internal use only).
 --
 -- @module internal.fq
 --
@@ -61,7 +61,7 @@ local T1 = {
 
 --- Carries a number in base 2²⁴.
 --
--- @tparam {number...} a A number 0 <= a < 2 ^ (24 * (#a + 1)) as limbs in
+-- @tparam {number...} a A number 0 <= a < 2 ^ (24 ✕ (#a + 1)) as limbs in
 -- [-2⁵²..2⁵²].
 -- @treturn {number...} a as #a + 1 limbs in [0..2²⁴).
 --
@@ -98,7 +98,7 @@ end
 --
 -- @tparam {number...} a An array of 11 limbs in [0..2²⁴).
 -- @tparam {number...} b An array of 11 limbs in [0..2²⁴).
--- @treturn {number...} a * b as 22 limbs in [0..2²⁴).
+-- @treturn {number...} a ✕ b as 22 limbs in [0..2²⁴).
 --
 local function intMul(a, b)
     local c = {}
@@ -110,19 +110,19 @@ local function intMul(a, b)
         end
     end
 
-    -- {a, b} < 2²⁶⁴ means that c < 2⁵²⁸ = 2 ^ (24 * (21 + 1)).
-    -- c's limbs are smaller than 2⁴⁸ * 11 < 2⁵², since multiplication doubles
+    -- {a, b} < 2²⁶⁴ means that c < 2⁵²⁸ = 2 ^ (24 ✕ (21 + 1)).
+    -- c's limbs are smaller than 2⁴⁸ ✕ 11 < 2⁵², since multiplication doubles
     -- bit length, and 11 multiplied limbs are added together.
     return carry(c)
 end
 
 --- Reduces a number modulo q.
 --
--- @tparam {number...} a A number a < 2 * q as 12 limbs in [0..2²⁴).
+-- @tparam {number...} a A number a < 2q as 12 limbs in [0..2²⁴).
 -- @treturn {number...} a mod q as 11 limbs in [0..2²⁴).
 --
 local function reduce(a)
-    local c = {unpack(a, 1, 11)} -- a < 2 * q implies that a[12] = 0.
+    local c = {unpack(a, 1, 11)} -- a < 2q implies that a[12] = 0.
 
     -- Return c if c < r.
     for i = 11, 1, -1 do
@@ -138,7 +138,7 @@ local function reduce(a)
     end
 
     -- c >= q means c - q >= 0.
-    -- Since q < 2²⁸⁸, c < 2 * q means c - q < q < 2²⁸⁸ = 2^(24 * (11 + 1)).
+    -- Since q < 2²⁸⁸, c < 2q means c - q < q < 2²⁸⁸ = 2^(24 ✕ (11 + 1)).
     -- c's limbs fit in [-2²⁵..2²⁵], since subtraction adds at most one bit.
     local cc = carry(c)
     cc[12] = nil -- cc < q implies that cc[12] = 0.
@@ -148,7 +148,7 @@ end
 --- Adds two scalars mod q.
 --
 -- If the two operands are in Montgomery form, returns the correct result also
--- in Montgomery form, since (2²⁶⁴ * a) + (2²⁶⁴ * b) ≡ 2²⁶⁴ * (a + b) (mod q).
+-- in Montgomery form, since (2²⁶⁴ ✕ a) + (2²⁶⁴ ✕ b) ≡ 2²⁶⁴ ✕ (a + b) (mod q).
 --
 -- @tparam {number...} a A number a < q as 11 limbs in [0..2²⁴).
 -- @tparam {number...} b A number b < q as 11 limbs in [0..2²⁴).
@@ -169,16 +169,16 @@ local function neg(a)
         c[i] = Q[i] - a[i]
     end
 
-    -- 0 < c < q implies 0 < q - c < q < 2²⁸⁸ = 2^(24 * (11 + 1)).
+    -- 0 < c < q implies 0 < q - c < q < 2²⁸⁸ = 2^(24 ✕ (11 + 1)).
     -- c's limbs fit in [-2²⁵..2²⁵], since subtraction adds at most one bit.
-    -- q - c < q also implies q - c < 2 * q.
+    -- q - c < q also implies q - c < 2q.
     return reduce(carry(c))
 end
 
 --- Given a scalar a, computes 2⁻²⁶⁴ a mod q.
 --
--- @tparam {number...} a A number a < 2²⁶⁴ * q as 22 limbs in [0..2²⁴).
--- @treturn {number...} 2⁻²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
+-- @tparam {number...} a A number a < 2²⁶⁴ ✕ q as 22 limbs in [0..2²⁴).
+-- @treturn {number...} 2⁻²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
 --
 local function redc(a)
     local al = {unpack(a, 1, 11)}
@@ -189,54 +189,54 @@ local function redc(a)
     return reduce({unpack(t, 12, 23)})
 end
 
---- Converts a scalar a into its Montgomery form 2²⁶⁴ a mod q.
+--- Converts a scalar into Montgomery form.
 --
 -- @tparam {number...} a A number a as 11 limbs in [0..2²⁴).
--- @treturn {number...} 2²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
 --
 local function montgomery(a)
-    -- a < 2²⁶⁴ and T1 < q imply that a * T1 < 2²⁶⁴ * q.
+    -- a < 2²⁶⁴ and T1 < q imply that a ✕ T1 < 2²⁶⁴ ✕ q.
     return redc(intMul(a, T1))
 end
 
---- Converts a scalar a from its Montgomery form 2²⁶⁴ a mod q.
+--- Converts a scalar from Montgomery form.
 --
 -- @tparam {number...} a A number a < q as 11 limbs in [0..2²⁴).
--- @treturn {number...} 2⁻²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2⁻²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
 --
 local function demontgomery(a)
     a = {unpack(a)}
     for i = 12, 22 do a[i] = 0 end
-    -- a < q < 2²⁶⁴ * q.
+    -- a < q < 2²⁶⁴ ✕ q.
     return redc(a)
 end
 
 --- Converts a Lua number to a scalar.
 --
 -- @tparam number n A number n in [0..2²⁴).
--- @treturn {number...} 2²⁶⁴ * n mod q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2²⁶⁴ ✕ n mod q as 11 limbs in [0..2²⁴).
 --
 local function num(n)
     return montgomery({n, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0})
 end
 
---- Multiplies two scalars in Montgomery form mod q.
+--- Multiplies two scalars mod q.
 --
--- @tparam {number...} a 2²⁶⁴ * a' mod q as 11 limbs in [0..2²⁴).
--- @tparam {number...} b 2²⁶⁴ * b' mod q as 11 limbs in [0..2²⁴).
--- @treturn {number...} 2²⁶⁴ * a' * b' mod q as 11 limbs in [0..2²⁴).
+-- @tparam {number...} a 2²⁶⁴ ✕ a' mod q as 11 limbs in [0..2²⁴).
+-- @tparam {number...} b 2²⁶⁴ ✕ b' mod q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2²⁶⁴ ✕ a' ✕ b' mod q as 11 limbs in [0..2²⁴).
 --
 local function mul(a, b)
-    -- {a, b} < q so a * b < q² < 2²⁶⁴ * q.
+    -- {a, b} < q so a ✕ b < q² < 2²⁶⁴ ✕ q.
     return redc(intMul(a, b))
 end
 
 --- Inverts a scalar mod q.
 --
--- Computation of the inverse requires several multiplications.
+-- Computation of the inverse takes 338 multiplications.
 --
--- @tparam {number...} a A number 2²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
--- @treturn[1] {number...} 2²⁶⁴ * a⁻¹ mod q as 11 limbs in [0..2²⁴).
+-- @tparam {number...} a A number 2²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
+-- @treturn[1] {number...} 2²⁶⁴ ✕ a⁻¹ mod q as 11 limbs in [0..2²⁴).
 -- @treturn[2] {number...} 0 if the argument is 0, which has no inverse.
 --
 local function invert(a)
@@ -252,7 +252,7 @@ end
 
 --- Encodes a scalar.
 --
--- @tparam {number...} a A number 2²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
+-- @tparam {number...} a A number 2²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
 -- @treturn string The 32-byte string encoding of a.
 --
 local function encode(a)
@@ -262,7 +262,7 @@ end
 --- Decodes a scalar.
 --
 -- @tparam string str A 32-byte string encoding some little-endian number a.
--- @treturn {number...} 2²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
 --
 local function decode(str)
     local dec = {("<I3I3I3I3I3I3I3I3I3I3I2"):unpack(str)} dec[12] = nil
@@ -272,7 +272,7 @@ end
 --- Decodes a scalar from a "wide" string.
 --
 -- @tparam string str A 64-byte string encoding some little-endian number a.
--- @treturn 2²⁶⁴ * a mod q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2²⁶⁴ ✕ a mod q as 11 limbs in [0..2²⁴).
 --
 local function decodeWide(str)
     local low = {("<I3I3I3I3I3I3I3I3I3I3I3"):unpack(str)} low[12] = nil
@@ -283,7 +283,7 @@ end
 --- Decodes a scalar using the X25519/Ed25519 bit clamping scheme.
 --
 -- @tparam string str A 32-byte string encoding some little-endian number a.
--- @treturn 2²⁶⁵ * clamp(a) mod q as 11 linbs in [0..2²⁴).
+-- @treturn {number...} 2²⁶⁴ ✕ clamp(a) mod q as 11 limbs in [0..2²⁴).
 --
 local function decodeClamped(str)
     -- Decode.
@@ -299,8 +299,8 @@ end
 
 --- Returns a scalar in binary.
 --
--- @tparam {number...} a A number a < q as limbs in [0..2²⁴).
--- @treturn {number...} 2⁻²⁶⁴ * a mod q as limbs in [0..2).
+-- @tparam {number...} a A number a < q as 11 limbs in [0..2²⁴).
+-- @treturn {number...} 2⁻²⁶⁴ ✕ a mod q as 265 bits.
 --
 local function bits(a)
     return util.rebaseLE(demontgomery(a), 2 ^ 24, 2)

internal/sha512.lua

@@ -1,4 +1,4 @@
---- The SHA512 cryptographic hash function.
+--- The SHA512 cryptographic hash function (unstable, for internal use only).
 --
 -- @module internal.sha512
 --