Unicrypto JavaScript API

There are multiple API libraries providing access to Universa functionality from JavaScript code, and multiple legacy APIs (which can be used but it is not recommended):

Unicrypto JavaScript API – UniversaBlockchain/unicrypto-js, npm:unicrypto – minimal library for basic operations over smart contracts: low-level parsing, creation and cryptography; TypeScript and WASM-based.
Universa-core JavaScript API – UniversaBlockchain/universa-core-js, npm:universa-core – full-featured class-based API for all operations with Universa smart contracts and network.

Minimalistic JavaScript library required to perform basic operations with Universa smart contracts/transaction packs.

Supports:

SHA family
HMAC
PBKDF2
RSA OAEP/PSS
AES256, AES512
BOSS

History

Installation

Node.js

For usage in an existing Node.js project, add it to your dependencies:

$ npm install unicrypto

or with yarn:

$ yarn add unicrypto

And use it with the following line wherever you need it:

const Universa = require('unicrypto');

Web

In root folder of package run

npm install
npm run build

In folder build there will be universa.js and boss.js. To enable RSA keys generation, you will need provide path to vendor/worker.js

Simply copy build/universa.js to wherever you keep your vendor scripts and include it as a script:

<script src="path/to/universa.js"></script>

Usage

Universa Capsule tools

Sign capsule

const { Capsule } = Universa;

const newCapsuleBin = Capsule.sign(capsuleBin, privateKey); // Uint8Array

Extract signatures

const { Capsule } = Universa;

const signatures = Capsule.getSignatures(capsuleBin); // Array[Uint8Array]

Extract signature keys

const { Capsule } = Universa;

const publicKeys = Capsule.getSignatureKeys(capsuleBin); // Array[PublicKey]

Misc

Random byte array for given length

const { randomBytes } = Universa.utils;
const bytes16 = randomBytes(16); // Uint8Array

HashId for binary data

const { hashId } = Universa.utils;
const id = hashId(decode64("abc")); // Uint8Array

CRC32

const { crc32 } = Universa.utils;
const digest = crc32(decode64("abc")); // Uint8Array

Converters

Convert byte array to hex string and back

    const { bytesToHex, hexToBytes } = Universa.utils;
    const hexString = bytesToHex(uint8arr);  // String
    const bytesArray = hexToBytes(hexString); // Uint8Array

Convert plain text to bytes

  const { textToBytes } = Universa.utils;
  textToBytes("one two three") // Uint8Array

Convert bytes to base64 and back

const { encode64, decode64 } = Universa.utils;
const bytes = decode64("abc"); // Uint8Array
const base64str = encode64(bytes); // String

Convert bytes to base58 and back

const { encode58, decode58 } = Universa.utils;
const bytes = decode58("abc"); // Uint8Array
const base58str = encode58(bytes); // String

SHA

Supports SHA256, SHA512, SHA1, SHA3(256, 384, 512)

Get instant hash value for given byte array

const { SHA } = Universa.hash;

// sha3 identifiers: "3_256", "3_384", "3_512"
const sha256 = new SHA(256);

const resultBytes = sha256.get(textToBytes('somevalue')); // Uint8Array

Get hash value for large data

const { SHA } = Universa.hash;
const sha512 = new SHA(512);

sha512.put(dataPart1); // dataPart1 is Uint8Array
sha512.put(dataPart2);
// .....
sha512.put(dataPartFinal);

const resultBytes = sha512.get(); // Uint8Array

Get hash value in HEX

const { SHA } = Universa.hash;
const sha256 = new SHA(256);
const hexResult = sha256.get(textToBytes("one two three"), 'hex'); // String

HMAC

const { SHA, HMAC } = Universa.hash;
const data = textToBytes('a quick brown for his done something disgusting');
const key = textToBytes('1234567890abcdef1234567890abcdef');

const sha256 = new SHA('256');
const hmac = new HMAC(sha256, key);
const result = hmac.get(data) // Uint8Array

PBKDF2

const { hexToBytes } = Universa.utils;
const { pbkdf2 } = Universa.pki;
const { SHA } = Universa.hash;

