keycard package

Subpackages

• keycard.commands package
  • Submodules
  • keycard.commands.ident module
    • ident()
  • keycard.commands.init module
    • init()
  • keycard.commands.mutually_authenticate module
    • mutually_authenticate()
  • keycard.commands.open_secure_channel module
    • open_secure_channel()
  • keycard.commands.pair module
    • pair()
  • keycard.commands.select module
    • select()
  • keycard.commands.unpair module
    • unpair()
  • keycard.commands.verify_pin module
    • verify_pin()
  • Module contents
    • APDUError
    • ApplicationInfo
      • ApplicationInfo.capabilities
      • ApplicationInfo.ecc_public_key
      • ApplicationInfo.instance_uid
      • ApplicationInfo.key_uid
      • ApplicationInfo.version_major
      • ApplicationInfo.version_minor
      • ApplicationInfo.capabilities
      • ApplicationInfo.ecc_public_key
      • ApplicationInfo.instance_uid
      • ApplicationInfo.is_initialized
      • ApplicationInfo.key_uid
      • ApplicationInfo.parse()
      • ApplicationInfo.version_major
      • ApplicationInfo.version_minor
    • CardInterface
      • CardInterface.card_public_key
      • CardInterface.is_initialized
      • CardInterface.is_pin_verified
      • CardInterface.is_secure_channel_open
      • CardInterface.is_selected
      • CardInterface.send_apdu()
      • CardInterface.send_secure_apdu()
    • DerivationOption
      • DerivationOption.CURRENT
      • DerivationOption.DERIVE
      • DerivationOption.DERIVE_AND_MAKE_CURRENT
      • DerivationOption.PINLESS
    • DerivationSource
      • DerivationSource.CURRENT
      • DerivationSource.MASTER
      • DerivationSource.PARENT
    • ECDH
      • ECDH.generate_private_key()
      • ECDH.generate_sharedsecret()
      • ECDH.generate_sharedsecret_bytes()
      • ECDH.get_public_key()
      • ECDH.load_private_key()
      • ECDH.load_private_key_bytes()
      • ECDH.load_private_key_der()
      • ECDH.load_private_key_pem()
      • ECDH.load_received_public_key()
      • ECDH.load_received_public_key_bytes()
      • ECDH.load_received_public_key_der()
      • ECDH.load_received_public_key_pem()
      • ECDH.set_curve()
    • ExportedKey
      • ExportedKey.chain_code
      • ExportedKey.has_private
      • ExportedKey.is_extended
      • ExportedKey.private_key
      • ExportedKey.public_key
    • InvalidResponseError
    • InvalidStateError
    • KeyExportOption
      • KeyExportOption.EXTENDED_PUBLIC
      • KeyExportOption.PRIVATE_AND_PUBLIC
      • KeyExportOption.PUBLIC_ONLY
    • KeyPath
      • KeyPath.MAX_COMPONENTS
      • KeyPath.to_string()
    • NotSelectedError
    • SecureChannel
      • SecureChannel.enc_key
      • SecureChannel.mac_key
      • SecureChannel.iv
      • SecureChannel.authenticated
      • SecureChannel.authenticated
      • SecureChannel.enc_key
      • SecureChannel.iv
      • SecureChannel.mac_key
      • SecureChannel.open()
      • SecureChannel.unwrap_response()
      • SecureChannel.wrap_apdu()
    • SignatureResult
      • SignatureResult.algo
      • SignatureResult.public_key
      • SignatureResult.r
      • SignatureResult.recovery_id
      • SignatureResult.s
      • SignatureResult.signature
      • SignatureResult.signature_der
    • SigningAlgorithm
      • SigningAlgorithm.BLS12_381
      • SigningAlgorithm.ECDSA_SECP256K1
      • SigningAlgorithm.EDDSA_ED25519
      • SigningAlgorithm.SCHNORR_BIP340
    • SigningKey
      • SigningKey.from_der()
      • SigningKey.from_pem()
      • SigningKey.from_secret_exponent()
      • SigningKey.from_string()
      • SigningKey.generate()
      • SigningKey.get_verifying_key()
      • SigningKey.sign()
      • SigningKey.sign_deterministic()
      • SigningKey.sign_digest()
      • SigningKey.sign_digest_deterministic()
      • SigningKey.sign_number()
      • SigningKey.to_der()
      • SigningKey.to_pem()
      • SigningKey.to_ssh()
      • SigningKey.to_string()
    • VerifyingKey
      • VerifyingKey.from_der()
      • VerifyingKey.from_pem()
      • VerifyingKey.from_public_key_recovery()
      • VerifyingKey.from_public_key_recovery_with_digest()
      • VerifyingKey.from_public_point()
      • VerifyingKey.from_string()
      • VerifyingKey.precompute()
      • VerifyingKey.to_der()
      • VerifyingKey.to_pem()
      • VerifyingKey.to_ssh()
      • VerifyingKey.to_string()
      • VerifyingKey.verify()
      • VerifyingKey.verify_digest()
    • aes_cbc_encrypt()
    • change_secret()
    • derive_key()
    • export_key()
    • factory_reset()
    • generate_key()
    • generate_mnemonic()
    • generate_pairing_token()
    • get_data()
    • get_status()
    • ident()
    • init()
    • load_key()
    • mutually_authenticate()
    • open_secure_channel()
    • pair()
    • parse()
    • remove_key()
    • require_initialized()
    • require_pin_verified()
    • require_secure_channel()
    • require_selected()
    • select()
    • set_pinless_path()
    • sigdecode_der()
    • sign()
    • store_data()
    • unblock_pin()
    • unpair()
    • urandom()
    • verify_pin()
