Misc SamAvTool

April 13, 2023 at 2:40 AM

SamAvTool

Name

SamAvTool.exe

Description

SamAvTool.exe is a command-line tool giving access to most features of the NXP SAM AV2 or AV3 secure element, through a PC/SC reader.

The tool can be used for:

  • Management of secret keys, RSA keys and counter in the SAM,
  • Analysis and management of the SAM itself,
  • Copy of a SAM to another, including transpose key options from a ‘root’ SAM to a derived ‘reader’ SAM or ‘reader-writer’ SAM,
  • Batch-creation of SAMs given a template file.

Notes:

  1. This tool does not support SAM AV1 legacy mode. See section Activate AV2 mode below to configure a SAM AV2 for AV2 mode before using it.
  2. This tool does not support secure communication modes. Only plain communications is supported.
  3. Unless specified, all numbers have to be entered and are shown in hexadecimal.

Dependencies

SamAvTool.exe runs over Microsoft .NET standard framework, version 4.6.2 or greater.

It is dependent on the following SpringCard libraries:

  • SpringCard.SamAvTool.dll : engine behind SamAvTool.exe
  • SpringCard.PCSC.CardHelpers.SamAV.dll : host-side implementation of NXP SAM AV2 functions
  • SpringCard.PCSC.CardHelpers.dll : utility library for host-side card implementations
  • SpringCard.PCSC.dll : PC/SC library (wrapper over winscard or libpcsclite)

It also has a dependency over BouncyCastle.Crypto.dll for RSA operations.

License

See LICENSE.txt in the tool directory.

Usage

Synopsis

SamAvTool.exe ACTION [PARAMETERS] [[OPTIONS]]

Main SAM management commands

Ceremony

Instantiate a new root SAM. The structure of the keys in the SAM is provided in the template file.

Optionally, the content of the root SAM may be saved in a project file.

SamAvTool.exe
	ceremony-root
	--input-file <template file>
	--reader <PS/SC reader with the root SAM>
	[--output-file <project file>]

Create a derived ‘writer’ SAM

(TODO)

From the root SAM
SamAvTool.exe
	create-writer
	--source-reader <PC/SC reader with the root SAM>
	--target-reader <PC/SC reader with the target SAM>
From the project file
SamAvTool.exe
	create-writer
	--input-file <project file>
	--reader <PC/SC reader with the target SAM>

Create a derived ‘reader’ SAM

From the root SAM

(TODO)

SamAvTool.exe
	create-reader
	--source-reader <PC/SC reader with the root SAM>
	--target-reader <PC/SC reader with the target SAM>

#####From the project file

SamAvTool.exe
	create-reader
	--input-file <project file>
	--reader <PC/SC reader with the target SAM>

Create a new root SAM

From the original root SAM
SamAvTool.exe
	create-root
	--source-reader <PC/SC reader with the root SAM>
	--target-reader <PC/SC reader with the target SAM>
From the project file
SamAvTool.exe
	create-root
	--input-file <project file>
	--reader <PC/SC reader with the target SAM>

Backup a root SAM to a project file

SamAvTool.exe
	backup-root
	--reader <PC/SC reader with the root SAM>
	--output-file <project file>

Erase a SAM

Using the project file
SamAvTool.exe
	blank
	--input-file <project file>
	--reader <PC/SC reader with the SAM>
Specifying the master key on the command line

(TODO)

SamAvTool.exe
	blank
	[--key-idx=<00..7F> (index of master key - default is 00)]
	[--key-version=<00..7F> (version of master key - default is 00)]
	[--key-type=<type> (type of master key - default is AES128)]
	--key-value <value of master key (hex)>
	--reader <PC/SC reader with the SAM>

Other SAM management commands

Show SAM version (and UID)

(TODO)

SamAvTool.exe
	info
	--reader <PC/SC reader with the SAM>

Activate AV2 mode

(TODO)

SamAvTool.exe
	go-av2
	--reader <PC/SC reader with the SAM>

Lock a SAM

(TODO)

SamAvTool.exe
	lock
	[--key-idx=<00..7F> (index of lock/unlock key - default is 01)]
	[--key-version=<00..7F> (version of lock/unlock key - default is 01)]
	[--key-type=<type> (type of lock/unlock key - defaut is Aes128)]
	--key-value <value of lock/unlock key (hex)>
	--reader <PC/SC reader with the SAM>

Unlock a SAM

(TODO)

