@parity/product-sdk-crypto

Exports

Functions

Interfaces

Type Aliases

Variables

Functions

aesGcmDecrypt()

Decrypt binary data with AES-256-GCM.

aesGcmDecrypt(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): Uint8Array

Parameters

• ciphertext: Data to decrypt (includes the 16-byte GCM auth tag).
• key: 32-byte AES-256 key (must match the encryption key).
• nonce: 12-byte nonce used during encryption.

Returns

The decrypted plaintext as a Uint8Array.

Throws

• If key is not 32 bytes, or if decryption/authentication fails.

aesGcmDecryptPacked()

Decrypt a packed AES-256-GCM buffer (nonce prepended to ciphertext).

Input format: nonce(12) || ciphertext.

aesGcmDecryptPacked(packed: Uint8Array, key: Uint8Array): Uint8Array

Parameters

• packed: The packed buffer to decrypt.
• key: 32-byte AES-256 key.

Returns

The decrypted plaintext as a Uint8Array.

Throws

• If key is not 32 bytes, the packed data is too short, or authentication fails.

aesGcmDecryptText()

Decrypt AES-256-GCM ciphertext back to a UTF-8 string.

aesGcmDecryptText(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): string

Parameters

• ciphertext: Data to decrypt.
• key: 32-byte AES-256 key.
• nonce: 12-byte nonce used during encryption.

Returns

The decrypted plaintext string.

Throws

• If decryption or authentication fails.

aesGcmEncrypt()

Encrypt binary data with AES-256-GCM.

Generates a random 12-byte nonce and returns it alongside the ciphertext. The ciphertext includes the 16-byte authentication tag appended by GCM.

aesGcmEncrypt(data: Uint8Array, key: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array }

Parameters

• data: Binary data to encrypt.
• key: 32-byte AES-256 key.

Returns

Object containing the ciphertext and the random nonce used.

Throws

• If key is not exactly 32 bytes.

Examples

import { aesGcmEncrypt, aesGcmDecrypt } from "@parity/product-sdk-crypto";
import { randomBytes } from "@parity/product-sdk-crypto";
 
const key = randomBytes(32);
const { ciphertext, nonce } = aesGcmEncrypt(data, key);
const plaintext = aesGcmDecrypt(ciphertext, key, nonce);

aesGcmEncryptPacked()

Encrypt binary data with AES-256-GCM, returning a single packed buffer.

Output format: nonce(12) || ciphertext. This is the convention used by the triangle-js-sdks session encryption and mark3t file encryption.

aesGcmEncryptPacked(data: Uint8Array, key: Uint8Array): Uint8Array

Parameters

• data: Binary data to encrypt.
• key: 32-byte AES-256 key.

Returns

Single Uint8Array with nonce prepended to ciphertext.

Throws

• If key is not exactly 32 bytes.

Examples

const packed = aesGcmEncryptPacked(data, key);
const plaintext = aesGcmDecryptPacked(packed, key);

aesGcmEncryptText()

Encrypt a UTF-8 string with AES-256-GCM.

Convenience wrapper that encodes the string to bytes before encrypting.

aesGcmEncryptText(plaintext: string, key: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array }

Parameters

• plaintext: The string to encrypt.
• key: 32-byte AES-256 key.

Returns

Object containing the ciphertext and the random nonce used.

Throws

• If key is not exactly 32 bytes.

blake2b256()

Compute a 32-byte BLAKE2b-256 hash.

This is the default hash algorithm used by the Polkadot ecosystem and the Bulletin Chain. Deterministic: same input always produces the same output.

blake2b256(data: Uint8Array): Uint8Array

Parameters

• data: Arbitrary bytes to hash.

Returns

32-byte BLAKE2b-256 digest.

Examples

import { blake2b256, bytesToHex } from "@parity/product-sdk-crypto";
 
const hash = blake2b256(new TextEncoder().encode("hello"));
console.log(bytesToHex(hash)); // 64-char hex string

boxDecrypt()

NaCl box decrypt: authenticated decryption where both sender and recipient are known.

Input format: nonce(24) || ciphertext.

