cryptnoxpy.card.base

Module for keeping information about the card attached to the reader

Module Contents

Classes

Base

Object that contains information about the card that is in the reader.

Attributes

User

cryptnoxpy.card.base.User
class cryptnoxpy.card.base.Base(connection: cryptnoxpy.connection.Connection, data: List[int] = None, debug: bool = False)

Object that contains information about the card that is in the reader.

Parameters
  • connection (Connection) – Connection to use for card initialization

  • debug (bool) – Show debug information to the user.

Variables
  • applet_version (List[int]) – Version of the applet on the card.

  • serial_number (int) – Serial number of card.

  • session_public_key (str) – Public key of the session.

  • initialized (bool) – The card has been initialized with secrets.

Raises

CardTypeException – The card in the reader is not a Cryptnox card

_ALGORITHM
PUK_LENGTH = 15
property select_apdu List[int]
Returns

Value to add to select command to select the applet on the card

Return type

List[int]

property type int
Returns

Card type

Return type

int

property pin_rule str

Human readable PIN code rule

Returns

Human readable PIN code rule

Return type

str

property puk_rule str

Human readable PUK code rule

Returns

Human readable PUK code rule

Return type

str

property alive(self) bool
Returns

The connection to the card is established and the card hasn’t been changed

Return type

bool

abstract change_pairing_key(self, index: int, pairing_key: bytes, puk: str = '') None

Set the pairing key of the card

Parameters
  • index (int) – Index of the pairing key

  • pairing_key (bytes) – Pairing key to set for the card

  • puk (str) – PUK code of the card

Raises
abstract change_pin(self, new_pin: str) None

Change the current pin code of the card to a new pin code.

The method will set the given pin code as the pin code of the card. For it to work the card first must be opened with the current pin code.

Requires
  • PIN code or challenge-response validated

Parameters

new_pin (str) – The desired PIN code to be set for the card (4-9 digits).

abstract change_puk(self, current_puk: str, new_puk: str) None

Change the current pin code of the card to a new pin code.

The method will set the given pin code as the pin code of the card. For it to work the card first must be opened with the current pin code.

Parameters
  • current_puk (str) – The current PUK code of the card

  • new_puk (str) – The desired PUK code to be set for the card

check_init(self) None

Check if the initialization has been done on the card.

It can be useful to check if the card is initialized before doing anything else, like asking for pin code from the user.

Raises

InitializationException – The card is not initialized

abstract derive(self, key_type: cryptnoxpy.enums.KeyType = KeyType.K1, path: str = '')

Derive key on path and make it the current key in the card

Requires
  • PIN code or challenge-response validated

  • Seed must exist

Parameters
  • key_type (KeyType) – Key type to do derive on

  • path (str) – Path on which to do derivation

abstract dual_seed_public_key(self, pin: str = '') bytes

Get the public key from the card for dual initialization of the cards

Requires
  • PIN code or challenge-response validated

Parameters

pin (str) – PIN code of card if it was opened with a PIN check

Returns

Public key and signature that can be sent into the other card

Return type

bytes

Raises

DataException – The received data is invalid

abstract dual_seed_load(self, data: bytes, pin: str = '') None

Load public key and signature from the other card into the card to generate same seed.

Requires
  • PIN code or challenge-response validated

Parameters
  • pin (str) – PIN code of card if it was opened with a PIN check

  • data (bytes) – Public key and signature of public key from the other card

property extended_public_key(self) bool
Returns

Extended public key turned on

Return type

bool

abstract generate_random_number(self, size: int) bytes

Generate random number on the car and return it.

Parameters

size (int) – Output data size in bytes (between 16 and 64, mod 4)

Returns

Random number generated by the chip

Return type

bytes

Raises

DataValidationException – size in not a number between 16 and 64 or is not divisible by 4

abstract generate_seed(self, pin: str = '') bytes

Generate a seed directly on the card.

Requires
  • PIN code or challenge-response validated

Parameters

pin (str, optional) – PIN code of the card. Can be empty if card is opened with challenge-response validation

Returns

Primary node “m” UID (hash of public key)

Return type

bytes

Raises
abstract get_public_key(self, derivation: cryptnoxpy.enums.Derivation, key_type: cryptnoxpy.enums.KeyType = KeyType.K1, path: str = '', compressed: bool = True) str

Get the public key from the card.

Requires
  • PIN code or challenge-response validated, except for PIN-less path

  • Seed must exist