SamAvTool.exe
	unlock
	[--key-idx=<00..7F> (index of lock/unlock key - default is 01)]
	[--key-version=<00..7F> (version of lock/unlock key - default is 01)]
	[--key-type=<type> (type of lock/unlock key - defaut is Aes128)]
	--key-value <value of lock/unlock key (hex)>
	--reader <PC/SC reader with the SAM>

Get authenticated onto a SAM

(TODO)

SamAvTool.exe
	host-auth
	[--key-idx=<00..7F> (index of host auth key - default is 00)]
	[--key-version=<00..7F> (version of host auth key - default is 00)]
	[--key-type=<type> (type of host auth key - defaut is Aes128)]
	--key-value <value of host auth key (hex)>
	--reader <PC/SC reader with the SAM>

Forget current authentication state

(TODO)

SamAvTool.exe
	kill-auth
	--reader <PC/SC reader with the SAM>

Key entry commands

Dump the key entries

SamAvTool.exe
	dump-keys
	--reader <PC/SC reader with the SAM>
	[--dump-secrets=<true|false> (default is false)]

RSA PKI commands

Dump the RSA entries

SamAvTool.exe
	dump-rsa
	--reader <PC/SC reader with the SAM>
	--dump-public=<true|false> (default is false)]
	--dump-private=<true|false> (default is false)]

Counter commands

Dump the counters

SamAvTool.exe
	dump-counters
	--reader <PC/SC reader with the SAM>

Change a counter limit

(TODO)

SamAvTool.exe
	set-counter
	--counter-idx=<0..F>
	--counter-limit=<00000000..FFFFFFFF>
	--reader <PC/SC reader with the SAM>

Format of the project files

Top-level structure

{
    "Keys": {
        "00": KEY-ENTRY@0x00,
        "01": KEY-ENTRY@0x01,
        ...
        "7F": KEY-ENTRY@0x7F
    },
    "RSA": {
    	"00": RSA-KEY-ENTRY@0x00,
    	"01": RSA-KEY-ENTRY@0x01,
    	"02": RSA-KEY-ENTRY@0x02
	},
    "Counters": {
		"00": COUNTER@0x00,
        "01": COUNTER@0x01,
        ...
        "0F": COUNTER@0x0F
    }
}

The KEY-ENTRY object

{
    "VersionA": "<Version of the secret key A (hex)>",
    "VersionB": "<Version of the secret key B (hex)>",
    "VersionC": "<Version of the secret key C (hex)>",
    "DesfireAid": "<Desfire Application IDentifier (hex)>",
    "DesfireKeyIdx": "<Key index in the Desfire application (hex)>",
    "ChangeKeyIdx": "<Index of the change key (hex)>",
    "ChangeKeyVersion": "<Version of the change key (hex)>",
    "CounterIdx": "<Index of the counter (hex)>",
    "KeyType": "Aes128",
    "KeyClass": "Host|OfflineChange|PICC|OfflineCrypto",
    "Flags": {
        "DisableKeyEntry": true|false,
        "KeepIV": true|false,
        "HostAuthKey": true|false,
        "LockUnlockKey": true|false,
        "DiversifiedOnly": true|false,
		"EnableDumpSecretKey": true|false,
        "EnableDumpSessionKey": true|false,
        "DisableWriteToPICC": true|false,
        "DisableDecrypt": true|false,
        "DisableEncrypt": true|false,
        "DisableVerifyMAC": true|false,
        "DisableGenerateMAC": true|false,
    },
    "ValueA": "<Value of the secret key A (hex)",
    "ValueB": "<Value of the secret key B (hex)",
    "ValueC": "<Value of the secret key C (hex)",
    "Generate": true|false					// Only before the ceremony
}

The RSA-KEY-ENTRY object

{
    "ChangeKeyIdx": "<Index of the change key (hex)>",
    "ChangeKeyVersion": "<Version of the change key (hex)>",
    "CounterIdx": "<Index of the counter (hex)>",
    "Flags": {
        "DisableKeyEntry": true|false,
        "PrivateKey": true|false,
        "EnableDumpPrivateKey": true|false,
        "DisableEncryptDecrypt": true|false,
        "DisableSignature": true|false
    },
    "Public": {
        "N": "<Public modulus (hex)",
        "E": "<Public exponent (hex)"
    },
    "Private": {							// Only for a private key
        "P": "<Prime P (hex)",
        "Q": "<Prime Q (hex)",
        "dP": "<Inverse of P mod N (hex)",
        "dQ": "<Inverse of Q mod N (hex)",
        "iPQ": "<Inverse of P mod Q (hex)"
    },
    "Generate": true|false					// Only before the ceremony
}

The COUNTER object