# Tutorial: Installing Open Source FIDO2 Applet on IDEX Card (macOS Silicon)

**Date:** May 4, 2025
**Compiled For:** Internal Use / Reproducibility

## Goal

To compile the `BryanJacobs/FIDO2Applet` open-source code into a `.cap` file and install it onto an IDEX Java Card using macOS (Apple Silicon), an Omnikey PC/SC reader, and specific Card Manager keys, enabling the card to function as a FIDO2 authenticator.

## System & Hardware Used

* **Operating System:** macOS Sonoma (approx. 15.3.1) on Apple Silicon (M4)
* **Username:** `eminmahrt`
* **Card Reader:** HID Global OMNIKEY 5422 Smartcard Reader (PC/SC)
* **Smart Card:** IDEX Access Biometric Solution Card
* **Platform:** Based on IDX5601/IDX6601 solution [cite: 378]
* **Chip:** SLC38 Secure Element [cite: 386]
* **OS:** Java Card OS 3.0.5 [cite: 386]
* **Features:** Supports FIDO2 applications[cite: 378], includes fingerprint sensor (not used by this applet), pre-loaded IDEX IBA Applet (`A00000090501000101` [cite: 43]).

## Required Keys (Card Manager / ISD Keys)

The following keys were provided by the user and successfully used for authentication:

* **ENC Key:** `74F46B2A4727D97A324FA0979E12D1D1`
* **MAC Key:** `66DB726D9726A15634738282687D53CE`
* **DEK Key:** `412F16AE6D90106DBC0920200D81AE01`

> **WARNING:** These keys are specific to the card used during this process. Using incorrect keys on a different card can permanently lock (brick) it.

## Required Software

* **Homebrew:** macOS package manager.
* **Git:** Version control system.
* **Zulu JDK 8:** Java Development Kit version 8 (required for JCDK 3.0.5 compatibility).
* **Oracle JDK 11 or newer:** (JDK 24 was used) Required to *run* the GlobalPlatformPro tool (`gp.jar`).
* **Gradle:** Build automation tool.
* **Java Card Development Kit (JCDK) 3.0.5:** Obtained via Git submodule.
* **GlobalPlatformPro (`gp.jar`):** Tool for managing Java Card applets (downloaded manually).

---

## Step 1: Setup Development Environment

1. **Install Homebrew:** If not installed, open Terminal:

    /bin/bash -c "$(curl -fsSL [https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh](https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh))"
    # Follow on-screen instructions to add brew to PATH if needed

2. **Install Tools via Homebrew:**

    brew install git
    brew install --cask zulu@8
    brew install gradle
    # Install JDK 11+ if needed (we used existing JDK 24)
    # brew install openjdk@11

3. **Configure `JAVA_HOME` for JDK 8:** Edit your shell profile (`~/.zshrc` recommended for modern macOS) using `nano ~/.zshrc` or another editor. Add:

    export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

Save the file, then reload the configuration: `source ~/.zshrc` or open a new Terminal tab.

## Step 2: Get FIDO2 Applet Source Code & JCDK

