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.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]
class ykman.settings.Configuration(name)[source]

Bases: 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]

Module contents