JCOP Cards

NXP's JCOP cards are Java Cards: a chip with a small Java virtual machine and a GlobalPlatform security domain that loads, installs and deletes applets. The kit puts the KABC payment applets on three of them. This page tells them apart, follows a card through its life from the chip factory to the end, and gives you sample scripts to read a card and move it through that life yourself.

1. The three cards: what each one is, and how to read its name.
2. The card lifecycle: unfused and fused, then OP_READY, INITIALIZED, SECURED, CARD_LOCKED and TERMINATED.
3. The applet lifecycle: loaded, installed, selectable and locked.
4. Sample scripts to identify, list, lock, unlock, initialize and secure a card.
5. Set the card's ATR: a test label and T=0 or T=1, and pre-personalizing an unfused J2A040.
6. Good to know: three kinds of lock, failed logins and unfused cards.

The default key is what settings.cmd and the kit's card.env come with. A card whose keys were changed needs its own: a wrong key counts down the card's retry counter, and the scripts stop at the first refusal.

How to read the name: J3R180

That is how the part numbers line up across NXP's range. Figures differ a little between card makers' configurations: the data sheet of the card in your hand is the reference. The kit's Check my setup and 1-identify.cmd read the card itself.

A GlobalPlatform card is always in one lifecycle state, kept by its security domain; 2-list.cmd prints it on its first line. Most steps go one way only. Pick a state to see what it means and what can come next.

Every step

The card commands are GlobalPlatform SET STATUS: 80 F0, then 80 for the card itself and the new state's code. gp.jar sends them inside the secure channel after its login, so the card also checks their MAC.

Each package and applet has a state of its own, separate from the card's: gp --list prints it after each AID, as in APP: A0000000041010 (SELECTABLE).

The kit's Install loads, installs and makes each applet selectable in one go; Remove and Wipe delete. Locking an applet is how to test a card with one application missing without deleting it.

Eight small Command Prompt scripts that run gp.jar for you. Each one says what it will do before it does it; the steps that cannot be undone ask you to type a word first, and after a failed login every script stops logging in until the key is fixed.

@echo off
setlocal EnableExtensions
title KABC JCOP card - 1 Identify the card
echo 1 Identify the card. Your card: J3R180, JCOP 4 on NXP's P71 chip (SmartMX3).
echo.
echo Shows the card's ATR, its CPLC data (who made the chip, and when it was made and pre-personalized),
echo its GlobalPlatform version and secure channel, and the types of its keys, never the keys themselves.
echo It does not log in to the card, so it is safe to run as often as you like.
echo.
echo If gp.jar finds the card but shows no card data, it may be unfused and not pre-personalized yet:
echo see the JCOP Cards page.
set "NOLOGIN=1"
call "%~dp0tools\gp.cmd" --info
echo.
pause

Then, on your PC

1. Unzip it: right-click, Extract All.
2. Have Java 11 or later and gp.jar. Put gp.jar next to the scripts, or leave it in your Downloads folder.
3. Put the card in a contact reader and double-click 1-identify.cmd, then 2-list.cmd.
4. settings.cmd comes with the J3R180's default test key already filled in. Open it in Notepad only to use a different key, or to name your reader when more than one is connected.

The card's key lives in settings.cmd and nowhere else; it is a test-card key, filled in as a default, not a secret. There is no script that changes the keys or terminates a card. To build and install the KABC applets, use the Build & Install Kit.

A card answers every reader with an ATR (Answer To Reset); its historical bytes are a short label a terminal reads. These scripts set that label to NRT Test Only and choose the contact protocol, T=1 (the usual one, needed to load applets) or T=0. On the J2A040 the same script pre-personalizes an unfused card and loads the default test key. It is the verified sequence from the reference ATR tools, in the per-card download under atr\.

• T=1 to load applets. A card set to T=0 cannot have applets loaded; pick T=1 unless you have a reason not to.
• Remove applets first. On JCOP 4 the card often refuses the configuration while packages are still loaded. Clear them with the kit's Wipe, then set the ATR.
• Cold reset to see it. The new contact ATR appears after you take the card out and put it back in.
• No fuse. These scripts do not fuse or permanently lock the card; those commands are left out on purpose.

