Skip to main content

​
Curve Cryptography

​
Curve.generateKeyPair

Generates a new Curve25519 key pair for Signal protocol. 
Curve.generateKeyPair(): KeyPair
​
return
KeyPair
A new cryptographic key pair
Example: 
const keyPair = Curve.generateKeyPair()
console.log(keyPair.public) // Buffer of 32 bytes

​
Curve.sharedKey

Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman). 
Curve.sharedKey(
  privateKey: Uint8Array,
  publicKey: Uint8Array
): Buffer
​
privateKey
Uint8Array
required
Your private key
​
publicKey
Uint8Array
required
Other party’s public key
​
return
Buffer
Shared secret derived from the key agreement

​
Curve.sign

Creates a cryptographic signature for data. 
Curve.sign(
  privateKey: Uint8Array,
  buf: Uint8Array
): Uint8Array
​
privateKey
Uint8Array
required
Private key for signing
​
buf
Uint8Array
required
Data to sign
​
return
Uint8Array
Cryptographic signature

​
Curve.verify

Verifies a cryptographic signature. 
Curve.verify(
  pubKey: Uint8Array,
  message: Uint8Array,
  signature: Uint8Array
): boolean
​
pubKey
Uint8Array
required
Public key of the signer
​
message
Uint8Array
required
Original message that was signed
​
signature
Uint8Array
required
Signature to verify
​
return
boolean
True if signature is valid, false otherwise

​
AES Encryption

​
aesEncryptGCM

Encrypts data using AES-256-GCM with authentication. 
function aesEncryptGCM(
  plaintext: Uint8Array,
  key: Uint8Array,
  iv: Uint8Array,
  additionalData: Uint8Array
): Buffer
​
plaintext
Uint8Array
required
Data to encrypt
​
key
Uint8Array
required
256-bit encryption key (32 bytes)
​
iv
Uint8Array
required
Initialization vector (16 bytes)
​
additionalData
Uint8Array
required
Additional authenticated data (not encrypted but authenticated)
​
return
Buffer
Encrypted ciphertext with authentication tag appended
The authentication tag (16 bytes) is automatically appended to the ciphertext.

​
aesDecryptGCM

Decrypts AES-256-GCM encrypted data and verifies authentication. 
function aesDecryptGCM(
  ciphertext: Uint8Array,
  key: Uint8Array,
  iv: Uint8Array,
  additionalData: Uint8Array
): Buffer
​
ciphertext
Uint8Array
required
Encrypted data with authentication tag appended
​
key
Uint8Array
required
256-bit decryption key (32 bytes)
​
iv
Uint8Array
required
Initialization vector (16 bytes)
​
additionalData
Uint8Array
required
Additional authenticated data used during encryption
​
return
Buffer
Decrypted plaintext
Throws an error if authentication fails or data has been tampered with.

​
aesEncryptCTR

Encrypts data using AES-256-CTR mode. 
function aesEncryptCTR(
  plaintext: Uint8Array,
  key: Uint8Array,
  iv: Uint8Array
): Buffer
​
plaintext
Uint8Array
required
Data to encrypt
​
key
Uint8Array
required
256-bit encryption key
​
iv
Uint8Array
required
Counter initialization vector
​
return
Buffer
Encrypted ciphertext

​
aesDecryptCTR

Decrypts AES-256-CTR encrypted data. 
function aesDecryptCTR(
  ciphertext: Uint8Array,
  key: Uint8Array,
  iv: Uint8Array
): Buffer

​
aesEncrypt

Encrypts data using AES-256-CBC with a random IV prepended. 
function aesEncrypt(
  buffer: Uint8Array,
  key: Uint8Array
): Buffer
​
buffer
Uint8Array
required
Data to encrypt
​
key
Uint8Array
required
256-bit encryption key
​
return
Buffer
Random IV (16 bytes) prepended to the ciphertext

​
aesDecrypt

Decrypts AES-256-CBC encrypted data where IV is prepended. 
function aesDecrypt(
  buffer: Uint8Array,
  key: Uint8Array
): Buffer
​
buffer
Uint8Array
required
IV-prepended ciphertext (first 16 bytes are IV)
​
key
Uint8Array
required
256-bit decryption key
​
return
Buffer
Decrypted plaintext

​
aesEncryptWithIV

Encrypts data using AES-256-CBC with a provided IV. 
function aesEncrypWithIV(
  buffer: Buffer,
  key: Buffer,
  IV: Buffer
): Buffer

​
aesDecryptWithIV

Decrypts AES-256-CBC encrypted data with a provided IV. 
function aesDecryptWithIV(
  buffer: Uint8Array,
  key: Uint8Array,
  IV: Uint8Array
): Buffer

​
Hashing & HMAC

​
sha256

Computes SHA-256 hash of data. 
function sha256(buffer: Buffer): Buffer
​
buffer
Buffer
required
Data to hash
​
return
Buffer
SHA-256 hash (32 bytes)
Example: 
const hash = sha256(Buffer.from('hello world'))
console.log(hash.toString('hex'))

