Device state: libmccr Reference Manual

Device state

Device state — Methods to query and manage the device state.

Functions

mccr_status_t	mccr_device_read_software_id ()
mccr_status_t	mccr_device_read_usb_serial_number ()
mccr_status_t	mccr_device_read_polling_interval ()
mccr_status_t	mccr_device_read_device_serial_number ()
mccr_status_t	mccr_device_read_magnesafe_version_number ()
const char *	mccr_track_state_to_string ()
mccr_status_t	mccr_device_read_track_id_enable ()
mccr_status_t	mccr_device_read_max_packet_size ()
mccr_status_t	mccr_device_read_iso_track_mask ()
mccr_status_t	mccr_device_read_aamva_track_mask ()
mccr_status_t	mccr_device_get_dukpt_ksn_and_counter ()
mccr_status_t	mccr_device_set_session_id ()
const char *	mccr_reader_state_to_string ()
const char *	mccr_reader_state_antecedent_to_string ()
mccr_status_t	mccr_device_get_reader_state ()
mccr_status_t	mccr_device_get_security_level ()
mccr_status_t	mccr_device_get_encryption_counter ()
mccr_status_t	mccr_device_get_magtek_update_token ()

Types and Values

enum	mccr_track_state_t
enum	mccr_reader_state_t
enum	mccr_reader_state_antecedent_t
enum	mccr_security_level_t
#define	MCCR_ENCRYPTION_COUNTER_DISABLED
#define	MCCR_ENCRYPTION_COUNTER_EXPIRED
#define	MCCR_ENCRYPTION_COUNTER_MIN
#define	MCCR_ENCRYPTION_COUNTER_MAX

Description

This section defines methods to query the current device state.

Example 3. Reading the DUKPT KSN and counter

mccr_status_t  st;
uint8_t       *ksn;
size_t         ksn_size, i;

if ((st = mccr_device_get_dukpt_ksn_and_counter (device, &ksn, &ksn_size)) != MCCR_STATUS_OK) {
  fprintf (stderr, "error: cannot get DUKPT KSN and counter: %s\n", mccr_status_to_string (st));
  return;
}

printf ("DUKPT KSN and counter: ");
for (i = 0; i < ksn_size; i++)
  printf ("%02x%s", ksn[i], i < (ksn_size - 1) ? ":" : "");
printf ("\n");

free (ksn);

Functions

mccr_device_read_software_id ()

mccr_status_t
mccr_device_read_software_id (mccr_device_t *device,
                              char **out_str);

Read the Software ID property string.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_str	output location for the newly allocated string property.

Returns

a mccr_status_t.

mccr_device_read_usb_serial_number ()

mccr_status_t
mccr_device_read_usb_serial_number (mccr_device_t *device,
                                    char **out_str);

Read the USB serial number property string.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_str	output location for the newly allocated string property.

Returns

a mccr_status_t.

mccr_device_read_polling_interval ()

mccr_status_t
mccr_device_read_polling_interval (mccr_device_t *device,
                                   uint8_t *out_val);

Read the polling interval, in milliseconds.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_val	output location for the uint8_t.

Returns

a mccr_status_t.

mccr_device_read_device_serial_number ()

mccr_status_t
mccr_device_read_device_serial_number (mccr_device_t *device,
                                       char **out_str);

Read the device serial number property string.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_str	output location for the newly allocated string property.

Returns

a mccr_status_t.

mccr_device_read_magnesafe_version_number ()

mccr_status_t
mccr_device_read_magnesafe_version_number
                               (mccr_device_t *device,
                                char **out_str);

Read the MagneSafe version number property string.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_str	output location for the newly allocated string property.

Returns

a mccr_status_t.

mccr_track_state_to_string ()

const char *
mccr_track_state_to_string (mccr_track_state_t st);

Gets a description for the given mccr_track_state_t.

Parameters

a mccr_track_state_t.

Returns

a constant string.

mccr_device_read_track_id_enable ()

