WIP: Update usability and repo clarity by petrs · Pull Request #278 · crocs-muni/JCAlgTest

petrs · 2026-02-25T08:51:58Z

This pull request introduces several improvements to the AlgTest JavaCard testing tools, focusing on enhanced usability, error handling, and support for new smartcard profiles. The most significant changes are:

more detailed help system for users
improved logging with a new verbosity option
better error reporting and recovery during performance tests
cleanup of repository for improved clarity

More detailed description is provided below.

Usability and Documentation Improvements:

Added a more detailed help system to AlgTestJClient, including usage examples, common troubleshooting tips, and bug reporting instructions. This is shown when the -help flag is used. [1] [2]
Updated the version history and changelog to reflect the new help features.

Logging and Output Enhancements:

Introduced a -verbose command-line flag to control console output detail; detailed per-algorithm logs are now shown on the console only when verbose mode is enabled, but always written to the log file. [1] [2] [3] [4]
Improved end-of-test messaging, clarifying where results are stored and encouraging users to submit results.

Error Handling and Recovery:

Enhanced error handling in performance testing: detects card removal or communication loss, provides clearer recovery instructions, and prompts the user to retry or skip problematic algorithms. [1] [2]

…ninstall, improved description for interactive and non-interactive modes, structure of folder with measurement results, Contributing, FAQ

Copilot

Pull request overview

This PR aims to improve JCAlgTest usability and repository clarity by expanding user-facing documentation/help, introducing a console verbosity flag, hardening performance-test recovery behavior, and updating project/repo housekeeping files.

Changes:

Expanded README/help guidance (examples, troubleshooting, contribution instructions) and added several new reference docs under docs/.
Added a -verbose CLI flag and extended logging/error-handling paths for performance testing.
Updated NetBeans/Ant project metadata and repo ignore rules as part of cleanup.

Reviewed changes

Copilot reviewed 17 out of 20 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
docs/smartcard_shops.txt	Adds a short list of smartcard vendor links.
docs/card_identification.txt	Adds reference links for identifying cards (NXP IDENTIFY, tooling sources).
docs/RID_list.txt	Adds a large RID-to-applicant mapping list (data/reference).
docs/DESFireSupportReadme.md	Adds extensive DESFire/Chameleon Mini documentation and usage examples.
coverity_model	Removes a previously-empty Coverity model stub.
README.md	Major usability/documentation expansion (modes, prerequisites, FAQ, contribution flow).
AlgTest_Process/run.bat	Changes output paths for generated web artifacts.
AlgTest_Process/nbproject/project.properties	Updates build classpath references for AlgTestProcess.
AlgTest_Process/cplc.py	Extends IC type mapping and removes duplicated logic.
AlgTest_JClient/src/algtestjclient/PerformanceTesting.java	Improves exception messaging and adds reconnect/retry guidance during perf tests.
AlgTest_JClient/src/algtestjclient/DirtyLogger.java	Adds “detail” logging methods and a verbose flag on the logger.
AlgTest_JClient/src/algtestjclient/Args.java	Introduces `-verbose` CLI flag.
AlgTest_JClient/src/algtestjclient/AlgTestJClient.java	Adds richer `--help` output and a top-level error banner; wires verbose into logger construction.
AlgTest_JClient/nbproject/project.xml	Adds a NetBeans build extension referencing `build-native.xml`.
AlgTest_JClient/nbproject/project.properties	Updates jcardsim jar reference and enables native bundling (and tweaks classpath).
AlgTest_JClient/nbproject/genfiles.properties	Updates generated CRCs for NetBeans build files.
AlgTest_JClient/nbproject/build-impl.xml	Imports `build-native.xml` into the generated Ant build.
.gitignore	Adds additional ignored paths (e.g., heap/, client logs, store output).

Comments suppressed due to low confidence (1)

AlgTest_JClient/src/algtestjclient/DirtyLogger.java:67

