ykman package

Submodules

ykman.base module

class ykman.base.YkmanDevice(transport, fingerprint, pid)[source]

Bases: YubiKeyDevice

YubiKey device reference, with optional PID

property pid: PID | None

Return the PID of the YubiKey, if available.

ykman.device module

ykman.device.list_all_devices(connection_types=dict_keys([<class 'yubikit.core.smartcard.SmartCardConnection'>, <class 'yubikit.core.otp.OtpConnection'>, <class 'fido2.ctap.CtapDevice'>]))[source]

Connect to all attached YubiKeys and read device info from them.

Parameters:

connection_types (Iterable[Type[Connection]]) – An iterable of YubiKey connection types.

Return type:

List[Tuple[YkmanDevice, DeviceInfo]]

Returns:

A list of (device, info) tuples for each connected device.

ykman.device.list_ccid_devices()[source]
ykman.device.list_ctap_devices()[source]
ykman.device.list_otp_devices()[source]
ykman.device.scan_devices()[source]

Scan USB for attached YubiKeys, without opening any connections.

Return type:

Tuple[Mapping[PID, int], int]

Returns:

A dict mapping PID to device count, and a state object which can be used to detect changes in attached devices.

ykman.fido module

ykman.fido.fips_change_pin(fido_connection, old_pin, new_pin)[source]

Change the PIN on a YubiKey 4 FIPS.

If no PIN is set, pass None or an empty string as old_pin.

Parameters:
  • fido_connection (CtapDevice) – A FIDO connection.

  • old_pin (Optional[str]) – The old PIN.

  • new_pin (str) – The new PIN.

ykman.fido.fips_reset(fido_connection)[source]

Reset the FIDO module of a YubiKey 4 FIPS.

Note: This action is only permitted immediately after YubiKey power-up. It also requires the user to touch the flashing button on the YubiKey, and will halt until that happens, or the command times out.

Parameters:

fido_connection (CtapDevice) – A FIDO connection.

ykman.fido.fips_verify_pin(fido_connection, pin)[source]

Unlock the YubiKey 4 FIPS U2F module for credential creation.

Parameters:
  • fido_connection (CtapDevice) – A FIDO connection.

  • pin (str) – The FIDO PIN.

ykman.fido.is_in_fips_mode(fido_connection)[source]

Check if a YubiKey 4 FIPS is in FIPS approved mode.

Parameters:

fido_connection (CtapDevice) – A FIDO connection.

Return type:

bool

ykman.hsmauth module

ykman.hsmauth.generate_random_management_key()[source]

Generate a new random management key.

Return type:

bytes

ykman.hsmauth.get_hsmauth_info(session)[source]

Get information about the YubiHSM Auth application.

ykman.oath module

ykman.oath.calculate_steam(app, credential, timestamp=None)[source]

Calculate steam codes.

Return type:

str

ykman.oath.delete_broken_credential(app)[source]

Checks for credential in a broken state and deletes it.

Return type:

bool

ykman.oath.is_hidden(credential)[source]

Check if OATH credential is hidden.

Return type:

bool

ykman.oath.is_in_fips_mode(app)[source]

Check if OATH application is in FIPS mode.

Return type:

bool

ykman.oath.is_steam(credential)[source]

Check if OATH credential is steam.

Return type:

bool

ykman.openpgp module

ykman.openpgp.get_openpgp_info(session)[source]

Get human readable information about the OpenPGP configuration.

Parameters:

session (OpenPgpSession) – The OpenPGP session.

ykman.piv module

class ykman.piv.PivmanData(raw_data=Tlv(tag=0x80, value=))[source]

Bases: object

get_bytes()[source]
Return type:

bytes

property has_derived_key: bool
property has_protected_key: bool
property has_stored_key: bool
property mgm_key_protected: bool
property puk_blocked: bool
class ykman.piv.PivmanProtectedData(raw_data=Tlv(tag=0x88, value=))[source]

Bases: object

get_bytes()[source]
Return type:

bytes

ykman.piv.check_key(session, slot, public_key)[source]

Check that a given public key corresponds to the private key in a slot.

This will create a signature using the private key, so the PIN must be verified prior to calling this function if the PIN policy requires it.

Parameters:
Return type:

bool

ykman.piv.derive_management_key(pin, salt)[source]

Derive a management key from the users PIN and a salt.

NOTE: This method of derivation is deprecated! Protect the management key using PivmanProtectedData instead.

Parameters:
  • pin (str) – The PIN.

  • salt (bytes) – The salt.

Return type:

bytes

ykman.piv.generate_ccc()[source]

Generate a CCC (Card Capability Container).

Return type:

bytes

ykman.piv.generate_chuid()[source]

Generate a CHUID (Cardholder Unique Identifier).

Return type:

bytes

ykman.piv.generate_csr(session, slot, public_key, subject_str, hash_algorithm=<class 'cryptography.hazmat.primitives.hashes.SHA256'>)[source]

Generate a CSR using a private key in a slot.

Parameters:
Return type:

CertificateSigningRequest

ykman.piv.generate_random_management_key(algorithm)[source]

