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 45ee947 updated js documentation
45ee947 is described below
commit 45ee947aaa90a2f5f71a2b8c08fbeb8d0b216bb4
Author: Kealan McCusker <[email protected]>
AuthorDate: Fri Jul 12 11:25:14 2019 +0100
updated js documentation
---
src/fp.js | 96 +++++++++++++++++++++++++++++-----------------------------
src/gcm.js | 49 +++++++++++++++++++++++++++---
src/hash256.js | 40 +++++++++++++++++++++---
src/hash384.js | 39 +++++++++++++++++++++---
src/hash512.js | 39 +++++++++++++++++++++---
5 files changed, 199 insertions(+), 64 deletions(-)
diff --git a/src/fp.js b/src/fp.js
index 787c533..2c37850 100644
--- a/src/fp.js
+++ b/src/fp.js
@@ -24,10 +24,10 @@ var FP = function(ctx) {
"use strict";
/**
- * Creates an instance of FP2.
+ * Creates an instance of FP.
*
* @constructor
- * @this {FP2}
+ * @this {FP}
* @param x FP / BIG instance
*/
var FP = function(x) {
@@ -65,9 +65,9 @@ var FP = function(ctx) {
FP.prototype = {
/**
- * Set FP2 to zero
+ * Set FP to zero
*
- * @this {FP2}
+ * @this {FP}
*/
zero: function() {
this.XES = 1;
@@ -77,8 +77,8 @@ var FP = function(ctx) {
/**
* copy from a ctx.BIG in ROM
*
- * @this {FP2}
- * @param x FP2 instance to be copied
+ * @this {FP}
+ * @param x FP instance to be copied
*/
rcopy: function(y) {
this.f.rcopy(y);
@@ -88,8 +88,8 @@ var FP = function(ctx) {
/**
* copy from another ctx.BIG
*
- * @this {FP2}
- * @param x FP2 instance to be copied
+ * @this {FP}
+ * @param x FP instance to be copied
*/
bcopy: function(y) {
this.f.copy(y);
@@ -97,10 +97,10 @@ var FP = function(ctx) {
},
/**
- * Copy FP2 to another FP2
+ * Copy FP to another FP
*
- * @this {FP2}
- * @param x FP2 instance to be copied
+ * @this {FP}
+ * @param x FP instance to be copied
*/
copy: function(y) {
this.XES = y.XES;
@@ -124,10 +124,10 @@ var FP = function(ctx) {
},
/**
- * Conditional copy of FP2 number
+ * Conditional copy of FP number
*
- * @this {FP2}
- * @param g FP2 instance
+ * @this {FP}
+ * @param g FP instance
* @param d copy depends on this value
*/
cmove: function(b, d) {
@@ -142,7 +142,7 @@ var FP = function(ctx) {
/**
* Converts from BIG integer to residue form mod Modulus
*
- * @this {FP2}
+ * @this {FP}
*/
nres: function() {
var r, d;
@@ -164,7 +164,7 @@ var FP = function(ctx) {
/**
* Converts from residue form back to BIG integer form
*
- * @this {FP2}
+ * @this {FP}
*/
redc: function() {
var r = new ctx.BIG(0),
@@ -185,7 +185,7 @@ var FP = function(ctx) {
/**
* convert to hex string
*
- * @this {FP2}
+ * @this {FP}
*/
toString: function() {
var s = this.redc().toString();
@@ -193,9 +193,9 @@ var FP = function(ctx) {
},
/**
- * Tests for FP2 equal to zero
+ * Tests for FP equal to zero
*
- * @this {FP2}
+ * @this {FP}
*/
iszilch: function() {
var c=new FP(0); c.copy(this);
@@ -204,9 +204,9 @@ var FP = function(ctx) {
},
/**
- * Reduces all components of possibly unreduced FP2 mod Modulus
+ * Reduces all components of possibly unreduced FP mod Modulus
*
- * @this {FP2}
+ * @this {FP}
*/
reduce: function() {
var q,carry,sr,sb,m = new ctx.BIG(0);
@@ -241,9 +241,9 @@ var FP = function(ctx) {
},
/**
- * Set FP2 to unity
+ * Set FP to unity
*
- * @this {FP2}
+ * @this {FP}
*/
one: function() {
this.f.one();
@@ -251,9 +251,9 @@ var FP = function(ctx) {
},
/**
- * Normalises the components of an FP2
+ * Normalises the components of an FP
*
- * @this {FP2}
+ * @this {FP}
*/
norm: function() {
return this.f.norm();
@@ -262,7 +262,7 @@ var FP = function(ctx) {
/**
* Fast Modular multiplication of two FPs, mod Modulus
*
- * @this {FP2}
+ * @this {FP}
* @param b FP number, the multiplier
*/
mul: function(b) {
@@ -280,9 +280,9 @@ var FP = function(ctx) {
},
/**
- * Multiplication of an FP2 by a small integer
+ * Multiplication of an FP by a small integer
*
- * @this {FP2}
+ * @this {FP}
* @param s integer
*/
imul: function(c) {
@@ -316,9 +316,9 @@ var FP = function(ctx) {
},
/**
- * Fast Squaring of an FP2
+ * Fast Squaring of an FP
*
- * @this {FP2}
+ * @this {FP}
*/
sqr: function() {
var d, t;
@@ -350,8 +350,8 @@ var FP = function(ctx) {
/**
* negate this
*
- * @this {FP2}
- * @param x FP2 instance to be set to one
+ * @this {FP}
+ * @param x FP instance to be set to one
*/
neg: function() {
var m = new ctx.BIG(0),
@@ -373,10 +373,10 @@ var FP = function(ctx) {
},
/**
- * subtraction of two FP2s
+ * subtraction of two FPs
*
- * @this {FP2}
- * @param x FP2 instance
+ * @this {FP}
+ * @param x FP instance
*/
sub: function(b) {
var n = new FP(0);
@@ -398,9 +398,9 @@ var FP = function(ctx) {
},
/**
- * Divide an FP2 by 2
+ * Divide an FP by 2
*
- * @this {FP2}
+ * @this {FP}
*/
div2: function() {
var p;
@@ -425,7 +425,7 @@ var FP = function(ctx) {
/**
* return this^(p-3)/4 or this^(p-5)/8
*
- * @this {FP2}
+ * @this {FP}
*/
fpow: function() {
var i,j,k,bw,w,c,nw,lo,m,n;
@@ -529,9 +529,9 @@ var FP = function(ctx) {
},
/**
- * Inverting an FP2
+ * Inverting an FP
*
- * @this {FP2}
+ * @this {FP}
*/
inverse: function() {
@@ -560,10 +560,10 @@ var FP = function(ctx) {
},
/**
- * Tests for equality of two FP2 instances
+ * Tests for equality of two FP instances
*
- * @this {FP2}
- * @param x FP2 instance to compare
+ * @this {FP}
+ * @param x FP instance to compare
*/
equals: function(a) {
var ft=new FP(0); ft.copy(this);
@@ -579,9 +579,9 @@ var FP = function(ctx) {
},
/**
- * Raises an FP2 to the power of a BIG
+ * Raises an FP to the power of a BIG
*
- * @this {FP2}
+ * @this {FP}
* @param e BIG instance exponent
*/
pow: function(e) {
@@ -621,7 +621,7 @@ var FP = function(ctx) {
/**
* return jacobi symbol (this/Modulus)
*
- * @this {FP2}
+ * @this {FP}
*/
jacobi: function() {
var p = new ctx.BIG(0),
@@ -635,7 +635,7 @@ var FP = function(ctx) {
/**
* Fast Modular square root of a an FP, mod Modulus
*
- * @this {FP2}
+ * @this {FP}
*/
sqrt: function() {
var i, v, r;
@@ -716,7 +716,7 @@ var FP = function(ctx) {
/**
* reduce a ctx.DBIG to a ctx.BIG using a "special" modulus
*
- * @this {FP2}
+ * @this {FP}
*/
FP.mod = function(d) {
var b = new ctx.BIG(0),
diff --git a/src/gcm.js b/src/gcm.js
index 0591972..a77eb87 100644
--- a/src/gcm.js
+++ b/src/gcm.js
@@ -39,6 +39,12 @@
var GCM = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of GCM
+ *
+ * @constructor
+ * @this {GCM}
+ */
var GCM = function() {
this.table = new Array(128);
for (var i = 0; i < 128; i++) {
@@ -63,6 +69,7 @@ var GCM = function(ctx) {
GCM.DECRYPTING = 1;
GCM.prototype = {
+
precompute: function(H) {
var b = [],
i, j, c;
@@ -148,7 +155,15 @@ var GCM = function(ctx) {
this.gf2mul();
},
- /* Initialize GCM mode */
+ /**
+ * Initialize GCM mode
+ *
+ * @this {GCM}
+ * @param nk is the key length in bytes, 16, 24 or 32
+ * @param key the AES key as an array of 16 bytes
+ * @param niv the number of bytes in the Initialisation Vector (IV)
+ * @param iv the IV
+ */
init: function(nk, key, niv, iv) { /* iv size niv is usually 12 bytes
(96 bits). ctx.AES key size nk can be 16,24 or 32 bytes */
var H = [],
b = [],
@@ -196,7 +211,13 @@ var GCM = function(ctx) {
this.status = GCM.ACCEPTING_HEADER;
},
- /* Add Header data - included but not encrypted */
+ /**
+ * Add header (material to be authenticated but not encrypted)
+ *
+ * @this {GCM}
+ * @param header is the header material to be added
+ * @param len the number of bytes in the header
+ */
add_header: function(header, len) { /* Add some header. Won't be
encrypted, but will be authenticated. len is length of header */
var i, j = 0;
@@ -256,7 +277,14 @@ var GCM = function(ctx) {
return true;
},
- /* Add Plaintext - included and encrypted */
+ /**
+ * Add plaintext and extract ciphertext
+ *
+ * @this {GCM}
+ * @param plain is the plaintext material to be added
+ * @param len the number of bytes in the plaintext
+ * @return cipher is the ciphertext generated
+ */
add_plain: function(plain, len) {
var B = [],
b = [],
@@ -311,7 +339,14 @@ var GCM = function(ctx) {
return cipher;
},
- /* Add Ciphertext - decrypts to plaintext */
+ /**
+ * Add Ciphertext - decrypts to plaintext
+ *
+ * @this {GCM}
+ * @param cipher is the ciphertext to be added
+ * @param len the number of bytes in the plaintext
+ * @return plain is the plaintext material generated
+ */
add_cipher: function(cipher, len) {
var B = [],
b = [],
@@ -369,6 +404,12 @@ var GCM = function(ctx) {
return plain;
},
+ /**
+ * Finish off and extract authentication tag (HMAC)
+ *
+ * @this {GCM}
+ * @return tag is the output 16 byte authentication tag
+ */
/* Finish and extract Tag */
finish: function(extract) { /* Finish off GHASH and extract tag (MAC)
*/
var tag = [],
diff --git a/src/hash256.js b/src/hash256.js
index 99b36f2..b0d3000 100644
--- a/src/hash256.js
+++ b/src/hash256.js
@@ -20,6 +20,12 @@
var HASH256 = function() {
"use strict";
+ /**
+ * Creates an instance of HASH256
+ *
+ * @constructor
+ * @this {HASH256}
+ */
var HASH256 = function() {
this.length = [];
this.h = [];
@@ -28,6 +34,7 @@ var HASH256 = function() {
};
HASH256.prototype = {
+
transform: function() { /* basic transformation step */
var a, b, c, d, e, f, g, hh, t1, t2, j;
@@ -68,7 +75,11 @@ var HASH256 = function() {
},
- /* Initialise Hash function */
+ /**
+ * Initialise Hash function
+ *
+ * @this {HASH256}
+ */
init: function() { /* initialise */
var i;
@@ -86,7 +97,12 @@ var HASH256 = function() {
this.h[7] = HASH256.H[7];
},
- /* process a single byte */
+ /**
+ * Process a single byte
+ *
+ * @this {HASH256}
+ * @param byt byte to be included in hash
+ */
process: function(byt) { /* process the next message byte */
var cnt;
@@ -105,14 +121,24 @@ var HASH256 = function() {
}
},
- /* process an array of bytes */
+ /**
+ * Process an array of bytes
+ *
+ * @this {HASH256}
+ * @param b byte arrray to be included in hash
+ */
process_array: function(b) {
for (var i = 0; i < b.length; i++) {
this.process(b[i]);
}
},
- /* process a 32-bit integer */
+ /**
+ * Process a 32-bit integer
+ *
+ * @this {HASH256}
+ * @param n Integer to be included in hash
+ */
process_num: function(n) {
this.process((n >> 24) & 0xff);
this.process((n >> 16) & 0xff);
@@ -120,6 +146,12 @@ var HASH256 = function() {
this.process(n & 0xff);
},
+ /**
+ * Generate 32-byte hash
+ *
+ * @this {HASH256}
+ * @return digest 32-byte hash
+ */
hash: function() { /* pad message and finish - supply digest */
var digest = [],
len0, len1, i;
diff --git a/src/hash384.js b/src/hash384.js
index 9c2941d..405f7c6 100644
--- a/src/hash384.js
+++ b/src/hash384.js
@@ -20,6 +20,12 @@
var HASH384 = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of HASH384
+ *
+ * @constructor
+ * @this {HASH384}
+ */
var HASH384 = function() {
this.length = [];
this.h = [];
@@ -73,7 +79,11 @@ var HASH384 = function(ctx) {
this.h[7].add(hh);
},
- /* Initialise Hash function */
+ /**
+ * Initialise Hash function
+ *
+ * @this {HASH384}
+ */
init: function() { /* initialise */
var i;
@@ -92,7 +102,12 @@ var HASH384 = function(ctx) {
this.h[7] = HASH384.H[7].copy();
},
- /* process a single byte */
+ /**
+ * Process a single byte
+ *
+ * @this {HASH384}
+ * @param byt byte to be included in hash
+ */
process: function(byt) { /* process the next message byte */
var cnt, e;
@@ -113,14 +128,24 @@ var HASH384 = function(ctx) {
}
},
- /* process an array of bytes */
+ /**
+ * Process an array of bytes
+ *
+ * @this {HASH384}
+ * @param b byte arrray to be included in hash
+ */
process_array: function(b) {
for (var i = 0; i < b.length; i++) {
this.process(b[i]);
}
},
- /* process a 32-bit integer */
+ /**
+ * Process a 32-bit integer
+ *
+ * @this {HASH384}
+ * @param n Integer to be included in hash
+ */
process_num: function(n) {
this.process((n >> 24) & 0xff);
this.process((n >> 16) & 0xff);
@@ -128,6 +153,12 @@ var HASH384 = function(ctx) {
this.process(n & 0xff);
},
+ /**
+ * Generate 32-byte hash
+ *
+ * @this {HASH384}
+ * @return digest 32-byte hash
+ */
hash: function() { /* pad message and finish - supply digest */
var digest = [],
len0, len1,
diff --git a/src/hash512.js b/src/hash512.js
index eb468a6..bede51a 100644
--- a/src/hash512.js
+++ b/src/hash512.js
@@ -20,6 +20,12 @@
var HASH512 = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of HASH512
+ *
+ * @constructor
+ * @this {HASH512}
+ */
var HASH512 = function() {
this.length = [];
this.h = [];
@@ -74,7 +80,11 @@ var HASH512 = function(ctx) {
this.h[7].add(hh);
},
- /* Initialise Hash function */
+ /**
+ * Initialise Hash function
+ *
+ * @this {HASH512}
+ */
init: function() { /* initialise */
var i;
@@ -94,7 +104,12 @@ var HASH512 = function(ctx) {
this.h[7] = HASH512.H[7].copy();
},
- /* process a single byte */
+ /**
+ * Process a single byte
+ *
+ * @this {HASH512}
+ * @param byt byte to be included in hash
+ */
process: function(byt) { /* process the next message byte */
var cnt, e;
@@ -115,14 +130,24 @@ var HASH512 = function(ctx) {
}
},
- /* process an array of bytes */
+ /**
+ * Process an array of bytes
+ *
+ * @this {HASH512}
+ * @param b byte arrray to be included in hash
+ */
process_array: function(b) {
for (var i = 0; i < b.length; i++) {
this.process(b[i]);
}
},
- /* process a 32-bit integer */
+ /**
+ * Process a 32-bit integer
+ *
+ * @this {HASH512}
+ * @param n Integer to be included in hash
+ */
process_num: function(n) {
this.process((n >> 24) & 0xff);
this.process((n >> 16) & 0xff);
@@ -130,6 +155,12 @@ var HASH512 = function(ctx) {
this.process(n & 0xff);
},
+ /**
+ * Generate 32-byte hash
+ *
+ * @this {HASH512}
+ * @return digest 32-byte hash
+ */
hash: function() { /* pad message and finish - supply digest */
var digest = [],
len0, len1, i;