Parameters
  • derivation (Derivation) – Derivation to use.

  • key_type (KeyType) – Key type to use

  • path (str) –

  • compressed (bool) – The returned value is in compressed format.

Returns

The public key for the given path in hexadecimal string format

Return type

str

Raises
abstract history(self, index: int = 0) NamedTuple

Get history of hashes the card has signed regardless of any parameters given to sign

Requires
  • PIN code or challenge-response validated

Parameters

index (int) – Index of entry in history

Returns

Return entry containing signing_counter, representing index of sign call, and hashed_data, the data that was signed

Return type

NamedTuple

property info(self) Dict[str, Any]

Get relevant information about the card.

Returns

Dictionary containing information for the card

Return type

Dict[str, Any]

abstract init(self, name: str, email: str, pin: str, puk: str, pairing_secret: bytes) bytes

Initialize the Cryptnox card.

Initialize the Cryptnox card with the owners name and email address. Set the PIN and PUK codes for authenticating with the card to be able to use it.

Parameters
  • name (str) – Name of the card owner

  • email (str) – Email of the card owner

  • pin (str) – PIN code that will be used to open the card

  • puk (str) – PUK code that will be used to open the card

  • pairing_secret (bytes) – Pairing secret to use with the card

Returns

Pairing secret

Return type

bytes

Raises

InitializationException – There was an issue with initialization

property initialized(self) bool
Returns

Whether the card is initialized

Return type

bool

abstract load_seed(self, seed: bytes, pin: str = '') None

Load the given seed into the Cryptnox card.

Requires
  • PIN code or challenge-response validated

Parameters
  • seed (bytes) – Seed to initialize the card with

  • pin (str, optional) – PIN code of the card. Can be empty if card is opened with challenge-response validation

Raises

KeyGenerationException – Data is not correct

property open(self) bool
Returns

Whether the user has authenticated using the PIN code or challenge-response validation

Return type

bool

property pin_authentication(self) bool
Returns

Whether the PIN code can be used for authentication

Return type

bool

property pinless_enabled(self) bool
Returns

Return whether the card has a pinless path

Return type

bool

abstract reset(self, puk: str) None

Reset the card and return it to factory settings.

Parameters

puk – PUK code associated with the card

property seed_source(self) cryptnoxpy.enums.SeedSource
Returns

How the seed was generated

Return type

SeedSource

abstract set_pin_authentication(self, status: bool, puk: str) None

Turn on/off authentication with the PIN code. Other methods can still be used.

Parameters
  • status (bool) – Status of PIN authentication

  • puk (str) – PUK code associated with the card

Raises
abstract set_pinless_path(self, path: bytes, puk: str) None

Enable working with the card without a PIN on path.

Parameters
  • path (bytes) – Path to be available without a PIN code

  • puk (str) – PUK code of the card

Raises
abstract set_extended_public_key(self, status: bool, puk: str) None

Turn on/off extended public key output.

Requires
  • Seed must be loaded

Parameters
  • status (bool) – Status of PIN authentication

  • puk (str) – PUK code associated with the card

Raises
abstract sign(self, data: bytes, derivation: cryptnoxpy.enums.Derivation, key_type: cryptnoxpy.enums.KeyType = KeyType.K1, path: str = '', pin: str = '', filter_eos: bool = False) bytes

Sign the message using given derivation.

Requires
  • PIN code provided, authenticate with user key by signing same message or PIN-less path used

  • Seed must be loaded

Parameters
  • data (bytes) – Data to sign

  • derivation (Derivation) – Derivation to use.

  • key_type (KeyType, optional) – Key type to use. Defaults to K1

  • path (str, optional) – Path of the key. If empty use main key

  • pin (str, optional) – PIN code of the card

  • filter_eos (str, optional) – Filter signature so it is valid for EOS network, might take longer. Defaults to False

Returns

The signature generated by the card in DER common format.

Return type

bytes

Raises

DataException – Invalid data received during signature

property signing_counter(self) int
Returns

Counter of how many times the card has been used to sign

Return type

int

unblock_pin(self, puk: str, new_pin: str) None

Verifies the user using the PUK code and sets a new PIN code on the card.

Method should be used when the user has forgotten this/hers PIN code. By entering the PUK code the user verifies his/hers identity and can set the new PIN code on the card. Can be used only if the card is locked.

Requires
  • User PIN must be locked

  • PIN code authentication must be enabled