m_verbose is set via the new constructor, but the regular print/println methods ignore it, and printlnDetail/printDetail aren’t used anywhere else in the codebase. As a result, the -verbose flag currently has no effect on console verbosity. Either route the noisy per-algorithm output through the *Detail methods, or have print/println support log levels so the flag actually changes what is printed to stdout.

    boolean             m_verbose = false;

    public DirtyLogger(FileOutputStream logFile, boolean bOutputSystemOut) {
        m_logFile = logFile;
        m_bOutputSystemOut = bOutputSystemOut;
    }

    public DirtyLogger(FileOutputStream logFile, boolean bOutputSystemOut, boolean verbose) {
        m_logFile = logFile;
        m_bOutputSystemOut = bOutputSystemOut;
        m_verbose = verbose;
    }

    public void println() {
        String logLine = "\n";
        print(logLine);
    }
    public void println(String logLine)  {
        logLine += "\n";
        print(logLine);
    }
    public void print(String logLine) {
        if (m_bOutputSystemOut) {
            System.out.print(logLine);
        }

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-25T09:44:28Z

+        <buildExtensions xmlns="http://www.netbeans.org/ns/ant-build-extender/1">
+            <extension file="build-native.xml" id="j2sedeploy"/>
+        </buildExtensions>


This project adds a build extension for build-native.xml, but that file does not exist in the repo (so NetBeans/Ant will fail when resolving the extension/import). Either include build-native.xml in the PR or revert the build extension change.

Copilot · 2026-02-25T09:44:29Z

-    ${file.reference.jcardsim-3.0.5-SNAPSHOT.jar}:\
    ${file.reference.jcommander-1.81.jar}:\
-    ${file.reference.jcommander-1.81.jar}
+    ${file.reference.jcommander-1.81.jar}:\


javac.classpath includes ${file.reference.jcommander-1.81.jar} twice, which looks accidental and makes the project properties noisier to maintain. Remove the duplicate entry to keep the generated classpath clean.

Suggested change

${file.reference.jcommander-1.81.jar}:\

Copilot · 2026-02-25T09:44:29Z

 file.reference.AlgTestJClient.jar=..\\AlgTest_JClient\\dist\\AlgTestJClient.jar
+file.reference.AlgTestJClient.jar-1=..\\libs\\AlgTestJClient.jar
 file.reference.json-simple-1.1.1.jar=..\\libs\\json-simple-1.1.1.jar
 includes=**
 jar.archive.disabled=${jnlp.enabled}
 jar.compress=false
 jar.index=${jnlp.enabled}
 javac.classpath=\
    ${file.reference.AlgTestJClient.jar}:\
-    ${file.reference.json-simple-1.1.1.jar}
+    ${file.reference.json-simple-1.1.1.jar}:\
+    ${file.reference.AlgTestJClient.jar-1}
 # Space-separated list of extra javac options


file.reference.AlgTestJClient.jar-1 points to ..\\libs\\AlgTestJClient.jar, but there is no libs/AlgTestJClient.jar in the repository. Keeping a non-existent JAR on javac.classpath can break IDE builds and confuse contributors. Either add the missing JAR (if intended) or remove this extra reference and rely on the existing ..\\AlgTest_JClient\\dist\\AlgTestJClient.jar reference.

Copilot · 2026-02-25T09:44:29Z

+java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ SIMILARITY ..\..\algtest_web\javacard\web\
+java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ JCINFO ..\..\algtest_web\javacard\web\
+java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ SORTABLE ..\..\algtest_web\javacard\web\
+java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ RADAR ..\..\algtest_web\javacard\web\
+java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\variable\ SCALABILITY ..\..\algtest_web\javacard\web\


The output folder was changed from ..\\..\\algtest_results\\javacard\\web\\ to ..\\..\\algtest_web\\javacard\\web\\, but there’s no algtest_web directory in this repository and the README examples in this repo still reference algtest_results\\...\\web\\. If the intent is to generate into a sibling repo/folder, please document that explicitly (or keep the path consistent with README).

Suggested change

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ SIMILARITY ..\..\algtest_web\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ JCINFO ..\..\algtest_web\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ SORTABLE ..\..\algtest_web\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ RADAR ..\..\algtest_web\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\variable\ SCALABILITY ..\..\algtest_web\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ SIMILARITY ..\..\algtest_results\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ JCINFO ..\..\algtest_results\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ SORTABLE ..\..\algtest_results\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\fixed\ RADAR ..\..\algtest_results\javacard\web\

java -jar ..\AlgTest_Process\dist\AlgTestProcess.jar ..\..\algtest_results\javacard\Profiles\performance\variable\ SCALABILITY ..\..\algtest_results\javacard\web\

Copilot · 2026-02-25T09:44:30Z

+| **ALG_SUPPORT_EXTENDED** | Which JCA/JCE algorithms the card firmware supports and which key sizes are accepted | Knowing exactly what a card offers for ussage in your applet; checking whether firmware updates added new algorithms |
+| **ALG_PERFORMANCE_STATIC** | Throughput and latency of every supported algorithm on 256-byte payloads | Comparing the speed of crypto operations across cards or choosing the fastest algorithm for your protocol |
+| **ALG_PERFORMANCE_VARIABLE** | Same as above, using payload sizes from 16 to 512 bytes (16, 32, 64, 128, 256, 512) | Understanding how performance scales with increases data size (due to limited internal memory); |


Typos/grammar in the new table section reduce readability: “ussage” → “usage”, and “scales with increases data size” should be rephrased (e.g., “scales with increasing data size”). Also the last cell ends with an extra trailing semicolon.

Suggested change

| **ALG_SUPPORT_EXTENDED** | Which JCA/JCE algorithms the card firmware supports and which key sizes are accepted | Knowing exactly what a card offers for ussage in your applet; checking whether firmware updates added new algorithms |

| **ALG_PERFORMANCE_STATIC** | Throughput and latency of every supported algorithm on 256-byte payloads | Comparing the speed of crypto operations across cards or choosing the fastest algorithm for your protocol |

| **ALG_PERFORMANCE_VARIABLE** | Same as above, using payload sizes from 16 to 512 bytes (16, 32, 64, 128, 256, 512) | Understanding how performance scales with increases data size (due to limited internal memory); |

| **ALG_SUPPORT_EXTENDED** | Which JCA/JCE algorithms the card firmware supports and which key sizes are accepted | Knowing exactly what a card offers for usage in your applet; checking whether firmware updates added new algorithms |

| **ALG_PERFORMANCE_STATIC** | Throughput and latency of every supported algorithm on 256-byte payloads | Comparing the speed of crypto operations across cards or choosing the fastest algorithm for your protocol |

| **ALG_PERFORMANCE_VARIABLE** | Same as above, using payload sizes from 16 to 512 bytes (16, 32, 64, 128, 256, 512) | Understanding how performance scales with increasing data size (due to limited internal memory). |

Indeed, the found typos should be addressed

Copilot · 2026-02-25T09:44:31Z

+`persistent_mem_allocated`, `ram_deselect_allocated`, `ram_reset_allocated` - number of bytes of given memory type consumed during algorithm object allocation. May not be present for older measurements.
+
+**Is it safe to run this on a card I use for other purposes?**
+The AlgTest applet only performs allocation and cryptographic test operations — it does not modify persistent card data outside its own applet storage. However, the extensive testing may cause your card to temporarily block/cripple itslef due to faulty firmware. The problem is typically solved after card restart and applet removal, but some cards can be completely blocked (see [KNOWN_ISSUES.md](KNOWN_ISSUES.md)). **ALG_SUPPORT_EXTENDED** operation is typically safe, more extensive performance testing is potentially more dangerous. It is good practice to test on a dedicated card and uninstall the applet when done (see Uninstall above). Assume that your card can be blocked and do not use card you cannot effort to loose.


Several typos in this safety note make it hard to read: “itslef”, “cannot effort”, and “loose” should be corrected (e.g., “itself”, “cannot afford”, “lose”).

Suggested change

The AlgTest applet only performs allocation and cryptographic test operations — it does not modify persistent card data outside its own applet storage. However, the extensive testing may cause your card to temporarily block/cripple itslef due to faulty firmware. The problem is typically solved after card restart and applet removal, but some cards can be completely blocked (see [KNOWN_ISSUES.md](KNOWN_ISSUES.md)). **ALG_SUPPORT_EXTENDED** operation is typically safe, more extensive performance testing is potentially more dangerous. It is good practice to test on a dedicated card and uninstall the applet when done (see Uninstall above). Assume that your card can be blocked and do not use card you cannot effort to loose.

The AlgTest applet only performs allocation and cryptographic test operations — it does not modify persistent card data outside its own applet storage. However, the extensive testing may cause your card to temporarily block/cripple itself due to faulty firmware. The problem is typically solved after card restart and applet removal, but some cards can be completely blocked (see [KNOWN_ISSUES.md](KNOWN_ISSUES.md)). **ALG_SUPPORT_EXTENDED** operation is typically safe, more extensive performance testing is potentially more dangerous. It is good practice to test on a dedicated card and uninstall the applet when done (see Uninstall above). Assume that your card can be blocked and do not use card you cannot afford to lose.

Indeed, the found typos should be addressed

Copilot · 2026-02-25T09:44:31Z

+#### DF_COMM_MODE -- Manually sets the communication mode of the current session
+
+This commanf sets the encryption mode for cryptographic operations. 


This section has multiple issues: the second header repeats DF_COMM_MODE but the examples below are for DF_ENCMODE, and there are several typos (“congiguration”, “let's”, “commanf”). Please rename the second header to match the command being documented and fix the typos to avoid confusing users.

Suggested change

#### DF_COMM_MODE -- Manually sets the communication mode of the current session

This commanf sets the encryption mode for cryptographic operations.

#### DF_ENCMODE -- Manually sets the communication mode of the current session

This command sets the encryption mode for cryptographic operations.

The relevant typo to be fixed and probably the mentioned typo in title is relevant

Copilot · 2026-02-25T09:44:32Z

+A000000277; Interac Association; Canada
+A000000278; MOPASS Consortium; Japan
+A000000279; Poslovno Informacioni Sistemi d.o.o.; Serbia and Montenegro
+A000000280; Soci?t? d'Automatisation des Fr?res Bouadou - SATIM -; Algeria


This entry appears to have broken character encoding (e.g., Soci?t? / Fr?res). If this file is intended to be human-readable, please ensure it’s stored as UTF-8 and replace the ? placeholders with the correct accented characters so names aren’t corrupted.

Suggested change

A000000280; Soci?t? d'Automatisation des Fr?res Bouadou - SATIM -; Algeria

A000000280; Société d'Automatisation des Frères Bouadou - SATIM -; Algeria

Copilot · 2026-02-25T09:44:32Z

+        System.out.println("                        Re-insert the card and re-run with -fresh to skip ahead.");
+        System.out.println("  Results incomplete -- Re-run with -fresh to discard partial results and start over.");


The troubleshooting tip says “Re-insert the card and re-run with -fresh to skip ahead”, but -fresh forces a fresh measurement (i.e., it prevents continuing from the *_already_measured.list file). To continue from the last measured algorithm, users should not use -fresh (and answer “y” when prompted to continue).

Suggested change

System.out.println(" Re-insert the card and re-run with -fresh to skip ahead.");

System.out.println(" Results incomplete -- Re-run with -fresh to discard partial results and start over.");

System.out.println(" Re-insert the card and re-run without -fresh, then answer 'y' when prompted to continue from the last measurement.");

System.out.println(" Results incomplete -- Re-run with -fresh to discard partial results and start over from the beginning.");

Copilot · 2026-02-25T09:44:32Z

 <project xmlns:if="ant:if" xmlns:j2seproject1="http://www.netbeans.org/ns/j2se-project/1" xmlns:j2seproject3="http://www.netbeans.org/ns/j2se-project/3" xmlns:jaxrpc="http://www.netbeans.org/ns/j2se-project/jax-rpc" xmlns:unless="ant:unless" basedir=".." default="default" name="AlgTestJClient-impl">
+    <import file="build-native.xml"/>
    <fail message="Please build using Ant 1.8.0 or higher.">
        <condition>


build-impl.xml imports build-native.xml, but there is no AlgTest_JClient/nbproject/build-native.xml (or AlgTest_JClient/build-native.xml) in the repository. This will cause Ant/NetBeans builds to fail with an import error. Either add the missing file to the PR or remove the import/extension if it’s not required.

MaryBak · 2026-03-12T13:01:45Z

Overall, the introduced in the PR changes are nicely addressing the found usability issues. Upon addressing those Copilot's suggestions, could be merged

petrs added 9 commits February 22, 2026 19:12

feat: improve readme documentation with new sections: What you get, U…

016a8e9

…ninstall, improved description for interactive and non-interactive modes, structure of folder with measurement results, Contributing, FAQ

feat: Improved help and logging messages

2e2e75b

feat: improved exception handling

638f7f4

feat: update nbproject build files

f165942

chore: cleaning unsued/untracked stuff

e0b9392

feat: add additional parsing of cplc info

ef25308

ci: updat run scripts

36044a0

docs: adding relevant info

28976e0

Merge branch 'master' into devel

2bfc328

petrs requested a review from Copilot February 25, 2026 09:32

Copilot started reviewing on behalf of petrs February 25, 2026 09:33 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

		#### DF_COMM_MODE -- Manually sets the communication mode of the current session

		This commanf sets the encryption mode for cryptographic operations.

	A000000280; Soci?t? d'Automatisation des Fr?res Bouadou - SATIM -; Algeria
	A000000280; Société d'Automatisation des Frères Bouadou - SATIM -; Algeria

		System.out.println(" Re-insert the card and re-run with -fresh to skip ahead.");
		System.out.println(" Results incomplete -- Re-run with -fresh to discard partial results and start over.");

Conversation

petrs commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

MaryBak Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

MaryBak Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

MaryBak Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

MaryBak commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

petrs commented Feb 25, 2026 •

edited

Loading