@trustchex/react-native-sdk 1.409.0 → 1.464.0

package/lib/module/Shared/EIDReader/protocol/paceProtocol.js

@@ -0,0 +1,655 @@
+"use strict";
+
+import { AESSecureMessagingWrapper } from "../aesSecureMessagingWrapper.js";
+import { TripleDesSecureMessagingWrapper } from "../tripleDesSecureMessagingWrapper.js";
+import { PACEInfo } from "../paceInfo.js";
+import { PACEResult } from "./paceResult.js";
+import { PACEKeySpec } from "../paceKeySpec.js";
+import { EID_CONSTANTS } from "../constants/eidConstants.js";
+import { aesDecryptCBC, aesEncryptCBC, aesCMAC, deriveKey } from "../utils/aesCrypto.utils.js";
+import cryptoUtils from "../utils/crypto.utils.js";
+import TLVUtil from "../tlv/tlv.utils.js";
+import { Buffer } from 'buffer';
+import { ec as EC } from 'elliptic';
+
+// Register brainpool curves in elliptic's curve registry (RFC 5639).
+// These are not built-in but are required by most EU ePassports (parameterId 13 = brainpoolP256r1).
+(function registerBrainpoolCurves() {
+  const _elliptic = require('elliptic');
+  const _hash = require('hash.js');
+  const PresetCurve = _elliptic.curves.PresetCurve;
+  if (!_elliptic.curves.brainpoolP256r1) {
+    _elliptic.curves.brainpoolP256r1 = new PresetCurve({
+      type: 'short',
+      prime: null,
+      p: 'a9fb57dba1eea9bc3e660a909d838d726e3bf623d52620282013481d1f6e5377',
+      a: '7d5a0975fc2c3057eef67530417affe7fb8055c126dc5c6ce94a4b44f330b5d9',
+      b: '26dc5c6ce94a4b44f330b5d9bbd77cbf958416295cf7e1ce6bccdc18ff8c07b6',
+      n: 'a9fb57dba1eea9bc3e660a909d838d718c397aa3b561a6f7901e0e82974856a7',
+      hash: _hash.sha256,
+      gRed: false,
+      g: ['8bd2aeb9cb7e57cb2c4b482ffc81b7afb9de27e1e3bd23c23a4453bd9ace3262', '547ef835c3dac4fd97f8461a14611dc9c27745132ded8e545c1d54c72f046997']
+    });
+  }
+  if (!_elliptic.curves.brainpoolP384r1) {
+    _elliptic.curves.brainpoolP384r1 = new PresetCurve({
+      type: 'short',
+      prime: null,
+      p: '8cb91e82a3386d280f5d6f7e50e641df152f7109ed5456b412b1da197fb71123acd3a729901d1a71874700133107ec53',
+      a: '7bc382c63d8c150c3c72080ace05afa0c2bea28e4fb22787139165efba91f90f8aa5814a503ad4eb04a8c7dd22ce2826',
+      b: '04a8c7dd22ce28268b39b55416f0447c2fb77de107dcd2a62e880ea53eeb62d57cb4390295dbc9943ab78696fa504c11',
+      n: '8cb91e82a3386d280f5d6f7e50e641df152f7109ed5456b31f166e6cac0425a7cf3ab6af6b7fc3103b883202e9046565',
+      hash: _hash.sha384,
+      gRed: false,
+      g: ['1d1c64f068cf45ffa2a63a81b7c13f6b8847a3e77ef14fe3db7fcafe0cbd10e8e826e03436d646aaef87b2e247d4af1e', '8abe1d7520f9c2a45cb1eb8e95cfd55262b70b29feec5864e19c054ff99129280e4646217791811142820341263c5315']
+    });
+  }
+  if (!_elliptic.curves.brainpoolP512r1) {
+    _elliptic.curves.brainpoolP512r1 = new PresetCurve({
+      type: 'short',
+      prime: null,
+      p: 'aadd9db8dbe9c48b3fd4e6ae33c9fc07cb308db3b3c9d20ed6639cca703308717d4d9b009bc66842aecda12ae6a380e62881ff2f2d82c68528aa6056583a48f3',
+      a: '7830a3318b603b89e2327145ac234cc594cbdd8d3df91610a83441caea9863bc2ded5d5aa8253aa10a2ef1c98b9ac8b57f1117a72bf2c7b9e7c1ac4d77fc94ca',
+      b: '3df91610a83441caea9863bc2ded5d5aa8253aa10a2ef1c98b9ac8b57f1117a72bf2c7b9e7c1ac4d77fc94cadc083e67984050b75ebae5dd2809bd638016f723',
+      n: 'aadd9db8dbe9c48b3fd4e6ae33c9fc07cb308db3b3c9d20ed6639cca70330870553e5c414ca92619418661197fac10471db1d381085ddaddb58796829ca90069',
+      hash: _hash.sha512,
+      gRed: false,
+      g: ['81aee4bdd82ed9645a21322e9c4c6a9385ed9f70b5d916c1b43b62eef4d0098eff3b1f78e2d0d48d50d1687b93b97d5f7c6d5047406a5e688b352209bcb9f822', '7dde385d566332ecc0eabfa9cf7822fdf209f70024a57b1aa000c55b881f8111b2dcde494a5f485e5bca4bd88a2763aed1ca2b2fa8f0540678cd1e0f3ad80892']
+    });
+  }
+})();
+const ENC_MODE = 1;
+const MAC_MODE = 2;
+const PACE_MODE = 3;
+
+/**
+ * Implements the PACE (Password Authenticated Connection Establishment) protocol.
+ *
+ * Supports Generic Mapping (GM) with ECDH, as used by modern ePassports
+ * per ICAO Doc 9303 Part 11 and BSI TR-03110.
+ */
+export class PACEProtocol {
+  constructor(service, wrapper, maxTransceiveLengthForProtocol, maxTransceiveLengthForSecureMessaging, shouldCheckMAC) {
+    this.service = service;
+    this.wrapper = wrapper;
+    this.maxTransceiveLengthForProtocol = maxTransceiveLengthForProtocol;
+    this.maxTransceiveLengthForSecureMessaging = maxTransceiveLengthForSecureMessaging;
+    this.shouldCheckMAC = shouldCheckMAC;
+  }
+
+  /**
+   * Performs the full PACE protocol.
+   *
+   * @param accessKey the access key (MRZ or CAN based)
+   * @param oid the PACE OID from EF.CardAccess
+   * @param parameterId the standard domain parameter ID (e.g., 13 for brainpoolP256r1)
+   */
+  async doPACE(accessKey, oid, parameterId, progressCallback) {
+    const mappingType = PACEInfo.toMappingType(oid);
+    const agreementAlg = PACEInfo.toKeyAgreementAlgorithm(oid);
+    const cipherAlg = PACEInfo.toCipherAlgorithm(oid);
+    const digestAlg = PACEInfo.toDigestAlgorithm(oid);
+    const keyLength = PACEInfo.toKeyLength(oid);
+    if (agreementAlg !== 'ECDH') {
+      throw new Error(`Only ECDH key agreement is supported, found: ${agreementAlg}`);
+    }
+    if (mappingType !== 'GM' && mappingType !== 'IM') {
+      throw new Error(`Unsupported PACE mapping type: ${mappingType}`);
+    }
+
+    // Derive static PACE key K_pi from the access key
+    const staticPACEKeyHex = PACEProtocol.deriveStaticPACEKey(accessKey, cipherAlg, keyLength, digestAlg);
+
+    // Determine key reference
+    let paceKeyReference = EID_CONSTANTS.MRZ_PACE_KEY_REFERENCE;
+    if (accessKey instanceof PACEKeySpec) {
+      paceKeyReference = accessKey.getKeyReference();
+    }
+    const refPrivate = parameterId != null ? PACEProtocol.i2os(parameterId) : null;
+
+    // Pre-initialize curve and generate mapping key pair BEFORE any NFC I/O.
+    // brainpoolP512r1 curve init + key gen can take several seconds in JS,
+    // which would cause the ISO 14443-4 NFC link to time out if done between steps.
+    const curveName = PACEProtocol.getCurveName(parameterId ?? 13);
+    console.debug(`[PACE] Starting with OID=${oid}, parameterId=${parameterId}, ` + `curve=${curveName}, ` + `cipher=${cipherAlg}, keyLen=${keyLength}, mapping=${mappingType}`);
+    console.debug('[PACE] Pre-initializing curve and generating mapping key pair...');
+    const curve = new EC(curveName);
+    const mappingKeyPair = curve.genKeyPair();
+    console.debug('[PACE] Curve and mapping key pair ready');
+    if (progressCallback) {
+      progressCallback(5);
+    }
+
+    // Step 0: MSE:Set AT
+    console.debug('[PACE] Step 0: MSE:Set AT');
+    await this.service.sendMSESetATMutualAuth(this.wrapper, oid, paceKeyReference, refPrivate);
+    console.debug('[PACE] Step 0: OK');
+    if (progressCallback) {
+      progressCallback(6);
+    }
+
+    // Step 1: Encrypted Nonce
+    console.debug('[PACE] Step 1: Encrypted Nonce');
+    const piccNonce = await this.doPACEStep1(staticPACEKeyHex, cipherAlg, keyLength);
+    console.debug(`[PACE] Step 1: OK, nonce length=${piccNonce.length / 2} bytes`);
+    if (progressCallback) {
+      progressCallback(7);
+    }
+
+    // Step 2: Map Nonce (GM or IM with ECDH)
+    let mappingResult;
+    console.debug(`[PACE] Step 2: Map Nonce (${mappingType})`);
+    if (mappingType === 'IM') {
+      mappingResult = await this.doPACEStep2IM(curveName, piccNonce, cipherAlg);
+    } else {
+      mappingResult = await this.doPACEStep2GM(curveName, piccNonce, mappingKeyPair);
+    }
+    console.debug(`[PACE] Step 2: OK, ephGen.x=${mappingResult.ephemeralParams.generatorX.substring(0, 16)}...`);
+
+    // Step 3: Key Agreement
+    console.debug('[PACE] Step 3: Key Agreement');
+    const {
+      pcdKeyPair,
+      piccPublicKey,
+      sharedSecret
+    } = await this.doPACEStep3(curveName, mappingResult.ephemeralParams);
+    console.debug(`[PACE] Step 3: OK, sharedSecret=${sharedSecret.substring(0, 16)}...`);
+
+    // Derive session keys
+    const encKeyHex = deriveKey(sharedSecret, cipherAlg, keyLength, ENC_MODE);
+    const macKeyHex = deriveKey(sharedSecret, cipherAlg, keyLength, MAC_MODE);
+    if (progressCallback) {
+      progressCallback(8);
+    }
+
+    // Step 4: Mutual Authentication
+    console.debug('[PACE] Step 4: Mutual Authentication');
+    await this.doPACEStep4(oid, pcdKeyPair.publicKeyBytes, piccPublicKey, macKeyHex, cipherAlg, keyLength);
+    console.debug('[PACE] Step 4: OK - PACE completed successfully');
+
+    // Create secure messaging wrapper
+    let newWrapper;
+    const ssc = this.wrapper == null ? 0n : this.wrapper.getSendSequenceCounter();
+    if (cipherAlg === 'AES') {
+      newWrapper = new AESSecureMessagingWrapper(encKeyHex, macKeyHex, this.maxTransceiveLengthForSecureMessaging, this.shouldCheckMAC, ssc);
+    } else {
+      newWrapper = new TripleDesSecureMessagingWrapper(encKeyHex, macKeyHex, this.maxTransceiveLengthForSecureMessaging, this.shouldCheckMAC, 0n);
+    }
+    this.wrapper = newWrapper;
+    return new PACEResult(accessKey, mappingType, agreementAlg, cipherAlg, digestAlg, keyLength, newWrapper);
+  }
+
+  /**
+   * Step 1: Receive encrypted nonce from PICC, decrypt it.
+   */
+  async doPACEStep1(staticPACEKeyHex, cipherAlg, _keyLength) {
+    // Send empty General Authenticate to receive encrypted nonce
+    const step1Response = await this.service.sendGeneralAuthenticate(this.wrapper, [], 256, false);
+
+    // Unwrap 0x80 tag to get encrypted nonce
+    const encryptedNonce = await TLVUtil.unwrapDO(0x80, step1Response);
+    const encryptedNonceHex = Buffer.from(encryptedNonce).toString('hex');
+
+    // Decrypt nonce using static PACE key
+    const zeroIV = cipherAlg === 'AES' ? '00000000000000000000000000000000' : '0000000000000000';
+    let piccNonce;
+    if (cipherAlg === 'AES') {
+      piccNonce = aesDecryptCBC(encryptedNonceHex, staticPACEKeyHex, zeroIV);
+    } else {
+      piccNonce = cryptoUtils.decryptWith3DES(encryptedNonceHex, staticPACEKeyHex);
+    }
+    return piccNonce;
+  }
+
+  /**
+   * Step 2: Generic Mapping with ECDH.
+   * Maps the PICC nonce to ephemeral domain parameters.
+   */
+  async doPACEStep2GM(curveName, piccNonceHex, preGeneratedKeyPair) {
+    const curve = new EC(curveName);
+
+    // Use pre-generated mapping key pair to avoid NFC timeout
+    const mappingKeyPair = preGeneratedKeyPair;
+    const mappingPublicKey = mappingKeyPair.getPublic();
+
+    // Encode PCD mapping public key (uncompressed: 0x04 || x || y)
+    const pcdMappingPublicKeyBytes = PACEProtocol.encodeECPublicKey(mappingPublicKey.getX().toString(16), mappingPublicKey.getY().toString(16), curve);
+
+    // Send mapping data (tag 0x81)
+    const step2Data = Array.from(TLVUtil.wrapDO(0x81, Array.from(pcdMappingPublicKeyBytes)));
+    const le = step2Data.length > 233 ? EID_CONSTANTS.EXTENDED_MAX_TRANSCEIVE_LENGTH : this.maxTransceiveLengthForProtocol;
+    const step2Response = await this.service.sendGeneralAuthenticate(this.wrapper, step2Data, le, false);
+
+    // Unwrap 0x82 tag to get PICC mapping public key
+    const piccMappingPublicKeyBytes = await TLVUtil.unwrapDO(0x82, step2Response);
+
+    // Decode PICC mapping public key
+    const piccMappingPublicKey = curve.keyFromPublic(Buffer.from(piccMappingPublicKeyBytes));
+
+    // Get the full point H from the key agreement
+    const H = piccMappingPublicKey.getPublic().mul(mappingKeyPair.getPrivate());
+
+    // Map nonce: G~ = [s]G + H
+    const s = Buffer.from(piccNonceHex, 'hex');
+    const sBN = PACEProtocol.bufferToBN(s, curve);
+    const G = curve.g;
+    const sG = G.mul(sBN);
+    const ephemeralGenerator = sG.add(H);
+    return {
+      ephemeralParams: {
+        generatorX: ephemeralGenerator.getX().toString(16),
+        generatorY: ephemeralGenerator.getY().toString(16),
+        curve: curveName
+      }
+    };
+  }
+
+  /**
+   * Step 2 (IM): Integrated Mapping with ECDH.
+   * PCD sends a random nonce T to the PICC; both sides independently compute
+   * the ephemeral generator via R_p(s, t) and Icart point encoding.
+   * Reference: BSI TR-03110 Part 3, Section 3.3.2 and ICAO SAC TR 2010 Section 4.4.3.3.
+   */
+  async doPACEStep2IM(curveName, piccNonceHex, cipherAlg) {
+    if (cipherAlg !== 'AES') {
+      throw new Error(`PACE IM: Only AES cipher is supported in this implementation, found: ${cipherAlg}`);
+    }
+    const curve = new EC(curveName);
+
+    // Generate random PCD nonce T with same byte length as PICC nonce s
+    const piccNonceBytes = Buffer.from(piccNonceHex, 'hex');
+    const pcdNonceHex = cryptoUtils.getRandomValues(piccNonceBytes.length);
+
+    // Send PCD nonce T in DO 0x81 to PICC via General Authenticate
+    // The PICC response (DO 0x82) is empty per TR-SAC 3.3.2 and is ignored
+    const step2Data = Array.from(TLVUtil.wrapDO(0x81, Array.from(Buffer.from(pcdNonceHex, 'hex'))));
+    const le = step2Data.length > 233 ? EID_CONSTANTS.EXTENDED_MAX_TRANSCEIVE_LENGTH : this.maxTransceiveLengthForProtocol;
+    await this.service.sendGeneralAuthenticate(this.wrapper, step2Data, le, false);
+
+    // Compute t = R_p(s, T) via pseudo-random function
+    const p = BigInt('0x' + curve.curve.p.toString(16));
+    const tHex = PACEProtocol.pseudoRandomFunction(piccNonceHex, pcdNonceHex, p, cipherAlg);
+
+    // Map t to an elliptic curve point (new ephemeral generator) via Icart encoding
+    const {
+      x: generatorX,
+      y: generatorY
+    } = PACEProtocol.icartPointEncode(tHex, curve);
+    return {
+      ephemeralParams: {
+        generatorX,
+        generatorY,
+        curve: curveName
+      }
+    };
+  }
+
+  /**
+   * Step 3: Key Agreement.
+   * Generate ephemeral key pair, exchange public keys, compute shared secret.
+   */
+  async doPACEStep3(curveName, ephemeralParams) {
+    const curve = new EC(curveName);
+
+    // Generate ephemeral key pair on the curve with the new generator
+    // We need to use the ephemeral generator, but elliptic library
+    // works with the original curve generator.
+    // Generate a random scalar and compute public key as scalar * ephemeralGenerator
+    const privateKey = curve.genKeyPair().getPrivate();
+    const ephGen = curve.curve.point(ephemeralParams.generatorX, ephemeralParams.generatorY);
+    const pcdPublicPoint = ephGen.mul(privateKey);
+
+    // Encode PCD ephemeral public key
+    const pcdPublicKeyBytes = PACEProtocol.encodeECPoint(pcdPublicPoint.getX().toString(16), pcdPublicPoint.getY().toString(16), curve);
+
+    // Send public key (tag 0x83)
+    const step3Data = Array.from(TLVUtil.wrapDO(0x83, Array.from(pcdPublicKeyBytes)));
+    const le = step3Data.length > 233 ? EID_CONSTANTS.EXTENDED_MAX_TRANSCEIVE_LENGTH : this.maxTransceiveLengthForProtocol;
+    const step3Response = await this.service.sendGeneralAuthenticate(this.wrapper, step3Data, le, false);
+
+    // Unwrap 0x84 tag to get PICC ephemeral public key
+    const piccPublicKeyBytes = await TLVUtil.unwrapDO(0x84, step3Response);
+
+    // Decode PICC public key
+    const piccPublicPoint = curve.curve.decodePoint(Buffer.from(piccPublicKeyBytes));
+
+    // Check PCD and PICC public keys differ
+    if (pcdPublicPoint.getX().cmp(piccPublicPoint.getX()) === 0 && pcdPublicPoint.getY().cmp(piccPublicPoint.getY()) === 0) {
+      throw new Error('PCD and PICC public keys are the same');
+    }
+
+    // Key agreement: K = [SK_PCD] * PK_PICC
+    const sharedSecretPoint = piccPublicPoint.mul(privateKey);
+    const sharedSecretX = sharedSecretPoint.getX().toString(16);
+
+    // Pad to full field size
+    const fieldSize = curve.curve.p.byteLength() * 2;
+    const sharedSecret = sharedSecretX.padStart(fieldSize, '0');
+    return {
+      pcdKeyPair: {
+        publicKeyBytes: pcdPublicKeyBytes,
+        privateKey
+      },
+      piccPublicKey: Uint8Array.from(piccPublicKeyBytes),
+      sharedSecret
+    };
+  }
+
+  /**
+   * Step 4: Mutual Authentication.
+   * Compute and exchange authentication tokens.
+   */
+  async doPACEStep4(oid, pcdPublicKeyBytes, piccPublicKeyBytes, macKeyHex, cipherAlg, _keyLength) {
+    // Compute PCD authentication token: T_PCD = MAC(K_mac, PK_PICC~)
+    const authInput = PACEProtocol.buildAuthenticationTokenInput(oid, piccPublicKeyBytes);
+    const pcdToken = PACEProtocol.computeAuthenticationToken(authInput, macKeyHex, cipherAlg);
+
+    // Send authentication token (tag 0x85)
+    const step4Data = Array.from(TLVUtil.wrapDO(0x85, Array.from(Buffer.from(pcdToken, 'hex'))));
+    const step4Response = await this.service.sendGeneralAuthenticate(this.wrapper, step4Data, 256, true);
+
+    // Unwrap 0x86 tag to get PICC authentication token
+    const piccTokenBytes = await TLVUtil.unwrapDO(0x86, step4Response);
+
+    // Compute expected PICC token: T_PICC = MAC(K_mac, PK_PCD~)
+    const expectedAuthInput = PACEProtocol.buildAuthenticationTokenInput(oid, pcdPublicKeyBytes);
+    const expectedPICCToken = PACEProtocol.computeAuthenticationToken(expectedAuthInput, macKeyHex, cipherAlg);
+
+    // Verify
+    const expectedBytes = Buffer.from(expectedPICCToken, 'hex');
+    const receivedBytes = Buffer.from(piccTokenBytes);
+    if (Buffer.compare(expectedBytes, receivedBytes) !== 0) {
+      throw new Error('PICC authentication token mismatch');
+    }
+  }
+
+  /**
+   * Build the input for the authentication token MAC.
+   * Per BSI TR-03110 Part 3 Section 4.5.3, the authentication token is computed
+   * over a public key data object wrapped in tag 0x7F49.
+   */
+  static buildAuthenticationTokenInput(oid, publicKeyBytes) {
+    // The authentication token input is:
+    // 0x7F49 || len || 0x06 || OID_len || OID_value || 0x86 || pubkey_len || pubkey_value
+    const oidComponents = oid.split('.').map(Number);
+    const oidEncoded = PACEProtocol.encodeOIDValue(oidComponents);
+    const oidTLV = [0x06, oidEncoded.length, ...oidEncoded];
+    const pubKeyTLV = [0x86, ...PACEProtocol.encodeLengthBytes(publicKeyBytes.length), ...publicKeyBytes];
+    const innerData = [...oidTLV, ...pubKeyTLV];
+    // Wrap in 0x7F49 tag (two-byte tag)
+    const wrapped = [0x7f, 0x49, ...PACEProtocol.encodeLengthBytes(innerData.length), ...innerData];
+    return Buffer.from(wrapped).toString('hex');
+  }
+  static encodeLengthBytes(length) {
+    if (length < 0x80) {
+      return [length];
+    } else if (length < 0x100) {
+      return [0x81, length];
+    } else {
+      return [0x82, length >> 8 & 0xff, length & 0xff];
+    }
+  }
+
+  /**
+   * Compute authentication token using AES-CMAC or DES MAC.
+   */
+  static computeAuthenticationToken(dataHex, macKeyHex, cipherAlg) {
+    if (cipherAlg === 'AES') {
+      const mac = aesCMAC(dataHex, macKeyHex);
+      // Truncate to 8 bytes for authentication token
+      return mac.substring(0, 16);
+    } else {
+      return cryptoUtils.computeMac(dataHex, macKeyHex, true);
+    }
+  }
+
+  /**
+   * Derive the static PACE key K_pi from the access key.
+   */
+  static deriveStaticPACEKey(accessKey, cipherAlg, keyLength, _digestAlg) {
+    let keySeed;
+    if ('getDocumentNumber' in accessKey && typeof accessKey.getDocumentNumber === 'function') {
+      // BAC key spec - use MRZ-derived key seed
+      keySeed = accessKey.getKey();
+    } else if (accessKey instanceof PACEKeySpec) {
+      keySeed = accessKey.getKey();
+    } else {
+      keySeed = accessKey.getKey();
+    }
+    return deriveKey(keySeed, cipherAlg, keyLength, PACE_MODE);
+  }
+
+  // --- EC Utility Methods ---
+
+  static encodeECPublicKey(xHex, yHex, curve) {
+    return PACEProtocol.encodeECPoint(xHex, yHex, curve);
+  }
+  static encodeECPoint(xHex, yHex, curve) {
+    const fieldSize = curve.curve.p.byteLength();
+    const x = xHex.padStart(fieldSize * 2, '0');
+    const y = yHex.padStart(fieldSize * 2, '0');
+    const uncompressed = '04' + x + y;
+    return Uint8Array.from(Buffer.from(uncompressed, 'hex'));
+  }
+  static bufferToBN(buf, curve) {
+    // Convert buffer to BN used by elliptic library
+    const hex = buf.toString('hex');
+    return curve.keyFromPrivate(hex).getPrivate();
+  }
+  static encodeOIDValue(components) {
+    if (components.length < 2) {
+      throw new Error('OID must have at least 2 components');
+    }
+    const encoded = [];
+    encoded.push(components[0] * 40 + components[1]);
+    for (let i = 2; i < components.length; i++) {
+      const value = components[i];
+      if (value < 128) {
+        encoded.push(value);
+      } else {
+        const bytes = [];
+        let v = value;
+        bytes.push(v & 0x7f);
+        v >>= 7;
+        while (v > 0) {
+          bytes.push(v & 0x7f | 0x80);
+          v >>= 7;
+        }
+        bytes.reverse();
+        encoded.push(...bytes);
+      }
+    }
+    return encoded;
+  }
+
+  // ---- PACE IM helpers ----
+
+  /**
+   * Fast modular exponentiation using BigInt (square-and-multiply).
+   */
+  static modPow(base, exp, mod) {
+    if (mod === 1n) return 0n;
+    let result = 1n;
+    base = (base % mod + mod) % mod;
+    while (exp > 0n) {
+      if (exp & 1n) {
+        result = result * base % mod;
+      }
+      exp >>= 1n;
+      base = base * base % mod;
+    }
+    return result;
+  }
+
+  /**
+   * Pseudo-random function R_p(s, t) for PACE Integrated Mapping.
+   * Specified in ICAO Doc 9303 Part 11, Section 4.4.3.3.2 and BSI TR-03110.
+   *
+   * Uses the block cipher in CBC mode (IV=0) to derive a field element mod p.
+   *
+   * @param sHex - PICC nonce s (hex)
+   * @param tHex - PCD nonce t (hex, same length as s)
+   * @param p    - prime of the field GF(p)
+   * @param cipherAlg - 'AES'
+   * @returns field element as hex string (big-endian, same byte length as s)
+   */
+  static pseudoRandomFunction(sHex, tHex, p, cipherAlg) {
+    if (cipherAlg !== 'AES') {
+      throw new Error(`PACE IM pseudoRandomFunction: unsupported cipher ${cipherAlg}`);
+    }
+    const l = sHex.length / 2 * 8; // bit length of s
+
+    // Constants from ICAO Doc 9303 Part 11, Table 4 (also BSI TR-03110)
+    let c0Hex;
+    let c1Hex;
+    if (l === 128) {
+      c0Hex = 'a668892a7c41e3ca739f40b057d85904';
+      c1Hex = 'a4e136ac725f738b01c1f60217c188ad';
+    } else if (l === 192 || l === 256) {
+      c0Hex = 'd463d65234124ef7897054986dca0a174e28df758cbaa03f240616414d5a1676';
+      c1Hex = '54bd7255f0aaf831bec3423fcf39d69b6cbf066677d0faae5aadd99df8e53517';
+    } else {
+      throw new Error(`PACE IM pseudoRandomFunction: unsupported nonce length ${l} bits`);
+    }
+    const zeroIV = '00000000000000000000000000000000'; // 16-byte zero IV
+
+    // Initial key: key_0 = E_T(S) — encrypt S with key T, AES-CBC, IV=0
+    let keyHex = aesEncryptCBC(sHex, tHex, zeroIV);
+
+    // Generate output blocks: for each i, key_{i+1} = E_key_i(c0), x_i = E_key_i(c1)
+    // Repeat until n blocks of l bits cover p.bitLength + 64 bits
+    const pBitLength = p.toString(2).length;
+    const outputBlocks = [];
+    let n = 0;
+    while (n * l < pBitLength + 64) {
+      const newKeyHex = aesEncryptCBC(c0Hex, keyHex, zeroIV);
+      const xiHex = aesEncryptCBC(c1Hex, keyHex, zeroIV);
+      keyHex = newKeyHex;
+      outputBlocks.push(xiHex);
+      n++;
+    }
+
+    // x = (x_1 || x_2 || ... || x_n) mod p, returned as field-element-sized hex
+    const xBigInt = BigInt('0x' + outputBlocks.join(''));
+    const result = xBigInt % p;
+    const fieldBytes = sHex.length / 2;
+    return result.toString(16).padStart(fieldBytes * 2, '0');
+  }
+
+  /**
+   * Icart's deterministic encoding of a field element to a curve point.
+   * Maps an element t ∈ GF(p) to a point (x, y) on y² = x³ + ax + b.
+   * Requires p ≡ 3 (mod 4).
+   * Reference: ICAO SAC TR 2010, Section 5.2.
+   *
+   * @param tHex - field element as hex string
+   * @param curve - the elliptic curve
+   * @returns { x, y } as hex strings (field-element-width, big-endian)
+   */
+  static icartPointEncode(tHex, curve) {
+    const p = BigInt('0x' + curve.curve.p.toString(16));
+    // curve.curve.a and .b are stored in Montgomery (red) form in elliptic —
+    // must call fromRed() to get the actual field element values.
+    const a = BigInt('0x' + curve.curve.a.fromRed().toString(16));
+    const b = BigInt('0x' + curve.curve.b.fromRed().toString(16));
+    if (p % 4n !== 3n) {
+      throw new Error('PACE IM Icart encoding requires p ≡ 3 (mod 4)');
+    }
+    const t = BigInt('0x' + tHex);
+    // Helper: reduce x into [0, p) handling negative intermediate values
+    const mod = x => (x % p + p) % p;
+
+    // 1. alpha = -t² mod p
+    const alpha = mod(-(t * t % p));
+
+    // 2. x2 = -b * (1 + alpha + alpha²) / (a * (alpha + alpha²)) mod p
+    const alphaSq = alpha * alpha % p;
+    const alphaPlusAlphaSq = (alpha + alphaSq) % p;
+    const onePlusAlphaPlusAlphaSq = (1n + alphaPlusAlphaSq) % p;
+    const aTimesAlphaPlusAlphaSq = a * alphaPlusAlphaSq % p;
+    // Modular inverse via Fermat's little theorem: a^(p-2) mod p
+    const inv = PACEProtocol.modPow(aTimesAlphaPlusAlphaSq, p - 2n, p);
+    const x2 = mod(-(b * onePlusAlphaPlusAlphaSq % p) * inv % p);
+
+    // 3. x3 = alpha * x2 mod p
+    const x3 = alpha * x2 % p;
+
+    // 4. h2 = x2³ + a*x2 + b mod p
+    const h2 = mod(x2 * x2 % p * x2 % p + a * x2 % p + b);
+
+    // 5. u = t³ * h2 mod p
+    const u = t * t % p * t % p * h2 % p;
+
+    // 6. aa = h2^(p-1-(p+1)/4) mod p  (related to square root formula for p ≡ 3 mod 4)
+    const ppo4 = (p + 1n) / 4n;
+    const aa = PACEProtocol.modPow(h2, p - 1n - ppo4, p);
+
+    // 7. Check if h2 is a quadratic residue (aa² * h2 == 1), choose (x,y) accordingly
+    const aaSqTimesH2 = PACEProtocol.modPow(aa, 2n, p) * h2 % p;
+    let resX;
+    let resY;
+    if (aaSqTimesH2 === 1n) {
+      resX = x2;
+      resY = aa * h2 % p;
+    } else {
+      resX = x3;
+      resY = aa * u % p;
+    }
+
+    // All PACE curves (NIST P-*, brainpool) have cofactor = 1, no cofactor multiplication needed
+    const fieldHexLen = Math.ceil(p.toString(16).length / 2) * 2;
+    return {
+      x: resX.toString(16).padStart(fieldHexLen, '0'),
+      y: resY.toString(16).padStart(fieldHexLen, '0')
+    };
+  }
+  static i2os(value) {
+    if (value === 0) return [0];
+    const bytes = [];
+    let v = value;
+    while (v > 0) {
+      bytes.unshift(v & 0xff);
+      v >>= 8;
+    }
+    return bytes;
+  }
+
+  /**
+   * Map standard domain parameter ID to elliptic curve name.
+   */
+  static getCurveName(parameterId) {
+    // BSI TR-03110 Table D.2 / ICAO Doc 9303 standardized domain parameters
+    switch (parameterId) {
+      case 8:
+        return 'p192';
+      // NIST P-192
+      case 9:
+        return 'brainpoolP192r1';
+      case 10:
+        return 'p224';
+      // NIST P-224
+      case 11:
+        return 'brainpoolP224r1';
+      case 12:
+        return 'p256';
+      // NIST P-256
+      case 13:
+        return 'brainpoolP256r1';
+      // Most common in EU passports
+      case 14:
+        return 'brainpoolP320r1';
+      case 15:
+        return 'p384';
+      // NIST P-384
+      case 16:
+        return 'brainpoolP384r1';
+      case 17:
+        return 'brainpoolP512r1';
+      case 18:
+        return 'p521';
+      // NIST P-521
+      default:
+        throw new Error(`Unsupported domain parameter ID: ${parameterId}`);
+    }
+  }
+}

package/lib/module/Shared/EIDReader/protocol/paceResult.js

@@ -0,0 +1,37 @@
+"use strict";
+
+/**
+ * Result of PACE protocol execution.
+ */
+export class PACEResult {
+  constructor(paceKey, mappingType, agreementAlg, cipherAlg, digestAlg, keyLength, wrapper) {
+    this.paceKey = paceKey;
+    this.mappingType = mappingType;
+    this.agreementAlg = agreementAlg;
+    this.cipherAlg = cipherAlg;
+    this.digestAlg = digestAlg;
+    this.keyLength = keyLength;
+    this.wrapper = wrapper;
+  }
+  getPACEKey() {
+    return this.paceKey;
+  }
+  getMappingType() {
+    return this.mappingType;
+  }
+  getAgreementAlg() {
+    return this.agreementAlg;
+  }
+  getCipherAlg() {
+    return this.cipherAlg;
+  }
+  getDigestAlg() {
+    return this.digestAlg;
+  }
+  getKeyLength() {
+    return this.keyLength;
+  }
+  getWrapper() {
+    return this.wrapper;
+  }
+}