mccr_status_t
mccr_device_read_track_id_enable (mccr_device_t *device,
                                  bool *out_aamva_supported,
                                  mccr_track_state_t *out_track_1,
                                  mccr_track_state_t *out_track_2,
                                  mccr_track_state_t *out_track_3);

Read the ISO track mask property string.

Parameters

device	an open mccr_device_t.
out_aamva_supported	output location for the boolean specifying whether AAMVA cards are supported..
out_track_1	output location for the mccr_track_state_t with the track 1 status.
out_track_2	output location for the mccr_track_state_t with the track 2 status.
out_track_3	output location for the mccr_track_state_t with the track 3 status.

Returns

a mccr_status_t.

mccr_device_read_max_packet_size ()

mccr_status_t
mccr_device_read_max_packet_size (mccr_device_t *device,
                                  uint8_t *out_val);

Read the maximum packet size, in bytes.

Parameters

device	an open mccr_device_t.
out_val	output location for the uint8_t.

Returns

a mccr_status_t.

mccr_device_read_iso_track_mask ()

mccr_status_t
mccr_device_read_iso_track_mask (mccr_device_t *device,
                                 char **out_str);

Read the ISO track mask property string.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_str	output location for the newly allocated string property.

Returns

a mccr_status_t.

mccr_device_read_aamva_track_mask ()

mccr_status_t
mccr_device_read_aamva_track_mask (mccr_device_t *device,
                                   char **out_str);

Read the AAMVA track mask property string.

When no longer needed, out_str should be disposed with free().

Parameters

device	an open mccr_device_t.
out_str	output location for the newly allocated string property.

Returns

a mccr_status_t.

mccr_device_get_dukpt_ksn_and_counter ()

mccr_status_t
mccr_device_get_dukpt_ksn_and_counter (mccr_device_t *device,
                                       uint8_t **out_ksn_and_counter,
                                       size_t *out_ksn_and_counter_size);

Get DUKPT KSN and counter.

The returned array will be 10 bytes long, the output out_ksn_and_counter_size is given for convenience.

When no longer needed, out_ksn_and_counter should be disposed with free().

Parameters

device	an open mccr_device_t.
out_ksn_and_counter	output location for the newly allocated array containing the KSN and counter.
out_ksn_and_counter_size	output location for the size_t with the size of `out_ksn_and_counter` .

Returns

a mccr_status_t.

mccr_device_set_session_id ()

mccr_status_t
mccr_device_set_session_id (mccr_device_t *device,
                            uint64_t session_id);

Set the current session id, used by the host to uniquely identify the present transaction.

Parameters

device	an open mccr_device_t.
session_id	a 64-bit value.

Returns

a mccr_status_t.

mccr_reader_state_to_string ()

const char *
mccr_reader_state_to_string (mccr_reader_state_t st);

Gets a description for the given mccr_reader_state_t.

Parameters

a mccr_reader_state_t.

Returns

a constant string.

mccr_reader_state_antecedent_to_string ()

const char *
mccr_reader_state_antecedent_to_string
                               (mccr_reader_state_antecedent_t val);

Gets a description for the given mccr_reader_state_antecedent_t.

Parameters

val

a mccr_reader_state_antecedent_t.

Returns

a constant string.

mccr_device_get_reader_state ()

mccr_status_t
mccr_device_get_reader_state (mccr_device_t *device,
                              mccr_reader_state_t *out_state,
                              mccr_reader_state_antecedent_t *out_antecedent);

Get current reader state and how the reader reached it.

Parameters

device	an open mccr_device_t.
out_state	output location for the mccr_reader_state_t.
out_antecedent	output location for the mccr_reader_state_antecedent_t.

Returns

a mccr_status_t.

mccr_device_get_security_level ()

mccr_status_t
mccr_device_get_security_level (mccr_device_t *device,
                                mccr_security_level_t *out_level);

Get current security level.

Parameters

device	an open mccr_device_t.
out_level	output location for the mccr_security_level_t.

Returns

a mccr_status_t.

mccr_device_get_encryption_counter ()

