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.