card_status.h File Reference

What a tapped card is missing, read from its SELECT response. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for card_status.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	CARD_SELECT_APDU
	SELECT for the Cryptnox applet: CLA INS P1 P2 Lc || AID.
#define	CARD_FLAGS_OFF   5U
	Offset of the flags byte in a SELECT response.
#define	CARD_SELECT_MIN   8U
	Shortest SELECT response this can read: flags plus the status word.
#define	CARD_FLAG_PIN_SET   0x40U
#define	CARD_FLAG_SEEDED   0x20U

Enumerations
enum	card_state_t { CARD_READY = 0 , CARD_UNKNOWN , CARD_NO_PIN , CARD_NO_KEY }
	What a tapped card is missing. More...

Functions
static card_state_t	card_state (const uint8_t *r, size_t n)
	Judge a card from its SELECT response.
static const char *	card_state_text (card_state_t s)
	The line to put in front of the operator, or NULL if there is none.

Detailed Description

What a tapped card is missing, read from its SELECT response.

A card straight out of its envelope has no PIN and no key on it. Neither the payment path nor the payout read can do anything with one, and without this both find out three APDUs later — as "Wrong card PIN" or as a sign error — which sends the operator looking for a fault that is not there. The applet publishes both facts in the clear in its SELECT response, before any secure channel or PIN is involved, so the terminal can simply say which.

Header-only and free of ESP-IDF, for the same reason addr_check.h is: it is a parser over bytes a card sent, so it is kept where a host test can reach it (tests/units/test_card_status.cpp).

The layout is the one cryptnox-sdk-py's factory._select() reads:

r[0]      card type, 'B' (Basic) or 'N' (NFT)
r[1..3]   applet version
r[4..35]  the 32 data bytes; r[5] is the flags byte
r[n-2..]  SW1 SW2

and the two flags are the ones it exposes as card.initialized and card.seeded.

Definition in file card_status.h.

Macro Definition Documentation

CARD_FLAG_PIN_SET

#define CARD_FLAG_PIN_SET   0x40U

Initialised: PIN and PUK are set.

Definition at line 48 of file card_status.h.

Referenced by card_state().

CARD_FLAG_SEEDED

#define CARD_FLAG_SEEDED   0x20U

A key has been generated or loaded.

Definition at line 49 of file card_status.h.

Referenced by card_state().

CARD_FLAGS_OFF

#define CARD_FLAGS_OFF   5U

Offset of the flags byte in a SELECT response.

Definition at line 43 of file card_status.h.

Referenced by card_state().

CARD_SELECT_APDU

#define CARD_SELECT_APDU

Value:

{ 0x00U, 0xA4U, 0x04U, 0x00U, 0x07U, \
0xA0U, 0x00U, 0x00U, 0x10U, 0x00U, 0x01U, 0x12U }

SELECT for the Cryptnox applet: CLA INS P1 P2 Lc || AID.

Definition at line 39 of file card_status.h.

Referenced by card_fault(), and pin_fail_text().

CARD_SELECT_MIN

#define CARD_SELECT_MIN   8U

Shortest SELECT response this can read: flags plus the status word.

Definition at line 46 of file card_status.h.

Referenced by card_state().

Enumeration Type Documentation

card_state_t

enum card_state_t

What a tapped card is missing.

Enumerator
CARD_READY	Initialised and seeded — usable.
CARD_UNKNOWN	Nothing this can judge; carry on and let the ordinary paths report whatever goes wrong.
CARD_NO_PIN	Never initialised: no PIN, no key, nothing.
CARD_NO_KEY	Initialised, but no seed loaded — cannot sign.

Definition at line 52 of file card_status.h.

Function Documentation

card_state()

card_state_t card_state ( const uint8_t * r, size_t n )

inlinestatic

Judge a card from its SELECT response.

Parameters

[in]	r	Response bytes as the card sent them, status word included.
[in]	n	Number of bytes in r.

Returns

The state, or CARD_UNKNOWN for anything that is not a successful SELECT of a card type these flags are known to describe. Unknown is deliberately not an error: this runs in front of every card operation, and a parser that guessed would refuse a working card.

Definition at line 70 of file card_status.h.

References CARD_FLAG_PIN_SET, CARD_FLAG_SEEDED, CARD_FLAGS_OFF, CARD_NO_KEY, CARD_NO_PIN, CARD_READY, CARD_SELECT_MIN, and CARD_UNKNOWN.

Referenced by card_fault().

card_state_text()

const char * card_state_text ( card_state_t s )

inlinestatic

The line to put in front of the operator, or NULL if there is none.

Short enough for the panel's failure line and the config page's note, and it names the fix rather than the flag: whoever is holding a blank card needs to be told to set it up, not told about bit 6.

Definition at line 94 of file card_status.h.

References CARD_NO_KEY, and CARD_NO_PIN.

Referenced by card_fault().