ciesign-react-native 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Coding Duck S.r.l.
+Copyright (c) 2025 PagoPA S.p.A. (ios/CieCard.swift is derived from pagopa/cie-sdk-ios)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# ciesign-react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+RSA signatures with the Italian electronic identity card (CIE 3.0) over NFC, for React Native. The library reads the card certificate and returns raw signatures; packaging them (PAdES, CAdES, XAdES…) is up to your code or your server.
+
+- One NFC tap and one PIN check, then as many signatures as you need. The card verifies the 8-digit PIN and signs with its PIN-protected key (RSA PKCS#1 v1.5); each signature is checked against the card certificate before it is returned.
+- Optionally, the PIN is saved behind Face ID, Touch ID or a fingerprint, protected by the Secure Enclave or the Android Keystore's secure hardware.
+
+A CIE signature is an advanced electronic signature (FEA), not a qualified one (FEQ/firma digitale). Validators don't trust the CIE CA by default, so recipients see an unknown signer until they trust it.
+
+> **Status:** not yet tested with a physical CIE, nor several signatures in one session. The iOS card protocol was compared byte by byte with PagoPA's Android SDK on a simulated card.
+
+## Install
+
+Requires iOS 16.4 or later, or an Android device with NFC. Expo module: it needs a development build (not Expo Go). Bare React Native apps need [Expo modules](https://docs.expo.dev/bare/installing-expo-modules/).
+
+```sh
+npx expo install ciesign-react-native
+```
+
+```json
+{ "expo": { "plugins": ["ciesign-react-native"] } }
+```
+
+The config plugin sets up iOS: the NFC tag reading entitlement, `NFCReaderUsageDescription` and `NSFaceIDUsageDescription` (override them with `["ciesign-react-native", { "nfcUsageDescription": "…", "faceIdUsageDescription": "…" }]`; existing values are kept) and the ISO 7816 application IDs. Without the plugin, add them by hand:
+
+```xml
+<!-- *.entitlements -->
+<key>com.apple.developer.nfc.readersession.formats</key>
+<array><string>TAG</string></array>
+
+<!-- Info.plist -->
+<key>NFCReaderUsageDescription</key>
+<string>…</string>
+<key>NSFaceIDUsageDescription</key> <!-- saved PIN only -->
+<string>…</string>
+<!-- keep this order -->
+<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
+<array>
+  <string>A0000002471001</string>
+  <string>A0000000308000000009816001</string>
+  <string>A00000000039</string>
+  <string>A0000002472001</string>
+  <string>00000000000000</string>
+</array>
+```
+
+Android needs nothing: the `NFC` and biometric permissions come with the library.
+
+## Use
+
+```ts
+import { cieSession } from 'ciesign-react-native';
+
+// DER DigestInfo of a SHA-256 hash: the algorithm prefix, then the 32-byte hash
+const SHA256 = [0x30, 0x31, 0x30, 0x0d, 0x06, 0x09, 0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x02, 0x01, 0x05, 0x00, 0x04, 0x20];
+const digestInfo = (hash: Uint8Array) => Uint8Array.from([...SHA256, ...hash]);
+
+const signatures = await cieSession(pin, async ({ certificate, sign }) => {
+  // e.g. CMS signed attributes, which reference the certificate
+  const hashes = await Promise.all(documents.map((document) => hashToSign(document, certificate)));
+  return Promise.all(hashes.map((hash) => sign(digestInfo(hash))));
+});
+```
+
+Inputs and outputs are `Uint8Array`. The promise stays pending until the card is tapped.
+
+| Export | |
+|---|---|
+| `cieSession(pin, use, { prompt?, error?, savePin?, biometricPrompt?, biometricCancel? })` | Waits for the card and verifies the PIN, then resolves to what `use({ certificate, sign })` resolves to. The NFC session ends when `use` settles: the card must stay on the phone until then. `pin` is the 8-digit PIN or `SAVED_PIN`. `prompt` and `error` are the iOS NFC sheet texts; the others are explained under [Saved PIN](#saved-pin). |
+| `certificate` | The card's DER authentication certificate: holder name and fiscal code are in its subject. |
+| `sign(digestInfo)` | RSA PKCS#1 v1.5 signature (the card adds the padding) of a DER DigestInfo, checked against `certificate`. Call it as often as needed while `use` runs; calls run one at a time, in order. |
+| `SAVED_PIN`, `pinStatus()`, `forgetPin()` | See [Saved PIN](#saved-pin). |
+| `cancel()` | Aborts the session in progress. Android has no system NFC sheet, so give users a cancel button. |
+
+iOS ends an NFC session 60 seconds after it starts, `use` included: prepare what does not depend on the certificate, such as a PDF's byte range, before calling `cieSession`.
+
+A PIN that is not 8 digits throws a plain `Error`. Card errors carry a `code`:
+
+| Code | Meaning |
+|---|---|
+| `WRONG_PIN_2`, `WRONG_PIN_1` | Wrong PIN, attempts left. Don't retry automatically. |
+| `PIN_LOCKED` | Three wrong PINs: the card needs the PUK. |
+| `NOT_A_CIE` | The tag is not a CIE. |
+| `TAG_LOST` | The card moved away during the operation. |
+| `CANCELLED` | `cancel()`, a newer session started, `sign` called after `use` settled, or the user closed the iOS sheet or the biometric prompt. |
+| `TIMEOUT` | iOS ends NFC sessions after 60 seconds. |
+| `BUSY` | iOS is still closing the previous NFC session: retry. |
+| `NFC_UNAVAILABLE` | No NFC, or, on Android, NFC turned off or no foreground activity. |
+| `CARD_ERROR` | Any other card or protocol failure, including a signature that does not verify against the card certificate. |
+| `PIN_NOT_SAVED` | `SAVED_PIN`, but no PIN is saved, or it was deleted because the enrolled biometrics changed or the device passcode was removed. Ask for the PIN. |
+| `WRONG_CARD` | `SAVED_PIN`, but the card is not the one the PIN was saved for. The PIN was not sent. |
+| `BIOMETRIC_UNAVAILABLE` | `SAVED_PIN` or `savePin` without a usable strong biometric: locked out after failed attempts, Face ID denied to the app, no secure hardware, or, for `savePin`, none enrolled. On Android, also when the activity is not a `FragmentActivity`. |
+
+On Android the app must stay in the foreground while the card is read.
+
+### Saved PIN
+
+Optional: apps that always pass the PIN don't need any of this. With `savePin`, the typed PIN is saved once the card accepts it. Later operations pass `SAVED_PIN`, which asks for Face ID, Touch ID or a fingerprint instead of the PIN.
+
+A biometric prompt appears only where the secure hardware requires one: to unlock on both platforms, and to save on Android, where the Keystore key encrypts only after a biometric. iOS saves with no prompt, because writing a Keychain item needs no authentication. Prompts come before the card is read; `biometricPrompt` and `biometricCancel` set their texts.
+
+```ts
+import { SAVED_PIN, cieSession, pinStatus } from 'ciesign-react-native';
+
+const status = await pinStatus(); // 'saved' | 'available' | 'unavailable'
+const signatures =
+  status === 'saved'
+    ? await cieSession(SAVED_PIN, use, { biometricPrompt: 'Firma i verbali' })
+    : await cieSession(pin, use, { savePin: status === 'available' && userWantsBiometrics });
+```
+
+- **Biometrics only.** iOS: a Keychain item with `.biometryCurrentSet`, available only while a passcode is set, never synced, backed up or moved to another device. Android: an AES-256-GCM Keystore key, in StrongBox when the device has it, otherwise in the TEE (software keys are refused). It encrypts and decrypts only right after a Class 3 biometric, through `BiometricPrompt` with a `CryptoObject`; the encrypted PIN is in `noBackupFilesDir`. The device passcode never unlocks it, and on Android face unlock only counts where it is Class 3.
+- **Cancelling the prompt cancels the operation** (`CANCELLED`): nothing is read or signed. After `CANCELLED` or `BIOMETRIC_UNAVAILABLE`, ask for the PIN, or retry without `savePin` to sign without saving.
+- **Enrolling a new face or finger deletes it**, and so does removing one on iOS, or all of them on Android, or turning off the device passcode (`PIN_NOT_SAVED` on the next use).
+- **Saved only after the card accepts it**, and deleted on `WRONG_PIN_*` or `PIN_LOCKED`: a PIN changed elsewhere costs one attempt, not three.
+- **Bound to its card.** The card's NIS (EF 1001), readable without the PIN, is checked first: another CIE gets `WRONG_CARD` and never sees the PIN.
+- **Native only.** A saved PIN is decrypted in native code and sent to the card; it never reaches JavaScript.
+- One PIN per app: saving again replaces it. `forgetPin()` deletes it. `savePin` fails with `BIOMETRIC_UNAVAILABLE` before the card is read when `pinStatus()` is `'unavailable'`.
+
+## How it works
+
+`cieSession` opens one NFC session: NIS read (EF 1001), secure messaging (Diffie-Hellman and device authentication), PIN verification, certificate read (EF 1003). Each `sign` then sends `MSE SET` (key `0x81`, RSA PKCS#1) and `INTERNAL AUTHENTICATE` with the DigestInfo over the same secure channel.
+
+- Android drives `CieCommands` from PagoPA's [`cie-sdk-android`](https://github.com/pagopa/cie-sdk-android) through a Java shim, because the class is Kotlin-internal. The dependency is pinned to `0.1.11`: check the shim before upgrading.
+- iOS implements the same protocol in `ios/CieCard.swift`, derived from PagoPA's [`cie-sdk-ios`](https://github.com/pagopa/cie-sdk-ios), whose signing code is not public.
+
+## Development
+
+Needs Node.js 24 and OpenSSL.
+
+```sh
+npm install
+npm test   # simulates the card with a throwaway RSA key made by OpenSSL
+```
+
+`npm test` covers the JavaScript side only: try changes to `ios/` and `android/` in a development build with a real CIE.
+
+Issues and pull requests are welcome, especially reports from physical cards. Report vulnerabilities privately, as described in [SECURITY.md](SECURITY.md).
+
+## Legal
+
+If your customers sign with the CIE in their dealings with you, you are an FEA provider under DPCM 22/02/2013 art. 55 c.2 lett. a, with the obligations of art. 57 (identification, information, insurance, 20-year retention). Get legal advice before offering CIE signing to third parties.
+
+## License
+
+[MIT](LICENSE). `ios/CieCard.swift` is derived from PagoPA's [`cie-sdk-ios`](https://github.com/pagopa/cie-sdk-ios), also MIT.

package/android/build.gradle

@@ -0,0 +1,21 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'it.codingduck.ciesign'
+version = '0.1.0'
+
+android {
+  namespace 'it.codingduck.ciesign'
+  defaultConfig {
+    versionCode 1
+    versionName '0.1.0'
+  }
+}
+
+dependencies {
+  // Exact version: CieCard.java calls classes that are Kotlin-internal in this release.
+  implementation 'it.pagopa.io.app.cie:cie:0.1.11'
+  implementation 'androidx.biometric:biometric:1.1.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.NFC" />
+</manifest>

package/android/src/main/java/it/codingduck/ciesign/CieCard.java

@@ -0,0 +1,30 @@
+package it.codingduck.ciesign;
+
+import it.pagopa.io.app.cie.cie.NfcEvent;
+import it.pagopa.io.app.cie.cie.OnTransmit;
+import it.pagopa.io.app.cie.cie.commands.CieCommands;
+
+/** PagoPA's CieCommands is Kotlin-internal: public in bytecode, so Java can call it and Kotlin cannot. */
+final class CieCard {
+  private final CieCommands commands;
+
+  CieCard(OnTransmit transmit) {
+    commands = new CieCommands(transmit);
+  }
+
+  /** NIS from EF.ID_Servizi, as hex: identifies the card and is readable without the PIN. */
+  String serviceId() throws Exception {
+    return commands.getServiceID();
+  }
+
+  /** Opens secure messaging, verifies the PIN and returns the certificate file (EF 1003, zero padded). */
+  byte[] open(String pin) throws Exception {
+    commands.startSecureChannel(pin);
+    return commands.readCertCie();
+  }
+
+  /** RSA signature of a DigestInfo with the PIN-protected key; the card adds the PKCS#1 v1.5 padding. */
+  byte[] sign(byte[] digestInfo) throws Exception {
+    return commands.sign(digestInfo, NfcEvent.SIGN);
+  }
+}

package/android/src/main/java/it/codingduck/ciesign/CieSignModule.kt

@@ -0,0 +1,207 @@
+package it.codingduck.ciesign
+
+import android.app.Activity
+import android.nfc.NfcAdapter
+import android.nfc.Tag
+import android.nfc.tech.IsoDep
+import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
+import androidx.biometric.BiometricPrompt
+import androidx.fragment.app.FragmentActivity
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import it.pagopa.io.app.cie.cie.ApduResponse
+import it.pagopa.io.app.cie.cie.CieSdkException
+import it.pagopa.io.app.cie.cie.NfcError
+import it.pagopa.io.app.cie.cie.NfcEvent
+import it.pagopa.io.app.cie.cie.OnTransmit
+import java.io.IOException
+import javax.crypto.Cipher
+
+class CieSignModule : Module() {
+  // Session state, guarded by `lock`. Ids come from JS; sessions up to `closed` are over, even if their connect arrives later.
+  private val lock = Any()
+  private var session = 0
+  private var closed = 0
+  private var pending: Promise? = null
+  private var tag: IsoDep? = null
+  private var card: CieCard? = null
+  private var prompt: BiometricPrompt? = null
+  private val savedPin by lazy { SavedPin(requireNotNull(appContext.reactContext)) }
+
+  override fun definition() = ModuleDefinition {
+    Name("CieSign")
+
+    // A null `pin` unlocks the saved one; `save` saves `pin` once the card accepts it. Both show the biometric prompt first.
+    AsyncFunction("connect") { id: Int, pin: String?, save: Boolean, _: String, biometricPrompt: String, biometricCancel: String, promise: Promise ->
+      val activity = appContext.currentActivity ?: throw CodedException("NFC_UNAVAILABLE", "No foreground activity", null)
+      val adapter = NfcAdapter.getDefaultAdapter(activity)
+      if (adapter?.isEnabled != true) throw CodedException("NFC_UNAVAILABLE", "NFC is missing or turned off", null)
+      synchronized(lock) {
+        if (id <= closed) throw cancelled()
+        end()
+        session = id
+        pending = promise
+      }
+      try {
+        when {
+          pin == null -> {
+            val saved = savedPin.saved() ?: throw CodedException("PIN_NOT_SAVED", "No saved PIN", null)
+            authenticate(activity, id, saved.cipher, biometricPrompt, biometricCancel) {
+              val unlocked = try {
+                String(it.doFinal(saved.pin))
+              } catch (e: Exception) {
+                savedPin.delete()
+                throw CodedException("PIN_NOT_SAVED", "The saved PIN cannot be decrypted", e)
+              }
+              read(activity, adapter, id, unlocked, saved.card, null)
+            }
+          }
+          save -> authenticate(activity, id, savedPin.encrypter(), biometricPrompt, biometricCancel) {
+            read(activity, adapter, id, pin, null, savedPin.seal(it, pin))
+          }
+          else -> read(activity, adapter, id, pin, null, null)
+        }
+      } catch (e: Exception) {
+        take(id)?.reject(coded(e))
+      }
+    }
+
+    AsyncFunction("sign") { id: Int, digestInfo: ByteArray ->
+      val card = synchronized(lock) { card.takeIf { session == id } } ?: throw cancelled()
+      try {
+        card.sign(digestInfo)
+      } catch (e: Exception) {
+        throw if (synchronized(lock) { session != id }) cancelled() else coded(e)
+      }
+    }
+
+    Function("close") { id: Int, _: String? ->
+      synchronized(lock) {
+        closed = maxOf(closed, id)
+        if (session in 1..id) end()
+      }
+    }
+
+    AsyncFunction("pinStatus") { savedPin.status() }
+
+    AsyncFunction("forgetPin") { savedPin.delete() }
+
+    OnDestroy { synchronized(lock) { end() } }
+  }
+
+  private fun take(id: Int): Promise? = synchronized(lock) { pending.takeIf { session == id }.also { if (it != null) pending = null } }
+
+  /** `owner`: NIS the saved PIN belongs to; `sealed`: encrypted PIN to save once the card accepts it. */
+  private fun read(activity: Activity, adapter: NfcAdapter, id: Int, pin: String, owner: String?, sealed: String?) {
+    val flags = NfcAdapter.FLAG_READER_NFC_A or NfcAdapter.FLAG_READER_NFC_B or NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK
+    synchronized(lock) {
+      if (session == id) adapter.enableReaderMode(activity, { onTag(it, id, pin, owner, sealed) }, flags, null)
+    }
+  }
+
+  /** Shows the biometric prompt for the Keystore `cipher`; once a strong biometric unlocks it, passes it to [then]. */
+  private fun authenticate(activity: Activity, id: Int, cipher: Cipher, title: String, cancel: String, then: (Cipher) -> Unit) {
+    val host = activity as? FragmentActivity ?: throw CodedException("BIOMETRIC_UNAVAILABLE", "The activity is not a FragmentActivity", null)
+    val info = BiometricPrompt.PromptInfo.Builder().setTitle(title).setNegativeButtonText(cancel).setAllowedAuthenticators(BIOMETRIC_STRONG).build()
+    val callback = object : BiometricPrompt.AuthenticationCallback() {
+      override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+        try {
+          then(requireNotNull(result.cryptoObject?.cipher))
+        } catch (e: Exception) {
+          take(id)?.reject(coded(e))
+        }
+      }
+
+      override fun onAuthenticationError(code: Int, message: CharSequence) {
+        take(id)?.reject(
+          when (code) {
+            BiometricPrompt.ERROR_NEGATIVE_BUTTON, BiometricPrompt.ERROR_USER_CANCELED, BiometricPrompt.ERROR_CANCELED, BiometricPrompt.ERROR_TIMEOUT -> cancelled()
+            else -> CodedException("BIOMETRIC_UNAVAILABLE", message.toString(), null)
+          }
+        )
+      }
+    }
+    activity.runOnUiThread {
+      val prompt = BiometricPrompt(host, { activity.runOnUiThread(it) }, callback)
+      if (synchronized(lock) { (session == id).also { if (it) this.prompt = prompt } }) prompt.authenticate(info, BiometricPrompt.CryptoObject(cipher))
+    }
+  }
+
+  // Runs on the NFC thread; the tag stays connected after returning, until the session ends.
+  private fun onTag(discovered: Tag, id: Int, pin: String, owner: String?, sealed: String?) {
+    val promise = take(id) ?: return
+    var pinStatus = 0
+    try {
+      val isoDep = IsoDep.get(discovered) ?: throw CodedException("NOT_A_CIE", "Not an ISO 14443-4 card", null)
+      isoDep.timeout = 10_000
+      isoDep.connect()
+      synchronized(lock) {
+        if (session != id) {
+          isoDep.close()
+          throw cancelled()
+        }
+        tag = isoDep
+      }
+      val c = CieCard(object : OnTransmit {
+        override fun sendCommand(apdu: ByteArray, nfcEvents: NfcEvent): ApduResponse {
+          val response = isoDep.transceive(apdu)
+          if (nfcEvents == NfcEvent.VERIFY_PIN) pinStatus = status(response)
+          return ApduResponse(response)
+        }
+
+        override fun error(error: NfcError) = Unit
+      })
+      val nis = c.serviceId()
+      if (owner != null && owner != nis) throw CodedException("WRONG_CARD", "Not the card the PIN was saved for", null)
+      val certificate = c.open(pin)
+      if (sealed != null) savedPin.store(nis, sealed)
+      synchronized(lock) {
+        if (session != id) throw cancelled()
+        card = c
+      }
+      promise.resolve(certificate)
+    } catch (e: Exception) {
+      val error = coded(e, pinStatus)
+      if (owner != null && (error.code.startsWith("WRONG_PIN") || error.code == "PIN_LOCKED")) savedPin.delete()
+      promise.reject(if (synchronized(lock) { session != id }) cancelled() else error)
+    }
+  }
+
+  private fun end() {
+    pending?.reject(cancelled())
+    pending = null
+    prompt?.let { appContext.currentActivity?.runOnUiThread(it::cancelAuthentication) }
+    prompt = null
+    card = null
+    runCatching { tag?.close() }
+    tag = null
+    session = 0
+    appContext.currentActivity?.let { NfcAdapter.getDefaultAdapter(it)?.disableReaderMode(it) }
+  }
+
+  private fun cancelled() = CodedException("CANCELLED", "Cancelled", null)
+
+  // Under secure messaging the card's status word is in DO 99, ahead of the MAC; otherwise it ends the response.
+  private fun status(response: ByteArray): Int {
+    val i = if (response.size >= 4 && response[0] == 0x99.toByte() && response[1] == 0x02.toByte()) 2 else response.size - 2
+    return ((response[i].toInt() and 0xFF) shl 8) or (response[i + 1].toInt() and 0xFF)
+  }
+
+  // PagoPA's SDK reports any unexpected VERIFY status as PIN_BLOCKED, so the status word decides.
+  private fun coded(e: Exception, pinStatus: Int = 0): CodedException {
+    val error = (e as? CieSdkException)?.getError()
+    return when {
+      e is CodedException -> e
+      error == NfcError.WRONG_PIN || error == NfcError.PIN_BLOCKED -> when {
+        pinStatus == 0x6983 || pinStatus == 0x63C0 -> CodedException("PIN_LOCKED", "PIN locked: unlock it with the PUK", e)
+        (pinStatus and 0xFFF0) == 0x63C0 -> CodedException("WRONG_PIN_${pinStatus and 0xF}", "Wrong PIN", e)
+        else -> CodedException("CARD_ERROR", "PIN verification failed: %04X".format(pinStatus), e)
+      }
+      error == NfcError.NOT_A_CIE -> CodedException("NOT_A_CIE", "Not a CIE", e)
+      e is IOException || e is SecurityException -> CodedException("TAG_LOST", "Card connection lost", e)
+      else -> CodedException("CARD_ERROR", error?.name ?: e.message ?: e.toString(), e)
+    }
+  }
+}

package/android/src/main/java/it/codingduck/ciesign/SavedPin.kt

@@ -0,0 +1,119 @@
+package it.codingduck.ciesign
+
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyInfo
+import android.security.keystore.KeyPermanentlyInvalidatedException
+import android.security.keystore.KeyProperties
+import android.util.Base64
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
+import expo.modules.kotlin.exception.CodedException
+import java.io.File
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.SecretKeyFactory
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * The CIE PIN encrypted with an AES-GCM Keystore key, in StrongBox when the device has it and otherwise in the TEE. The key
+ * encrypts and decrypts only right after a strong biometric matches one enrolled when it was made. The file is not backed up.
+ */
+internal class SavedPin(private val context: Context) {
+  /** The encrypted PIN, the NIS of its card and the decrypt cipher that a biometric unlocks. */
+  class Saved(val card: String, val pin: ByteArray, val cipher: Cipher)
+
+  private val file = File(context.noBackupFilesDir, "ciesign-pin")
+  private val keyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
+
+  val canSave get() = BiometricManager.from(context).canAuthenticate(BIOMETRIC_STRONG) == BiometricManager.BIOMETRIC_SUCCESS
+
+  fun status() = when {
+    saved() != null -> "saved"
+    canSave -> "available"
+    else -> "unavailable"
+  }
+
+  /** Null when nothing is saved, or when a biometric enrolled since then invalidated the key. */
+  fun saved(): Saved? {
+    val (card, iv, pin) = runCatching { file.readLines() }.getOrNull()?.takeIf { it.size == 3 } ?: return null
+    val cipher = cipher(Cipher.DECRYPT_MODE, Base64.decode(iv, Base64.NO_WRAP)) ?: return null.also { delete() }
+    return Saved(card, Base64.decode(pin, Base64.NO_WRAP), cipher)
+  }
+
+  /** Encrypt cipher that a biometric unlocks; makes the key first when there is no valid one. */
+  fun encrypter(): Cipher {
+    if (!canSave) throw unavailable()
+    return cipher(Cipher.ENCRYPT_MODE) ?: generate().let { cipher(Cipher.ENCRYPT_MODE) } ?: throw unavailable()
+  }
+
+  /** Encrypts `pin` with an unlocked [encrypter]; [store] saves the result once the card accepts the PIN. */
+  fun seal(cipher: Cipher, pin: String): String =
+    try {
+      val iv = cipher.iv
+      "${encode(iv)}\n${encode(cipher.doFinal(pin.toByteArray()))}"
+    } catch (e: Exception) {
+      throw unavailable(e)
+    }
+
+  /** Replaces the saved PIN; `card` is the NIS of the card that accepted it. */
+  fun store(card: String, sealed: String) = file.writeText("$card\n$sealed")
+
+  fun delete() {
+    file.delete()
+  }
+
+  private fun cipher(mode: Int, iv: ByteArray? = null): Cipher? {
+    val key = keyStore.getKey(ALIAS, null) as? SecretKey ?: return null
+    return try {
+      Cipher.getInstance("AES/GCM/NoPadding").apply { if (iv == null) init(mode, key) else init(mode, key, GCMParameterSpec(128, iv)) }
+    } catch (e: KeyPermanentlyInvalidatedException) {
+      null
+    }
+  }
+
+  private fun generate() {
+    val strongBox = Build.VERSION.SDK_INT >= 28 && context.packageManager.hasSystemFeature(PackageManager.FEATURE_STRONGBOX_KEYSTORE)
+    try {
+      val key = if (strongBox) runCatching { key(true) }.getOrElse { key(false) } else key(false)
+      val info = SecretKeyFactory.getInstance(key.algorithm, "AndroidKeyStore").getKeySpec(key, KeyInfo::class.java) as KeyInfo
+      val hardware = if (Build.VERSION.SDK_INT >= 31) {
+        info.securityLevel != KeyProperties.SECURITY_LEVEL_SOFTWARE && info.securityLevel != KeyProperties.SECURITY_LEVEL_UNKNOWN
+      } else {
+        @Suppress("DEPRECATION") info.isInsideSecureHardware
+      }
+      check(hardware && info.isUserAuthenticationRequirementEnforcedBySecureHardware) { "The Keystore key is not in secure hardware" }
+    } catch (e: Exception) {
+      keyStore.deleteEntry(ALIAS)
+      throw unavailable(e)
+    }
+  }
+
+  private fun key(strongBox: Boolean): SecretKey {
+    val spec = KeyGenParameterSpec.Builder(ALIAS, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+      .setKeySize(256)
+      .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+      .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+      .setUserAuthenticationRequired(true)
+      .setInvalidatedByBiometricEnrollment(true)
+      .apply {
+        if (Build.VERSION.SDK_INT >= 30) setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG)
+        else @Suppress("DEPRECATION") setUserAuthenticationValidityDurationSeconds(-1)
+        if (strongBox && Build.VERSION.SDK_INT >= 28) setIsStrongBoxBacked(true)
+      }
+      .build()
+    return KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore").apply { init(spec) }.generateKey()
+  }
+
+  private companion object {
+    const val ALIAS = "it.codingduck.ciesign.pin"
+
+    fun encode(bytes: ByteArray): String = Base64.encodeToString(bytes, Base64.NO_WRAP)
+
+    fun unavailable(cause: Throwable? = null) = CodedException("BIOMETRIC_UNAVAILABLE", "No strong biometric or secure hardware", cause)
+  }
+}

package/app.plugin.js

@@ -0,0 +1,25 @@
+const { withEntitlementsPlist, withInfoPlist } = require('expo/config-plugins');
+
+// iOS tries these AIDs in order when a card is detected; this order is the one known to work with the CIE.
+const AIDS = ['A0000002471001', 'A0000000308000000009816001', 'A00000000039', 'A0000002472001', '00000000000000'];
+const SELECT_IDENTIFIERS = 'com.apple.developer.nfc.readersession.iso7816.select-identifiers';
+const FORMATS = 'com.apple.developer.nfc.readersession.formats';
+
+module.exports = (
+  config,
+  {
+    nfcUsageDescription = 'La CIE viene letta via NFC per firmare documenti.',
+    faceIdUsageDescription = 'Face ID sblocca il PIN della CIE salvato sul dispositivo.',
+  } = {},
+) => {
+  config = withEntitlementsPlist(config, (c) => {
+    c.modResults[FORMATS] = [...new Set([...(c.modResults[FORMATS] ?? []), 'TAG'])];
+    return c;
+  });
+  return withInfoPlist(config, (c) => {
+    c.modResults.NFCReaderUsageDescription ??= nfcUsageDescription;
+    c.modResults.NSFaceIDUsageDescription ??= faceIdUsageDescription;
+    c.modResults[SELECT_IDENTIFIERS] = [...new Set([...(c.modResults[SELECT_IDENTIFIERS] ?? []), ...AIDS])];
+    return c;
+  });
+};

package/build/certificate.d.ts

@@ -0,0 +1,8 @@
+export type Bytes = Uint8Array;
+export declare const fail: (code: string, message: string) => Error & {
+    code: string;
+};
+/** Drops the padding after the certificate (the CIE stores it in a zero-filled file). */
+export declare const trimDer: (der: Bytes) => Uint8Array<ArrayBufferLike>;
+/** Checks an RSA PKCS#1 v1.5 signature of `digestInfo` against the certificate's public key. */
+export declare const verify: (certificate: Bytes, digestInfo: Bytes, signature: Bytes) => void;

package/build/certificate.js

@@ -0,0 +1,44 @@
+export const fail = (code, message) => Object.assign(new Error(message), { code });
+const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+/** Value start and end offsets of the DER TLV at `i`. */
+const bounds = (der, i = 0) => {
+    let length = der[i + 1];
+    let start = i + 2;
+    if (length & 0x80) {
+        const n = length & 0x7f;
+        length = 0;
+        for (let k = 0; k < n; k++)
+            length = length * 256 + der[start++];
+    }
+    return { start, end: start + length };
+};
+/** The TLVs inside a constructed DER value. */
+const children = (der) => {
+    const out = [];
+    for (let i = bounds(der).start; i < bounds(der).end; i = bounds(der, i).end)
+        out.push(der.subarray(i, bounds(der, i).end));
+    return out;
+};
+const value = (der) => der.subarray(bounds(der).start, bounds(der).end);
+/** Drops the padding after the certificate (the CIE stores it in a zero-filled file). */
+export const trimDer = (der) => {
+    const { end } = bounds(der);
+    if (der[0] !== 0x30 || !(end <= der.length))
+        throw fail('CARD_ERROR', 'Invalid certificate');
+    return der.subarray(0, end);
+};
+/** Checks an RSA PKCS#1 v1.5 signature of `digestInfo` against the certificate's public key. */
+export const verify = (certificate, digestInfo, signature) => {
+    const fields = children(children(certificate)[0]); // TBSCertificate, with or without [0] version
+    const spki = children(fields[fields[0][0] === 0xa0 ? 6 : 5]);
+    const [n, e] = children(value(spki[1]).subarray(1)).map((i) => BigInt('0x' + hex(value(i))));
+    let result = 1n;
+    for (let base = BigInt('0x' + (hex(signature) || '0')) % n, x = e; x > 0n; x >>= 1n, base = (base * base) % n) {
+        if (x & 1n)
+            result = (result * base) % n;
+    }
+    const k = (n.toString(16).length + 1) >> 1;
+    const encoded = '01' + 'ff'.repeat(k - digestInfo.length - 3) + '00' + hex(digestInfo);
+    if (signature.length !== k || result !== BigInt('0x' + encoded))
+        throw fail('CARD_ERROR', 'The signature does not match the certificate');
+};