yubikit.core.smartcard

Submodules

• yubikit.core.smartcard.scp

Attributes

INS_EXTERNAL_AUTHENTICATE
INS_SELECT
P1_SELECT
P2_SELECT
INS_SEND_REMAINING
SHORT_APDU_MAX_CHUNK
SW1_HAS_MORE_DATA

Exceptions

ApplicationNotAvailableError	The application is either disabled or not supported on this YubiKey
BadResponseError	Invalid response data from the YubiKey
CommandError	An error response from a YubiKey
NotSupportedError	Attempting an action that is not supported on this YubiKey
ApduError	Thrown when an APDU response has the wrong SW code

Classes

LOG_LEVEL	Enum where members are also (and must be) ints
TRANSPORT	YubiKey physical connection transports.
USB_INTERFACE	YubiKey USB interface identifiers.
Connection	A connection to a YubiKey
Version	3-digit version tuple.
Scp03KeyParams	Helper class that provides a standard way to create an ABC using
Scp11KeyParams	Helper class that provides a standard way to create an ABC using
ScpKeyParams	Helper class that provides a standard way to create an ABC using
ScpState
SmartCardConnection	A connection to a YubiKey
ApduFormat	APDU encoding format
AID	YubiKey Application smart card AID values.
SW	Enum where members are also (and must be) ints
ApduFormatter	Helper class that provides a standard way to create an ABC using
ShortApduFormatter	Helper class that provides a standard way to create an ABC using
ExtendedApduFormatter	Helper class that provides a standard way to create an ABC using
ApduProcessor	Helper class that provides a standard way to create an ABC using
ApduFormatProcessor	Helper class that provides a standard way to create an ABC using
CommandChainingProcessor	Helper class that provides a standard way to create an ABC using
ResponseChainingProcessor	Helper class that provides a standard way to create an ABC using
TouchWorkaroundProcessor	Helper class that provides a standard way to create an ABC using
ScpProcessor	Helper class that provides a standard way to create an ABC using
SmartCardProtocol	An implementation of the Smart Card protocol.

Package Contents

class yubikit.core.smartcard.LOG_LEVEL

Bases: enum.IntEnum

Enum where members are also (and must be) ints

ERROR = 40

WARNING = 30

INFO = 20

DEBUG = 10

TRAFFIC = 5

NOTSET = 0

class yubikit.core.smartcard.TRANSPORT

Bases: str, enum.Enum

YubiKey physical connection transports.

USB = 'usb'

NFC = 'nfc'

__str__()

Return str(self).

class yubikit.core.smartcard.USB_INTERFACE

Bases: enum.IntFlag

YubiKey USB interface identifiers.

OTP = 1

FIDO = 2

CCID = 4

exception yubikit.core.smartcard.ApplicationNotAvailableError

Bases: CommandError

The application is either disabled or not supported on this YubiKey

exception yubikit.core.smartcard.BadResponseError

Bases: CommandError

Invalid response data from the YubiKey

exception yubikit.core.smartcard.CommandError

Bases: Exception

An error response from a YubiKey

class yubikit.core.smartcard.Connection

Bases: abc.ABC

A connection to a YubiKey

usb_interface: ClassVar[USB_INTERFACE]

close()

Close the device, releasing any held resources.

Return type:

None

__enter__()

__exit__(typ, value, traceback)

exception yubikit.core.smartcard.NotSupportedError

Bases: ValueError

Attempting an action that is not supported on this YubiKey

class yubikit.core.smartcard.Version

Bases: NamedTuple

3-digit version tuple.

major: int

minor: int

patch: int

__str__()

__bool__()

classmethod from_bytes(data)

Parameters:

data (bytes)

Return type:

Version

classmethod from_string(data)

Parameters:

data (str)

Return type:

Version

yubikit.core.smartcard.INS_EXTERNAL_AUTHENTICATE = 130

class yubikit.core.smartcard.Scp03KeyParams

