{"id":17271703,"url":"https://github.com/martinpaljak/apdu4j","last_synced_at":"2025-04-04T07:05:28.604Z","repository":{"id":24376999,"uuid":"27776499","full_name":"martinpaljak/apdu4j","owner":"martinpaljak","description":"Java code for APDU level smart cards: javax.smartcardio, PC/SC and remote JSON","archived":false,"fork":false,"pushed_at":"2025-03-11T09:32:41.000Z","size":2797,"stargazers_count":116,"open_issues_count":1,"forks_count":50,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-28T06:05:03.371Z","etag":null,"topics":["apdu","java","jna","pcsc","smartcard-reader","smartcardio"],"latest_commit_sha":null,"homepage":"https://github.com/martinpaljak/apdu4j/wiki","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martinpaljak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-09T16:47:26.000Z","updated_at":"2025-03-11T09:32:46.000Z","dependencies_parsed_at":"2023-12-10T18:24:30.618Z","dependency_job_id":"995ac17a-a9f1-41d3-a86f-5c4d2530466e","html_url":"https://github.com/martinpaljak/apdu4j","commit_stats":{"total_commits":358,"total_committers":5,"mean_commits":71.6,"dds":"0.11173184357541899","last_synced_commit":"77049d94a0471c6414adfc7fd986302d15203e64"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpaljak%2Fapdu4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpaljak%2Fapdu4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpaljak%2Fapdu4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpaljak%2Fapdu4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martinpaljak","download_url":"https://codeload.github.com/martinpaljak/apdu4j/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135142,"owners_count":20889420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apdu","java","jna","pcsc","smartcard-reader","smartcardio"],"created_at":"2024-10-15T08:46:22.760Z","updated_at":"2025-04-04T07:05:28.583Z","avatar_url":"https://github.com/martinpaljak.png","language":"Java","funding_links":[],"categories":["SIM Cards"],"sub_categories":["SIM/USIM Tools \u0026 Hardware"],"readme":"# apdu4j\n\n[![Build Status](https://github.com/martinpaljak/apdu4j/actions/workflows/robot.yml/badge.svg?branch=master)](https://github.com/martinpaljak/apdu4j/actions)\n\u0026nbsp;[![Maven version](https://img.shields.io/maven-metadata/v?label=javacard.pro%20version\u0026metadataUrl=https%3A%2F%2Fmvn.javacard.pro%2Fmaven%2Fcom%2Fgithub%2Fmartinpaljak%2Fapdu4j-pcsc%2Fmaven-metadata.xml)](https://gist.github.com/martinpaljak/c77d11d671260e24eef6c39123345cae)\n\u0026nbsp;[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/martinpaljak/apdu4j/blob/master/LICENSE)\n\u0026nbsp;[![Made in Estonia](https://img.shields.io/badge/Made_in-Estonia-blue)](https://estonia.ee)\n\nCommand line tool and library of useful Java classes for working with smart cards and smart card readers via [JSR268](https://jcp.org/en/jsr/detail?id=268) (commonly known as [javax.smartcardio](https://docs.oracle.com/javase/8/docs/jre/api/security/smartcardio/spec/javax/smartcardio/package-summary.html)). While focus is on desktop PC/SC readers, some code can be re-used with arbitrary \"APDU-command-response-ish\" interfaces, either as [CommandAPDU](https://docs.oracle.com/javase/8/docs/jre/api/security/smartcardio/spec/javax/smartcardio/CommandAPDU.html)/[ResponseAPDU](https://docs.oracle.com/javase/8/docs/jre/api/security/smartcardio/spec/javax/smartcardio/ResponseAPDU.html) pairs or plain byte arrays.\n\n## Features\n* PinPad support (PC/SC v2 part 10 / CCID)\n* Fixes all the stupid things with Java on non-windows platforms: OSX, Debian, Ubuntu, Fedora, CentOS, FreeBSD.\n* Java tools for convenient APDU logging, PIN handling and more\n* Bundles [jnasmartcardio][jnasmartcardio] in the command line tool for easy testing with a sane `javax.smartcardio` implementation with reader locking\n* Easy to use [`RemoteTerminal`](https://martinpaljak.github.io/apdu4j/apdu4j/remote/RemoteTerminal.html) for building central services\n  * Combine with [GlobalPlatformPro](https://github.com/martinpaljak/GlobalPlatformPro) for flexible central provisioning\n\n#### Jump to ...\n* [Download](#get-it-now)\n* [Usage from command line](#usage-from-command-line)\n* [Usage from Java](#usage-from-java)\n* [Similar and related projects](#similar-and-related-projects)\n* [Contact](#contact)\n\n### Get it now!\n* Download latest pre-built .JAR or .EXE from [release area](https://github.com/martinpaljak/apdu4j/releases)\n* Or fetch from github and build it yourself, it is really easy (more instructions in [CONTRIBUTING](./CONTRIBUTING.md)):\n\n```shell\ngit clone https://github.com/martinpaljak/apdu4j\ncd apdu4j\n./mvnw package\n```\n\n### Usage from command line\n * Before you begin:\n   * You can run the command line utility anywhere where Java runs, like this:\n\n         java -jar apdu4j.jar\n   * But it is easier to add an alias or use a wrapper.            \n   * On Linux add an alias to the shell like this:\n\n         alias sc=\"java -jar $(PWD)/apdu4j.jar\"\n         # Now you can avoid typing java -jar and sc works from any folder\n         sc -h\n\n   * On Windows just use pre-packaged `apdu4j.exe` like this or rename it:\n\n         apdu4j.exe -h\n\n * Display all options:\n\n       sc -h\n \n * List readers:\n\n       sc -l\n   \n   Will produce something like\n\n       [ ] Gemalto Ezio Shield 01 00\n       [*] ACS ACR 38U-CCID 02 00\n\n   The presence of a card or token is indicated with the asterisk\n * Be verbose:\n\n       sc -l -v\n       \n   Will produce:\n\n       # Using jnasmartcardio.Smartcardio - JNA2PCSC version 0.2\n       # Found 4 terminals\n       [X] [   ] Yubico Yubikey 4 U2F+CCID\n                 3BF81300008131FE15597562696B657934D4\n       [ ] [VMD] Gemalto Ezio Shield 01 00\n       [*] [   ] ACS ACR 38U-CCID 02 00\n                 3BF91300008131FE454A434F503234325233A2\n       [ ] [   ] ACS ACR 38U-CCID 03 00\n\n   In addition to the ATR of the inserted card below the reader, PinPad features of the terminal are shown: V - PIN verification, M - PIN modification, D - display. X instead of the asterisk indicates a reader used exclusively by some other application.\n\n * Take you directly to the [online ATR database](http://smartcard-atr.appspot.com/)\n\n       sc -l -v -w\n\n * Use a virtual smart card reader provider (format for `-p` is `jar:class:args`, where `args` part can be URL-encoded):\n       \n       sc -p some.jar:com.example.VirtualTerminalProvider:tcp%3A%2F%2F192.168.1.1%3A7000 -lv\n\n * Send the APDU `00A40C0000` to the card:\n\n       sc -a 00A40C0000\n\n * The same with forced T=0 protocol (similar for T=1):\n\n       sc -t0 -a 00A40C0000\n\n * The same, with an additional APDU, while dumping everything to `card.dump`\n \n       sc -t0 -a 00A40C0000 -a 80:01:04:00:00 -dump card.dump\n\n * SunPCSC - use specific PC/SC library:\n\n       sc -lib /usr/local/lib/pcsclite.so -l\n\n * SunPCSC - don't issue `GET RESPONSE` commands:\n\n       sc -no-get-response -a 00A4040000 -v\n\n * Show APDU-s sent to the card (using `LoggingCardTerminal`):\n   \n   add `-debug` or `-d` to your command\n\n * Be verbose:\n   \n   add `-verbose` or `-v` to your command\n\n### Usage from Java\nInclude the dependency\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.martinpaljak\u003c/groupId\u003e\n    \u003cartifactId\u003eapdu4j\u003c/artifactId\u003e\n    \u003cversion\u003e17.11.26\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nMore information can be found from [Javadocs](https://martinpaljak.github.io/apdu4j), which are always improving.\n\nBefore anything make sure you set the necessary properties to make javax.smartcardio work without tuning:\n\n```java\nimport apdu4j.TerminalManager;\nTerminalManager.fixPlatformPaths();\n```\n\n#### LoggingCardTerminal\n * Show a debugging trace (like `-d`) of PC/SC calls and exhanged APDU-s with timing on System.out:\n \n```java\nimport apdu4j.LogginCardTerminal;\n        \nTerminalFactory f = TerminalFactory.getDefault();\nCardReader r = f.terminals().terminal(\"Your Smart Card Reader Name\");\nreader = LoggingCardTerminal.getInstance(reader);\n// Now use javax.smartcardio as you normally do\n```\n\n * This will give you output similar to:\n```\nSCardConnect(\"SCM Microsystems Inc. SCR 355 00 00\", T=*) -\u003e T=1, 3BFC180000813180459067464A00680804000000000E\nSCardBeginTransaction(\"SCM Microsystems Inc. SCR 355 00 00\")\nA\u003e\u003e T=1 (4+0000) 00A40400 00 \nA\u003c\u003c (0018+2) (17ms) 6F108408A000000003000000A5049F6501FF 9000\nA\u003e\u003e T=1 (4+0000) 80CA9F7F 00 \nA\u003c\u003c (0000+2) (11ms) 6A88\n```\n\n * Dump all APDU communication with a card to a file:\n\n```java\nimport apdu4j.LogginCardTerminal;\n        \nTerminalFactory tf = TerminalFactory.getDefault();\nCardReader r = tf.terminals().terminal(\"Your Smart Card Reader Name\");\nFileOutputStream o = new FileOutputStream(new File(\"card.dump\"));\nreader = LoggingCardTerminal.getInstance(reader, o);\n// Now use javax.smartcardio as you normally do\n```\n * This will make a dump file similar to this:\n\n```\n# Generated on Wed, 31 Dec 2014 18:10:35 +0200 by apdu4j\n# Using SCM Microsystems Inc. SCR 355 00 00\n# ATR: 3BFE1800008031FE4553434536302D43443038312D6E46A9\n# PROTOCOL: T=1\n#\n# Sent\n00A4040000\n# Received in 24ms\n6F108408A000000003000000A5049F6501FF9000\n# Sent\n80500000084D080A4D1C5EBC92\n# Received in 70ms\n00001248950019F738700103002421796B41BB3B7014659BFC8A54B2479000\n```\n \nNEW release\n### Similar and related projects\n * SCUBA (LGPL) - http://scuba.sourceforge.net/\n   * :| written in Java \n   * :( no command line utility\n   * :) has *Provider*-s for weird hardware\n * jnasmartcardio (CC0) - https://github.com/jnasmartcardio/jnasmartcardio\n   * :| written in Java\n   * :) provides a \"better\" wrapper for system PC/SC service with JNA as a *Provider*\n   * :) used by apdu4j\n * OpenCard Framework (OPEN CARD CONSORTIUM SOURCE LICENSE) - http://www.openscdp.org/ocf/\n   * :| written in Java\n   * :( really old (pre-2000, comparable to CT-API)\n   * :( no command line utility\n * intarsys smartcard-io (BSD) - https://github.com/intarsys/smartcard-io\n   * :| written in Java \n   * :| similar to jnasmartcardio (alternative native *Provider*)\n * OpenSC (opensc-tool, LGPL) - https://github.com/OpenSC/OpenSC\n   * :| written in C\n   * :| related to rest of OpenSC, but allows to send APDU-s from command line with ```opensc-tool -s XX:XX:XX:XX```\n * Countless other apdu/script tools\n   * :| written in different languages\n   * :| use different input formats and script files\n   * :| just FYI\n\n\n### History and motivation\n\nWhen working with [GlobalPlatformPro](https://github.com/martinpaljak/GlobalPlatformPro) and [JavaCard](http://javacard.pro)-s, some low level code wanted to sneak into projects where it did not belong, so it made sense to capture it into a separate library. Also, while command line tools for accessing readers on APDU (PC/SC) level existed for C, nothing was available for doing the same via Java stack, thus the need for a DWIM command line tool.\n\n\n### Included/used open source projects\n\n * [picocli](https://picocli.info/) for parsing command line (Apache 2.0)\n * [Launch4j](http://launch4j.sourceforge.net/) for generating .exe (BSD/MIT)\n * [jnasmartcardio][jnasmartcardio] for PC/SC access (CC0 / public domain)\n\n### License\n\n * [MIT](./LICENSE)\n\n### Contact \n\n* martin@martinpaljak.net\n\n\n[TerminalFactory]: https://docs.oracle.com/javase/8/docs/jre/api/security/smartcardio/spec/javax/smartcardio/TerminalFactory.html\n[jnasmartcardio]: https://github.com/jnasmartcardio/jnasmartcardio\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinpaljak%2Fapdu4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartinpaljak%2Fapdu4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinpaljak%2Fapdu4j/lists"}