Documentation: Cryptographic Utilities

This page covers documentation of cryptographic utility functions, which offer various operations such as converting bytes to passphrase, converting a passphrase back to bytes, and manipulating byte arrays.

Importing the Utilities

utils.ts

import {
  bytesToPassphrase,
  passphraseToBytes,
  concatUint8Arrays,
  extractVarintPrefixed,
  varintPrefixed,
} from '@skiff-org/skiff-crypto';

Functions Overview

bytesToPassphrase(bytes: Buffer, separator?: string): string

  • Description: Converts a byte array into a mnemonic phrase for verifying users.
  • Parameters:
    • bytes: Buffer - The bytes to convert.
    • separator: string (optional) - The separator to use for words, defaults to a single space.
  • Returns: A passphrase consisting of words translated from input bytes.

passphraseToBytes(passphrase: string | string[]): Buffer

  • Description: Converts a mnemonic phrase back into a series of bytes.
  • Parameters:
    • passphrase: string | string[] - The passphrase as a string or array of words.
  • Returns: The encoded bytes as a Buffer.
  • Throws:
    • PassphraseError: If there is an unrecognized word in the passphrase.
    • ChecksumError: If there is an intermediate or leading checksum failure.

concatUint8Arrays(...u8s: Uint8Array[]): Uint8Array

  • Description: Concatenates several Uint8Arrays together. Equivalent to calling Uint8Array.of(...u8s[0], ...u8s[1], ...), but shouldn't blow up the stack for large arrays.
  • Parameters:
    • ...u8s: Uint8Array[] - Arrays to be concatenated.
  • Returns: A concatenated Uint8Array.

extractVarintPrefixed(o: { bs: Uint8Array }): Uint8Array

  • Description: Extracts a varint-prefixed value from the underlying byte array. A varint is a multi-byte 7-bit encoding of a number representing how many of the following bytes are a part of this field. The 8th bit represents whether or not the number is continued into the next byte.
  • Parameters:
    • o: { bs: Uint8Array } - Object containing a reference to a Uint8Array. Modifies this value in-place.
  • Returns: A Uint8Array representing the extracted chunk.

varintPrefixed(data: Uint8Array): Uint8Array

  • Description: Encodes a Uint8Array with a varint prefix indicating its length.
  • Parameters:
    • data: Uint8Array - The data to be encoded.
  • Returns: A Uint8Array with the varint prefix.

Dependencies

The functions utilize the following libraries:

  • varint: For variable-length integer encoding.
  • buffer: For using Buffer to manipulate byte sequences.

Ensure these libraries are installed and available in your project:

npm install varint buffer

Example Usage

utils.ts

import {
  bytesToPassphrase,
  passphraseToBytes,
  concatUint8Arrays,
  extractVarintPrefixed,
  varintPrefixed,
} from '@skiff-org/skiff-crypto';

// Bytes to passphrase example
const bytes = Buffer.from([72, 101, 108, 108, 111]);
console.log(bytesToPassphrase(bytes));

// Passphrase to bytes example
const passphrase = "word1 word2 word3";
console.log(passphraseToBytes(passphrase

));

// Concatenate Uint8Arrays example
const arr1 = new Uint8Array([1, 2, 3]);
const arr2 = new Uint8Array([4, 5, 6]);
console.log(concatUint8Arrays(arr1, arr2));

// Varint prefixed example
const data = new Uint8Array([7, 8, 9]);
console.log(varintPrefixed(data));

Note

Ensure you have a clear understanding of the cryptographic concepts behind these utilities before using them. Misuse can lead to security vulnerabilities in your application.