Python SDK for managing Cryptnox Hardware Wallet smart cards
cryptnox_sdk_py is a Python 3 library used to communicate with the Cryptnox Smartcard Applet.
It provides a high-level API to manage Cryptnox Hardware Wallet smart cards, including initialization,
secure channel setup, seed management, and cryptographic signing.
Works with Cryptnox Hardware Wallet smart cards running firmware v1.6.0 or later.
| Smart card | Wallet version |
|---|---|
| Crypto Hardware Wallet – Dual Card Set | v1.6.1 |
Works with Cryptnox readers and any other standard PC/SC smart card reader:
| Reader | Type | Interface |
|---|---|---|
| Cryptnox® Smartcard Reader | Contact (ID-1 + SIM) | USB-A |
| Compact USB Mini Smartcard Reader | Contact (ID-1) | USB-A |
| Cryptnox NFC Contactless Reader | Contactless (NFC/ISO 14443) | USB-C |
- Establish communication with Cryptnox smart cards
- Initialize and manage card lifecycle
- Secure channel authentication and pairing
- Seed generation and restoration (BIP32 / BIP39 compatibility)
- ECDSA secp256k1 signing for blockchain applications
pip install cryptnox_sdk_pyOr from source:
git clone https://github.com/cryptnox/cryptnox-sdk-py.git
cd cryptnox-sdk-py
pip install .Requires:
- Python 3.11 – 3.13.7
- PC/SC Smart Card service (
pcscd) on Linux
On Linux, ensure the PC/SC service is running:
sudo systemctl start pcscd
sudo systemctl enable pcscdimport cryptnox_sdk_py
from cryptnox_sdk_py import exceptions
connection = None
try:
connection = cryptnox_sdk_py.Connection(0)
card = cryptnox_sdk_py.factory.get_card(connection)
# Card is loaded and can be used
print(f"Card serial number: {card.serial_number}")
except exceptions.ReaderException:
print("Reader not found at index")
except exceptions.CryptnoxException as error:
# Issue loading the card
print(error)
finally:
# Always close the connection when done
if connection:
connection.disconnect()In the PIN verification example below the card must be initialized before calling verify_pin.
import cryptnox_sdk_py
from cryptnox_sdk_py import exceptions
connection = None
try:
# Connect to the Cryptnox card first
connection = cryptnox_sdk_py.Connection(0) # Connect to card at index 0
card = cryptnox_sdk_py.factory.get_card(connection)
# Once connected, verify the PIN
pin_to_test = "1234" # Example PIN
card.verify_pin(pin_to_test)
print("PIN verified successfully. Card is ready for operations.")
except exceptions.ReaderException:
print("Reader not found at index")
except exceptions.CryptnoxException as error:
print(f"Error loading card: {error}")
except exceptions.PinException:
print("Invalid PIN code.")
except exceptions.DataValidationException:
print("Invalid PIN length or PIN authentication disabled.")
except exceptions.SoftLock:
print("Card is locked. Please power cycle the card.")
finally:
# Always close the connection when done
if connection:
connection.disconnect()In the example below the card must be init before generating a seed.
import binascii
import cryptnox_sdk_py
from cryptnox_sdk_py import exceptions
PIN = "1234" # or "" if the card was opened via challenge-response
def main():
connection = None
try:
connection = cryptnox_sdk_py.Connection(0)
card = cryptnox_sdk_py.factory.get_card(connection)
seed_uid = card.generate_seed(PIN)
# seed_uid is of type bytes: display in hex for readability
print("Seed (primary node m) UID:", binascii.hexlify(seed_uid).decode())
except exceptions.ReaderException:
print("Reader not found at index")
except exceptions.CryptnoxException as err:
print(f"Error loading card: {err}")
except exceptions.KeyAlreadyGenerated:
print("A seed is already generated on this card.")
except exceptions.KeyGenerationException as err:
print(f"Failed to generate seed: {err}")
finally:
# Always close the connection when done
if connection:
connection.disconnect()
if __name__ == "__main__":
main()📚 Full API reference: https://cryptnox.github.io/cryptnox-sdk-py/
The project includes automatically generated class diagrams in the documentation.
Quick Start:
# Install dependencies
pip install -r dev-requirements.txt
# Install Graphviz (required for diagrams)
# Windows: Download from https://graphviz.org/download/
# macOS: brew install graphviz
# Linux: sudo apt-get install graphviz
# Build documentation
cd docs
sphinx-build -b html . _build/htmlDocumentation Guides:
- Developer Guide: docs/DEVELOPER_GUIDE_DIAGRAMS.md
cryptnox-sdk-py is dual-licensed:
- LGPL-3.0 for open-source projects and proprietary projects that comply with LGPL requirements
- Commercial license for projects that require a proprietary license without LGPL obligations (see COMMERCIAL.md for details)
For commercial inquiries, contact: contact@cryptnox.com