1. **Clone Applet Repository:**

    # Navigate to your development directory first, e.g., cd ~/Developer
    git clone [https://github.com/BryanJacobs/FIDO2Applet.git](https://github.com/BryanJacobs/FIDO2Applet.git)
    cd FIDO2Applet

2. **Add JCDK 3.0.5 Submodule:** This downloads the necessary Java Card SDK files into an `sdks` subdirectory.

    git submodule add [https://github.com/martinpaljak/oracle_javacard_sdks.git](https://github.com/martinpaljak/oracle_javacard_sdks.git) sdks
    git submodule update --init --recursive

3. **Configure `JC_HOME`:** Edit your shell profile (`~/.zshrc`) again and add:

    # Ensure this path is correct relative to where you cloned FIDO2Applet
    # If FIDO2Applet is in ~/Developer/FIDO2Applet, this should work:
    export JC_HOME="$HOME/Developer/FIDO2Applet/sdks/jc305u4_kit"

Save and reload: `source ~/.zshrc`.

## Step 3: Build the FIDO2 Applet (.cap file)

1. **Navigate to Project Directory:** Ensure you are in the `FIDO2Applet` directory.

2. **(Troubleshooting 1: Gradle using wrong Java)**
* **Problem:** The first build attempt failed with `Unsupported class file major version 68`, indicating Gradle was using Java 24 instead of the required Java 8 (defined by `JAVA_HOME`).
* **Fix:** Force Gradle to use JDK 8 by creating/editing the file `gradle.properties` in the `FIDO2Applet` root directory:

        nano gradle.properties

Add this line (confirming the path with `echo $(/usr/libexec/java_home -v 1.8)`):

        org.gradle.java.home=/Library/Java/JavaVirtualMachines/zulu-8.jdk/Contents/Home

Save and exit (`Ctrl+O`, Enter, `Ctrl+X`).

3. **Run the Build:**

    ./gradlew buildJavaCard

4. **Verify Output:**
* The build should now complete successfully.
* **(Mistake 1: Incorrect Filename)** We initially looked for `FIDO2Applet.cap`. The correct output file, confirmed via screenshot, is located at: `build/javacard/FIDO2.cap`.

## Step 4: Prepare GlobalPlatformPro (GPPro) Tool

1. **(Troubleshooting 2: Homebrew `gp` command issues)**
* **Problem:** The `gp` command installed via Homebrew (`brew install martinpaljak/brew/gppro`) ran using Java 24 and failed to parse commands involving keys (it just printed the help text).
* **Fix:** Avoid the Homebrew version and use the official `.jar` release directly.
2. **Download `gp.jar`:**
* Go to [https://github.com/martinpaljak/GlobalPlatformPro/releases](https://github.com/martinpaljak/GlobalPlatformPro/releases).
* Download `gp.jar` from the "Assets" section of the latest release (e.g., `v24.10.15`).
3. **Place `gp.jar`:** Move the downloaded `gp.jar` into the `FIDO2Applet` project directory.

    # Example if downloaded to Downloads folder
    mv ~/Downloads/gp.jar .

## Step 5: Verify Card Manager Keys & Reader Communication

1. **Connect Reader & Card:** Plug in the Omnikey reader with the IDEX card.
2. **(Troubleshooting 3: GPTool requires Java 11+)**
* **Problem:** Running `java -jar gp.jar` using the Java 8 path failed (`UnsupportedClassVersionError: class file version 55.0`). The tool itself needs Java 11+.
* **Fix:** Execute `gp.jar` using the `java` command from a Java 11+ installation (we used the existing Java 24).
3. **Run Verification Command:** Use the `-list` command with the provided keys and the Java 24 path. Use the key flags (`--key-enc`, etc.) exactly as listed in the `gp --help` output.

    # Verify path with: echo $(/usr/libexec/java_home -v 24)/bin/java
    /Library/Java/JavaVirtualMachines/jdk-24.jdk/Contents/Home/bin/java -jar gp.jar \
        -debug \
        --key-enc 74F46B2A4727D97A324FA0979E12D1D1 \
        --key-mac 66DB726D9726A15634738282687D53CE \
        --key-dek 412F16AE6D90106DBC0920200D81AE01 \
        -list

4. **Confirm Success:** The command output showed successful authentication (`EXTERNAL AUTHENTICATE` returned `9000`) and listed the card's ISD and other applets/packages, confirming the keys are correct and the reader is communicating.

## Step 6: Install the FIDO2 Applet

1. **Navigate to Project Directory:** Ensure you are in `FIDO2Applet`.
2. **(Troubleshooting 4: Incorrect Filename)**
* **Problem:** The initial install attempt failed with `ERROR: build/javacard/FIDO2Applet.cap`.
* **Fix:** Use the correct filename identified in Step 3 (`FIDO2.cap`).
3. **Run Install Command:** Use the Java 11+ path, correct keys, and correct filename.

    /Library/Java/JavaVirtualMachines/jdk-24.jdk/Contents/Home/bin/java -jar gp.jar \
        --key-enc 74F46B2A4727D97A324FA0979E12D1D1 \
        --key-mac 66DB726D9726A15634738282687D53CE \
        --key-dek 412F16AE6D90106DBC0920200D81AE01 \
        -install build/javacard/FIDO2.cap

4. **Confirm Success:** The command output `build/javacard/FIDO2.cap loaded: us.q3q.fido2 A000000647` indicates the applet package was successfully loaded onto the card.

## Step 7: Testing the FIDO2 Functionality

1. **Test Websites:** Use [https://webauthn.io/](https://webauthn.io/) or similar FIDO2/WebAuthn test sites.
2. **Browser:** Use Safari, Brave, Chrome, etc.
3. **Process:**
* Connect reader, insert card.
* Click "Register" on the test site.
* **(Troubleshooting 5: Browser Prompts / Reader Recognition)**
* **Problem:** macOS shows prompts for iCloud/Phone first. After selecting "Use... security key", the browser prompt might appear but stall ("Insert... and touch it"), potentially because the browser isn't communicating correctly with the PC/SC reader on desktop. (User noted testing *did* work via mobile, suggesting the applet is functional).
* **Diagnosis/Workaround:** Ensure "Use your security key" is selected. Check browser debug logs (`chrome://device-log` for Brave) or use terminal tools (`pcsctest`, `fido2-token -L`) to verify reader communication outside the browser. If desktop browser interaction consistently fails despite the applet working (e.g., on mobile), consider FIDO PC/SC-to-HID bridge software or focus on environments where it works (like mobile).
* Follow prompts (potentially set a FIDO PIN for the credential).
* Attempt authentication on the test site.

---

**Conclusion:**

This process successfully built the open-source `BryanJacobs/FIDO2Applet` and installed it onto the IDEX card using the provided Card Manager keys after navigating several troubleshooting steps related to Java versions, tool compatibility, and file naming. Further troubleshooting may be needed for consistent desktop browser compatibility with the PC/SC reader.