#SpringCoreTool

#Name

SpringCoreTool.exe

#Description

SpringCoreTool.exe is a command-line tool giving access to many features of any SpringCore device.

The tool can be used for:

• Query device’s information, technical data, statistics, and read its registers,
• Manage the device’s authenticity seal,
• Get authenticated onto the device and manage its security keys,
• Send direct commands to the device (reset, shutdown, etc).

#Dependencies

SpringCoreTool.exe runs over Microsoft .NET standard framework, version 4.6.2 or greater. On Linux and Mac OS X, it runs over Mono.

#Copyright and License

Copyright 2019-2020 SpringCard SAS, France. All Rights Reserved.

See LICENSE.txt in the tool directory for the complete License.

#Synopsis

Windows:

> SpringCoreTool.exe ACTION [PARAMETERS] [[OPTIONS]]

Linux / Mac OS X:

$ mono SpringCoreTool.exe ACTION [PARAMETERS] [[OPTIONS]]

#Common features

#Device selection

SpringCoreTool.exe needs to open a communication channel with the SpringCore device. See Device selection for details.

#Secure sessions

See Secure sessions.

#Misc.

See Misc. options.

#Action list

SpringCoreTool.exe provides a rich variety of actions. Each action can have many argument parameters and options.

#infos

Show device’s information

This function uses the SpringCore GET_DATA instruction to fetch all the information from the devices, and display them in a friendly way.

SpringCoreTool.exe infos [--json]

Add the --json option to format the output as a JSON object.

#stats

Show device’s usage statistics

This function collects the device’s usage statistics and display them in a friendly way.

SpringCoreTool.exe stats [--json]

Add the --json option to format the output as a JSON object.

#dump-consts

Dump the constants

This command dumps the content of registers 0100 to 01FF (constants).

SpringCoreTool.exe dump-consts [--names] [--json]

Add the --name option to show the register names (when known). Default is showing their address only.

Add the --json option to format the output as a JSON object.

Note that dumping the constants could be disabled in the device’s configuration to enforce security.

#dump-config

Dump the configuration

This command dumps the content of registers 0200 to 02FF (configuration).

SpringCoreTool.exe dump-config [--names] [--json]

Add the --name option to show the register names (when known). Default is showing their address only.

Add the --json option to format the output as a JSON object.

Note that dumping the configuration could be disabled in the device’s configuration to enforce security.

#dump-templates

Dump the template settings

This command dumps the content of registers 0300 to 03FF (templates).

SpringCoreTool.exe dump-templates [--names] [--json]

Add the --name option to show the register names (when known). Default is showing their address only.

Add the --json option to format the output as a JSON object.

Note that dumping the configuration could be disabled in the device’s configuration to enforce security.

#battery

Show the state of the battery

If the device features a battery, this command shows the current level and charging status.

SpringCoreTool.exe battery [--json]

Add the --json option to format the output as a JSON object.

#bootloader

Show the bootloader data

If the device features a bootloader, this command shows its version and parameters.

SpringCoreTool.exe bootloader [--json]

Add the --json option to format the output as a JSON object.

#auth-key

Get authenticated using a secret key

If the device supports AES mutual-authentication, this command runs the mutual-authentication over either the Admin or the User key.

SpringCoreTool.exe auth-key <admin|user> <SECRET KEY> [--no-div]

Specify admin for Admin key or user for User key.

Provide the secret key in hex (16 bytes i.e. 32 hex chars). Use the alias BLANK for an all-00 key.

The secret key is diversified by the device’s serial number. Add the --no-div option to disable the diversification.

Only devices featuring a ATAES Secure Element are expected to provide this feature.

#auth-pass

Get authenticated using a pass-phrase as secret key

If the device supports AES mutual-authentication, this command runs the mutual-authentication over either the Admin or the User key, using a pass-phrase instead of a raw secret key.

At the difference of the auth-key command which expects the “raw” key bytes, the auth-pass command takes a passphrase has inputs and uses a hash function to create the key bytes.

SpringCoreTool.exe auth-pass <admin|user> "<SECRET PASSPHRASE>" [--no-div]

