expo-device-crypto 0.3.0 → 0.3.1

package/README.md

@@ -26,78 +26,36 @@ If you want to allow Face ID on iOS, add this to your app config:
 
 ## Supported Algorithms
 
-### Signature Algorithms
+### ✍️ Signature Algorithms
 
 - `ECDSA_SECP256R1_SHA256`
 
-**Curve:** P-256 / secp256r1. </br>
-**Hash:** SHA-256. </br>
+  **Curve:** P-256 / secp256r1. </br>
+  **Hash:** SHA-256. </br>
 
-### Encryption Algorithms
+### 🔐 Encryption Algorithms
 
 - `RSA_2048_PKCS1`
 
-**Key size:** 2048 bits. </br>
-**Padding:** PKCS#1 v1.5. </br>
+  **Key size:** 2048 bits. </br>
+  **Padding:** PKCS#1 v1.5. </br>
 
 - `RSA_2048_OAEP_SHA1`
 
-**Key size:** 2048 bits. </br>
-**Padding:** OAEP with SHA-1 and MGF1. </br>
+  **Key size:** 2048 bits. </br>
+  **Padding:** OAEP with SHA-1 and MGF1. </br>
 
 - `ECIES_P256_AES256_GCM`
 
-**Curve:** P-256 (secp256r1). </br>
-**Symmetric cipher:** AES-256-GCM. </br>
-**Key derivation:** HKDF-SHA256 (32-byte key from ECDH shared secret). </br>
+  **Curve:** P-256 (secp256r1). </br>
+  **Symmetric cipher:** AES-256-GCM. </br>
+  **Key derivation:** HKDF-SHA256 (32-byte key from ECDH shared secret). </br>
 
 **More coming soon...**
 
-## Example: ECDSA with Biometric
+## Example
 
