universa-js/universajs
Minimalistic Javascript library required to perform basic operations with Universa smart contracts and other objects.
Supports:
Installation
Node.js
For usage in an existing Node.js project, add it to your dependencies:
$ npm install universa-minicrypto
or with yarn:
$ yarn add universa-minicrypto
And use it with the following line wherever you need it:
const Universa = ;
Web
In root folder of package run
npm installnpm run build
In folder dist
there will be universa.min.js
and boss.min.js
. Also there will be *.LICENSE files.
Simply copy dist/universa.min.js
to wherever you keep your vendor scripts and include
it as a script:
Usage
Universa Capsule tools
Sign capsule
const Capsule = Universa; const newCapsuleBin = Capsule; // Uint8Array
Extract signatures
const Capsule = Universa; const signatures = Capsule; // Array[Uint8Array]
Extract signature keys
const Capsule = Universa; const publicKeys = Capsule; // Array[PublicKey]
Signed record
Pack data to signed record (Uint8Array) with key:
const SignedRecord decode64 PrivateKey = Universa; const payload = ab: "cd" ;const nonce = ;const key = PrivateKey; const recordBinary = SignedRecord; // Uint8Array
Unpack signed record:
const SignedRecord decode64 PrivateKey = Universa; const payload = ab: "cd" ;const nonce = ;const key = PrivateKey; const recordBinary = SignedRecord; // Uint8Array const record = SignedRecord; recordrecordType === SignedRecordRECORD_WITH_KEY; // truerecordnonce // noncerecordpayload // payloadrecordkey // PublicKey
Misc
Random byte array for given length
const randomBytes = Universa;const bytes16 = ; // Uint8Array
HashId for binary data
const hashId = Universa;const id = ; // Uint8Array
CRC32
const crc32 = Universa;const digest = ; // Uint8Array
Converters
Convert byte array to hex string and back
const bytesToHex hexToBytes = Universa; const hexString = ; // String const bytesArray = ; // Uint8Array
Convert plain text to bytes and back
const textToBytes bytesToText = Universa; const bytes = ; // Uint8Array const text = ; // "one two three"
Convert bytes to base64 and back
const encode64 encode64Short decode64 = Universa;const bytes = ; // Uint8Arrayconst base64str = ; // String // short representation of base64 stringconst base64ShortString = ;
Convert bytes to base58 and back
const encode58 decode58 = Universa;const bytes = ; // Uint8Arrayconst base58str = ; // String
SHA
Supports SHA256, SHA512, SHA1, SHA3(256, 384, 512)
Get instant hash value for given byte array
const SHA = Universa; // sha3 identifiers: "3_256", "3_384", "3_512"const sha256 = 256; const resultBytes = sha256; // Uint8Array
Get hash value for large data
const SHA = Universa;const sha512 = 512; sha512; // dataPart1 is Uint8Arraysha512;// .....sha512; const resultBytes = sha512; // Uint8Array
Get hash value in HEX
const SHA = Universa;const sha256 = 256;const hexResult = sha256; // String
HMAC
const SHA HMAC = Universa;const data = ;const key = ; const sha256 = '256';const hmac = sha256 key;const result = hmac // Uint8Array
PBKDF2
const hexToBytes pbkdf2 SHA = Universa; const derivedKey = ; // Uint8Array
RSA Pair, keys helpers
Private key unpack
const PrivateKey decode64 BigInteger = Universa; const bossEncodedKey = ; const privateKey1 = 'BOSS' bossEncodedKey;const privateKey2 = PrivateKey;const privateKey3 = 'EXPONENTS' e: eHex 16 p: pHex 16 q: qHex 16; // Read password-protected keyconst privateKey4 = 'BOSS' bin: bossEncodedKey password: "somepassword"const privateKey5 = PrivateKey;
Public key unpack
const PublicKey PrivateKey decode64 BigInteger = Universa; const bossEncodedKey = ;const privateKey2 = 'BOSS' privateEncoded; const publicKey1 = 'BOSS' bossEncodedKey;const publicKey2 = privateKey2publicKey;const publicKey3 = 'EXPONENTS' n: nHex 16 e: eHex 16;const publicKey4 = PublicKey;
Public key fingerprint
publicKey; // fingerprint (Uint8Array)
Public key bit strength
publicKey; // number
Public key address
publicKey; // short address (Uint8Array)publicKey; // short address (Uint8Array)publicKey; // long address (Uint8Array)publicKey; // long address (Uint8Array)
Check if given address is valid
const PublicKey = Universa; PublicKey // true // accepts base58 representation of address tooPublicKey // true
Generate private key
const PrivateKey PublicKey createKeys = Universa; const options = bits: 2048 e: 0x10001 ; ;
Private(public) key - export
const PrivateKey = Universa;const bossEncodedKey = ; const priv = 'BOSS' bossEncodedKey; const hashWithExponents = priv; // hash map with exponentsconst bossEncoded = priv; // Uint8Array const bossEncodedPublic = privpublicKeypacked;
Password-protected Private key export
// default pbkdf2 rounds = 160000const bossEncoded = privateKey; // use custom pbkdf2 roundsconst bossEncodedFast = privateKey;
Get type of key package. There are 4 types of what key binary package may contain.
AbstractKey.TYPE_PRIVATE - binary package of private key without password AbstractKey.TYPE_PUBLIC - binary package of public key without password AbstractKey.TYPE_PRIVATE_PASSWORD_V2 - binary package of private key with password (actual version) AbstractKey.TYPE_PRIVATE_PASSWORD_V1 - binary package of private key with password (deprecated version)
const AbstractKey = Universa; const bossEncoded = privateKey; AbstractKey === AbstractKeyTYPE_PRIVATE_PASSWORD_V2 // true
KEY INFO
Contains information about Key and helper to match keys compatibility
Supported algorithms: RSAPublic, RSAPrivate, AES256
Supported PRF: HMAC_SHA1, HMAC_SHA256, HMAC_SHA512
const KeyInfo = Universa;const keyInfo = algorithm: KeyInfoAlgorithmAES256 tag: // Uint8Array keyLength: 32 // Int prf: KeyInfoPRFHMAC_SHA256 rounds: 16000 // number of iterations salt: // Uint8Array;
Pack to BOSS
const packed = keyInfo; // Uint8Array
Read from BOSS
// bossEncoded is Uint8Arrayconst keyInfo = KeyInfo; // KeyInfo
Check that this key can decrypt other key
const canDecrypt = keyInfo; // boolean
Derived key from password
const derivedKey = keyInfo; // 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; // Creates random key (AES256, CTR)const symmetricKey = ; // Creates key by derived key (Uint8Array) and it's info (KeyInfo)const symmetricKey2 = keyBytes: derivedKey keyInfo: keyInfo; // Creates key by derived key (Uint8Array)const symmetricKey2 = keyBytes: derivedKey; // Creates key by password (String) and number of rounds (Int). Salt is optional// Uint8Array, null by defaultconst symmetricKey3 = SymmetricKey;
Pack symmetric key (get derived key bytes)
const SymmetricKey = Universa; // Creates random key (AES256, CTR)const symmetricKey = ; const derivedKey = symmetricKey; // Uint8Array
Encrypt / decrypt data with AES256 in CRT mode with IV
// data is Uint8Arrayconst encrypted = symmetricKey; // Uint8Arrayconst decrypted = symmetricKey; // Uint8Array
Encrypt / decrypt data with EtA using Sha256-based HMAC
// data is Uint8Arrayconst encrypted = symmetricKey; // Uint8Arrayconst decrypted = symmetricKey; // Uint8Array
RSA OAEP/PSS
OAEP encrypt/decrypt
You can pass hash types with instances or with string types. Supported types for SHA: sha1 sha256 sha384 sha512 sha512/256 sha3_256 sha3_384 sha3_512
const privateKey; // some PrivateKey instanceconst publicKey = privateKeypublicKey; // encrypt dataconst data = ;const options = seed: // optional, default none mgf1Hash: 512 // optional, default SHA(256) oaepHash: 'sha512' // optional, default SHA(256);const encrypted = publicKey;const decrypted = privateKey; === ; // true
OAEP max encryption message length
const privateKey; // some PrivateKey instanceconst publicKey = privateKeypublicKey; // encrypt dataconst options = seed: // optional, default none mgf1Hash: 'SHA512' // optional, default SHA(256) oaepHash: 'SHA512' // optional, default SHA(256); const maxLength = publicKey;
OAEP default hash
publicKeyDEFAULT_OAEP_HASH // SHA1 instance
MGF1 default hash
publicKeyDEFAULT_MGF1_HASH // SHA1 instance
PSS sign/verify
You can pass hash types with instances or with string types. Supported types for SHA: sha1 sha256 sha384 sha512 sha512/256 sha3_256 sha3_384 sha3_512
const privateKey; // some PrivateKey instanceconst publicKey = privateKeypublicKey; const options = salt: // optional saltLength: null // optional, numeric mgf1Hash: 'sha512' // optional, default SHA(256) pssHash: 'sha512' // optional, default SHA(256); const message = 'abc123'; const signature = privateKey;const isCorrect = publicKey;console; // true
Extended signature
Sign/verify
const ExtendedSignature = Universa;const data = ;const privateKey; // some PrivateKey instanceconst publicKey = privateKeypublicKey; const signature = privateKey;const es = publicKey; const isCorrect = !!es;console; // Date - signature created atconsole; // Uint8Array - PublicKey fingerprintconsole; // PublicKey instance
BOSS
Encode/decode
const Boss = Universa;const boss = ; const data = a: b: c: 1 2 'test' d: a: 1 ; const encoded = boss; // Uint8Arrayconst decoded = boss; // original data
Encode stream
const writer = ; writer;writer;writer;writer; const dump = writer; // Uint8Array
Decode stream
const reader = ; const arg1 = reader; // 0const arg2 = reader; // 1const arg3 = reader; // 2const arg4 = reader; // 3const arg5 = reader; // undefined
AES
Encrypt/decrypt
const AES = Universa;const key = ; // 16 bytes for aes128, 32 bytes for aes256const message = ; const aes256 = key;const encrypted = aes256; // Uint8Arrayconst decrypted = aes256; // Uint8Array
Create bundle
Run in package root folder
npm installnpm run build
In folder dist
there will be universa.min.js
and boss.min.js
. Also there will be *.LICENSE files.
Running tests
npm test
NOTES
node-forge has broken method for encoding bytes, it should be replaced with:
utilbinaryraw { return bytes;};