cryptnoxpy.card.base
¶
Module for keeping information about the card attached to the reader
Module Contents¶
Classes¶
Object that contains information about the card that is in the reader. |
Attributes¶
- 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
DataValidationException – input data is not valid
SecureChannelException – operation not allowed
PukException – PUK code is not valid
- 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
KeyGenerationException – There was an issue with generating the key
KeyAlreadyGenerated – The card already has a seed generated
- 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
DerivationSelectionException – Card is not initialized with seed
ReadPublicKeyException – Invalid data received from card
- 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
- 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
DataValidationException – input data is not valid
PukException – PUK code is not valid
- 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
DataValidationException – input data is not valid
PukException – PUK code is not valid
- 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
DataValidationException – input data is not valid
PukException – PUK code is not valid
KeyException – Seed not found
- 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
PukException – PUK code not valid
CardNotBlocked – Card is not blocked, operation can’t be done
- 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
PinException – Invalid PIN code
DataValidationException – Invalid length or PIN code authentication disabled
SoftLock – The card has been locked and needs power cycling before it can be used again
- 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).