Bases: ScpKeyParams

Helper class that provides a standard way to create an ABC using inheritance.

ref: KeyRef

keys: StaticKeys

class yubikit.core.smartcard.Scp11KeyParams

Bases: ScpKeyParams

Helper class that provides a standard way to create an ABC using inheritance.

pk_sd_ecka: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey

oce_ref: KeyRef | None = None

sk_oce_ecka: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey | None = None

certificates: Sequence[cryptography.x509.Certificate] = []

class yubikit.core.smartcard.ScpKeyParams

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

ref: KeyRef

class yubikit.core.smartcard.ScpState(session_keys, mac_chain=b'\x00' * 16, enc_counter=1)

Parameters:

• session_keys (SessionKeys)

• mac_chain (bytes)

• enc_counter (int)

encrypt(data)

Parameters:

data (bytes)

Return type:

bytes

mac(data)

Parameters:

data (bytes)

Return type:

bytes

unmac(data, sw)

Parameters:

• data (bytes)

• sw (int)

Return type:

bytes

decrypt(encrypted)

Parameters:

encrypted (bytes)

Return type:

bytes

classmethod scp03_init(send_apdu, key_params, *, host_challenge=None)

Parameters:

• send_apdu (SendApdu)

• key_params (Scp03KeyParams)

• host_challenge (Optional[bytes])

Return type:

tuple[ScpState, bytes]

classmethod scp11_init(send_apdu, key_params)

Parameters:

• send_apdu (SendApdu)

• key_params (Scp11KeyParams)

Return type:

ScpState

class yubikit.core.smartcard.SmartCardConnection

Bases: yubikit.core.Connection

A connection to a YubiKey

usb_interface

property transport: yubikit.core.TRANSPORT

Abstractmethod:

Return type:

yubikit.core.TRANSPORT

Get the transport type of the connection (USB or NFC)

abstract send_and_receive(apdu)

Sends a command APDU and returns the response

Parameters:

apdu (bytes)

Return type:

tuple[bytes, int]

exception yubikit.core.smartcard.ApduError(data, sw)

Bases: yubikit.core.CommandError

Thrown when an APDU response has the wrong SW code

Parameters:

• data (bytes)

• sw (int)

data

sw

__str__()

Return str(self).

class yubikit.core.smartcard.ApduFormat

Bases: str, enum.Enum

APDU encoding format

SHORT = 'short'

EXTENDED = 'extended'

class yubikit.core.smartcard.AID

Bases: bytes, enum.Enum

YubiKey Application smart card AID values.

OTP

MANAGEMENT

OPENPGP

OATH

PIV

FIDO

HSMAUTH

SECURE_DOMAIN

class yubikit.core.smartcard.SW

Bases: enum.IntEnum

Enum where members are also (and must be) ints

NO_INPUT_DATA = 25221

VERIFY_FAIL_NO_RETRY = 25536

MEMORY_FAILURE = 25985

WRONG_LENGTH = 26368

SECURITY_CONDITION_NOT_SATISFIED = 27010

AUTH_METHOD_BLOCKED = 27011

DATA_INVALID = 27012

CONDITIONS_NOT_SATISFIED = 27013

COMMAND_NOT_ALLOWED = 27014

INCORRECT_PARAMETERS = 27264

FUNCTION_NOT_SUPPORTED = 27265

FILE_NOT_FOUND = 27266

RECORD_NOT_FOUND = 27267

NO_SPACE = 27268

REFERENCE_DATA_NOT_FOUND = 27272

APPLET_SELECT_FAILED = 27033

WRONG_PARAMETERS_P1P2 = 27392

INVALID_INSTRUCTION = 27904

CLASS_NOT_SUPPORTED = 28160

COMMAND_ABORTED = 28416

OK = 36864

yubikit.core.smartcard.INS_SELECT = 164

yubikit.core.smartcard.P1_SELECT = 4

yubikit.core.smartcard.P2_SELECT = 0

