SpringCore is the umbrella name to the new generation of SpringCard devices (Puck, SpringPark, etc.) that share the same MCU platform and the same overall architecture. All the devices in this family could be configured easily and securely thanks to SpringCard 2nd generation of master cards.
A master card v2 is a Desfire EV1 (or later) contactless card, that contains the configuration parameters you want to apply to many devices. The data are protected by AES128 for authentication and secure communication, and their authenticity is validated by an ECC256 digital signature.
Thanks to this robust security scheme, only your devices can read and accept your master cards, while refusing (and being actually unable to read) master cards created by 3rd parties. Symmetrically, only the devices that you have commissioned with your own key-set are able to read your master cards, thus protecting your assets (secret keys and specific configuration parameters) against any unwanted disclosure, even if the master card is lost or stolen.
This article shows how-to create master cards v2 using springcoremastercard.exe tool and/or SpringCard Companion, and what are the best practices to use them efficiently and securely.
Preparation
Hardware requirements
Master cards v2 are NXP Desfire EV1 cards. Desfire EV2 and Desfire EV3 are supported as well. Make sure you have at least 3 blank cards available to follow this tutorial to the end.
To write (encode) the master cards v2, you need a contactless PC/SC reader. SpringCard recommends using either a Prox’n’Roll PC/SC or a Puck PC/SC (any version, namely Puck One or Puck Base, provided that it is already configured for PC/SC operation).
Software requirements
springcoremaster.exe, a software from the SpringCore Tools suite, is the command-line utility to manipulate device configurations.
To download and setup springcoremaster.exe and the related tools, please read Installing the SpringCore Tools.
NB: all screenshots in the article have been taken on a Windows system, but the software also runs on macOS and Linux (over the Mono runtime).
SpringCard Companion is the new all-in-one solution to manage, configure and update the SpringCore devices. SpringCard Companion is both a Web application (companion.springcard.com) and a gateway software (the Companion Service) that runs on a Windows computer.
To install and start using SpringCard Companion, please read Getting started with SpringCard Companion.
Designing a hierarchy of master cards
Master card-related configuration registers inside the device
A master card is accepted by the device if and only if:
- The Key ID of the master card (reference of the key-set used to create it) is the same as the Master Key ID stored in register 02F3 in the device,
- The AES128 authentication key of the master card equals is the same as the Master Auth Key stored in register 02F4 in the device,
- The ECC256 private key used to sign the master card is valid against the Master Public Key stored in register 02F5 in the device.
Therefore, before being able to create your own master cards, you have to:
- Generate an ECC256 private key + public key couple,
- Generate an AES128 secret key,
- Assign a unique Key ID to your key-set containing both keys (a good practice is to take the CRC32 of the ECC256 public key as Key ID)
Then you can write master cards that will be accepted by any device that have the same master key-set configured in its 3 registers 02F3, 02F4 and 02F5 (public part of the ECC256 couple only – the private part stays on your computer).
The first question is, how can the device accept its “first” master card, when its 3 master key-set registers are still empty?
Default master key-set
Actually, when the 3 master key-set registers are left empty, a default key-set is used (with Key ID=CD06361D). The corresponding Auth Key and ECC Key are known by the springcoremaster.exe (and may be disclosed by SpringCard under NDA should you need them to create your own tool).
Master cards written with the default master key-set are accepted by all new, not-commissioned devices.
This leads to 2 important precautions:
Caution 1
Always configure a key-set when installing your devices, or permanently disable the support of master cards in its configuration (bits 1-0 of register 02F0),
Caution 2
The “first” master card a device could accept has to be written using the default master key-set. Since this default master key-set is known by all the devices coming out of our production, it is not impossible for an attacker to read-back the content of such a master card. Symmetrically, new devices will accept any master card created using the default master key-set (not only the master cards you have actually created yourself).
Therefore,
- You shall use your “first” master card to commission your devices as soon as you receive them, to prevent anybody else to configure the devices in your place,
- You shall store your “first” master card in a secure place (in a safe ideally) since this card contains your AES128 master auth key (not in the plain, but protected by a default key that should be considered as unsafe),
- Don’t put any other sensitive information (namely the authentication keys to read the users’ cards in the case of Smart Reader devices, and/or the remote administration keys in the case of network-connected devices) in the “first” master card.
The suggested 3-card hierarchy is the best approach to secure your system.
“First” master card: commission
As explained above, the “first” master card shall to nothing more than writing your very master key-set in register 02F3, 02F4, 02F5 (and possibly set the access conditions in register 02F0 as well, to protect your devices against unwanted operations).
Commission all your devices with this “first” master card as soon as you get them.
“Normal” master card(s): configure
The actual configuration comes to the devices in a master card that is secured by your specific key-set. We use the word “normal” to describe such master cards that stores configurations (not only the keys and key-set parameters).
Even if it is a good idea to protect them against loss or theft, “normal” master cards are less sensitive than “first” cards (just a remark: even if an attacker manages to get both a “first” and one of your “normal” cards, your system is still protected by the ECC signature).
A “normal” master card does not have to rewrite the master key-set registers. Applying a “normal” master card fully overwrites the configuration that has been written by an other “normal” master card earlier, allowing to change the devices parameters on the field.
“Last” master card: back to defaults
A “last” master card is the inverse of a “first” master card: it erases all registers, including 02F3, 02F4, 02F5, thus restore the devices to their out-of-factory state. To be accepted, this “last” master card has to be secured by your specific key-set, in the same way as one of the “next” master cards.
It is always a good idea to create a “last” master card in the same time you create your “first” master card. Doing so, you may clean-up your devices anytime.
Preparing your master cards
Generate your key-set
Use springcoremastercard.exe –keyset=<NAME OF KEY SET FILE> –generate to create a new key-set.
Remarks
To prevent losing the secret and private keys, the software prevents overwriting an existing key-set file.
The software expects a secret passphrase to protect the key-set file. Add flag –no-keyset-pass to overcome or use –keyset-pass “<PASSPHRASE>” to specify the passphrase of the key-set file on the command-line (not recommended). With the flag –window, the software opens a GUI instead of reading the password from the command-line.
List the PC/SC readers
The software uses a (contactless) PC/SC reader to write the Desfire-based master cards. Use springcoremastercard.exe –list to get the list of readers.
Locate the reader you want to use. In the following steps, use either –name <READER NAME> or –index <INDEX OF READER IN THE LIST> to specify the target PC/SC reader.
Create your “first” master card
Place a blank Desfire EV1 card on the reader, and use springcoremaster.exe –first –keyset <NAME OF KEY SET FILE> to create the “first” master card (don’t forget to select the reader using either –name or –index).
Remarks
If the key-set file is protected, the software prompts for its passphrase. Use flag –keyset-pass “<PASSPHRASE>” to specify the passphrase on the command-line (not recommended!).
If the card is not blank (list of applications not empty), the software prevents using it. Add flag –overwrite to overcome.
If the card’s master key (key 00 of application 000000) is not NXP’s default (blank) key , use flag –master-key <CARD MASTER KEY> to provide the right key (in hexadecimal).
NB: this operation changes the card’s master key to a secret key that is specific to the key-set and to the card itself (computed from the UID). Use springcardmaster.exe –erase should you need to restore the card in its blank state.
Create your “last” master card
Place a blank Desfire EV1 card on the reader, and use springcoremaster.exe –last –keyset <NAME OF KEY SET FILE> to create the “last” master card (don’t forget to select the reader using either –name or –index).
Remarks
If the key-set file is protected, the software prompts for its passphrase. Use flag –keyset-pass “<PASSPHRASE>” to specify the passphrase on the command-line (not recommended!).
If the card is not blank (list of applications not empty), the software prevents using it. Add flag –overwrite to overcome.
If the card’s master key (key 00 of application 000000) is not NXP’s default (blank) key, use flag –master-key <CARD MASTER KEY> to provide the right key (16 bytes in hexadecimal).
NB: this operation changes the card’s master key to a secret key that is specific to the key-set and to the card itself (computed from the UID). Use springcardmaster.exe –erase should you need to restore the card in its blank state.
Create a “normal” master card
“Normal” master cards contain the actual configurations of your devices. Creating a “normal” master card is done by copying the content of a configuration file onto the master card.
Creating or obtaining the configuration file
springcardmastercard.exe supports the same file types as springcoreconfig.exe, i.e.:
- Key/Value pairs files (.CFG extension)
- JSON files (.JSON extension).
The actual content of these files is out of scope of this article. The reference documentation is available online (direct links: CFG files, JSON files). You may also find more information regarding the configuration files in the article about springcoreconfig.exe.
We’ll come back later in this article on how-to get a configuration file (in .JSON format) from SpringCard Companion.
Always make sure that the configuration you intend to apply to your device is valid and compatible with this very device, and label your master cards carefully to remember precisely which master card could be applied on which devices.
Copying the configuration file onto the master card
Place a blank Desfire EV1 card on the reader, and use springcoremaster.exe –file <NAME OF CONFIGURATION FILE> –keyset <NAME OF KEY SET FILE> to create a “normal” master card (don’t forget to select the reader using either –name or –index). If the file extension is not explicit, add –file-type JSON or –file-type CFG.
Remarks
If the key-set file is protected, the software prompts for its passphrase. Use flag –keyset-pass “<PASSPHRASE>” to specify the passphrase on the command-line (not recommended!).
If the configuration file itself is also protected, the software prompts for its password. Use flag –pass <PASSWORD> to specify the password on the command-line.
If the card is not blank (list of applications not empty), the software prevents using it. Add flag –overwrite to overcome.
If the card’s master key (key 00 of application 000000) is not NXP’s default (blank) key, use flag –master-key <CARD MASTER KEY> to provide the right key (16 bytes in hexadecimal).
NB: this operation changes the card’s master key to a secret key that is specific to the key-set and to the card itself (computed from the UID). Use springcardmaster.exe –erase should you need to restore the card in its blank state.
Erase a master card
Place a master card on the reader, and use springcoremaster.exe –erase –keyset <NAME OF KEY SET FILE> to erase it (don’t forget to select the reader using either –name or –index).
Be sure to place the right card on the reader! The software does not wait for a confirmation and is able to erase ANY master card provided that it belongs to the right key-set.
Remarks
If the key-set file is protected, the software prompts for its passphrase. Use flag –keyset-pass “<PASSPHRASE>” to specify the passphrase on the command-line (not recommended!).
At the end of the procedure, the card is blank and NXP’s default key (00..00) is restored. This makes it possible to use it again for something else.
Applying a master card to a device
The way a device accepts a master card depends both on the settings found in its configuration register 02F0 and on its operating mode.
Pay attention that processing the master card may be completely disabled by the bits 1-0 in byte 0 of register 02F0. In this case, another method must be used to configure the device.
Devices configured for Smart Reader or RFID Scanner modes:
Devices running as Smart Reader or RFID Scanner are continuously looking for contactless cards. As soon as a contactless card is found, the device’s template engine tries to run the transaction that would retrieve useful data from the card.
If the contactless card is a master card, the device makes no difference: the engine tries all its templates one after the other, and eventually runs the “master card template”. The master card may then be accepted at any time (if register 02F0 allows it), for the reader is always processing automatically the cards it sees.
- Place the master card over the reader’s antenna and hold it during 3 seconds until the reader accepts it (single beep),
- Wait while the reader processes the master card (1 to 10 seconds depending on the size of the configuration),
- The reader beeps repeatedly to confirm the end of the procedure,
- Remove the card – the reader resets to apply the new configuration.
Devices configured for PC/SC mode:
Things are different for devices running in PC/SC mode because in this mode the applications running in the computer expect to have full control over the contactless cards, and expect to have it immediately. Starting the “master card template” every time a card is inserted would dramatically decrease the device’s performances and create undesirable side-effects.
Therefore, whatever the settings in register 02F0, a device running in PC/SC mode will process the master cards only on startup.
- Unplug the reader from the computer (USB) or switch its power supply off (network/BLE),
- Place the card over the reader’s antenna and keep it steady,
- Plug the reader back to the computer (USB) or switch its power supply on again (network/BLE),
- Wait about 5 seconds until the reader “sees” the master card (single beep),
- Wait while the reader processes the master card (1 to 10 seconds depending on the size of the configuration),
- The reader beeps repeatedly to confirm the end of the procedure,
- Remove the card – the reader resets to apply the new configuration.
Video gallery: Puck & master card
Using SpringCard Companion to create configuration files
SpringCard Companion Web application (companion.springcard.com) is the recommended method for creating and editing configurations. The Web application could be used even if you don’t want to install the Companion Service, or if your operating system does not support the Companion Service.
After you’ve created your configuration in Companion, click the button Apply to device, and then click the button Download the configuration in JSON format.
Use springcoremastercard.exe to copy the downloaded JSON file to a master card.
Alternatively, you may use springcoremastercard.exe –url <COMPLETE URL OF THE CONFIGURATION> to write a configuration directly from its web address.
In the Web application, select the configuration you want and open its popup menu (3 vertical dots), then click Get unique URL.
The configuration’s URL is then copied into the clipboard.
Write springcoremastercard.exe –url on the command-line, and paste the URL (shortcut Ctrl+V). Don’t forget to specify the key-set file and other required parameters as well.
