react-native-nacl-jsi

Sodium library for React Native with JSI binding.

Features

• ⚡️ High performance integration of the Sodium library written in C++
• 🔗 Synchronous calls without the bridge, uses JSI
• 🧩 Compatible with the new architecture

Source compilation

Precompiled binaries of libsodium will be linked by default. Optionally, you can choose to compile libsodium by yourself (run npm run rebuild in package directory). Source code will be downloaded and verified before compilation.

MacOS prerequisites

• libtool (macports, homebrew)
• autoconf (macports, homebrew)
• automake (macports, homebrew)
• Xcode (12 or newer)

Android prerequisites

• Android NDK
• CMake
• LLDB

Recompile

npm run rebuild

Installation

Using Hermes on Android is required.

npm install react-native-nacl-jsi
npx pod-install

Usage

Encoding/decoding

All functions takes and returns Uint8Array. There are helper functions that support encoding and decoding to and from UTF-8, hexadecimal and base64 strings.

Example

import {
  secretboxGenerateKey,
  secretboxSeal,
  secretboxOpen,
} from 'react-native-nacl-jsi';

const key = secretboxGenerateKey();
const encrypted = secretboxSeal(decodeUtf8('encrypt me'), key);
const decrypted = secretboxOpen(encrypted, key);

console.log(encodeUtf8(decrypted));

Public-key authenticated encryption (box)

Generates a random key pair for box and returns a KeyPair:

function boxGenerateKey(): KeyPair;

// With KeyPair:
type KeyPair = {
  publicKey: Uint8Array;
  secretKey: Uint8Array;
};

Encrypts and authenticates message using the recipient's public key and the sender's secret key:

function boxSeal(
  message: Uint8Array,
  recipientPublicKey: Uint8Array,
  senderSecretKey: Uint8Array
): Uint8Array;

Authenticates and decrypts the encrypted message using the sender's public key and the recipient's secret key:

function boxOpen(
  encryptedMessage: Uint8Array,
  senderPublicKey: Uint8Array,
  recipientSecretKey: Uint8Array
): Uint8Array;

Secret-key authenticated encryption (secretbox)

Generates a random key for secretbox:

function secretboxGenerateKey(): Uint8Array;

Encrypts and authenticates message using the key:

function secretboxSeal(message: Uint8Array, secretKey: Uint8Array): Uint8Array;

Authenticates and decrypts the encrypted message using the key:

function secretboxOpen(
  encryptedMessage: Uint8Array,
  secretKey: Uint8Array
): Uint8Array;

Signature

Generates a signing key pair:

function signGenerateKey(): KeyPair;

// With KeyPair:
type KeyPair = {
  publicKey: Uint8Array;
  secretKey: Uint8Array;
};

Signs a message and returns the signature:

function signDetached(
  messageToSign: Uint8Array,
  secretKey: Uint8Array
): Uint8Array;

Verifies a signature:

function signVerifyDetached(
  message: Uint8Array,
  publicKey: Uint8Array,
  signature: Uint8Array
): boolean;

Password hashing

Hash the password using the Argon2id algorithm:

function argon2idHash(
  password: Uint8Array,
  iterations: BigInt,
  memoryLimit: BigInt
): Promise<string>;

Verifies a hash and returns true if the hash matches the password:

function argon2idVerify(hash: string, password: Uint8Array): Promise<boolean>;

Key derivation

Derives the key using a salt and the Argon2id algorithm:

function argon2idDeriveKey(
  key: Uint8Array,
  salt: Uint8Array,
  keyLength: number,
  iterations: BigInt,
  memoryLimit: BigInt
): Promise<Uint8Array>;

AES256-GCM

Generates a random key to use for AES256-GCM encryption:

function aesGenerateKey(): Uint8Array;

Encrypts the message using the key and returns a AesResult:

function aesEncrypt(message: Uint8Array, key: Uint8Array): Promise<AesResult>;

// With AesResult:
type AesResult = {
  encrypted: Uint8Array;
  iv: Uint8Array;
};

Decrypts the encrypted message using the initialisation vector iv and the key:

function aesDecrypt(
  cipherText: Uint8Array,
  key: Uint8Array,
  iv: Uint8Array
): Promise<Uint8Array>;

Generates random bytes

function getRandomBytes(size: number | BigInt): Uint8Array;

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

Author

Rémy Dautriche (@remydautriche)

PACE, a private fitness tracker, implements its cryptography using react-native-nacl-jsi.

License

MIT