const derivedKey = pbkdf2(new SHA('256'), {
  iterations: 1, // number of iterations
  keyLength: 20  // bytes length
  password: 'password',
  salt: hexToBytes('abc123'),
}); // Uint8Array

RSA Pair, keys helpers

Private key unpack

const { PrivateKey } = Universa.pki;
const { decode64, BigInteger } = Universa.utils;

const bossEncodedKey = decode64(keyPacked64);

const privateKey1 = new PrivateKey('BOSS', bossEncodedKey);
const privateKey2 = new PrivateKey('EXPONENTS', {
  e: new BigInteger(eHex, 16),
  p: new BigInteger(pHex, 16),
  q: new BigInteger(qHex, 16)
});

// Read password-protected key
const privateKey3 = new PrivateKey('BOSS', {
  bin: bossEncodedKey,
  password: "somepassword"
})

Public key unpack

const { PublicKey, PrivateKey } = Universa.pki;
const { decode64, BigInteger } = Universa.utils;

const bossEncodedKey = decode64(keyPacked64);
const privateKey2 = new PrivateKey('BOSS', privateEncoded);

const publicKey1 = new PublicKey('BOSS', bossEncodedKey);
const publicKey2 = privateKey2.publicKey;
const publicKey3 = new PublicKey('EXPONENTS', {
  n: new BigInteger(nHex, 16),
  e: new BigInteger(eHex, 16),
});

Public key fingerprint

publicKey.fingerprint(); // fingerprint (Uint8Array)

Public key address

publicKey.address();               // short address (Uint8Array)
publicKey.shortAddress();          // short address (Uint8Array)
publicKey.address({ long: true }); // long address (Uint8Array)
publicKey.longAddress();           // long address (Uint8Array)

Generate private key

const { PrivateKey, PublicKey } = Universa.pki;
const { createKeys } = Universa.pki.rsa;

const options = { bits: 2048, e: 0x10001 };

createKeys(options, (err, pair) => {
  console.log(pair.publicKey instanceof PublicKey); // true
  console.log(pair.privateKey instanceof PrivateKey); // true
});

Private(public) key - export

const { PrivateKey } = Universa.pki;
const bossEncodedKey = decode64(keyPacked64);

const priv = new PrivateKey('BOSS', bossEncodedKey);

const hashWithExponents = priv.pack('EXPONENTS'); // hash map with exponents
const bossEncoded = priv.pack('BOSS'); // Uint8Array

Password-protected Private key export

// default pbkdf2 rounds = 160000
const bossEncoded = privateKey.pack("BOSS", "somepassword");

// use custom pbkdf2 rounds
const bossEncodedFast = privateKey.pack("BOSS", {
  password: "somepassword",
  rounds: 16000
});

KEY INFO

Contains information about Key and helper to match keys compatibility

Supported algorithms: RSAPublic, RSAPrivate, AES256

Supported PRF: HMACSHA1, HMACSHA256, HMAC_SHA512

const { KeyInfo} = Universa.pki;
const keyInfo = new KeyInfo({
  algorithm: KeyInfo.Algorithm.AES256,
  tag: decode64("abc"), // Uint8Array
  keyLength: 32,        // Int
  prf: KeyInfo.PRF.HMAC_SHA256,
  rounds: 16000,        // number of iterations
  salt: decode64("bcd") // Uint8Array
});

Pack to BOSS

const packed = keyInfo.pack(); // Uint8Array

Read from BOSS

// bossEncoded is Uint8Array
const keyInfo = KeyInfo.unpack(bossEncoded); // KeyInfo

Check that this key can decrypt other key

const canDecrypt = keyInfo.matchType(otherKeyInfo); // boolean

Derived key from password

const derivedKey = keyInfo.derivePassword("somepassword"); // Uint8Array

SYMMETRIC KEY

Symmetric key: main interface to the symmetric cipher. This implementation uses AES256 in CTR mode with IV to encrypt / decrypt.

const { SymmetricKey } = Universa.pki;

// Creates random key (AES256, CTR)
const symmetricKey = new SymmetricKey();

// Creates key by derived key (Uint8Array) and it's info (KeyInfo)
const symmetricKey2 = new SymmetricKey({
  keyBytes: derivedKey,
  keyInfo: keyInfo
});

