ykman package

Subpackages

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_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.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.diagnostics module

ykman.diagnostics.sys_info()[source]
ykman.diagnostics.mgmt_info(pid, conn)[source]
ykman.diagnostics.piv_info(conn)[source]
ykman.diagnostics.openpgp_info(conn)[source]
ykman.diagnostics.oath_info(conn)[source]
ykman.diagnostics.hsmauth_info(conn)[source]
ykman.diagnostics.ccid_info()[source]
ykman.diagnostics.otp_info()[source]
ykman.diagnostics.fido_info()[source]
ykman.diagnostics.get_diagnostics()[source]

Runs diagnostics.

The result of this can be printed using pretty_print.

ykman.fido module

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.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_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.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.hsmauth module

ykman.hsmauth.get_hsmauth_info(session)[source]

Get information about the YubiHSM Auth application.

ykman.hsmauth.generate_random_management_key()[source]

Generate a new random management key.

Return type:

bytes

ykman.logging module

ykman.logging.set_log_level(level)[source]
ykman.logging.init_logging(log_level, log_file=None, replace=False)[source]

ykman.logging_setup module

ykman.logging_setup.log_sys_info(log)[source]
ykman.logging_setup.setup(log_level_name, log_file=None)[source]

ykman.oath module

ykman.oath.is_hidden(credential)[source]

Check if OATH credential is hidden.

Return type:

bool

ykman.oath.is_steam(credential)[source]

Check if OATH credential is steam.

Return type:

bool

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

Calculate steam codes.

Return type:

str

ykman.oath.is_in_fips_mode(app)[source]

Check if OATH application is in FIPS mode.

Return type:

bool

ykman.oath.delete_broken_credential(app)[source]

Checks for credential in a broken state and deletes it.

Return type:

bool

ykman.openpgp module

ykman.openpgp.safe_reset(connection)[source]

Performs an OpenPGP factory reset while avoiding any unneccessary commands.

If any data is unreadable preventing the OpenPgpSession from initializing, then OpenPgpSession.reset() will not be able to be called. This function can instead be used to reset the application into a fresh state.

Return type:

None

ykman.openpgp.get_key_info(discretionary, ref, status)[source]
ykman.openpgp.get_openpgp_info(session)[source]

Get human readable information about the OpenPGP configuration.

Parameters:

session (OpenPgpSession) – The OpenPGP session.

ykman.otp module

ykman.otp.is_in_fips_mode(session)[source]

Check if the OTP application of a FIPS YubiKey is in FIPS approved mode.

Parameters:

session (YubiOtpSession) – The YubiOTP session.

Return type:

bool

ykman.otp.generate_static_pw(length, keyboard_layout=KEYBOARD_LAYOUT.MODHEX, blocklist=['\\t', '\\n', ' '])[source]

Generate a random password.

Parameters:

  • length (int) – The length of the password.

  • keyboard_layout (KEYBOARD_LAYOUT) – The keyboard layout.

  • blocklist (Iterable[str]) – The list of characters to block.

Return type:

str

ykman.otp.parse_oath_key(val)[source]

Parse a secret key encoded as either Hex or Base32.

Parameters:

val (str) – The secret key.

Return type:

bytes

ykman.otp.format_oath_code(response, digits=6)[source]

Format an OATH code from a hash response.

Parameters:

  • response (bytes) – The response.

  • digits (int) – The number of digits in the OATH code.

Return type:

str

ykman.otp.time_challenge(timestamp, period=30)[source]

Format a HMAC-SHA1 challenge based on an OATH timestamp and period.

Parameters:

  • timestamp (int) – The timestamp.

  • period (int) – The period.

Return type:

bytes

ykman.otp.format_csv(serial, public_id, private_id, key, access_code=None, timestamp=None)[source]

Produce a CSV line in the “Yubico” format.

Parameters:

  • serial (int) – The serial number.

  • public_id (bytes) – The public ID.

  • private_id (bytes) – The private ID.

  • key (bytes) – The secret key.

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

Return type:

str

ykman.piv module

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.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_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

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

Bases: object

property puk_blocked: bool
property mgm_key_protected: bool
property has_protected_key: bool
property has_derived_key: bool
property has_stored_key: bool
get_bytes()[source]
Return type:

bytes

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

Bases: object

get_bytes()[source]
Return type:

bytes

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.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_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_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.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.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.generate_chuid()[source]

Generate a CHUID (Cardholder Unique Identifier).

Return type:

bytes

ykman.piv.generate_ccc()[source]

Generate a CCC (Card Capability Container).

Return type:

bytes

ykman.piv.get_piv_info(session)[source]

Get human readable information about the PIV configuration.

Parameters:

session (PivSession) – The PIV session.

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.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.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.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.

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

fido()[source]

Establish a FIDO connection.

Return type:

CtapDevice

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.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.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

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.settings module

class ykman.settings.Settings(name)[source]

Bases: dict

write()[source]
ykman.settings.Configuration

alias of Settings

exception ykman.settings.KeystoreError[source]

Bases: Exception

Error accessing the OS keystore

exception ykman.settings.UnwrapValueError[source]

Bases: Exception

Error unwrapping a particular secret value

class ykman.settings.AppData(name, keyring_service='ykman', keyring_key='wrap_key')[source]

Bases: Settings

property keyring_unlocked: bool
ensure_unlocked()[source]
get_secret(key)[source]
put_secret(key, value)[source]
Return type:

None

ykman.util module

exception ykman.util.InvalidPasswordError[source]

Bases: Exception

Raised when parsing key/certificate and the password might be wrong/missing.

ykman.util.parse_private_key(data, password)[source]

Identify, decrypt and return a cryptography private key object.

Parameters:

  • data – The private key in bytes.

  • password – The password to decrypt the private key (if it is encrypted).

ykman.util.parse_certificates(data, password)[source]

Identify, decrypt and return a list of cryptography x509 certificates.

Parameters:

  • data – The certificate(s) in bytes.

  • password – The password to decrypt the certificate(s).

ykman.util.get_leaf_certificates(certs)[source]

Extract the leaf certificates from a list of certificates.

Leaf certificates are ones whose subject does not appear as issuer among the others.

Parameters:

certs – The list of cryptography x509 certificate objects.

ykman.util.is_pem(data)[source]
ykman.util.is_pkcs12(data)[source]

Tries to identify a PKCS12 container. The PFX PDU version is assumed to be v3. See: https://tools.ietf.org/html/rfc7292.

ykman.util.display_serial(serial)[source]

Displays an x509 certificate serial number in a readable format.

Return type:

str

class ykman.util.OSVERSIONINFOW[source]

Bases: Structure

dwBuildNumber

Structure/Union member

dwMajorVersion

Structure/Union member

dwMinorVersion

Structure/Union member

dwOSVersionInfoSize

Structure/Union member

dwPlatformId

Structure/Union member

szCSDVersion

Structure/Union member

ykman.util.get_windows_version()[source]

Get the true Windows version, since sys.getwindowsversion lies.

Return type:

Tuple[int, int, int]

ykman.util.is_nfc_restricted(connection)[source]

Check if the given SmartCardConnection over NFC is in restricted NFC mode.

Return type:

bool

Module contents