cryptnox-id-cli 1.0.2

cryptnox-id-cli

CLI for managing Cryptnox multi-applet ID smart cards

cryptnox-id-cli is a command-line interface for managing the Cryptnox ID multi-applet smart card: PIV identity credentials, FIDO2 passkeys, and MIFARE DESFire contactless applications — three independent functions on one physical card, driven by one tool.

Supported hardware

Cryptnox ID smart cards

One card, four applets, reachable over two interfaces:

Smart card readers

Works with Cryptnox readers and any other standard PC/SC smart card reader:

Verified third-party readers: ACS ACR39U (contact), ACS ACR1252 (contactless, native DESFire OK). The HID OMNIKEY 5422CL does not support DESFire.

[!IMPORTANT] MIFARE DESFire requires a contactless reader that passes native DESFire commands — not all contactless readers do.

Installation

[!IMPORTANT] This is only a minimal setup. Additional packages may be required depending on your operating system. See Installation in the documentation.

Requirements: Python 3.10+ and a PC/SC stack (built into Windows and macOS; on Linux install pcscd + libccid).

From PyPI

Recommended: pipx — makes cryptnox-id available globally while keeping its dependencies isolated, and works on current Linux distributions where installing into the system Python is blocked (PEP 668):

pipx install cryptnox-id-cli

Plain pip also works where the environment allows it (e.g. Windows):

pip install cryptnox-id-cli

A virtual environment works too, but the command is then only available while the venv is activated — fine for development, not for day-to-day use.

Three interchangeable console commands are installed: cryptnox-id, the short cnx-id, and cryptnox-id-card.

From source

git clone https://github.com/cryptnox/cryptnox-id-cli.git
cd cryptnox-id-cli
pip install .

Quick usage examples

[!TIP] The examples below are only a subset of available commands. The complete list of commands and detailed usage instructions is described in the official documentation.

1. Inspect the card

cryptnox-id readers     # list readers, card presence, ATR
cryptnox-id info        # detect the card + all functions on one screen
cryptnox-id doctor      # PC/SC service, reader, per-function reachability

info and doctor are read-only and safe to run any time.

2. Provision a PIV credential

1. Run cryptnox-id piv quickstart on a contact reader.
2. The card gets a key, a certificate, a CHUID and a CCC — usable by standard PIV tooling (yubico-piv-tool, OpenSC, OS smart-card stacks).

3. Create a passkey and prove the whole loop

1. Run cryptnox-id fido credential self-test — registers a credential, requests an assertion, and verifies the returned signature: the full WebAuthn round trip against the real authenticator.
2. For a resident, PIN-verified credential: cryptnox-id fido pin set, then re-run the self-test with --rk. On Windows, run from an Administrator terminal.

4. Prove the card is genuine

1. Run cryptnox-id genuine verify on a contact reader.
2. The card signs a fresh nonce and the on-card certificate is chained to the pinned Cryptnox root — the verdict is GENUINE only when both checks pass.

5. Work interactively

cryptnox-id shell       # run subcommands without re-typing the prefix

Documentation

The full User & Developer documentation is available at the Cryptnox ID CLI Documentation. It covers installation and setup, quick starts and usage guides for every card function (PIV, FIDO2, MIFARE DESFire, genuineness), the complete CLI command reference, JSON output and exit codes, and factory/provisioning notes.

Development

pip install -e ".[dev]"
ruff check src tests && ruff format --check src tests
mypy
pytest -q -m "not real_card"

Unit tests use a mock transport — no reader or card required. Real-card tests are opt-in (-m real_card) and never run in CI.

License

cryptnox-id-cli is dual-licensed:

• LGPL-3.0 for open-source projects and proprietary projects that comply with LGPL requirements (see LICENSE)
• Commercial license for projects that require a proprietary license without LGPL obligations (see COMMERCIAL.md for details)

The documentation is licensed CC BY-NC-ND 4.0.

For commercial inquiries, contact: contact@cryptnox.com