Expo Crypto

A universal library for crypto operations.

Android

iOS

tvOS

Web

Included in Expo Go

GitHub

npm

Changelog

Bundled version:

~55.0.0

expo-crypto enables you to hash data in an equivalent manner to the Node.js core crypto API, and perform crypto operations such as AES encryption and decryption.

Installation

Terminal

- npx expo install expo-crypto

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Basic Crypto usage

import { useEffect } from 'react';
import { StyleSheet, View, Text } from 'react-native';
import * as Crypto from 'expo-crypto';

export default function App() {
  useEffect(() => {
    (async () => {
      const digest = await Crypto.digestStringAsync(
        Crypto.CryptoDigestAlgorithm.SHA256,
        'GitHub stars are neat 🌟'
      );
      console.log('Digest: ', digest);
      /* Some crypto operation... */
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Crypto Module Example</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

AES encryption and decryption

Simple encryption / decryption

import { useEffect } from 'react';
import { StyleSheet, View, Text } from 'react-native';
import { AESEncryptionKey, aesEncryptAsync, aesDecryptAsync } from 'expo-crypto';

export default function App() {
  useEffect(() => {
    (async () => {
      const plaintext = 'Hello, world!';
      const plaintextBase64 = btoa(plaintexxt);

      const encryptionKey = await AESEncryptionKey.generate();
      const sealedData = await aesEncryptAsync(plaintextBase64, key);
      const decryptedBase64 = await aesDecryptAsync(sealedData, key, {
        output: 'base64',
      });

      const decrpyted = atob(decryptedBase64);
      console.log('Decrypted: ', decrpyted);
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Crypto Module Example</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Encrypt data and save it to the file

example.ts

import { AESEncryptionKey, aesEncryptAsync } from 'expo-crypto';
import { File, Paths } from 'expo-file-system';
import * as SecureStore from 'expo-secure-store';

async function encryptAndSaveData(plaintextData: Uint8Array) {
  // Generate encryption key
  const encryptionKey = await AESEncryptionKey.generate();

  // Encrypt data
  const sealedData = await aesEncryptAsync(plaintextData, encryptionKey);
  const encryptedBytes = await sealedData.combined();

  // Store encryption key
  const keyHex = await encryptionKey.encoded('hex');
  await SecureStore.setItemAsync('aes-encryption-key', keyHex);

  // Save encrypted file
  const file = new File(Paths.cache, 'encrypted.dat');
  file.create({ overwrite: true });
  file.write(encryptedBytes);
}

Load file and decrypt data

example.ts

import { AESEncryptionKey, AESSealedData, aesDecryptAsync } from 'expo-crypto';
import { File, Paths } from 'expo-file-system';
import * as SecureStore from 'expo-secure-store';

async function loadAndDecryptData(): Promise<Uint8Array | null> {
  // Load encryption key
  const keyHex = await SecureStore.getItemAsync('aes-encryption-key');
  if (!keyHex) {
    return null;
  }
  const encryptionKey = await AESEncryptionKey.import(keyHex, 'hex');

  // Load encrypted file
  const file = new File(Paths.cache, 'encrypted.dat');
  if (!file.exists) {
    return null;
  }
  const encryptedBytes = await file.bytes();
  const sealedData = AESSealedData.fromCombined(encryptedBytes);

  // Decrypt data
  const plaintextBytes = await aesDecryptAsync(data, encryptionKey);
  return plaintextBytes;
}

API

import * as Crypto from 'expo-crypto';

Classes

`AESEncryptionKey`

Android

iOS

tvOS

Web

Type: Class extends EncryptionKey

Represents an AES encryption key that can be used for encryption and decryption operations. This class provides methods to generate, import, and export encryption keys.

AESEncryptionKey Properties

`size`

Android

iOS

tvOS

Web

Type: AESKeySize

The size of the encryption key in bits (128, 192, or 256).

AESEncryptionKey Methods

`bytes()`

Android

iOS

tvOS

Web

Retrieves the key as a byte array. Asynchronous due to the use of SubtleCrypto exportKey API.

Returns:

Promise<Uint8Array<ArrayBufferLike>>

A promise that resolves to the byte array representation of the key.

`encoded(encoding)`

Android

iOS

tvOS

Web

Parameter	Type	Description
encoding	`'hex' \| 'base64'`	The encoding format to use ('hex' or 'base64').

Retrieves the key encoded as a string in the specified format. Asynchronous due to the use of SubtleCrypto exportKey API.

Returns:

Promise<string>

A promise that resolves to the string representation of the key.

`generate(size)`

Android

iOS

tvOS

Web

Parameter	Type	Description
size(optional)	`AESKeySize`	The size of the key (128, 192, or 256). Defaults to 256.

Generates a new AES encryption key of the specified size.

Returns:

Promise<EncryptionKey>

A promise that resolves to an EncryptionKey instance.

`import(bytes)`

Android

iOS

tvOS

Web

Overload #1

Parameter	Type	Description
bytes	`Uint8Array`	The key as a byte array.

Imports an encryption key from a byte array. Validates the size of the key.

Returns:

Promise<EncryptionKey>

A promise that resolves to an EncryptionKey instance.

`import(hexString, encoding)`

Android

iOS

tvOS

Web

Overload #2

Parameter	Type	Description
hexString	`string`	The key as a string.
encoding	`'hex' \| 'base64'`	The encoding used in the string ('hex' or 'base64').

Imports an encryption key from a string representation (hex or base64). Validates the size of the key.

Returns:

Promise<EncryptionKey>

A promise that resolves to an EncryptionKey instance.

`AESSealedData`

Android

iOS

tvOS

Web

Type: Class extends SealedData

Represents encrypted data including the ciphertext, initialization vector, and authentication tag. This class provides methods to create sealed data from various formats and extract its components.

AESSealedData Properties

`combinedSize`

Android

iOS

tvOS

Web

Read Only • Type: number

Total size of the combined data (IV + ciphertext + tag) in bytes.

`ivSize`

Android

iOS

tvOS

Web

Read Only • Type: number

Size of the initialization vector in bytes.

`tagSize`

Android

iOS

tvOS

Web

Read Only • Type: GCMTagByteLength

Size of the authentication tag in bytes.

AESSealedData Methods

`ciphertext(options)`

Android

iOS

tvOS

Web

Parameter	Type	Description
options	`{ encoding: 'base64' \| 'bytes', withTag: boolean }`	Options controlling whether to include the authentication tag and output encoding.

Retrieves the ciphertext from the sealed data.

Returns:

Promise<string | Uint8Array<ArrayBufferLike>>

The ciphertext as a Uint8Array or base64 string depending on encoding option.

`combined(encoding)`

Android

iOS

tvOS

Web

Parameter	Type	Description
encoding(optional)	`'base64' \| 'bytes'`	Output encoding format. Defaults to `bytes`.

Retrieves a combined representation of the IV, ciphertext, and tag.

Returns:

Promise<string | Uint8Array<ArrayBufferLike>>

The combined data as a Uint8Array or base64 string depending on encoding.

`fromCombined(combined, config)`

Android

iOS

tvOS

Web

Parameter	Type	Description
combined	`BinaryInput`	The combined data array. When providing a string, it must be base64-encoded.
config(optional)	`AESSealedDataConfig`	Configuration specifying IV and tag lengths.

Static method. Creates a SealedData instance from a combined byte array, including the IV, ciphertext, and tag.

Returns:

AESSealedData

A SealedData object.

`fromParts(iv, ciphertext, tag)`

Android

iOS

tvOS

Web

Overload #1

Parameter	Type	Description
iv	`BinaryInput`	The initialization vector. When providing a string, it must be base64-encoded.
ciphertext	`BinaryInput`	The encrypted data. Should not include GCM tag. When providing a string, it must be base64-encoded.
tag	`BinaryInput`	The authentication tag. When providing a string, it must be base64-encoded.

Static method. Creates a SealedData instance from separate nonce, ciphertext, and optionally a tag.

Returns:

AESSealedData

A SealedData object.

`fromParts(iv, ciphertextWithTag, tagLength)`

Android

iOS

tvOS

Web

Overload #2

Parameter	Type	Description
iv	`BinaryInput`	The initialization vector. When providing a string, it must be base64-encoded.
ciphertextWithTag	`BinaryInput`	The encrypted data with GCM tag appended. When providing a string, it must be base64-encoded.
tagLength(optional)	`number`	Authentication tag length in bytes. Defaults to 16.

Static method. Creates a SealedData instance from separate nonce, ciphertext, and optionally a tag.

Returns:

AESSealedData

A SealedData object.

`iv(encoding)`

Android

iOS

tvOS

Web

Parameter	Type	Description
encoding(optional)	`'base64' \| 'bytes'`	Output encoding format. Defaults to `bytes`.

Retrieves the initialization vector (nonce) from the sealed data.

Returns:

Promise<string | Uint8Array<ArrayBufferLike>>

The initialization vector as a Uint8Array or base64 string depending on encoding.

`tag(encoding)`

Android

iOS

tvOS

Web

Parameter	Type	Description
encoding(optional)	`'base64' \| 'bytes'`	Output encoding format. Defaults to `bytes`.

Retrieves the authentication tag from the sealed data.

Returns:

Promise<string | Uint8Array<ArrayBufferLike>>

The authentication tag as a Uint8Array or base64 string depending on encoding.

Methods

`Crypto.aesDecryptAsync(sealedData, key, options)`

Android

iOS

tvOS

Web

Parameter	Type	Description
sealedData	`AESSealedData`	The data to decrypt.
key	`AESEncryptionKey`	The key to use for decryption.
options(optional)	`AESDecryptOptions`	Options for decryption, including output encoding and additional data.

Decrypts the given sealed data using the specified key and options.

Returns:

Promise<string | Uint8Array<ArrayBufferLike>>

A promise that resolves to the decrypted data buffer or string, depending on encoding option.

`Crypto.aesEncryptAsync(plaintext, key, options)`

Android

iOS

tvOS

Web

Parameter	Type	Description
plaintext	`BinaryInput`	The data to encrypt. When providing a string, it must be base64-encoded.
key	`AESEncryptionKey`	The encryption key to use.
options(optional)	`AESEncryptOptions`	Optional encryption parameters including nonce, tag length, and additional data. Default:`{}`

Encrypts the given plaintext using AES-GCM with the specified key.

Returns:

Promise<AESSealedData>

A promise that resolves to a SealedData instance containing the encrypted data.

`Crypto.digest(algorithm, data)`

Android

iOS

tvOS

Web

Parameter	Type	Description
algorithm	`CryptoDigestAlgorithm`	The cryptographic hash function to use to transform a block of data into a fixed-size output.
data	`BufferSource`	The value that will be used to generate a digest.

The digest() method of Crypto generates a digest of the supplied TypedArray of bytes data with the provided digest algorithm. A digest is a short fixed-length value derived from some variable-length input. Cryptographic digests should exhibit collision-resistance, meaning that it's very difficult to generate multiple inputs that have equal digest values. On web, this method can only be called from a secure origin (HTTPS) otherwise, an error will be thrown.

Returns:

Promise<ArrayBuffer>

A Promise which fulfills with an ArrayBuffer representing the hashed input.

Example

const array = new Uint8Array([1, 2, 3, 4, 5]);
const digest = await Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA512, array);
console.log('Your digest: ' + digest);

`Crypto.digestStringAsync(algorithm, data, options)`

Android

iOS

tvOS

Web

Parameter	Type	Description
algorithm	`CryptoDigestAlgorithm`	The cryptographic hash function to use to transform a block of data into a fixed-size output.
data	`string`	The value that will be used to generate a digest.
options(optional)	`CryptoDigestOptions`	Format of the digest string. Defaults to: `CryptoDigestOptions.HEX`.

The digestStringAsync() method of Crypto generates a digest of the supplied data string with the provided digest algorithm. A digest is a short fixed-length value derived from some variable-length input. Cryptographic digests should exhibit collision-resistance, meaning that it's very difficult to generate multiple inputs that have equal digest values. You can specify the returned string format as one of CryptoEncoding. By default, the resolved value will be formatted as a HEX string. On web, this method can only be called from a secure origin (HTTPS) otherwise, an error will be thrown.

Returns:

Promise<string>

Return a Promise which fulfills with a value representing the hashed input.

Example

const digest = await Crypto.digestStringAsync(
  Crypto.CryptoDigestAlgorithm.SHA512,
  '🥓 Easy to Digest! 💙'
);

`Crypto.getRandomBytes(byteCount)`

Android

iOS

tvOS

Web

Parameter	Type	Description
byteCount	`number`	A number within the range from `0` to `1024`. Anything else will throw a `TypeError`.

Generates completely random bytes using native implementations. The byteCount property is a number indicating the number of bytes to generate in the form of a Uint8Array. Falls back to Math.random during development to prevent issues with React Native Debugger.

Returns:

Uint8Array

An array of random bytes with the same length as the byteCount.

`Crypto.getRandomBytesAsync(byteCount)`

Android

iOS

tvOS

Web

Parameter	Type	Description
byteCount	`number`	A number within the range from `0` to `1024`. Anything else will throw a `TypeError`.

Generates completely random bytes using native implementations. The byteCount property is a number indicating the number of bytes to generate in the form of a Uint8Array.

Returns:

Promise<Uint8Array<ArrayBufferLike>>

A promise that fulfills with an array of random bytes with the same length as the byteCount.

`Crypto.getRandomValues(typedArray)`

Android

iOS

tvOS

Web

Parameter	Type	Description
typedArray	`T`	An integer based `TypedArray` to fill with cryptographically secure random values. It modifies the input array in place.

The getRandomValues() method of Crypto fills a provided TypedArray with cryptographically secure random values.

Returns:

T

The input array filled with cryptographically secure random values.

Example

const byteArray = new Uint8Array(16);
Crypto.getRandomValues(byteArray);
console.log('Your lucky bytes: ' + byteArray);

`Crypto.randomUUID()`

Android

iOS

tvOS

Web

The randomUUID() method returns a unique identifier based on the V4 UUID spec (RFC4122). It uses cryptographically secure random values to generate the UUID.

Returns:

string

A string containing a newly generated UUIDv4 identifier

Example

const UUID = Crypto.randomUUID();
console.log('Your UUID: ' + UUID);

Interfaces

`AESDecryptOptions`

Android

iOS

tvOS

Web

Options for the decryption process.

Property	Type	Description
additionalData(optional)	`BinaryInput`	Additional authenticated data (AAD) for GCM mode. When provided as a string, it must be base64-encoded.
output(optional)	`'base64' \| 'bytes'`	Output format for the decrypted data. Default:`'bytes'`

`AESEncryptOptions`

Android

iOS

tvOS

Web

Options for the encryption process.

Property	Type	Description
additionalData(optional)	`BinaryInput`	Additional authenticated data (AAD) for GCM mode. When provided as a string, it must be base64-encoded.
nonce(optional)	`GCMNonceParam`	Parameters for nonce generation.
tagLength(optional)	`GCMTagByteLength`	Only for: Android Web The length of the authentication tag in bytes. Note: On Apple, this option is ignored. The tag will always have 16 bytes. Default:`16`

`AESSealedDataConfig`

Android

iOS

tvOS

Web

Configuration for parsing sealed data from combined format.

Property	Type	Description
ivLength(optional)	`number`	The length of the initialization vector in bytes. Default:`12`
tagLength(optional)	`GCMTagByteLength`	The length of the authentication tag in bytes. Default:`16`

Types

`BinaryInput`

Android

iOS

tvOS

Web

Literal Type: union

Represents binary input data that can be processed by AES APIs. When providing a string, it must be base64-encoded.

Acceptable values are: string | Uint8Array | ArrayBuffer

`CryptoDigestOptions`

Android

iOS

tvOS

Web

Property	Type	Description
encoding	`CryptoEncoding`	Format the digest is returned in.

`Digest`

Android

iOS

tvOS

Web

Type: string

`GCMNonceParam`

Android

iOS

tvOS

Web

Configuration for the nonce (initialization vector) during encryption. Can specify either the byte length of the IV to generate or provide an IV directly.

Type: object shaped as below:

Property	Type	Description
length(optional)	`number`	Byte length of nonce to be generated. Default:`12`

Or object shaped as below:

Property	Type	Description
bytes	`BinaryInput`	Provided nonce bytes.

`GCMTagByteLength`

Android

iOS

tvOS

Web

Literal Type: number

Byte length of the GCM authentication tag, is a security parameter. The AES-GCM specification recommends that it should be 16, 15, 14, 13, or 12 bytes, although 8 or 4 bytes may be acceptable in some applications. For additional guidance, see Appendix C of the NIST Publication on "Recommendation for Block Cipher Modes of Operation".

Default and recommended value is 16. On Apple, the only supported value for encryption is 16.

Acceptable values are: '16' | '15' | '14' | '13' | '12' | '8' | '4'

Enums

`AESKeySize`

Android

iOS

tvOS

Web

AES key sizes in bits.

`AES128`

AESKeySize.AES128 ＝ 128

128-bit AES key

`AES192`

Android

Apple

AESKeySize.AES192 ＝ 192

192-bit AES key. It is unsupported on Web.

`AES256`

AESKeySize.AES256 ＝ 256

256-bit AES key

`CryptoDigestAlgorithm`

Android

iOS

tvOS

Web

Cryptographic hash function

`MD2`

iOS

CryptoDigestAlgorithm.MD2 ＝ "MD2"

128 bits.

`MD4`

iOS

CryptoDigestAlgorithm.MD4 ＝ "MD4"

128 bits.

`MD5`

Android

iOS

CryptoDigestAlgorithm.MD5 ＝ "MD5"

128 bits.

`SHA1`

CryptoDigestAlgorithm.SHA1 ＝ "SHA-1"

160 bits.

`SHA256`

CryptoDigestAlgorithm.SHA256 ＝ "SHA-256"

256 bits. Collision Resistant.

`SHA384`

CryptoDigestAlgorithm.SHA384 ＝ "SHA-384"

384 bits. Collision Resistant.

`SHA512`

CryptoDigestAlgorithm.SHA512 ＝ "SHA-512"

512 bits. Collision Resistant.

`CryptoEncoding`

Android

iOS

tvOS

Web

`BASE64`

CryptoEncoding.BASE64 ＝ "base64"

Has trailing padding. Does not wrap lines. Does not have a trailing newline.

`HEX`

CryptoEncoding.HEX ＝ "hex"

Error codes

Code	Description
`ERR_CRYPTO_UNAVAILABLE`	Web Only. Access to the WebCrypto API is restricted to secure origins (localhost/https).
`ERR_CRYPTO_DIGEST`	An invalid encoding type provided.