post-e-voting/source-code/scytl-cryptolib/cryptolib-js-messagedigest

Message Digest Module

This module defines the message digest API for Scytl's JavaScript cryptographic library. The starting point for using this module is the instantiation of a message digest service.

How to view, build and test the source code of this module

Start by git cloning the project comm/scytl-cryptolib from Stash.

The source code of this module will be found in the directory scytl-cryptolib/cryptolib-js-messagedigest/lib.

To build this module, change to the directory scytl-cryptolib/cryptolib-js-messagedigest and do the following:

npm install
--or--
mvn clean install -DskipTests

The unit tests of this module will be found in the directory scytl-cryptolib/cryptolib-js-messagedigest/spec. To run the tests, change to the directory scytl-cryptolib/cryptolib-js-messagedigest and do the following:

karma test
--or--
mvn test

To only run a chosen test suite, add an f in front of the corresponding describe statement. For example:

fdescribe('create a message digester that should be able to', function()
...

To only run a chosen test, add an f in front of the corresponding it statement. For example:

fit('generate digests that are deterministic', function() {
...

Note: To build and test the entire scytl-cryptolib project, change to the directory scytl-cryptolib and do the following:

mvn clean install

How to generate the JSDoc for this module

To generate the JSDoc for this module, change to the directory scytl-cryptolib/cryptolib-js-messagedigest, build the module (if not already done) and do the following:

node_modules/.bin/jsdoc lib

This will generate a file called out. Double click on the file out/index.html to view the JSDoc.

How to npm install this module

To npm install this module in standalone mode, do the following:

npm install --registry https://nexus.scytl.net/content/groups/public-npm/ scytl-messagedigest

To npm install this module as a dependency of your own module, do the following:

1. Add the following lines to the dependencies section of your module's package.json file.

   "scytl-bitwise": "^2.1.0",
   "scytl-codec": "^2.1.0",
   "scytl-cryptopolicy": "^2.1.0",
   "scytl-messagedigest": "^2.1.0",
   

2. Make sure that the .npmrc file of your module contains the following line.

   registry=https://nexus.scytl.net/content/groups/public-npm/
   

3. Install all dependencies.

   npm install
   

   How to instantiate a message digest service

The following example shows the default way to create a new instance of a message digest service.

var messageDigest = require('scytl-messagedigest');

var messageDigestService = messageDigest.newService();

The message digest service accepts an optional input argument that can be used to override the default cryptographic policy used for message digest operations. For example, to set the message digest hashing algorithm to SHA512/224, one could do the following.

var cryptoPolicy = require('scytl-cryptopolicy');
var messageDigest = require('scytl-messagedigest');

var myPolicy = cryptoPolicy.newInstance();

myPolicy.primitives.messageDigest.algorithm =
  cryptoPolicy.options.primitives.messageDigest.algorithm.SHA512_224;

var messageDigestService = messageDigest.newService({policy: myPolicy});

Note It is desirable to use the property CryptographicPolicy.options to override the default policy, as shown above, in order to ensure that one is using an option that is allowed by the cryptographic policy.

How to instantiate a message digester

The following example shows how to create a new message digester. This digester will be initialized internally.

var digester = messageDigestService.newDigester();

How to generate a message digest

The following examples show how to generate a message digest from some data. The data can be provided as a string or as a byte array, wrapped in a Uint8Array object. The output will be in the form of a byte array, wrapped in a Uint8Array object. The digester will be automatically reinitialized by the method digest after the digest has been generated.

var codec = require('scytl-codec');
...

var digest = digester.digest('myData');
var digest = digester.digest(new Uint8Array([0x01, 0x02, 0x03]));

How to generate a message digest from multiple data parts

The following example shows how to generate a message digest from multiple data parts by making a call to the update method for each part to add. The digester will be automatically reinitialized by the method digest after the digest has been generated.

var dataParts = ['myData1', 'myData1', 'myData3'];
...

for (var i = 0; i < dataParts.length; i++) {
  digester.update(dataParts[i]);
}
var digest = digester.digester();

--or--

for (var i = 0; i < (dataParts.length-1); i++) {
  digester.update(dataParts[i]);
}
var digest = digester.digester('myData3');

The following example shows how to write the calls shown above in a single line of code, using method chaining:

var digest = digester.update('myData1').update('myData2').update('myData3').digest();

--or--

var digest = digester.update(data1).update(data2).digest(data3);