-```ts
-import DeviceCrypto, {
-  AuthCheckResult,
-  AuthMethod,
-  SigningAlgorithm,
-} from "expo-device-crypto";
-
-const alias = "user-signing-key";
-const payload = "Sign this challenge payload";
-const algorithmType = SigningAlgorithm.ECDSA_SECP256R1_SHA256;
-const authMethod = AuthMethod.PASSCODE_OR_BIOMETRIC;
-
-// 1) Ensure device authentication is configured (passcode at minimum)
-const authStatus = DeviceCrypto.isAuthCheckAvailable();
-if (authStatus !== AuthCheckResult.AVAILABLE) {
-  throw new Error(`Authentication unavailable: ${authStatus}`);
-}
-
-// 2) Generate an auth-protected ECDSA key pair
-await DeviceCrypto.generateKeyPair(alias, {
-  requireAuthentication: true,
-  authMethod, // iOS: defined at key generation;
-  algorithmType,
-});
-
-// 3) Optional: share public key with backend
-const publicKeyPem = DeviceCrypto.getPublicKey(alias, { format: "PEM" });
-
-// 4) Sign with private key (prompts biometric/passcode on protected keys)
-// Note: The data to sign must be in UTF-8 format.
-// Note: This function should display the system user authentication prompt.
-const signature = await DeviceCrypto.sign(alias, payload, {
-  algorithmType,
-  authMethod, // Android: defined when signing
-});
-
-// 5) Verify locally (usually done server-side with stored public key)
-const isValid = await DeviceCrypto.verify(alias, payload, signature ?? "", {
-  algorithmType,
-});
-```
-
-## Example: RSA with Biometric
+### RSA with Biometric
 
 ```ts
 import DeviceCrypto, {
@@ -107,7 +65,7 @@ import DeviceCrypto, {
 } from "expo-device-crypto";
 
 const alias = "user-encryption-key";
-const secret = "Sensitive token";
+const dataToEncrypt = "Sensitive data";
 const algorithmType = EncryptionAlgorithm.RSA_2048_PKCS1;
 const authMethod = AuthMethod.PASSCODE_OR_BIOMETRIC;
 
@@ -125,17 +83,17 @@ await DeviceCrypto.generateKeyPair(alias, {
 });
 
 // 3) Optional: retrieve/share public key with backend
-const publicKeyPem = DeviceCrypto.getPublicKey(alias, { format: "PEM" });
+const publicKeyPem = DeviceCrypto.getPublicKey(alias);
 
 // 4) Encrypt with public key
-const encrypted = await DeviceCrypto.encrypt(alias, secret, {
+const encrypted = await DeviceCrypto.encrypt(alias, dataToEncrypt, {
   algorithmType,
 });
 
-// 5) Decrypt with private key (prompts biometric/passcode on protected keys)
+// 5) Decrypt with private key
 // Note: Data to decrypt must be in Base64 format.
 // Note: This function should display the system user authentication prompt.
-const decrypted = await DeviceCrypto.decrypt(alias, encrypted ?? "", {
+const decrypted = await DeviceCrypto.decrypt(alias, encrypted, {
   algorithmType,
   authMethod, // Android: defined when decrypting
 });
@@ -143,7 +101,11 @@ const decrypted = await DeviceCrypto.decrypt(alias, encrypted ?? "", {
 
 > ⚠️ Because iOS Keychain/Secure Enclave binds authentication policy to key creation, `authMethod` must be set in `generateKeyPair`. On Android Keystore, authentication is applied at key usage time, so `authMethod` is provided in operations like `sign` and `decrypt`.
 
-### Methods
+### 📚 More examples
+
+You can find additional usage examples in the [`examples` directory](https://github.com/piotr-pietras/expo-device-crypto/tree/master/examples) of the main repository.
+
+### 🛠️ Methods
 
 - `isAuthCheckAvailable(): AuthCheckResult`
   - Returns device authentication availability (`AVAILABLE`, `NO_HARDWARE`, `UNAVAILABLE`).
@@ -186,7 +148,7 @@ const decrypted = await DeviceCrypto.decrypt(alias, encrypted ?? "", {
 - `isStrongBoxAvailable(): boolean`
   - Returns `true` if StrongBox Keystore is supported on the device.
 
-## Important
+## ⚠️ Important
 
 ### Enable Strong Box on Android
 
@@ -211,3 +173,7 @@ If StrongBox is not available, Android falls back to the Trusted Execution Envir
 ### Secure Enclave support on iOS
 
 On iOS, only ECDSA keys can use the [Secure Enclave processor](https://developer.apple.com/documentation/security/ksecattrtokenidsecureenclave?utm_source=chatgpt.com#Discussion). RSA private-key operations are software-backed and handled by Apple’s system cryptographic services, which still provide strong isolation and protection.
+
+### ECIES - EC encryption schema
+
+For library purposes, ECIES is referred to as an encryption algorithm for simplification, even though it is technically a broader encryption scheme.

package/android/build.gradle

@@ -1,7 +1,7 @@
 apply plugin: 'com.android.library'
 
 group = 'expo.modules.devicecrypto'
-version = '0.3.0'
+version = '0.3.1'
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin
@@ -35,7 +35,7 @@ android {
   namespace "expo.modules.devicecrypto"
   defaultConfig {
     versionCode 1
-    versionName "0.3.0"
+    versionName "0.3.1"
   }
   lintOptions {
     abortOnError false

package/build/DeviceCrypto.types.d.ts

@@ -38,7 +38,7 @@ export type GenerateKeyPairOptions = {
     requireAuthentication?: boolean;
     /**
      * The method of authentication to use.
-     * Note that on Android you have to define it when signing.
+     * Note that on Android you have to define it when signing or decrypting.
      *
      * If you want to allow to use Face ID, you need to add the following to your app.json config file:
      * ```json