Generate a new random management key.

Parameters:

algorithm (MANAGEMENT_KEY_TYPE) – The algorithm for the management key.

Return type:

bytes

ykman.piv.generate_self_signed_certificate(session, slot, public_key, subject_str, valid_from, valid_to, hash_algorithm=<class 'cryptography.hazmat.primitives.hashes.SHA256'>)[source]

Generate a self-signed certificate using a private key in a slot.

Parameters:
Return type:

Certificate

ykman.piv.get_piv_info(session)[source]

Get human readable information about the PIV configuration.

Parameters:

session (PivSession) – The PIV session.

ykman.piv.get_pivman_data(session)[source]

Read out the Pivman data from a YubiKey.

Parameters:

session (PivSession) – The PIV session.

Return type:

PivmanData

ykman.piv.get_pivman_protected_data(session)[source]

Read out the Pivman protected data from a YubiKey.

This function requires PIN verification prior to being called.

Parameters:

session (PivSession) – The PIV session.

Return type:

PivmanProtectedData

ykman.piv.list_certificates(session)[source]

Read out and parse stored certificates.

Only certificates which are successfully parsed are returned.

Parameters:

session (PivSession) – The PIV session.

Return type:

Mapping[SLOT, Optional[Certificate]]

ykman.piv.parse_rfc4514_string(value)[source]

Parse an RFC 4514 string into a x509.Name.

See: https://tools.ietf.org/html/rfc4514.html

Parameters:

value (str) – An RFC 4514 string.

Return type:

Name

ykman.piv.pivman_change_pin(session, old_pin, new_pin)[source]

Change the PIN, while keeping PivmanData in sync.

Parameters:
  • session (PivSession) – The PIV session.

  • old_pin (str) – The old PIN.

  • new_pin (str) – The new PIN.

Return type:

None

ykman.piv.pivman_set_mgm_key(session, new_key, algorithm, touch=False, store_on_device=False)[source]

Set a new management key, while keeping PivmanData in sync.

Parameters:
  • session (PivSession) – The PIV session.

  • new_key (bytes) – The new management key.

  • algorithm (MANAGEMENT_KEY_TYPE) – The algorithm for the management key.

  • touch (bool) – If set, touch is required.

  • store_on_device (bool) – If set, the management key is stored on device.

Return type:

None

ykman.piv.pivman_set_pin_attempts(session, pin_attempts, puk_attempts)[source]

Set the number of PIN and PUK retry attempts, while keeping PivmanData in sync.

Parameters:
  • session (PivSession) – The PIV session.

  • pin_attempts (int) – The PIN attempts.

  • puk_attempts (int) – The PUK attempts.

Return type:

None

ykman.piv.sign_certificate_builder(session, slot, key_type, builder, hash_algorithm=<class 'cryptography.hazmat.primitives.hashes.SHA256'>)[source]

Sign a Certificate.

Parameters:
Return type:

Certificate

ykman.piv.sign_csr_builder(session, slot, public_key, builder, hash_algorithm=<class 'cryptography.hazmat.primitives.hashes.SHA256'>)[source]

Sign a CSR.

Parameters:
Return type:

CertificateSigningRequest

ykman.scripting module

class ykman.scripting.ScriptingDevice(wrapped, info)[source]

Bases: object

Scripting-friendly proxy for YkmanDevice.

This wrapper adds some helpful utility methods useful for scripting.

fido()[source]

Establish a FIDO connection.

Return type:

CtapDevice

property info: DeviceInfo
property name: str
otp()[source]

Establish a OTP connection.

Return type:

OtpConnection

smart_card()[source]

Establish a Smart Card connection.

Return type:

SmartCardConnection

ykman.scripting.multi(*, ignore_duplicates=True, allow_initial=False, prompt=True)[source]

Connect to multiple YubiKeys.

Parameters:
  • ignore_duplicates (bool) – When set, duplicates are ignored.

  • allow_initial (bool) – When set, YubiKeys can be connected at the start of the function call.

  • prompt (bool) – When set, you will be prompted to insert a YubiKey.

Return type:

Generator[ScriptingDevice, None, None]

ykman.scripting.multi_nfc(reader='', *, ignore_duplicates=True, allow_initial=False, prompt=True)[source]

Connect to multiple YubiKeys over NFC.

Parameters:
  • reader – The name of the NFC reader.

  • ignore_duplicates – When set, duplicates are ignored.

  • allow_initial – When set, YubiKeys can be connected at the start of the function call.

  • prompt – When set, you will be prompted to place YubiKeys on the NFC reader.

Return type:

Generator[ScriptingDevice, None, None]

ykman.scripting.single(*, prompt=True)[source]

Connect to a YubiKey.

Parameters:

prompt – When set, you will be prompted to insert a YubiKey.

Return type:

ScriptingDevice

ykman.scripting.single_nfc(reader='', *, prompt=True)[source]

Connect to a YubiKey over NFC.

Parameters:
  • reader – The name of the NFC reader.

  • prompt – When set, you will prompted to place a YubiKey on NFC reader.

Return type:

ScriptingDevice

Module contents