mccr_status_t
mccr_device_get_encryption_counter (mccr_device_t *device,
                                    char **out_device_serial_number,
                                    uint32_t *out_encryption_counter);

Get device serial number and encryption counter.

When no longer needed, out_device_serial_number should be disposed with free().

Parameters

device	an open mccr_device_t.
out_device_serial_number	output location for the newly allocated device serial number string.
out_encryption_counter	output location for the encryption counter.

Returns

a mccr_status_t.

mccr_device_get_magtek_update_token ()

mccr_status_t
mccr_device_get_magtek_update_token (mccr_device_t *device,
                                     uint8_t **out_mut,
                                     size_t *out_mut_size);

Get Magtek Update Token (MUT).

The returned array will be 36 bytes long, the output out_mut_size is given for convenience.

When no longer needed, out_mut should be disposed with free().

Parameters

device	an open mccr_device_t.
out_mut	output location for the array containing the MUT.
out_mut_size	output location for the size_t with the size of `out_mut` .

Returns

a mccr_status_t.

Types and Values

enum mccr_track_state_t

State of the card track.

Members

MCCR_TRACK_STATE_DISABLED	Track is disabled.
MCCR_TRACK_STATE_ENABLED	Track is enabled.
MCCR_TRACK_STATE_ENABLED_REQUIRED	Track is enabled and required (error if blank).

enum mccr_reader_state_t

Current reader state.

Members

MCCR_READER_STATE_WAIT_ACTIVATE_AUTHENTICATION	Waiting for authenticated mode.
MCCR_READER_STATE_WAIT_ACTIVATION_REPLY	Waiting for activation challenge reply.
MCCR_READER_STATE_WAIT_SWIPE	Waiting for swipe.
MCCR_READER_STATE_WAIT_DELAY	Waiting for anti-hacking timer.

enum mccr_reader_state_antecedent_t

How the reader got into its current state.

Members

MCCR_READER_STATE_ANTECEDENT_POWERED_UP	Powered up.
MCCR_READER_STATE_ANTECEDENT_GOOD_AUTHENTICATION	Good authentication.
MCCR_READER_STATE_ANTECEDENT_GOOD_SWIPE	Good swipe.
MCCR_READER_STATE_ANTECEDENT_BAD_SWIPE	Bad swipe.
MCCR_READER_STATE_ANTECEDENT_FAILED_AUTHENTICATION	Failed authentication.
MCCR_READER_STATE_ANTECEDENT_FAILED_DEACTIVATION	Failed deactivation.
MCCR_READER_STATE_ANTECEDENT_TIMED_OUT_AUTHENTICATION	Authentication timed out.
MCCR_READER_STATE_ANTECEDENT_TIMED_OUT_SWIPE	Swipe timed out.
MCCR_READER_STATE_ANTECEDENT_KEY_SYNC_ERROR	Key sync error.

enum mccr_security_level_t

Security level.

Members

MCCR_SECURITY_LEVEL_0	Security level 0: all DUKPT keys used.
MCCR_SECURITY_LEVEL_1	Security level 1: factory test only.
MCCR_SECURITY_LEVEL_2	Security level 2: least secure user mode, only track data is sent, no magneprint data.
MCCR_SECURITY_LEVEL_3	Security level 3: encryption of track data, magneprint data and session id enabled.
MCCR_SECURITY_LEVEL_4	Security level 4: authentication required.

MCCR_ENCRYPTION_COUNTER_DISABLED

#define MCCR_ENCRYPTION_COUNTER_DISABLED 0xFFFFFF

Encryption counter is disabled.

MCCR_ENCRYPTION_COUNTER_EXPIRED

#define MCCR_ENCRYPTION_COUNTER_EXPIRED 0x000000

Encryption counter is expired (all transactions prohibited).

MCCR_ENCRYPTION_COUNTER_MIN

#define MCCR_ENCRYPTION_COUNTER_MIN 0x000001

Minimum valid encryption counter.

MCCR_ENCRYPTION_COUNTER_MAX

#define MCCR_ENCRYPTION_COUNTER_MAX 0x0F4240

Maximum valid encryption counter.