Specify admin for Admin key or user for User key.

Provide the secret passphrase, enclosed by quotes.

The secret key is computed by hashing the passphrase, then diversified by the device’s serial number. Add the --no-div option to disable the diversification.

Only devices featuring a ATAES Secure Element are expected to provide this feature.

#auth-ecdh

Get authenticated using a ECC private key

#Private key on the command line:

SpringCoreTool.exe auth-ecdh <admin|user> <PRIVATE KEY> 

#Private in a PEM file:

SpringCoreTool.exe auth-ecdh <admin|user> --key-file <PRIVATE KEY FILE>

#auth-reset

Forget current authentication state

SpringCoreTool.exe auth-reset

#change-key

Change the secret key

If the device supports AES mutual-authentication, this command changes one of the AES secret keys.

SpringCoreTool.exe change-key <user|admin> <NEW SECRET KEY> [--no-div]

Specify admin for Admin key or user for User key.

Provide the secret key in hex (16 bytes i.e. 32 hex chars). Use the alias BLANK for an all-00 key.

The secret key is diversified by the device’s serial number. Add the --no-div option to disable the diversification.

Only devices featuring a ATAES Secure Element are expected to provide this feature.

#change-pass

Change the secret key using a pass-phrase

If the device supports AES mutual-authentication, this command changes one of the AES secret keys, using a pass-phrase instead of a raw secret key.

SpringCoreTool.exe change-pass <user|admin> "<NEW SECRET PASSPHRASE>" [--no-div]

Specify admin for Admin key or user for User key.

Provide the secret passphrase, enclosed by quotes.

The secret key is computed by hashing the passphrase, then diversified by the device’s serial number. Add the --no-div option to disable the diversification.

Only devices featuring a ATAES Secure Element are expected to provide this feature.

#pass-to-key

Transform a pass-phrase into a secret key

This commands performs the same algorithm as auth-pass and change-pass but echoes the secret key instead of using it.

SpringCoreTool.exe pass-to-key <user|admin> "<SECRET PASSPHRASE>"

This command does not need a connection to the device.

#datetime-get

Get device’s date & time

SpringCoreTool.exe datetime-get [--utc]

If the --utc option is asserted, the date & time is displayed as it is in the device, i.e. in UTC. Otherwise, the date & time is converted to local before displaying.

Only devices featuring a (battery-backed-up) real-time clock are expected to provide this feature. Internally, the device’s RTC uses UTC.

#datetime-set

Set device’s date & time

Set device’s date & time to the computer’s:

SpringCoreTool.exe datetime-set

Set device’s date & time manually:

SpringCoreTool.exe datetime-set --date=YYYY-MM-DD --time=HH:MM:SS [--utc]

If the --utc option is asserted, the tool assumes that the date & time is entered directly UTC. Otherwise, the date & time is converted from local to UTC before being sent to the device.

Only devices featuring a (battery-backed-up) real-time clock are expected to provide this feature. Internally, the device’s RTC uses UTC.

#load-defaults

Load out-of-factory configuration

Use this command to revert the device to its default configuration. This blanks the templates (registers 0300 to 03FF) and set back the configuration registers (0200 to 03FF) to the value they had at delivery-time.

SpringCoreTool.exe load-defaults

Note that re-loading the out-of-factory configuration could be disabled in the device’s configuration to protect the device against unwanted configuration changes.

#reset

Reset the device

Use this command to reset the device, for instance to have it apply a new configuration.

SpringCoreTool.exe reset

#shutdown

Shutdown the device

SpringCoreTool.exe shutdown

Only devices with a deep power-down mode are expected to provide this feature.

#wink

Ask the device to ‘wink’

A SpringCore device respond to a wink command by a specific LED/buzzer sequence that helps the user to locate the very product he is working on, among others.

SpringCoreTool.exe wink

#seal-verify

Verify the device’s authenticity seal

SpringCoreTool.exe seal-verify

#seal-subject

Read the subject of the device’s authenticity seal

SpringCoreTool.exe seal-subject

#seal-get

Read the value of the device’s authenticity seal

