SAM Tool - Executable Master Tool App

(Secure Access Module)

Digital Logic SAM Tool App is a comprehensive SAM development tool with a user-friendly graphic interface, suitable for end-users and system integrators.

A Secure Access Module (or Secure Application Module) is based on SmartCard Integrated circuits and is used to enhance the security and cryptography performance in devices. It finds its purpose in the solutions for secured transactions, such as ATM, POS terminals, and other payment systems.SAM module is often present in the ticketing equipment (personalization, sales, validation, control, etc.) and other systems where the secret Keys as a security measure is recommended.

The SAM Card is a tamper-resistant card, physically similar to a SIM card. For this reason, it can be inserted into a reader SAM slot, or the SAM slot inside the hardware housing.

Docs & Software Download

Software overview

Software functions:

Get version
Get UID
AV1 personalization mode functions
- AES Master Key
- Switch to AV2 mode
AV2 mode functions
- Host Key
- CaKey
SAM Key unlock function
- SAM unlock the Key stored into the reader
- Reader Key lock/unlock.

Available programming languages:

SAM Tool is an executable app.

Supported operating systems, platforms, and environments:

Windows OS

Supported tags, labels, cards:

NXP SAM Card® T1AD2060
NXP SAM Card T1AR1070

Recommended hardware:

Note: SAM slot is an optional upgrade for the listed devices

Software download

Description

sam_tool-executable

Executable software tool for SAM (Secure Access Module) contact cards initialization and personalization.

Software manual

1. SAM Tool Software – Start the App

Download: sam_tool-executable

The SAM Tool software is an executable Windows app.

It is used for SAM (Secure Application Module) personalization in AV1 mode and Key management in AV2 mode.

The software root folder contains an executive sam_tools.gui.exe file and a relevant library (the ibwinpthread-1.dll). If µFR Series drivers are already installed on your machine, you can run SAM tool software with no additional setup.

For the app’s complete functionality, you need to connect the µFR Series device with SAM card support to the PC first. The SAM Card support is provided by the µFR Series firmware 5.100.xxx. Please, check your device firmware version and update it if necessary.

Note: Firmware versions 5.0.xxx for these devices don’t have the SAM support, but instead rely on storing security keys inside the devices MCU.

Launching the application opens the user interface with available functions.

2. SAM Tool Software – Key personalization and managing

The SAM cards that come as a set with our readers are preset to AV2 mode.

Their Master Key structure is:

KeyA= 0
VerA = 0
KeyB = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
VerB = 1
KeyC= 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
VerC = 2
SAM is unlocked at power-up or reset
All KST (1 – 127) values reset
Key No CEK = 0

Key Ver CEK = Ver A = 0

If you use a SAM card with AV1 mode, you can use the SAM Tool function to switch to AV2 mode.

2.1 SAM Tool Software – Get version and UID

This function displays the SAM Type (version) and its 7-byte UID (Unique Identifier).

SAM Tool supports:

T1AD2060 AV1 MODE
T1AD2060 AV2 MODE
T1AR1070 AV1 MODE
T1AR1070 AV2 MODE

2.2 SAM Tool Software – AV1 personalization mode

The SAM Card default mode is AV1. Its default Master Key value is DES 00 00 00 00 00 00 00 00 (eight zeros).

To use the SAMTool app with a SAM Card in AV1 mode with a Master Key different than the default, you need to reset the card Master Key first.

2.2.1 AES Master Key

For SAM Card personalization to AV1 mode, the first step is the Master Key KST (Key Storage Table) defining.
On this panel, you define 3 AES128 Keys (16 bytes long), and the Keys versions (0 – 255). The Key version is the index number of the stored Key. Finally, click the STORE MASTER KEY button to save the settings.

The Status Bar displays the current operation status.

Note: Once it is defined, The Master Key version A (index number 0) should not be modified. Otherwise, its modification may corrupt the SAM Card. Therefore, the software prohibits the master Key version subsequent change. This warning applies to the Key version only while the AES Key can be modified.

2.2.2 Switch to AV2 mode

Attention: The switch-mode process is irreversible! Once you switch the SAM Card mode from AV1 to AV2 mode, the reverse process is not possible.

The switch-mode function requires AES Master Key authentication. By switching SAM Card mode to AV2, you will reset all its KST Keys, except for the Master Key (Key version in the range of 1 – 127). To change KST Keys, you have to authenticate this action by providing the Master Key A, and Master Key A version.

Now check the SAM Card current mode:

2.3 SAM Tool Software – AV2 mode functions

This section explains the operations with SAM Card Keys in AV2 mode.

2.3.1 Host Key

The Host Key is an AES key. It is used to authenticate the Host and/or authenticate the SAM card lock / unlock functions.
SAM Card Keys modification requires Host authentication.
Once the Key mode is set to AV2 mode, the Host authenticates with Master Key A (key no = 0, Key version = Master Key A version).

The Host Key is an AES key. It finds its place in the Host Authentication process and/or in the SAM card lock / unlock functions.

SAM Card Keys modification requires Host authentication.

Once the Key mode is set to AV2 mode, the Host authenticates with Master Key A (Key No = 0, Key version = Master Key A version).

To modify the KST, you need to authenticate. To do this, go to the AES key panel and enter the Key number equal to the current Key No CEK (Key Reference Number of Change Entry Key) (0 – 127).

In the case of the Master Key, the Key number is 0. The Key version has to be equal to the current Key version CEK (Key Version of Change Entry Key).