@echo off
setlocal EnableExtensions
title KABC JCOP card - set the ATR (J3R180, T=1)
echo Set the card's ATR historical bytes to the test label "NRT Test Only", protocol T=1.
echo It writes the configuration in one authenticated session; gp.cmd uses the key in settings.cmd.
echo If the card has applets or packages loaded, remove them first with the kit's Wipe, or the
echo card may refuse these commands.
echo The new contact ATR shows after a COLD reset: remove the card and put it back in.
echo This does NOT fuse or permanently lock the card.
echo.
set "ANSWER="
set /p "ANSWER=Type ATR to write it, or press Enter to stop: "
if /i not "%ANSWER%"=="ATR" goto :stopped
call "%~dp0..\tools\gp.cmd" -c A000000151000000 --mode MAC ^
 -s 80E2880007DF2B0410A50104 ^
 -s 80E288000BDF2B08109E050578777102 ^
 -s 80E2880007DF2B04109F010A ^
 -s 80E2880010DF2B0D10A00A50564A434F5034534944 ^
 -s 80E2880007DF2B0410A10100 ^
 -s 80E2880007DF2B0410A20148 ^
 -s 80E2880007DF2B0410A30120 ^
 -s 80E2880007DF2B0410A40124 ^
 -s 80E2880007DF2B0410900124 ^
 -s 80E2880007DF2B0410980124 ^
 -s 80E2880007DF2B04108C0108 ^
 -s 80E2880007DF2B0410940108 ^
 -s 80E288000EDF2B0B108D08F01300008131FE45 ^
 -s 80E288000EDF2B0B109508F01300008131FE45 ^
 -s 80E2880007DF2B04108E010D ^
 -s 80E2880007DF2B041096010D ^
 -s 80E2880013DF2B10108F0D4E52542054657374204F6E6C79 ^
 -s 80E2880013DF2B1010970D4E52542054657374204F6E6C79 ^
 -s 80E2880007DF2B0410AD0103 ^
 -s 80E2880007DF2B0420150101 ^
 -s 80E2880007DF2B04109C0146 ^
 -s 80E2880008DF2B05F82602010F ^
 -s 80E2880007DF2B0410C1015A ^
 -s 80E2880008DF2B05108B021000
if errorlevel 1 goto :end
echo.
echo Done. Take the card out and put it back in (cold reset) to see the new ATR.
goto :end

:stopped
echo Stopped. Nothing was sent to the card.

:end
echo.
pause

Both ATR scripts are in the download above for the J3R180, in the atr\ folder.

• "Lock" means three different things. gp --lock-card blocks the whole card (CARD_LOCKED, can be undone); gp --lock-applet blocks one applet (can be undone); gp --lock is gp.jar's name for changing the card's keys Can brick the card. No script does the last one: keep the default key on a test card, and if you do change it, keep the new key safe first — lose it and the card is gone.
• A failed login is never harmless. Can brick the card Each failed login counts down the security domain's retry counter; at zero the card is locked for good. The scripts and the kit stop at the first one.
• A test card does not need fusing. An unfused card that has been pre-personalized (on a J2A040, with the ATR script above) installs, lists and deletes applets just like a fused one, and it stays resettable: run the pre-personalization again to re-initialize it, reset its ATR and protocol, or reload its keys. Fusing makes that configuration permanent and takes the reset away, so keep development cards unfused and fuse only a card that is finished. Whether a card's pre-personalization matches the script depends on its profile, which differs by maker. If 1-identify.cmd finds the card but shows no card data, it may be unfused and not pre-personalized yet.
• Read the card's history. 1-identify.cmd prints the CPLC (Card Production Life Cycle) data, as the chip and card makers wrote it: the chip's fabrication date, who pre-personalized it and when, and the personalization date.
• A test card can stay in OP_READY. Nothing on these pages needs another state. INITIALIZED and SECURED are worth trying on a spare card, to see a card the way issuers ship it.
• Install over contact. Applets are loaded through a contact reader. The J3R150 and J3R180 then also work contactless at a terminal; the J2A040 is contact only.
• No terminate script. Bricks the card TERMINATED is the end of a card, with no undo, so neither the scripts nor the kit go there.