package/build/DeviceCrypto.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"DeviceCrypto.types.js","sourceRoot":"","sources":["../src/DeviceCrypto.types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,kEAAyC,CAAA;IACzC,4EAAmD,CAAA;IACnD,wDAA+B,CAAA;AACjC,CAAC,EAJW,qBAAqB,KAArB,qBAAqB,QAIhC;AAED,MAAM,CAAN,IAAY,eAIX;AAJD,WAAY,eAAe;IACzB,0CAAuB,CAAA;IACvB,8CAA2B,CAAA;IAC3B,8CAA2B,CAAA;AAC7B,CAAC,EAJW,eAAe,KAAf,eAAe,QAI1B;AAED,MAAM,CAAN,IAAY,UAGX;AAHD,WAAY,UAAU;IACpB,mCAAqB,CAAA;IACrB,6DAA+C,CAAA;AACjD,CAAC,EAHW,UAAU,KAAV,UAAU,QAGrB;AAED,MAAM,CAAN,IAAY,gBAEX;AAFD,WAAY,gBAAgB;IAC1B,qEAAiD,CAAA;AACnD,CAAC,EAFW,gBAAgB,KAAhB,gBAAgB,QAE3B;AAID,MAAM,CAAN,IAAY,mBAIX;AAJD,WAAY,mBAAmB;IAC7B,wDAAiC,CAAA;IACjC,gEAAyC,CAAA;IACzC,sEAA+C,CAAA;AACjD,CAAC,EAJW,mBAAmB,KAAnB,mBAAmB,QAI9B","sourcesContent":["export enum GenerateKeyPairResult {\n  KEY_PAIR_GENERATED = \"KEY_PAIR_GENERATED\",\n  KEY_PAIR_ALREADY_EXISTS = \"KEY_PAIR_ALREADY_EXISTS\",\n  NOT_AVAILABLE = \"NOT_AVAILABLE\",\n}\n\nexport enum AuthCheckResult {\n  AVAILABLE = \"AVAILABLE\",\n  NO_HARDWARE = \"NO_HARDWARE\",\n  UNAVAILABLE = \"UNAVAILABLE\",\n}\n\nexport enum AuthMethod {\n  PASSCODE = \"PASSCODE\",\n  PASSCODE_OR_BIOMETRIC = \"PASSCODE_OR_BIOMETRIC\",\n}\n\nexport enum SigningAlgorithm {\n  ECDSA_SECP256R1_SHA256 = \"ECDSA_SECP256R1_SHA256\",\n}\n\ntype EciesAlgorithm = \"ECIES_P256_AES256_GCM\";\ntype RsaAlgorithm = \"RSA_2048_PKCS1\" | \"RSA_2048_OAEP_SHA1\";\nexport enum EncryptionAlgorithm {\n  RSA_2048_PKCS1 = \"RSA_2048_PKCS1\",\n  RSA_2048_OAEP_SHA1 = \"RSA_2048_OAEP_SHA1\",\n  ECIES_P256_AES256_GCM = \"ECIES_P256_AES256_GCM\",\n}\n\nexport type GenerateKeyPairOptions = {\n  /**\n   * The algorithm type of the key to generate.\n   */\n  algorithmType: SigningAlgorithm | EncryptionAlgorithm;\n  /**\n   * Whether to require authentication to sign.\n   * Setting this to true will prompt biometric or passcode authentication before signing.\n   *\n   * Please check the *`isAuthCheckAvailable`* function to see if authentication is available.\n   * If authentication is not available, generating a key pair will throw an error.\n   * @default false\n   */\n  requireAuthentication?: boolean;\n  /**\n   * The method of authentication to use.\n   * Note that on Android you have to define it when signing.\n   *\n   * If you want to allow to use Face ID, you need to add the following to your app.json config file:\n   * ```json\n   * \"ios\": {\n   *   \"infoPlist\": {\n   *     \"NSFaceIDUsageDescription\": \"We use Face ID to secure your data.\",\n   *   }\n   * }\n   * ```\n   * @default AuthMethod.PASSCODE_OR_BIOMETRIC\n   * @platform ios 🍏\n   */\n  authMethod?: AuthMethod;\n  /**\n   * If the Strong Box is available, it will be used instead of the Trusted Execution Environment (TEE).\n   * @default false\n   * @platform android 🤖\n   */\n  preferStrongBox?: boolean;\n}\n\ntype BaseAuthOptions = {\n  /**\n   * The title of the prompt to show when authentication is required.\n   * @default \"Unlock\"\n   * @platform android 🤖\n   */\n  promptTitle?: string;\n  /**\n   * The subtitle of the prompt to show when authentication is required.\n   * @default \"Enter your PIN to continue\"\n   * @platform android 🤖\n   */\n  promptSubtitle?: string;\n  /**\n   * The method of authentication to use.\n   * Note that on iOS you have to define it when generating the key pair.\n   * @default AuthMethod.PASSCODE_OR_BIOMETRIC\n   * @platform android 🤖\n   */\n  authMethod?: AuthMethod;\n}\n\ntype BaseSigningOptions = {\n  /**\n   * The algorithm type of the key to use for signing.\n   */\n  algorithmType: SigningAlgorithm;\n};\ntype BaseVerifyOptions = BaseSigningOptions;\n\ntype BaseRsaEncryptionOptions = {\n  /**\n   * The algorithm type of the key to use for encrypting.\n   */\n  algorithmType: RsaAlgorithm;\n};\ntype BaseRsaDecryptionOptions = BaseRsaEncryptionOptions;\n\ntype BaseEciesEncryptionOptions = {\n  /**\n   * The algorithm type of the key to use for encrypting.\n   */\n  algorithmType: EciesAlgorithm;\n  /**\n   * The peer public key to use for ECIES.\n   */\n  peerPublicKey: string;\n};\ntype BaseEciesDecryptionOptions = BaseEciesEncryptionOptions;\n\nexport type SignOptions = BaseAuthOptions & BaseSigningOptions;\nexport type VerifyOptions = BaseVerifyOptions;\n\nexport type DecryptOptions =\n  | (BaseAuthOptions & BaseEciesDecryptionOptions)\n  | (BaseAuthOptions & BaseRsaDecryptionOptions);\nexport type EncryptOptions =\n  | (BaseAuthOptions & BaseEciesEncryptionOptions)\n  | BaseRsaEncryptionOptions;\n\nexport interface GetPublicKeyOptions {\n  /**\n   * The format of the public key to return.\n   * @default \"PEM\" (Base64 of PEM-encoded SubjectPublicKeyInfo (SPKI) for P‑256)\n   */\n  format?: \"PEM\" | \"BASE64\";\n}\n"]}
+{"version":3,"file":"DeviceCrypto.types.js","sourceRoot":"","sources":["../src/DeviceCrypto.types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAN,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,kEAAyC,CAAA;IACzC,4EAAmD,CAAA;IACnD,wDAA+B,CAAA;AACjC,CAAC,EAJW,qBAAqB,KAArB,qBAAqB,QAIhC;AAED,MAAM,CAAN,IAAY,eAIX;AAJD,WAAY,eAAe;IACzB,0CAAuB,CAAA;IACvB,8CAA2B,CAAA;IAC3B,8CAA2B,CAAA;AAC7B,CAAC,EAJW,eAAe,KAAf,eAAe,QAI1B;AAED,MAAM,CAAN,IAAY,UAGX;AAHD,WAAY,UAAU;IACpB,mCAAqB,CAAA;IACrB,6DAA+C,CAAA;AACjD,CAAC,EAHW,UAAU,KAAV,UAAU,QAGrB;AAED,MAAM,CAAN,IAAY,gBAEX;AAFD,WAAY,gBAAgB;IAC1B,qEAAiD,CAAA;AACnD,CAAC,EAFW,gBAAgB,KAAhB,gBAAgB,QAE3B;AAID,MAAM,CAAN,IAAY,mBAIX;AAJD,WAAY,mBAAmB;IAC7B,wDAAiC,CAAA;IACjC,gEAAyC,CAAA;IACzC,sEAA+C,CAAA;AACjD,CAAC,EAJW,mBAAmB,KAAnB,mBAAmB,QAI9B","sourcesContent":["export enum GenerateKeyPairResult {\n  KEY_PAIR_GENERATED = \"KEY_PAIR_GENERATED\",\n  KEY_PAIR_ALREADY_EXISTS = \"KEY_PAIR_ALREADY_EXISTS\",\n  NOT_AVAILABLE = \"NOT_AVAILABLE\",\n}\n\nexport enum AuthCheckResult {\n  AVAILABLE = \"AVAILABLE\",\n  NO_HARDWARE = \"NO_HARDWARE\",\n  UNAVAILABLE = \"UNAVAILABLE\",\n}\n\nexport enum AuthMethod {\n  PASSCODE = \"PASSCODE\",\n  PASSCODE_OR_BIOMETRIC = \"PASSCODE_OR_BIOMETRIC\",\n}\n\nexport enum SigningAlgorithm {\n  ECDSA_SECP256R1_SHA256 = \"ECDSA_SECP256R1_SHA256\",\n}\n\ntype EciesAlgorithm = \"ECIES_P256_AES256_GCM\";\ntype RsaAlgorithm = \"RSA_2048_PKCS1\" | \"RSA_2048_OAEP_SHA1\";\nexport enum EncryptionAlgorithm {\n  RSA_2048_PKCS1 = \"RSA_2048_PKCS1\",\n  RSA_2048_OAEP_SHA1 = \"RSA_2048_OAEP_SHA1\",\n  ECIES_P256_AES256_GCM = \"ECIES_P256_AES256_GCM\",\n}\n\nexport type GenerateKeyPairOptions = {\n  /**\n   * The algorithm type of the key to generate.\n   */\n  algorithmType: SigningAlgorithm | EncryptionAlgorithm;\n  /**\n   * Whether to require authentication to sign.\n   * Setting this to true will prompt biometric or passcode authentication before signing.\n   *\n   * Please check the *`isAuthCheckAvailable`* function to see if authentication is available.\n   * If authentication is not available, generating a key pair will throw an error.\n   * @default false\n   */\n  requireAuthentication?: boolean;\n  /**\n   * The method of authentication to use.\n   * Note that on Android you have to define it when signing or decrypting.\n   *\n   * If you want to allow to use Face ID, you need to add the following to your app.json config file:\n   * ```json\n   * \"ios\": {\n   *   \"infoPlist\": {\n   *     \"NSFaceIDUsageDescription\": \"We use Face ID to secure your data.\",\n   *   }\n   * }\n   * ```\n   * @default AuthMethod.PASSCODE_OR_BIOMETRIC\n   * @platform ios 🍏\n   */\n  authMethod?: AuthMethod;\n  /**\n   * If the Strong Box is available, it will be used instead of the Trusted Execution Environment (TEE).\n   * @default false\n   * @platform android 🤖\n   */\n  preferStrongBox?: boolean;\n}\n\ntype BaseAuthOptions = {\n  /**\n   * The title of the prompt to show when authentication is required.\n   * @default \"Unlock\"\n   * @platform android 🤖\n   */\n  promptTitle?: string;\n  /**\n   * The subtitle of the prompt to show when authentication is required.\n   * @default \"Enter your PIN to continue\"\n   * @platform android 🤖\n   */\n  promptSubtitle?: string;\n  /**\n   * The method of authentication to use.\n   * Note that on iOS you have to define it when generating the key pair.\n   * @default AuthMethod.PASSCODE_OR_BIOMETRIC\n   * @platform android 🤖\n   */\n  authMethod?: AuthMethod;\n}\n\ntype BaseSigningOptions = {\n  /**\n   * The algorithm type of the key to use for signing.\n   */\n  algorithmType: SigningAlgorithm;\n};\ntype BaseVerifyOptions = BaseSigningOptions;\n\ntype BaseRsaEncryptionOptions = {\n  /**\n   * The algorithm type of the key to use for encrypting.\n   */\n  algorithmType: RsaAlgorithm;\n};\ntype BaseRsaDecryptionOptions = BaseRsaEncryptionOptions;\n\ntype BaseEciesEncryptionOptions = {\n  /**\n   * The algorithm type of the key to use for encrypting.\n   */\n  algorithmType: EciesAlgorithm;\n  /**\n   * The peer public key to use for ECIES.\n   */\n  peerPublicKey: string;\n};\ntype BaseEciesDecryptionOptions = BaseEciesEncryptionOptions;\n\nexport type SignOptions = BaseAuthOptions & BaseSigningOptions;\nexport type VerifyOptions = BaseVerifyOptions;\n\nexport type DecryptOptions =\n  | (BaseAuthOptions & BaseEciesDecryptionOptions)\n  | (BaseAuthOptions & BaseRsaDecryptionOptions);\nexport type EncryptOptions =\n  | (BaseAuthOptions & BaseEciesEncryptionOptions)\n  | BaseRsaEncryptionOptions;\n\nexport interface GetPublicKeyOptions {\n  /**\n   * The format of the public key to return.\n   * @default \"PEM\" (Base64 of PEM-encoded SubjectPublicKeyInfo (SPKI) for P‑256)\n   */\n  format?: \"PEM\" | \"BASE64\";\n}\n"]}

package/ios/DeviceCrypto.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name           = 'DeviceCrypto'
-  s.version        = '0.3.0'
+  s.version        = '0.3.1'
   s.summary        = 'Device crypto'
   s.description    = 'Device crypto for Expo using device hardware capabilities'
   s.author         = 'Piotr Pietras'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-device-crypto",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Crypto for Expo using device hardware capabilities",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/DeviceCrypto.types.ts

@@ -43,7 +43,7 @@ export type GenerateKeyPairOptions = {
   requireAuthentication?: boolean;
   /**
    * The method of authentication to use.
-   * Note that on Android you have to define it when signing.
+   * Note that on Android you have to define it when signing or decrypting.
    *
    * If you want to allow to use Face ID, you need to add the following to your app.json config file:
    * ```json