yubikit.core.smartcard.INS_SEND_REMAINING = 192

class yubikit.core.smartcard.ApduFormatter

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstract format_apdu(cla, ins, p1, p2, data, le)

Parameters:

• cla (int)

• ins (int)

• p1 (int)

• p2 (int)

• data (bytes)

• le (int)

Return type:

bytes

yubikit.core.smartcard.SHORT_APDU_MAX_CHUNK = 255

class yubikit.core.smartcard.ShortApduFormatter

Bases: ApduFormatter

Helper class that provides a standard way to create an ABC using inheritance.

format_apdu(cla, ins, p1, p2, data, le)

class yubikit.core.smartcard.ExtendedApduFormatter(max_apdu_size)

Bases: ApduFormatter

Helper class that provides a standard way to create an ABC using inheritance.

format_apdu(cla, ins, p1, p2, data, le)

class yubikit.core.smartcard.ApduProcessor

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstract send_apdu(cla, ins, p1, p2, data, le)

Parameters:

• cla (int)

• ins (int)

• p1 (int)

• p2 (int)

• data (bytes)

• le (int)

Return type:

tuple[bytes, int]

class yubikit.core.smartcard.ApduFormatProcessor(connection, formatter)

Bases: ApduProcessor

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

• connection (SmartCardConnection)

• formatter (ApduFormatter)

connection

formatter

send_apdu(cla, ins, p1, p2, data, le)

class yubikit.core.smartcard.CommandChainingProcessor(connection)

Bases: ApduFormatProcessor

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

connection (SmartCardConnection)

send_apdu(cla, ins, p1, p2, data, le)

yubikit.core.smartcard.SW1_HAS_MORE_DATA = 97

class yubikit.core.smartcard.ResponseChainingProcessor(delegate, ins_send_remaining=INS_SEND_REMAINING)

Bases: ApduProcessor

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

• delegate (ApduProcessor)

• ins_send_remaining (int)

delegate

ins_send_remaining = 192

send_apdu(cla, ins, p1, p2, data, le)

class yubikit.core.smartcard.TouchWorkaroundProcessor(delegate)

Bases: ApduProcessor

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

delegate (ApduProcessor)

delegate

send_apdu(cla, ins, p1, p2, data, le)

class yubikit.core.smartcard.ScpProcessor(delegate, formatter, scp_state)

Bases: ApduProcessor

Helper class that provides a standard way to create an ABC using inheritance.

Parameters:

• delegate (ApduProcessor)

• formatter (ApduFormatter)

• scp_state (scp.ScpState)

extended_formatter

delegate

formatter

state

send_apdu(cla, ins, p1, p2, data, le, encrypt=True)

Parameters:

encrypt (bool)

class yubikit.core.smartcard.SmartCardProtocol(smartcard_connection, ins_send_remaining=INS_SEND_REMAINING)

An implementation of the Smart Card protocol.

Parameters:

• smartcard_connection (SmartCardConnection)

• ins_send_remaining (int)

connection

property apdu_format: ApduFormat

Return type:

ApduFormat

close()

Return type:

None

enable_touch_workaround(version)

Parameters:

version (yubikit.core.Version)

Return type:

None

configure(version, force_short=False)

Configure the connection optimally for the given YubiKey version.

Parameters:

• version (yubikit.core.Version)

• force_short (bool)

Return type:

None

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

Send APDU message.

Parameters:

• cla (int) – The instruction class.

• ins (int) – The instruction code.

• p1 (int) – The instruction parameter.

• p2 (int) – The instruction parameter.

• data (bytes) – The command data in bytes.

• le (int) – The maximum number of bytes in the data field of the response.

Return type:

bytes

select(aid)

Perform a SELECT instruction.

Parameters:

aid (bytes) – The YubiKey application AID value.

Return type:

bytes

init_scp(key_params)

Parameters:

key_params (scp.ScpKeyParams)

Return type:

None