tauri-plugin-secure-element-api 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -27,7 +27,7 @@ yarn add tauri-plugin-secure-element-api
 
 ```toml
 [dependencies]
-tauri-plugin-secure-element = "0.1.0-beta.1"
+tauri-plugin-secure-element = "0.1.0-beta.2"
 ```
 
 ## Setup
@@ -95,11 +95,17 @@ import {
   signWithKey,
   deleteKey,
   type AuthenticationMode,
+  type SecureElementBacking,
+  type SecureElementCapabilities,
 } from "tauri-plugin-secure-element-api";
 
-// Check if secure element is supported
-const support = await checkSecureElementSupport();
-console.log("Secure element supported:", support.secureElementSupported);
+// Check device secure element capabilities
+const capabilities = await checkSecureElementSupport();
+console.log("Strongest backing:", capabilities.strongest);
+console.log(
+  "Can enforce biometric-only:",
+  capabilities.canEnforceBiometricOnly
+);
 
 // Generate a new secure key
 const { publicKey, keyName } = await generateSecureKey(
@@ -122,18 +128,68 @@ await deleteKey("my-key-name");
 
 ### `checkSecureElementSupport()`
 
-Returns information about secure element support on the device.
+Returns detailed information about secure element hardware capabilities on the device.
 
-**Returns:** `Promise<SecureElementSupport>`
+**Returns:** `Promise<SecureElementCapabilities>`
 
 ```typescript
-interface SecureElementSupport {
-  secureElementSupported: boolean;
-  teeSupported: boolean;
+/**
+ * Hardware backing tiers, ordered weakest → strongest:
+ * "none" < "firmware" < "integrated" < "discrete"
+ */
+type SecureElementBacking = "none" | "firmware" | "integrated" | "discrete";
+
+interface SecureElementCapabilities {
+  /** A discrete physical security chip is available (e.g. discrete TPM 2.0, macOS T2, Android StrongBox) */
+  discrete: boolean;
+  /** An on-die isolated security core is available (e.g. Apple Silicon Secure Enclave, ARM TrustZone/TEE) */
+  integrated: boolean;
+  /** Firmware-backed security is available but no dedicated secure processor (e.g. Windows fTPM via Intel PTT or AMD PSP) */
+  firmware: boolean;
+  /** The security is emulated/virtual (e.g. vTPM in a VM, iOS Simulator, Android Emulator) */
+  emulated: boolean;
+  /** The strongest hardware backing tier available on this device */
+  strongest: SecureElementBacking;
+  /** Whether biometric-only authentication can be enforced at the key level (Android API 30+ only) */
   canEnforceBiometricOnly: boolean;
 }
 ```
 
+**Hardware Backing Tiers:**
+
+| Tier         | Description                                    | Examples                                           |
+| ------------ | ---------------------------------------------- | -------------------------------------------------- |
+| `none`       | No secure element available (software-only)    | Unsupported devices, some VMs                      |
+| `firmware`   | Firmware-backed, no dedicated secure processor | Windows fTPM (Intel PTT, AMD PSP)                  |
+| `integrated` | On-die isolated security core                  | Apple Silicon Secure Enclave, ARM TrustZone/TEE    |
+| `discrete`   | Physically separate security processor         | Discrete TPM 2.0, macOS T2 chip, Android StrongBox |
+
+**Usage Example:**
+
+```typescript
+const caps = await checkSecureElementSupport();
+
+// Check if any hardware backing is available
+if (caps.strongest === "none") {
+  console.warn("No secure element available - keys will be software-only");
+}
+
+// Check for high-security backing (discrete or integrated)
+if (caps.strongest === "discrete" || caps.strongest === "integrated") {
+  console.log("High-security hardware backing available");
+}
+
+// Warn if running in emulated environment
+if (caps.emulated) {
+  console.warn("Running in emulator/VM - security may be reduced");
+}
+
+// Check before creating biometric-only keys
+if (caps.canEnforceBiometricOnly) {
+  await generateSecureKey("my-key", "biometricOnly");
+}
+```
+
 ### `generateSecureKey(keyName: string, authMode?: AuthenticationMode)`
 
 Generates a new secure key in the device's secure element.
@@ -175,9 +231,11 @@ Signs data using a key stored in the secure element.
 **Parameters:**
 
 - `keyName`: Name of the key to use
-- `data`: Data to sign as `Uint8Array`
+- `data`: Raw data to sign as `Uint8Array` (do not pre-hash)
 
-**Returns:** `Promise<Uint8Array>` - The signature
+**Returns:** `Promise<Uint8Array>` - DER-encoded ECDSA signature
+
+**Important:** The plugin automatically hashes your data with SHA-256 before signing. Pass raw data, not a pre-computed hash. See [Signature Format](#signature-format) for details.
 
 ### `deleteKey(keyName?: string, publicKey?: string)`
 
@@ -197,6 +255,100 @@ Public keys are returned as base64-encoded strings in **X9.62 uncompressed point
 
 All keys use the **secp256r1 (P-256)** elliptic curve.
 
+## Signature Format
+
+### Hashing Convention
+
+**The plugin automatically hashes your data with SHA-256 before signing.** This is handled internally on all platforms:
+
+- **iOS/macOS**: Hashes data, then signs with `.ecdsaSignatureDigestX962SHA256`
+- **Android**: Uses `SHA256withECDSA` which hashes internally
+- **Windows**: Explicitly hashes with SHA-256 before calling `NCryptSignHash`
+
+**Do not pre-hash your data.** Pass the raw data to `signWithKey()` and the plugin handles hashing.
+
+### Signature Output
+
+Signatures are returned as **DER-encoded ECDSA signatures** (ASN.1 format), consistent across all platforms. Typical size is 70-72 bytes for P-256.
+
+```
+SEQUENCE {
+  INTEGER r,  -- 32-33 bytes (may have leading 0x00 for sign bit)
+  INTEGER s   -- 32-33 bytes (may have leading 0x00 for sign bit)
+}
+```
+
+### Verifying Signatures
+
+To verify a signature produced by this plugin:
+
+1. Use the **raw original data** (not hashed)
+2. Use an **ECDSA-SHA256** verification algorithm (the verifier will hash internally)
+3. Use the **secp256r1 (P-256)** curve
+4. The signature is **DER-encoded**
+
+**Example (Node.js):**
+
+```typescript
+import { createVerify } from "crypto";
+
+function verifySignature(
+  publicKeyBase64: string,
+  data: Uint8Array,
+  signatureDer: Uint8Array
+): boolean {
+  // Convert X9.62 public key to PEM format
+  const publicKeyBuffer = Buffer.from(publicKeyBase64, "base64");
+  const publicKey = {
+    key: publicKeyBuffer,
+    format: "raw",
+    type: "spki",
+    namedCurve: "P-256",
+  };
+
+  const verify = createVerify("SHA256");
+  verify.update(data); // Pass raw data - verify() hashes internally
+  return verify.verify(
+    { key: publicKey, dsaEncoding: "der" },
+    Buffer.from(signatureDer)
+  );
+}
+```
+
+**Example (Web Crypto API):**
+
+```typescript
+async function verifySignature(
+  publicKeyBase64: string,
+  data: Uint8Array,
+  signatureDer: Uint8Array
+): Promise<boolean> {
+  const publicKeyBytes = Uint8Array.from(atob(publicKeyBase64), (c) =>
+    c.charCodeAt(0)
+  );
+
+  // Import the raw public key
+  const publicKey = await crypto.subtle.importKey(
+    "raw",
+    publicKeyBytes,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["verify"]
+  );
+
+  // Note: Web Crypto expects raw R||S format, not DER
+  // You may need to convert DER to raw format (64 bytes)
+  const signatureRaw = derToRaw(signatureDer);
+
+  return crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    publicKey,
+    signatureRaw,
+    data // Pass raw data - verify() hashes internally
+  );
+}
+```
+
 ## Platform Support
 
 - **iOS**: Uses Secure Enclave for key generation and signing

package/dist-js/index.cjs

@@ -20,8 +20,8 @@ async function generateSecureKey(keyName, authMode = "pinOrBiometric") {
 async function listKeys(keyName, publicKey) {
     return await core.invoke("plugin:secure-element|list_keys", {
         payload: {
-            keyName: keyName || null,
-            publicKey: publicKey || null,
+            keyName: keyName ?? null,
+            publicKey: publicKey ?? null,
         },
     }).then((r) => r.keys);
 }
@@ -40,8 +40,8 @@ async function signWithKey(keyName, data) {
 async function deleteKey(keyName, publicKey) {
     return await core.invoke("plugin:secure-element|delete_key", {
         payload: {
-            keyName: keyName || null,
-            publicKey: publicKey || null,
+            keyName: keyName ?? null,
+            publicKey: publicKey ?? null,
         },
     }).then((r) => r.success);
 }

package/dist-js/index.d.ts

@@ -4,7 +4,7 @@ export interface KeyInfo {
 }
 export declare function ping(value: string): Promise<string | null>;
 export type AuthenticationMode = "none" | "pinOrBiometric" | "biometricOnly";
-export type HardwareBacking = "secureEnclave" | "strongBox" | "tee";
+export type HardwareBacking = "secureEnclave" | "strongBox" | "tee" | "ngc" | "tpm";
 export interface GenerateSecureKeyResult {
     publicKey: string;
     keyName: string;
@@ -19,9 +19,26 @@ export declare function signWithKey(keyName: string, data: Uint8Array): Promise<
  * At least one of keyName or publicKey must be provided.
  */
 export declare function deleteKey(keyName?: string, publicKey?: string): Promise<boolean>;
-export interface SecureElementSupport {
-    secureElementSupported: boolean;
-    teeSupported: boolean;
+/**
+ * Secure element hardware backing tiers.
+ * Ordered weakest → strongest: none < firmware < integrated < discrete
+ */
+export type SecureElementBacking = "none" | "firmware" | "integrated" | "discrete";
+/**
+ * Secure element capabilities for the current device.
+ */
+export interface SecureElementCapabilities {
+    /** A discrete physical security chip is available (e.g. discrete TPM, T2, StrongBox) */
+    discrete: boolean;
+    /** An on-die isolated security core is available (e.g. Secure Enclave, TrustZone/TEE) */
+    integrated: boolean;
+    /** Firmware-backed security is available but no dedicated secure processor (e.g. fTPM) */
+    firmware: boolean;
+    /** The security is emulated/virtual (e.g. vTPM in VM, iOS Simulator, Android Emulator) */
+    emulated: boolean;
+    /** The strongest tier available on this device */
+    strongest: SecureElementBacking;
+    /** Whether biometric-only authentication can be enforced at the key level */
     canEnforceBiometricOnly: boolean;
 }
-export declare function checkSecureElementSupport(): Promise<SecureElementSupport>;
+export declare function checkSecureElementSupport(): Promise<SecureElementCapabilities>;

package/dist-js/index.js

@@ -18,8 +18,8 @@ async function generateSecureKey(keyName, authMode = "pinOrBiometric") {
 async function listKeys(keyName, publicKey) {
     return await invoke("plugin:secure-element|list_keys", {
         payload: {
-            keyName: keyName || null,
-            publicKey: publicKey || null,
+            keyName: keyName ?? null,
+            publicKey: publicKey ?? null,
         },
     }).then((r) => r.keys);
 }
@@ -38,8 +38,8 @@ async function signWithKey(keyName, data) {
 async function deleteKey(keyName, publicKey) {
     return await invoke("plugin:secure-element|delete_key", {
         payload: {
-            keyName: keyName || null,
-            publicKey: publicKey || null,
+            keyName: keyName ?? null,
+            publicKey: publicKey ?? null,
         },
     }).then((r) => r.success);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tauri-plugin-secure-element-api",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Tauri plugin for secure element use on iOS (Secure Enclave) and Android (Strongbox and TEE).",
   "repository": "https://github.com/dkackman/tauri-plugin-secure-element",
   "license": "Apache-2.0",