On the panel Key number and options, enter the KST Key number (Key Reference Number) to be modified, the Key No CEK and Key version CEK new values, the Host authentication capability option, and the SAM lock/unlock the capability option.

If the Master Key Host authentication is enabled (Key index number = 0), you need to unlock the SAM Card after every reset or power-up. To authenticate the unlocking action, provide the relevant Host Key or Master Key.

If the master key SAM lock/unlock option is enabled, SAM will be locked after power-up or reset, and only minimal command set will be active.

The SAM unlocking requires authentication by providing the SAM Lock/unlock capable Key or the Host authentication Key. More details on SAM Card is available in NXP documentation.

After the SAM Card activation, the µFR reader checks the Master Key SAM Lock/unlock option status. If this status is enabled, the reader attempts to unlock the SAM Card with the AES Key stored into the reader. This feature prevents the SAM Card misuse and ensures its functionality with the readers containing the right Unlock Key only.

As for the other Host Keys (Key index number 1 – 127), the Host Authentication option can be used to assign the Host Authentication Capability of the selected Host Key, while the Lock/unlock option enables to assign the Lock/unlock Capability of the selected Host Key.

SAM Tool software does not support the Ref No KUC (Reference Number of Key Usage Counter) option. There is no limit for the number of authentication attempts (Ref No KUC = 255).

On the Host Key KST panel, enter all AES Keys (HEX 16-byte Key) and Key Versions ( value in the range of 0 – 255) and click the STORE HOST KEY button to store this KST into SAM Card.

This Host Key parameters are:

Key number = 105
current Key No CEK = 0
current Key Ver CEK = 0 (first Key modification with Master Key A)
new Key No CEK = 0
new Key Ver CEK = 1 (the new Key changing with Master Key B (Master Key B version = 1)),
Host Authentication Capability enabled, Lock/unlock Capability disabled.

KST values are:

Key A = 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16
Key A version = 10
Key B = 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55 55
Key B version = 20
Key C = 66 66 66 66 66 66 66 66 66 66 66 66 66 66 66 66
Key C version = 30

EXAMPLE 1

For example, modify the Host Key 105 to a Key that has Lock/unlock ability only. Leave other parameters, and values unchanged.

Assign Host Key 106 for Host Authentication.

sam-tool-av2-operations-example-1a-768x302

2.3.2 SAM Card Key

The Card (PICC) Key is the Key to authenticate on the PICC.

This Key can be:

AES (16 bytes) for DESFire and Mifare plus card
DES (8 bytes) for DESFire card
2K3DES (16 bytes) for Ultralight C card
2K3DES (16 bytes) for DESFire card
3K3DES (24 bytes) for DESFire card
Crypto1 (6 bytes) for Mifare classic card

As with previously explained Host Key authentication, fill in the Host Authentication Key parameters and values fields of the AES Key panel.

Under the Key Number And Option panel, fill in the Key Number, Key No CEK, and Key Ver CEK values. Ignore all other parameter fields.

Under the Card Key panel, select the Key type, and enter the Key value. For Crypto1 Key type, enter two Keys (KeyA and KeyB) in a row (6-byte Key A, and 6-byte Key B 6, total 12 bytes).

Click the STORE CARD KEY button to store the Key into the SAM Card.

One KST can hold just one Card Key. This limit ensures the Card functionality on the systems with the Reader Internal Key authentication.

For Crypto1 Keys, the Reader Internal Key Index is a value in the range 0-to 31, while the AES, DES, 2K3DES, and 3K3DES Key Index is in the range of 0-15.

SAM Card Key Index allows any value in the range of 1-127, except for the Host Key indexes.

Card Key parameters and values:

Key No = 107
current Key No CEK = 0
current Key ver CEK = 0 (first key changing with master key A)
new Key No CEK = 106
new Key Ver CEK = 100 (Key A of KST 106)
type of card Key is 3K3DES (24 bytes)
value of the Key 11 11 11 11 11 11 22 22 22 22 22 22 AA AA AA AA AA AA BB BB BB BB BB BB

This action changse the Key No 107 value to 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24.
Other parameters remain the same.

2.4 SAM Tool Software – SAM Unlock Key functions

This section explains the SAM Unlock Key function.

2.4.1 SAM Unlock Key stored into the reader

If the Master Key Lock/unlock parameter is enabled, to unlock the SAM Card, you need a Key with Lock/unlock capability.

The µFR reader attempts to unlock the SAM Card by the Key stored into the reader.

On the SAM Unlock Key panel fill in the parameters and the value of the Key with Lock/unlock capability stored into the SAM Card, click the STORE UNLOCK KEY button to confirm the entry and store the Key into the reader.

If the reader Internal Keys are locked, this action will be rejected. In this case, the Internal Keys unlock is required.

Example:

Store the Key A No 105 into the reader. The Key 105 has the Lock/unlock capability, and has no Host Authentication capability.

2.4.2 Lock or Unlock Reader Key

Lock/unlock Reader Key is a security option that provides protection against unauthorized change of the Keys stored in the reader. To unlock the Reader Keys, you need to provide a valid 8-byte password and press the button UNLOCK READER KEYS of the Lock or Unlock Reader Keys panel.

To lock the Reader Keys, you need to enter any 8-byte password. The factory default status for the Reader Keys is unlocked.

To create a password, you can choose between ASCII and the hexadecimal number system (as shown in the screenshots below).

ASCII

HEX

HOME

HARDWARE PRODUCTS

SDK SOFTWARE