#Build Your Own Keycard

If you have a blank JavaCard 3.0.5+ card (readily available for purchase on the web) you can build your own Keycard. There are two ways to get there:

• Installing from binaries — download the Keycard CLI and the released cap files. This is the path to take if you just want Keycard running on a card of your own.
• Installing from source — build the applet with Gradle. This is the path to take if you want to change the applet or contribute to it, since it also leaves you with a working development environment.

#What you need

Both paths need the same hardware:

• A JavaCard 3.0.5+ smartcard with T=1 and SCP02 support. Cards of the JCOP4 family are known to work well. We sell and ship this type of keycards for developers on our shop. For detailed requirements about the card, we recommend to check the card requirements in the keycard github repository.
• A standard PCSC smartcard reader. Contact (USB) readers are more reliable than NFC ones. Make sure no other PCSC reader (or Yubikey) is plugged in while installing.
• A card whose GlobalPlatform ISD keys are the default GlobalPlatform keys (true for most cards sold online) or the Keycard development keys (if you bought a development card from us). If you already played with the card and changed those keys yourself, reset them first with a GlobalPlatform management tool.

#Installing from binaries

#1. Get the Keycard CLI

Download the binary for your platform from the Keycard CLI releases page and rename it to keycard, dropping the platform suffix:

chmod +x keycard-darwin-arm64
mv keycard-darwin-arm64 /usr/local/bin/keycard
keycard version

Every release carries a SHA256SUMS file covering all the binaries — check your download with sha256sum -c SHA256SUMS. On Linux you also need the PC/SC runtime (sudo apt install pcscd libpcsclite1); macOS and Windows need nothing else. The Linux binaries are built on Ubuntu 24.04, so they need glibc 2.39 or newer.

#2. Download the cap files

You need two files, both from the latest release of their repository:

Pick the math package that matches your card:

The JCOP package only forwards the big number operations to the modular arithmetic NXP ships in the JCOP environment (com.nxp.id.jcopx.math), which is faster than doing it in JavaCard bytecode. The soft package is the portable software implementation, and is the one to take on any card that is not a JCOP.

#3. Install the applets

With the card in the reader:

keycard install --applet-file keycard_vx.y.z.cap --load-math math_soft_vx.y.z.cap

This loads the math package and installs the Keycard and Ident applets. --load-math is only needed the first time, since the library package stays on the card — leave it out on reinstallations. Use math_jcop_vx.y.z.cap instead if you are on a JCOP card.

#4. Provision an identity

The applet refuses every command — not even SELECT is answered — until it has an identity certificate, because the secure channel authenticates the card with that key. Load one:

keycard load-ident --test

--test generates a random identity and a certificate from the Keycard test CA, which is what you want while developing. A card with a test identity has to be explicitly trusted by the client: --test-card (or KEYCARD_TEST_CARD=true) with the CLI, the test CA as an anchor or a pinned card identity in the SDKs, the equivalent option in wallets.

If you are building a card you intend to use for real, generate the certificate under your own CA and load it with keycard load-ident --hex "0x..." instead, making sure the CA public key is the one your clients trust. Cards bought from us already carry a production identity and need none of this.

#5. Initialize the card

keycard init

This sets up the PIN, PUK and (on applet versions before 4.0) the pairing password, generating them randomly and showing them once — pass --pin / --puk (or the KEYCARD_PIN / KEYCARD_PUK environment variables) to choose them yourself. Check everything worked with:

keycard info

Done — your card is now a Keycard. Continue with the Keycard SDK or the Keycard API.

#Installing from source

Building from source gives you the applet straight from the repository, plus a development environment you can iterate on. A single Gradle task builds the applet, installs it, and leaves the card initialized with a test identity.

#Requirements

• Linux, Windows or Mac computer
• OpenJDK 11 (this specific version is required — newer JDKs are not compatible with the JavaCard build tools)
• The card and reader listed under What you need

#Setting up OpenJDK 11

#macOS

brew install openjdk@11
export JAVA_HOME=/opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk/Contents/Home
export PATH="/opt/homebrew/opt/openjdk@11/bin:$PATH"
java -version   # should show openjdk version "11.0.x"

#Linux (Debian/Ubuntu)

sudo apt update
sudo apt install openjdk-11-jdk pcscd libpcsclite-dev
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64

#Windows

Download and install OpenJDK 11 from Adoptium (select Windows, x64, JDK, .msi). You can either

• check the option to set JAVA_HOME during installation, or
• Open a new terminal and run command set JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-11

#Build and install steps

1. 1
   Plugin your PCSC reader and insert the card. Make sure no other PCSC reader (or Yubikey) is plugged in
2. 2
   Open your terminal app of choice
3. 3
   Clone the Keycard repo with the command git clone --recurse-submodules https://github.com/keycard-tech/status-keycard
4. 4
   Enter the repository with cd status-keycard
5. 5
   Build the applet, install it on the card and run the applet test suite against it:

   • macOS / Linux: ./gradlew test
   • Windows: gradlew.bat test
6. 6
   When you see BUILD SUCCESSFUL you are done. The task loads both the keycard-math support package (required since 4.0) and the Keycard package, installs the Keycard, NDEF, Cash and Ident applets, then exercises them on the card
7. 7
   The test suite also provisions and initializes the card for you: it loads an identity certificate from the Keycard test CA and runs INIT with PIN 000000 and PUK 024680. So there is nothing else to do — the card answers commands right away, and clients just have to trust the test CA with --test-card / KEYCARD_TEST_CARD (or pin the card identity). Change the PIN with keycard change-pin if you keep using the card.

If you do not want to run the tests, use ./gradlew install instead. It only loads the packages and installs the applets, leaving the card without an identity and uninitialized, so you then have to provision an identity and run keycard init as in the binary path above.

If you only want the cap file — for example to install the applet on a card you are not holding in a reader right now — run ./gradlew convertJavacard and find keycard.cap in the build directory.

#Locking the card

After following the installation steps above your card will still be open to changes. This is very useful during development because you can repeat the installation steps as many times as you want to test changes you made to the app. To make your card immutable, in a way similar to what we do you need to do 2 things:

1. 1
   Change the ISD keys to random ones. If you store these you will still be able to reinstall the applet or update to a new version. Since only you will have the keys this is reasonably safe, however you would have to store these keys securely.
2. 2
   Bring the card from the OP_READY lifecycle state to the SECURED one

If you built from source, you can perform these two steps with ./gradlew lock from the status-keycard directory.

NOTE: THIS PROCEDURE IS NOT REVERSIBLE. THE AUTOMATED LOCKING TOOL DOES NOT PRINT OR STORE THE RANDOMLY GENERATED KEYS ANYWHERE