GlobalPlatform from OpenKMS

Load and manage applets on compatible JavaCards from command line or from your Java project with a DWIM approach.

Provides a high level and easy to use interface that most of the time JustWorks^(TM) yet is as flexible as GPShell. Fully open source.

Jump to ...

• Download
• Usage
• Supported cards
• Contact & support
• Similar projects
• About OpenKMS & legal

Get it now!

• Download latest pre-built JAR or .EXE from release area
• Or fetch from github and build it yourself, it is really easy:

git clone https://github.com/martinpaljak/GlobalPlatform
cd GlobalPlatform
ant

• Status
  • Travis -
  • Coverity -

Usage

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

Command line samples assume default test keys of 40..4F. If you need custom keys, specify them with any or all of the following options: -keyid -keyver and -enc -mac -kek or -key (for a single master key). You need to know the details or ask your card provider. Some cards require key diversification with -emv or -visa2 (you should be notified if that's the case).

• 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
    

• List applets (this and following commands can brick your card with wrong keys!):

   java -jar gp.jar -list
  

• Delete current default applet:

   java -jar gp.jar -delete -default
  

• Delete module D27600012401 and all applets from it:

   java -jar gp.jar -delete D27600012401 -deletedeps
  

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

   java -jar gp.jar -install applet.cap -default
  

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

   java -jar gp.jar -install applet.cap
  

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

   java -jar gp.jar -uninstall applet.cap
  

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

   java -jar gp.jar -lock 010B0371D78377B801F2D62AFC671D95
  

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

   java -jar gp.jar -key 010B0371D78377B801F2D62AFC671D95 -unlock
  

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

   java -jar gp.jar -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:

   java -jar gp.jar -visa2 -key 47454D5850524553534F53414D504C45 -unlock -mode clr
  

• 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

• For now consult the command line utility source code
• Javadoc is in a bad shape but shall be improved near v1.0
• Expect RuntimeException-s when things go horribly wrong, CardException-s when link layer fails and GPException-s when protocol layer fails.

Supported cards

• See TestedCards
• Generally speaking any modern JavaCard that speaks GlobalPlatform 2.1.1+
• Available cards from all major vendors have been tested for basic compatibility: Athena, Gemalto, Giesecke & Devrient, Infineon, NXP (JCOP), Oberthur
  • If you are a smart card vendor please do get in touch for clarification and better support!

Contact

• martin@martinpaljak.net
• File an issue on Github. Better yet - a pull request!
• For support:
  • re-run your failing command with -d -v -i switches and send the output, information about your card and applet
• For general conversation: OpenKMS forum

History

The ancestor of this code is GPJ (Global Platform for SmartCardIO) which is (still) available from http://gpj.sourceforge.net.

Credits (from GPJ):

• Wojciech Mostowski woj@cs.ru.nl,
• Francois Kooman F.Kooman@student.science.ru.nl
• Martijn Oostdijk martijn.oostdijk@gmail.com
• Martin Paljak martin@martinpaljak.net
• Hendrik Tews
• Dusan Kovacevic

Similar projects

• gpj (the grandparent) - http://gpj.sf.net (LGPL)
  • written in Java
  • not maintained
  • harder to use from the command line
• GPShell + globalplatform library - http://sourceforge.net/projects/globalplatform/ (LGPL)
  • written in C
  • often referred to as the de facto open source GlobalPlatform implementation.
  • several components need to be compiled and installed before usage
  • requires more complex "script files" and does not provide a command line utility
• jcManager - http://www.brokenmill.com/2010/03/java-secure-card-manager/ (LGPL)
  • written in Java
  • has a basic GUI
  • old and not maintained
• gpjNG - https://github.com/SimplyTapp/gpjNG (LGPL)
  • fork of gpj with minor additions, mostly a "script mode" that makes it similar to GPShell
• Ruby smartcard module - http://smartcard.rubyforge.org/classes/Smartcard/Gp/GpCardMixin.html (MIT)
  • written in Ruby
  • does not seem to expose all functionality (key diversification, key change etc)
  • no command line utility
• JGPShell - https://sourceforge.net/projects/jgpshell/ (GPL2)
  • written in Java
  • GPShell-style scripting goal
  • not really usable and also abandoned.
• OPAL - https://bitbucket.org/ssd/opal (CeCILL, GPLv2 compatible)
  • written in Java
  • claims to have SCP03 support (but no tested cards)
  • looks "heavy"
  • smoke tests give exceptions and doesn't work on OSX nor Debian.
• JCOP tools, RADIII, JCardManager4 etc
  • not publicly available open source projects and thus not suitable for this comparision

Upcoming releases and major new features

• T+1 (v0.2.5)
• Re-written command line utility
• Windows .exe for ease of use
• -lock and -unlock commands for changing secure channel keys
• T+2/3/4
• Support for storing card management keys in PKCS#11 tokens (HSM)
• Simple GUI for basic operations/browsing
• T+X (wishlist)
• SCP03
• GPShell-style scripts

Design principles

• focus on: real life, practical, simple use cases
• KISS, YAGNI, DWIM
• javax.smartcardio access to (most probably real) tokens
• thin and self-contained, re-usable
• easily readable, auditable and secure codebase

About OpenKMS

The promise of OpenKMS 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 describe in the GlobalPlatform specification that actually make your card work... you still have to use those proprietary commands, but OpenKMS GlobalPlatform toolkit's flexibility (and its license) should allow you to do that as well.

* _{With the difference that OpenKMS thrives for a easily usable and pleasantly readable, auditable and secure codebase. And yes, you have probably already sold your soul to the devil...}

License

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

Included/used open source projects

• BouncyCastle for OID parsing (MIT)
• JOpt Simple for parsing command line (MIT)
• Launch4j for generating .exe (BSD/MIT)
• jnasmartcardio for PC/SC access (CC0 / public domain)

Legal disclaimer

The casual: trademarks to their owners, copyrights to authors, software patents to hell, legal letters to /dev/null PGP key 0x307E3452. 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?

---

OpenKMS - open source key management - openkms.org