SpringCoreTool.exe seal-get

#Advanced actions (factory only)

The following actions are reserved for SpringCard factory and after-sales service, and for integrators under NDA with SpringCard to provide after-sales service themselves and/or to load specific configuration into the SpringCore devices before delivery.

#auth-factory

Get authenticated against a factory RSA private key

SpringCoreTool.exe auth-factory [--key-file=<PRIVATE KEY (PEM)>]

#seal-set

Write the value of the device’s authenticity seal

SpringCoreTool.exe seal-set <INPUT>

#seal-erase

Erase the current authenticity seal

SpringCoreTool.exe seal-erase

#seal-lock

Lock the authenticity seal

This command sets the Lock Authenticity Seal bit in the FUSES registers.

SpringCoreTool.exe seal-lock

#seal-create

Create and write the authenticity seal locally

This command creates an authenticity seal for the device, and writes it into it. The private key to the authenticity seals is provided in a PEM file.

SpringCoreTool.exe seal-create --key-file=<PRIVATE KEY (PEM)>

Note: the private key file for the authenticity seals is not available outside SpringCard’s factory

#seal-create-server

Create and write the authenticity seal using the Server

This command asks the SpringCard production server to create an authenticity seal for the device, and writes it into it

SpringCoreTool.exe seal-create-server [--url=<SIGNATURE REST API>] [--login=<LOGIN>] [--password=<PASSWORD>] \
	[-product-code=<CODE>] [--factory-id=<ID>] [--machine-id=<ID>] \
	[--order-code=<CODE>] [--batch-num=<NUM>]

Note: use only the parameter specified by SpringCard

#seal-create-sam

Create and write the Seal using a SAM

This command creates an authenticity seal for the device, and writes it into it. The private key to the authenticity seals is provided in a SAM AV.

SpringCoreTool.exe seal-create-sam [--reader=<SAM READER>] [--key-index=<0|1>]

#seal-verify-sam

Verify the authenticity seal using a SAM

This command verifies the device’s authenticity seal. The public key to the authenticity seals is provided in a SAM AV.

SpringCoreTool.exe seal-verify-sam [--reader=<SAM READER>] [--key-index=<0|1>]

#seal-create-file

Reserved for future use

#seal-verify-file

Reserved for future use

#blank-stats

Erase the statistics

This command erase the device’s statistics (registers 0400 to 04FF)

SpringCoreTool.exe blank-stats

Note: this command is only available after a successfull auth-factory command followed by a unlock command.

#blank-all

Erase everything

This command erase all the device’s constants, configuration, templates and statistics (registers 0100 to 04FF)

SpringCoreTool.exe blank-all

Note: this command is only available after a successfull auth-factory command followed by a unlock command.

#blank

Erase the configuration

This command erase most the device’s configuration, templates and statistics (registers 0200 to 04FF).

SpringCoreTool.exe blank

Note: this command is only available after a successfull auth-factory command followed by a unlock command.

#save-defaults

Store the out-of-factory configuration

This command saves a copy of the current configuration as the device’s out-of-factory configuration

SpringCoreTool.exe save-defaults

Note: this command is only available after a successfull auth-factory command.

#lock-defaults

Lock the out-of-factory configuration

This command sets the Lock Factory Config bit in the FUSES registers.

SpringCoreTool.exe lock-defaults

#lock-consts

Lock the constants

This command sets the Lock Constants bit in the FUSES registers.

SpringCoreTool.exe lock-constants

#lock-seal

Lock the authenticity seal

This command sets the Lock Authenticity Seal bit in the FUSES registers.

SpringCoreTool.exe lock-seal

#lock-all

Lock everything

This command sets all bits in the FUSES registers.

SpringCoreTool.exe lock-all

#unlock

Unlock the device

This command (temporarily) overcomes the lock bits set in the FUSES registers.

SpringCoreTool.exe unlock

Note: this command is only available after a successfull auth-factory command.

#apply

This command takes in accound the new value of the configuration and template registers without resetting the device.

SpringCoreTool.exe apply

Note: this command is only available after a successfull auth-factory command.