/GlobalPlatformPro

Manage applets and keys on JavaCard-s like a pro (via command line or from your Java project)

Primary LanguageJavaGNU Lesser General Public License v3.0LGPL-3.0

Actions Status Coverity status Maven Central Latest release LGPL-3.0 licensed

GlobalPlatformPro

   from JavaCard.pro

Load and manage applets on compatible JavaCards from command line or from your Java project with a Do What I Mean approach (testimonials).

Provides an easy to use and high level interface that most of the time JustWorks(TM), is flexible and 100% open source!

Building JavaCard applets is equally pleasing with ant-javacard

Jump to ...

Get it now!

git clone https://github.com/martinpaljak/GlobalPlatformPro
cd GlobalPlatformPro
mvn package && ant

NEWS

Usage

Beware: until v0.5 is released, both command line and Java API are subject to change without notice. Check back often.

Warning about correct keying

Command line samples assume default test keys of 40..4F. If you need a custom key, specify it with -key (you can give separate keyset components with -key-mac, -key-enc and -key-kek. You need to know the details or ask your card provider. Some cards require key diversification with -emv or -visa2 (ask your vendor if unsure). A Key Check Value can be given with -kcv option.

Generic information

  • Show some basic information about a card (failsafe):

    java -jar gp.jar -info

    • On Windows just replace java -jar gp.jar with gp.exe like this:

      gp.exe -info

    • On Linux it is easier to add an alias to the shell like this:

      alias gp="java -jar $PWD/gp.jar"
# Now you can avoid typing `java -jar` and `gp` works from any folder
gp -h

List / install / delete applets

Please consult the help output for options that are not described here

  • List applets (this and following commands open the secure channel and thus can brick your card with wrong keys!):

    gp -list # or gp -l

    How to interpret the output:

    • All AID-s of on-card objects are listed, starting with Issuer Security Domain (ISD)
    • Object's type, lifecycle state and privileges are listed below the AID line
    • Applications have type App and a state (like SELECTABLE) and privileges (like Default selected)
    • Executable Modules (type ExM, representing Java packages) are listed together with applets in them (which can be initiated with --create)
    • Security Domains have type SeD

  • Delete current default applet's package and all instances:

    gp -delete -default

  • Delete package D27600012401 and all applets from it:

    gp -delete D27600012401

  • Install applet.cap as default applet (with AID information from the CAP):

    gp -install applet.cap -default

  • Install applet.cap (with AID information from the CAP):

    gp -install applet.cap

  • Unistall applet.cap (with AID information from the CAP):

    gp -uninstall applet.cap

  • Force installation of applet.cap, deleting anything that's necessary, with AID information from the CAP:

    gp -f -install applet.cap

  • Create new instance of applet D2760001240102000000000000000000 from package D27600012401 with AID D2760001240102000000000272950000:

    gp -package D27600012401 -applet D2760001240102000000000000000000 -create D2760001240102000000000272950000

  • Same as previous, but takes the package/applet AID-s from CAP file and makes the new instance default selected:

    gp -cap OpenPGPApplet.cap -create D2760001240102000000000272950000 -default
Installation options
  • -default - makes the applet default selected
  • -terminate - gives card lock and card terminate privileges to the applet
  • -sdomain - specifies security domain privilege
  • -params <hex> - installation parameters for applet

Lock / unlock usage

  • Set 010B0371D78377B801F2D62AFC671D95 key to a card with default 40..4F keys:

    gp -lock 010B0371D78377B801F2D62AFC671D95

  • Set default 40..4F keys to card that was previously locked with key 010B0371D78377B801F2D62AFC671D95:

    gp -key 010B0371D78377B801F2D62AFC671D95 -unlock

  • Set the default 40..4F keys to a card that uses EMV diversification (like G&D):

    gp -emv -unlock

    * note that you will have to use --relax option after this operation to get rid of the warning about probably needed diversification, which is not true any more.

  • Set the default 40..4F keys to a card that uses VISA2 diversification with the well-known mother key on a Gemalto card:

    gp -visa2 -key 47454D5850524553534F53414D504C45 -unlock -mode clr

Access Control

SE Access Control commands used to list, add & delete access rules.

  • list access control rules

    gp -acr-list

The following command -acr-add & -acr-delete require authentication (install for personalization) :

  • add an access control rule to authorize (-acr-rule 01) apdu access for application signed with certificate hash 53AC1FC8DB794570D0CF2565DBFBE98C266AE07F for applet with AID D2760001240102000000000000000000

    gp -acr-add -acr-rule 01 -app D2760001240102000000000000000000 -acr-hash 53AC1FC8DB794570D0CF2565DBFBE98C266AE07F

  • add an access control rule to deny (-acr-rule 00) apdu access for application signed with certificate hash 53AC1FC8DB794570D0CF2565DBFBE98C266AE07F for applet with AID D2760001240102000000000000000000

    gp -acr-add -acr-rule 00 -app D2760001240102000000000000000000 -acr-hash 53AC1FC8DB794570D0CF2565DBFBE98C266AE07F

  • delete all access control rule for applet with AID D2760001240102000000000000000000

    gp -acr-delete -app D2760001240102000000000000000000

Debugging options

  • Show APDU-s sent to the card:

    add -debug or -d to your command

  • Be more verbose about decisions and conditions:

    add -verbose or -v to your command

  • Don't use MAC on commands (plain GlobalPlatform syntax):

    add -mode clr to your command (not supported on all cards)

  • Show all options recognized by gp utility:

    add -help or -h or --help to your gp command

Usage from Java   Maven Central

Include the dependency:

<!-- https://mvnrepository.com/artifact/com.github.martinpaljak/globalplatformpro -->
<dependency>
    <groupId>com.github.martinpaljak</groupId>
    <artifactId>globalplatformpro</artifactId>
    <version>0.3.10-rc6</version>
</dependency>
  • For now consult the command line utility source code
  • Rudimentary Javadoc
  • General rules:
    • Expect RuntimeException-s when things go unexpectedly wrong
    • CardException-s when link layer fails
    • GPException-s when protocol layer fails

Supported cards

History

The ancestor of this code is GPJ (Global Platform for SmartCardIO) which is (still) available from http://gpj.sourceforge.net. I started the project because I felt that messing with cryptic script files was not nice and I wanted to have a simple, open source, usable and native-to-the-rest-of-development-environment (Java) toolchain.

Credits (from GPJ):

Similar projects

Design principles

  • focus on real life and practical daily use cases
  • KISS, YAGNI, DWIM, no-NIH
  • APDU-chat over anything that extends CardChannel to (most probably real) tokens
  • thin and self-contained, re-usable, easy to integrate
  • easily readable, auditable and secure codebase (less is more)

About

The promise of GlobalPlatformPro is similar to OpenSSL:

Why buy a smart card software kit as a black box when you can get an open one for free?

In regard to GlobalPlatform, the goal is to make simple operations like installing and removing applets and locking the card with new keys as easy as next-next-done - you don't have to know the whole Global Platform specification by heart for that or buy a piece of proprietary software for a few hundred euros! For all those features that are not described in the GlobalPlatform specification that actually make your card work... you still have to use those proprietary commands, but OpenKMS GlobalPlatformPro toolkit's flexibility (and its license) should allow you to do that as well.

License

  • LGPL-3.0 for derived code and MIT/LGPL3 for original code.

Included/used open source projects

  • BouncyCastle for OID parsing and NIST SP 800-108/NIST SP 800-38B (MIT)
  • JOpt Simple for parsing command line (MIT)
  • Launch4j for generating the .exe (BSD/MIT)
  • apdu4j for APDU level PC/SC access/logging/replaying (MIT)
  • ber-tlv for tag parsing (Apache)

Contact

  • Generic enquiries: martin@martinpaljak.net
  • For technical support:
    • re-run your failing command with -d -v -i switches and send the output, information about your card and applet/CAP
    • Only plaintext logs. NO screenshots, pictures, word documents. NO generic questions about java/linux/windows/globalplatform. Questions about jcshell/gpshell/gpj/something else shall be ignored.
    • If unsure, first read about asking questions
    • If you want to have a chat-like experience, try to Gitter
  • File an issue on Github. Better yet - a pull request!
  • Want to donate? E-mail or paypal to martin@martinpaljak.net

Legal disclaimer

The casual: trademarks to their owners, copyrights to authors, software patents to hell, legal letters to /dev/null PGP key 0x1d86f74c7b9dd593. Everything is provided AS-IS AND THERE IS A CONSTANT RISK OF DEATH FROM SUDDEN LIGHTNING. Writing in all caps made it look like serious, didn't it?

JavaCard.pro