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 35f4fe0 updated js documentation
35f4fe0 is described below
commit 35f4fe0bd7d96bf494f4951531e213dd447f6561
Author: Kealan McCusker <[email protected]>
AuthorDate: Tue Jul 9 14:11:37 2019 +0100
updated js documentation
---
src/aes.js | 24 ++---
src/big.js | 2 +-
src/ecdh.js | 162 +++++++++++++++++++++++++++++--
src/ecp.js | 205 +++++++++++++++++++++++++++++++++------
src/ecp2.js | 180 ++++++++++++++++++++++++++++------
src/ecp4.js | 177 +++++++++++++++++++++++++++++-----
src/ecp8.js | 177 +++++++++++++++++++++++++++++-----
src/ff.js | 313 +++++++++++++++++++++++++++++++++++++++++++++++++++---------
src/fp12.js | 234 ++++++++++++++++++++++++++++++++++++++-------
src/fp16.js | 241 +++++++++++++++++++++++++++++++++++++++-------
src/fp2.js | 221 +++++++++++++++++++++++++++++++++++-------
src/fp24.js | 229 +++++++++++++++++++++++++++++++++++++-------
src/fp48.js | 228 ++++++++++++++++++++++++++++++++++++-------
13 files changed, 2044 insertions(+), 349 deletions(-)
diff --git a/src/aes.js b/src/aes.js
index 37b5e34..298fe2b 100644
--- a/src/aes.js
+++ b/src/aes.js
@@ -25,7 +25,7 @@ var AES = function() {
*
* @constructor
* @this {AES}
- */
+ */
var AES = function() {
this.Nk = 0;
this.Nr = 0;
@@ -58,8 +58,8 @@ var AES = function() {
* Reset AES mode or IV
*
* @this {AES}
- * @param {number} m The new active mode of operation (ECB, CBC, OFB,
CFB etc)
- * @param {string} iv The new Initialisation Vector
+ * @param m The new active mode of operation (ECB, CBC, OFB, CFB etc)
+ * @param iv The new Initialisation Vector
*/
reset: function(m, iv) { /* reset mode, or reset iv */
var i;
@@ -81,7 +81,7 @@ var AES = function() {
* Reset Extract chaining vector
*
* @this {AES}
- * @return {string} f the extracted chaining vector
+ * @return f the extracted chaining vector
*/
getreg: function() {
var ir = [],
@@ -110,10 +110,10 @@ var AES = function() {
* Initialise an instance of AES and its mode of operation
*
* @this {AES}
- * @parameter m is the active mode of operation (ECB, CBC, OFB, CFB
etc)
- * @parameter n is the key length in bytes, 16, 24 or 32
- * @parameter key the AES key as an array of 16 bytes
- * @parameter iv the Initialisation Vector
+ * @param m is the active mode of operation (ECB, CBC, OFB, CFB etc)
+ * @param n is the key length in bytes, 16, 24 or 32
+ * @param key the AES key as an array of 16 bytes
+ * @param iv the Initialisation Vector
*/
init: function(m, nk, key, iv) { /* Key=16 bytes */
/* Key Scheduler. Create expanded encryption key */
@@ -191,7 +191,7 @@ var AES = function() {
* Encrypt a single 16 byte block in ECB mode
*
* @this {AES}
- * @parameter {string} buff is an array of 16 plaintext bytes, on exit
becomes ciphertext
+ * @param {string} buff is an array of 16 plaintext bytes, on exit
becomes ciphertext
*/
ecb_encrypt: function(buff) {
var b = [],
@@ -270,7 +270,7 @@ var AES = function() {
* Decrypt a single 16 byte block in ECB mode
*
* @this {AES}
- * @parameter {string} buff is an array of 16 cipherext bytes, on exit
becomes plaintext
+ * @param buff is an array of 16 cipherext bytes, on exit becomes
plaintext
*/
ecb_decrypt: function(buff) {
var b = [],
@@ -348,7 +348,7 @@ var AES = function() {
* Encrypt using selected mode of operation
*
* @this {AES}
- * @parameter {string} buff is an array of 16 plaintext bytes, on exit
becomes ciphertext
+ * @param {string} buff is an array of 16 plaintext bytes, on exit
becomes ciphertext
*/
encrypt: function(buff) {
var st = [],
@@ -430,7 +430,7 @@ var AES = function() {
* Decrypt using selected mode of operation
*
* @this {AES}
- * @parameter {string} buff is an array of 16 cipherext bytes, on exit
becomes plaintext
+ * @param {string} buff is an array of 16 cipherext bytes, on exit
becomes plaintext
*/
decrypt: function(buff) {
var st = [],
diff --git a/src/big.js b/src/big.js
index fd95781..07226ed 100644
--- a/src/big.js
+++ b/src/big.js
@@ -672,7 +672,7 @@ BIG = function(ctx) {
},
/**
- * set x = x mod 2^m */
+ * set x = x mod 2^m
*
* @this {BIG}
* @parameter m Exponent
diff --git a/src/ecdh.js b/src/ecdh.js
index 8298e22..43a3b0b 100644
--- a/src/ecdh.js
+++ b/src/ecdh.js
@@ -37,7 +37,14 @@ var ECDH = function(ctx) {
SHA384: 48,
SHA512: 64,
- /* Convert Integer to n-byte array */
+ /**
+ * Convert Integer to n-byte array
+ *
+ * @this {ECDH}
+ * @parameter n integer
+ * @parameter len integer length
+ * @return byte array
+ */
inttobytes: function(n, len) {
var b = [],
i;
@@ -56,6 +63,13 @@ var ECDH = function(ctx) {
return b;
},
+ /**
+ * Convert byte array to string
+ *
+ * @this {ECDH}
+ * @parameter b byte array
+ * @return string
+ */
bytestostring: function(b) {
var s = "",
len = b.length,
@@ -70,6 +84,13 @@ var ECDH = function(ctx) {
return s;
},
+ /**
+ * Convert string to byte array
+ *
+ * @this {ECDH}
+ * @parameter s string
+ * @return byte array
+ */
stringtobytes: function(s) {
var b = [],
i;
@@ -81,6 +102,16 @@ var ECDH = function(ctx) {
return b;
},
+ /**
+ * general purpose hash function w=hash(B|n)
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter A byte array involved in the hash
+ * @parameter n integer involved in the hash
+ * @parameter pad padding
+ * @return w output
+ */
hashit: function(sha, A, n, B, pad) {
var R = [],
H, W, i, len;
@@ -130,6 +161,7 @@ var ECDH = function(ctx) {
return W;
},
+
KDF1: function(sha, Z, olen) {
/* NOTE: the parameter olen is the length of the output K in bytes
*/
var hlen = sha,
@@ -164,6 +196,16 @@ var ECDH = function(ctx) {
return K;
},
+ /**
+ * IEEE-1363 Key Derivation Function - generates key K from inputs Z
and P
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter Z input byte array
+ * @parameter P input key derivation parameters - can be NULL
+ * @parameter 0len is output desired length of key
+ * @return K derived key
+ */
KDF2: function(sha, Z, P, olen) {
/* NOTE: the parameter olen is the length of the output k in bytes
*/
var hlen = sha,
@@ -198,10 +240,17 @@ var ECDH = function(ctx) {
return K;
},
- /* Password based Key Derivation Function */
- /* Input password p, salt s, and repeat count */
- /* Output key of length olen */
-
+ /**
+ * Password Based Key Derivation Function - generates key K from
password, salt and repeat counter
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter Pass input password
+ * @parameter Salt salt value
+ * @parameter rep Number of times to be iterated.
+ * @parameter 0len is output desired length of key
+ * @return key derived key
+ */
PBKDF2: function(sha, Pass, Salt, rep, olen) {
var F = new Array(sha),
U = [],
@@ -255,6 +304,16 @@ var ECDH = function(ctx) {
return key;
},
+ /**
+ * HMAC of message M using key K to create tag of length tag.length
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter M input message
+ * @parameter K input encryption key
+ * @parameter tag is the output HMAC
+ * @return error code
+ */
HMAC: function(sha, M, K, tag) {
/* Input is from an octet m *
* olen is requested output length in bytes. k is the key *
@@ -309,8 +368,14 @@ var ECDH = function(ctx) {
return 1;
},
- /* ctx.AES encryption/decryption */
-
+ /**
+ * AES encrypts a plaintext to a ciphtertext
+ *
+ * @this {ECDH}
+ * @parameter M input message
+ * @parameter K AES key
+ * @return C Ciphertext
+ */
AES_CBC_IV0_ENCRYPT: function(K, M) { /* ctx.AES CBC encryption, with
Null IV and key K */
/* Input is from an octet string M, output is to an octet string C
*/
/* Input is padded as necessary to make up a full final block */
@@ -360,6 +425,14 @@ var ECDH = function(ctx) {
return C;
},
+ /**
+ * AES encrypts a plaintext to a ciphtertext
+ *
+ * @this {ECDH}
+ * @parameter C Ciphertext
+ * @parameter K AES key
+ * @return P Plaintext
+ */
AES_CBC_IV0_DECRYPT: function(K, C) { /* padding is removed */
var a = new ctx.AES(),
buff = [],
@@ -431,6 +504,15 @@ var ECDH = function(ctx) {
return M;
},
+ /**
+ * Generate an ECC public/private key pair
+ *
+ * @this {ECDH}
+ * @parameter rng Cryptographically Secure Random Number Generator
+ * @parameter S the private key
+ * @parameter W the output public key, which is s.G, where G is a
fixed generator
+ * @return 0 or an error code
+ */
KEY_PAIR_GENERATE: function(RNG, S, W) {
var res = 0,
r, s, G, WP;
@@ -456,6 +538,13 @@ var ECDH = function(ctx) {
return res;
},
+ /**
+ * Generate an ECC public/private key pair
+ *
+ * @this {ECDH}
+ * @parameter W the input public key to be validated
+ * @return 0 or an error code
+ */
PUBLIC_KEY_VALIDATE: function(W) {
var WP = ctx.ECP.fromBytes(W),
res = 0,
@@ -494,6 +583,15 @@ var ECDH = function(ctx) {
return res;
},
+ /**
+ * Generate Diffie-Hellman shared key
+ *
+ * @this {ECDH}
+ * @parameter S the private key
+ * @parameter W the output public key, which is s.G, where G is a
fixed generator
+ * @parameter K the output shared key, in fact the x-coordinate of s.W
+ * @return 0 or an error code
+ */
ECPSVDP_DH: function(S, WD, Z) {
var T = [],
res = 0,
@@ -526,6 +624,18 @@ var ECDH = function(ctx) {
return res;
},
+ /**
+ * ECDSA Signature
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter RNG Cryptographically Secure Random Number Generator
+ * @parameter S the private key
+ * @parameter F the input message to be signed
+ * @parameter C component of the output signature
+ * @parameter D component of the output signature
+ * @return 0 or an error code
+ */
ECPSP_DSA: function(sha, RNG, S, F, C, D) {
var T = [],
i, r, s, f, c, d, u, vx, w,
@@ -576,6 +686,17 @@ var ECDH = function(ctx) {
return 0;
},
+ /**
+ * ECDSA Signature Verification
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter W the public key
+ * @parameter F the input message to be signed
+ * @parameter C component of the output signature
+ * @parameter D component of the output signature
+ * @return 0 or an error code
+ */
ECPVP_DSA: function(sha, W, F, C, D) {
var B = [],
res = 0,
@@ -625,6 +746,20 @@ var ECDH = function(ctx) {
return res;
},
+ /**
+ * ECIES Encryption
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter P1 input Key Derivation parameters
+ * @parameter P2 input Encoding parameters
+ * @parameter RNG Cryptographically Secure Random Number Generator
+ * @parameter W the public key
+ * @parameter M the input message to be encrypted
+ * @parameter V component of the output ciphertext
+ * @parameter T the output HMAC tag, part of the ciphertext
+ * @return C ciphertext
+ */
ECIES_ENCRYPT: function(sha, P1, P2, RNG, W, M, V, T) {
var Z = [],
VZ = [],
@@ -687,6 +822,19 @@ var ECDH = function(ctx) {
return false;
},
+ /**
+ * ECIES Encryption
+ *
+ * @this {ECDH}
+ * @parameter sha is the hash type
+ * @parameter P1 input Key Derivation parameters
+ * @parameter P2 input Encoding parameters
+ * @parameter V component of the output ciphertext
+ * @parameter C Ciphertext
+ * @parameter T the output HMAC tag, part of the ciphertext
+ * @parameter U the private key
+ * @return M plaintext
+ */
ECIES_DECRYPT: function(sha, P1, P2, V, C, T, U) {
var Z = [],
VZ = [],
diff --git a/src/ecp.js b/src/ecp.js
index e6c078e..db556d2 100644
--- a/src/ecp.js
+++ b/src/ecp.js
@@ -22,7 +22,12 @@
var ECP = function(ctx) {
"use strict";
- /* Constructor */
+ /**
+ * Creates an instance of ECP
+ *
+ * @constructor
+ * @this {ECP}
+ */
var ECP = function(input) {
if (input instanceof ECP) {
// copy constructor
@@ -62,7 +67,13 @@ var ECP = function(ctx) {
ECP.AESKEY = ctx.config["@AK"];
ECP.prototype = {
- /* test this=O point-at-infinity */
+
+ /**
+ * Tests for ECP point equal to infinity
+ *
+ * @this {ECP}
+ * @param 1 if infinity, else returns 0
+ */
is_infinity: function() {
this.x.reduce();
@@ -83,7 +94,12 @@ var ECP = function(ctx) {
return true;
},
- /* conditional swap of this and Q dependant on d */
+
+ /**
+ * conditional swap of this and Q dependant on dCopy ECP point to
another ECP point
+ *
+ * @this {ECP}
+ */
cswap: function(Q, d) {
this.x.cswap(Q.x, d);
@@ -94,7 +110,11 @@ var ECP = function(ctx) {
},
- /* conditional move of Q to P dependant on d */
+ /**
+ * conditional move of Q to P dependant on d
+ *
+ * @this {ECP}
+ */
cmove: function(Q, d) {
this.x.cmove(Q.x, d);
@@ -105,7 +125,11 @@ var ECP = function(ctx) {
},
- /* Constant time select from pre-computed table */
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {ECP}
+ */
select: function(W, b) {
var MP = new ECP(),
m = b >> 31,
@@ -160,7 +184,12 @@ var ECP = function(ctx) {
return true;
},
- /* copy this=P */
+ /**
+ * Copy ECP point to another ECP point
+ *
+ * @this {ECP}
+ * @param P ECP instance
+ */
copy: function(P) {
this.x.copy(P.x);
if (ECP.CURVETYPE != ECP.MONTGOMERY) {
@@ -169,7 +198,11 @@ var ECP = function(ctx) {
this.z.copy(P.z);
},
- /* this=-this */
+ /**
+ * set this=-this
+ *
+ * @this {ECP}
+ */
neg: function() {
if (ECP.CURVETYPE == ECP.WEIERSTRASS) {
this.y.neg();
@@ -182,7 +215,11 @@ var ECP = function(ctx) {
return;
},
- /* set this=O */
+ /**
+ * Set ECP to point-at-infinity
+ *
+ * @this {ECP}
+ */
inf: function() {
this.x.zero();
@@ -197,7 +234,13 @@ var ECP = function(ctx) {
}
},
- /* set this=(x,y) where x and y are BIGs */
+ /**
+ * set this=(x,y)
+ *
+ * @this {ECP}
+ * @param ix x-value
+ * @param iy y-value
+ */
setxy: function(ix, iy) {
var rhs, y2;
@@ -226,7 +269,13 @@ var ECP = function(ctx) {
}
},
- /* set this=x, where x is ctx.BIG, y is derived from sign s */
+ /**
+ * set this=x, where x is ctx.BIG, y is derived from sign s
+ *
+ * @this {ECP}
+ * @param ix x-value
+ * @param s sign to derive y
+ */
setxi: function(ix, s) {
var rhs, ny;
@@ -247,7 +296,13 @@ var ECP = function(ctx) {
}
},
- /* set this=x, y calculated from curve equation */
+ /**
+ *
+ * set this=x, y calculated from curve equation
+ *
+ * @this {ECP}
+ * @param ix x-value
+ */
setx: function(ix) {
var rhs;
@@ -266,7 +321,11 @@ var ECP = function(ctx) {
}
},
- /* set this to affine - from (x,y,z) to (x,y) */
+ /**
+ * convert this to affine, from (x,y,z) to (x,y)
+ *
+ * @this {ECP}
+ */
affine: function() {
var one;
@@ -296,40 +355,69 @@ var ECP = function(ctx) {
}
},
- /* extract x as ctx.BIG */
+ /**
+ * extract affine x as ctx.FP2
+ *
+ * @this {ECP}
+ */
getX: function() {
var W=new ECP(); W.copy(this); W.affine();
return W.x.redc();
},
- /* extract y as ctx.BIG */
+ /**
+ * extract affine y as ctx.FP2
+ *
+ * @this {ECP}
+ */
getY: function() {
var W=new ECP(); W.copy(this); W.affine();
return W.y.redc();
},
- /* get sign of Y */
+ /**
+ * get sign of Y
+ *
+ * @this {ECP}
+ */
getS: function() {
var y = this.getY();
return y.parity();
},
- /* extract x as ctx.FP */
+ /**
+ * extract x as ctx.FP
+ *
+ * @this {ECP}
+ */
getx: function() {
return this.x;
},
- /* extract y as ctx.FP */
+ /**
+ * extract y as ctx.FP
+ *
+ * @this {ECP}
+ */
gety: function() {
return this.y;
},
- /* extract z as ctx.FP */
+ /**
+ * extract z as ctx.FP
+ *
+ * @this {ECP}
+ */
getz: function() {
return this.z;
},
- /* convert to byte array */
+ /**
+ * convert this to byte arrayextract projective x
+ *
+ * @this {ECP}
+ * @param b byte array output
+ */
toBytes: function(b,compress) {
var t = [],
i;
@@ -361,7 +449,13 @@ var ECP = function(ctx) {
b[i + ctx.BIG.MODBYTES + 1] = t[i];
}
},
- /* convert to hex string */
+
+ /**
+ * convert this to hex string
+ *
+ * @this {ECP}
+ * @return hex string
+ */
toString: function() {
var W=new ECP(); W.copy(this);
if (W.is_infinity()) {
@@ -377,7 +471,11 @@ var ECP = function(ctx) {
}
},
- /* this+=this */
+ /**
+ * this+=this
+ *
+ * @this {ECP}
+ */
dbl: function() {
var t0, t1, t2, t3, x3, y3, z3, b,
C, D, H, J,
@@ -600,7 +698,12 @@ var ECP = function(ctx) {
return;
},
- /* this+=Q */
+ /**
+ * Adds ECP instances
+ *
+ * param Q ECP instance
+ * @this {ECP}
+ */
add: function(Q) {
var b, t0, t1, t2, t3, t4, x3, y3, z3,
A, B, C, D, E, F, G;
@@ -936,14 +1039,25 @@ var ECP = function(ctx) {
// this.x.norm();
},
- /* this-=Q */
+ /**
+ * Subtracts ECP instance Q from this
+ *
+ * @this {ECP}
+ * @param Q ECP instance
+ */
sub: function(Q) {
var NQ = new ECP(); NQ.copy(Q);
NQ.neg();
this.add(NQ);
},
- /* constant time multiply by small integer of length bts - use ladder
*/
+ /**
+ * constant time multiply by small integer of length bts - use ladder
+ *
+ * @this {ECP}
+ * @param e small integer
+ * @param bts e bit length
+ */
pinmul: function(e, bts) {
var i, b, P, R0, R1;
@@ -972,7 +1086,11 @@ var ECP = function(ctx) {
}
},
- // multiply this by the curves cofactor
+ /**
+ * multiply this by the curves cofactor
+ *
+ * @this {ECP}
+ */
cfp: function() {
var cf=ctx.ROM_CURVE.CURVE_Cof_I,
c = new ctx.BIG(0);
@@ -992,7 +1110,12 @@ var ECP = function(ctx) {
},
- /* return e.this - SPA immune, using Ladder */
+ /**
+ * Multiplies an ECP instance P by a BIG, side-channel resistant
+ *
+ * @this {ECP}
+ * @param e BIG number multiplier
+ */
mul: function(e) {
var P, D, R0, R1, mt, t, Q, C, W, w,
i, b, nb, s, ns;
@@ -1086,8 +1209,14 @@ var ECP = function(ctx) {
return P;
},
- /* Return e.this+f.Q */
-
+ /**
+ * Return e.this+f.Q
+ *
+ * @this {ECP}
+ * @param e BIG number multiplier
+ * @param Q ECP instance
+ * @param f BIG number multiplier
+ */
mul2: function(e, Q, f) {
var te = new ctx.BIG(),
tf = new ctx.BIG(),
@@ -1190,7 +1319,11 @@ var ECP = function(ctx) {
}
};
- // set to group generator
+ /**
+ * Set group generator
+ *
+ * @this {ECP}
+ */
ECP.generator = function() {
var G=new ECP(),
gx = new ctx.BIG(0),
@@ -1214,7 +1347,12 @@ var ECP = function(ctx) {
return ((x >> 31) & 1);
};
- /* convert from byte array to ECP */
+ /**
+ * convert from byte array to point
+ *
+ * @this {ECP}
+ * @param b input byte array
+ */
ECP.fromBytes = function(b) {
var t = [],
P = new ECP(),
@@ -1261,7 +1399,12 @@ var ECP = function(ctx) {
return P;
};
- /* Calculate RHS of curve equation */
+ /**
+ * Calculate RHS of the curve equation
+ *
+ * @this {ECP}
+ * @param x x-value
+ */
ECP.RHS = function(x) {
var r = new ctx.FP(0),
b, cx, one, x3;
diff --git a/src/ecp2.js b/src/ecp2.js
index a813edd..98f2cf0 100644
--- a/src/ecp2.js
+++ b/src/ecp2.js
@@ -22,7 +22,12 @@
var ECP2 = function(ctx) {
"use strict";
- /* Constructor */
+ /**
+ * Creates an instance of ECP2
+ *
+ * @constructor
+ * @this {ECP2}
+ */
var ECP2 = function(input) {
if (input instanceof ECP2) {
// copy constructor
@@ -38,7 +43,13 @@ var ECP2 = function(ctx) {
};
ECP2.prototype = {
- /* Test this=O? */
+
+ /**
+ * Tests for ECP2 point equal to infinity
+ *
+ * @this {ECP2}
+ * @param 1 if infinity, else returns 0
+ */
is_infinity: function() {
this.x.reduce();
@@ -47,28 +58,45 @@ var ECP2 = function(ctx) {
return (this.x.iszilch() && this.z.iszilch());
},
- /* copy this=P */
+ /**
+ * Copy ECP2 point to another ECP2 point
+ *
+ * @this {ECP2}
+ * @param P ECP2 instance
+ */
copy: function(P) {
this.x.copy(P.x);
this.y.copy(P.y);
this.z.copy(P.z);
},
- /* set this=O */
+ /**
+ * Set ECP2 to point-at-infinity
+ *
+ * @this {ECP2}
+ */
inf: function() {
this.x.zero();
this.y.one();
this.z.zero();
},
- /* conditional move of Q to P dependant on d */
+ /**
+ * conditional move of Q to P dependant on d
+ *
+ * @this {ECP2}
+ */
cmove: function(Q, d) {
this.x.cmove(Q.x, d);
this.y.cmove(Q.y, d);
this.z.cmove(Q.z, d);
},
- /* Constant time select from pre-computed table */
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {ECP2}
+ */
select: function(W, b) {
var MP = new ECP2(),
m, babs;
@@ -91,7 +119,12 @@ var ECP2 = function(ctx) {
this.cmove(MP, (m & 1));
},
- /* Test P == Q */
+ /**
+ * Test P == Q
+ *
+ * @this {ECP2}
+ * @param Q ECP2 instance
+ */
equals: function(Q) {
var a, b;
@@ -123,7 +156,11 @@ var ECP2 = function(ctx) {
return true;
},
- /* set this=-this */
+ /**
+ * set this=-this
+ *
+ * @this {ECP2}
+ */
neg: function() {
this.y.norm();
this.y.neg();
@@ -131,7 +168,11 @@ var ECP2 = function(ctx) {
return;
},
- /* convert this to affine, from (x,y,z) to (x,y) */
+ /**
+ * convert this to affine, from (x,y,z) to (x,y)
+ *
+ * @this {ECP2}
+ */
affine: function() {
var one;
@@ -156,34 +197,60 @@ var ECP2 = function(ctx) {
this.z.copy(one);
},
- /* extract affine x as ctx.FP2 */
+ /**
+ * extract affine x as ctx.FP2
+ *
+ * @this {ECP2}
+ */
getX: function() {
var W=new ECP2(); W.copy(this); W.affine();
return W.x;
},
- /* extract affine y as ctx.FP2 */
+
+ /**
+ * extract affine y as ctx.FP2
+ *
+ * @this {ECP2}
+ */
getY: function() {
var W=new ECP2(); W.copy(this); W.affine();
return W.y;
},
- /* extract projective x */
+ /**
+ * extract projective x
+ *
+ * @this {ECP2}
+ */
getx: function() {
return this.x;
},
- /* extract projective y */
+ /**
+ * extract projective y
+ *
+ * @this {ECP2}
+ */
gety: function() {
return this.y;
},
- /* extract projective z */
+ /**
+ * extract projective z
+ *
+ * @this {ECP2}
+ */
getz: function() {
return this.z;
},
- /* convert this to byte array */
+ /**
+ * convert this to byte arrayextract projective x
+ *
+ * @this {ECP2}
+ * @param b byte array output
+ */
toBytes: function(b) {
var t = [],
i;
@@ -208,7 +275,12 @@ var ECP2 = function(ctx) {
}
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {ECP2}
+ * @return hex string
+ */
toString: function() {
var W=new ECP2(); W.copy(this);
if (W.is_infinity()) {
@@ -218,7 +290,14 @@ var ECP2 = function(ctx) {
return "(" + W.x.toString() + "," + W.y.toString() + ")";
},
- /* set this=(x,y) */
+
+ /**
+ * set this=(x,y)
+ *
+ * @this {ECP2}
+ * @param ix x-value
+ * @param iy y-value
+ */
setxy: function(ix, iy) {
var rhs, y2;
@@ -237,7 +316,12 @@ var ECP2 = function(ctx) {
}
},
- /* set this=(x,.) */
+ /**
+ * set this=(x,.)
+ *
+ * @this {ECP2}
+ * @param ix x-value
+ */
setx: function(ix) {
var rhs;
@@ -254,7 +338,11 @@ var ECP2 = function(ctx) {
}
},
- /* set this*=q, where q is Modulus, using Frobenius */
+ /**
+ * set this*=q, where q is Modulus, using Frobenius
+ *
+ * @this {ECP2}
+ */
frob: function(X) {
var X2;
@@ -269,7 +357,11 @@ var ECP2 = function(ctx) {
this.y.mul(X);
},
- /* this+=this */
+ /**
+ * this+=this
+ *
+ * @this {ECP2}
+ */
dbl: function() {
var iy, t0, t1, t2, x3, y3;
@@ -338,8 +430,12 @@ var ECP2 = function(ctx) {
return 1;
},
- /* this+=Q - return 0 for add, 1 for double, -1 for O */
- /* this+=Q */
+ /**
+ * Adds ECP2 instances
+ *
+ * param Q ECP2 instance
+ * @this {ECP2}
+ */
add: function(Q) {
var b, t0, t1, t2, t3, t4, x3, y3, z3;
@@ -455,7 +551,12 @@ var ECP2 = function(ctx) {
return 0;
},
- /* this-=Q */
+ /**
+ * Subtracts ECP instance Q from this
+ *
+ * @this {ECP2}
+ * @param Q ECP2 instance
+ */
sub: function(Q) {
var D;
var NQ=new ECP2(); NQ.copy(Q);
@@ -464,7 +565,12 @@ var ECP2 = function(ctx) {
return D;
},
- /* P*=e */
+ /**
+ * Multiplies an ECP2 instance P by a BIG, side-channel resistant
+ *
+ * @this {ECP2}
+ * @param e BIG number multiplier
+ */
mul: function(e) {
/* fixed size windows */
var mt = new ctx.BIG(),
@@ -532,7 +638,11 @@ var ECP2 = function(ctx) {
}
};
- // set to group generator
+ /**
+ * Set group generator
+ *
+ * @this {ECP2}
+ */
ECP2.generator = function() {
var G=new ECP2(),
A = new ctx.BIG(0),
@@ -551,7 +661,12 @@ var ECP2 = function(ctx) {
return G;
};
- /* convert from byte array to point */
+ /**
+ * convert from byte array to point
+ *
+ * @this {ECP2}
+ * @param b input byte array
+ */
ECP2.fromBytes = function(b) {
var t = [],
ra, rb, i, rx, ry, P;
@@ -584,7 +699,12 @@ var ECP2 = function(ctx) {
return P;
};
- /* Calculate RHS of curve equation x^3+B */
+ /**
+ * Calculate RHS of curve equation x^3+B
+ *
+ * @this {ECP2}
+ * @param x x-value
+ */
ECP2.RHS = function(x) {
var r, c, b;
@@ -617,6 +737,12 @@ var ECP2 = function(ctx) {
// Bos & Costello https://eprint.iacr.org/2013/458.pdf
// Faz-Hernandez & Longa & Sanchez https://eprint.iacr.org/2013/158.pdf
// Side channel attack secure
+
+ /**
+ * Calculate P=u0.Q0+u1*Q1+u2*Q2+u3*Q3
+ *
+ * @this {ECP2}
+ */
ECP2.mul4 = function(Q, u) {
var W = new ECP2(),
P = new ECP2(),
diff --git a/src/ecp4.js b/src/ecp4.js
index 9726b89..c11c520 100644
--- a/src/ecp4.js
+++ b/src/ecp4.js
@@ -22,7 +22,12 @@
var ECP4 = function(ctx) {
"use strict";
- /* Constructor */
+ /**
+ * Creates an instance of ECP4
+ *
+ * @constructor
+ * @this {ECP4}
+ */
var ECP4 = function(input) {
if (input instanceof ECP4) {
// copy constructor
@@ -38,7 +43,13 @@ var ECP4 = function(ctx) {
};
ECP4.prototype = {
- /* Test this=O? */
+
+ /**
+ * Tests for ECP4 point equal to infinity
+ *
+ * @this {ECP4}
+ * @param 1 if infinity, else returns 0
+ */
is_infinity: function() {
this.x.reduce();
this.y.reduce();
@@ -46,21 +57,34 @@ var ECP4 = function(ctx) {
return (this.x.iszilch() && this.z.iszilch());
},
- /* copy this=P */
+ /**
+ * Copy ECP4 point to another ECP4 point
+ *
+ * @this {ECP4}
+ * @param P ECP4 instance
+ */
copy: function(P) {
this.x.copy(P.x);
this.y.copy(P.y);
this.z.copy(P.z);
},
- /* set this=O */
+ /**
+ * conditional move of Q to P dependant on d
+ *
+ * @this {ECP4}
+ */
inf: function() {
this.x.zero();
this.y.one();
this.z.zero();
},
- /* conditional move of Q to P dependant on d */
+ /**
+ * conditional move of Q to P dependant on d
+ *
+ * @this {ECP4}
+ */
cmove: function(Q, d) {
this.x.cmove(Q.x, d);
this.y.cmove(Q.y, d);
@@ -68,7 +92,11 @@ var ECP4 = function(ctx) {
},
- /* Constant time select from pre-computed table */
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {ECP4}
+ */
select: function(W, b) {
var MP = new ECP4(),
m = b >> 31,
@@ -90,7 +118,12 @@ var ECP4 = function(ctx) {
this.cmove(MP, (m & 1));
},
- /* Test P == Q */
+ /**
+ * Test P == Q
+ *
+ * @this {ECP4}
+ * @param Q ECP4 instance
+ */
equals: function(Q) {
var a, b;
@@ -114,7 +147,11 @@ var ECP4 = function(ctx) {
return true;
},
- /* set this=-this */
+ /**
+ * set this=-this
+ *
+ * @this {ECP4}
+ */
neg: function() {
this.y.norm();
this.y.neg();
@@ -122,7 +159,11 @@ var ECP4 = function(ctx) {
return;
},
- /* convert this to affine, from (x,y,z) to (x,y) */
+ /**
+ * convert this to affine, from (x,y,z) to (x,y)
+ *
+ * @this {ECP4}
+ */
affine: function() {
var one;
@@ -147,34 +188,59 @@ var ECP4 = function(ctx) {
this.z.copy(one);
},
- /* extract affine x as ctx.FP4 */
+ /**
+ * extract affine x as ctx.FP2
+ *
+ * @this {ECP4}
+ */
getX: function() {
var W=new ECP4(); W.copy(this); W.affine();
return W.x;
},
- /* extract affine y as ctx.FP4 */
+ /**
+ * extract affine y as ctx.FP2
+ *
+ * @this {ECP4}
+ */
getY: function() {
var W=new ECP4(); W.copy(this); W.affine();
return W.y;
},
- /* extract projective x */
+ /**
+ * extract projective x
+ *
+ * @this {ECP4}
+ */
getx: function() {
return this.x;
},
- /* extract projective y */
+ /**
+ * extract projective y
+ *
+ * @this {ECP4}
+ */
gety: function() {
return this.y;
},
- /* extract projective z */
+ /**
+ * extract projective z
+ *
+ * @this {ECP4}
+ */
getz: function() {
return this.z;
},
- /* convert this to byte array */
+ /**
+ * convert this to byte arrayextract projective x
+ *
+ * @this {ECP4}
+ * @param b byte array output
+ */
toBytes: function(b) {
var t = [],
i;
@@ -216,7 +282,12 @@ var ECP4 = function(ctx) {
}
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {ECP4}
+ * @return hex string
+ */
toString: function() {
var W=new ECP4(); W.copy(this);
if (W.is_infinity()) {
@@ -226,7 +297,13 @@ var ECP4 = function(ctx) {
return "(" + W.x.toString() + "," + W.y.toString() + ")";
},
- /* set this=(x,y) */
+ /**
+ * set this=(x,y)
+ *
+ * @this {ECP4}
+ * @param ix x-value
+ * @param iy y-value
+ */
setxy: function(ix, iy) {
var rhs, y2;
@@ -246,7 +323,12 @@ var ECP4 = function(ctx) {
},
- /* set this=(x,.) */
+ /**
+ * set this=(x,.)
+ *
+ * @this {ECP4}
+ * @param ix x-value
+ */
setx: function(ix) {
var rhs;
@@ -262,7 +344,11 @@ var ECP4 = function(ctx) {
}
},
- /* set this*=q, where q is Modulus, using Frobenius */
+ /**
+ * set this*=q, where q is Modulus, using Frobenius
+ *
+ * @this {ECP4}
+ */
frob: function(F,n) {
for (var i=0;i<n;i++) {
this.x.frob(F[2]);
@@ -276,7 +362,11 @@ var ECP4 = function(ctx) {
}
},
- /* this+=this */
+ /**
+ * this+=this
+ *
+ * @this {ECP4}
+ */
dbl: function() {
var iy, t0, t1, t2, x3, y3;
@@ -338,7 +428,12 @@ var ECP4 = function(ctx) {
return 1;
},
- /* this+=Q */
+ /**
+ * Adds ECP4 instances
+ *
+ * param Q ECP4 instance
+ * @this {ECP4}
+ */
add: function(Q) {
var b, t0, t1, t2, t3, t4, x3, y3, z3;
@@ -441,7 +536,12 @@ var ECP4 = function(ctx) {
return 0;
},
- /* this-=Q */
+ /**
+ * Subtracts ECP instance Q from this
+ *
+ * @this {ECP4}
+ * @param Q ECP4 instance
+ */
sub: function(Q) {
var D;
var NQ=new ECP4(); NQ.copy(Q);
@@ -450,7 +550,12 @@ var ECP4 = function(ctx) {
return D;
},
- /* P*=e */
+ /**
+ * Multiplies an ECP4 instance P by a BIG, side-channel resistant
+ *
+ * @this {ECP4}
+ * @param e BIG number multiplier
+ */
mul: function(e) {
/* fixed size windows */
var mt = new ctx.BIG(),
@@ -518,7 +623,11 @@ var ECP4 = function(ctx) {
}
};
- // set to group generator
+ /**
+ * Set group generator
+ *
+ * @this {ECP4}
+ */
ECP4.generator = function() {
var G=new ECP4(),
A = new ctx.BIG(0),
@@ -550,7 +659,12 @@ var ECP4 = function(ctx) {
return G;
};
- /* convert from byte array to point */
+ /**
+ * convert from byte array to point
+ *
+ * @this {ECP4}
+ * @param b input byte array
+ */
ECP4.fromBytes = function(b) {
var t = [],
ra, rb, ra4, rb4, i, rx, ry, P;
@@ -606,7 +720,12 @@ var ECP4 = function(ctx) {
return P;
};
- /* Calculate RHS of curve equation x^3+B */
+ /**
+ * Calculate RHS of curve equation x^3+B
+ *
+ * @this {ECP4}
+ * @param x x-value
+ */
ECP4.RHS = function(x) {
var r, c, b;
@@ -636,6 +755,12 @@ var ECP4 = function(ctx) {
// Bos & Costello https://eprint.iacr.org/2013/458.pdf
// Faz-Hernandez & Longa & Sanchez https://eprint.iacr.org/2013/158.pdf
// Side channel attack secure
+
+ /**
+ * Calculate P=u0.Q0+u1*Q1+u2*Q2+u3*Q3...
+ *
+ * @this {ECP4}
+ */
ECP4.mul8 = function(Q, u) {
var W = new ECP4(),
P = new ECP4(),
diff --git a/src/ecp8.js b/src/ecp8.js
index 644f27f..b67cd43 100644
--- a/src/ecp8.js
+++ b/src/ecp8.js
@@ -22,7 +22,12 @@
var ECP8 = function(ctx) {
"use strict";
- /* Constructor */
+ /**
+ * Creates an instance of ECP8
+ *
+ * @constructor
+ * @this {ECP8}
+ */
var ECP8 = function(input) {
if (input instanceof ECP8) {
// copy constructor
@@ -38,7 +43,13 @@ var ECP8 = function(ctx) {
};
ECP8.prototype = {
- /* Test this=O? */
+
+ /**
+ * Tests for ECP8 point equal to infinity
+ *
+ * @this {ECP8}
+ * @param 1 if infinity, else returns 0
+ */
is_infinity: function() {
this.x.reduce();
@@ -47,28 +58,45 @@ var ECP8 = function(ctx) {
return (this.x.iszilch() && this.z.iszilch());
},
- /* copy this=P */
+ /**
+ * Copy ECP8 point to another ECP8 point
+ *
+ * @this {ECP8}
+ * @param P ECP8 instance
+ */
copy: function(P) {
this.x.copy(P.x);
this.y.copy(P.y);
this.z.copy(P.z);
},
- /* set this=O */
+ /**
+ * Set ECP8 to point-at-infinity
+ *
+ * @this {ECP8}
+ */
inf: function() {
this.x.zero();
this.y.one();
this.z.zero();
},
- /* conditional move of Q to P dependant on d */
+ /**
+ * conditional move of Q to P dependant on d
+ *
+ * @this {ECP8}
+ */
cmove: function(Q, d) {
this.x.cmove(Q.x, d);
this.y.cmove(Q.y, d);
this.z.cmove(Q.z, d);
},
- /* Constant time select from pre-computed table */
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {ECP8}
+ */
select: function(W, b) {
var MP = new ECP8(),
m = b >> 31,
@@ -90,7 +118,12 @@ var ECP8 = function(ctx) {
this.cmove(MP, (m & 1));
},
- /* Test P == Q */
+ /**
+ * Test P == Q
+ *
+ * @this {ECP8}
+ * @param Q ECP8 instance
+ */
equals: function(Q) {
var a, b;
@@ -114,7 +147,11 @@ var ECP8 = function(ctx) {
return true;
},
- /* set this=-this */
+ /**
+ * set this=-this
+ *
+ * @this {ECP8}
+ */
neg: function() {
this.y.norm();
this.y.neg();
@@ -122,7 +159,11 @@ var ECP8 = function(ctx) {
return;
},
- /* convert this to affine, from (x,y,z) to (x,y) */
+ /**
+ * convert this to affine, from (x,y,z) to (x,y)
+ *
+ * @this {ECP8}
+ */
affine: function() {
var one;
@@ -146,34 +187,59 @@ var ECP8 = function(ctx) {
this.z.copy(one);
},
- /* extract affine x as ctx.FP8 */
+ /**
+ * extract affine x as ctx.FP2
+ *
+ * @this {ECP8}
+ */
getX: function() {
var W=new ECP8(); W.copy(this); W.affine();
return W.x;
},
- /* extract affine y as ctx.FP8 */
+ /**
+ * extract affine y as ctx.FP2
+ *
+ * @this {ECP8}
+ */
getY: function() {
var W=new ECP8(); W.copy(this); W.affine();
return W.y;
},
- /* extract projective x */
+ /**
+ * extract projective x
+ *
+ * @this {ECP8}
+ */
getx: function() {
return this.x;
},
- /* extract projective y */
+ /**
+ * extract projective y
+ *
+ * @this {ECP8}
+ */
gety: function() {
return this.y;
},
- /* extract projective z */
+ /**
+ * extract projective z
+ *
+ * @this {ECP8}
+ */
getz: function() {
return this.z;
},
- /* convert this to byte array */
+ /**
+ * convert this to byte arrayextract projective x
+ *
+ * @this {ECP8}
+ * @param b byte array output
+ */
toBytes: function(b) {
var t = [],
i;
@@ -248,7 +314,12 @@ var ECP8 = function(ctx) {
}
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {ECP8}
+ * @return hex string
+ */
toString: function() {
var W=new ECP8(); W.copy(this);
if (W.is_infinity()) {
@@ -258,7 +329,13 @@ var ECP8 = function(ctx) {
return "(" + W.x.toString() + "," + W.y.toString() + ")";
},
- /* set this=(x,y) */
+ /**
+ * set this=(x,y)
+ *
+ * @this {ECP8}
+ * @param ix x-value
+ * @param iy y-value
+ */
setxy: function(ix, iy) {
var rhs, y2;
@@ -277,7 +354,12 @@ var ECP8 = function(ctx) {
}
},
- /* set this=(x,.) */
+ /**
+ * set this=(x,.)
+ *
+ * @this {ECP8}
+ * @param ix x-value
+ */
setx: function(ix) {
var rhs;
@@ -293,7 +375,11 @@ var ECP8 = function(ctx) {
}
},
- /* set this*=q, where q is Modulus, using Frobenius */
+ /**
+ * set this*=q, where q is Modulus, using Frobenius
+ *
+ * @this {ECP8}
+ */
frob: function(F,n) {
for (var i=0;i<n;i++) {
this.x.frob(F[2]);
@@ -318,7 +404,11 @@ var ECP8 = function(ctx) {
}
},
- /* this+=this */
+ /**
+ * this+=this
+ *
+ * @this {ECP8}
+ */
dbl: function() {
var iy, t0, t1, t2, x3, y3;
@@ -380,7 +470,12 @@ var ECP8 = function(ctx) {
return 1;
},
- /* this+=Q */
+ /**
+ * Adds ECP8 instances
+ *
+ * param Q ECP8 instance
+ * @this {ECP8}
+ */
add: function(Q) {
var b, t0, t1, t2, t3, t4, x3, y3, z3;
@@ -483,7 +578,12 @@ var ECP8 = function(ctx) {
return 0;
},
- /* this-=Q */
+ /**
+ * Subtracts ECP instance Q from this
+ *
+ * @this {ECP8}
+ * @param Q ECP8 instance
+ */
sub: function(Q) {
var D;
var NQ=new ECP8(); NQ.copy(Q);
@@ -492,7 +592,12 @@ var ECP8 = function(ctx) {
return D;
},
- /* P*=e */
+ /**
+ * Multiplies an ECP8 instance P by a BIG, side-channel resistant
+ *
+ * @this {ECP8}
+ * @param e BIG number multiplier
+ */
mul: function(e) {
/* fixed size windows */
var mt = new ctx.BIG(),
@@ -560,7 +665,11 @@ var ECP8 = function(ctx) {
}
};
- // set to group generator
+ /**
+ * Set group generator
+ *
+ * @this {ECP8}
+ */
ECP8.generator = function() {
var G=new ECP8(),
A = new ctx.BIG(0),
@@ -618,7 +727,12 @@ var ECP8 = function(ctx) {
return G;
};
- /* convert from byte array to point */
+ /**
+ * convert from byte array to point
+ *
+ * @this {ECP8}
+ * @param b input byte array
+ */
ECP8.fromBytes = function(b) {
var t = [],
ra, rb, ra4, rb4, ra8, rb8, i, rx, ry, P;
@@ -722,7 +836,12 @@ var ECP8 = function(ctx) {
return P;
};
- /* Calculate RHS of curve equation x^3+B */
+ /**
+ * Calculate RHS of curve equation x^3+B
+ *
+ * @this {ECP8}
+ * @param x x-value
+ */
ECP8.RHS = function(x) {
var r, c, b;
@@ -752,6 +871,12 @@ var ECP8 = function(ctx) {
// Bos & Costello https://eprint.iacr.org/2013/458.pdf
// Faz-Hernandez & Longa & Sanchez https://eprint.iacr.org/2013/158.pdf
// Side channel attack secure
+
+ /**
+ * Calculate P=u0.Q0+u1*Q1+u2*Q2+u3*Q3...
+ *
+ * @this {ECP8}
+ */
ECP8.mul16 = function(Q, u) {
var W = new ECP8(),
P = new ECP8(),
diff --git a/src/ff.js b/src/ff.js
index 8bcd3c4..23b7e8c 100644
--- a/src/ff.js
+++ b/src/ff.js
@@ -22,7 +22,12 @@
var FF = function(ctx) {
"use strict";
- /* General purpose Constructor */
+ /**
+ * Creates an instance of FF.
+ *
+ * @constructor
+ * @this {FF}
+ */
var FF = function(n) {
this.v = new Array(n);
this.length = n;
@@ -58,32 +63,59 @@ var FF = function(ctx) {
return this.length;
},
- /* set to integer */
+ /**
+ * set to integer
+ *
+ * @this {FF}
+ * @param m Integer value to be set to
+ */
set: function(m) {
this.zero();
this.v[0].set(0, (m & ctx.BIG.BMASK));
this.v[0].set(1, (m >> ctx.BIG.BASEBITS));
},
- /* copy from FF b */
+
+ /**
+ * copy from FF b
+ *
+ * @this {FF}
+ * @param b FF element to copy from
+ */
copy: function(b) {
for (var i = 0; i < this.length; i++) {
this.v[i].copy(b.v[i]);
}
},
- /* copy from FF b */
+
+ /**
+ * copy from FF b
+ *
+ * @this {FF}
+ * @param b FF element to copy from
+ */
rcopy: function(b) {
for (var i = 0; i < this.length; i++) {
this.v[i].rcopy(b[i]);
}
},
- /* x=y<<n */
+
+ /**
+ * x=y<<n
+ *
+ * @this {FF}
+ */
dsucopy: function(b) {
for (var i = 0; i < b.length; i++) {
this.v[b.length + i].copy(b.v[i]);
this.v[i].zero();
}
},
- /* x=y */
+
+ /**
+ * x=y
+ *
+ * @this {FF}
+ */
dscopy: function(b) {
for (var i = 0; i < b.length; i++) {
this.v[i].copy(b.v[i]);
@@ -91,19 +123,29 @@ var FF = function(ctx) {
}
},
- /* x=y>>n */
+ /**
+ * x=y>>n
+ *
+ * @this {FF}
+ */
sducopy: function(b) {
for (var i = 0; i < this.length; i++) {
this.v[i].copy(b.v[this.length + i]);
}
},
+
one: function() {
this.v[0].one();
for (var i = 1; i < this.length; i++) {
this.v[i].zero();
}
},
- /* test equals 0 */
+
+ /**
+ * test equals 0
+ *
+ * @this {FF}
+ */
iszilch: function() {
for (var i = 0; i < this.length; i++) {
if (!this.v[i].iszilch()) {
@@ -113,7 +155,12 @@ var FF = function(ctx) {
return true;
},
- /* shift right by BIGBITS-bit words */
+
+ /**
+ * shift right by BIGBITS-bit words
+ *
+ * @this {FF}
+ */
shrw: function(n) {
for (var i = 0; i < n; i++) {
this.v[i].copy(this.v[i + n]);
@@ -121,14 +168,23 @@ var FF = function(ctx) {
}
},
- /* shift left by BIGBITS-bit words */
+ /**
+ * shift left by BIGBITS-bit words
+ *
+ * @this {FF}
+ */
shlw: function(n) {
for (var i = 0; i < n; i++) {
this.v[n + i].copy(this.v[i]);
this.v[i].zero();
}
},
- /* extract last bit */
+
+ /**
+ * extract last bit
+ *
+ * @this {FF}
+ */
parity: function() {
return this.v[0].parity();
},
@@ -137,7 +193,11 @@ var FF = function(ctx) {
return this.v[0].lastbits(m);
},
- /* recursive add */
+ /**
+ * recursive add
+ *
+ * @this {FF}
+ */
radd: function(vp, x, xp, y, yp, n) {
for (var i = 0; i < n; i++) {
this.v[vp + i].copy(x.v[xp + i]);
@@ -145,14 +205,22 @@ var FF = function(ctx) {
}
},
- /* recursive inc */
+ /**
+ * recursive inc
+ *
+ * @this {FF}
+ */
rinc: function(vp, y, yp, n) {
for (var i = 0; i < n; i++) {
this.v[vp + i].add(y.v[yp + i]);
}
},
- /* recursive sub */
+ /**
+ * recursive sub
+ *
+ * @this {FF}
+ */
rsub: function(vp, x, xp, y, yp, n) {
for (var i = 0; i < n; i++) {
this.v[vp + i].copy(x.v[xp + i]);
@@ -160,35 +228,55 @@ var FF = function(ctx) {
}
},
- /* recursive dec */
+ /**
+ * recursive dec
+ *
+ * @this {FF}
+ */
rdec: function(vp, y, yp, n) {
for (var i = 0; i < n; i++) {
this.v[vp + i].sub(y.v[yp + i]);
}
},
- /* simple add */
+ /**
+ * simple add
+ *
+ * @this {FF}
+ */
add: function(b) {
for (var i = 0; i < this.length; i++) {
this.v[i].add(b.v[i]);
}
},
- /* simple sub */
+ /**
+ * simple sub
+ *
+ * @this {FF}
+ */
sub: function(b) {
for (var i = 0; i < this.length; i++) {
this.v[i].sub(b.v[i]);
}
},
- /* reverse sub */
+ /**
+ * reverse sub
+ *
+ * @this {FF}
+ */
revsub: function(b) {
for (var i = 0; i < this.length; i++) {
this.v[i].rsub(b.v[i]);
}
},
- /* increment/decrement by a small integer */
+ /**
+ * increment/decrement by a small integer
+ *
+ * @this {FF}
+ */
inc: function(m) {
this.v[0].inc(m);
this.norm();
@@ -199,7 +287,11 @@ var FF = function(ctx) {
this.norm();
},
- /* normalise - but hold any overflow in top part unless n<0 */
+ /**
+ * normalise - but hold any overflow in top part unless n<0
+ *
+ * @this {FF}
+ */
rnorm: function(vp, n) {
var trunc = false,
i, carry;
@@ -227,7 +319,11 @@ var FF = function(ctx) {
this.rnorm(0, this.length);
},
- /* shift left by one bit */
+ /**
+ * shift left by one bit
+ *
+ * @this {FF}
+ */
shl: function() {
var delay_carry = 0,
i, carry;
@@ -243,7 +339,11 @@ var FF = function(ctx) {
this.v[this.length - 1].inc(delay_carry);
},
- /* shift right by one bit */
+ /**
+ * shift right by one bit
+ *
+ * @this {FF}
+ */
shr: function() {
var i, carry;
@@ -255,7 +355,11 @@ var FF = function(ctx) {
this.v[0].fshr(1);
},
- /* Convert to Hex String */
+ /**
+ * Convert to Hex String
+ *
+ * @this {FF}
+ */
toString: function() {
var s = "",
i;
@@ -268,7 +372,12 @@ var FF = function(ctx) {
return s;
},
- /* Convert FFs to/from byte arrays */
+
+ /**
+ * Convert FFs to/from byte arrays
+ *
+ * @this {FF}
+ */
toBytes: function(b) {
var i;
@@ -277,7 +386,11 @@ var FF = function(ctx) {
}
},
- /* z=x*y, t is workspace */
+ /**
+ * z=x*y, t is workspace
+ *
+ * @this {FF}
+ */
karmul: function(vp, x, xp, y, yp, t, tp, n) {
var nd2, d;
@@ -368,7 +481,11 @@ var FF = function(ctx) {
this.rnorm(nd2, n);
},
- /* return low part of product this*y */
+ /**
+ * return low part of product this*y
+ *
+ * @this {FF}
+ */
lmul: function(y) {
var n = this.length,
t = new FF(2 * n),
@@ -378,7 +495,11 @@ var FF = function(ctx) {
this.karmul_lower(0, x, 0, y, 0, t, 0, n);
},
- /* Set b=b mod c */
+ /**
+ * Set b=b mod c
+ *
+ * @this {FF}
+ */
mod: function(c) {
var k = 0;
@@ -404,7 +525,14 @@ var FF = function(ctx) {
}
},
- /* return This mod modulus, N is modulus, ND is Montgomery Constant */
+ /**
+ * return this mod modulus
+ *
+ * @this {FF}
+ * @param N Mmodulus
+ * @param ND Montgomery Constant
+ * @return this mod N
+ */
reduce: function(N, ND) { /* fast karatsuba Montgomery reduction */
var n = N.length,
t = new FF(2 * n),
@@ -426,6 +554,14 @@ var FF = function(ctx) {
/* Set r=this mod b */
/* this is of length - 2*n */
/* r,b is of length - n */
+
+ /**
+ * Reduces a double-length FF with respect to a given modulus
+ *
+ * @this {FF}
+ * @param b Mmodulus
+ * @return this mod N
+ */
dmod: function(b) {
var n = b.length,
m = new FF(2 * n),
@@ -460,7 +596,11 @@ var FF = function(ctx) {
return r;
},
- /* Set return=1/this mod p. Binary method - a<p on entry */
+ /**
+ * Set return=1/this mod p. Binary method - a<p on entry
+ *
+ * @this {FF}
+ */
invmodp: function(p) {
var n = p.length,
u = new FF(n),
@@ -532,7 +672,11 @@ var FF = function(ctx) {
}
},
- /* nresidue mod m */
+ /**
+ * nresidue mod m
+ *
+ * @this {FF}
+ */
nres: function(m) {
var n = m.length,
d;
@@ -572,7 +716,11 @@ var FF = function(ctx) {
}
},
- /* U=1/a mod 2^m - Arazi & Qi */
+ /**
+ * U=1/a mod 2^m - Arazi & Qi
+ *
+ * @this {FF}
+ */
invmod2m: function() {
var n = this.length,
b = new FF(n),
@@ -627,7 +775,11 @@ var FF = function(ctx) {
}
},
- /* generate random x */
+ /**
+ * generate random x
+ *
+ * @this {FF}
+ */
randomnum: function(p, rng) {
var n = this.length,
d = new FF(2 * n),
@@ -640,7 +792,11 @@ var FF = function(ctx) {
this.copy(d.dmod(p));
},
- /* this*=y mod p */
+ /**
+ * this*=y mod p
+ *
+ * @this {FF}
+ */
modmul: function(y, p, nd) {
var ex = this.P_EXCESS(),
ey = y.P_EXCESS(),
@@ -660,7 +816,11 @@ var FF = function(ctx) {
}
},
- /* this*=y mod p */
+ /**
+ * this*=y mod p
+ *
+ * @this {FF}
+ */
modsqr: function(p, nd) {
var ex = this.P_EXCESS(),
n, d;
@@ -679,7 +839,13 @@ var FF = function(ctx) {
}
},
- /* this=this^e mod p using side-channel resistant Montgomery Ladder,
for large e */
+ /**
+ * this=this^e mod p using side-channel resistant Montgomery Ladder,
for large e
+ *
+ * @this {FF}
+ * @param e exponent
+ * @param p modulus
+ */
skpow: function(e, p) {
var n = p.length,
R0 = new FF(n),
@@ -710,7 +876,13 @@ var FF = function(ctx) {
this.redc(p, ND);
},
- /* this =this^e mod p using side-channel resistant Montgomery Ladder,
for short e */
+ /**
+ * this=this^e mod p using side-channel resistant Montgomery Ladder,
for short e
+ *
+ * @this {FF}
+ * @param e exponent
+ * @param p modulus
+ */
skspow: function(e, p) {
var n = p.length,
R0 = new FF(n),
@@ -739,7 +911,13 @@ var FF = function(ctx) {
this.redc(p, ND);
},
- /* raise to an integer power - right-to-left method */
+ /**
+ * raise to an integer power - right-to-left method
+ *
+ * @this {FF}
+ * @param e exponent
+ * @param p modulus
+ */
power: function(e, p) {
var n = p.length,
f = true,
@@ -773,7 +951,13 @@ var FF = function(ctx) {
this.redc(p, ND);
},
- /* this=this^e mod p, faster but not side channel resistant */
+ /**
+ * this=this^e mod p, faster but not side channel resistant
+ *
+ * @this {FF}
+ * @param e exponent
+ * @param p modulus
+ */
pow: function(e, p) {
var n = p.length,
w = new FF(n),
@@ -796,7 +980,15 @@ var FF = function(ctx) {
this.redc(p, ND);
},
- /* double exponentiation r=x^e.y^f mod p */
+ /**
+ * double exponentiation r=x^e.y^f mod p
+ *
+ * @this {FF}
+ * @param e exponent
+ * @param y FF instance
+ * @param f exponent
+ * @param p modulus
+ */
pow2: function(e, y, f, p) {
var n = p.length,
xn = new FF(n),
@@ -834,7 +1026,13 @@ var FF = function(ctx) {
this.redc(p, ND);
},
- /* quick and dirty check for common factor with n */
+ /**
+ * Test if an FF has factor in common with integer s
+ *
+ * @this {FF}
+ * @param s integerexponent
+ * @return true or false
+ */
cfactor: function(s) {
var n = this.length,
x = new FF(n),
@@ -864,7 +1062,14 @@ var FF = function(ctx) {
}
};
- /* compare x and y - must be normalised, and of same length */
+ /**
+ * compare a and b - must be normalised, and of same length
+ *
+ * @this {FF}
+ * @param a FF number
+ * @param b FF number
+ * @return zero of error codetrue or false
+ */
FF.comp = function(a, b) {
var i, j;
@@ -886,7 +1091,11 @@ var FF = function(ctx) {
}
};
- /* in-place swapping using xor - side channel resistant - lengths must be
the same */
+ /**
+ * in-place swapping using xor - side channel resistant - lengths must be
the same
+ *
+ * @this {FF}
+ */
FF.cswap = function(a, b, d) {
var i;
@@ -895,7 +1104,11 @@ var FF = function(ctx) {
}
};
- /* z=x*y. Assumes x and y are of same length. */
+ /**
+ * z=x*y. Assumes x and y are of same length.
+ *
+ * @this {FF}
+ */
FF.mul = function(x, y) {
var n = x.length,
z = new FF(2 * n),
@@ -906,7 +1119,11 @@ var FF = function(ctx) {
return z;
};
- /* z=x^2 */
+ /**
+ * z=x^2
+ *
+ * @this {FF}
+ */
FF.sqr = function(x) {
var n = x.length,
z = new FF(2 * n),
@@ -932,7 +1149,13 @@ var FF = function(ctx) {
return y;
};
- /* Miller-Rabin test for primality. Slow. */
+ /**
+ * Miller-Rabin test for primality.
+ *
+ * @this {FF}
+ * @param p FF instance to be tested
+ * @param rmg an instance of a Cryptographically Secure Random Number
Generator
+ */
FF.prime = function(p, rng) {
var n = p.length,
s = 0,
diff --git a/src/fp12.js b/src/fp12.js
index aa29a39..5dfbee1 100644
--- a/src/fp12.js
+++ b/src/fp12.js
@@ -24,7 +24,12 @@
var FP12 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP12.
+ *
+ * @constructor
+ * @this {FP12}
+ */
var FP12 = function(d, e, f) {
if (d instanceof FP12) {
// ignore e, d, which are assumed be undefined in this case
@@ -55,33 +60,56 @@ var FP12 = function(ctx) {
};
FP12.prototype = {
- /* reduce all components of this mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP12 mod Modulus
+ *
+ * @this {FP12}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
this.c.reduce();
},
- /* normalize all components of this mod Modulus */
+ /**
+ * Normalises the components of an FP12
+ *
+ * @this {FP12}
+ */
norm: function() {
this.a.norm();
this.b.norm();
this.c.norm();
},
- /* test x==0 ? */
+ /**
+ * Tests for FP12 equal to zero
+ *
+ * @this {FP12}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch() && this.c.iszilch());
},
- /* test x==1 ? */
+ /**
+ * Tests for FP12 equal to unity
+ *
+ * @this {FP12}
+ */
isunity: function() {
var one = new ctx.FP4(1);
return (this.a.equals(one) && this.b.iszilch() &&
this.c.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP12 number
+ *
+ * @this {FP12}
+ * @param g FP12 instance
+ * @param d copy depends on this value
+ */
cmove: function(g, d) {
this.a.cmove(g.a, d);
this.b.cmove(g.b, d);
@@ -91,8 +119,12 @@ var FP12 = function(ctx) {
},
- /* Constant time select from pre-computed table */
- select: function(g, b) {
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {FP12}
+ */
+ select: function(g, b) {
var invf = new FP12(0),
m, babs;
@@ -122,27 +154,49 @@ var FP12 = function(ctx) {
return this.stype;
},
- /* extract a from this */
+ /**
+ * extract a from this
+ *
+ * @this {FP12}
+ */
geta: function() {
return this.a;
},
- /* extract b */
+ /**
+ * extract b from this
+ *
+ * @this {FP12}
+ */
getb: function() {
return this.b;
},
- /* extract c */
+ /**
+ * extract c from this
+ *
+ * @this {FP12}
+ */
getc: function() {
return this.c;
},
- /* return 1 if x==y, else 0 */
+ /**
+ * Tests for equality of two FP12s
+ *
+ * @this {FP12}
+ * @param x FP12 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b) &&
this.c.equals(x.c));
},
- /* copy this=x */
+ /**
+ * Copy FP12 to another FP12
+ *
+ * @this {FP12}
+ * @param x FP12 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
@@ -150,7 +204,12 @@ var FP12 = function(ctx) {
this.stype=x.stype;
},
- /* set this=1 */
+ /**
+ * Set FP12 to unity
+ *
+ * @this {FP12}
+ * @param x FP12 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
@@ -158,7 +217,11 @@ var FP12 = function(ctx) {
this.stype=ctx.FP.ONE;
},
- /* set this=0 */
+ /**
+ * Set FP12 to zero
+ *
+ * @this {FP12}
+ */
zero: function() {
this.a.zero();
this.b.zero();
@@ -166,30 +229,50 @@ var FP12 = function(ctx) {
this.stype=ctx.FP.ZERO;
},
- /* this=conj(this) */
+ /**
+ * Conjugation of FP12
+ *
+ * @this {FP12}
+ */
conj: function() {
this.a.conj();
this.b.nconj();
this.c.conj();
},
- /* set this from 3 FP4s */
+ /**
+ * Set FP12 from three FP4 values
+ *
+ * @this {FP12}
+ * @param d FP4 instance
+ * @param e FP4 instance
+ * @param f FP4 instance
+ */
set: function(d, e, f) {
this.a.copy(d);
this.b.copy(e);
this.c.copy(f);
- this.stype=ctx.FP.DENSE;
+ this.stype=ctx.FP.DENSE;
},
- /* set this from one ctx.FP4 */
+ /**
+ * Set FP12 from one FP4 value
+ *
+ * @this {FP12}
+ * @param d FP4 instance
+ */
seta: function(d) {
this.a.copy(d);
this.b.zero();
this.c.zero();
- this.stype=ctx.FP.SPARSER
+ this.stype=ctx.FP.SPARSER
},
- /* Granger-Scott Unitary Squaring */
+ /**
+ * Fast Squaring of an FP12 in "unitary" form
+ *
+ * @this {FP12}
+ */
usqr: function() {
var A = new ctx.FP4(this.a),
B = new ctx.FP4(this.c),
@@ -228,7 +311,11 @@ var FP12 = function(ctx) {
this.reduce();
},
- /* Chung-Hasan SQR2 method from
http://cacr.uwaterloo.ca/techreports/2006/cacr2006-24.pdf */
+ /**
+ * Fast Squaring of an FP12
+ *
+ * @this {FP12}
+ */
sqr: function() {
if (this.stype==ctx.FP.ONE)
return;
@@ -270,7 +357,12 @@ var FP12 = function(ctx) {
this.norm();
},
- /* FP12 full multiplication this=this*y */
+ /**
+ * Full unconditional Multiplication of two FP12s
+ *
+ * @this {FP12}
+ * @param y FP12 instance, the multiplier
+ */
mul: function(y) {
var z0 = new ctx.FP4(this.a),
z1 = new ctx.FP4(0),
@@ -343,8 +435,15 @@ var FP12 = function(ctx) {
/* FP12 multiplication w=w*y */
/* catering for special case that arises from special form of ATE pairing line
function */
-/* w and y are both sparser line functions - cost = 6m */
- smul: function(y) {
+ /* w and y are both sparser line functions - cost = 6m */
+
+ /**
+ * Fast multiplication of two sparse FP12s that arises from ATE
pairing line functions
+ *
+ * @this {FP12}
+ * @param y FP12 instance, the multiplier
+ */
+ smul: function(y) {
if (ctx.ECP.SEXTIC_TWIST==ctx.ECP.D_TYPE)
{
var w1=new ctx.FP2(this.a.geta());
@@ -454,8 +553,15 @@ var FP12 = function(ctx) {
/* FP12 full multiplication w=w*y */
/* Supports sparse multiplicands */
-/* Usually w is denser than y */
- ssmul: function(y) {
+ /* Usually w is denser than y */
+
+ /**
+ * Fast multiplication of what may be sparse multiplicands
+ *
+ * @this {FP12}
+ * @param y FP12 instance, the multiplier
+ */
+ ssmul: function(y) {
if (this.stype==ctx.FP.ONE)
{
this.copy(y);
@@ -649,7 +755,11 @@ var FP12 = function(ctx) {
this.norm();
},
- /* this=1/this */
+ /**
+ * Inverting an FP12
+ *
+ * @this {FP12}
+ */
inverse: function() {
var f0 = new ctx.FP4(this.a),
f1 = new ctx.FP4(this.b),
@@ -696,7 +806,12 @@ var FP12 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* this=this^p, where p=Modulus, using Frobenius */
+ /**
+ * Raises an FP12 to the power of the internal modulus p, using the
Frobenius
+ *
+ * @this {FP12}
+ * @param f Modulus
+ */
frob: function(f) {
var f2 = new ctx.FP2(f),
f3 = new ctx.FP2(f);
@@ -713,7 +828,11 @@ var FP12 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* trace function */
+ /**
+ * Calculate the trace of an FP12
+ *
+ * @this {FP12}
+ */
trace: function() {
var t = new ctx.FP4(0);
@@ -724,12 +843,21 @@ var FP12 = function(ctx) {
return t;
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {FP12}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "," +
this.c.toString() + "]");
},
- /* convert this to byte array */
+ /**
+ * convert this to byte array
+ *
+ * @this {FP12}
+ * @param w Byte array
+ */
toBytes: function(w) {
var t = [],
i;
@@ -786,7 +914,12 @@ var FP12 = function(ctx) {
}
},
- /* set this=this^e */
+ /**
+ * Raises an FP12 to the power of a BIG
+ *
+ * @this {FP12}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var e1, e3, w, nb, i, bt, sf;
e1 = new ctx.BIG(e);
@@ -818,7 +951,13 @@ var FP12 = function(ctx) {
return w;
},
- /* constant time powering by small integer of max length bts */
+ /**
+ * Raises an FP12 instance x to a small integer power, side-channel
resistant
+ *
+ * @this {FP12}
+ * @param e small integer exponent
+ * @param bts maximum number of bits in exponent
+ */
pinpow: function(e, bts) {
var R = [],
i, b;
@@ -835,7 +974,13 @@ var FP12 = function(ctx) {
this.copy(R[0]);
},
- /* Faster compressed powering for unitary elements */
+ /**
+ * Raises an FP12 instance to a BIG power, compressed to FP4
+ *
+ * @this {FP12}
+ * @param e BIG exponent
+ * @param r BIG group order
+ */
compow: function(e, r) {
var fa, fb, f, q, m, a, b, g1, g2, c, cp, cpm1, cpm2;
@@ -882,7 +1027,12 @@ var FP12 = function(ctx) {
}
};
- /* convert from byte array to FP12 */
+ /**
+ * convert from byte array to FP12
+ *
+ * @this {FP12}
+ * @param w Byte array
+ */
FP12.fromBytes = function(w) {
var t = [],
i, a, b, c, d, e, f, g, r;
@@ -959,7 +1109,11 @@ var FP12 = function(ctx) {
};
- /* return 1 if b==c, no branching */
+ /**
+ * return 1 if b==c, no branching
+ *
+ * @this {FP12}
+ */
FP12.teq = function(b, c) {
var x = b ^ c;
x -= 1; // if x=0, x now -1
@@ -970,6 +1124,12 @@ var FP12 = function(ctx) {
// Bos & Costello https://eprint.iacr.org/2013/458.pdf
// Faz-Hernandez & Longa & Sanchez https://eprint.iacr.org/2013/158.pdf
// Side channel attack secure
+
+ /**
+ * p=q0^u0.q1^u1.q2^u2.q3^u3
+ *
+ * @this {FP12}
+ */
FP12.pow4 = function(q, u) {
var g = [],
r = new FP12(0),
diff --git a/src/fp16.js b/src/fp16.js
index 14d10e8..0627f73 100644
--- a/src/fp16.js
+++ b/src/fp16.js
@@ -24,7 +24,12 @@
var FP16 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP16.
+ *
+ * @constructor
+ * @this {FP16}
+ */
var FP16 = function(c, d) {
if (c instanceof FP16) {
this.a = new ctx.FP8(c.a);
@@ -36,90 +41,164 @@ var FP16 = function(ctx) {
};
FP16.prototype = {
- /* reduce all components of this mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP16 mod Modulus
+ *
+ * @this {FP16}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
},
- /* normalise all components of this mod Modulus */
+ /**
+ * Normalises the components of an FP16
+ *
+ * @this {FP16}
+ */
norm: function() {
this.a.norm();
this.b.norm();
},
- /* test this==0 ? */
+ /**
+ * Tests for FP16 equal to zero
+ *
+ * @this {FP16}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch());
},
- /* test this==1 ? */
+ /**
+ * Tests for FP16 equal to unity
+ *
+ * @this {FP16}
+ */
isunity: function() {
var one = new ctx.FP8(1);
return (this.a.equals(one) && this.b.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP16 number
+ *
+ * @this {FP16}
+ * @param g FP16 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 {FP16}
+ */
isreal: function() {
return this.b.iszilch();
},
- /* extract real part a */
+ /**
+ * extract real part a
+ *
+ * @this {FP16}
+ */
real: function() {
return this.a;
},
+ /**
+ * extract a from this
+ *
+ * @this {FP16}
+ */
geta: function() {
return this.a;
},
- /* extract imaginary part b */
+ /**
+ * extract b from this
+ *
+ * @this {FP16}
+ */
getb: function() {
return this.b;
},
- /* test this=x? */
+ /**
+ * Tests for equality of two FP16s
+ *
+ * @this {FP16}
+ * @param x FP16 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b));
},
- /* copy this=x */
+ /**
+ * Copy FP16 to another FP16
+ *
+ * @this {FP16}
+ * @param x FP16 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
},
- /* this=0 */
+ /**
+ * Set FP16 to zero
+ *
+ * @this {FP16}
+ */
zero: function() {
this.a.zero();
this.b.zero();
},
- /* this=1 */
+ /**
+ * Set FP16 to unity
+ *
+ * @this {FP16}
+ * @param x FP16 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
},
- /* set from two FP8s */
+ /**
+ * Set FP16 from two FP8 values
+ *
+ * @this {FP16}
+ * @param c FP8 instance
+ * @param d FP8 instance
+ */
set: function(c, d) {
this.a.copy(c);
this.b.copy(d);
},
- /* set a */
+ /**
+ * Set FP16 from one FP8 value
+ *
+ * @this {FP16}
+ * @param c FP8 instance
+ */
seta: function(c) {
this.a.copy(c);
this.b.zero();
},
- /* this=-this */
+ /**
+ * this=-this
+ *
+ * @this {FP16}
+ */
neg: function() {
var m = new ctx.FP8(this.a),
t = new ctx.FP8(0);
@@ -136,50 +215,87 @@ var FP16 = function(ctx) {
this.norm();
},
- /* this=conjugate(this) */
+ /**
+ * Conjugation of FP16
+ *
+ * @this {FP16}
+ */
conj: function() {
this.b.neg();
this.norm();
},
- /* this=-conjugate(this) */
+ /**
+ * Negative conjugation of FP16
+ *
+ * @this {FP16}
+ */
nconj: function() {
this.a.neg();
this.norm();
},
- /* this+=x */
+ /**
+ * addition of two FP16s
+ *
+ * @this {FP16}
+ * @param x FP16 instance
+ */
add: function(x) {
this.a.add(x.a);
this.b.add(x.b);
},
- /* this-=x */
+ /**
+ * subtraction of two FP16s
+ *
+ * @this {FP16}
+ * @param x FP16 instance
+ */
sub: function(x) {
var m = new FP16(x);
m.neg();
this.add(m);
},
- /* this*=s where s is FP8 */
+ /**
+ * Multiplication of an FP16 by an FP8
+ *
+ * @this {FP16}
+ * @param s FP8 instance
+ */
pmul: function(s) {
this.a.mul(s);
this.b.mul(s);
},
- /* this*=s where s is FP2 */
+ /**
+ * Multiplication of an FP16 by an FP2
+ *
+ * @this {FP16}
+ * @param s FP2 instance
+ */
qmul: function(s) {
this.a.qmul(s);
this.b.qmul(s);
},
- /* this*=c where s is int */
+ /**
+ * Multiplication of an FP16 by a small integer
+ *
+ * @this {FP16}
+ * @param s integer
+ */
imul: function(c) {
this.a.imul(c);
this.b.imul(c);
},
- /* this*=this */
+ /**
+ * Fast Squaring of an FP16
+ *
+ * @this {FP16}
+ */
sqr: function() {
var t1 = new ctx.FP8(this.a),
t2 = new ctx.FP8(this.b),
@@ -210,7 +326,12 @@ var FP16 = function(ctx) {
this.norm();
},
- /* this*=y */
+ /**
+ * Full unconditional Multiplication of two FP16s
+ *
+ * @this {FP16}
+ * @param y FP16 instance, the multiplier
+ */
mul: function(y) {
var t1 = new ctx.FP8(this.a),
@@ -245,12 +366,20 @@ var FP16 = function(ctx) {
this.norm();
},
- /* convert to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {FP16}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "]");
},
- /* this=1/this */
+ /**
+ * Inverting an FP16
+ *
+ * @this {FP16}
+ */
inverse: function() {
//this.norm();
@@ -269,7 +398,11 @@ var FP16 = function(ctx) {
this.b.mul(t1);
},
- /* this*=i where i = sqrt(-1+sqrt(-1)) */
+ /**
+ * multiplies an FP16 instance by irreducible polynomial
sqrt(1+sqrt(-1))
+ *
+ * @this {FP16}
+ */
times_i: function() {
var s = new ctx.FP8(this.b),
t = new ctx.FP8(this.a);
@@ -281,18 +414,33 @@ var FP16 = function(ctx) {
this.norm();
},
+ /**
+ * multiplies an FP16 instance by irreducible polynomial (1+sqrt(-1))
+ *
+ * @this {FP16}
+ */
times_i2: function() {
this.a.times_i();
this.b.times_i();
},
+ /**
+ * multiplies an FP16 instance by irreducible polynomial (1+sqrt(-1))
+ *
+ * @this {FP16}
+ */
times_i4: function() {
this.a.times_i2();
this.b.times_i2();
},
- /* this=this^q using Frobenius, where q is Modulus */
+ /**
+ * Raises an FP16 to the power of the internal modulus p, using the
Frobenius
+ *
+ * @this {FP16}
+ * @param f Modulus
+ */
frob: function(f) {
var ff=new ctx.FP2(f); ff.sqr(); ff.norm();
this.a.frob(ff);
@@ -301,7 +449,12 @@ var FP16 = function(ctx) {
this.b.times_i();
},
- /* this=this^e */
+ /**
+ * Raises an FP16 to the power of a BIG
+ *
+ * @this {FP16}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var w = new FP16(this),
@@ -329,7 +482,14 @@ var FP16 = function(ctx) {
return r;
},
- /* XTR xtr_a function */
+ /**
+ * Calculates the XTR addition function r=w*x-conj(x)*y+z
+ *
+ * @this {FP16}
+ * @param w FP16 instance
+ * @param y FP16 instance
+ * @param z FP16 instance
+ */
xtr_A: function(w, y, z) {
var r = new FP16(w),
t = new FP16(w);
@@ -349,7 +509,11 @@ var FP16 = function(ctx) {
this.reduce();
},
- /* XTR xtr_d function */
+ /**
+ * Calculates the XTR doubling function r=x^2-2*conj(x)
+ *
+ * @this {FP16}
+ */
xtr_D: function() {
var w = new FP16(this);
this.sqr();
@@ -359,7 +523,12 @@ var FP16 = function(ctx) {
this.reduce();
},
- /* r=x^n using XTR method on traces of FP12s */
+ /**
+ * Calculates FP16 trace of an FP16 raised to the power of a BIG number
+ *
+ * @this {FP16}
+ * @param n Big number
+ */
xtr_pow: function(n) {
var sf = new FP16(this);
sf.norm();
@@ -414,7 +583,11 @@ var FP16 = function(ctx) {
return r;
},
- /* r=ck^a.cl^n using XTR double exponentiation method on traces of
FP12s. See Stam thesis. */
+ /**
+ * Calculates FP16 trace of c^a.d^b, where c and d are derived from
FP16 traces of FP16s
+ *
+ * @this {FP16}
+ */
xtr_pow2: function(ck, ckml, ckm2l, a, b) {
var e = new ctx.BIG(a),
diff --git a/src/fp2.js b/src/fp2.js
index d2d1a50..70b0477 100644
--- a/src/fp2.js
+++ b/src/fp2.js
@@ -24,7 +24,12 @@
var FP2 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP2.
+ *
+ * @constructor
+ * @this {FP2}
+ */
var FP2 = function(c, d) {
if (c instanceof FP2) {
this.a = new ctx.FP(c.a);
@@ -36,93 +41,170 @@ var FP2 = function(ctx) {
};
FP2.prototype = {
- /* reduce components mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP2 mod Modulus
+ *
+ * @this {FP2}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
},
- /* normalise components of w */
+ /**
+ * Normalises the components of an FP2
+ *
+ * @this {FP2}
+ */
norm: function() {
this.a.norm();
this.b.norm();
},
- /* test this=0 ? */
+ /**
+ * Tests for FP2 equal to zero
+ *
+ * @this {FP2}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch());
},
- /* test this=1 ? */
+ /**
+ * Tests for FP2 equal to unity
+ *
+ * @this {FP2}
+ */
isunity: function() {
var one = new ctx.FP(1);
return (this.a.equals(one) && this.b.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP2 number
+ *
+ * @this {FP2}
+ * @param g FP2 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 this=x */
+ /**
+ * Tests for equality of two FP2 instances
+ *
+ * @this {FP2}
+ * @param x FP2 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b));
},
- /* extract a */
+ /**
+ * extract a from this
+ *
+ * @this {FP2}
+ */
getA: function() {
return this.a.redc();
},
- /* extract b */
+ /**
+ * extract b from this
+ *
+ * @this {FP2}
+ */
getB: function() {
return this.b.redc();
},
- /* set from pair of FPs */
+ /**
+ * Set FP2 from two FP values
+ *
+ * @this {FP2}
+ * @param c FP instance
+ * @param d FP instance
+ */
set: function(c, d) {
this.a.copy(c);
this.b.copy(d);
},
- /* set a */
+ /**
+ * Set FP2 from one FP value
+ *
+ * @this {FP2}
+ * @param c FP instance
+ */
seta: function(c) {
this.a.copy(c);
this.b.zero();
},
- /* set from two BIGs */
+ /**
+ * Set FP2 from two BIG values
+ *
+ * @this {FP2}
+ * @param c BIG instance
+ * @param d BIG instance
+ */
bset: function(c, d) {
this.a.bcopy(c);
this.b.bcopy(d);
},
- /* set from one ctx.BIG */
+ /**
+ * Set FP2 from one BIG value
+ *
+ * @this {FP2}
+ * @param c BIG instance
+ */
bseta: function(c) {
this.a.bcopy(c);
this.b.zero();
},
- /* copy this=x */
+ /**
+ * Copy FP2 to another FP2
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
},
- /* set this=0 */
+ /**
+ * Set FP2 to zero
+ *
+ * @this {FP2}
+ */
zero: function() {
this.a.zero();
this.b.zero();
},
- /* set this=1 */
+ /**
+ * Set FP2 to unity
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
},
- /* negate this */
+ /**
+ * negate this
+ *
+ * @this {FP2}
+ * @param x FP2 instance to be set to one
+ */
neg: function() {
var m = new ctx.FP(this.a),
t = new ctx.FP(0);
@@ -136,19 +218,33 @@ var FP2 = function(ctx) {
this.a.copy(t);
},
- /* conjugate this */
+ /**
+ * Conjugation of FP2
+ *
+ * @this {FP2}
+ */
conj: function() {
this.b.neg();
this.b.norm();
},
- /* this+=a */
+ /**
+ * addition of two FP2s
+ *
+ * @this {FP2}
+ * @param x FP2 instance
+ */
add: function(x) {
this.a.add(x.a);
this.b.add(x.b);
},
- /* this-=x */
+ /**
+ * subtraction of two FP2s
+ *
+ * @this {FP2}
+ * @param x FP2 instance
+ */
sub: function(x) {
var m = new FP2(x);
m.neg();
@@ -160,19 +256,33 @@ var FP2 = function(ctx) {
this.add(x);
},
- /* this*=s, where s is FP */
+ /**
+ * Multiplication of an FP2 by an FP8
+ *
+ * @this {FP2}
+ * @param s FP8 instance
+ */
pmul: function(s) {
this.a.mul(s);
this.b.mul(s);
},
- /* this*=c, where s is int */
+ /**
+ * Multiplication of an FP2 by a small integer
+ *
+ * @this {FP2}
+ * @param s integer
+ */
imul: function(c) {
this.a.imul(c);
this.b.imul(c);
},
- /* this*=this */
+ /**
+ * Fast Squaring of an FP2
+ *
+ * @this {FP2}
+ */
sqr: function() {
var w1 = new ctx.FP(this.a),
w3 = new ctx.FP(this.a),
@@ -192,8 +302,12 @@ var FP2 = function(ctx) {
this.a.mul(w1);
},
- /* this*=y */
- /* Now using Lazy reduction - inputs must be normed */
+ /**
+ * Full unconditional Multiplication of two FP2s
+ *
+ * @this {FP2}
+ * @param y FP2 instance, the multiplier
+ */
mul: function(y) {
var p = new ctx.BIG(0),
pR = new ctx.DBIG(0),
@@ -240,8 +354,12 @@ var FP2 = function(ctx) {
this.b.XES = 2;
},
- /* sqrt(a+ib) =
sqrt(a+sqrt(a*a-n*b*b)/2)+ib/(2*sqrt(a+sqrt(a*a-n*b*b)/2)) */
- /* returns true if this is QR */
+ /**
+ * sqrt(a+ib) =
sqrt(a+sqrt(a*a-n*b*b)/2)+ib/(2*sqrt(a+sqrt(a*a-n*b*b)/2))
+ *
+ * @this {FP2}
+ * @return true if this is QR
+ */
sqrt: function() {
var w1, w2;
@@ -283,12 +401,20 @@ var FP2 = function(ctx) {
return true;
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {FP2}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "]");
},
- /* this=1/this */
+ /**
+ * Inverting an FP2
+ *
+ * @this {FP2}
+ */
inverse: function() {
var w1, w2;
@@ -307,13 +433,21 @@ var FP2 = function(ctx) {
this.b.mul(w1);
},
- /* this/=2 */
+ /**
+ * Divide an FP2 by 2
+ *
+ * @this {FP2}
+ */
div2: function() {
this.a.div2();
this.b.div2();
},
- /* this*=sqrt(-1) */
+ /**
+ * Multiply an FP2 by sqrt(-1)
+ *
+ * @this {FP2}
+ */
times_i: function() {
var z = new ctx.FP(this.a); //z.copy(this.a);
this.a.copy(this.b);
@@ -321,8 +455,11 @@ var FP2 = function(ctx) {
this.b.copy(z);
},
- /* w*=(1+sqrt(-1)) */
- /* where X*2-(1+sqrt(-1)) is irreducible for FP4, assumes p=3 mod 8 */
+ /**
+ * Multiply an FP2 by (1+sqrt(-1))
+ *
+ * @this {FP2}
+ */
mul_ip: function() {
var t = new FP2(this),
z = new ctx.FP(this.a);
@@ -334,6 +471,11 @@ var FP2 = function(ctx) {
// this.norm();
},
+ /**
+ * Divide an FP2 by (1+sqrt(-1))/2
+ *
+ * @this {FP2}
+ */
div_ip2: function() {
var t = new FP2(0);
this.norm();
@@ -345,7 +487,11 @@ var FP2 = function(ctx) {
this.norm();
},
- /* w/=(1+sqrt(-1)) */
+ /**
+ * Divide an FP2 by (1+sqrt(-1))
+ *
+ * @this {FP2}
+ */
div_ip: function() {
var t = new FP2(0);
this.norm();
@@ -358,7 +504,12 @@ var FP2 = function(ctx) {
this.div2();
},
- /* this=this^e */
+ /**
+ * Raises an FP2 to the power of a BIG
+ *
+ * @this {FP2}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
this.norm();
diff --git a/src/fp24.js b/src/fp24.js
index 50cd3d2..97ece0c 100644
--- a/src/fp24.js
+++ b/src/fp24.js
@@ -24,7 +24,12 @@
var FP24 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP24.
+ *
+ * @constructor
+ * @this {FP24}
+ */
var FP24 = function(d, e, f) {
if (!isNaN(d))
{
@@ -50,32 +55,55 @@ var FP24 = function(ctx) {
};
FP24.prototype = {
- /* reduce all components of this mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP24 mod Modulus
+ *
+ * @this {FP24}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
this.c.reduce();
},
- /* normalize all components of this mod Modulus */
+ /**
+ * Normalises the components of an FP24
+ *
+ * @this {FP24}
+ */
norm: function() {
this.a.norm();
this.b.norm();
this.c.norm();
},
- /* test x==0 ? */
+ /**
+ * Tests for FP24 equal to zero
+ *
+ * @this {FP24}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch() && this.c.iszilch());
},
- /* test x==1 ? */
+ /**
+ * Tests for FP24 equal to unity
+ *
+ * @this {FP24}
+ */
isunity: function() {
var one = new ctx.FP8(1);
return (this.a.equals(one) && this.b.iszilch() &&
this.c.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP24 number
+ *
+ * @this {FP24}
+ * @param g FP24 instance
+ * @param d copy depends on this value
+ */
cmove: function(g, d) {
this.a.cmove(g.a, d);
this.b.cmove(g.b, d);
@@ -84,7 +112,11 @@ var FP24 = function(ctx) {
this.stype^=(this.stype^g.stype)&d;
},
- /* Constant time select from pre-computed table */
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {FP24}
+ */
select: function(g, b) {
var invf = new FP24(0),
m, babs;
@@ -114,27 +146,50 @@ var FP24 = function(ctx) {
gettype: function() {
return this.stype;
},
- /* extract a from this */
+
+ /**
+ * extract a from this
+ *
+ * @this {FP24}
+ */
geta: function() {
return this.a;
},
- /* extract b */
+ /**
+ * extract b from this
+ *
+ * @this {FP24}
+ */
getb: function() {
return this.b;
},
- /* extract c */
+ /**
+ * extract c from this
+ *
+ * @this {FP24}
+ */
getc: function() {
return this.c;
},
- /* return 1 if x==y, else 0 */
+ /**
+ * Tests for equality of two FP24s
+ *
+ * @this {FP24}
+ * @param x FP24 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b) &&
this.c.equals(x.c));
},
- /* copy this=x */
+ /**
+ * Copy FP24 to another FP24
+ *
+ * @this {FP24}
+ * @param x FP24 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
@@ -142,7 +197,12 @@ var FP24 = function(ctx) {
this.stype=x.stype;
},
- /* set this=1 */
+ /**
+ * Set FP24 to unity
+ *
+ * @this {FP24}
+ * @param x FP24 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
@@ -150,7 +210,11 @@ var FP24 = function(ctx) {
this.stype=ctx.FP.ONE;
},
- /* set this=0 */
+ /**
+ * Set FP24 to zero
+ *
+ * @this {FP24}
+ */
zero: function() {
this.a.zero();
this.b.zero();
@@ -158,14 +222,25 @@ var FP24 = function(ctx) {
this.stype=ctx.FP.ZERO;
},
- /* this=conj(this) */
+ /**
+ * Conjugation of FP24
+ *
+ * @this {FP24}
+ */
conj: function() {
this.a.conj();
this.b.nconj();
this.c.conj();
},
- /* set this from 3 FP8s */
+ /**
+ * Set FP24 from three FP8 values
+ *
+ * @this {FP24}
+ * @param d FP8 instance
+ * @param e FP8 instance
+ * @param f FP8 instance
+ */
set: function(d, e, f) {
this.a.copy(d);
this.b.copy(e);
@@ -173,7 +248,12 @@ var FP24 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* set this from one ctx.FP8 */
+ /**
+ * Set FP24 from one FP8 value
+ *
+ * @this {FP24}
+ * @param c FP8 instance
+ */
seta: function(d) {
this.a.copy(d);
this.b.zero();
@@ -181,7 +261,11 @@ var FP24 = function(ctx) {
this.stype=ctx.FP.SPARSER
},
- /* Granger-Scott Unitary Squaring */
+ /**
+ * Fast Squaring of an FP24 in "unitary" form
+ *
+ * @this {FP24}
+ */
usqr: function() {
var A = new ctx.FP8(this.a),
B = new ctx.FP8(this.c),
@@ -220,7 +304,11 @@ var FP24 = function(ctx) {
this.reduce();
},
- /* Chung-Hasan SQR2 method from
http://cacr.uwaterloo.ca/techreports/2006/cacr2006-24.pdf */
+ /**
+ * Fast Squaring of an FP24
+ *
+ * @this {FP24}
+ */
sqr: function() {
if (this.stype==ctx.FP.ONE)
return;
@@ -262,7 +350,12 @@ var FP24 = function(ctx) {
this.norm();
},
- /* FP24 full multiplication this=this*y */
+ /**
+ * Full unconditional Multiplication of two FP24s
+ *
+ * @this {FP24}
+ * @param y FP24 instance, the multiplier
+ */
mul: function(y) {
var z0 = new ctx.FP8(this.a),
z1 = new ctx.FP8(0),
@@ -336,8 +429,15 @@ var FP24 = function(ctx) {
/* FP24 multiplication w=w*y */
/* catering for special case that arises from special form of ATE pairing line
function */
-/* w and y are both sparser line functions - cost = 6m */
- smul: function(y) {
+ /* w and y are both sparser line functions - cost = 6m */
+
+ /**
+ * Fast multiplication of two sparse FP24s that arises from ATE
pairing line functions
+ *
+ * @this {FP24}
+ * @param y FP24 instance, the multiplier
+ */
+ smul: function(y) {
if (ctx.ECP.SEXTIC_TWIST==ctx.ECP.D_TYPE)
{
var w1=new ctx.FP4(this.a.geta());
@@ -447,8 +547,15 @@ var FP24 = function(ctx) {
/* FP24 full multiplication w=w*y */
/* Supports sparse multiplicands */
-/* Usually w is denser than y */
- ssmul: function(y) {
+ /* Usually w is denser than y */
+
+ /**
+ * Fast multiplication of what may be sparse multiplicands
+ *
+ * @this {FP24}
+ * @param y FP24 instance, the multiplier
+ */
+ ssmul: function(y) {
if (this.stype==ctx.FP.ONE)
{
this.copy(y);
@@ -642,7 +749,11 @@ var FP24 = function(ctx) {
this.norm();
},
- /* this=1/this */
+ /**
+ * Inverting an FP24
+ *
+ * @this {FP24}
+ */
inverse: function() {
var f0 = new ctx.FP8(this.a),
f1 = new ctx.FP8(this.b),
@@ -689,7 +800,12 @@ var FP24 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* this=this^p, where p=Modulus, using Frobenius */
+ /**
+ * Raises an FP24 to the power of the internal modulus p, using the
Frobenius
+ *
+ * @this {FP24}
+ * @param f Modulus
+ */
frob: function(f,n) {
var f2 = new ctx.FP2(f),
f3 = new ctx.FP2(f),
@@ -711,7 +827,11 @@ var FP24 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* trace function */
+ /**
+ * Calculate the trace of an FP24
+ *
+ * @this {FP24}
+ */
trace: function() {
var t = new ctx.FP8(0);
@@ -722,12 +842,21 @@ var FP24 = function(ctx) {
return t;
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {FP24}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "," +
this.c.toString() + "]");
},
- /* convert this to byte array */
+ /**
+ * convert this to byte array
+ *
+ * @this {FP24}
+ * @param w Byte array
+ */
toBytes: function(w) {
var t = [],
i;
@@ -835,7 +964,12 @@ var FP24 = function(ctx) {
}
},
- /* set this=this^e */
+ /**
+ * Raises an FP24 to the power of a BIG
+ *
+ * @this {FP24}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var e1, e3, w, nb, i, bt, sf;
@@ -869,7 +1003,13 @@ var FP24 = function(ctx) {
return w;
},
- /* constant time powering by small integer of max length bts */
+ /**
+ * Raises an FP24 instance x to a small integer power, side-channel
resistant
+ *
+ * @this {FP24}
+ * @param e small integer exponent
+ * @param bts maximum number of bits in exponent
+ */
pinpow: function(e, bts) {
var R = [],
i, b;
@@ -886,7 +1026,13 @@ var FP24 = function(ctx) {
this.copy(R[0]);
},
- /* Faster compressed powering for unitary elements */
+ /**
+ * Raises an FP24 instance to a BIG power, compressed to FP4
+ *
+ * @this {FP24}
+ * @param e BIG exponent
+ * @param r BIG group order
+ */
compow: function(e, r) {
var fa, fb, f, q, m, a, b, g1, g2, c, cp, cpm1, cpm2;
@@ -933,7 +1079,12 @@ var FP24 = function(ctx) {
}
};
- /* convert from byte array to FP12 */
+ /**
+ * convert from byte array to FP24
+ *
+ * @this {FP24}
+ * @param w Byte array
+ */
FP24.fromBytes = function(w) {
var t = [],
i, a, b, c, d, e, f, g, r, ea, eb;
@@ -1081,7 +1232,11 @@ var FP24 = function(ctx) {
return r;
};
- /* return 1 if b==c, no branching */
+ /**
+ * return 1 if b==c, no branching
+ *
+ * @this {FP24}
+ */
FP24.teq = function(b, c) {
var x = b ^ c;
x -= 1; // if x=0, x now -1
@@ -1092,6 +1247,12 @@ var FP24 = function(ctx) {
// Bos & Costello https://eprint.iacr.org/2013/458.pdf
// Faz-Hernandez & Longa & Sanchez https://eprint.iacr.org/2013/158.pdf
// Side channel attack secure
+
+ /**
+ * p=q0^u0.q1^u1.q2^u2.q3^u3...
+ *
+ * @this {FP24}
+ */
FP24.pow8 = function(q, u) {
var g1 = [],
g2 = [],
diff --git a/src/fp48.js b/src/fp48.js
index 58ac47b..c3e6704 100644
--- a/src/fp48.js
+++ b/src/fp48.js
@@ -24,7 +24,12 @@
var FP48 = function(ctx) {
"use strict";
- /* general purpose constructor */
+ /**
+ * Creates an instance of FP48.
+ *
+ * @constructor
+ * @this {FP48}
+ */
var FP48 = function(d, e, f) {
if (!isNaN(d))
{
@@ -50,32 +55,55 @@ var FP48 = function(ctx) {
};
FP48.prototype = {
- /* reduce all components of this mod Modulus */
+
+ /**
+ * Reduces all components of possibly unreduced FP48 mod Modulus
+ *
+ * @this {FP48}
+ */
reduce: function() {
this.a.reduce();
this.b.reduce();
this.c.reduce();
},
- /* normalize all components of this mod Modulus */
+ /**
+ * Normalises the components of an FP48
+ *
+ * @this {FP48}
+ */
norm: function() {
this.a.norm();
this.b.norm();
this.c.norm();
},
- /* test x==0 ? */
+ /**
+ * Tests for FP48 equal to zero
+ *
+ * @this {FP48}
+ */
iszilch: function() {
return (this.a.iszilch() && this.b.iszilch() && this.c.iszilch());
},
- /* test x==1 ? */
+ /**
+ * Tests for FP48 equal to unity
+ *
+ * @this {FP48}
+ */
isunity: function() {
var one = new ctx.FP16(1);
return (this.a.equals(one) && this.b.iszilch() &&
this.c.iszilch());
},
- /* conditional copy of g to this depending on d */
+ /**
+ * Conditional copy of FP48 number
+ *
+ * @this {FP48}
+ * @param g FP48 instance
+ * @param d copy depends on this value
+ */
cmove: function(g, d) {
this.a.cmove(g.a, d);
this.b.cmove(g.b, d);
@@ -85,7 +113,11 @@ var FP48 = function(ctx) {
},
- /* Constant time select from pre-computed table */
+ /**
+ * Constant time select from pre-computed table
+ *
+ * @this {FP48}
+ */
select: function(g, b) {
var invf = new FP48(0),
m, babs;
@@ -116,27 +148,49 @@ var FP48 = function(ctx) {
return this.stype;
},
- /* extract a from this */
+ /**
+ * extract a from this
+ *
+ * @this {FP48}
+ */
geta: function() {
return this.a;
},
- /* extract b */
+ /**
+ * extract b from this
+ *
+ * @this {FP48}
+ */
getb: function() {
return this.b;
},
- /* extract c */
+ /**
+ * extract c from this
+ *
+ * @this {FP48}
+ */
getc: function() {
return this.c;
},
- /* return 1 if x==y, else 0 */
+ /**
+ * Tests for equality of two FP48s
+ *
+ * @this {FP48}
+ * @param x FP48 instance to compare
+ */
equals: function(x) {
return (this.a.equals(x.a) && this.b.equals(x.b) &&
this.c.equals(x.c));
},
- /* copy this=x */
+ /**
+ * Copy FP48 to another FP48
+ *
+ * @this {FP48}
+ * @param x FP48 instance to be copied
+ */
copy: function(x) {
this.a.copy(x.a);
this.b.copy(x.b);
@@ -144,7 +198,12 @@ var FP48 = function(ctx) {
this.stype=x.stype;
},
- /* set this=1 */
+ /**
+ * Set FP48 to unity
+ *
+ * @this {FP48}
+ * @param x FP48 instance to be set to one
+ */
one: function() {
this.a.one();
this.b.zero();
@@ -152,7 +211,11 @@ var FP48 = function(ctx) {
this.stype=ctx.FP.ONE;
},
- /* set this=0 */
+ /**
+ * Set FP48 to zero
+ *
+ * @this {FP48}
+ */
zero: function() {
this.a.zero();
this.b.zero();
@@ -160,14 +223,25 @@ var FP48 = function(ctx) {
this.stype=ctx.FP.ZERO;
},
- /* this=conj(this) */
+ /**
+ * Conjugation of FP48
+ *
+ * @this {FP48}
+ */
conj: function() {
this.a.conj();
this.b.nconj();
this.c.conj();
},
- /* set this from 3 FP16s */
+ /**
+ * Set FP48 from three FP16 values
+ *
+ * @this {FP48}
+ * @param d FP16 instance
+ * @param e FP16 instance
+ * @param f FP16 instance
+ */
set: function(d, e, f) {
this.a.copy(d);
this.b.copy(e);
@@ -175,7 +249,12 @@ var FP48 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* set this from one ctx.FP16 */
+ /**
+ * Set FP48 from one FP16 value
+ *
+ * @this {FP48}
+ * @param c FP16 instance
+ */
seta: function(d) {
this.a.copy(d);
this.b.zero();
@@ -183,7 +262,11 @@ var FP48 = function(ctx) {
this.stype=ctx.FP.SPARSER
},
- /* Granger-Scott Unitary Squaring */
+ /**
+ * Fast Squaring of an FP48 in "unitary" form
+ *
+ * @this {FP48}
+ */
usqr: function() {
var A = new ctx.FP16(this.a),
B = new ctx.FP16(this.c),
@@ -222,7 +305,11 @@ var FP48 = function(ctx) {
this.reduce();
},
- /* Chung-Hasan SQR2 method from
http://cacr.uwaterloo.ca/techreports/2006/cacr2006-24.pdf */
+ /**
+ * Fast Squaring of an FP48
+ *
+ * @this {FP48}
+ */
sqr: function() {
if (this.stype==ctx.FP.ONE)
return;
@@ -264,7 +351,12 @@ var FP48 = function(ctx) {
this.norm();
},
- /* FP48 full multiplication this=this*y */
+ /**
+ * Full unconditional Multiplication of two FP48s
+ *
+ * @this {FP48}
+ * @param y FP48 instance, the multiplier
+ */
mul: function(y) {
var z0 = new ctx.FP16(this.a),
z1 = new ctx.FP16(0),
@@ -338,8 +430,15 @@ var FP48 = function(ctx) {
/* FP48 multiplication w=w*y */
/* catering for special case that arises from special form of ATE pairing line
function */
-/* w and y are both sparser line functions - cost = 6m */
- smul: function(y) {
+ /* w and y are both sparser line functions - cost = 6m */
+
+ /**
+ * Fast multiplication of two sparse FP48s that arises from ATE
pairing line functions
+ *
+ * @this {FP48}
+ * @param y FP48 instance, the multiplier
+ */
+ smul: function(y) {
if (ctx.ECP.SEXTIC_TWIST==ctx.ECP.D_TYPE)
{
var w1=new ctx.FP8(this.a.geta());
@@ -449,8 +548,15 @@ var FP48 = function(ctx) {
/* FP48 full multiplication w=w*y */
/* Supports sparse multiplicands */
-/* Usually w is denser than y */
- ssmul: function(y) {
+ /* Usually w is denser than y */
+
+ /**
+ * Fast multiplication of what may be sparse multiplicands
+ *
+ * @this {FP48}
+ * @param y FP48 instance, the multiplier
+ */
+ ssmul: function(y) {
if (this.stype==ctx.FP.ONE)
{
this.copy(y);
@@ -645,7 +751,11 @@ var FP48 = function(ctx) {
},
- /* this=1/this */
+ /**
+ * Inverting an FP48
+ *
+ * @this {FP48}
+ */
inverse: function() {
var f0 = new ctx.FP16(this.a),
f1 = new ctx.FP16(this.b),
@@ -692,7 +802,12 @@ var FP48 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* this=this^p, where p=Modulus, using Frobenius */
+ /**
+ * Raises an FP48 to the power of the internal modulus p, using the
Frobenius
+ *
+ * @this {FP48}
+ * @param f Modulus
+ */
frob: function(f,n) {
var f2 = new ctx.FP2(f),
f3 = new ctx.FP2(f),
@@ -715,7 +830,11 @@ var FP48 = function(ctx) {
this.stype=ctx.FP.DENSE;
},
- /* trace function */
+ /**
+ * Calculate the trace of an FP48
+ *
+ * @this {FP48}
+ */
trace: function() {
var t = new ctx.FP16(0);
@@ -726,12 +845,21 @@ var FP48 = function(ctx) {
return t;
},
- /* convert this to hex string */
+ /**
+ * convert this to hex string
+ *
+ * @this {FP48}
+ */
toString: function() {
return ("[" + this.a.toString() + "," + this.b.toString() + "," +
this.c.toString() + "]");
},
- /* convert this to byte array */
+ /**
+ * convert this to byte array
+ *
+ * @this {FP48}
+ * @param w Byte array
+ */
toBytes: function(w) {
var t = [],
i;
@@ -941,7 +1069,12 @@ var FP48 = function(ctx) {
}
},
- /* set this=this^e */
+ /**
+ * Raises an FP48 to the power of a BIG
+ *
+ * @this {FP48}
+ * @param e BIG instance exponent
+ */
pow: function(e) {
var e1, e3, w, nb, i, bt, sf;
@@ -975,7 +1108,13 @@ var FP48 = function(ctx) {
return w;
},
- /* constant time powering by small integer of max length bts */
+ /**
+ * Raises an FP48 instance x to a small integer power, side-channel
resistant
+ *
+ * @this {FP48}
+ * @param e small integer exponent
+ * @param bts maximum number of bits in exponent
+ */
pinpow: function(e, bts) {
var R = [],
i, b;
@@ -992,7 +1131,13 @@ var FP48 = function(ctx) {
this.copy(R[0]);
},
- /* Faster compressed powering for unitary elements */
+ /**
+ * Raises an FP48 instance to a BIG power, compressed to FP4
+ *
+ * @this {FP48}
+ * @param e BIG exponent
+ * @param r BIG group order
+ */
compow: function(e, r) {
var fa, fb, f, q, m, a, b, g1, g2, c, cp, cpm1, cpm2;
@@ -1039,7 +1184,12 @@ var FP48 = function(ctx) {
}
};
- /* convert from byte array to FP12 */
+ /**
+ * convert from byte array to FP48
+ *
+ * @this {FP48}
+ * @param w Byte array
+ */
FP48.fromBytes = function(w) {
var t = [],
i, a, b, c, d, e, f, g, r, ea, eb, fa, fb;
@@ -1331,7 +1481,11 @@ var FP48 = function(ctx) {
return r;
};
- /* return 1 if b==c, no branching */
+ /**
+ * return 1 if b==c, no branching
+ *
+ * @this {FP48}
+ */
FP48.teq = function(b, c) {
var x = b ^ c;
x -= 1; // if x=0, x now -1
@@ -1342,6 +1496,12 @@ var FP48 = function(ctx) {
// Bos & Costello https://eprint.iacr.org/2013/458.pdf
// Faz-Hernandez & Longa & Sanchez https://eprint.iacr.org/2013/158.pdf
// Side channel attack secure
+
+ /**
+ * p=q0^u0.q1^u1.q2^u2.q3^u3...
+ *
+ * @this {FP48}
+ */
FP48.pow16 = function(q, u) {
var g1 = [],
g2 = [],