• keycard.crypto package
  • Submodules
  • keycard.crypto.aes module
    • aes_cbc_decrypt()
    • aes_cbc_encrypt()
  • keycard.crypto.padding module
    • iso7816_pad()
    • iso7816_unpad()
  • Module contents
• keycard.parsing package
  • Submodules
  • keycard.parsing.application_info module
    • ApplicationInfo
      • ApplicationInfo.capabilities
      • ApplicationInfo.ecc_public_key
      • ApplicationInfo.instance_uid
      • ApplicationInfo.key_uid
      • ApplicationInfo.version_major
      • ApplicationInfo.version_minor
      • ApplicationInfo.capabilities
      • ApplicationInfo.ecc_public_key
      • ApplicationInfo.instance_uid
      • ApplicationInfo.is_initialized
      • ApplicationInfo.key_uid
      • ApplicationInfo.parse()
      • ApplicationInfo.version_major
      • ApplicationInfo.version_minor
  • keycard.parsing.capabilities module
    • Capabilities
      • Capabilities.SECURE_CHANNEL
      • Capabilities.KEY_MANAGEMENT
      • Capabilities.CREDENTIALS_MANAGEMENT
      • Capabilities.NDEF
      • Capabilities.CREDENTIALS_MANAGEMENT
      • Capabilities.KEY_MANAGEMENT
      • Capabilities.NDEF
      • Capabilities.SECURE_CHANNEL
      • Capabilities.parse()
  • keycard.parsing.identity module
    • parse()
  • keycard.parsing.tlv module
    • encode_tlv()
    • parse_tlv()
  • Module contents

Submodules

keycard.apdu module

This module provides classes and functions for handling APDU (Application Protocol Data Unit) responses and encoding data in LV (Length-Value) format.

class keycard.apdu.APDUResponse(data, status_word)

Bases: object

Represents a response to an APDU (Application Protocol Data Unit) command.

data

The response data returned from the APDU command.

Type:

bytes

status_word

The status word indicating the result of the APDU command.

Type:

int

data: bytes

status_word: int

keycard.apdu.encode_lv(value)

Encodes the given bytes using LV (Length-Value) encoding.

The function prepends the length of the input bytes as a single byte, followed by the value itself. The maximum supported length is 255 bytes.

