This is an automated email from the ASF dual-hosted git repository.
kmccusker pushed a commit to branch issue10
in repository
https://gitbox.apache.org/repos/asf/incubator-milagro-crypto-js.git
The following commit(s) were added to refs/heads/issue10 by this push:
new bd8b43a updated js documentation
bd8b43a is described below
commit bd8b43a394900ae471b0cadd195a2654f0c24058
Author: Kealan McCusker <[email protected]>
AuthorDate: Thu Jul 11 14:28:29 2019 +0100
updated js documentation
---
src/fp.js | 183 ++++++++++++++++++++++++++++++++++-------
src/fp4.js | 250 ++++++++++++++++++++++++++++++++++++++++++++++++--------
src/fp8.js | 268 +++++++++++++++++++++++++++++++++++++++++++++++++++++--------
3 files changed, 607 insertions(+), 94 deletions(-)
diff --git a/src/fp.js b/src/fp.js
index ebb0d74..787c533 100644
--- a/src/fp.js
+++ b/src/fp.js
@@ -23,7 +23,13 @@
var FP = function(ctx) {
"use strict";
- /* General purpose Constructor */
+ /**
+ * Creates an instance of FP2.
+ *
+ * @constructor
+ * @this {FP2}
+ * @param x FP / BIG instance
+ */
var FP = function(x) {
if (x instanceof FP) {
this.f = new ctx.BIG(x.f);
@@ -57,31 +63,57 @@ var FP = function(ctx) {
FP.TMASK = (1 << FP.TBITS) - 1;
FP.prototype = {
- /* set this=0 */
+
+ /**
+ * Set FP2 to zero
+ *
+ * @this {FP2}
+ */
zero: function() {
this.XES = 1;
this.f.zero();
},
- /* copy from a ctx.BIG in ROM */
+ /**
+ * copy from a ctx.BIG in ROM
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be copied
+ */
rcopy: function(y) {
this.f.rcopy(y);
this.nres();
},
- /* copy from another ctx.BIG */
+ /**
+ * copy from another ctx.BIG
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be copied
+ */
bcopy: function(y) {
this.f.copy(y);
this.nres();
},
- /* copy from another FP */
+ /**
+ * Copy FP2 to another FP2
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be copied
+ */
copy: function(y) {
this.XES = y.XES;
this.f.copy(y.f);
},
- /* conditional swap of a and b depending on d */
+ /**
+ * Conditional constant time swap of two FP numbers
+ *
+ * @this {BIG}
+ * @parameter b FP number
+ * @parameter d Integer
+ */
cswap: function(b, d) {
this.f.cswap(b.f, d);
var t, c = d;
@@ -91,7 +123,13 @@ var FP = function(ctx) {
b.XES ^= t;
},
- /* conditional copy of b to a depending on d */
+ /**
+ * Conditional copy of FP2 number
+ *
+ * @this {FP2}
+ * @param g FP2 instance
+ * @param d copy depends on this value
+ */
cmove: function(b, d) {
var c = d;
@@ -101,7 +139,11 @@ var FP = function(ctx) {
this.XES ^= (this.XES ^ b.XES) & c;
},
- /* convert to Montgomery n-residue form */
+ /**
+ * Converts from BIG integer to residue form mod Modulus
+ *
+ * @this {FP2}
+ */
nres: function() {
var r, d;
@@ -119,7 +161,11 @@ var FP = function(ctx) {
return this;
},
- /* convert back to regular form */
+ /**
+ * Converts from residue form back to BIG integer form
+ *
+ * @this {FP2}
+ */
redc: function() {
var r = new ctx.BIG(0),
d, w;
@@ -136,20 +182,32 @@ var FP = function(ctx) {
return r;
},
- /* convert this to string */
+ /**
+ * convert to hex string
+ *
+ * @this {FP2}
+ */
toString: function() {
var s = this.redc().toString();
return s;
},
- /* test this=0 */
+ /**
+ * Tests for FP2 equal to zero
+ *
+ * @this {FP2}
+ */
iszilch: function() {
var c=new FP(0); c.copy(this);
c.reduce();
return c.f.iszilch();
},
- /* reduce this mod Modulus */
+ /**
+ * Reduces all components of possibly unreduced FP2 mod Modulus
+ *
+ * @this {FP2}
+ */
reduce: function() {
var q,carry,sr,sb,m = new ctx.BIG(0);
m.rcopy(ctx.ROM_FIELD.Modulus);
@@ -182,18 +240,31 @@ var FP = function(ctx) {
this.XES = 1;
},
- /* set this=1 */
+ /**
+ * Set FP2 to unity
+ *
+ * @this {FP2}
+ */
one: function() {
this.f.one();
this.nres();
},
- /* normalise this */
+ /**
+ * Normalises the components of an FP2
+ *
+ * @this {FP2}
+ */
norm: function() {
return this.f.norm();
},
- /* this*=b mod Modulus */
+ /**
+ * Fast Modular multiplication of two FPs, mod Modulus
+ *
+ * @this {FP2}
+ * @param b FP number, the multiplier
+ */
mul: function(b) {
var d;
@@ -208,7 +279,12 @@ var FP = function(ctx) {
return this;
},
- /* this*=c mod Modulus where c is an int */
+ /**
+ * Multiplication of an FP2 by a small integer
+ *
+ * @this {FP2}
+ * @param s integer
+ */
imul: function(c) {
var s = false,
d, n;
@@ -239,7 +315,11 @@ var FP = function(ctx) {
return this;
},
- /* this*=this mod Modulus */
+ /**
+ * Fast Squaring of an FP2
+ *
+ * @this {FP2}
+ */
sqr: function() {
var d, t;
@@ -266,7 +346,13 @@ var FP = function(ctx) {
return this;
},
- /* this=-this mod Modulus */
+
+ /**
+ * negate this
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be set to one
+ */
neg: function() {
var m = new ctx.BIG(0),
sb;
@@ -286,7 +372,12 @@ var FP = function(ctx) {
return this;
},
- /* this-=b */
+ /**
+ * subtraction of two FP2s
+ *
+ * @this {FP2}
+ * @param x FP2 instance
+ */
sub: function(b) {
var n = new FP(0);
@@ -306,7 +397,11 @@ var FP = function(ctx) {
this.add(n);
},
- /* this/=2 mod Modulus */
+ /**
+ * Divide an FP2 by 2
+ *
+ * @this {FP2}
+ */
div2: function() {
var p;
@@ -325,8 +420,14 @@ var FP = function(ctx) {
},
// return this^(p-3)/4 or this^(p-5)/8
-// See https://eprint.iacr.org/2018/1038
- fpow: function() {
+ // See https://eprint.iacr.org/2018/1038
+
+ /**
+ * return this^(p-3)/4 or this^(p-5)/8
+ *
+ * @this {FP2}
+ */
+ fpow: function() {
var i,j,k,bw,w,c,nw,lo,m,n;
var xp=[];
var ac=[1,2,3,6,12,15,30,60,120,240,255];
@@ -427,7 +528,11 @@ var FP = function(ctx) {
return r;
},
- /* this=1/this mod Modulus */
+ /**
+ * Inverting an FP2
+ *
+ * @this {FP2}
+ */
inverse: function() {
if (FP.MODTYPE == FP.PSEUDO_MERSENNE || FP.MODTYPE ==
FP.GENERALISED_MERSENNE)
@@ -454,7 +559,12 @@ var FP = function(ctx) {
}
},
- /* return TRUE if this==a */
+ /**
+ * Tests for equality of two FP2 instances
+ *
+ * @this {FP2}
+ * @param x FP2 instance to compare
+ */
equals: function(a) {
var ft=new FP(0); ft.copy(this);
var sd=new FP(0); sd.copy(a);
@@ -468,7 +578,12 @@ var FP = function(ctx) {
return false;
},
- /* return this^e mod Modulus */
+ /**
+ * Raises an FP2 to the power of a BIG
+ *
+ * @this {FP2}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var i,w=[],
tb=[],
@@ -503,7 +618,11 @@ var FP = function(ctx) {
return r;
},
- /* return jacobi symbol (this/Modulus) */
+ /**
+ * return jacobi symbol (this/Modulus)
+ *
+ * @this {FP2}
+ */
jacobi: function() {
var p = new ctx.BIG(0),
w = this.redc();
@@ -513,7 +632,11 @@ var FP = function(ctx) {
return w.jacobi(p);
},
- /* return sqrt(this) mod Modulus */
+ /**
+ * Fast Modular square root of a an FP, mod Modulus
+ *
+ * @this {FP2}
+ */
sqrt: function() {
var i, v, r;
@@ -590,7 +713,11 @@ var FP = function(ctx) {
return Math.floor(num/(den+1))
};
- /* reduce a ctx.DBIG to a ctx.BIG using a "special" modulus */
+ /**
+ * reduce a ctx.DBIG to a ctx.BIG using a "special" modulus
+ *
+ * @this {FP2}
+ */
FP.mod = function(d) {
var b = new ctx.BIG(0),
i, t, v, tw, tt, lo, carry, m, dd;
diff --git a/src/fp4.js b/src/fp4.js
index 12c7c97..2ad664e 100644
--- a/src/fp4.js
+++ b/src/fp4.js
@@ -24,7 +24,12 @@
var FP4 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP4
+ *
+ * @constructor
+ * @this {FP4}
+ */
var FP4 = function(c, d) {
if (c instanceof FP4) {
this.a = new ctx.FP2(c.a);
@@ -36,90 +41,164 @@ var FP4 = function(ctx) {
};
FP4.prototype = {
- /* reduce all components of this mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP4 mod Modulus
+ *
+ * @this {FP4}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
},
- /* normalise all components of this mod Modulus */
+ /**
+ * Normalises the components of an FP4
+ *
+ * @this {FP4}
+ */
norm: function() {
this.a.norm();
this.b.norm();
},
- /* test this==0 ? */
+ /**
+ * Tests for FP4 equal to zero
+ *
+ * @this {FP4}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch());
},
- /* test this==1 ? */
+ /**
+ * Tests for FP4 equal to unity
+ *
+ * @this {FP4}
+ */
isunity: function() {
var one = new ctx.FP2(1);
return (this.a.equals(one) && this.b.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP4 number
+ *
+ * @this {FP4}
+ * @param g FP4 instance
+ * @param d copy depends on this value
+ */
cmove: function(g, d) {
this.a.cmove(g.a, d);
this.b.cmove(g.b, d);
},
- /* test is w real? That is in a+ib test b is zero */
+ /**
+ * test is w real? That is in a+ib test b is zero
+ *
+ * @this {FP4}
+ */
isreal: function() {
return this.b.iszilch();
},
- /* extract real part a */
+ /**
+ * extract real part a
+ *
+ * @this {FP4}
+ */
real: function() {
return this.a;
},
+ /**
+ * extract a from this
+ *
+ * @this {FP4}
+ */
geta: function() {
return this.a;
},
- /* extract imaginary part b */
+ /**
+ * extract b from this
+ *
+ * @this {FP4}
+ */
getb: function() {
return this.b;
},
- /* test this=x? */
+ /**
+ * Tests for equality of two FP4s
+ *
+ * @this {FP4}
+ * @param x FP4 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b));
},
- /* copy this=x */
+ /**
+ * Copy FP4 to another FP4
+ *
+ * @this {FP4}
+ * @param x FP4 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
},
- /* this=0 */
+ /**
+ * Set FP4 to zero
+ *
+ * @this {FP4}
+ */
zero: function() {
this.a.zero();
this.b.zero();
},
- /* this=1 */
+ /**
+ * Set FP4 to unity
+ *
+ * @this {FP4}
+ * @param x FP4 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
},
- /* set from two FP2s */
+ /**
+ * Set FP4 from two FP2 values
+ *
+ * @this {FP4}
+ * @param c FP2 instance
+ * @param d FP2 instance
+ */
set: function(c, d) {
this.a.copy(c);
this.b.copy(d);
},
- /* set a */
+ /**
+ * Set FP4 from one FP2 value
+ *
+ * @this {FP4}
+ * @param c FP2 instance
+ */
seta: function(c) {
this.a.copy(c);
this.b.zero();
},
- /* this=-this */
+ /**
+ * Negation of FP4
+ *
+ * @this {FP4}
+ */
neg: function() {
this.norm();
var m = new ctx.FP2(this.a),
@@ -135,25 +214,43 @@ var FP4 = function(ctx) {
this.norm();
},
- /* this=conjugate(this) */
+ /**
+ * Conjugation of FP4
+ *
+ * @this {FP4}
+ */
conj: function() {
this.b.neg();
this.norm();
},
- /* this=-conjugate(this) */
+ /**
+ * Negative conjugation of FP4
+ *
+ * @this {FP4}
+ */
nconj: function() {
this.a.neg();
this.norm();
},
- /* this+=x */
+ /**
+ * addition of two FP4s
+ *
+ * @this {FP4}
+ * @param x FP4 instance
+ */
add: function(x) {
this.a.add(x.a);
this.b.add(x.b);
},
- /* this-=x */
+ /**
+ * subtraction of two FP4s
+ *
+ * @this {FP4}
+ * @param x FP4 instance
+ */
sub: function(x) {
var m = new FP4(x);
m.neg();
@@ -165,19 +262,33 @@ var FP4 = function(ctx) {
this.add(x);
},
- /* this*=s where s is FP2 */
+ /**
+ * Multiplication of an FP4 by an FP8
+ *
+ * @this {FP4}
+ * @param s FP8 instance
+ */
pmul: function(s) {
this.a.mul(s);
this.b.mul(s);
},
- /* this*=c where s is int */
+ /**
+ * Multiplication of an FP4 by an integer
+ *
+ * @this {FP4}
+ * @param s integer multiplier
+ */
imul: function(c) {
this.a.imul(c);
this.b.imul(c);
},
- /* this*=this */
+ /**
+ * Fast Squaring of an FP4
+ *
+ * @this {FP4}
+ */
sqr: function() {
// this.norm();
@@ -211,7 +322,12 @@ var FP4 = function(ctx) {
this.norm();
},
- /* this*=y */
+ /**
+ * Full unconditional Multiplication of two FP4s
+ *
+ * @this {FP4}
+ * @param y FP4 instance, the multiplier
+ */
mul: function(y) {
// this.norm();
@@ -247,12 +363,20 @@ var FP4 = function(ctx) {
this.norm();
},
- /* convert to hex string */
+ /**
+ * convert to hex string
+ *
+ * @this {FP4}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "]");
},
- /* this=1/this */
+ /**
+ * Inverting an FP4
+ *
+ * @this {FP4}
+ */
inverse: function() {
this.norm();
@@ -271,7 +395,11 @@ var FP4 = function(ctx) {
this.b.mul(t1);
},
- /* this*=i where i = sqrt(-1+sqrt(-1)) */
+ /**
+ * multiplies an FP4 instance by irreducible polynomial
sqrt(1+sqrt(-1))
+ *
+ * @this {FP4}
+ */
times_i: function() {
var s = new ctx.FP2(this.b), //s.copy(this.b);
t = new ctx.FP2(this.b); //t.copy(this.b);
@@ -283,14 +411,24 @@ var FP4 = function(ctx) {
this.norm();
},
- /* this=this^q using Frobenius, where q is Modulus */
+ /**
+ * Raises an FP4 to the power of the internal modulus p, using the
Frobenius
+ *
+ * @this {FP4}
+ * @param f Modulus
+ */
frob: function(f) {
this.a.conj();
this.b.conj();
this.b.mul(f);
},
- /* this=this^e */
+ /**
+ * Raises an FP4 to the power of a BIG
+ *
+ * @this {FP4}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var w = new FP4(this),
z = new ctx.BIG(e),
@@ -317,7 +455,14 @@ var FP4 = function(ctx) {
return r;
},
- /* XTR xtr_a function */
+ /**
+ * Calculates the XTR addition function r=w*x-conj(x)*y+z
+ *
+ * @this {FP4}
+ * @param w FP4 instance
+ * @param y FP4 instance
+ * @param z FP4 instance
+ */
xtr_A: function(w, y, z) {
var r = new FP4(w),
t = new FP4(w);
@@ -338,7 +483,11 @@ var FP4 = function(ctx) {
this.reduce();
},
- /* XTR xtr_d function */
+ /**
+ * Calculates the XTR doubling function r=x^2-2*conj(x)
+ *
+ * @this {FP4}
+ */
xtr_D: function() {
var w = new FP4(this);
this.sqr();
@@ -348,7 +497,12 @@ var FP4 = function(ctx) {
this.reduce();
},
- /* r=x^n using XTR method on traces of FP12s */
+ /**
+ * Calculates FP4 trace of an FP4 raised to the power of a BIG number
+ *
+ * @this {FP4}
+ * @param n Big number
+ */
xtr_pow: function(n) {
var sf = new FP4(this);
sf.norm();
@@ -404,7 +558,11 @@ var FP4 = function(ctx) {
return r;
},
- /* r=ck^a.cl^n using XTR double exponentiation method on traces of
FP12s. See Stam thesis. */
+ /**
+ * Calculates FP4 trace of c^a.d^b, where c and d are derived from FP4
traces of FP4s
+ *
+ * @this {FP4}
+ */
xtr_pow2: function(ck, ckml, ckm2l, a, b) {
var e = new ctx.BIG(a),
@@ -554,11 +712,21 @@ var FP4 = function(ctx) {
/* New stuff for ecp4.js */
+ /**
+ * Divide an FP4 by 2
+ *
+ * @this {FP4}
+ */
div2: function() {
this.a.div2();
this.b.div2();
},
+ /**
+ * Divide FP4 number by QNR
+ *
+ * @this {FP4}
+ */
div_i: function() {
var u=new ctx.FP2(this.a),
v=new ctx.FP2(this.b);
@@ -567,6 +735,11 @@ var FP4 = function(ctx) {
this.b.copy(u);
},
+ /**
+ * Divide an FP4 by QNR/2
+ *
+ * @this {FP4}
+ */
div_2i: function() {
var u=new ctx.FP2(this.a),
v=new ctx.FP2(this.b);
@@ -576,11 +749,22 @@ var FP4 = function(ctx) {
this.b.copy(u);
},
+ /**
+ * Multiplication of an FP4 by an FP
+ *
+ * @this {FP4}
+ * @param s FP multiplier
+ */
qmul: function(s) {
this.a.pmul(s);
this.b.pmul(s);
},
+ /**
+ * Calculate square root of an FP4
+ *
+ * @this {FP4}
+ */
sqrt: function() {
if (this.iszilch()) {
return true;
diff --git a/src/fp8.js b/src/fp8.js
index 21aa7bd..6e9ec98 100644
--- a/src/fp8.js
+++ b/src/fp8.js
@@ -24,7 +24,14 @@
var FP8 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP8
+ *
+ * @constructor
+ * @this {FP4}
+ * @param c FP8 / FP4 instance
+ * @param d FP4 instance
+ */
var FP8 = function(c, d) {
if (c instanceof FP8) {
this.a = new ctx.FP4(c.a);
@@ -36,90 +43,164 @@ var FP8 = function(ctx) {
};
FP8.prototype = {
- /* reduce all components of this mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP8 mod Modulus
+ *
+ * @this {FP8}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
},
- /* normalise all components of this mod Modulus */
+ /**
+ * Normalises the components of an FP8
+ *
+ * @this {FP8}
+ */
norm: function() {
this.a.norm();
this.b.norm();
},
- /* test this==0 ? */
+ /**
+ * Tests for FP8 equal to zero
+ *
+ * @this {FP8}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch());
},
- /* test this==1 ? */
+ /**
+ * Tests for FP8 equal to unity
+ *
+ * @this {FP8}
+ */
isunity: function() {
var one = new ctx.FP4(1);
return (this.a.equals(one) && this.b.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP8 number
+ *
+ * @this {FP8}
+ * @param g FP8 instance
+ * @param d copy depends on this value
+ */
cmove: function(g, d) {
this.a.cmove(g.a, d);
this.b.cmove(g.b, d);
},
- /* test is w real? That is in a+ib test b is zero */
+ /**
+ * test is w real? That is in a+ib test b is zero
+ *
+ * @this {FP8}
+ */
isreal: function() {
return this.b.iszilch();
},
- /* extract real part a */
+ /**
+ * extract real part a
+ *
+ * @this {FP8}
+ */
real: function() {
return this.a;
},
+ /**
+ * extract a from this
+ *
+ * @this {FP8}
+ */
geta: function() {
return this.a;
},
- /* extract imaginary part b */
+ /**
+ * extract b from this
+ *
+ * @this {FP8}
+ */
getb: function() {
return this.b;
},
- /* test this=x? */
+ /**
+ * Tests for equality of two FP8s
+ *
+ * @this {FP8}
+ * @param x FP8 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b));
},
- /* copy this=x */
+ /**
+ * Copy FP8 to another FP8
+ *
+ * @this {FP8}
+ * @param x FP8 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
},
- /* this=0 */
+ /**
+ * Set FP8 to zero
+ *
+ * @this {FP8}
+ */
zero: function() {
this.a.zero();
this.b.zero();
},
- /* this=1 */
+ /**
+ * Set FP8 to unity
+ *
+ * @this {FP8}
+ * @param x FP8 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
},
- /* set from two FP4s */
+ /**
+ * Set FP8 from two FP4 values
+ *
+ * @this {FP8}
+ * @param c FP4 instance
+ * @param d FP4 instance
+ */
set: function(c, d) {
this.a.copy(c);
this.b.copy(d);
},
- /* set a */
+ /**
+ * Set FP8 from one FP4 value
+ *
+ * @this {FP8}
+ * @param c FP4 instance
+ */
seta: function(c) {
this.a.copy(c);
this.b.zero();
},
- /* this=-this */
+ /**
+ * Negation of FP8
+ *
+ * @this {FP8}
+ */
neg: function() {
this.norm();
var m = new ctx.FP4(this.a),
@@ -135,25 +216,43 @@ var FP8 = function(ctx) {
this.norm();
},
- /* this=conjugate(this) */
+ /**
+ * Conjugation of FP8
+ *
+ * @this {FP8}
+ */
conj: function() {
this.b.neg();
this.norm();
},
- /* this=-conjugate(this) */
+ /**
+ * Negative conjugation of FP8
+ *
+ * @this {FP8}
+ */
nconj: function() {
this.a.neg();
this.norm();
},
- /* this+=x */
+ /**
+ * addition of two FP8s
+ *
+ * @this {FP8}
+ * @param x FP8 instance
+ */
add: function(x) {
this.a.add(x.a);
this.b.add(x.b);
},
- /* this-=x */
+ /**
+ * subtraction of two FP8s
+ *
+ * @this {FP8}
+ * @param x FP8 instance
+ */
sub: function(x) {
var m = new FP8(x);
m.neg();
@@ -165,19 +264,33 @@ var FP8 = function(ctx) {
this.add(x);
},
- /* this*=s where s is FP4 */
+ /**
+ * Multiplication of an FP8 by an FP8
+ *
+ * @this {FP8}
+ * @param s FP8 instance
+ */
pmul: function(s) {
this.a.mul(s);
this.b.mul(s);
},
- /* this*=c where s is int */
+ /**
+ * Multiplication of an FP8 by a small integer
+ *
+ * @this {FP8}
+ * @param s integer
+ */
imul: function(c) {
this.a.imul(c);
this.b.imul(c);
},
- /* this*=this */
+ /**
+ * Fast Squaring of an FP8
+ *
+ * @this {FP8}
+ */
sqr: function() {
var t1 = new ctx.FP4(this.a),
t2 = new ctx.FP4(this.b),
@@ -208,7 +321,12 @@ var FP8 = function(ctx) {
this.norm();
},
- /* this*=y */
+ /**
+ * Full unconditional Multiplication of two FP8s
+ *
+ * @this {FP8}
+ * @param y FP8 instance, the multiplier
+ */
mul: function(y) {
var t1 = new ctx.FP4(this.a),
t2 = new ctx.FP4(this.b),
@@ -242,12 +360,20 @@ var FP8 = function(ctx) {
this.norm();
},
- /* convert to hex string */
+ /**
+ * convert to hex string
+ *
+ * @this {FP8}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "]");
},
- /* this=1/this */
+ /**
+ * Inverting an FP8
+ *
+ * @this {FP8}
+ */
inverse: function() {
this.norm();
@@ -266,7 +392,11 @@ var FP8 = function(ctx) {
this.b.mul(t1);
},
- /* this*=i where i = sqrt(-1+sqrt(-1)) */
+ /**
+ * multiplies an FP8 instance by irreducible polynomial
sqrt(1+sqrt(-1))
+ *
+ * @this {FP8}
+ */
times_i: function() {
var s = new ctx.FP4(this.b),
t = new ctx.FP4(this.a);
@@ -278,12 +408,22 @@ var FP8 = function(ctx) {
this.norm();
},
+ /**
+ * multiplies an FP8 instance by irreducible polynomial (1+sqrt(-1))
+ *
+ * @this {FP8}
+ */
times_i2: function() {
this.a.times_i();
this.b.times_i();
},
- /* this=this^q using Frobenius, where q is Modulus */
+ /**
+ * Raises an FP8 to the power of the internal modulus p, using the
Frobenius
+ *
+ * @this {FP8}
+ * @param f Modulus
+ */
frob: function(f) {
var ff=new ctx.FP2(f); ff.sqr(); ff.mul_ip(); ff.norm();
this.a.frob(ff);
@@ -292,7 +432,12 @@ var FP8 = function(ctx) {
this.b.times_i();
},
- /* this=this^e */
+ /**
+ * Raises an FP8 to the power of a BIG
+ *
+ * @this {FP8}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var w = new FP8(this),
z = new ctx.BIG(e),
@@ -319,7 +464,14 @@ var FP8 = function(ctx) {
return r;
},
- /* XTR xtr_a function */
+ /**
+ * Calculates the XTR addition function r=w*x-conj(x)*y+z
+ *
+ * @this {FP8}
+ * @param w FP8 instance
+ * @param y FP8 instance
+ * @param z FP8 instance
+ */
xtr_A: function(w, y, z) {
var r = new FP8(w),
t = new FP8(w);
@@ -339,7 +491,11 @@ var FP8 = function(ctx) {
this.reduce();
},
- /* XTR xtr_d function */
+ /**
+ * Calculates the XTR doubling function r=x^2-2*conj(x)
+ *
+ * @this {FP8}
+ */
xtr_D: function() {
var w = new FP8(this); //w.copy(this);
this.sqr();
@@ -349,7 +505,12 @@ var FP8 = function(ctx) {
this.reduce();
},
- /* r=x^n using XTR method on traces of FP12s */
+ /**
+ * Calculates FP8 trace of an FP8 raised to the power of a BIG number
+ *
+ * @this {FP8}
+ * @param n Big number
+ */
xtr_pow: function(n) {
var sf = new FP8(this);
sf.norm();
@@ -404,7 +565,11 @@ var FP8 = function(ctx) {
return r;
},
- /* r=ck^a.cl^n using XTR double exponentiation method on traces of
FP12s. See Stam thesis. */
+ /**
+ * Calculates FP8 trace of c^a.d^b, where c and d are derived from FP8
traces of FP8s
+ *
+ * @this {FP8}
+ */
xtr_pow2: function(ck, ckml, ckm2l, a, b) {
var e = new ctx.BIG(a),
@@ -554,11 +719,21 @@ var FP8 = function(ctx) {
/* New stuff for ecp4.js */
+ /**
+ * Divide an FP8 by 2
+ *
+ * @this {FP8}
+ */
div2: function() {
this.a.div2();
this.b.div2();
},
+ /**
+ * Divide FP8 number by QNR
+ *
+ * @this {FP8}
+ */
div_i: function() {
var u=new ctx.FP4(this.a),
v=new ctx.FP4(this.b);
@@ -567,11 +742,21 @@ var FP8 = function(ctx) {
this.b.copy(u);
},
+ /**
+ * Divide an FP8 by QNR twice
+ *
+ * @this {FP8}
+ */
div_i2: function() {
this.a.div_i();
this.b.div_i();
},
+ /**
+ * Divide an FP8 by QNR/2
+ *
+ * @this {FP8}
+ */
div_2i: function() {
var u=new ctx.FP4(this.a),
v=new ctx.FP4(this.b);
@@ -581,16 +766,33 @@ var FP8 = function(ctx) {
this.b.copy(u);
},
+ /**
+ * Multiplication of an FP8 by an FP2
+ *
+ * @this {FP8}
+ * @param s FP2 multiplier
+ */
qmul: function(s) {
this.a.pmul(s);
this.b.pmul(s);
},
+ /**
+ * Multiplication of an FP8 by an FP
+ *
+ * @this {FP8}
+ * @param s FP multiplier
+ */
tmul: function(s) {
this.a.qmul(s);
this.b.qmul(s);
},
+ /**
+ * Calculate square root of an FP8
+ *
+ * @this {FP8}
+ */
sqrt: function() {
if (this.iszilch()) {
return true;
