yubikit package

Subpackages

Submodules

yubikit.hsmauth module

class yubikit.hsmauth.ALGORITHM(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Algorithms for YubiHSM Auth credentials.

AES128_YUBICO_AUTHENTICATION = 38
EC_P256_YUBICO_AUTHENTICATION = 39
property key_len
property pubkey_len
class yubikit.hsmauth.Credential(label, algorithm, counter, touch_required)[source]

Bases: object

A YubiHSM Auth credential object.

label: str
algorithm: ALGORITHM
counter: int
touch_required: Optional[bool]
class yubikit.hsmauth.SessionKeys(key_senc: bytes, key_smac: bytes, key_srmac: bytes)[source]

Bases: NamedTuple

YubiHSM Session Keys.

key_senc: bytes

Alias for field number 0

key_smac: bytes

Alias for field number 1

key_srmac: bytes

Alias for field number 2

classmethod parse(response)[source]
Return type:

SessionKeys

class yubikit.hsmauth.HsmAuthSession(connection, scp_key_params=None)[source]

Bases: object

A session with the YubiHSM Auth application.

property version: Version

The YubiHSM Auth application version.

reset()[source]

Perform a factory reset on the YubiHSM Auth application.

Return type:

None

list_credentials()[source]

List YubiHSM Auth credentials on YubiKey

Return type:

List[Credential]

put_credential_symmetric(management_key, label, key_enc, key_mac, credential_password, touch_required=False)[source]

Import a symmetric YubiHSM Auth credential.

Parameters:

  • management_key (bytes) – The management key.

  • label (str) – The label of the credential.

  • key_enc (bytes) – The static K-ENC.

  • key_mac (bytes) – The static K-MAC.

  • credential_password (Union[bytes, str]) – The password used to protect access to the credential.

  • touch_required (bool) – The touch requirement policy.

Return type:

Credential

put_credential_derived(management_key, label, derivation_password, credential_password, touch_required=False)[source]

Import a symmetric YubiHSM Auth credential derived from password.

Parameters:

  • management_key (bytes) – The management key.

  • label (str) – The label of the credential.

  • derivation_password (str) – The password used to derive the keys from.

  • credential_password (Union[bytes, str]) – The password used to protect access to the credential.

  • touch_required (bool) – The touch requirement policy.

Return type:

Credential

put_credential_asymmetric(management_key, label, private_key, credential_password, touch_required=False)[source]

Import an asymmetric YubiHSM Auth credential.

Parameters:

  • management_key (bytes) – The management key.

  • label (str) – The label of the credential.

  • private_key (EllipticCurvePrivateKey) – Private key corresponding to the public authentication key object on the YubiHSM.

  • credential_password (Union[bytes, str]) – The password used to protect access to the credential.

  • touch_required (bool) – The touch requirement policy.

Return type:

Credential

generate_credential_asymmetric(management_key, label, credential_password, touch_required=False)[source]

Generate an asymmetric YubiHSM Auth credential.

Generates a private key on the YubiKey, whose corresponding public key can be retrieved using get_public_key.

Parameters:

  • management_key (bytes) – The management key.

  • label (str) – The label of the credential.

  • credential_password (Union[bytes, str]) – The password used to protect access to the credential.

  • touch_required (bool) – The touch requirement policy.

Return type:

Credential

get_public_key(label)[source]

Get the public key for an asymmetric credential.

This will return the long-term public key “PK-OCE” for an asymmetric credential.

Parameters:

label (str) – The label of the credential.

Return type:

EllipticCurvePublicKey

delete_credential(management_key, label)[source]

Delete a YubiHSM Auth credential.

Parameters:

  • management_key (bytes) – The management key.

  • label (str) – The label of the credential.

Return type:

None

put_management_key(management_key, new_management_key)[source]

Change YubiHSM Auth management key

Parameters:

  • management_key (bytes) – The current management key.

  • new_management_key (bytes) – The new management key.

Return type:

None

get_management_key_retries()[source]

Get retries remaining for Management key

Return type:

int

calculate_session_keys_symmetric(label, context, credential_password, card_crypto=None)[source]

Calculate session keys from a symmetric YubiHSM Auth credential.

Parameters:

  • label (str) – The label of the credential.

  • context (bytes) – The context (host challenge + hsm challenge).

  • credential_password (Union[bytes, str]) – The password used to protect access to the credential.

  • card_crypto (Optional[bytes]) – The card cryptogram.

Return type:

SessionKeys

calculate_session_keys_asymmetric(label, context, public_key, credential_password, card_crypto)[source]

Calculate session keys from an asymmetric YubiHSM Auth credential.

Parameters:

  • label (str) – The label of the credential.

  • context (bytes) – The context (EPK.OCE + EPK.SD).

  • public_key (EllipticCurvePublicKey) – The YubiHSM device’s public key.

  • credential_password (Union[bytes, str]) – The password used to protect access to the credential.

  • card_crypto (bytes) – The card cryptogram.

Return type:

SessionKeys

get_challenge(label, credential_password=None)[source]

Get the Host Challenge.

For symmetric credentials this is Host Challenge, a random 8 byte value. For asymmetric credentials this is EPK-OCE.

Parameters:

  • label (str) – The label of the credential.

  • credential_password (Union[bytes, str, None]) – The password used to protect access to the credential, needed for asymmetric credentials.

Return type:

bytes

yubikit.logging module

class yubikit.logging.LOG_LEVEL(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

ERROR = 40
WARNING = 30
INFO = 20
DEBUG = 10
TRAFFIC = 5
NOTSET = 0

yubikit.management module

class yubikit.management.CAPABILITY(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

YubiKey Application identifiers.

OTP = 1
U2F = 2
FIDO2 = 512
OATH = 32
PIV = 16
OPENPGP = 8
HSMAUTH = 256
property display_name: str
property usb_interfaces: USB_INTERFACE
class yubikit.management.FORM_FACTOR(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

YubiKey device form factors.

UNKNOWN = 0
USB_A_KEYCHAIN = 1
USB_A_NANO = 2
USB_C_KEYCHAIN = 3
USB_C_NANO = 4
USB_C_LIGHTNING = 5
USB_A_BIO = 6
USB_C_BIO = 7
classmethod from_code(code)[source]
Return type:

FORM_FACTOR

class yubikit.management.DEVICE_FLAG(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

Configuration flags.

REMOTE_WAKEUP = 64
EJECT = 128
class yubikit.management.DeviceConfig(enabled_capabilities=<factory>, auto_eject_timeout=None, challenge_response_timeout=None, device_flags=None, nfc_restricted=None)[source]

Bases: object

Management settings for YubiKey which can be configured by the user.

enabled_capabilities: Mapping[TRANSPORT, CAPABILITY]
auto_eject_timeout: Optional[int] = None
challenge_response_timeout: Optional[int] = None
device_flags: Optional[DEVICE_FLAG] = None
nfc_restricted: Optional[bool] = None
get_bytes(reboot, cur_lock_code=None, new_lock_code=None)[source]
Return type:

bytes

class yubikit.management.DeviceInfo(config, serial, version, form_factor, supported_capabilities, is_locked, is_fips=False, is_sky=False, part_number=None, fips_capable=<CAPABILITY: 0>, fips_approved=<CAPABILITY: 0>, pin_complexity=False, reset_blocked=<CAPABILITY: 0>, fps_version=None, stm_version=None)[source]

Bases: object

Information about a YubiKey readable using the ManagementSession.

config: DeviceConfig
serial: Optional[int]
version: Version
form_factor: FORM_FACTOR
supported_capabilities: Mapping[TRANSPORT, CAPABILITY]
is_locked: bool
is_fips: bool = False
is_sky: bool = False
part_number: Optional[str] = None
fips_capable: CAPABILITY = 0
fips_approved: CAPABILITY = 0
pin_complexity: bool = False
reset_blocked: CAPABILITY = 0
fps_version: Optional[Version] = None
stm_version: Optional[Version] = None
has_transport(transport)[source]
Return type:

bool

classmethod parse(encoded, default_version)[source]
Return type:

DeviceInfo

classmethod parse_tlvs(data, default_version)[source]
Return type:

DeviceInfo

class yubikit.management.Mode(interfaces)[source]

Bases: object

YubiKey USB Mode configuration for use with YubiKey NEO and 4.

code: int
interfaces: USB_INTERFACE
classmethod from_code(code)[source]
Return type:

Mode

class yubikit.management.ManagementSession(connection, scp_key_params=None)[source]

Bases: object

close()[source]

Close the underlying connection.

Deprecated:

call .close() on the underlying connection instead.

Return type:

None

property version: Version

The firmware version of the YubiKey

read_device_info()[source]

Get detailed information about the YubiKey.

Return type:

DeviceInfo

write_device_config(config=None, reboot=False, cur_lock_code=None, new_lock_code=None)[source]

Write configuration settings for YubiKey.

Parameters:
Return type:

None

set_mode(mode, chalresp_timeout=0, auto_eject_timeout=None)[source]

Write connection modes (USB interfaces) for YubiKey.

Parameters:

  • mode (Mode) – The connection modes (USB interfaces).

  • chalresp_timeout (int) – The timeout when waiting for touch for challenge response.

  • auto_eject_timeout (Optional[int]) – When set, the smartcard will automatically eject after the given time.

Return type:

None

device_reset()[source]

Global factory reset.

This is only available for YubiKey Bio, which has a PIN that is shared between applications. This will factory reset the global PIN as well as the associated applications.

Return type:

None

yubikit.oath module

class yubikit.oath.HASH_ALGORITHM(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

SHA1 = 1
SHA256 = 2
SHA512 = 3
class yubikit.oath.OATH_TYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

HOTP = 16
TOTP = 32
yubikit.oath.parse_b32_key(key)[source]

Parse Base32 encoded key.

Parameters:

key (str) – The Base32 encoded key.

class yubikit.oath.CredentialData(name, oath_type, hash_algorithm, secret, digits=6, period=30, counter=0, issuer=None)[source]

Bases: object

An object holding OATH credential data.

name: str
oath_type: OATH_TYPE
hash_algorithm: HASH_ALGORITHM
secret: bytes
digits: int = 6
period: int = 30
counter: int = 0
issuer: Optional[str] = None
classmethod parse_uri(uri)[source]

Parse OATH credential data from URI.

Parameters:

uri (str) – The URI to parse from.

Return type:

CredentialData

get_id()[source]
Return type:

bytes

class yubikit.oath.Code(value, valid_from, valid_to)[source]

Bases: object

An OATH code object.

value: str
valid_from: int
valid_to: int
class yubikit.oath.Credential(device_id, id, issuer, name, oath_type, period, touch_required)[source]

Bases: object

An OATH credential object.

device_id: str
id: bytes
issuer: Optional[str]
name: str
oath_type: OATH_TYPE
period: int
touch_required: Optional[bool]
class yubikit.oath.OathSession(connection, scp_key_params=None)[source]

Bases: object

A session with the OATH application.

property version: Version

The version of the OATH application.

property device_id: str

The device ID.

A random static identifier that is re-generated on reset.

property has_key: bool

If True, the YubiKey has an access key set.

property locked: bool

If True, the OATH application is currently locked via an access key.

reset()[source]

Perform a factory reset on the OATH application.

Return type:

None

derive_key(password)[source]

Derive an access key from a password.

Parameters:

password (str) – The derivation password.

Return type:

bytes

validate(key)[source]

Validate authentication with access key.

This unlocks the session for use.

Parameters:

key (bytes) – The access key.

Return type:

None

set_key(key)[source]

Set an access key for authentication.

Parameters:

key (bytes) – The access key.

Return type:

None

unset_key()[source]

Remove the access key.

This removes the need to authentication a session before using it.

Return type:

None

put_credential(credential_data, touch_required=False)[source]

Add an OATH credential.

Parameters:

  • credential_data (CredentialData) – The credential data.

  • touch_required (bool) – The touch policy.

Return type:

Credential

rename_credential(credential_id, name, issuer=None)[source]

Rename a OATH credential.

Parameters:

  • credential_id (bytes) – The id of the credential.

  • name (str) – The new name of the credential.

  • issuer (Optional[str]) – The credential issuer.

Return type:

bytes

list_credentials()[source]

List OATH credentials.

Return type:

List[Credential]

calculate(credential_id, challenge)[source]

Perform a calculate for an OATH credential.

Parameters:

  • credential_id (bytes) – The id of the credential.

  • challenge (bytes) – The challenge.

Return type:

bytes

delete_credential(credential_id)[source]

Delete an OATH credential.

Parameters:

credential_id (bytes) – The id of the credential.

Return type:

None

calculate_all(timestamp=None)[source]

Calculate codes for all OATH credentials on the YubiKey.

This excludes credentials which require touch as well as HOTP credentials.

Parameters:

timestamp (Optional[int]) – A timestamp used for the TOTP challenge.

Return type:

Mapping[Credential, Optional[Code]]

calculate_code(credential, timestamp=None)[source]

Calculate code for an OATH credential.

Parameters:
Return type:

Code

yubikit.openpgp module

class yubikit.openpgp.UIF(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

OFF = 0
ON = 1
FIXED = 2
CACHED = 3
CACHED_FIXED = 4
classmethod parse(encoded)[source]
property is_fixed: bool
property is_cached: bool
class yubikit.openpgp.PIN_POLICY(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

ALWAYS = 0
ONCE = 1
class yubikit.openpgp.INS(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

VERIFY = 32
CHANGE_PIN = 36
RESET_RETRY_COUNTER = 44
PSO = 42
ACTIVATE = 68
GENERATE_ASYM = 71
GET_CHALLENGE = 132
INTERNAL_AUTHENTICATE = 136
SELECT_DATA = 165
GET_DATA = 202
PUT_DATA = 218
PUT_DATA_ODD = 219
TERMINATE = 230
GET_VERSION = 241
SET_PIN_RETRIES = 242
GET_ATTESTATION = 251
class yubikit.openpgp.PW(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

USER = 129
RESET = 130
ADMIN = 131
class yubikit.openpgp.DO(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

PRIVATE_USE_1 = 257
PRIVATE_USE_2 = 258
PRIVATE_USE_3 = 259
PRIVATE_USE_4 = 260
AID = 79
NAME = 91
LOGIN_DATA = 94
LANGUAGE = 61229
SEX = 24373
URL = 24400
HISTORICAL_BYTES = 24402
EXTENDED_LENGTH_INFO = 32614
GENERAL_FEATURE_MANAGEMENT = 32628
ALGORITHM_ATTRIBUTES_SIG = 193
ALGORITHM_ATTRIBUTES_DEC = 194
ALGORITHM_ATTRIBUTES_AUT = 195
ALGORITHM_ATTRIBUTES_ATT = 218
PW_STATUS_BYTES = 196
FINGERPRINT_SIG = 199
FINGERPRINT_DEC = 200
FINGERPRINT_AUT = 201
FINGERPRINT_ATT = 219
CA_FINGERPRINT_1 = 202
CA_FINGERPRINT_2 = 203
CA_FINGERPRINT_3 = 204
CA_FINGERPRINT_4 = 220
GENERATION_TIME_SIG = 206
GENERATION_TIME_DEC = 207
GENERATION_TIME_AUT = 208
GENERATION_TIME_ATT = 221
RESETTING_CODE = 211
UIF_SIG = 214
UIF_DEC = 215
UIF_AUT = 216
UIF_ATT = 217
SECURITY_SUPPORT_TEMPLATE = 122
CARDHOLDER_CERTIFICATE = 32545
KDF = 249
ALGORITHM_INFORMATION = 250
ATT_CERTIFICATE = 252
class yubikit.openpgp.OpenPgpAid[source]

Bases: bytes

OpenPGP Application Identifier (AID)

The OpenPGP AID is a string of bytes identifying the OpenPGP application. It also embeds some values which are accessible though properties.

property version: Tuple[int, int]

OpenPGP version (tuple of 2 integers: main version, secondary version).

property manufacturer: int

16-bit integer value identifying the manufacturer of the device.

This should be 6 for Yubico devices.

property serial: int

The serial number of the YubiKey.

NOTE: This value is encoded in BCD. In the event of an invalid value (hex A-F) the entire 4 byte value will instead be decoded as an unsigned integer, and negated.

class yubikit.openpgp.EXTENDED_CAPABILITY_FLAGS(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

KDF = 1
PSO_DEC_ENC_AES = 2
ALGORITHM_ATTRIBUTES_CHANGEABLE = 4
PRIVATE_USE = 8
PW_STATUS_CHANGEABLE = 16
KEY_IMPORT = 32
GET_CHALLENGE = 64
SECURE_MESSAGING = 128
class yubikit.openpgp.CardholderRelatedData(name, language, sex)[source]

Bases: object

name: bytes
language: bytes
sex: int
classmethod parse(encoded)[source]
Return type:

CardholderRelatedData

class yubikit.openpgp.ExtendedLengthInfo(request_max_bytes, response_max_bytes)[source]

Bases: object

request_max_bytes: int
response_max_bytes: int
classmethod parse(encoded)[source]
Return type:

ExtendedLengthInfo

class yubikit.openpgp.GENERAL_FEATURE_MANAGEMENT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

TOUCHSCREEN = 1
MICROPHONE = 2
LOUDSPEAKER = 4
LED = 8
KEYPAD = 16
BUTTON = 32
BIOMETRIC = 64
DISPLAY = 128
class yubikit.openpgp.ExtendedCapabilities(flags, sm_algorithm, challenge_max_length, certificate_max_length, special_do_max_length, pin_block_2_format, mse_command)[source]

Bases: object

flags: EXTENDED_CAPABILITY_FLAGS
sm_algorithm: int
challenge_max_length: int
certificate_max_length: int
special_do_max_length: int
pin_block_2_format: bool
mse_command: bool
classmethod parse(encoded)[source]
Return type:

ExtendedCapabilities

class yubikit.openpgp.PwStatus(pin_policy_user, max_len_user, max_len_reset, max_len_admin, attempts_user, attempts_reset, attempts_admin)[source]

Bases: object

pin_policy_user: PIN_POLICY
max_len_user: int
max_len_reset: int
max_len_admin: int
attempts_user: int
attempts_reset: int
attempts_admin: int
get_max_len(pw)[source]
Return type:

int

get_attempts(pw)[source]
Return type:

int

classmethod parse(encoded)[source]
Return type:

PwStatus

class yubikit.openpgp.CRT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: bytes, Enum

Control Reference Template values.

SIG = b'\xb6\x00'
DEC = b'\xb8\x00'
AUT = b'\xa4\x00'
ATT = b'\xb6\x03\x84\x01\x81'
class yubikit.openpgp.KEY_REF(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

SIG = 1
DEC = 2
AUT = 3
ATT = 129
property algorithm_attributes_do: DO
property uif_do: DO
property generation_time_do: DO
property fingerprint_do: DO
property crt: CRT
class yubikit.openpgp.KEY_STATUS(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

NONE = 0
GENERATED = 1
IMPORTED = 2
class yubikit.openpgp.AlgorithmAttributes(algorithm_id)[source]

Bases: ABC

OpenPGP key algorithm attributes.

algorithm_id: int
classmethod parse(encoded)[source]
Return type:

AlgorithmAttributes

class yubikit.openpgp.RSA_SIZE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

RSA2048 = 2048
RSA3072 = 3072
RSA4096 = 4096
class yubikit.openpgp.RSA_IMPORT_FORMAT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

STANDARD = 0
STANDARD_W_MOD = 1
CRT = 2
CRT_W_MOD = 3
class yubikit.openpgp.RsaAttributes(algorithm_id, n_len, e_len, import_format)[source]

Bases: AlgorithmAttributes

n_len: int
e_len: int
import_format: RSA_IMPORT_FORMAT
classmethod create(n_len, import_format=RSA_IMPORT_FORMAT.STANDARD)[source]
Return type:

RsaAttributes

class yubikit.openpgp.CurveOid[source]

Bases: bytes

class yubikit.openpgp.OID(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: CurveOid, Enum

SECP256R1 = SECP256R1(2a8648ce3d030107)
SECP256K1 = SECP256K1(2b8104000a)
SECP384R1 = SECP384R1(2b81040022)
SECP521R1 = SECP521R1(2b81040023)
BrainpoolP256R1 = BrainpoolP256R1(2b2403030208010107)
BrainpoolP384R1 = BrainpoolP384R1(2b240303020801010b)
BrainpoolP512R1 = BrainpoolP512R1(2b240303020801010d)
X25519 = X25519(2b060104019755010501)
Ed25519 = Ed25519(2b06010401da470f01)
class yubikit.openpgp.EC_IMPORT_FORMAT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

STANDARD = 0
STANDARD_W_PUBKEY = 255
class yubikit.openpgp.EcAttributes(algorithm_id, oid, import_format)[source]

Bases: AlgorithmAttributes

oid: CurveOid
import_format: EC_IMPORT_FORMAT
classmethod create(key_ref, oid)[source]
Return type:

EcAttributes

class yubikit.openpgp.DiscretionaryDataObjects(extended_capabilities, attributes_sig, attributes_dec, attributes_aut, attributes_att, pw_status, fingerprints, ca_fingerprints, generation_times, key_information, uif_sig, uif_dec, uif_aut, uif_att)[source]

Bases: object

extended_capabilities: ExtendedCapabilities
attributes_sig: AlgorithmAttributes
attributes_dec: AlgorithmAttributes
attributes_aut: AlgorithmAttributes
attributes_att: Optional[AlgorithmAttributes]
pw_status: PwStatus
fingerprints: Mapping[KEY_REF, bytes]
ca_fingerprints: Mapping[KEY_REF, bytes]
generation_times: Mapping[KEY_REF, int]
key_information: Mapping[KEY_REF, KEY_STATUS]
uif_sig: Optional[UIF]
uif_dec: Optional[UIF]
uif_aut: Optional[UIF]
uif_att: Optional[UIF]
classmethod parse(encoded)[source]
Return type:

DiscretionaryDataObjects

get_algorithm_attributes(key_ref)[source]
Return type:

AlgorithmAttributes

class yubikit.openpgp.ApplicationRelatedData(aid, historical, extended_length_info, general_feature_management, discretionary)[source]

Bases: object

OpenPGP related data.

aid: OpenPgpAid
historical: bytes
extended_length_info: Optional[ExtendedLengthInfo]
general_feature_management: Optional[GENERAL_FEATURE_MANAGEMENT]
discretionary: DiscretionaryDataObjects
classmethod parse(encoded)[source]
Return type:

ApplicationRelatedData

class yubikit.openpgp.SecuritySupportTemplate(signature_counter)[source]

Bases: object

signature_counter: int
classmethod parse(encoded)[source]
Return type:

SecuritySupportTemplate

class yubikit.openpgp.Kdf[source]

Bases: ABC

algorithm: ClassVar[int]
abstract process(pw, pin)[source]

Run the KDF on the input PIN.

Return type:

bytes

classmethod parse(encoded)[source]
Return type:

Kdf

class yubikit.openpgp.KdfNone[source]

Bases: Kdf

algorithm: ClassVar[int] = 0
process(pw, pin)[source]

Run the KDF on the input PIN.

class yubikit.openpgp.HASH_ALGORITHM(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

SHA256 = 8
SHA512 = 10
create_digest()[source]
class yubikit.openpgp.KdfIterSaltedS2k(hash_algorithm, iteration_count, salt_user, salt_reset, salt_admin, initial_hash_user, initial_hash_admin)[source]

Bases: Kdf

algorithm: ClassVar[int] = 3
hash_algorithm: HASH_ALGORITHM
iteration_count: int
salt_user: bytes
salt_reset: bytes
salt_admin: bytes
initial_hash_user: Optional[bytes]
initial_hash_admin: Optional[bytes]
classmethod create(hash_algorithm=HASH_ALGORITHM.SHA256, iteration_count=7864320)[source]
Return type:

KdfIterSaltedS2k

get_salt(pw)[source]
Return type:

bytes

process(pw, pin)[source]

Run the KDF on the input PIN.

class yubikit.openpgp.PrivateKeyTemplate(crt)[source]

Bases: ABC

crt: CRT
class yubikit.openpgp.RsaKeyTemplate(crt, e, p, q)[source]

Bases: PrivateKeyTemplate

e: bytes
p: bytes
q: bytes
class yubikit.openpgp.RsaCrtKeyTemplate(crt, e, p, q, iqmp, dmp1, dmq1, n)[source]

Bases: RsaKeyTemplate

iqmp: bytes
dmp1: bytes
dmq1: bytes
n: bytes
class yubikit.openpgp.EcKeyTemplate(crt, private_key, public_key)[source]

Bases: PrivateKeyTemplate

private_key: bytes
public_key: Optional[bytes]
class yubikit.openpgp.OpenPgpSession(connection, scp_key_params=None)[source]

Bases: object

A session with the OpenPGP application.

property aid: OpenPgpAid

Get the AID used to select the applet.

property version: Version

Get the firmware version of the key.

For YubiKey NEO this is the PGP applet version.

property extended_capabilities: ExtendedCapabilities

Get the Extended Capabilities from the YubiKey.

get_challenge(length)[source]

Get random data from the YubiKey.

Parameters:

length (int) – Length of the returned data.

Return type:

bytes

get_data(do)[source]

Get a Data Object from the YubiKey.

Parameters:

do (DO) – The Data Object to get.

Return type:

bytes

put_data(do, data)[source]

Write a Data Object to the YubiKey.

Parameters:
Return type:

None

get_pin_status()[source]

Get the current status of PINS.

Return type:

PwStatus

get_signature_counter()[source]

Get the number of times the signature key has been used.

Return type:

int

Read the Application Related Data.

Return type:

ApplicationRelatedData

set_signature_pin_policy(pin_policy)[source]

Set signature PIN policy.

Requires Admin PIN verification.

Parameters:

pin_policy (PIN_POLICY) – The PIN policy.

Return type:

None

reset()[source]

Perform a factory reset on the OpenPGP application.

WARNING: This will delete all stored keys, certificates and other data.

Return type:

None

set_pin_attempts(user_attempts, reset_attempts, admin_attempts)[source]

Set the number of PIN attempts to allow before blocking.

WARNING: On YubiKey NEO this will reset the PINs to their default values.

Requires Admin PIN verification.

Parameters:

  • user_attempts (int) – The User PIN attempts.

  • reset_attempts (int) – The Reset Code attempts.

  • admin_attempts (int) – The Admin PIN attempts.

Return type:

None

get_kdf()[source]

Get the Key Derivation Function data object.

Return type:

Kdf

set_kdf(kdf)[source]

Set up a PIN Key Derivation Function.

This enables (or disables) the use of a KDF for PIN verification, as well as resetting the User and Admin PINs to their default (initial) values.

If a Reset Code is present, it will be invalidated.

This command requires Admin PIN verification.

Parameters:

kdf (Kdf) – The key derivation function.

Return type:

None

verify_pin(pin, extended=False)[source]

Verify the User PIN.

This will unlock functionality that requires User PIN verification. Note that with extended=False (default) only sign operations are allowed. Inversely, with extended=True sign operations are NOT allowed.

Parameters:

  • pin – The User PIN.

  • extended (bool) – If False only sign operations are allowed, otherwise sign operations are NOT allowed.

verify_admin(admin_pin)[source]

Verify the Admin PIN.

This will unlock functionality that requires Admin PIN verification.

Parameters:

admin_pin – The Admin PIN.

unverify_pin(pw)[source]

Reset verification for PIN.

Parameters:

pw (PW) – The User, Admin or Reset PIN

Return type:

None

change_pin(pin, new_pin)[source]

Change the User PIN.

Parameters:

  • pin (str) – The current User PIN.

  • new_pin (str) – The new User PIN.

Return type:

None

change_admin(admin_pin, new_admin_pin)[source]

Change the Admin PIN.

Parameters:

  • admin_pin (str) – The current Admin PIN.

  • new_admin_pin (str) – The new Admin PIN.

Return type:

None

set_reset_code(reset_code)[source]

Set the Reset Code for User PIN.

The Reset Code can be used to set a new User PIN if it is lost or becomes blocked, using the reset_pin method.

This command requires Admin PIN verification.

Parameters:

reset_code (str) – The Reset Code for User PIN.

Return type:

None

reset_pin(new_pin, reset_code=None)[source]

Reset the User PIN to a new value.

This command requires Admin PIN verification, or the Reset Code.

Parameters:

  • new_pin (str) – The new user PIN.

  • reset_code (Optional[str]) – The Reset Code.

Return type:

None

get_algorithm_attributes(key_ref)[source]

Get the algorithm attributes for one of the key slots.

Parameters:

key_ref (KEY_REF) – The key slot.

Return type:

AlgorithmAttributes

get_algorithm_information()[source]

Get the list of supported algorithm attributes for each key.

The return value is a mapping of KEY_REF to a list of supported algorithm attributes, which can be set using set_algorithm_attributes.

Return type:

Mapping[KEY_REF, Sequence[AlgorithmAttributes]]

set_algorithm_attributes(key_ref, attributes)[source]

Set the algorithm attributes for a key slot.

WARNING: This will delete any key already stored in the slot if the attributes are changed!

This command requires Admin PIN verification.

Parameters:
Return type:

None

get_uif(key_ref)[source]

Get the User Interaction Flag (touch requirement) for a key.

Parameters:

key_ref (KEY_REF) – The key slot.

Return type:

UIF

set_uif(key_ref, uif)[source]

Set the User Interaction Flag (touch requirement) for a key.

Requires Admin PIN verification.

Parameters:

  • key_ref (KEY_REF) – The key slot.

  • uif (UIF) – The User Interaction Flag.

Return type:

None

get_key_information()[source]

Get the status of the keys.

Return type:

Mapping[KEY_REF, KEY_STATUS]

get_generation_times()[source]

Get timestamps for when keys were generated.

Return type:

Mapping[KEY_REF, int]

set_generation_time(key_ref, timestamp)[source]

Set the generation timestamp for a key.

Requires Admin PIN verification.

Parameters:

  • key_ref (KEY_REF) – The key slot.

  • timestamp (int) – The timestamp.

Return type:

None

get_fingerprints()[source]

Get key fingerprints.

Return type:

Mapping[KEY_REF, bytes]

set_fingerprint(key_ref, fingerprint)[source]

Set the fingerprint for a key.

Requires Admin PIN verification.

Parameters:

  • key_ref (KEY_REF) – The key slot.

  • fingerprint (bytes) – The fingerprint.

Return type:

None

get_public_key(key_ref)[source]

Get the public key from a slot.

Parameters:

key_ref (KEY_REF) – The key slot.

Return type:

Union[EllipticCurvePublicKey, Ed25519PublicKey, X25519PublicKey, RSAPublicKey]

generate_rsa_key(key_ref, key_size)[source]

Generate an RSA key in the given slot.

Requires Admin PIN verification.

Parameters:

  • key_ref (KEY_REF) – The key slot.

  • key_size (RSA_SIZE) – The size of the RSA key.

Return type:

RSAPublicKey

generate_ec_key(key_ref, curve_oid)[source]

Generate an EC key in the given slot.

Requires Admin PIN verification.

Parameters:

  • key_ref (KEY_REF) – The key slot.

  • curve_oid (CurveOid) – The curve OID.

Return type:

Union[EllipticCurvePublicKey, Ed25519PublicKey, X25519PublicKey]

put_key(key_ref, private_key)[source]

Import a private key into the given slot.

Requires Admin PIN verification.

Parameters:
Return type:

None

delete_key(key_ref)[source]

Delete the contents of a key slot.

Requires Admin PIN verification.

Parameters:

key_ref (KEY_REF) – The key slot.

Return type:

None

get_certificate(key_ref)[source]

Get a certificate from a slot.

Parameters:

key_ref (KEY_REF) – The slot.

Return type:

Certificate

put_certificate(key_ref, certificate)[source]

Import a certificate into a slot.

Requires Admin PIN verification.

Parameters:

  • key_ref (KEY_REF) – The slot.

  • certificate (Certificate) – The X.509 certificate to import.

Return type:

None

delete_certificate(key_ref)[source]

Delete a certificate in a slot.

Requires Admin PIN verification.

Parameters:

key_ref (KEY_REF) – The slot.

Return type:

None

attest_key(key_ref)[source]

Create an attestation certificate for a key.

The certificate is written to the certificate slot for the key, and its content is returned.

Requires User PIN verification.

Parameters:

key_ref (KEY_REF) – The key slot.

Return type:

Certificate

sign(message, hash_algorithm)[source]

Sign a message using the SIG key.

Requires User PIN verification.

Parameters:

  • message (bytes) – The message to sign.

  • hash_algorithm (HashAlgorithm) – The pre-signature hash algorithm.

Return type:

bytes

decrypt(value)[source]

Decrypt a value using the DEC key.

For RSA the value should be an encrypted block. For ECDH the value should be a peer public-key to perform the key exchange with, and the result will be the derived shared secret.

Requires (extended) User PIN verification.

Parameters:

value (Union[bytes, EllipticCurvePublicKey, Ed25519PublicKey, X25519PublicKey]) – The value to decrypt.

Return type:

bytes

authenticate(message, hash_algorithm)[source]

Authenticate a message using the AUT key.

Requires User PIN verification.

Parameters:

  • message (bytes) – The message to authenticate.

  • hash_algorithm (HashAlgorithm) – The pre-authentication hash algorithm.

Return type:

bytes

yubikit.piv module

class yubikit.piv.ALGORITHM(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: str, Enum

EC = 'ec'
RSA = 'rsa'
yubikit.piv.require_version(my_version, *args, **kwargs)[source]
class yubikit.piv.KEY_TYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

RSA1024 = 6
RSA2048 = 7
RSA3072 = 5
RSA4096 = 22
ECCP256 = 17
ECCP384 = 20
ED25519 = 224
X25519 = 225
property algorithm
property bit_len
classmethod from_public_key(key)[source]
class yubikit.piv.MANAGEMENT_KEY_TYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

TDES = 3
AES128 = 8
AES192 = 10
AES256 = 12
property key_len
property challenge_len
class yubikit.piv.SLOT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

AUTHENTICATION = 154
SIGNATURE = 156
KEY_MANAGEMENT = 157
CARD_AUTH = 158
RETIRED1 = 130
RETIRED2 = 131
RETIRED3 = 132
RETIRED4 = 133
RETIRED5 = 134
RETIRED6 = 135
RETIRED7 = 136
RETIRED8 = 137
RETIRED9 = 138
RETIRED10 = 139
RETIRED11 = 140
RETIRED12 = 141
RETIRED13 = 142
RETIRED14 = 143
RETIRED15 = 144
RETIRED16 = 145
RETIRED17 = 146
RETIRED18 = 147
RETIRED19 = 148
RETIRED20 = 149
ATTESTATION = 249
class yubikit.piv.OBJECT_ID(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

CAPABILITY = 6275335
CHUID = 6275330
AUTHENTICATION = 6275333
FINGERPRINTS = 6275331
SECURITY = 6275334
FACIAL = 6275336
PRINTED = 6275337
SIGNATURE = 6275338
KEY_MANAGEMENT = 6275339
CARD_AUTH = 6275329
DISCOVERY = 126
KEY_HISTORY = 6275340
IRIS = 6275361
RETIRED1 = 6275341
RETIRED2 = 6275342
RETIRED3 = 6275343
RETIRED4 = 6275344
RETIRED5 = 6275345
RETIRED6 = 6275346
RETIRED7 = 6275347
RETIRED8 = 6275348
RETIRED9 = 6275349
RETIRED10 = 6275350
RETIRED11 = 6275351
RETIRED12 = 6275352
RETIRED13 = 6275353
RETIRED14 = 6275354
RETIRED15 = 6275355
RETIRED16 = 6275356
RETIRED17 = 6275357
RETIRED18 = 6275358
RETIRED19 = 6275359
RETIRED20 = 6275360
ATTESTATION = 6291201
classmethod from_slot(slot)[source]
class yubikit.piv.PIN_POLICY(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

DEFAULT = 0
NEVER = 1
ONCE = 2
ALWAYS = 3
MATCH_ONCE = 4
MATCH_ALWAYS = 5
class yubikit.piv.TOUCH_POLICY(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

DEFAULT = 0
NEVER = 1
ALWAYS = 2
CACHED = 3
class yubikit.piv.PinMetadata(default_value, total_attempts, attempts_remaining)[source]

Bases: object

default_value: bool
total_attempts: int
attempts_remaining: int
class yubikit.piv.ManagementKeyMetadata(key_type, default_value, touch_policy)[source]

Bases: object

key_type: MANAGEMENT_KEY_TYPE
default_value: bool
touch_policy: TOUCH_POLICY
class yubikit.piv.SlotMetadata(key_type, pin_policy, touch_policy, generated, public_key_encoded)[source]

Bases: object

key_type: KEY_TYPE
pin_policy: PIN_POLICY
touch_policy: TOUCH_POLICY
generated: bool
public_key_encoded: bytes
property public_key
class yubikit.piv.BioMetadata(configured, attempts_remaining, temporary_pin)[source]

Bases: object

configured: bool
attempts_remaining: int
temporary_pin: bool
yubikit.piv.check_key_support(version, key_type, pin_policy, touch_policy, generate=True)[source]

Check if a key type is supported by a specific YubiKey firmware version.

This method will return None if the key (with PIN and touch policies) is supported, or it will raise a NotSupportedError if it is not.

Deprecated:

Use PivSession.check_key_support() instead.

Return type:

None

class yubikit.piv.PivSession(connection, scp_key_params=None)[source]

Bases: object

A session with the PIV application.

property version: Version

The version of the PIV application, typically the same as the YubiKey firmware.

property management_key_type: MANAGEMENT_KEY_TYPE

The algorithm of the management key currently in use.

reset()[source]

Factory reset the PIV application data.

This deletes all user-data from the PIV application, and resets the default values for PIN, PUK, and management key.

Return type:

None

authenticate(management_key)[source]

Authenticate to PIV with management key.

Parameters:

management_key (bytes) – The management key in raw bytes.

Return type:

None

set_management_key(key_type, management_key, require_touch=False)[source]

Set a new management key.

Parameters:

  • key_type (MANAGEMENT_KEY_TYPE) – The management key type.

  • management_key (bytes) – The management key in raw bytes.

  • require_touch (bool) – The touch policy.

Return type:

None

verify_pin(pin)[source]

Verify the user by PIN.

Parameters:

pin (str) – The PIN.

Return type:

None

verify_uv(temporary_pin=False, check_only=False)[source]

Verify the user by fingerprint (YubiKey Bio only).

Fingerprint verification will allow usage of private keys which have a PIN policy allowing MATCH. For those using MATCH_ALWAYS, the fingerprint must be verified just prior to using the key, or by first requesting a temporary PIN and then later verifying the PIN just prior to key use.

Parameters:

  • temporary_pin (bool) – Request a temporary PIN for later use within the session.

  • check_only (bool) – Do not verify the user, instead immediately throw an InvalidPinException containing the number of remaining attempts.

Return type:

Optional[bytes]

verify_temporary_pin(pin)[source]

Verify the user via temporary PIN.

Parameters:

pin (bytes) – A temporary PIN previously requested via verify_uv.

Return type:

None

get_pin_attempts()[source]

Get remaining PIN attempts.

Return type:

int

change_pin(old_pin, new_pin)[source]

Change the PIN.

Parameters:

  • old_pin (str) – The current PIN.

  • new_pin (str) – The new PIN.

Return type:

None

change_puk(old_puk, new_puk)[source]

Change the PUK.

Parameters:

  • old_puk (str) – The current PUK.

  • new_puk (str) – The new PUK.

Return type:

None

unblock_pin(puk, new_pin)[source]

Reset PIN with PUK.

Parameters:

  • puk (str) – The PUK.

  • new_pin (str) – The new PIN.

Return type:

None

set_pin_attempts(pin_attempts, puk_attempts)[source]

Set PIN retries for PIN and PUK.

Both PIN and PUK will be reset to default values when this is executed.

Requires authentication with management key and PIN verification.

Parameters:

  • pin_attempts (int) – The PIN attempts.

  • puk_attempts (int) – The PUK attempts.

Return type:

None

get_pin_metadata()[source]

Get PIN metadata.

Return type:

PinMetadata

get_puk_metadata()[source]

Get PUK metadata.

Return type:

PinMetadata

get_management_key_metadata()[source]

Get management key metadata.

Return type:

ManagementKeyMetadata

get_slot_metadata(slot)[source]

Get slot metadata.

Parameters:

slot (SLOT) – The slot to get metadata from.

Return type:

SlotMetadata

get_bio_metadata()[source]

Get YubiKey Bio metadata.

This tells you if fingerprints are enrolled or not, how many fingerprint verification attempts remain, and whether or not a temporary PIN is currently active.

Return type:

BioMetadata

sign(slot, key_type, message, hash_algorithm, padding=None)[source]

Sign message with key.

Requires PIN verification.

Parameters:

  • slot (SLOT) – The slot of the key to use.

  • key_type (KEY_TYPE) – The type of the key to sign with.

  • message (bytes) – The message to sign.

  • hash_algorithm (HashAlgorithm) – The pre-signature hash algorithm to use.

  • padding (Optional[AsymmetricPadding]) – The pre-signature padding.

Return type:

bytes

decrypt(slot, cipher_text, padding)[source]

Decrypt cipher text.

Requires PIN verification.

Parameters:

  • slot (SLOT) – The slot.

  • cipher_text (bytes) – The cipher text to decrypt.

  • padding (AsymmetricPadding) – The padding of the plain text.

Return type:

bytes

calculate_secret(slot, peer_public_key)[source]

Calculate shared secret using ECDH.

Requires PIN verification.

Parameters:
Return type:

bytes

get_object(object_id)[source]

Get object by ID.

Requires PIN verification for protected objects.

Parameters:

object_id (int) – The object identifier.

Return type:

bytes

put_object(object_id, data=None)[source]

Write data to PIV object.

Requires authentication with management key.

Parameters:

  • object_id (int) – The object identifier.

  • data (Optional[bytes]) – The object data.

Return type:

None

get_certificate(slot)[source]

Get certificate from slot.

Parameters:

slot (SLOT) – The slot to get the certificate from.

Return type:

Certificate

put_certificate(slot, certificate, compress=False)[source]

Import certificate to slot.

Requires authentication with management key.

Parameters:

  • slot (SLOT) – The slot to import the certificate to.

  • certificate (Certificate) – The certificate to import.

  • compress (bool) – If the certificate should be compressed or not.

Return type:

None

delete_certificate(slot)[source]

Delete certificate.

Requires authentication with management key.

Parameters:

slot (SLOT) – The slot to delete the certificate from.

Return type:

None

put_key(slot, private_key, pin_policy=PIN_POLICY.DEFAULT, touch_policy=TOUCH_POLICY.DEFAULT)[source]

Import a private key to slot.

Requires authentication with management key.

Parameters:
Return type:

None

generate_key(slot, key_type, pin_policy=PIN_POLICY.DEFAULT, touch_policy=TOUCH_POLICY.DEFAULT)[source]

Generate private key in slot.

Requires authentication with management key.

Parameters:

  • slot (SLOT) – The slot to generate the private key in.

  • key_type (KEY_TYPE) – The key type.

  • pin_policy (PIN_POLICY) – The PIN policy.

  • touch_policy (TOUCH_POLICY) – The touch policy.

Return type:

Union[RSAPublicKey, EllipticCurvePublicKey]

attest_key(slot)[source]

Attest key in slot.

Parameters:

slot (SLOT) – The slot where the key has been generated.

Return type:

Certificate

Returns:

A X.509 certificate.

move_key(from_slot, to_slot)[source]

Move key from one slot to another.

Requires authentication with management key.

Parameters:

  • from_slot (SLOT) – The slot containing the key to move.

  • to_slot (SLOT) – The new slot to move the key to.

Return type:

None

delete_key(slot)[source]

Delete a key in a slot.

Requires authentication with management key.

Parameters:

slot (SLOT) – The slot containing the key to delete.

Return type:

None

check_key_support(key_type, pin_policy, touch_policy, generate, fips_restrictions=False)[source]

Check if a key type is supported by this YubiKey.

This method will return None if the key (with PIN and touch policies) is supported, or it will raise a NotSupportedError if it is not.

Set the generate parameter to True to check if generating the key is supported (in addition to importing).

Set fips_restrictions to True to apply restrictions based on FIPS status.

Return type:

None

yubikit.securitydomain module

class yubikit.securitydomain.KeyType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

AES = 136
ECC_PUBLIC_KEY = 176
ECC_PRIVATE_KEY = 177
ECC_KEY_PARAMS = 240
class yubikit.securitydomain.Curve(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

SECP256R1 = 0
SECP384R1 = 1
SECP521R1 = 2
BrainpoolP256R1 = 3
BrainpoolP384R1 = 5
BrainpoolP512R1 = 7
class yubikit.securitydomain.SecurityDomainSession(connection)[source]

Bases: object

A session for managing SCP keys

authenticate(key_params)[source]

Initialize SCP and authenticate the session.

SCP11b does not authenticate the OCE, and will not allow the usage of commands which require authentication of the OCE.

Return type:

None

get_data(tag, data=b'')[source]

Read data from the security domain.

Return type:

bytes

get_key_information()[source]

Get information about the currently loaded keys.

Return type:

Mapping[KeyRef, Mapping[int, int]]

get_card_recognition_data()[source]

Get information about the card.

Return type:

bytes

get_supported_ca_identifiers(kloc=False, klcc=False)[source]

Get a list of the CA issuer Subject Key Identifiers for keys.

Setting one of kloc or klcc to True will cause only those CAs to be returned. By default, this will get both KLOC and KLCC CAs.

Parameters:

  • kloc (bool) – Get KLOC CAs.

  • klcc (bool) – Get KLCC CAs.

Return type:

Mapping[KeyRef, bytes]

get_certificate_bundle(key)[source]

Get the certificates associated with the given SCP11 private key.

Certificates are returned leaf-last.

Return type:

Sequence[Certificate]

reset()[source]

Perform a factory reset of the Security Domain.

This will remove all keys and associated data, as well as restore the default SCP03 static keys, and generate a new (attestable) SCP11b key.

Return type:

None

store_data(data)[source]

Stores data in the security domain.

Requires OCE verification.

Return type:

None

store_certificate_bundle(key, certificates)[source]

Store the certificate chain for the given key.

Requires OCE verification.

Certificates should be in order, with the leaf certificate last.

Return type:

None

store_allowlist(key, serials)[source]

Store which certificate serial numbers that can be used for a given key.

Requires OCE verification.

If no allowlist is stored, any certificate signed by the CA can be used.

Return type:

None

store_ca_issuer(key, ski)[source]

Store the SKI (Subject Key Identifier) for the CA of a given key.

Requires OCE verification.

Return type:

None

delete_key(kid=0, kvn=0, delete_last=False)[source]

Delete one (or more) keys.

Requires OCE verification.

All keys matching the given KID and/or KVN will be deleted. To delete the final key you must set delete_last = True.

Return type:

None

generate_ec_key(key, curve=Curve.SECP256R1, replace_kvn=0)[source]

Generate a new SCP11 key.

Requires OCE verification.

Use replace_kvn to replace an existing key.

Return type:

EllipticCurvePublicKey

put_key(key, sk, replace_kvn=0)[source]

Import an SCP key.

Requires OCE verification.

The value of the sk argument should match the SCP type as defined by the KID. Use replace_kvn to replace an existing key.

Return type:

None

yubikit.support module

yubikit.support.read_info(conn, pid=None)[source]

Reads out DeviceInfo from a YubiKey, or attempts to synthesize the data.

Reading DeviceInfo from a ManagementSession is only supported for newer YubiKeys. This function attempts to read that information, but will fall back to gathering the data using other mechanisms if needed. It will also make adjustments to the data if required, for example to “fix” known bad values.

The pid parameter must be provided whenever the YubiKey is connected via USB.

Parameters:
Return type:

DeviceInfo

yubikit.support.get_name(info, key_type)[source]

Determine the product name of a YubiKey

Parameters:
Return type:

str

yubikit.yubiotp module

class yubikit.yubiotp.SLOT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

ONE = 1
TWO = 2
static map(slot, one, two)[source]
Return type:

TypeVar(T)

class yubikit.yubiotp.CONFIG_SLOT(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

CONFIG_1 = 1
NAV = 2
CONFIG_2 = 3
UPDATE_1 = 4
UPDATE_2 = 5
SWAP = 6
NDEF_1 = 8
NDEF_2 = 9
DEVICE_SERIAL = 16
DEVICE_CONFIG = 17
SCAN_MAP = 18
YK4_CAPABILITIES = 19
YK4_SET_DEVICE_INFO = 21
CHAL_OTP_1 = 32
CHAL_OTP_2 = 40
CHAL_HMAC_1 = 48
CHAL_HMAC_2 = 56
class yubikit.yubiotp.TKTFLAG(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

TAB_FIRST = 1
APPEND_TAB1 = 2
APPEND_TAB2 = 4
APPEND_DELAY1 = 8
APPEND_DELAY2 = 16
APPEND_CR = 32
PROTECT_CFG2 = 128
OATH_HOTP = 64
CHAL_RESP = 64
class yubikit.yubiotp.CFGFLAG(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

SEND_REF = 1
PACING_10MS = 4
PACING_20MS = 8
STATIC_TICKET = 32
TICKET_FIRST = 2
ALLOW_HIDTRIG = 16
SHORT_TICKET = 2
STRONG_PW1 = 16
STRONG_PW2 = 64
MAN_UPDATE = 128
OATH_HOTP8 = 2
OATH_FIXED_MODHEX1 = 16
OATH_FIXED_MODHEX2 = 64
OATH_FIXED_MODHEX = 80
OATH_FIXED_MASK = 80
CHAL_YUBICO = 32
CHAL_HMAC = 34
HMAC_LT64 = 4
CHAL_BTN_TRIG = 8
class yubikit.yubiotp.EXTFLAG(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

SERIAL_BTN_VISIBLE = 1
SERIAL_USB_VISIBLE = 2
SERIAL_API_VISIBLE = 4
USE_NUMERIC_KEYPAD = 8
FAST_TRIG = 16
ALLOW_UPDATE = 32
DORMANT = 64
LED_INV = 128
class yubikit.yubiotp.NDEF_TYPE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

TEXT = 84
URI = 85
class yubikit.yubiotp.CFGSTATE(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntFlag

SLOT1_VALID = 1
SLOT2_VALID = 2
SLOT1_TOUCH = 4
SLOT2_TOUCH = 8
LED_INV = 16
class yubikit.yubiotp.SlotConfiguration[source]

Bases: object

is_supported_by(version)[source]
Return type:

bool

get_config(acc_code=None)[source]
Return type:

bytes

serial_api_visible(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

serial_usb_visible(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

allow_update(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

dormant(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

invert_led(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

protect_slot2(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.HmacSha1SlotConfiguration(key)[source]

Bases: SlotConfiguration

is_supported_by(version)[source]
require_touch(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

lt64(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.KeyboardSlotConfiguration[source]

Bases: SlotConfiguration

append_cr(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

fast_trigger(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

pacing(pacing_10ms=False, pacing_20ms=False)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

use_numeric(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.HotpSlotConfiguration(key)[source]

Bases: KeyboardSlotConfiguration

is_supported_by(version)[source]
digits8(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

token_id(token_id, fixed_modhex1=False, fixed_modhex2=True)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

imf(imf)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.StaticPasswordSlotConfiguration(scan_codes)[source]

Bases: KeyboardSlotConfiguration

is_supported_by(version)[source]
class yubikit.yubiotp.YubiOtpSlotConfiguration(fixed, uid, key)[source]

Bases: KeyboardSlotConfiguration

tabs(before=False, after_first=False, after_second=False)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

delay(after_first=False, after_second=False)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

send_reference(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.StaticTicketSlotConfiguration(fixed, uid, key)[source]

Bases: KeyboardSlotConfiguration

short_ticket(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

strong_password(upper_case=False, digit=False, special=False)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

manual_update(value)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.UpdateConfiguration[source]

Bases: KeyboardSlotConfiguration

is_supported_by(version)[source]
protect_slot2(value)[source]
tabs(before=False, after_first=False, after_second=False)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

delay(after_first=False, after_second=False)[source]
Return type:

TypeVar(Cfg, bound= SlotConfiguration)

class yubikit.yubiotp.ConfigState(version, touch_level)[source]

Bases: object

The configuration state of the YubiOTP application.

is_configured(slot)[source]

Checks of a slot is programmed, or empty

Return type:

bool

is_touch_triggered(slot)[source]

Checks if a (programmed) state is triggered by touch (not challenge-response) Requires YubiKey 3 or later.

Return type:

bool

is_led_inverted()[source]

Checks if the LED behavior is inverted.

Return type:

bool

class yubikit.yubiotp.YubiOtpSession(connection, scp_key_params=None)[source]

Bases: object

A session with the YubiOTP application.

close()[source]

Close the underlying connection.

Deprecated:

call .close() on the underlying connection instead.

Return type:

None

property version: Version

The version of the Yubico OTP application, typically the same as the YubiKey firmware.

get_serial()[source]

Get serial number.

Return type:

int

get_config_state()[source]

Get configuration state of the YubiOTP application.

Return type:

ConfigState

put_configuration(slot, configuration, acc_code=None, cur_acc_code=None)[source]

Write configuration to slot.

Parameters:
Return type:

None

update_configuration(slot, configuration, acc_code=None, cur_acc_code=None)[source]

Update configuration in slot.

Parameters:
Return type:

None

swap_slots()[source]

Swap the two slot configurations.

Return type:

None

delete_slot(slot, cur_acc_code=None)[source]

Delete configuration stored in slot.

Parameters:

  • slot (SLOT) – The slot to delete the configuration in.

  • cur_acc_code (Optional[bytes]) – The current access code.

Return type:

None

set_scan_map(scan_map, cur_acc_code=None)[source]

Update scan-codes on YubiKey.

This updates the scan-codes (or keyboard presses) that the YubiKey will use when typing out OTPs.

Return type:

None

set_ndef_configuration(slot, uri=None, cur_acc_code=None, ndef_type=NDEF_TYPE.URI)[source]

Configure a slot to be used over NDEF (NFC).

Parameters:

  • slot (SLOT) – The slot to configure.

  • uri (Optional[str]) – URI or static text.

  • cur_acc_code (Optional[bytes]) – The current access code.

  • ndef_type (NDEF_TYPE) – The NDEF type (text or URI).

Return type:

None

calculate_hmac_sha1(slot, challenge, event=None, on_keepalive=None)[source]

Perform a challenge-response operation using HMAC-SHA1.

Parameters:

  • slot (SLOT) – The slot to perform the operation against.

  • challenge (bytes) – The challenge.

  • event (Optional[Event]) – An event.

Return type:

bytes

Module contents

Contains the modules corresponding to the different applications supported by a YubiKey.