Return type:

bytes

Parameters:

value (bytes) – The data to encode.

Returns:

The LV-encoded bytes.

Return type:

bytes

Raises:

ValueError – If the input exceeds 255 bytes in length.

keycard.constants module

This module defines constants used for communication with the Keycard applet via APDU commands.

class keycard.constants.DerivationOption(*values)

Bases: IntEnum

CURRENT = 0

DERIVE = 1

DERIVE_AND_MAKE_CURRENT = 2

PINLESS = 3

class keycard.constants.DerivationSource(*values)

Bases: IntEnum

CURRENT = 128

MASTER = 0

PARENT = 64

class keycard.constants.KeyExportOption(*values)

Bases: IntEnum

EXTENDED_PUBLIC = 2

PRIVATE_AND_PUBLIC = 0

PUBLIC_ONLY = 1

class keycard.constants.LoadKeyType(*values)

Bases: IntEnum

BIP39_SEED = 3

ECC = 1

EXTENDED_ECC = 2

class keycard.constants.PinType(*values)

Bases: IntEnum

PAIRING = 2

PUK = 1

USER = 0

class keycard.constants.SigningAlgorithm(*values)

Bases: IntEnum

BLS12_381 = 2

ECDSA_SECP256K1 = 0

EDDSA_ED25519 = 1

SCHNORR_BIP340 = 3

class keycard.constants.StorageSlot(*values)

Bases: IntEnum

CASH = 2

NDEF = 1

PUBLIC = 0

keycard.exceptions module

exception keycard.exceptions.APDUError(sw)

Bases: KeyCardError

Raised when APDU returns non-success status word.

exception keycard.exceptions.InvalidResponseError

Bases: KeyCardError

Raised when response parsing fails.

exception keycard.exceptions.InvalidStateError(message)

Bases: KeyCardError

Raised when a precondition is not met.

exception keycard.exceptions.KeyCardError

Bases: Exception

Base exception for Keycard SDK

exception keycard.exceptions.NotInitializedError

Bases: KeyCardError

Raised when trying to use card public key before select().

exception keycard.exceptions.NotSelectedError

Bases: KeyCardError

Raised when trying to use card before select().

exception keycard.exceptions.TransportError

Bases: KeyCardError

Raised there are no readers

keycard.keycard module

class keycard.keycard.KeyCard(transport=None)

Bases: CardInterface

High-level interface for interacting with a Keycard device.

This class provides convenient methods to manage pairing, secure channels, and card operations.

change_pairing_secret(new_value)

Changes the pairing secret on the card.

Return type:

None

Parameters:

new_value (str) – The new pairing secret value to set.

Raises:

• ValueError – If input format is invalid.

• APDUError – If the response status word is not 0x9000.

change_pin(new_value)

Changes the user PIN on the card.

Return type:

None

Parameters:

new_value (str) – The new PIN value to set.

Raises:

• ValueError – If input format is invalid.

• APDUError – If the response status word is not 0x9000.

change_puk(new_value)

Changes the PUK on the card.

Return type:

None

Parameters:

new_value (str) – The new PUK value to set.

Raises:

• ValueError – If input format is invalid.

• APDUError – If the response status word is not 0x9000.

derive_key(path='')

Set the derivation path for subsequent SIGN and EXPORT KEY commands.

Return type:

None

Parameters:

path (str) – BIP-32-style path (e.g., “m/44’/60’/0’/0/0”) or “../0/1” (parent) or “./0” (current).

export_current_key(public_only=False)

Exports the current key from the card.

This is a convenience method that uses the CURRENT derivation option and does not require a keypath.

Return type:

ExportedKey

Parameters:

public_only (bool) – If True, only the public key will be returned.

Returns:

An object containing the public key, and optionally

the private key and chain code.

Return type:

ExportedKey

export_key(derivation_option, public_only, keypath=None, make_current=False, source=DerivationSource.MASTER)

Export a key from the card.

This is a proxy for keycard.commands.export_key(), provided here for convenience.

