Feature/emv sm adapter

jpos/src/main/java/org/jpos/security/EMVCAPublicKey.java

@@ -0,0 +1,112 @@
+/*
+ * jPOS Project [http://jpos.org]
+ * Copyright (C) 2000-2026 jPOS Software SRL
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.jpos.security;
+
+import java.util.Arrays;
+
+import org.jpos.iso.ISOUtil;
+
+/**
+ * EMV Certification Authority (CA) Public Key, as used to verify Issuer
+ * Public Key Certificates during offline data authentication.
+ * <p>
+ * CA public keys are published per scheme (Visa, Mastercard, JCB, etc.)
+ * and identified by the pair ({@link #rid}, {@link #index}). They are
+ * clear public values — there is no LMK wrapping involved — so this
+ * type holds the modulus and exponent as raw {@code byte[]}.
+ * <p>
+ * Used as input to
+ * {@link EMVSMAdapter#recoverIssuerPublicKey(EMVCAPublicKey, byte[], byte[], byte[], String)}.
+ *
+ * @param rid 5-byte Registered Application Provider Identifier
+ *        (scheme-specific; e.g. Visa = {@code A000000003})
+ * @param index 1-byte CA public key index within the RID
+ * @param modulus big-endian RSA modulus, variable length per spec
+ *        (EMV currently allows 1024 to 1984 bits)
+ * @param exponent big-endian RSA public exponent, typically
+ *        {@code {0x03}} or {@code {0x01, 0x00, 0x01}}
+ * @param hashAlgorithmIndicator hash algorithm identifier as defined by
+ *        EMV (0x01 = SHA-1; other values currently unsupported by the
+ *        JCE adapter)
+ * @param publicKeyAlgorithmIndicator public key algorithm identifier
+ *        (0x01 = RSA)
+ */
+public record EMVCAPublicKey(byte[] rid, byte index, byte[] modulus,
+                             byte[] exponent, byte hashAlgorithmIndicator,
+                             byte publicKeyAlgorithmIndicator) {
+
+    public EMVCAPublicKey {
+        rid = copy(rid);
+        modulus = copy(modulus);
+        exponent = copy(exponent);
+    }
+
+    @Override
+    public byte[] rid() {
+        return copy(rid);
+    }
+
+    @Override
+    public byte[] modulus() {
+        return copy(modulus);
+    }
+
+    @Override
+    public byte[] exponent() {
+        return copy(exponent);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof EMVCAPublicKey other)) return false;
+        return index == other.index
+                && hashAlgorithmIndicator == other.hashAlgorithmIndicator
+                && publicKeyAlgorithmIndicator == other.publicKeyAlgorithmIndicator
+                && Arrays.equals(rid, other.rid)
+                && Arrays.equals(modulus, other.modulus)
+                && Arrays.equals(exponent, other.exponent);
+    }
+
+    @Override
+    public int hashCode() {
+        int h = Arrays.hashCode(rid);
+        h = 31 * h + index;
+        h = 31 * h + Arrays.hashCode(modulus);
+        h = 31 * h + Arrays.hashCode(exponent);
+        h = 31 * h + hashAlgorithmIndicator;
+        h = 31 * h + publicKeyAlgorithmIndicator;
+        return h;
+    }
+
+    @Override
+    public String toString() {
+        return "EMVCAPublicKey[rid=" + (rid == null ? "" : ISOUtil.hexString(rid))
+                + ", index=" + String.format("%02X", index & 0xff)
+                + ", modulus=" + (modulus == null ? "" : ISOUtil.hexString(modulus))
+                + ", exponent=" + (exponent == null ? "" : ISOUtil.hexString(exponent))
+                + ", hashAlg=" + String.format("%02X", hashAlgorithmIndicator & 0xff)
+                + ", pkAlg=" + String.format("%02X", publicKeyAlgorithmIndicator & 0xff)
+                + "]";
+    }
+
+    private static byte[] copy(byte[] bytes) {
+        return bytes == null ? null : bytes.clone();
+    }
+}

jpos/src/main/java/org/jpos/security/EMVCDAResult.java

