Cryptnox SDK Python Overview

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 Cards, including initialization, secure channel setup, seed management, and cryptographic signing.

Supported Hardware

Cryptnox smart cards 💳
Standard PC/SC smart card readers: either USB NFC reader or a USB smart card reader

Get your cards and readers here: shop.cryptnox.com

Features

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

Installation

From PyPI

pip install cryptnox_sdk_py

From source

git clone https://github.com/cryptnox/cryptnox-sdk-py.git
cd cryptnox-sdk-py
pip install .

Requirements

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 pcscd

Quick Usage Examples

1. Connect to a Cryptnox Card

import 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()

2. Test PIN code

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()

3. Generate a new seed

In the example below the card must be initialized 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()

Documentation

📚 Full API reference: https://cryptnox.github.io/cryptnox-sdk-py/

License

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