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 741faa2 update JavaScript documentation
741faa2 is described below
commit 741faa285831773c1755d88bc56798a3fc5eeded
Author: Kealan McCusker <[email protected]>
AuthorDate: Thu Jul 18 12:51:51 2019 +0100
update JavaScript documentation
---
src/rand.js | 14 +++----
src/rsa.js | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---
src/sha3.js | 34 ++++++++++++++++-
src/uint64.js | 25 +++++++++++++
4 files changed, 174 insertions(+), 14 deletions(-)
diff --git a/src/rand.js b/src/rand.js
index 17c73d0..d5200a7 100644
--- a/src/rand.js
+++ b/src/rand.js
@@ -32,10 +32,10 @@ var RAND = function(ctx) {
"use strict";
/**
- * Creates an instance of MPIN256
+ * Creates an instance of RAND
*
* @constructor
- * @this {MPIN256}
+ * @this {RAND}
*/
var RAND = function() {
/* Cryptographically strong pseudo-random number generator */
@@ -55,7 +55,7 @@ var RAND = function(ctx) {
/**
* Delete all internal state of a random number generator
*
- * @this {MPIN256}
+ * @this {RAND}
*/
clean: function() {
var i;
@@ -76,7 +76,7 @@ var RAND = function(ctx) {
/**
* Marsaglia & Zaman random number generator
*
- * @this {MPIN256}
+ * @this {RAND}
*/
sbrand: function() {
var i, k, pdiff, t;
@@ -149,7 +149,7 @@ var RAND = function(ctx) {
/**
* Initialize RNG with some real entropy from some external source
*
- * @this {MPIN256}
+ * @this {RAND}
* @param rawlen the number of seed bytes provided
* @param raw an array of seed bytes
*/
@@ -188,7 +188,7 @@ var RAND = function(ctx) {
/**
* Get random byte
*
- * @this {MPIN256}
+ * @this {RAND}
*/
getByte: function() {
var r = this.pool[this.pool_ptr++];
@@ -204,7 +204,7 @@ var RAND = function(ctx) {
/**
* Pack 4 bytes into a 32-bit Word
*
- * @this {MPIN256}
+ * @this {RAND}
*/
RAND.pack = function(b) {
return (((b[3]) & 0xff) << 24) | ((b[2] & 0xff) << 16) | ((b[1] &
0xff) << 8) | (b[0] & 0xff);
diff --git a/src/rsa.js b/src/rsa.js
index d04ba30..7428c14 100644
--- a/src/rsa.js
+++ b/src/rsa.js
@@ -25,6 +25,12 @@ var RSA,
RSA = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of RSA
+ *
+ * @constructor
+ * @this {RSA}
+ */
var RSA = {
RFS: ctx.BIG.MODBYTES * ctx.FF.FFLEN,
SHA256: 32,
@@ -38,6 +44,13 @@ RSA = function(ctx) {
SHA384ID: [0x30, 0x41, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
0x65, 0x03, 0x04, 0x02, 0x02, 0x05, 0x00, 0x04, 0x30],
SHA512ID: [0x30, 0x51, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01,
0x65, 0x03, 0x04, 0x02, 0x03, 0x05, 0x00, 0x04, 0x40],
+ /**
+ * Convert byte array to hex string
+ *
+ * @this {RSA}
+ * @param b byte array
+ * @return s hex string
+ */
bytestohex: function(b) {
var s = "",
len = b.length,
@@ -52,6 +65,13 @@ RSA = function(ctx) {
return s;
},
+ /**
+ * Convert byte array to string
+ *
+ * @this {RSA}
+ * @param b byte array
+ * @return s string
+ */
bytestostring: function(b) {
var s = "",
i;
@@ -63,6 +83,13 @@ RSA = function(ctx) {
return s;
},
+ /**
+ * Convert a string to byte array
+ *
+ * @this {RSA}
+ * @param s string
+ * @return b byte array
+ */
stringtobytes: function(s) {
var b = [],
i;
@@ -74,6 +101,15 @@ RSA = function(ctx) {
return b;
},
+ /**
+ * General purpose hash function
+ *
+ * @this {RSA}
+ * @param sha is the hash type
+ * @param A byte array
+ * @param n Integer
+ * @return R hash value
+ */
hashit: function(sha, A, n) {
var R = [],
H;
@@ -119,6 +155,15 @@ RSA = function(ctx) {
return R;
},
+ /**
+ * RSA Key Pair Generator
+ *
+ * @this {RSA}
+ * @param rng is a pointer to a cryptographically secure random number
generator
+ * @param e the encryption exponent
+ * @param PRIV the output RSA private key
+ * @param PUB the output RSA public key
+ */
KEY_PAIR: function(rng, e, PRIV, PUB) { /* IEEE1363 A16.11/A16.12 more
or less */
var n = PUB.n.length >> 1,
t = new ctx.FF(n),
@@ -225,6 +270,16 @@ RSA = function(ctx) {
}
},
+ /**
+ * PKCS V1.5 padding of a message prior to RSA signature
+ *
+ * @this {RSA}
+ * @param rng is a pointer to a cryptographically secure random number
generator
+ * @param e the encryption exponent
+ * @param PRIV the output RSA private key
+ * @param PUB the output RSA public key
+ * @return true or false
+ */
PKCS15: function(sha, m, w) {
var olen = ctx.FF.FF_BITS / 8,
hlen = sha,
@@ -270,7 +325,16 @@ RSA = function(ctx) {
return true;
},
- /* OAEP Message Encoding for Encryption */
+ /**
+ * OAEP padding of a message prior to RSA encryption
+ *
+ * @this {RSA}
+ * @param sha is the hash type
+ * @param m is the input message
+ * @param rng is a pointer to a cryptographically secure random number
generator
+ * @param P are input encoding parameter string (could be NULL)
+ * @return f is the output encoding, ready for RSA encryption
+ */
OAEP_ENCODE: function(sha, m, rng, p) {
var olen = RSA.RFS - 1,
mlen = m.length,
@@ -333,7 +397,15 @@ RSA = function(ctx) {
return f;
},
- /* OAEP Message Decoding for Decryption */
+ /**
+ * OAEP unpadding of a message after RSA decryption
+ *
+ * @this {RSA}
+ * @param sha is the hash type
+ * @param P are input encoding parameter string (could be NULL)
+ * @param f is the padded message
+ * @return r is the unpadded message
+ */
OAEP_DECODE: function(sha, p, f) {
var olen = RSA.RFS - 1,
SEED = [],
@@ -431,7 +503,12 @@ RSA = function(ctx) {
return r;
},
- /* destroy the Private Key structure */
+ /**
+ * Destroy an RSA private Key
+ *
+ * @this {RSA}
+ * @param PRIV the input RSA private key. Destroyed on output.
+ */
PRIVATE_KEY_KILL: function(PRIV) {
PRIV.p.zero();
PRIV.q.zero();
@@ -440,7 +517,14 @@ RSA = function(ctx) {
PRIV.c.zero();
},
- /* RSA encryption with the public key */
+ /**
+ * RSA encryption of suitably padded plaintext
+ *
+ * @this {RSA}
+ * @param PUB the input RSA public key
+ * @param F is input padded message
+ * @param G is the output ciphertext
+ */
ENCRYPT: function(PUB, F, G) {
var n = PUB.n.getlen(),
f = new ctx.FF(n);
@@ -452,7 +536,14 @@ RSA = function(ctx) {
f.toBytes(G);
},
- /* RSA decryption with the private key */
+ /**
+ * RSA decryption of ciphertext
+ *
+ * @this {RSA}
+ * @param PRIV the input RSA private key
+ * @param G is the input ciphertext
+ * @param F is output plaintext (requires unpadding)
+ */
DECRYPT: function(PRIV, G, F) {
var n = PRIV.p.getlen(),
g = new ctx.FF(2 * n),
@@ -492,6 +583,13 @@ RSA = function(ctx) {
rsa_private_key = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of rsa_private_key
+ *
+ * @constructor
+ * @this {rsa_private_key}
+ * @param n FF length
+ */
var rsa_private_key = function(n) {
this.p = new ctx.FF(n);
this.q = new ctx.FF(n);
@@ -506,6 +604,13 @@ rsa_private_key = function(ctx) {
rsa_public_key = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of rsa_public_key
+ *
+ * @constructor
+ * @this {rsa_private_key}
+ * @param m FF length
+ */
var rsa_public_key = function(m) {
this.e = 0;
this.n = new ctx.FF(m);
diff --git a/src/sha3.js b/src/sha3.js
index 345de82..2c0442e 100644
--- a/src/sha3.js
+++ b/src/sha3.js
@@ -29,6 +29,13 @@
var SHA3 = function(ctx) {
"use strict";
+ /**
+ * Creates an instance of SHA3
+ *
+ * @constructor
+ * @this {SHA3}
+ * @param olen output length
+ */
var SHA3 = function(olen) {
this.length = 0;
this.rate = 0;
@@ -106,7 +113,12 @@ var SHA3 = function(ctx) {
}
},
- /* Initialise Hash function */
+ /**
+ * Initialise an instance of SHA3
+ *
+ * @this {SHA3}
+ * @param olen output length
+ */
init: function(olen) { /* initialise */
var i, j;
for (i = 0; i < 5; i++) {
@@ -120,7 +132,12 @@ var SHA3 = function(ctx) {
this.rate = 200 - 2 * olen;
},
- /* process a single byte */
+ /**
+ * Process a byte for SHA3
+ *
+ * @this {SHA3}
+ * @byt byte of date to be processed
+ */
process: function(byt) { /* process the next message byte */
var i, j, k, b, cnt, el;
@@ -183,6 +200,12 @@ var SHA3 = function(ctx) {
}
},
+ /**
+ * Create fixed length hash output of SHA3
+ *
+ * @this {SHA3}
+ * @param buff byte array to store hash
+ */
hash: function(buff) { /* pad message and finish - supply digest */
var q = this.rate - (this.length % this.rate);
if (q == 1) {
@@ -197,6 +220,13 @@ var SHA3 = function(ctx) {
this.squeeze(buff, this.len);
},
+ /**
+ * Create variable length hash output of SHA3
+ *
+ * @this {SHA3}
+ * @param buff byte array to store hash
+ * @param olen length of the hash
+ */
shake: function(buff, olen) { /* pad message and finish - supply
digest */
var q = this.rate - (this.length % this.rate);
if (q == 1) {
diff --git a/src/uint64.js b/src/uint64.js
index 124497a..4b769c1 100644
--- a/src/uint64.js
+++ b/src/uint64.js
@@ -22,12 +22,27 @@
var UInt64 = function() {
"use strict";
+ /**
+ * Creates an instance of UInt64. Rudimentary unsigned 64-bit type for
SHA384 and SHA512
+ *
+ * @constructor
+ * @this {UInt64}
+ * @param top Top 32 bits
+ * @param bot Bottom 32 bits
+ */
var UInt64 = function(top, bot) {
this.top = top;
this.bot = bot;
};
UInt64.prototype = {
+
+ /**
+ * Add value
+ *
+ * @this {UInt64}
+ * @param y UInt64 value
+ */
add: function(y) {
var t = (this.bot >>> 0) + (y.bot >>> 0),
low = t >>> 0,
@@ -44,11 +59,21 @@ var UInt64 = function() {
return this;
},
+ /**
+ * Copy value
+ *
+ * @this {UInt64}
+ */
copy: function() {
var r = new UInt64(this.top, this.bot);
return r;
},
+ /**
+ * Shift left
+ *
+ * @this {UInt64}
+ */
shlb: function() {
var t = this.bot >>> 24;
this.top = t + (this.top << 8);
