Getting started

First contact with the card:

$ cryptnox-id readers       # which reader to use (note the --reader hint)
$ cryptnox-id info          # all three functions on one screen
$ cryptnox-id doctor        # if anything looks off

info and doctor are read-only and safe to run any time. doctor exits with code 2 if a blocking check fails (useful in scripts); FIDO/DESFire warnings on a contact or non-elevated setup are not blocking.

Then pick your path: Quick start: a working PIV card, Quick start: a tamper-evident NFC tag (SDM/SUN) or Quick start: a passkey on the card.

Choosing a reader

Every command talks to exactly one reader.

  • Default (no ``–reader``) — the tool picks the single Cryptnox or ACS reader that has a card. This is deliberate: it avoids touching another project’s card in some other reader.

  • If there is no Cryptnox/ACS reader, or several readers with cards, the tool refuses to guess and asks you to pass --reader.

  • ``–reader <index>`` — the number from cryptnox-id readers (e.g. --reader 0).

  • ``–reader <name>`` — a case-insensitive substring of the reader name (e.g. --reader CryptnoxCR, --reader ACR39, --reader PICC); an ambiguous substring is an error.

Two things to know:

  • Virtual readers such as “Windows Hello for Business” show up in readers — ignore them; they are not Cryptnox cards.

  • The same physical card over a contact vs a contactless reader exposes different applets. If PIV looks present but MIFARE does not, you are on a contact reader — and vice versa. Reader names also differ per unit and OS/driver (PICC = contactless, ICC / ACR39U = contact; some Cryptnox units report CryptnoxCR / Cryptnox NFC instead), so prefer selecting by name substring.

A bench with both a contact and a contactless reader loaded:

$ cryptnox-id readers
#  0 | ACS ACR39U ICC Reader 0 (ACS) | present | 3B...     <- contact
#  1 | Feitian R502 0                | present | 3B...     <- contactless
$ cryptnox-id --reader 0 piv info        # PIV over contact
$ cryptnox-id --reader 1 mifare info     # DESFire over contactless

Global options

These sit before the command and apply to it:

Option

Meaning

--reader <name|index>

Select the PC/SC reader (default: the ACS reader with a card).

--json

Machine-readable JSON to stdout; diagnostics go to stderr.

--verbose

Human debug output; a redacted APDU trace to stderr.

--apdu-log <file>

Append a redacted APDU transcript to a file.

--dry-run

Write nothing to the card. Commands that can plan (piv quickstart, apdu, factory, the key imports) show the intended actions; every other command refuses to run under the flag rather than executing for real (fail-closed).

--yes

Skip destructive confirmation prompts.

--timeout <seconds>

Reader/card timeout.

--no-color

Disable coloured output.

One card operation at a time

Each cryptnox-id invocation opens the reader, does one thing, and releases it. Admin and personalization commands each open their own SCP03 session (this card accepts one application APDU per applet-directed session), so there is nothing to “keep open” between commands. For a running prompt that issues many commands in a row without re-typing the prefix, use the interactive shell (cryptnox-id shell).

Development keys

Warning

Cards ship with well-known default keys so that the first personalization works out of the box, and the examples in this documentation use them too:

  • PIV admin channel (SCP03) — key version 1 of the card’s PIV security domain (A00000015153504101) holds the published GlobalPlatform test key 40 41 42 … 4F (--default-keys). The card manager (ISD) is a separate domain with per-card keys that the CLI never uses;

  • PIV management key (9B) — the same published GlobalPlatform test value, doubled for an AES-256 key object (--default-keys);

  • DESFire application keys after app create — all-zero AES (--zero-key);

  • PIV PIN / PUK in the examples — 123456 / 12345678.

These are not secrets — they are public, published values. A production deployment must replace them. The environment variables only authenticate with keys that are already on the card; putting new admin keys on the card is a separate step, see Rotating the PIV admin keys. After it, the admin channel takes PIV_SCP03_ENC / PIV_SCP03_MAC / PIV_SCP03_DEK; PIV_MGMT_KEY carries the PIV management key, CRYPTNOX_PIV_PIN / CRYPTNOX_PIV_NEW_PIN / CRYPTNOX_PIV_NEW_PUK the PINs and PUKs, and DESFire keys use the --key-env NAME form.

Next