@ton/crypto
Version:
[](https://www.npmjs.com/package/@ton/crypto)
174 lines (126 loc) • 6.04 kB
Markdown
# TON crypto
[](https://www.npmjs.com/package/@ton/crypto)
Cross-platform crypto primitives for building apps for TON blockchain. Uses native crypto available in NodeJS or in browser.
## Features
- 🦺 All required crypto for TON and apps
- 💪 Works everywhere: Browser, NodeJS and React Native
- 🚀 Promise-based API
- 🏎 Built on top of Buffer (polyfill required in browsers)
- 🍰 No reimplemented crypto
## Implemented
- SHA-256
- SHA-512
- HMAC-SHA-512
- PBKDF2-SHA-512
- TON Mnemonics
- NaCL sign/verify for signing (used by TON blockchain)
- NaCL sealBox/openBox for symmetric encryption
- SLIP-10 Ed25519 HD Keys (for hierarchical keys)
## Install
```bash
yarn add @ton/crypto buffer
```
#### Browser polyfill
```js
// Add before using library
require("buffer");
```
## React Native
To make it work on react native `expo-crypto` native module is required:
`
expo install expo-crypto
`
## Secure random
```js
import { getSecureRandomBytes, getSecureRandomWords, getSecureRandomNumber, newSecureWords, newSecurePassphrase } from '@ton/crypto';
const randomBytes: Buffer = await getSecureRandomBytes(32); // 32 random bytes
const randomWords: Uint16Array = await getSecureRandomBytes(32); // 64 random bytes packaed into words
const randomNumber: number = await getSecureRandomNumber(0, 10); // Random number from 0 (inclusive) to 10 (exclusive)
const secureWords: string[] = await newSecureWords(12); // Random 12 words from BIP-13 wordlist
const securePassptrase: string = await newSecurePassphrase(10); // Random 10 words that connected by dashes to make it look like password
```
## SHA-256 and SHA-512
All methods accept strings or Buffers as arguments.
```js
import { sha256, sha512, pbkdf2_sha512, hmac_sha512, sha256_sync, sha512_sync } from '@ton/crypto';
// Async methods
const hash1: Buffer = await sha256('hello-world');
const hash2: Buffer = await sha512(Buffer.from('hello-world', 'utf-8'));
// Sync methods
const hash1Sync: Buffer = await sha256_sync('hello-world');
const hash2Sync: Buffer = await sha512_sync('hello-world');
```
## HMAC-SHA-512
```js
const hmac: Buffer = await hmac_sha512('hmac-key', 'data');
```
## PBKDF2-SHA-512
```js
const key: Buffer = await pbkdf2_sha512('password', 'salt', 10000, 64);
```
## TON mnemonics
TON uses BIP-39 styled english mnemonics with custom key deriviation and built-in checksums.
```js
import { mnemonicNew, mnemonicValidate, mnemonicToPrivateKey, mnemonicToWalletKey, mnemonicToSeed, mnemonicWordList, KeyPair, mnemonicToHDSeed } from '@ton/crypto';
const password: string | null | undefined = null; // Optional password
const mnemonics: string[] = await mnemonicNew(24, password); // Generate new menemonics
const mnemonicsValid: boolean = await mnemonicValidate(mnemonics, password); // Validate mnemonics
const keypair1: KeyPair = await mnemonicToPrivateKey(mnemonics, password); // Generates KeyPair from mnemonics
const keypair2: KeyPair = await mnemonicToWalletKey(mnemonics, password); // Generates KeyPair from mnemonics (results are SEEMS TO BE same as above)
const mnemonicsSeed: Buffer = await mnemonicToSeed(mnemonics, 'Seed text', password); // Generates 64 bytes of seed from mnemonics and seed text.
const mnemonicHDSeed: Buffer = await mnemonicToHDSeed(mnemonics, password); // Generates 64 bytes of seed for HD Keys
const wordlist = mnemonicWordList; // BIP39 word list
```
## NaCL-compatible Ed25519 signing
Ed25519 is used by TON in contracts to check signatures.
```js
import { keyPairFromSeed, keyPairFromSecretKey, sign, signVerify, KeyPair } from '@ton/crypto';
const data = Buffer.from('Hello wordl!');
// Create Keypair
const seed: Buffer = await getSecureRandomBytes(32); // Seed is always 32 bytes
const keypair: KeyPair = keyPairFromSeed(seed); // Creates keypair from random seed
const keypair2: KeyPair = keyPairFromSecretKey(keypair.secret); // Creates keypair from secret key
// Sign
const signature = sign(data, keypair.secret); // Creates signature for arbitrary data (it is recommended to get hash from data first)
// Check
const valid: boolean = signVerify(data, signature, keypair.public);
```
## NaCL-compatible symmetrict encryption
```js
import { sealBox, openBox, getSecureRandomBytes } from '@ton/crypto';
const data = Buffer.from('Hello wordl!');
// Encryption
const key: Buffer = await getSecureRandomBytes(32); // Key is always 32 bytes and secret
const nonce: Buffer = await getSecureRandomBytes(24); // Nonce is always 24 bytes and public
const sealed: Buffer = sealBox(data, nonce, key); // Sealed box
// Decryption
const decrypted: Buffer | null = openBox(sealed, nonce, key); // Decrypted with integrity check. null if failed.
```
## SLIP-10 Ed25519 HD Keys
Generates SLIP-10 compatible hierarchy of keys
```js
import { newMnemonics, mnemonicToHDSeed, deriveEd25519Path, KeyPair } from '@ton/crypto';
// Generate HD seed
// You can just generate 64-128 random bytes, but this way you will be able to
// create it from mnemonics that you already have for a wallet
const mnemonics: string[] = await newMnemonics();
const seed: Buffer = await mnemonicToHDSeed(mnemonics);
// Derive secret key from path m/0'/1'/2'/3'
const derivedSeed: Buffer = await deriveEd25519Path(seed, [0, 1, 2, 3]);
// Create key pair
const keyPair: KeyPair = keyPairFromSeed(derivedSeed);
```
## SLIP-21 Symmetric HD Keys
Generates SLIP-21 compatible hierarchy of keys for symmetric encryption.
```js
import { newMnemonics, mnemonicToHDSeed, deriveSymmetricPath, KeyPair } from '@ton/crypto';
// Generate HD seed
// You can just generate 64-128 random bytes, but this way you will be able to
// create it from mnemonics that you already have for a wallet
const mnemonics: string[] = await newMnemonics();
const seed: Buffer = await mnemonicToHDSeed(mnemonics);
// Derive secret key from path m/0'/1'/2'/3'
const derivedKey: Buffer = await deriveSymmetricPath(seed, ['ton-seed', 'some-key', 'some-key2']);
```
# License
MIT