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 c744342 update js documentation
c744342 is described below
commit c74434243378dc096f4adec4e946ea6b6c334d00
Author: Kealan McCusker <[email protected]>
AuthorDate: Tue Jul 16 17:04:37 2019 +0100
update js documentation
---
src/pair.js | 117 ++++++++++++++++++++++++++++++++++++++++++++++++---------
src/pair192.js | 115 ++++++++++++++++++++++++++++++++++++++++++++++++--------
src/pair256.js | 117 ++++++++++++++++++++++++++++++++++++++++++++++++---------
src/rand.js | 40 +++++++++++++++++---
4 files changed, 334 insertions(+), 55 deletions(-)
diff --git a/src/pair.js b/src/pair.js
index bf009a7..3f58375 100644
--- a/src/pair.js
+++ b/src/pair.js
@@ -20,8 +20,19 @@
var PAIR = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of PAIR
+ *
+ * @constructor
+ * @this {PAIR}
+ */
var PAIR = {
- /* Line function */
+
+ /**
+ * Line function
+ *
+ * @this {PAIR}
+ */
line: function(A, B, Qx, Qy) {
var r = new ctx.FP12(1),
c = new ctx.FP4(0),
@@ -127,16 +138,26 @@ var PAIR = function(ctx) {
return r;
},
- /* prepare for multi-pairing */
- initmp: function() {
+ /**
+ * prepare for multi-pairing
+ *
+ * @this {PAIR}
+ */
+ initmp: function() {
var r=[];
for (var i=0;i<ctx.ECP.ATE_BITS;i++)
r[i] = new ctx.FP12(1);
return r;
},
- /* basic Miller loop */
- miller: function(r) {
+ /**
+ * basic Miller loop
+ *
+ * @this {PAIR}
+ * @param r FP12 precomputed array of accumulated line functions
+ * @param res FP12 result
+ */
+ miller: function(r) {
var res=new ctx.FP12(1);
for (var i=ctx.ECP.ATE_BITS-1; i>=1; i--)
{
@@ -151,8 +172,15 @@ var PAIR = function(ctx) {
return res;
},
- /* Accumulate another set of line functions for n-pairing */
- another: function(r,P1,Q1) {
+ /**
+ * Precompute line functions for n-pairing
+ *
+ * @this {PAIR}
+ * @param r array of precomputed FP48 products of line functions
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ */
+ another: function(r,P1,Q1) {
var f;
var n=new ctx.BIG(0);
@@ -229,7 +257,14 @@ var PAIR = function(ctx) {
}
},
- /* Optimal R-ate pairing */
+ /**
+ * Calculate Miller loop for Optimal ATE pairing e(P,Q)
+ *
+ * @this {PAIR}
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ * @result r An element of GT i.e. result of the pairing calculation
e(P,Q)
+ */
ate: function(P1, Q1) {
var fa, fb, f, x, n, n3, K, lv, lv2,
Qx, Qy, A, NP, r, nb, bt,
@@ -309,7 +344,16 @@ var PAIR = function(ctx) {
return r;
},
- /* Optimal R-ate double pairing e(P,Q).e(R,S) */
+ /**
+ * Calculate Miller loop for Optimal ATE double-pairing e(P,Q).e(R,S)
+ *
+ * @this {PAIR}
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ * @param R1 An element of G2
+ * @param S1 An element of G1
+ * @result r An element of GT i.e. result of the double pairing
calculation e(P,Q).e(R,S)
+ */
ate2: function(P1, Q1, R1, S1) {
var fa, fb, f, x, n, n3, K, lv, lv2,
Qx, Qy, Sx, Sy, A, B, NP,NR,r, nb, bt,
@@ -418,7 +462,13 @@ var PAIR = function(ctx) {
return r;
},
- /* final exponentiation - keep separate for multi-pairings and to
avoid thrashing stack */
+ /**
+ * Final exponentiation of pairing, converts output of Miller loop to
element in GT
+ *
+ * @this {PAIR}
+ * @param m FP12 value
+ * @result r m^((p^12-1)/r) where p is modulus and r is the group order
+ */
fexp: function(m) {
var fa, fb, f, x, r, lv,
x0, x1, x2, x3, x4, x5,
@@ -564,8 +614,12 @@ var PAIR = function(ctx) {
}
};
- /* prepare ate parameter, n=6u+2 (BN) or n=u (BLS), n3=3*n */
- PAIR.lbits = function(n3,n) {
+ /**
+ * prepare ate parameter, n=6u+2 (BN) or n=u (BLS), n3=3*n
+ *
+ * @this {PAIR}
+ */
+ PAIR.lbits = function(n3,n) {
n.rcopy(ctx.ROM_CURVE.CURVE_Bnx);
if (ctx.ECP.CURVE_PAIRING_TYPE==ctx.ECP.BN)
{
@@ -585,7 +639,11 @@ var PAIR = function(ctx) {
return n3.nbits();
};
- /* GLV method */
+ /**
+ * GLV method
+ *
+ * @this {PAIR}
+ */
PAIR.glv = function(e) {
var u = [],
t, q, v, d, x, x2, i, j;
@@ -631,7 +689,11 @@ var PAIR = function(ctx) {
return u;
};
- /* Galbraith & Scott Method */
+ /**
+ * Galbraith & Scott Method
+ *
+ * @this {PAIR}
+ */
PAIR.gs = function(e) {
var u = [],
i, j, t, q, v, d, x, w;
@@ -684,7 +746,14 @@ var PAIR = function(ctx) {
return u;
};
- /* Multiply P by e in group G1 */
+ /**
+ * Fast point multiplication of a member of the group G1 by a BIG number
+ *
+ * @this {PAIR}
+ * @param P Member of G1
+ * @param e BIG multiplier
+ * @return R Member of G1 R=e.P
+ */
PAIR.G1mul = function(P, e) {
var R, Q, q, bcru, cru, t, u, np, nn;
@@ -728,7 +797,14 @@ var PAIR = function(ctx) {
return R;
};
- /* Multiply P by e in group G2 */
+ /**
+ * Multiply P by e in group G2
+ *
+ * @this {PAIR}
+ * @param P Member of G2
+ * @param e BIG multiplier
+ * @return R Member of G2 R=e.P
+ */
PAIR.G2mul = function(P, e) {
var R, Q, fa, fb, f, q, u, t, i, np, nn;
@@ -778,7 +854,14 @@ var PAIR = function(ctx) {
return R;
};
- /* Note that this method requires a lot of RAM! Better to use compressed
XTR method, see ctx.FP4.js */
+ /**
+ * Fast raising of a member of GT to a BIG power
+ *
+ * @this {PAIR}
+ * @param d Member of GT
+ * @param e BIG exponent
+ * @return r d^e
+ */
PAIR.GTpow = function(d, e) {
var r, g, fa, fb, f, q, t, u, i, np, nn;
diff --git a/src/pair192.js b/src/pair192.js
index b01ced3..5108cd1 100644
--- a/src/pair192.js
+++ b/src/pair192.js
@@ -20,8 +20,19 @@
var PAIR192 = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of PAIR192
+ *
+ * @constructor
+ * @this {PAIR192}
+ */
var PAIR192 = {
- /* Line function */
+
+ /**
+ * Line function
+ *
+ * @this {PAIR192}
+ */
line: function(A, B, Qx, Qy) {
var r = new ctx.FP24(1),
XX, YY, ZZ, YZ, sb,
@@ -125,16 +136,26 @@ var PAIR192 = function(ctx) {
return r;
},
- /* prepare for multi-pairing */
- initmp: function() {
+ /**
+ * prepare for multi-pairing
+ *
+ * @this {PAIR192}
+ */
+ initmp: function() {
var r=[];
for (var i=0;i<ctx.ECP.ATE_BITS;i++)
r[i] = new ctx.FP24(1);
return r;
},
- /* basic Miller loop */
- miller: function(r) {
+ /**
+ * basic Miller loop
+ *
+ * @this {PAIR192}
+ * @param r FP24 precomputed array of accumulated line functions
+ * @param res FP24 result
+ */
+ miller: function(r) {
var res=new ctx.FP24(1);
for (var i=ctx.ECP.ATE_BITS-1; i>=1; i--)
{
@@ -149,8 +170,15 @@ var PAIR192 = function(ctx) {
return res;
},
- /* Accumulate another set of line functions for n-pairing */
- another: function(r,P1,Q1) {
+ /**
+ * Precompute line functions for n-pairing
+ *
+ * @this {PAIR192}
+ * @param r array of precomputed FP24 products of line functions
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ */
+ another: function(r,P1,Q1) {
var f;
var n=new ctx.BIG(0);
var n3=new ctx.BIG(0);
@@ -195,7 +223,14 @@ var PAIR192 = function(ctx) {
},
- /* Optimal R-ate pairing */
+ /**
+ * Calculate Miller loop for Optimal ATE pairing e(P,Q)
+ *
+ * @this {PAIR192}
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ * @result r An element of GT i.e. result of the pairing calculation
e(P,Q)
+ */
ate: function(P1, Q1) {
var x, n, n3, lv, lv2,
Qx, Qy, A, NP, r, nb, bt,
@@ -244,7 +279,16 @@ var PAIR192 = function(ctx) {
return r;
},
- /* Optimal R-ate double pairing e(P,Q).e(R,S) */
+ /**
+ * Calculate Miller loop for Optimal ATE double-pairing e(P,Q).e(R,S)
+ *
+ * @this {PAIR192}
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ * @param R1 An element of G2
+ * @param S1 An element of G1
+ * @result r An element of GT i.e. result of the double pairing
calculation e(P,Q).e(R,S)
+ */
ate2: function(P1, Q1, R1, S1) {
var x, n, n3, lv, lv2,
Qx, Qy, Sx, Sy, A, B, NP, NR, r, nb, bt,
@@ -311,7 +355,13 @@ var PAIR192 = function(ctx) {
return r;
},
- /* final exponentiation - keep separate for multi-pairings and to
avoid thrashing stack */
+ /**
+ * Final exponentiation of pairing, converts output of Miller loop to
element in GT
+ *
+ * @this {PAIR192}
+ * @param m FP24 value
+ * @result r m^((p^12-1)/r) where p is modulus and r is the group order
+ */
fexp: function(m) {
var fa, fb, f, x, r, lv,
t0,t1,t2,t3,t4,t5,t6,t7;
@@ -414,7 +464,11 @@ var PAIR192 = function(ctx) {
}
};
- /* prepare ate parameter, n=6u+2 (BN) or n=u (BLS), n3=3*n */
+ /**
+ * prepare ate parameter, n=6u+2 (BN) or n=u (BLS), n3=3*n
+ *
+ * @this {PAIR192}
+ */
PAIR192.lbits = function(n3,n) {
n.rcopy(ctx.ROM_CURVE.CURVE_Bnx);
n3.copy(n);
@@ -423,7 +477,11 @@ var PAIR192 = function(ctx) {
return n3.nbits();
};
- /* GLV method */
+ /**
+ * GLV method
+ *
+ * @this {PAIR192}
+ */
PAIR192.glv = function(e) {
var u = [],
q, x, x2;
@@ -444,7 +502,11 @@ var PAIR192 = function(ctx) {
return u;
};
- /* Galbraith & Scott Method */
+ /**
+ * Galbraith & Scott Method
+ *
+ * @this {PAIR192}
+ */
PAIR192.gs = function(e) {
var u = [],
i, q, x, w;
@@ -472,7 +534,14 @@ var PAIR192 = function(ctx) {
return u;
};
- /* Multiply P by e in group G1 */
+ /**
+ * Fast point multiplication of a member of the group G1 by a BIG number
+ *
+ * @this {PAIR192}
+ * @param P Member of G1
+ * @param e BIG multiplier
+ * @return R Member of G1 R=e.P
+ */
PAIR192.G1mul = function(P, e) {
var R, Q, q, bcru, cru, t, u, np, nn;
@@ -516,7 +585,14 @@ var PAIR192 = function(ctx) {
return R;
};
- /* Multiply P by e in group G2 */
+ /**
+ * Multiply P by e in group G2
+ *
+ * @this {PAIR192}
+ * @param P Member of G2
+ * @param e BIG multiplier
+ * @return R Member of G2 R=e.P
+ */
PAIR192.G2mul = function(P, e) {
var R, Q, F, q, u, t, i, np, nn;
@@ -558,7 +634,14 @@ var PAIR192 = function(ctx) {
return R;
};
- /* Note that this method requires a lot of RAM! Better to use compressed
XTR method, see ctx.FP4.js */
+ /**
+ * Fast raising of a member of GT to a BIG power
+ *
+ * @this {PAIR192}
+ * @param d Member of GT
+ * @param e BIG exponent
+ * @return r d^e
+ */
PAIR192.GTpow = function(d, e) {
var r, g, fa, fb, f, q, t, u, i, np, nn;
diff --git a/src/pair256.js b/src/pair256.js
index b48126f..d8dfc5a 100644
--- a/src/pair256.js
+++ b/src/pair256.js
@@ -20,8 +20,19 @@
var PAIR256 = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of PAIR256
+ *
+ * @constructor
+ * @this {PAIR256}
+ */
var PAIR256 = {
- /* Line function */
+
+ /**
+ * Line function
+ *
+ * @this {PAIR256}
+ */
line: function(A, B, Qx, Qy) {
var r = new ctx.FP48(1),
XX, YY, ZZ, YZ, sb,
@@ -125,16 +136,26 @@ var PAIR256 = function(ctx) {
return r;
},
- /* prepare for multi-pairing */
- initmp: function() {
+ /**
+ * prepare for multi-pairing
+ *
+ * @this {PAIR256}
+ */
+ initmp: function() {
var r=[];
for (var i=0;i<ctx.ECP.ATE_BITS;i++)
r[i] = new ctx.FP48(1);
return r;
},
- /* basic Miller loop */
- miller: function(r) {
+ /**
+ * basic Miller loop
+ *
+ * @this {PAIR256}
+ * @param r FP48 precomputed array of accumulated line functions
+ * @param res FP48 result
+ */
+ miller: function(r) {
var res=new ctx.FP48(1);
for (var i=ctx.ECP.ATE_BITS-1; i>=1; i--)
{
@@ -149,8 +170,15 @@ var PAIR256 = function(ctx) {
return res;
},
- /* Accumulate another set of line functions for n-pairing */
- another: function(r,P1,Q1) {
+ /**
+ * Precompute line functions for n-pairing
+ *
+ * @this {PAIR256}
+ * @param r array of precomputed FP48 products of line functions
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ */
+ another: function(r,P1,Q1) {
var f;
var n=new ctx.BIG(0);
var n3=new ctx.BIG(0);
@@ -195,7 +223,14 @@ var PAIR256 = function(ctx) {
},
- /* Optimal R-ate pairing */
+ /**
+ * Calculate Miller loop for Optimal ATE pairing e(P,Q)
+ *
+ * @this {PAIR256}
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ * @result r An element of GT i.e. result of the pairing calculation
e(P,Q)
+ */
ate: function(P1, Q1) {
var x, n, n3, lv, lv2,
Qx, Qy, A, NP, r, nb, bt,
@@ -244,7 +279,16 @@ var PAIR256 = function(ctx) {
return r;
},
- /* Optimal R-ate double pairing e(P,Q).e(R,S) */
+ /**
+ * Calculate Miller loop for Optimal ATE double-pairing e(P,Q).e(R,S)
+ *
+ * @this {PAIR256}
+ * @param P1 An element of G2
+ * @param Q1 An element of G1
+ * @param R1 An element of G2
+ * @param S1 An element of G1
+ * @result r An element of GT i.e. result of the double pairing
calculation e(P,Q).e(R,S)
+ */
ate2: function(P1, Q1, R1, S1) {
var x, n, n3, lv, lv2,
Qx, Qy, Sx, Sy, A, B, NP, NR, r, nb, bt,
@@ -311,7 +355,13 @@ var PAIR256 = function(ctx) {
return r;
},
- /* final exponentiation - keep separate for multi-pairings and to
avoid thrashing stack */
+ /**
+ * Final exponentiation of pairing, converts output of Miller loop to
element in GT
+ *
+ * @this {PAIR256}
+ * @param m FP48 value
+ * @result r m^((p^12-1)/r) where p is modulus and r is the group order
+ */
fexp: function(m) {
var fa, fb, f, x, r, lv,
t1,t2,t3,t7;
@@ -485,8 +535,12 @@ var PAIR256 = function(ctx) {
}
};
- /* prepare ate parameter, n=6u+2 (BN) or n=u (BLS), n3=3*n */
- PAIR256.lbits = function(n3,n) {
+ /**
+ * prepare ate parameter, n=6u+2 (BN) or n=u (BLS), n3=3*n
+ *
+ * @this {PAIR256}
+ */
+ PAIR256.lbits = function(n3,n) {
n.rcopy(ctx.ROM_CURVE.CURVE_Bnx);
n3.copy(n);
n3.pmul(3);
@@ -494,7 +548,11 @@ var PAIR256 = function(ctx) {
return n3.nbits();
};
- /* GLV method */
+ /**
+ * GLV method
+ *
+ * @this {PAIR256}
+ */
PAIR256.glv = function(e) {
var u = [],
q, x, x2;
@@ -516,7 +574,11 @@ var PAIR256 = function(ctx) {
return u;
};
- /* Galbraith & Scott Method */
+ /**
+ * Galbraith & Scott Method
+ *
+ * @this {PAIR256}
+ */
PAIR256.gs = function(e) {
var u = [],
i, q, x, w;
@@ -549,7 +611,14 @@ var PAIR256 = function(ctx) {
return u;
};
- /* Multiply P by e in group G1 */
+ /**
+ * Fast point multiplication of a member of the group G1 by a BIG number
+ *
+ * @this {PAIR256}
+ * @param P Member of G1
+ * @param e BIG multiplier
+ * @return R Member of G1 R=e.P
+ */
PAIR256.G1mul = function(P, e) {
var R, Q, q, bcru, cru, t, u, np, nn;
@@ -593,7 +662,14 @@ var PAIR256 = function(ctx) {
return R;
};
- /* Multiply P by e in group G2 */
+ /**
+ * Multiply P by e in group G2
+ *
+ * @this {PAIR256}
+ * @param P Member of G2
+ * @param e BIG multiplier
+ * @return R Member of G2 R=e.P
+ */
PAIR256.G2mul = function(P, e) {
var R, Q, F, q, u, t, i, np, nn;
@@ -635,7 +711,14 @@ var PAIR256 = function(ctx) {
return R;
};
- /* Note that this method requires a lot of RAM! Better to use compressed
XTR method, see ctx.FP4.js */
+ /**
+ * Fast raising of a member of GT to a BIG power
+ *
+ * @this {PAIR256}
+ * @param d Member of GT
+ * @param e BIG exponent
+ * @return r d^e
+ */
PAIR256.GTpow = function(d, e) {
var r, g, fa, fb, f, q, t, u, i, np, nn;
diff --git a/src/rand.js b/src/rand.js
index db110b0..17c73d0 100644
--- a/src/rand.js
+++ b/src/rand.js
@@ -31,6 +31,12 @@
var RAND = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of MPIN256
+ *
+ * @constructor
+ * @this {MPIN256}
+ */
var RAND = function() {
/* Cryptographically strong pseudo-random number generator */
this.ira = []; /* random number... */
@@ -46,7 +52,11 @@ var RAND = function(ctx) {
NJ: 6,
NV: 8,
- /* Terminate and clean up */
+ /**
+ * Delete all internal state of a random number generator
+ *
+ * @this {MPIN256}
+ */
clean: function() {
var i;
@@ -63,7 +73,12 @@ var RAND = function(ctx) {
this.pool_ptr = 0;
},
- sbrand: function() { /* Marsaglia & Zaman random number generator */
+ /**
+ * Marsaglia & Zaman random number generator
+ *
+ * @this {MPIN256}
+ */
+ sbrand: function() {
var i, k, pdiff, t;
this.rndptr++;
@@ -131,7 +146,13 @@ var RAND = function(ctx) {
this.pool_ptr = 0;
},
- /* Initialize RNG with some real entropy from some external source */
+ /**
+ * Initialize RNG with some real entropy from some external source
+ *
+ * @this {MPIN256}
+ * @param rawlen the number of seed bytes provided
+ * @param raw an array of seed bytes
+ */
seed: function(rawlen, raw) { /* initialise from at least 128 byte
string of raw random entropy */
var sh = new ctx.HASH256(),
digest = [],
@@ -164,7 +185,11 @@ var RAND = function(ctx) {
this.fill_pool();
},
- /* get random byte */
+ /**
+ * Get random byte
+ *
+ * @this {MPIN256}
+ */
getByte: function() {
var r = this.pool[this.pool_ptr++];
@@ -176,7 +201,12 @@ var RAND = function(ctx) {
}
};
- RAND.pack = function(b) { /* pack 4 bytes into a 32-bit Word */
+ /**
+ * Pack 4 bytes into a 32-bit Word
+ *
+ * @this {MPIN256}
+ */
+ RAND.pack = function(b) {
return (((b[3]) & 0xff) << 24) | ((b[2] & 0xff) << 16) | ((b[1] &
0xff) << 8) | (b[0] & 0xff);
};