Return type:

ExportedKey

Parameters:

• derivation_option – One of the derivation options (CURRENT, DERIVE, DERIVE_AND_MAKE_CURRENT).

• public_only – If True, only the public key will be returned.

• keypath – BIP32-style string (e.g. “m/44’/60’/0’/0/0”) or packed bytes. If derivation_option is CURRENT, this can be omitted.

• make_current – If True, updates the card’s current derivation path.

• source – Which node to derive from: MASTER, PARENT, or CURRENT.

Returns:

An object containing the public key, and optionally

the private key and chain code.

Return type:

ExportedKey

See also

• keycard.commands.export_key() - for the lower-level

  implementation

• keycard.types.ExportedKey - return value

  structure

factory_reset()

Sends the FACTORY_RESET command to the card.

Return type:

None

Raises:

APDUError – If the card returns a failure status word.

generate_key()

Generates a new key on the card and returns the key UID.

Return type:

bytes

Returns:

Key UID (SHA-256 of the public key)

Return type:

bytes

Raises:

APDUError – If the response status word is not 0x9000

generate_mnemonic(checksum_size=6)

Generate a BIP39 mnemonic using the card’s RNG.

Return type:

list[int]

Parameters:

checksum_size (int) – Number of checksum bits (between 4 and 8 inclusive).

Returns:

List of integers (0-2047) corresponding to wordlist

indexes.

Return type:

List[int]

get_data(slot=StorageSlot.PUBLIC)

Gets the data on the card previously stored with the store data command in the specified slot.

Return type:

bytes

Parameters:

slot (StorageSlot) – Where to retrieve the data (PUBLIC, NDEF, CASH)

Raises:

ValueError – If slot is invalid or data is too long.

property get_key_path: dict[str, int | bool] | list[int]

Returns the current key derivation path from the card.

Returns:

List of 32-bit integers representing the key path.

Return type:

list of int

Raises:

RuntimeError – If the secure session is not open.

ident(challenge=None)

Sends an identity challenge to the card.

Return type:

bytes

Parameters:

challenge (bytes) – A challenge (nonce or data) to send to the card. If None, a random 32-byte challenge is generated.

Returns:

The public key extracted from the card’s identity response.

Return type:

bytes

init(pin, puk, pairing_secret)

Initializes the card with security credentials.

Return type:

None

Parameters:

• pin (bytes) – The PIN code in bytes.

• puk (bytes) – The PUK code in bytes.

• pairing_secret (bytes) – The shared secret for pairing.

property is_initialized: bool

Checks if the Keycard is initialized.

Returns:

True if the Keycard is initialized, False otherwise.

Return type:

bool

property is_pin_verified: bool

Checks if the user PIN has been verified.

Returns:

True if the PIN is verified, False otherwise.

Return type:

bool

property is_secure_channel_open: bool

Checks if a secure channel is currently open.

Returns:

True if a secure channel is established, False otherwise.

Return type:

bool

property is_selected: bool

Checks if a card is selected and has a public key.

Returns:

True if a card is selected, False otherwise.

Return type:

bool

property is_session_open: bool

Checks if a secure session is currently open.

Returns:

True if a secure session is established, False otherwise.

Return type:

bool

load_key(key_type, public_key=None, private_key=None, chain_code=None, bip39_seed=None)

Load a key into the card for signing purposes.

Return type:

bytes

Parameters:

• key_type – Key type

• public_key – Optional ECC public key (tag 0x80).

• private_key – ECC private key (tag 0x81).

• chain_code – Optional chain code (tag 0x82, only for extended key).

• bip39_seed – 64-byte BIP39 seed (only for key_type=BIP39_SEED).

Returns:

UID of the loaded key (SHA-256 of public key).

mutually_authenticate()

Performs mutual authentication between host and card.

Return type:

None

Raises:

APDUError – If the authentication fails.

open_secure_channel(pairing_index, pairing_key, mutually_authenticate=True)

Opens a secure session with the card.

Return type:

