Skip to main content

Passport NFC signing

VaultysID type 0x05 uses an ePassport chip's Active Authentication (AA) key to sign. The signing key stays on the chip. A verifier uses @vaultys/id and the public ID, including in a browser.

Install the core archive and the reader for your platform from the Passport NFC release. The core archive includes VaultysId.fromPassportAA(). The passport must expose an AA public key in DG15. An ECDSA passport also needs supported SHA-2 parameters in DG14. Some ePassports only offer Chip Authentication.

Install the desktop reader​

Use Node.js 20 or later, Go 1.26.10 or later, a C compiler, and an ISO 14443 USB reader with a PC/SC driver. macOS supplies PC/SC. On Linux, install PC/SC Lite and its development headers and enable the smart-card service.

On Apple silicon Macs, extract the helper from vaultys-passport-nfc-macos-arm64.tar.gz in the release. Go and a C compiler are needed when building the helper from source. To build it and pack the npm archives from the VaultysID checkout, run the following commands.

(cd passport-nfc && mkdir -p bin && CGO_ENABLED=1 go build -o bin/vaultys-passport-nfc . && npm pack)
(cd typescript && pnpm install --frozen-lockfile && pnpm build && pnpm pack)

Install vaultys-id-4.0.0.tgz and vaultys-passport-nfc-0.1.0.tgz in your Node.js app. Place the passport on the reader, then pass the printed machine-readable zone (MRZ). Use listPassportReaders() to find the exact reader name when several are connected. The helper uses the MRZ to start a PACE or BAC session.

import { VaultysId } from "@vaultys/id";
import { readPassportAA, type PassportNfcOptions } from "@vaultys/passport-nfc";

export async function signWithPassport(
options: PassportNfcOptions,
encryptionSecretKey: Uint8Array,
message: Uint8Array,
) {
const passport = await readPassportAA(options);
const identity = VaultysId.fromPassportAA({ ...passport, encryptionSecretKey });
return { id: identity.id, signature: await identity.sign(message) };
}

Set options.executable to the built helper's absolute path if it is outside PATH. Keep the passport stationary until signing completes. The reader opens a fresh chip session to sign all four AA challenges.

Use a mobile reader​

The native iOS library uses Core NFC and the Android library uses IsoDep. The host app starts NFC polling and bridges the native read and sign methods to its JavaScript code. With Capacitor, expose DG15 and DG14 from the native read method, and use the native sign method in the reader callback passed to VaultysId.fromPassportAA().

Download vaultys-passport-ios.zip for iOS 15 and later or vaultys-passport-android.aar for Android API 24 and later from the release. The iOS ZIP contains a local Swift package. Both packages expose a native PassportTagReader. To rebuild them from the source checkout, run ./build-mobile.sh ios with Xcode or ./build-mobile.sh android with the Android SDK, NDK, and JDK from passport-nfc/. The native sign call takes the four eight-byte challenges as one 32-byte buffer and returns four fixed-width chip responses in order.

On iOS, enable NFC Tag Reading, add a usage description, and list the passport application identifier A0000002471001 in the ISO 7816 app identifiers. On Android, declare the NFC permission and use foreground reader mode to discover an ISO-DEP tag. Test on physical NFC-capable devices.

Verify and restore​

import { VaultysId } from "@vaultys/id";

export function verifyPassportSignature(
id: Uint8Array,
message: Uint8Array,
signature: Uint8Array,
) {
return VaultysId.fromId(id).verify(message, signature);
}

Generate a 32-byte X25519 secret once for the identity and store it securely. Restore signing with the same passport AA key and X25519 secret. The existing IdManager profile and backup flows require an exportable signing secret. The public ID can be stored as a contact.

A valid AA signature proves access to the registered AA key. Passport authenticity and holder identity require separate evidence. The signature also carries no user-verification signal.