phoenex Exchange Frontend Cryptography

NPM package phoenex-exchange-crypto to concentrate all cryptography-related stuff in a single component.

Vault

The package provides you with a Vault class. It's capable of cryptography operations such as signing. Helps in building frontend not disclosing user's password to anyone.

openVault factory

Produces a Vault instance from given login and password. Cryptoparameters were intentionally chosen to take at least one second of computations on a modern machine in a browser.

declare function openVault({
  login: string,
  password: string,
}): Promise<Vault>;

Example:

import { openVault } from 'phoenex-exchange-crypto';
import type { Vault } from 'phoenex-exchange-crypto';

// Takes at least one second to compute
const vault: Vault = await openVault({
  login: '[email protected]',
  password: 'Юг. Qwerty $%',
});

Constructor

Builds a new Vault from given private key.

Example:

const vault: Vault = new Vault('');

vault.getPrivateKey

Provides vault's private key. Very useful to keep the key in a local storage and build the same Vault later.

declare function getPrivateKey(): Hex;

Example:

import type { Hex } from 'phoenex-exchange-crypto';

const privateKey: Hex = vault.getPrivateKey(); //=> 'b81dda8d1eb395ba2698bb2f1779be12ee9f3b561f186f8db950bf59742f78fa'

vault.getPublicKey

Provides vault's public key. Very usefult to send that public key to your verifying counterpart.

declare function getPublicKey(): Hex;

Example:

import type { Hex } from 'phoenex-exchange-crypto';

const publicKey: Hex = vault.getPublicKey(); //=> '09dc4e12c6c7d6752599ebdc68ad2207b0d4f50f14d4f5f57d1aef7a851adad82abcb2258d7d30f8076be58de8020e436c9bbf7aef8e0cd2e0f6b12045c3ea5f'

vault.sign

Signs given message. You're able to sign any Serializable (to JSON) value.

Please note that elliptic-curve cryptography generates randomized signatures of the same data (varying from call to call) because of security reasons.

declare function sign(Serializable): Promise<{|
  serializedMessage: string,
  signature: Hex,
|}>;

Example:

import type { Hex } from 'phoenex-exchange-crypto';

const OBJECT = {
  bim: [
    314159265358979,
    null,
    'hello',
  ],
  foo: 'Hello',
  baz: 0.0015,
  boo: 'В чащах \'Юга\' жил-был "цитрусъ"?',
};
const {
  serializedMessage, //=> {"baz":1.5E-3,"bim":[314159265358979,null,"hello"],"boo":"В чащах 'Юга' жил-был \"цитрусъ\"?","foo":"Hello"}
  signature, //=> '5c8cad58a0e419d522b0b22946ebb6914867d03e1518f77e5cfece8b8ee1c94bb2c8733e142e486594c9f83bf29eb93ed9e5580156af138dbe4d38ea801b2eba'
} = await vault.sign(OBJECT);

vault.signHex

Signs bytes from the given hex string.

Please note that elliptic-curve cryptography generates randomized signatures of the same data (varying from call to call) because of security reasons.

declare function signHex(Hex): Promise<Hex>;

Example:

import type { Hex } from 'phoenex-exchange-crypto';

const MESSAGE = 'da19267ec9300915376e1f27c23496619b13aa2ff816a6a544be1766c276dc3d';
await vault.signHex(MESSAGE); //=> '42d0a87644ec207ba67c1126d4cefcd43311711bc6cb575f8a6a2a2164ec894d031460230b90f14ebc8ecab352826719ba76c9c7b0aaa12a686615a14361472f'
await vault.signHex(MESSAGE); //=> '01237d946ad14b2f6c76f354c5254792ac2155039d83c58a5703eaa84b566e5b2f5fde569de5a7b2366c41a2ba29264e72d35038137b30e1a0c494f05e3aaf27'
await vault.signHex(MESSAGE); //=> '04048046dc59622149a748461f48249f3ee6ff8696d8a70b7cab4f50fc35c3a120b4c83f54800a159ef75ff305d6065da795884a0ddc07e3dc26629d23bec076'

How does user registration work?

1. At first our user has only email and password. With createSalt function you can derive salt from the email:

   createSalt('[email protected]') //=> 'acf5771ac43eae908af2918b5e835d2f'

2. After that we're deriving private key from password and salt. For password test1234 and salt acf5771ac43eae908af2918b5e835d2f it will be: 3e6056acb0a3e19a58375df7acb629f8f9d2e1799488d3738963399970807be9

3. After that we're deriving public key from the private key. In our example it will be: 65daa3068523b54475a5e952d18b8831f61d414386411fab9f7c137af7ca167c7b205fa315b97dab12e13efc5c69f1785fc90d4f794d3cade918477f224d5180

Contributing

To contribute to phoenex-exchange-crypto execute the following:

yarn
yarn dev:bootstrap
yarn dev:watch

Now you're able to do yarn link phoenex-exchange-crypto in the project under development to connect it with your copy of the package.

How to publish a new version?

yarn publish:git