// Creates key by derived key (Uint8Array)
const symmetricKey2 = new SymmetricKey({
  keyBytes: derivedKey
});

// Creates key by password (String) and number of rounds (Int). Salt is optional
// Uint8Array, null by default
const symmetricKey3 = SymmetricKey.fromPassword(password, rounds, salt);

Pack symmetric key (get derived key bytes)

const { SymmetricKey } = Universa.pki;

// Creates random key (AES256, CTR)
const symmetricKey = new SymmetricKey();

const derivedKey = symmetricKey.pack(); // Uint8Array

Encrypt / decrypt data with AES256 in CRT mode with IV

// data is Uint8Array
const encrypted = symmetricKey.encrypt(data); // Uint8Array
const decrypted = symmetricKey.decrypt(encrypted); // Uint8Array

Encrypt / decrypt data with EtA using Sha256-based HMAC

// data is Uint8Array
const encrypted = symmetricKey.etaEncrypt(data); // Uint8Array
const decrypted = symmetricKey.etaDecrypt(encrypted); // Uint8Array

RSA OAEP/PSS

OAEP encrypt/decrypt

const privateKey; // some PrivateKey instance
const publicKey = privateKey.publicKey;

// encrypt data
const data = decode64("abc123");
const options = {
  seed: decode64("abcabc"), // optional, default none
  mgf1Hash: new SHA(512), // optional, default SHA(256)
  oaepHash: new SHA(512) // optional, default SHA(256)
};
const encrypted = publicKey.encrypt(data, options);
const decrypted = privateKey.decrypt(encrypted, options);

encode64(data) === encode64(decrypted); // true

PSS sign/verify

const privateKey; // some PrivateKey instance
const publicKey = privateKey.publicKey;

const options = {
  salt: decode64("abcabc"), // optional
  saltLength: null, // optional, numeric
  mgf1Hash: new SHA(512), // optional, default SHA(256)
  pssHash: new SHA(512) // optional, default SHA(256)
};

const message = 'abc123';

const signature = privateKey.sign(message, options);
const isCorrect = publicKey.verify(message, signature, options);
console.log(isCorrect); // true

Extended signature

Sign/verify

const { ExtendedSignature } = Universa.pki;
const data = decode64("abcde12345");
const privateKey; // some PrivateKey instance
const publicKey = privateKey.publicKey;

const signature = privateKey.signExtended(data);
const es = publicKey.verifyExtended(signature, data);

const isCorrect = !!es;
console.log(es.created_at); // Date - signature created at
console.log(es.key); // Uint8Array - PublicKey fingerprint
console.log(ExtendedSignature.extractPublicKey(signature)); // PublicKey instance

BOSS

Encode/decode

const { Boss } = Universa;
const boss = new Boss();

const data = {
  a: decode64("abc")
  b: new Date(),
  c: [1, 2, 'test'],
  d: { a: 1 }
};

const encoded = boss.dump(data); // Uint8Array
const decoded = boss.load(encoded); // original data

Encode stream

const writer = new Boss.writer();

writer.write(0);
writer.write(1);
writer.write(2);
writer.write(3);

const dump = writer.get(); // Uint8Array

Decode stream

const reader = new Boss.reader(hexToBytes('00081018'));

const arg1 = reader.read(); // 0
const arg2 = reader.read(); // 1
const arg3 = reader.read(); // 2
const arg4 = reader.read(); // 3
const arg5 = reader.read(); // undefined

AES

Encrypt/decrypt

const { AES } = Universa.cipher;
const key = decode64("abc"); // 16 bytes for aes128, 32 bytes for aes256
const message = textToBytes('some text');

const aes256 = new AES(key);
const encrypted = aes256.encrypt(message);   // Uint8Array
const decrypted = aes256.decrypt(encrypted); // Uint8Array

Create bundle

Run in package root folder

npm install
npm run build

In folder build there will be universa.js and boss.js. To enable RSA keys generation, you will need provide path to vendor/worker.js

Running tests

mocha

NOTES

node-forge has broken method for encoding bytes, it should be replaced with:

util.binary.raw.encode = function(bytes) {
  return bytes.reduce(function (data, byte) {
    return data + String.fromCharCode(byte);
  }, '');
};