expo-clave-tee

Expo module for interacting with TEE

Features

• Supports both Android and iOS
• Selects best possible option to store credentials, and falls back to less secure options if necessary
• Uses best practices to store credentials securely, CryptoKit on iOS and KeyStore on Android

API

import { 
    fetchPublicKey,
    createKeyPair,
    deleteKeyPair,
    sign,
    verify
} from "expo-clave-tee";
import { assert } from "assert";

async function main() {
    const ALIAS = "my-key-pair";
    // Create a key pair
    const pubKey1 = await createKeyPair(ALIAS);
    // Fetch the created key pair
    const pubKey2 = await fetchPublicKey(ALIAS);
    assert(pubKey1 === pubKey2);

    // Delete the key pair
    await deleteKeyPair(ALIAS);
    const pubKey3 = await fetchPublicKey(ALIAS);
    // fetchPublicKey returns undefined if the key pair does not exist
    assert(pubKey3 == undefined);

    // Sign a message
    // sign and verify functions accept hex strings as input
    const message = "Hello World!";
    const hexMessage = Buffer.from(message, "utf8").toString("hex");
    const signature = await sign(ALIAS, hexMessage);
    // Verify the signature
    const isVerified = await verify(pubKey1, hexMessage, signature);
    assert(isVerified);

    // Sign function accepts an optional prompt parameter
    const signature2 = await sign(ALIAS, hexMessage, {
        usageMessage: "Please sign this message",
        androidTitle: "Sign",
    });
}

main();

Error Codes

Each error in the module has an assigned error code to it. It follows this format:

E{`platform`}{`function_type`#02}{`error_type`#02}: {`error_message`}

• platform:
  • 1: android
  • 2: ios
• function_type:
  • 1: fetchPublicKey
  • 2: createKeyPair
  • 3: deleteKeyPair
  • 4: sign
  • 5: verify
• error_type: Type of the error, differs on Android and iOS

In an example error: "E10102: Something is wrong"

• android is the platform
• Error occured from fetchPublicKey function
• Error type is 2 (more details in Error Types)
• Error message is "Something is wrong"

Error Types

|Platform|Code|Error| |--------|----|-----| | android | 10101 | Key not found in keychain | | android | 10102 | Couldn't parse key in the keychain | | android | 10201 | Key not found in keychain | | android | 10202 | Couldn't parse key in the keychain | | android | 10301 | Couldn't delete key, keystore has not been initialized, or if the entry cannot be removed | | android | 10401 | Key not found in keychain | | android | 10402 | Couldn't parse key in the keychain | | android | 10403 | Biometric authentication failed for unknown reasons | | android | 10404 | Biometric authentication wasn't valid and failed | | android | 10501 | Key not found in keychain | | android | 10502 | Couldn't parse key in the keychain | | ios | 20101 | Couldn't convert the key in the keystore | | ios | 20102 | Couldn't read the key from the keystore | | ios | 20201 | Something is wrong with access control | | ios | 20202 | Couldn't create key | | ios | 20203 | Couldn't store key in the keychain | | ios | 20204 | Couldn't convert the key in the keychain | | ios | 20205 | Key not found in the keychain | | ios | 20206 | Couldn't create key with context | | ios | 20301 | Couldn't delete key from the keystore | | ios | 20401 | Couldn't convert the key in the keychain | | ios | 20402 | Couldn't read the key from the keystore | | ios | 20403 | Key not found in the keychain | | ios | 20404 | Couldn't create key with context | | ios | 20501 | Couldn't convert the key in the keychain | | ios | 20502 | Couldn't read the key from the keystore | | ios | 20503 | Key not found in the keychain | | ios | 20504 | Couldn't parse the signature |

Running the example app

iOS

npm i
cd example
npm run ios

Android

In order to run it without a problem I had to follow these steps

• Remove existing Java and Gradle installations
• Install Java 17 (on MacOS, best way to do this is to use sdkman with sdk install java 17.0.4.1-tem)
• Install Android Studio and create a new Android emulator
• Start the emulator
• Run the following commands

Optionally you can install Gradle 7.4, but it should be installed automatically by the npm run android command

npm i
cd example
npm run android