# Tauri Plugin Secure Element
A Tauri plugin for secure element functionality on iOS (Secure Enclave) and Android (Strongbox and TEE).
## Features
- Generate secure keys using hardware-backed secure storage
- Sign data with keys stored in secure elements
- List and manage secure keys
- Check secure element support on the device
- Support for biometric and PIN authentication modes
- Cross-platform support for iOS and Android
## Installation
### npm
```bash
npm install tauri-plugin-secure-element-api
# or
pnpm add tauri-plugin-secure-element-api
# or
yarn add tauri-plugin-secure-element-api
```
### Cargo
```toml
[dependencies]
tauri-plugin-secure-element = "0.1.0"
```
## Setup
Add the plugin to your Rust code in `src-tauri/src/lib.rs`:
```rust
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
tauri::Builder::default()
.plugin(tauri_plugin_secure_element::init())
// ... other plugins
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
Add the plugin permissions to `src-tauri/capabilities/default.json`:
```json
{
"identifier": "default",
"description": "Capability for the main window",
"windows": ["main"],
"permissions": ["core:default", "secure-element:default"]
}
```
### Android Biometrics
In order to use biometric protected keys, add this to `src-tauri/gen/android/app/build.gradle.kts`:
```kotlin
dependencies {
implementation("androidx.biometric:biometric:1.1.0")
}
```
**Note**: The `src-tauri/gen/android` folder is generated by Tauri but should be **committed to version control** and customized as needed. Once you add the biometric dependency, it will persist across builds (you only need to add it again if you completely regenerate the Android project with `tauri android init`).
### iOS Face ID Permission
**Important**: For authentication-required keys to work on iOS with Face ID, you must add the Face ID usage description to your iOS Info.plist.
Add to `src-tauri/gen/apple/tauri-app_iOS/Info.plist` (replace `tauri-app_iOS` with your app name):
```xml
<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to authenticate access to your secure keys.</string>
```
Add this entry anywhere within the `<dict>` section of the Info.plist file.
**Note**: Like the Android configuration, the `src-tauri/gen/apple` folder should be **committed to version control**. The Face ID permission will persist across builds unless you regenerate the iOS project with `tauri ios init`.
Touch ID does not require a separate permission entry - it works automatically when Face ID permission is granted or when no biometric hardware is available.
## Usage
```typescript
import {
checkSecureElementSupport,
generateSecureKey,
listKeys,
signWithKey,
deleteKey,
type AuthenticationMode,
} from "tauri-plugin-secure-element-api";
// Check if secure element is supported
const support = await checkSecureElementSupport();
console.log("Secure element supported:", support.secureElementSupported);
// Generate a new secure key
const { publicKey, keyName } = await generateSecureKey(
"my-key-name",
"pinOrBiometric" // or 'none' or 'biometricOnly'
);
// List all keys
const keys = await listKeys();
// Sign data with a key
const data = new Uint8Array([1, 2, 3, 4]);
const signature = await signWithKey("my-key-name", data);
// Delete a key
await deleteKey("my-key-name");
```
## API Reference
### `checkSecureElementSupport()`
Returns information about secure element support on the device.
**Returns:** `Promise<SecureElementSupport>`
```typescript
interface SecureElementSupport {
secureElementSupported: boolean;
teeSupported: boolean;
canEnforceBiometricOnly: boolean;
}
```
### `generateSecureKey(keyName: string, authMode?: AuthenticationMode)`
Generates a new secure key in the device's secure element.
**Parameters:**
- `keyName`: Unique name for the key
- `authMode`: Authentication mode (`'none'`, `'pinOrBiometric'`, or `'biometricOnly'`)
**Returns:** `Promise<GenerateSecureKeyResult>`
```typescript
interface GenerateSecureKeyResult {
publicKey: string;
keyName: string;
```
**Note:** The `biometricOnly` mode requires Android 11 (API 30) or higher. On older Android versions, this mode will be rejected with an error. Use `checkSecureElementSupport().canEnforceBiometricOnly` to check support before creating biometric-only keys.
### `listKeys(keyName?: string, publicKey?: string)`
Lists keys stored in the secure element. Can filter by key name or public key.
**Returns:** `Promise<KeyInfo[]>`
```typescript
interface KeyInfo {
keyName: string;
publicKey: string;
}
```
### `signWithKey(keyName: string, data: Uint8Array)`
Signs data using a key stored in the secure element.
**Parameters:**
- `keyName`: Name of the key to use
- `data`: Data to sign as `Uint8Array`
**Returns:** `Promise<Uint8Array>` - The signature
### `deleteKey(keyName?: string, publicKey?: string)`
Deletes a key from the secure element. At least one parameter must be provided.
**Returns:** `Promise<boolean>` - Success status
## Platform Support
- **iOS**: Uses Secure Enclave for key generation and signing
- **Android**: Uses StrongBox (when available) with fallback to TEE (Trusted Execution Environment)
## Platform Limitations
### Android
| Hardware-backed keys | API 23+ | TEE or StrongBox required |
| StrongBox | API 28+ | Falls back to TEE if unavailable |
| `biometricOnly` auth mode | API 30+ | Rejected on older versions |
### iOS
- Secure Enclave is available on all devices with A7 chip or later (iPhone 5s+)
- Simulator does not support Secure Enclave - test on physical devices
### Authentication Modes
| `none` | ✅ No auth required | ✅ No auth required |
| `pinOrBiometric` | ✅ Face ID, Touch ID, or passcode | ✅ Biometric or PIN/pattern/password |
| `biometricOnly` | ✅ Face ID or Touch ID only | ✅ API 30+ only, biometric only |
## License
Apache-2.0
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Links
- [Repository](https://github.com/dkackman/tauri-plugin-secure-element)
- [Issues](https://github.com/dkackman/tauri-plugin-secure-element/issues)