boxDecrypt(packed: Uint8Array, senderPublicKey: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array

Parameters

• packed: The packed message produced by boxEncrypt.
• senderPublicKey: The sender’s 32-byte Curve25519 public key.
• recipientSecretKey: The recipient’s 32-byte Curve25519 secret key.

Returns

The decrypted plaintext bytes.

Throws

• If the packed data is too short, or decryption/authentication fails.

boxEncrypt()

NaCl box encrypt: authenticated encryption where both sender and recipient are known.

Uses X25519 for key agreement and XSalsa20-Poly1305 for encryption. Output format: nonce(24) || ciphertext (ciphertext includes 16-byte auth tag).

boxEncrypt(message: Uint8Array, recipientPublicKey: Uint8Array, senderSecretKey: Uint8Array): Uint8Array

Parameters

• message: The plaintext bytes to encrypt.
• recipientPublicKey: The recipient’s 32-byte Curve25519 public key.
• senderSecretKey: The sender’s 32-byte Curve25519 secret key.

Returns

A single Uint8Array with nonce prepended to ciphertext.

Throws

• If encryption fails.

Examples

import { boxEncrypt, boxDecrypt } from "@parity/product-sdk-crypto";
import nacl from "tweetnacl";
 
const alice = nacl.box.keyPair();
const bob = nacl.box.keyPair();
 
const packed = boxEncrypt(message, bob.publicKey, alice.secretKey);
const plaintext = boxDecrypt(packed, alice.publicKey, bob.secretKey);

bytesToHex()

Convert byte array to hex string. Uses the built-in function when available and assumes it matches the tested fallback semantics.

bytesToHex(bytes: TArg<Uint8Array<ArrayBufferLike>>): string

Parameters

• bytes: bytes to encode

Returns

Lowercase hexadecimal string.

Throws

• On wrong argument types. TypeError

Examples

Convert bytes to lowercase hexadecimal.

bytesToHex(Uint8Array.from([0xca, 0xfe, 0x01, 0x23])); // 'cafe0123'

chachaDecrypt()

Decrypt binary data with ChaCha20-Poly1305 (RFC 8439).

chachaDecrypt(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): Uint8Array

Parameters

• ciphertext: Data to decrypt (includes 16-byte Poly1305 tag).
• key: 32-byte encryption key.
• nonce: 12-byte nonce used during encryption.

Returns

The decrypted plaintext.

Throws

• If key is not 32 bytes, or if decryption/authentication fails.

chachaDecryptText()

Decrypt ChaCha20-Poly1305 ciphertext back to a UTF-8 string.

chachaDecryptText(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): string

Parameters

• ciphertext: Data to decrypt.
• key: 32-byte encryption key.
• nonce: 12-byte nonce used during encryption.

Returns

The decrypted plaintext string.

Throws

• If decryption or authentication fails.

chachaEncrypt()

Encrypt binary data with ChaCha20-Poly1305 (RFC 8439).

Uses a random 12-byte nonce. Callers must ensure a given key is not reused for more than ~2^32 encryptions to avoid nonce collision. For high-volume random-nonce use cases, prefer xchachaEncrypt (24-byte nonce).

chachaEncrypt(data: Uint8Array, key: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array }

Parameters

• data: Binary data to encrypt.
• key: 32-byte encryption key.

Returns

Object containing the ciphertext (with 16-byte Poly1305 tag appended) and nonce.

Throws

• If key is not exactly 32 bytes.

Examples

import { chachaEncrypt, chachaDecrypt, randomBytes } from "@parity/product-sdk-crypto";
 
const key = randomBytes(32);
const { ciphertext, nonce } = chachaEncrypt(data, key);
const plaintext = chachaDecrypt(ciphertext, key, nonce);

chachaEncryptText()

Encrypt a UTF-8 string with ChaCha20-Poly1305.

chachaEncryptText(plaintext: string, key: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array }

Parameters

• plaintext: The string to encrypt.
• key: 32-byte encryption key.

Returns

Object containing ciphertext and nonce.

Throws

• If key is not exactly 32 bytes.

concatBytes()

Copies several Uint8Arrays into one.

concatBytes(...arrays: TArg<Uint8Array<ArrayBufferLike>[]>): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

• arrays: arrays to concatenate

Returns

Concatenated byte array.

Throws

• On wrong argument types. TypeError

Examples

Concatenate multiple byte arrays.

concatBytes(new Uint8Array([1]), new Uint8Array([2]));

deriveKey()

Derive a 32-byte key using HKDF-SHA256 (RFC 5869).

This is a convenience wrapper around the full HKDF function, fixed to SHA-256 and a 32-byte output length — suitable for deriving symmetric encryption keys.

deriveKey(ikm: Uint8Array, salt: string | Uint8Array<ArrayBufferLike>, info: string | Uint8Array<ArrayBufferLike>): Uint8Array

Parameters

• ikm: Input keying material (e.g. a shared secret or master key).
• salt: Salt value (string or bytes). Use a unique, application-specific salt.
• info: Context/application-specific info string (string or bytes).

Returns

A 32-byte derived key as Uint8Array.

Examples

import { deriveKey, randomBytes } from "@parity/product-sdk-crypto";
 
const masterKey = randomBytes(32);
const encryptionKey = deriveKey(masterKey, "myapp-v1", "document-encryption");

expand()

HKDF-expand from the spec. The most important part. HKDF-Expand(PRK, info, L) -> OKM

expand(hash: TArg<CHash>, prk: TArg<Uint8Array<ArrayBufferLike>>, info?: TArg<Uint8Array<ArrayBufferLike>>, length?: number): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

• hash: hash function that would be used (e.g. sha256)
• prk: a pseudorandom key of at least HashLen octets (usually, the output from the extract step)
• info: optional context and application specific information (can be a zero-length string)
• length: length of output keying material in bytes. RFC 5869 §2.3 allows 0..255*HashLen, so 0 returns an empty OKM.

Returns

Output keying material with the requested length.

Throws

• If the requested output length exceeds the HKDF limit for the selected hash. Error

Examples

Run the HKDF expand step.

import { expand } from '@noble/hashes/hkdf.js';
import { sha256 } from '@noble/hashes/sha2.js';
expand(sha256, new Uint8Array(32), new Uint8Array([1, 2, 3]), 16);

extract()

HKDF-extract from spec. Less important part. HKDF-Extract(IKM, salt) -> PRK Arguments position differs from spec (IKM is first one, since it is not optional) Local validation only checks hash; ikm / salt byte validation is delegated to hmac().

extract(hash: TArg<CHash>, ikm: TArg<Uint8Array<ArrayBufferLike>>, salt?: TArg<Uint8Array<ArrayBufferLike>>): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

• hash: hash function that would be used (e.g. sha256)
• ikm: input keying material, the initial key
• salt: optional salt value (a non-secret random value)

Returns

Pseudorandom key derived from input keying material.

Examples

Run the HKDF extract step.

import { extract } from '@noble/hashes/hkdf.js';
import { sha256 } from '@noble/hashes/sha2.js';
extract(sha256, new Uint8Array([1, 2, 3]), new Uint8Array([4, 5, 6]));

hexToBytes()

Convert hex string to byte array. Uses built-in function, when available.

hexToBytes(hex: string): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

• hex: hexadecimal string to decode

Returns

Decoded bytes.

Throws

• On wrong argument types. TypeError
• On wrong argument ranges or values. RangeError

Examples

Decode lowercase hexadecimal into bytes.

hexToBytes('cafe0123'); // Uint8Array.from([0xca, 0xfe, 0x01, 0x23])

keccak256()

Compute a 32-byte Keccak-256 hash.

Used for Ethereum-compatible operations (address derivation, EVM function selectors) and supported by the Bulletin Chain for cross-chain compatibility.

keccak256(data: Uint8Array): Uint8Array

Parameters

• data: Arbitrary bytes to hash.

Returns

32-byte Keccak-256 digest.

Examples

import { keccak256, bytesToHex } from "@parity/product-sdk-crypto";
 
const hash = keccak256(new TextEncoder().encode("hello"));
console.log(bytesToHex(hash)); // 64-char hex string

randomBytes()

Cryptographically secure PRNG backed by crypto.getRandomValues.

randomBytes(bytesLength?: number): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

• bytesLength: number of random bytes to generate

Returns

Random bytes. The platform getRandomValues() implementation still defines any single-call length cap, and this helper rejects oversize requests with a stable library RangeError instead of host-specific errors.

Throws

• On wrong argument types. TypeError
• On wrong argument ranges or values. RangeError
• If the current runtime does not provide crypto.getRandomValues. Error

Examples

Generate a fresh random key or nonce.

const key = randomBytes(16);

sealedBoxDecrypt()

Sealed box decrypt: extract ephemeral public key and nonce, then open with recipient’s secret key.

Input format: ephemeralPubKey(32) || nonce(24) || ciphertext.

sealedBoxDecrypt(sealed: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array

Parameters

• sealed: The sealed message produced by sealedBoxEncrypt.
• recipientSecretKey: The recipient’s 32-byte Curve25519 secret key.

Returns

The decrypted plaintext bytes.

Throws

• If the sealed data is too short, or decryption/authentication fails.

sealedBoxEncrypt()

Sealed box encrypt: uses an ephemeral keypair so the recipient cannot identify the sender.

Output format: ephemeralPubKey(32) || nonce(24) || ciphertext. The ciphertext includes the 16-byte Poly1305 authentication tag.

sealedBoxEncrypt(message: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array

Parameters

• message: The plaintext bytes to encrypt.
• recipientPublicKey: The recipient’s 32-byte Curve25519 public key.

Returns

A single Uint8Array containing the sealed message.

Throws

• If encryption fails (e.g. invalid public key).

Examples

import { sealedBoxEncrypt, sealedBoxDecrypt } from "@parity/product-sdk-crypto";
import nacl from "tweetnacl";
 
const recipient = nacl.box.keyPair();
const sealed = sealedBoxEncrypt(message, recipient.publicKey);
const plaintext = sealedBoxDecrypt(sealed, recipient.secretKey);

sha256()

Compute a 32-byte SHA2-256 hash.

Used by bulletin-deploy and supported by the Bulletin Chain as an alternative hashing algorithm.

sha256(data: Uint8Array): Uint8Array

Parameters

• data: Arbitrary bytes to hash.

Returns

32-byte SHA2-256 digest.

Examples

import { sha256, bytesToHex } from "@parity/product-sdk-crypto";
 
const hash = sha256(new TextEncoder().encode("hello"));
console.log(bytesToHex(hash)); // 64-char hex string

utf8ToBytes()

Converts string to bytes using UTF8 encoding. Built-in doesn’t validate input to be string: we do the check. Non-ASCII details are delegated to the platform TextEncoder.

utf8ToBytes(str: string): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

• str: string to encode

Returns

UTF-8 encoded bytes.

Throws

• On wrong argument types. TypeError

Examples

Encode a string as UTF-8 bytes.

utf8ToBytes('abc'); // Uint8Array.from([97, 98, 99])

xchachaDecrypt()

Decrypt binary data with XChaCha20-Poly1305.

xchachaDecrypt(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): Uint8Array

Parameters

• ciphertext: Data to decrypt (includes 16-byte Poly1305 tag).
• key: 32-byte encryption key.
• nonce: 24-byte nonce used during encryption.

Returns

The decrypted plaintext.

Throws

• If key is not 32 bytes, or if decryption/authentication fails.

xchachaDecryptPacked()

Decrypt a packed XChaCha20-Poly1305 buffer (nonce prepended to ciphertext).

Input format: nonce(24) || ciphertext.

xchachaDecryptPacked(packed: Uint8Array, key: Uint8Array): Uint8Array

Parameters

• packed: The packed buffer to decrypt.
• key: 32-byte encryption key.

Returns

The decrypted plaintext.

Throws

• If the packed data is too short, key is invalid, or authentication fails.

xchachaDecryptText()

Decrypt XChaCha20-Poly1305 ciphertext back to a UTF-8 string.

xchachaDecryptText(ciphertext: Uint8Array, key: Uint8Array, nonce: Uint8Array): string

Parameters

• ciphertext: Data to decrypt.
• key: 32-byte encryption key.
• nonce: 24-byte nonce used during encryption.

Returns

The decrypted plaintext string.

Throws

• If decryption or authentication fails.

xchachaEncrypt()

Encrypt binary data with XChaCha20-Poly1305.

The 24-byte nonce makes random nonce generation safe for virtually unlimited encryptions under the same key (~2^96 nonce space vs 2^48 for 12-byte). This is the recommended symmetric cipher for most use cases.

xchachaEncrypt(data: Uint8Array, key: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array }

Parameters

• data: Binary data to encrypt.
• key: 32-byte encryption key.

Returns

Object containing ciphertext (with 16-byte tag) and 24-byte nonce.

Throws

• If key is not exactly 32 bytes.

Examples

import { xchachaEncrypt, xchachaDecrypt, randomBytes } from "@parity/product-sdk-crypto";
 
const key = randomBytes(32);
const { ciphertext, nonce } = xchachaEncrypt(data, key);
const plaintext = xchachaDecrypt(ciphertext, key, nonce);

xchachaEncryptPacked()

Encrypt binary data with XChaCha20-Poly1305, returning a single packed buffer.

Output format: nonce(24) || ciphertext. Convenient for storage or transmission where a single blob is preferred.

xchachaEncryptPacked(data: Uint8Array, key: Uint8Array): Uint8Array

Parameters

• data: Binary data to encrypt.
• key: 32-byte encryption key.

Returns

Single Uint8Array with nonce prepended to ciphertext.

Throws

• If key is not exactly 32 bytes.

Examples

const packed = xchachaEncryptPacked(data, key);
const plaintext = xchachaDecryptPacked(packed, key);

xchachaEncryptText()

Encrypt a UTF-8 string with XChaCha20-Poly1305.

xchachaEncryptText(plaintext: string, key: Uint8Array): { ciphertext: Uint8Array; nonce: Uint8Array }

Parameters

• plaintext: The string to encrypt.
• key: 32-byte encryption key.

Returns

Object containing ciphertext and 24-byte nonce.

Throws

• If key is not exactly 32 bytes.

Interfaces

interface EncryptedPayload

Common encrypted payload envelope carrying algorithm metadata alongside ciphertext. Useful for protocols that need to negotiate or identify the cipher used.

Properties

algorithm

The symmetric algorithm used to produce this ciphertext.

ciphertext

The encrypted data (does not include the nonce).

kem

How the symmetric key was established (omit if key was pre-shared or derived directly via HKDF).

nonce

The nonce/IV used during encryption.

interface nacl

Re-export of the upstream tweetnacl module — the primitive library that backs the box helpers in this package. Reach for it directly when you need raw NaCl operations the SDK doesn’t wrap, such as nacl.box.keyPair(), nacl.randomBytes(n), or nacl.sign(...).

Properties

box

hash

scalarMult

secretbox

sign

Methods

randomBytes

randomBytes(n: number): Uint8Array

setPRNG

setPRNG(fn: (x: Uint8Array, n: number) => void): void

verify

verify(x: Uint8Array, y: Uint8Array): boolean

Type Aliases

type KemAlgorithm

Key encapsulation mechanism identifiers.

Classical:

• "x25519" — Curve25519 Diffie-Hellman key agreement.

Post-quantum (future, not yet implemented):

• "ml-kem-768" — Module-Lattice Key Encapsulation (FIPS 203), ~AES-192 equivalent security.
• "x25519-ml-kem-768" — Hybrid classical + post-quantum for defense-in-depth.

PQC types are defined for forward compatibility. Implementations will be added when audited libraries (e.g. @noble/post-quantum) reach stable releases.

type KemAlgorithm = "x25519" | "ml-kem-768" | "x25519-ml-kem-768"

type SymmetricAlgorithm

Symmetric cipher algorithm identifiers supported by this package.

• "aes-256-gcm" — AES-256 in Galois/Counter Mode (128-bit tag).
• "chacha20-poly1305" — ChaCha20 with Poly1305 MAC (RFC 8439, 12-byte nonce).
• "xchacha20-poly1305" — Extended-nonce ChaCha20 with Poly1305 (24-byte nonce). Preferred for random nonce generation due to negligible collision probability.

type SymmetricAlgorithm = "aes-256-gcm" | "chacha20-poly1305" | "xchacha20-poly1305"

Variables

hkdf

HKDF (RFC 5869): derive keys from an initial input. Combines hkdf_extract + hkdf_expand in one step

let hkdf: (hash: TArg<CHash>, ikm: TArg<Uint8Array>, salt: TArg<Uint8Array | undefined>, info: TArg<Uint8Array | undefined>, length: number) => TRet<Uint8Array>

Examples

HKDF (RFC 5869): derive keys from an initial input.

import { hkdf } from '@noble/hashes/hkdf.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { randomBytes, utf8ToBytes } from '@noble/hashes/utils.js';
const inputKey = randomBytes(32);
const salt = randomBytes(32);
const info = utf8ToBytes('application-key');
const okm = hkdf(sha256, inputKey, salt, info, 32);

nacl

Re-export of the upstream tweetnacl module — the primitive library that backs the box helpers in this package. Reach for it directly when you need raw NaCl operations the SDK doesn’t wrap, such as nacl.box.keyPair(), nacl.randomBytes(n), or nacl.sign(...).

let nacl: nacl

Namespaces

• nacl — export