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

Codec Module

This module defines the codec utilities API for Scytl's JavaScript cryptographic library.

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-codec/lib.

To build this module, change to the directory scytl-cryptolib/cryptolib-js-codec 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-codec/spec. To run the tests, change to the directory scytl-cryptolib/cryptolib-js-codec and do the following:

karma test
--or--
mvn test

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

fit('UTF-8 encode a string', 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-codec, 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-codec

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

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

   "scytl-codec": "^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 UTF-8 encode and decode a string

The following example shows how to UTF-8 encode and decode a string. The output of the UTF-8 encoding method will be a byte array, wrapped in a Uint8Array object.

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

var str = 'myString';

var encoded = codec.utf8Encode(str);
var decoded = codec.utf8Decode(encoded);

expect(decoded).toBe(str);

How to convert a BigInteger object to and from bytes

The following example shows how to convert a BigInteger object to and from bytes. The output of the bigIntegerToBytes method will be in the form of a byte array, wrapped in a Uint8Array object.

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

var bigInt = new BigInteger('85');

var bytes = codec.bigIntegerToBytes(bigInt);
var bigIntFromBytes = codec.bytesToBigInteger(bytes);

expect(bigIntFromBytes).toEqual(bigInt);

How to Base64 encode and decode some data

The following example shows how to Base64 encode and decode some bytes. The output of the Base64 encoding method will be a string.

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

var bytes = new Uint8Array([105, 73, 99]);

var encoded = codec.base64Encode(bytes);
var decoded = codec.base64Decode(encoded);

expect(decoded).toEqual(bytes);

The following example shows how to Base64 encode and decode a string. The output of the Base64 encoding method will be a string. The output of the Base64 decoding method will be a byte array, wrapped in a Uint8Array object, and it must be UTF-8 decoded to retrieve the string.

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

var str = 'myString';

var encoded = codec.base64Encode(str);
var decoded = codec.base64Decode(encoded);
var decodedStr = codec.utf8Decode(decoded);

expect(decodedStr).toBe(str);

The following example shows how to Base64 encode and decode a BigInteger object. The output of the Base64 encoding method will be a string. The output of the Base64 decoding method will be a byte array, wrapped in a Uint8Array object, and it must be converted to retrieve the BigInteger object.

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

var bigInt = new BigInteger('120');

var encoded = codec.base64Encode(bigInt);
var decoded = codec.base64Decode(encoded);
var decodedBigInt = codec.bytesToBigInteger(decoded);

expect(decodedBigInt).toEqual(bigInt);

How to hexadecimally encode and decode some data

The following example shows how to hexadecimally encode and decode some bytes. The output of the hexadecimal encoding method will be a string.

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

var bytes = new Uint8Array([23, 33, 90]);

var encoded = codec.hexEncode(bytes);
var decoded = codec.hexDecode(encoded);

expect(decoded).toEqual(bytes);

The following example shows how to hexadecimally encode and decode a string. The output of the hexadecimal encoding method will be a string. The output of the hexadecimal decoding method will be a byte array, wrapped in a Uint8Array object, and it must be UTF-8 decoded to retrieve the string.

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

var str = 'myString';

var encoded = codec.hexEncode(str);
var decoded = codec.hexDecode(encoded);
var decodedStr = codec.utf8Decode(decoded);

expect(decodedStr).toBe(str);

The following example shows how to hexadecimally encode and decode a BigInteger object. The output of the hexadecimal encoding method will be a string. The output of the hexadecimal decoding method will be a byte array, wrapped in a Uint8Array object, and it must be converted to retrieve the BigInteger object.

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

var bigInt = new BigInteger('35');

var encoded = codec.hexEncode(bigInt);
var decoded = codec.hexDecode(encoded);
var decodedBigInt = codec.bytesToBigInteger(decoded);

expect(decodedBigInt).toEqual(bigInt);

How to binary encode and decode some bytes

WARNING: The methods described here are DEPRECATED. They are primarily intended for internal use by the library, in order to handle the conversion between Uint8Array objects and the binary encoded strings defined by earlier versions of forge to represent byte arrays, before Uint8Array objects were in widespread use. The only reason you would need these methods would be if you were working with forge directly, rather than using this library.

The following example shows how to binary encode and decode some bytes. The output of the binary encoding method will be a string.

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

var bytes = new Uint8Array([5, 16, 9]);

var encoded = codec.binaryEncode(bytes);
var decoded = codec.binaryDecode(encoded);

expect(decoded).toEqual(bytes);