Parameters
  • puk (str) – PUK code for verification of the user, before changing the PIN code.

  • new_pin (str) – The desired PIN code to be set for the card (4-9 digits).

Raises
property user_data(self) bytes
Returns

Read user data that was written into the card.

Return type

bytes

abstract user_key_add(self, slot: cryptnoxpy.enums.SlotIndex, data_info: str, public_key: bytes, puk_code: str, cred_id: bytes = b'') None

Add user public key into the card for user authentication

Parameters
  • slot (int) – Slot to write the public key to 1 - EC256R1 2 - RSA key, 2048 bits, public exponent must be 65537 3 - FIDO key

  • data_info (bytes) – 64 bytes of user data

  • public_key (bytes) – Public key of the secure element to be used for authentication

  • puk_code (str) – PUK code of the card

  • cred_id (bytes, optional) – Cred id. Used for FIDO2 authentication

Raises

DataValidationException – Invalid input data

abstract user_key_delete(self, slot: cryptnoxpy.enums.SlotIndex, puk_code: str) None

Delete the user key from slot and free up for insertion

Parameters
  • slot (SlotIndex) – Slot to remove the key from

  • puk_code (str) – PUK code of the card

Raises

DataValidationException – Invalid input data

abstract user_key_info(self, slot: cryptnoxpy.enums.SlotIndex) Tuple[str, str]

Get the description and public key of the user key

Requires
  • PIN code or challenge-response validated

Parameters

slot (SlotIndex) – Index of slot for which to fetch the description

Returns

Description and public key in slot

Return type

tuple[str, str]

abstract user_key_enabled(self, slot_index: cryptnoxpy.enums.SlotIndex) bool

Check if user key is present in given slot

Parameters

slot_index (SlotIndex) – Slot index to check for

Returns

Whether the user key for slot is present

Return type

bool

abstract user_key_challenge_response_nonce(self) bytes

Get 32 bytes random value from the card that is used to open the card with a user key

Take nonce value from the card. Sign it with a third party application, like TPM. Send the signature back into the card using user_key_challenge_response_open()

Returns

32 bytes random value used as nonce

Return type

bytes

abstract user_key_challenge_response_open(self, slot: cryptnoxpy.enums.SlotIndex, signature: bytes) bool

Send the nonce signature to the card to open it for operations, like it was opened by a PIN code

Parameters
  • slot (SlotIndex) – Slot to use to open the card

  • signature (bytes) – Signature generated by a third party like TPM.

Returns

Whether the challenge response authentication succeeded

Return type

bool

Raises

DataValidationException – invalid input data

abstract user_key_signature_open(self, slot: cryptnoxpy.enums.SlotIndex, message: bytes, signature: bytes) bool

Used for opening the card to sign the given message

Parameters
  • slot (SlotIndex) – Slot to use to open the card

  • message (bytes) – Message that will be sent to sign operation

  • signature (bytes) – Signature generated by a third party, like TPM, on the same message

Returns

Whether the challenge response authentication succeeded

Return type

bool

Raises

DataValidationException – invalid input data

property valid_key(self) bool

Check if the card has a valid key

Returns

Whether the card has a valid key.

Return type

bool

abstract static valid_pin(pin: str, pin_name: str = 'pin') str

Check if provided pin is valid

Parameters
  • pin (str) – The pin to check if valid

  • pin_name (str) – Value used in DataValidationException for pin name

Return str

Provided pin in str format if valid

Raises

DataValidationException – Provided pin is not valid

abstract static valid_puk(puk: str, puk_name: str = 'puk') str

Check if provided puk is valid

Parameters
  • puk (str) – The puk to check if valid

  • puk_name (str, optional) – Value used in DataValidationException for puk name. Defaults to: puk

Return str

Provided puk in str format if valid

Raises

DataValidationException – Provided puk is not valid

abstract verify_pin(self, pin: str) None

Check PIN code and open the card for operations that are protected.

The method is sending the PIN code to the card to open it for other operations. If there is an issue an exception will be raised.

Parameters

pin (str) – PIN code to check against the card.

Raises
property _owner(self) User

Get the available information about the owner of the card from the card

When the card is initialized the owner name and email address are stored on the card. This method will read and return them.

Returns

A dictionary containing the owner name and email address

Return type

Dict[str, str]

Raises
  • CryptnoxCard.PinException – PIN code wasn’t validated.

  • CryptnoxCard.SecureChannelException – Secure channel not opened.

classmethod __subclasshook__(cls, c)

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__repr__(self)

Return repr(self).