​
hmacSign

Creates HMAC signature using SHA-256 or SHA-512. 
function hmacSign(
  buffer: Buffer | Uint8Array,
  key: Buffer | Uint8Array,
  variant?: 'sha256' | 'sha512'
): Buffer
​
buffer
Buffer | Uint8Array
required
Data to sign
​
key
Buffer | Uint8Array
required
HMAC key
​
variant
'sha256' | 'sha512'
Hash algorithm to use (default: ‘sha256’)
​
return
Buffer
HMAC signature

​
hkdf

HMAC-based Key Derivation Function for deriving keys. 
function hkdf(
  buffer: Uint8Array | string,
  expandedLength: number,
  options?: { info?: string; salt?: Buffer }
): Buffer
​
buffer
Uint8Array | string
required
Input key material
​
expandedLength
number
required
Desired output length in bytes
​
options
object
HKDF options
​
return
Buffer
Derived key material of specified length
Example: 
const derivedKey = hkdf(
  mediaKey,
  112,
  { info: 'WhatsApp Image Keys' }
)

​
Media Encryption

​
getMediaKeys

Generates all keys required for media encryption/decryption. 
async function getMediaKeys(
  buffer: Uint8Array | string | null | undefined,
  mediaType: MediaType
): Promise<MediaDecryptionKeyInfo>
​
buffer
Uint8Array | string
required
Media key (base64 string or bytes)
​
mediaType
MediaType
required
Type of media: ‘image’, ‘video’, ‘audio’, ‘document’, ‘sticker’, etc.
​
return
MediaDecryptionKeyInfo
Derived encryption keys
Example: 
const { iv, cipherKey, macKey } = await getMediaKeys(
  mediaMessage.mediaKey,
  'image'
)

​
encryptedStream

Encrypts a media stream for WhatsApp upload. 
async function encryptedStream(
  media: WAMediaUpload,
  mediaType: MediaType,
  options?: EncryptedStreamOptions
): Promise<{
  mediaKey: Buffer
  encFilePath: string
  originalFilePath?: string
  mac: Buffer
  fileEncSha256: Buffer
  fileSha256: Buffer
  fileLength: number
}>
​
media
WAMediaUpload
required
Media to encrypt - can be Buffer, stream, or file path/URL
​
mediaType
MediaType
required
Type of media being encrypted
​
options
EncryptedStreamOptions
Encryption options
​
return
object
Encryption result with all necessary metadata

​
downloadContentFromMessage

Downloads and decrypts media from a WhatsApp message. 
async function downloadContentFromMessage(
  message: DownloadableMessage,
  type: MediaType,
  opts?: MediaDownloadOptions
): Promise<Transform>
​
message
DownloadableMessage
required
Message containing media keys and URL
​
type
MediaType
required
Type of media being downloaded
​
opts
MediaDownloadOptions
Download options including byte range
​
return
Transform
Readable stream of decrypted media data
Example: 
const stream = await downloadContentFromMessage(
  message.message.imageMessage,
  'image'
)

const buffer = await streamToBuffer(stream)
await fs.writeFile('image.jpg', buffer)

​
Signal Protocol

​
signedKeyPair

Generates a signed pre-key pair for Signal protocol. 
function signedKeyPair(
  identityKeyPair: KeyPair,
  keyId: number
): SignedKeyPair
​
identityKeyPair
KeyPair
required
Identity key pair for signing
​
keyId
number
required
ID number for this signed pre-key
​
return
SignedKeyPair
Signed pre-key with signature

​
generateSignalPubKey

Prefixes version byte to public keys for Signal protocol compatibility. 
function generateSignalPubKey(
  pubKey: Uint8Array | Buffer
): Buffer
​
pubKey
Uint8Array | Buffer
required
Public key (32 or 33 bytes)
​
return
Buffer
Public key with version byte prefix (33 bytes total)

​
derivePairingCodeKey

Derives encryption key from pairing code using PBKDF2. 
async function derivePairingCodeKey(
  pairingCode: string,
  salt: Buffer
): Promise<Buffer>
​
pairingCode
string
required
8-digit pairing code
​
salt
Buffer
required
Salt for key derivation
​
return
Buffer
Derived 32-byte encryption key
Uses 131,072 iterations of PBKDF2 with SHA-256.

​
Utility Functions

​
md5

Computes MD5 hash (imported from whatsapp-rust-bridge). 
function md5(data: Uint8Array): Buffer
​
data
Uint8Array
required
Data to hash
​
return
Buffer
MD5 hash (16 bytes)
MD5 is cryptographically broken. Only use where required for WhatsApp protocol compatibility.

Auth Utilities

Authentication and key management

Media Operations

Complete media handling guide

Build docs developers (and LLMs) love

Get started for freeTalk to us