Add Derive DUKPT AES Key operation (ANSI X9.24-3 AES-128)
This commit is contained in:
Jacob Marks
parent
46228977d6
commit
9207d79356
303
src/core/operations/DeriveDUKPTAESKey.mjs
Normal file
303
src/core/operations/DeriveDUKPTAESKey.mjs
Normal file
@ -0,0 +1,303 @@
|
||||
/**
|
||||
* @license Apache-2.0
|
||||
* @author Jacob Marks [https://jacobmarks.com]
|
||||
*/
|
||||
|
||||
import forge from "node-forge";
|
||||
import Operation from "../Operation.mjs";
|
||||
import OperationError from "../errors/OperationError.mjs";
|
||||
import { toHexFast } from "../lib/Hex.mjs";
|
||||
|
||||
// ── X9.24-3 key usage indicators (bytes 2-3 of derivation data) ───────────────
|
||||
|
||||
const KEY_USAGE = {
|
||||
"IK Derivation": 0x8000, // BDK → device Initial Key
|
||||
"Intermediate": 0x0000, // internal binary-tree node (not user-visible)
|
||||
"PIN Encryption": 0x1000,
|
||||
"MAC Generation": 0x2000, // sender / request direction
|
||||
"MAC Verification": 0x2001, // receiver / response direction
|
||||
"MAC Both Ways": 0x2002,
|
||||
"Data Encryption": 0x3000,
|
||||
"Data Decryption": 0x3001,
|
||||
"Data Both Ways": 0x3002,
|
||||
};
|
||||
|
||||
// AES-128 wire constants
|
||||
const ALGO_CODE = 0x0002; // AES-128 algorithm identifier
|
||||
const KEY_LEN_VAL = 0x0080; // 128 bits
|
||||
|
||||
// CMAC Rb constant for 128-bit block (RFC 4493)
|
||||
const RB = new Uint8Array(16);
|
||||
RB[15] = 0x87;
|
||||
|
||||
// ── Helpers ───────────────────────────────────────────────────────────────────
|
||||
|
||||
function parseHex(hex, expectedBytes, name) {
|
||||
const h = (hex || "").replace(/\s+/g, "");
|
||||
if (!/^[0-9a-fA-F]+$/.test(h) || h.length % 2 !== 0)
|
||||
throw new OperationError(`${name} must be a hex string.`);
|
||||
const bytes = new Uint8Array(h.length / 2);
|
||||
for (let i = 0; i < bytes.length; i++)
|
||||
bytes[i] = parseInt(h.slice(i * 2, i * 2 + 2), 16);
|
||||
if (expectedBytes && bytes.length !== expectedBytes)
|
||||
throw new OperationError(`${name} must be ${expectedBytes} bytes (got ${bytes.length}).`);
|
||||
return bytes;
|
||||
}
|
||||
|
||||
function xor(a, b) {
|
||||
const out = new Uint8Array(a.length);
|
||||
for (let i = 0; i < a.length; i++) out[i] = a[i] ^ b[i];
|
||||
return out;
|
||||
}
|
||||
|
||||
function shiftLeft1(a) {
|
||||
const out = new Uint8Array(a.length);
|
||||
for (let i = 0; i < a.length - 1; i++)
|
||||
out[i] = ((a[i] << 1) | (a[i + 1] >> 7)) & 0xFF;
|
||||
out[a.length - 1] = (a[a.length - 1] << 1) & 0xFF;
|
||||
return out;
|
||||
}
|
||||
|
||||
function toByteString(bytes) {
|
||||
return Array.from(bytes, b => String.fromCharCode(b)).join("");
|
||||
}
|
||||
|
||||
function hex(bytes) {
|
||||
return toHexFast(bytes).toUpperCase();
|
||||
}
|
||||
|
||||
// ── AES-128 ECB single-block encrypt ─────────────────────────────────────────
|
||||
// Reuses the forge cipher object across calls (same pattern as CMAC.mjs).
|
||||
|
||||
function makeEcbCipher(key16) {
|
||||
return forge.cipher.createCipher("AES-ECB", toByteString(key16));
|
||||
}
|
||||
|
||||
function ecbBlock(cipher, block16) {
|
||||
cipher.start();
|
||||
cipher.update(forge.util.createBuffer(toByteString(block16)));
|
||||
cipher.finish();
|
||||
return Uint8Array.from(cipher.output.getBytes(), c => c.charCodeAt(0)).slice(0, 16);
|
||||
}
|
||||
|
||||
// ── AES-CMAC (RFC 4493) ───────────────────────────────────────────────────────
|
||||
|
||||
function aesCmac(key16, message) {
|
||||
const cipher = makeEcbCipher(key16);
|
||||
|
||||
// Subkey generation
|
||||
const L = ecbBlock(cipher, new Uint8Array(16));
|
||||
const K1 = shiftLeft1(L);
|
||||
if (L[0] & 0x80) for (let i = 0; i < 16; i++) K1[i] ^= RB[i];
|
||||
const K2 = shiftLeft1(K1);
|
||||
if (K1[0] & 0x80) for (let i = 0; i < 16; i++) K2[i] ^= RB[i];
|
||||
|
||||
const n = Math.max(1, Math.ceil(message.length / 16));
|
||||
const flag = message.length > 0 && message.length % 16 === 0;
|
||||
|
||||
// Prepare final block
|
||||
const lastRaw = message.slice((n - 1) * 16);
|
||||
const lastBlock = new Uint8Array(16);
|
||||
lastBlock.set(lastRaw);
|
||||
if (!flag) lastBlock[lastRaw.length] = 0x80; // ISO/IEC 7816-4 padding
|
||||
const lastXored = xor(lastBlock, flag ? K1 : K2);
|
||||
|
||||
// CBC-MAC chain
|
||||
let X = new Uint8Array(16);
|
||||
for (let i = 0; i < n - 1; i++)
|
||||
X = ecbBlock(cipher, xor(X, message.slice(i * 16, (i + 1) * 16)));
|
||||
return ecbBlock(cipher, xor(X, lastXored));
|
||||
}
|
||||
|
||||
// ── X9.24-3 AES-128 DUKPT derivation ─────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Builds the 20-byte derivation data block (ANSI X9.24-3-2017).
|
||||
*
|
||||
* Layout:
|
||||
* [0-1] version = 0x0001
|
||||
* [2-3] key usage indicator
|
||||
* [4-5] algorithm = 0x0002 (AES-128)
|
||||
* [6-7] key length = 0x0080 (128 bits)
|
||||
* [8-15] IKI (8 bytes, from KSN bytes 0-7)
|
||||
* [16-19] counter register (4 bytes)
|
||||
*/
|
||||
function derivationData(usage, iki8, counterReg) {
|
||||
const d = new Uint8Array(20);
|
||||
d[0] = 0x00; d[1] = 0x01;
|
||||
d[2] = (usage >> 8) & 0xFF; d[3] = usage & 0xFF;
|
||||
d[4] = (ALGO_CODE >> 8) & 0xFF; d[5] = ALGO_CODE & 0xFF;
|
||||
d[6] = (KEY_LEN_VAL >> 8) & 0xFF; d[7] = KEY_LEN_VAL & 0xFF;
|
||||
d.set(iki8, 8);
|
||||
d[16] = (counterReg >>> 24) & 0xFF;
|
||||
d[17] = (counterReg >>> 16) & 0xFF;
|
||||
d[18] = (counterReg >>> 8) & 0xFF;
|
||||
d[19] = counterReg & 0xFF;
|
||||
return d;
|
||||
}
|
||||
|
||||
/** BDK + IKI → Initial Key loaded into the terminal. */
|
||||
function deriveIK(bdk16, iki8) {
|
||||
return aesCmac(bdk16, derivationData(KEY_USAGE["IK Derivation"], iki8, 0));
|
||||
}
|
||||
|
||||
/**
|
||||
* Binary-tree traversal from IK to the leaf transaction key.
|
||||
* Uses the 21 usable counter bits (bits 20-0 of the 4-byte counter field).
|
||||
*/
|
||||
function deriveTransactionKey(ik16, iki8, counter) {
|
||||
const usable = counter & 0x1FFFFF;
|
||||
if (usable === 0) throw new OperationError(
|
||||
"Counter 0 is reserved — no transactions have occurred yet."
|
||||
);
|
||||
if (usable === 0x1FFFFF) throw new OperationError(
|
||||
"Counter 0x1FFFFF indicates key exhaustion — this terminal needs a new IK."
|
||||
);
|
||||
let key = Uint8Array.from(ik16);
|
||||
let reg = 0;
|
||||
for (let bit = 20; bit >= 0; bit--) {
|
||||
if (usable & (1 << bit)) {
|
||||
reg |= (1 << bit);
|
||||
key = aesCmac(key, derivationData(KEY_USAGE["Intermediate"], iki8, reg));
|
||||
}
|
||||
}
|
||||
return key;
|
||||
}
|
||||
|
||||
/** Transaction key + purpose → purpose-specific working key. */
|
||||
function deriveWorkingKey(txKey16, iki8, counter, purposeName) {
|
||||
return aesCmac(txKey16, derivationData(KEY_USAGE[purposeName], iki8, counter & 0x1FFFFF));
|
||||
}
|
||||
|
||||
// ── Operation class ───────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Derive DUKPT AES Key operation.
|
||||
*/
|
||||
class DeriveDUKPTAESKey extends Operation {
|
||||
|
||||
constructor() {
|
||||
super();
|
||||
|
||||
this.name = "Derive DUKPT AES Key";
|
||||
this.module = "Payment";
|
||||
this.description = [
|
||||
"Derives AES DUKPT working keys per <b>ANSI X9.24-3</b> (AES-128).",
|
||||
"<br><br>",
|
||||
"<b>Input:</b> 16-byte BDK as hex, or the 16-byte Initial Key (IK) if you already have it.",
|
||||
"<br><br>",
|
||||
"The <b>KSN</b> is 12 bytes: 8-byte Initial Key Identifier (IKI) + 4-byte transaction counter.",
|
||||
"Only the low 21 bits of the counter are used for derivation (max 2,097,151 transactions per IK).",
|
||||
"<br><br>",
|
||||
"<b>Derivation data format (X9.24-3, 20 bytes):</b>",
|
||||
"<pre>",
|
||||
"[0-1] version = 0x0001\n",
|
||||
"[2-3] key usage indicator\n",
|
||||
"[4-5] algorithm = 0x0002 (AES-128)\n",
|
||||
"[6-7] key length = 0x0080 (128 bits)\n",
|
||||
"[8-15] IKI (8 bytes from KSN)\n",
|
||||
"[16-19] counter register (4 bytes)\n",
|
||||
"</pre>",
|
||||
"<b>Key usage codes:</b> PIN Encryption=0x1000, MAC Generation=0x2000, ",
|
||||
"MAC Verification=0x2001, MAC Both Ways=0x2002, ",
|
||||
"Data Encryption=0x3000, Data Decryption=0x3001, Data Both Ways=0x3002.",
|
||||
"<br><br>",
|
||||
"AES-192 and AES-256 require a multi-block KDF and are not implemented here.",
|
||||
" Cross-verify results against KABC (kabc.ca/payment/dukptaes) or the X9.24-3 annex test vectors.",
|
||||
].join("");
|
||||
this.inlineHelp = [
|
||||
"<strong>Input:</strong> BDK hex (16 bytes) or IK hex (16 bytes).",
|
||||
"<strong>KSN:</strong> 24 hex chars = 8-byte IKI + 4-byte counter.",
|
||||
].join(" ");
|
||||
this.testDataSamples = [
|
||||
{
|
||||
name: "Derive IK from BDK",
|
||||
input: "FEDCBA9876543210F1F1F1F1F1F1F1F1",
|
||||
args: ["BDK", "Derive IK", "123456789012345600000001", "PIN Encryption", false],
|
||||
},
|
||||
];
|
||||
this.infoURL = "https://www.eftlab.com/knowledge-base/dukpt-aes";
|
||||
this.inputType = "string";
|
||||
this.outputType = "string";
|
||||
this.args = [
|
||||
{
|
||||
name: "Input key type",
|
||||
type: "option",
|
||||
value: ["BDK", "Initial Key (IK)"],
|
||||
},
|
||||
{
|
||||
name: "Derive",
|
||||
type: "option",
|
||||
value: ["Initial Key (IK)", "Working Key"],
|
||||
},
|
||||
{
|
||||
name: "KSN (24 hex chars — 8-byte IKI + 4-byte counter)",
|
||||
type: "string",
|
||||
value: "",
|
||||
},
|
||||
{
|
||||
name: "Key purpose",
|
||||
type: "option",
|
||||
value: [
|
||||
"PIN Encryption",
|
||||
"MAC Generation",
|
||||
"MAC Verification",
|
||||
"MAC Both Ways",
|
||||
"Data Encryption",
|
||||
"Data Decryption",
|
||||
"Data Both Ways",
|
||||
],
|
||||
},
|
||||
{
|
||||
name: "Output as JSON",
|
||||
type: "boolean",
|
||||
value: false,
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {string} input
|
||||
* @param {Object[]} args
|
||||
* @returns {string}
|
||||
*/
|
||||
run(input, args) {
|
||||
const [inputKeyType, deriveMode, ksnHex, purpose, outputJson] = args;
|
||||
|
||||
const inputKey = parseHex(input, 16, "Input key");
|
||||
const ksn = parseHex(ksnHex, 12, "KSN");
|
||||
const iki = ksn.slice(0, 8);
|
||||
const counter = (ksn[8] << 24 | ksn[9] << 16 | ksn[10] << 8 | ksn[11]) >>> 0;
|
||||
|
||||
// Resolve IK
|
||||
const ik = inputKeyType === "BDK" ? deriveIK(inputKey, iki) : Uint8Array.from(inputKey);
|
||||
|
||||
if (deriveMode === "Initial Key (IK)") {
|
||||
if (outputJson) {
|
||||
const out = { inputKeyType, ik: hex(ik) };
|
||||
if (inputKeyType === "BDK") out.bdk = hex(inputKey);
|
||||
return JSON.stringify(out, null, 4);
|
||||
}
|
||||
return hex(ik);
|
||||
}
|
||||
|
||||
// Derive working key
|
||||
const txKey = deriveTransactionKey(ik, iki, counter);
|
||||
const wkKey = deriveWorkingKey(txKey, iki, counter, purpose);
|
||||
|
||||
if (outputJson) {
|
||||
const out = { inputKeyType, iki: hex(iki), counter: `0x${counter.toString(16).padStart(8, "0").toUpperCase()}` };
|
||||
if (inputKeyType === "BDK") out.bdk = hex(inputKey);
|
||||
out.ik = hex(ik);
|
||||
out.transactionKey = hex(txKey);
|
||||
out.purpose = purpose;
|
||||
out.workingKey = hex(wkKey);
|
||||
return JSON.stringify(out, null, 4);
|
||||
}
|
||||
|
||||
return hex(wkKey);
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
export default DeriveDUKPTAESKey;
|
||||
Loading…
x
Reference in New Issue
Block a user