@@ -0,0 +1,80 @@
+/*
+ * jPOS Project [http://jpos.org]
+ * Copyright (C) 2000-2026 jPOS Software SRL
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.jpos.security;
+
+import java.util.Arrays;
+
+import org.jpos.iso.ISOUtil;
+
+/**
+ * Outcome of a successful EMV CDA (Combined DDA + AC) verification, per
+ * EMV 4.4 Book 2 §6.6.
+ * <p>
+ * Returned by
+ * {@link EMVSMAdapter#verifyCDA(EMVICCPublicKey, byte[], byte[], byte[], byte[])}
+ * after all twelve validation steps pass. The terminal uses
+ * {@link #cid} to route the transaction (bits 7-6 of CID select
+ * ARQC / TC / AAC) and may use {@link #iccDynamicNumber} for
+ * downstream diagnostics.
+ *
+ * @param iccDynamicNumber the per-transaction nonce the card included
+ *        in its signed dynamic data (variable length, 2 to 8 bytes
+ *        per EMV §6.5.2)
+ * @param cid Cryptogram Information Data byte the card committed to
+ *        inside the signature (also returned in tag {@code 0x9F27}
+ *        out-of-band)
+ */
+public record EMVCDAResult(byte[] iccDynamicNumber, byte cid) {
+
+    public EMVCDAResult {
+        iccDynamicNumber = copy(iccDynamicNumber);
+    }
+
+    @Override
+    public byte[] iccDynamicNumber() {
+        return copy(iccDynamicNumber);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof EMVCDAResult other)) return false;
+        return cid == other.cid
+                && Arrays.equals(iccDynamicNumber, other.iccDynamicNumber);
+    }
+
+    @Override
+    public int hashCode() {
+        int h = Arrays.hashCode(iccDynamicNumber);
+        h = 31 * h + cid;
+        return h;
+    }
+
+    @Override
+    public String toString() {
+        return "EMVCDAResult[iccDynamicNumber="
+                + (iccDynamicNumber == null ? "" : ISOUtil.hexString(iccDynamicNumber))
+                + ", cid=" + String.format("%02X", cid & 0xff)
+                + "]";
+    }
+
+    private static byte[] copy(byte[] bytes) {
+        return bytes == null ? null : bytes.clone();
+    }
+}

jpos/src/main/java/org/jpos/security/EMVDerivedKey.java

@@ -0,0 +1,85 @@
+/*
+ * jPOS Project [http://jpos.org]
+ * Copyright (C) 2000-2026 jPOS Software SRL
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.jpos.security;
+
+import java.util.Arrays;
+import java.util.Objects;
+
+import org.jpos.iso.ISOUtil;
+
+/**
+ * Result of an EMV key-derivation operation: the derived key paired with its
+ * Key Check Value.
+ * <p>
+ * The {@code key} component is parametric on {@link SecureKey} so that the
+ * type carries through whatever wrapping the underlying security module
+ * uses. The software JCE adapter populates it with a {@link SecureDESKey}
+ * (wrapped under the LMK); a future HSM adapter that speaks ANSI X9.143 /
+ * TR-31 key blocks would populate it with its own key-block type.
+ * <p>
+ * The KCV is the standard 3-byte short check value (the high-order bytes of
+ * encrypting an all-zero block with the clear derived key). It is held as a
+ * {@code byte[]} to match {@link SecureKey#getKeyCheckValue()}; the
+ * {@link #equals(Object)}, {@link #hashCode()} and {@link #toString()}
+ * overrides below compare and render it by content rather than by array
+ * identity.
+ *
+ * @param <T> the {@link SecureKey} implementation type carried by the
+ *            underlying security module. By convention {@code T} is always
+ *            a {@code SecureKey} subtype (matching {@code SMAdapter}'s
+ *            usage), though the bound is left unconstrained to stay
+ *            compatible with the rest of the {@code org.jpos.security}
+ *            public API surface.
+ * @param key the derived key, wrapped per the adapter's convention
+ * @param kcv the Key Check Value, normally 3 bytes
+ */
+public record EMVDerivedKey<T>(T key, byte[] kcv) {
+
+    public EMVDerivedKey {
+        kcv = copy(kcv);
+    }
+
+    @Override
+    public byte[] kcv() {
+        return copy(kcv);
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof EMVDerivedKey<?> other)) return false;
+        return Objects.equals(key, other.key) && Arrays.equals(kcv, other.kcv);
+    }
+
+    @Override
+    public int hashCode() {
+        return 31 * Objects.hashCode(key) + Arrays.hashCode(kcv);
+    }
+
+    @Override
+    public String toString() {
+        return "EMVDerivedKey[key=" + key
+                + ", kcv=" + (kcv == null ? "" : ISOUtil.hexString(kcv))
+                + "]";
+    }
+
+    private static byte[] copy(byte[] bytes) {
+        return bytes == null ? null : bytes.clone();
+    }
+}