tauri-plugin-secure-element 0.1.0-beta.1

# Tauri Plugin Secure Element

A Tauri plugin for secure element functionality on macOS & 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 macOS, Windows, 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-beta.1"
```

## 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;
  hardwareBacking: "secureEnclave" | "strongBox" | "tee";
}
```

**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

## Public Key Format

Public keys are returned as base64-encoded strings in **X9.62 uncompressed point format** (65 bytes), consistent across all platforms:

| Byte(s) | Content                 |
| ------- | ----------------------- |
| 0       | `0x04` (uncompressed)   |
| 1-32    | X coordinate (32 bytes) |
| 33-64   | Y coordinate (32 bytes) |

All keys use the **secp256r1 (P-256)** elliptic curve.

## Platform Support

- **iOS**: Uses Secure Enclave for key generation and signing
- **Android**: Uses StrongBox and TEE (Trusted Execution Environment) when available
- **Windows**: Uses TPM 2.0 for key generation and signing
- **macOS**: Uses Secure Enclave for key generation and signing

## Platform Limitations

### Windows

- Windows 11 (build 22000 or higher) requires TPM 2.0
- TPM 2.0 is supported on Windows 10 (since version 1507)

### macOS

- Secure Enclave is available on Macs with Apple Silicon (M1/M2/M3/M4) or T2 chip

### Android

| Feature                   | Requirement | Notes                            |
| ------------------------- | ----------- | -------------------------------- |
| 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

| Mode             | iOS/MacOS                         | Android                              | Windows             |
| ---------------- | --------------------------------- | ------------------------------------ | ------------------- |
| `none`           | ✅ No auth required               | ✅ No auth required                  | ✅ No auth required |
| `pinOrBiometric` | ✅ Face ID, Touch ID, or passcode | ✅ Biometric or PIN/pattern/password | ✅ Windows Hello    |
| `biometricOnly`  | ❌ Not supported                  | ✅ API 30+ only, biometric only      | ❌ Not supported    |

## 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)