None

Parameters:

• pairing_index (int) – Index of the pairing slot to use.

• pairing_key (bytes) – The shared pairing key (32 bytes).

• mutually_authenticate (bool) – Execute mutually authenticate when a secure channel has been opened

pair(shared_secret)

Pairs with the card using an ECDH-derived shared secret.

Return type:

tuple[int, bytes]

Parameters:

shared_secret (bytes) – 32-byte ECDH shared secret.

Returns:

The pairing index and client cryptogram.

Return type:

tuple[int, bytes]

remove_key()

Removes the current key from the card.

Return type:

None

Raises:

APDUError – If the response status word is not 0x9000.

select()

Selects the Keycard applet and retrieves application metadata.

Return type:

ApplicationInfo

Returns:

Object containing ECC public key and card info.

Return type:

ApplicationInfo

send_apdu(ins, p1=0, p2=0, data=b'', cla=None)

Return type:

bytes

send_secure_apdu(ins, p1=0, p2=0, data=b'')

Return type:

bytes

set_pinless_path(path)

Set a PIN-less path on the card. Allows signing without PIN/auth if the current derived key matches this path.

Return type:

None

Parameters:

path (str) – BIP-32-style path (e.g., “m/44’/60’/0’/0/0”). An empty string disables the pinless path.

sign(digest)

Sign using the currently loaded keypair. Requires PIN verification and secure channel.

Return type:

SignatureResult

Parameters:

digest (bytes) – 32-byte hash to sign

Returns:

Parsed signature result, including the signature

(DER or raw), algorithm, and optional recovery ID or public key.

Return type:

SignatureResult

sign_pinless(digest)

Sign using the predefined PIN-less path. Does not require secure channel or PIN.

Return type:

SignatureResult

Parameters:

digest (bytes) – 32-byte hash to sign

Returns:

Parsed signature result, including the signature

(DER or raw), algorithm, and optional recovery ID or public key.

Return type:

SignatureResult

Raises:

APDUError – if no PIN-less path is set

sign_with_path(digest, path, make_current=False)

Sign using a derived keypath. Optionally updates the current path.

Return type:

SignatureResult

Parameters:

• digest (bytes) – 32-byte hash to sign

• path (list[int]) – list of 32-bit integers

• make_current (bool) – whether to update current path on card

Returns:

Parsed signature result, including the signature

(DER or raw), algorithm, and optional recovery ID or public key.

Return type:

SignatureResult

property status: dict[str, int | bool] | list[int]

Retrieves the application status using the secure session.

Returns:

A dictionary with:

• pin_retry_count (int)

• puk_retry_count (int)

• initialized (bool)

Return type:

dict

Raises:

RuntimeError – If the secure session is not open.

store_data(data, slot=StorageSlot.PUBLIC)

Stores data on the card in the specified slot.

Return type:

None

Parameters:

• data (bytes) – The data to store (max 127 bytes).

• slot (StorageSlot) – Where to store the data (PUBLIC, NDEF, CASH)

Raises:

ValueError – If slot is invalid or data is too long.

unblock_pin(puk, new_pin)

Unblocks the user PIN using the provided PUK and sets a new PIN.

Return type:

None

Parameters:

puk_and_pin (str | bytes) – Concatenation of PUK (12 digits) + new PIN (6 digits)

Raises:

• ValueError – If the format is invalid.

• APDUError – If the card returns an error.

unpair(index)

Removes a pairing slot from the card.

Return type:

None

Parameters:

index (int) – Index of the pairing slot to remove.

verify_pin(pin)

Verifies the user PIN with the card.

Return type:

bool

Parameters:

pin (str) – The user-entered PIN.

Returns:

True if PIN is valid, otherwise False.

Return type:

bool

keycard.transport module

class keycard.transport.Transport

Bases: object

connect(index=0)

Return type:

None

disconnect()

Return type:

None

send_apdu(apdu)

Return type:

APDUResponse

Module contents

Python SDK for interacting with Status Keycard.