YubiKey Manager

https://github.com/yubico/yubikey-manager
Admin
YubiKey Manager is a Python library and command-line tool for configuring and managing YubiKey...
Tokens:124,789
Snippets:714
Trust Score:9.5
License:BSD-2-Clause
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and set up pre-commit

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Development.adoc

Install pre-commit and set up the hook for code style and security linting.

```shell
$ uv tool install pre-commit
$ pre-commit install
```

--------------------------------

### Example: get_openpgp_info usage

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.openpgp.md

Example usage of get_openpgp_info to retrieve and print OpenPGP version, application version, and PIN tries remaining.

```python
from yubikit.core.smartcard import SmartCardConnection
from yubikit.openpgp import OpenPgpSession
from ykman.openpgp import get_openpgp_info

with yubikey.open_connection(SmartCardConnection) as conn:
    session = OpenPgpSession(conn)
    info = get_openpgp_info(session)
    print(info["OpenPGP version"], info["Application version"])
    print("PIN tries remaining:", info["PIN tries remaining"])
```

--------------------------------

### Example: safe_reset usage

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.openpgp.md

Example usage of safe_reset to perform a factory reset even when the applet data is unreadable.

```python
from yubikit.core.smartcard import SmartCardConnection
from ykman.openpgp import safe_reset

# Reset even when the applet data is unreadable
with yubikey.open_connection(SmartCardConnection) as conn:
    safe_reset(conn)
```

--------------------------------

### Parse PEM key and certificates

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.util.md

Example showing how to parse a private key and certificates from PEM files, then get the leaf certificate and print its subject and serial.

```python
from ykman.util import parse_certificates, parse_private_key

with open("key.pem", "rb") as f:
    key = parse_private_key(f.read(), password=None)

with open("chain.pem", "rb") as f:
    certs = parse_certificates(f.read(), password=None)
leaf = get_leaf_certificates(certs)[0]

print("Leaf subject:", leaf.subject)
print("Serial:", display_serial(leaf.serial_number))
```

--------------------------------

### PIV session example with ykman.scripting

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.scripting.md

Example from the Examples section: waits for a single YubiKey, prints its name (e.g. "YubiKey 5 NFC (123456)"), opens a smart card connection, and prints the PIV version using PivSession.

```python
from ykman import scripting as s
from yubikit.piv import PivSession, SLOT

yubikey = s.single()
print("Using:", yubikey)          # e.g. "YubiKey 5 NFC (123456)"

with yubikey.smart_card() as conn:
    session = PivSession(conn)
    print("PIV version:", session.version)
```

--------------------------------

### Install dependencies on Debian-based Linux

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Development.adoc

Install swig and related dependencies on Debian-based Linux distributions using apt.

```shell
$ sudo apt install swig libu2f-udev pcscd libpcsclite-dev
```

--------------------------------

### Verify ykman import with python -c

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Library_Usage.adoc

Run this command to confirm ykman is installed and importable. If it runs without error and produces no output, the setup is correct.

```bash
$ python -c "import ykman"
```

--------------------------------

### Configure YubiOTP slot and export CSV

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.otp.md

Example showing how to configure a YubiOTP slot with random keys and print a Yubico-format CSV row.

```python
import os
from ykman.otp import format_csv
from yubikit.yubiotp import SLOT, YubiOtpSession, YubiOtpSlotConfiguration

with yubikey.open_connection(OtpConnection) as conn:
    session = YubiOtpSession(conn)
    serial = session.get_serial()
    public_id = b"\x00\x00" + serial.to_bytes(4, "big")
    private_id = os.urandom(6)
    key = os.urandom(16)
    session.put_configuration(
        SLOT.TWO,
        YubiOtpSlotConfiguration(public_id, private_id, key).append_cr(True),
    )
    # Yubico-format CSV row for a validation server
    print(format_csv(serial, public_id, private_id, key))
```

--------------------------------

### PIV session setup and key generation

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.piv.md

Opens a SmartCardConnection, creates a PivSession, authenticates with the default management key, verifies the PIN, and generates an RSA2048 key in the authentication slot with a one-time PIN policy. Prints the PIV version, management key type, and generated key, and retrieves the capability object.

```python
from yubikit.core.smartcard import SmartCardConnection
from yubikit.piv import DEFAULT_MANAGEMENT_KEY, KEY_TYPE, PIN_POLICY, PivSession, SLOT

with yubikey.open_connection(SmartCardConnection) as conn:
    session = PivSession(conn)
    print("PIV version:", session.version)
    print("Management key type:", session.management_key_type)

    session.authenticate(DEFAULT_MANAGEMENT_KEY)
    session.verify_pin("123456")

    pub_key = session.generate_key(
        SLOT.AUTHENTICATION, KEY_TYPE.RSA2048,
        pin_policy=PIN_POLICY.ONCE,
    )
    print("Generated key:", pub_key)
    cert_info = bytes(session.get_object(OBJECT_ID.CAPABILITY))
```

--------------------------------

### First script: print Hello from ykman

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Scripting.adoc

First script example: creates myscript.py that prints a message, runs it with ykman script, and shows the expected terminal output.

```python
print("Hello, from ykman!")
```

```bash
ykman script myscript.py
```

```text
> ykman script myscript.py
Hello, from ykman!
>
```

--------------------------------

### Example: U2F call via FidoConnection

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.core-fido.md

Shows opening a FidoConnection with yubikey.open_connection and sending a U2F APDU directly using CTAPHID.MSG.

```python
from yubikit.core.fido import FidoConnection
from fido2.hid import CTAPHID

# U2F-style direct APDU over HID
with yubikey.open_connection(FidoConnection) as fido:
    resp = fido.call(CTAPHID.MSG, b"\x00\x03\x00\x00\x00\x00\x00")
```

--------------------------------

### Install YubiKey Manager on FreeBSD with pkg

Source: https://github.com/yubico/yubikey-manager/blob/main/README.adoc

Install the FreeBSD binary package for YubiKey Manager, built for Python 3.8. Replace 'py38' with the appropriate Python version (e.g., py39, py310) as needed.

```shell
# pkg install py38-yubikey-manager
```

--------------------------------

### Example: CTAP2 GET_INFO over NFC via SmartCardCtapDevice

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.core-fido.md

Shows wrapping a SmartCardConnection with SmartCardCtapDevice to perform a CTAP2 GET_INFO call (CTAPHID.CBOR, b'\x04') over NFC.

```python
from yubikit.core.fido import SmartCardCtapDevice
from yubikit.core.smartcard import SmartCardConnection

# CTAP2 over NFC: wrap a smart card connection
with yubikey.open_connection(SmartCardConnection) as conn:
    ctap = SmartCardCtapDevice(conn)
    # call GET_INFO (CTAPHID.CBOR, b"\x04")
    info = ctap.call(0x10, b"\x04")
```

--------------------------------

### Batch programming with s.multi

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.scripting.md

Batch-programming example: uses s.multi(allow_initial=True) to iterate over newly inserted YubiKeys, printing each device and opening an OTP connection to configure slots. The loop ends when interrupted with Ctrl+C.

```python
# Batch-program multiple YubiKeys (pattern from examples/yubiotp_batch.py)
from ykman import scripting as s

print("Insert YubiKeys one at a time, Ctrl+C when done")
for device in s.multi(allow_initial=True):
    print("Programming:", device)
    with device.otp() as conn:
        ...  # configure slots
```

--------------------------------

### Run a YubiKey script with ykman or Python

Source: https://github.com/yubico/yubikey-manager/blob/main/examples/README.adoc

Two ways to run example scripts: pass the script to the ykman tool, or run it with the standard Python interpreter (requires ykman and its dependencies to be available).

```bash
ykman script script_file.py [args...]
```

```bash
python script_file.py [args...]
```

--------------------------------

### Generate static password and encode to scan codes

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.otp.md

Example showing how to generate a random static password using the US layout and encode it to scan codes.

```python
from ykman.otp import format_csv, generate_static_pw, parse_oath_key
from ykman.scancodes import KEYBOARD_LAYOUT, encode

# Random static password over the US layout
password = generate_static_pw(38, KEYBOARD_LAYOUT.US)
scan_codes = encode(password, KEYBOARD_LAYOUT.US)
```

--------------------------------

### Add credential and get challenge with HsmAuthSession

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.hsmauth.md

Opens a smart card connection and uses HsmAuthSession to add a credential with derived keys and generate a host challenge. The default management key is all zeros. The credential label and algorithm name are printed after adding, and the challenge is printed as hex.

```python
from yubikit.hsmauth import HsmAuthSession

with yubikey.open_connection(SmartCardConnection) as conn:
    session = HsmAuthSession(conn)
    mgmt_key = b"\x00" * 16  # default management key

    cred = session.put_credential_derived(
        mgmt_key, "my-creds", "derivation-pass", "credential-pass"
    )
    print("Added:", cred.label, cred.algorithm.name)
    challenge = session.get_challenge("my-creds", "credential-pass")
    print("Host challenge:", challenge.hex())
```

--------------------------------

### Read info and get name over NFC

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.support.md

Example of using read_info and get_name over NFC. PID is omitted and key type is guessed. The example prints the name and serial.

```python
# Over NFC the PID is unknown; read_info infers what it can
with nfc_yubikey.open_connection(SmartCardConnection) as conn:
    info = read_info(conn)          # pid omitted - NFC
    name = get_name(info, None)     # key type guessed
    print(name, info.serial)
```

--------------------------------

### Settings.__init__(name)

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.settings.md

Initializes a Settings instance, loading the JSON file from the config directory if it exists. Corrupt or unreadable files are ignored with a warning.

```APIDOC
## Settings.__init__(name)

### Description
Initializes a Settings instance, loading the JSON file from the config directory if it exists. Corrupt or unreadable files are ignored with a warning.

### Method
Constructor

### Parameters
- **name** (str) - Required - The name of the settings file (without extension).

### Response
Returns a new Settings instance.

```

--------------------------------

### Read info and get name over USB

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.support.md

Example of using read_info and get_name over USB. PID is required for non-NFC connections. The example prints the serial, version, and product name.

```python
from yubikit.support import read_info, get_name

# Over USB: PID is required
with yubikey.open_connection(SmartCardConnection) as conn:
    info = read_info(conn, yubikey.pid)
    print("Serial:", info.serial, "Version:", info.version)
    print("Name:", get_name(info, yubikey.pid.yubikey_type))
```

--------------------------------

### AppData.__init__(name, keyring_service=KEYRING_SERVICE, keyring_key=KEYRING_KEY)

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.settings.md

Initializes an AppData instance, loading the JSON file from the data directory and configuring the keyring service and username for secret storage.

```APIDOC
## AppData.__init__(name, keyring_service=KEYRING_SERVICE, keyring_key=KEYRING_KEY)

### Description
Initializes an AppData instance, loading the JSON file from the data directory and configuring the keyring service and username for secret storage.

### Method
Constructor

### Parameters
- **name** (str) - Required - The name of the data file (without extension).
- **keyring_service** (str) - Optional - The OS keyring service name. Defaults to KEYRING_SERVICE.
- **keyring_key** (str) - Optional - The keyring username/key holding the secret-wrap key. Defaults to KEYRING_KEY.

### Response
Returns a new AppData instance.

```

--------------------------------

### Install yubikey-manager with pip

Source: https://github.com/yubico/yubikey-manager/blob/main/README.adoc

Installs YubiKey Manager via pip for the current user. On Linux, pcscd must be installed and running for SmartCard communication, and additional permissions may be needed for HID access.

```bash
pip install --user yubikey-manager
```

--------------------------------

### Version and PID usage

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.core.md

Demonstrates parsing a firmware version string, introspecting a PID's yubikey_type and usb_interfaces, and building a PID from parts using PID.of.

```python
from yubikit.core import PID, TRANSPORT, USB_INTERFACE, YUBIKEY, Version

# Parse a firmware version from a device string
v = Version.from_string("YubiKey 5.7.1 (5.7.1)")
assert v >= (5, 0, 0)

# PID introspection
pid = PID.YK4_OTP_FIDO_CCID
print(pid.yubikey_type)     # YUBIKEY.YK4
print(pid.usb_interfaces)   # 0x07 (OTP | FIDO | CCID)

# Build a PID from parts
pid2 = PID.of(YUBIKEY.NEO, USB_INTERFACE.OTP | USB_INTERFACE.CCID)
assert pid2 == PID.NEO_OTP_CCID
```

--------------------------------

### Install swig on macOS

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Development.adoc

Install swig on macOS using Homebrew. Required for development on macOS.

```shell
$ brew install swig
```

--------------------------------

### ScriptingDevice.__init__(self, wrapped, info)

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.scripting.md

Initializes a ScriptingDevice proxy wrapping a YkmanDevice and its DeviceInfo.

```APIDOC
## ScriptingDevice.__init__

### Description
Initializes a new ScriptingDevice instance.

### Method
Constructor

### Parameters
- **wrapped** (YkmanDevice) - Required - The underlying YkmanDevice to wrap.
- **info** (DeviceInfo) - Required - The device information.

### Response
None
```

--------------------------------

### HsmAuthSession.__init__

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.hsmauth.md

Initializes a new HsmAuthSession instance. It selects the HSMAUTH AID, reads the application version, configures the protocol, and initializes SCP if scp_key_params is provided.

```APIDOC
## HsmAuthSession.__init__

### Description
Initializes a new HsmAuthSession instance. It selects the HSMAUTH AID, reads the application version, configures the protocol, and initializes SCP if scp_key_params is provided.

### Method
Constructor

### Parameters
- **connection** (SmartCardConnection) - Required - The smart card connection to use.
- **scp_key_params** (ScpKeyParams | None) - Optional - SCP key parameters for secure channel setup.

```

--------------------------------

### Install dependencies on RPM-based Linux

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Development.adoc

Install dependencies on RPM-based Linux distributions using dnf. Tested on Fedora 34.

```shell
# Tested on Fedora 34
$ sudo dnf install pcsc-lite-devel python3-devel swig
```

--------------------------------

### Clone and enter yubikey-manager repository

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Development.adoc

Clone the yubikey-manager repository and change into the directory.

```shell
$ git clone https://github.com/Yubico/yubikey-manager.git
$ cd yubikey-manager
```

--------------------------------

### Uninstall yubikey-manager macOS .pkg

Source: https://github.com/yubico/yubikey-manager/blob/main/README.adoc

Run this command to uninstall yubikey-manager when it was installed via the macOS .pkg installer. It removes the ykman executable and its associated directory.

```shell
sudo rm -rf /usr/local/bin/ykman /usr/local/ykman
```

--------------------------------

### ManagementSession.__init__

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.management.md

Initializes a ManagementSession with a connection and optional SCP key parameters.

```APIDOC
## ManagementSession.__init__

### Description
Initializes a ManagementSession with the given connection and optional SCP key parameters. The connection selects the backend: OTP HID, smart card (CCID/NFC), or CTAP. SCP parameters are only valid with a SmartCardConnection.

### Method
Constructor

### Parameters
- **connection** (`OtpConnection | SmartCardConnection | FidoConnection`) - Required - Selects the backend: OTP HID, smart card (CCID/NFC), or CTAP.
- **scp_key_params** (`ScpKeyParams | None`) - Optional - SCP03/SCP11 parameters; only valid with `SmartCardConnection` (`ValueError` otherwise).

### Behavior Notes
- OTP backend raises `ApplicationNotAvailableError` for firmware 1.0.x–2.x (`(1,0,0) <= version < (3,0,0)`).
- Smart card backend reads the version from the MANAGEMENT AID select response, handles the NEO (3.x) case by de-selecting and falling back to the OTP AID (over NFC when the Management applet is missing), and initializes SCP when `scp_key_params` is given. SCP over a NEO (3.x) raises `ValueError("SCP is not supported")`.
- Unknown connection types raise `TypeError("Unsupported connection type")`.
```

--------------------------------

### ScriptingDevice.otp()

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.scripting.md

Opens an OtpConnection to the device, usable as a context manager.

```APIDOC
## ScriptingDevice.otp

### Description
Opens a connection to the OTP application.

### Method
Method invocation

### Parameters
None

### Response
- **OtpConnection** - A context manager for the OTP connection.
```

--------------------------------

### HsmAuthSession.get_challenge

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.hsmauth.md

Gets a challenge for a credential.

```APIDOC
## HsmAuthSession.get_challenge

### Description
Gets a challenge for a credential.

### Method
get_challenge(label, credential_password=None)

### Parameters
- **label** (str) - Required - The credential label.
- **credential_password** (bytes | str | None) - Optional - The credential password.

### Returns
- **bytes** - The challenge.

```

--------------------------------

### Basic usage of Settings and AppData

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.settings.md

Shows basic usage of Settings for plain JSON storage and AppData for secret storage with the OS keyring.

```python
from ykman.settings import Settings, AppData

# Plain settings
settings = Settings("my-app")
settings["enabled"] = True
settings.write()

# Secret storage backed by the OS keyring
app = AppData("oath")
app.put_secret("serial:123456", "derived-password")
value = app.get_secret("serial:123456")
```

--------------------------------

### ManagementSession.version

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.management.md

Gets the firmware version of the YubiKey.

```APIDOC
## ManagementSession.version

### Description
Gets the firmware version of the YubiKey.

### Method
Property

### Returns
- **Version** - The firmware version of the YubiKey.
```

--------------------------------

### HsmAuthSession.get_public_key

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.hsmauth.md

Gets the public key for a credential.

```APIDOC
## HsmAuthSession.get_public_key

### Description
Gets the public key for a credential.

### Method
get_public_key(label)

### Parameters
- **label** (str) - Required - The credential label.

### Returns
- **ec.EllipticCurvePublicKey** - The public key.

```

--------------------------------

### HsmAuthSession.version

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.hsmauth.md

Gets the version of the YubiHSM Auth application.

```APIDOC
## HsmAuthSession.version

### Description
Gets the version of the YubiHSM Auth application.

### Method
Property

### Returns
- **Version** - The application version.

```

--------------------------------

### HsmAuthSession.get_management_key_retries

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.hsmauth.md

Gets the number of retries remaining for the management key.

```APIDOC
## HsmAuthSession.get_management_key_retries

### Description
Gets the number of retries remaining for the management key.

### Method
get_management_key_retries()

### Parameters
None

### Returns
- **int** - The number of retries remaining.

```

--------------------------------

### OpenPgpSession

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.openpgp.md

Documentation for the OpenPgpSession class and its methods for interacting with the OpenPGP applet on a YubiKey.

```APIDOC
## OpenPgpSession

### Description
Opens a session with the OpenPGP applet on a YubiKey and provides methods for authentication, signing, key management, and PIN operations.

### Methods

#### verify_pin(pin: str) -> None
- **Description**: Verifies the user PIN.
- **Parameters**:
  - `pin` (str) - The PIN to verify.
- **Raises**: `InvalidPinError` if the PIN is incorrect.

#### sign(data: bytes, hash_algorithm: HashAlgorithm) -> bytes
- **Description**: Signs the given data using the specified hash algorithm.
- **Parameters**:
  - `data` (bytes) - The data to sign.
  - `hash_algorithm` (HashAlgorithm) - The hash algorithm to use (e.g., `hashes.SHA256()`).
- **Returns**: The signature as bytes.

#### change_pin(old_pin: str, new_pin: str) -> None
- **Description**: Changes the user PIN.
- **Parameters**:
  - `old_pin` (str) - The current PIN.
  - `new_pin` (str) - The new PIN.
- **Raises**: `InvalidPinError` if the old PIN is incorrect, `NotSupportedError` if the operation is not supported.

#### verify_admin(pin: str) -> None
- **Description**: Verifies the admin PIN.
- **Parameters**:
  - `pin` (str) - The admin PIN.

#### set_kdf(kdf: KdfIterSaltedS2k) -> None
- **Description**: Sets the KDF (Key Derivation Function) settings. This resets the PINs on the device.
- **Parameters**:
  - `kdf` (KdfIterSaltedS2k) - The KDF object created with `KdfIterSaltedS2k.create()`.

#### generate_rsa_key(key_ref: KEY_REF, rsa_size: RSA_SIZE) -> bytes
- **Description**: Generates an RSA key pair on the device.
- **Parameters**:
  - `key_ref` (KEY_REF) - The key reference (e.g., `KEY_REF.SIG`).
  - `rsa_size` (RSA_SIZE) - The RSA key size (e.g., `RSA_SIZE.RSA2048`).
- **Returns**: The public key as bytes.

#### set_uif(key_ref: KEY_REF, uif: UIF) -> None
- **Description**: Sets the User Interface (UIF) touch requirement for a key.
- **Parameters**:
  - `key_ref` (KEY_REF) - The key reference.
  - `uif` (UIF) - The UIF setting (e.g., `UIF.ON` to require touch).

#### get_fingerprints() -> dict
- **Description**: Returns a dictionary mapping key references to their fingerprints.
- **Returns**: A dictionary with `KEY_REF` keys and fingerprint bytes as values.

### Properties

- `version` (str) - The applet version.
- `aid` (bytes) - The application identifier.

### Example Usage

```python
from yubikit.openpgp import KEY_REF, OpenPgpSession

with yubikey.open_connection(SmartCardConnection) as conn:
    session = OpenPgpSession(conn)
    print("Applet version:", session.version)
    print("AID:", session.aid)

    session.verify_pin("123456")
    sig = session.sign(b"message", hashes.SHA256())
    print("Signature:", sig.hex())
```
```

--------------------------------

### SecurityDomainSession.get_data

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.securitydomain.md

Low-level GET DATA command (INS 0xCA) to retrieve data from the card.

```APIDOC
## get_data

### Description
Low-level GET DATA (INS 0xCA) to retrieve data from the card.

### Method
N/A (SDK method)

### Parameters
- **tag** (int) - Required - The tag of the data to retrieve.
- **data** (bytes) - Optional - Additional data to send with the command. Defaults to b"".

### Returns
- **bytes** - The retrieved data.
```

--------------------------------

### ykman CLI global options help output

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.cli.md

Output of `ykman --help` showing the top-level CLI group's global options. Use these options to select a YubiKey by serial or reader, configure SCP11/SCP03 secure messaging, enable logging, or show diagnostics. Note that `--reader` cannot be combined with `--device` or `list`, `--log-file` requires `--log-level`, and `--full-help` reveals hidden commands.

```text
Usage: ykman [OPTIONS] COMMAND [ARGS]...

Options:
  -d, --device SERIAL             specify which YubiKey to interact with by serial number
  -r, --reader NAME               specify a YubiKey by smart card reader name
                                  (can't be used with --device or list)
  -t, --scp-ca FILE               specify the CA to use to verify the SCP11 card key (CA-KLCC)
  -c, --scp-sd KID KVN            specify which key the YubiKey is using to authenticate
  -o, --scp-oce KID KVN           specify which key the OCE is using to authenticate
  -s, --scp CRED                  specify private key and certificate chain for secure messaging,
                                  can be used multiple times (private key, certificates in
                                  leaf-last order), OR SCP03 keys in hex separated by colon (:)
                                  K-ENC:K-MAC[:K-DEK]
  -p, --scp-password PASSWORD     specify a password required to access the --scp file, if needed
  -l, --log-level [ERROR|WARNING|INFO|DEBUG|TRAFFIC]
                                  enable logging at given verbosity level
  --log-file FILE                 write log to FILE instead of printing to stderr (requires --log-level)
  --diagnose                      show diagnostics information useful for troubleshooting
  -v, --version                   show version information about the app
  --full-help                     show --help output, including hidden commands
  -h, --help                      show this message and exit
```

--------------------------------

### generate_chuid()

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.piv.md

Generates a CHUID object with a non-Federal Issuer FASC-N, random GUID, expiration 2030-01-01 and empty signature.

```APIDOC
## generate_chuid()

### Description
Generates a CHUID object with a non-Federal Issuer FASC-N, random GUID, expiration 2030-01-01 and empty signature.

### Returns
- **bytes** - The generated CHUID object.
```

--------------------------------

### ScriptingDevice.smart_card()

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.scripting.md

Opens a SmartCardConnection to the device, usable as a context manager.

```APIDOC
## ScriptingDevice.smart_card

### Description
Opens a connection to the smart card (PIV) application.

### Method
Method invocation

### Parameters
None

### Response
- **SmartCardConnection** - A context manager for the smart card connection.
```

--------------------------------

### Handle PKCS12 with wrong password

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.util.md

Example showing how to check if data is PKCS12 and catch InvalidPasswordError when parsing with a wrong password.

```python
from ykman.util import is_pkcs12, InvalidPasswordError

data = open("keystore.p12", "rb").read()
if is_pkcs12(data):
    try:
        key, certs = parse_private_key(data, b"secret"), parse_certificates(data, b"secret")
    except InvalidPasswordError:
        print("Wrong password for PKCS12 container")
```

--------------------------------

### get_openpgp_info(session: OpenPgpSession)

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.openpgp.md

Returns a dict with human-readable OpenPGP configuration, including version information, PIN tries remaining, and per-key details.

```APIDOC
## get_openpgp_info(session: OpenPgpSession)

### Description
Returns a dict with human-readable OpenPGP configuration.

### Parameters
- **session** (OpenPgpSession) - Required - An initialized OpenPgpSession.

### Returns
A dictionary with the following keys:

| Key | Source |
|-----|--------|
| `OpenPGP version` | `session.get_application_related_data().aid.version` as `"x.y"` |
| `Application version` | `session.version` as `"x.y.z"` |
| `PIN tries remaining` / `Reset code tries remaining` / `Admin PIN tries remaining` | `PwStatus.attempts_user/reset/admin` |
| `Require PIN for signature` | `PwStatus.pin_policy_user` |
| `KDF enabled` | `not isinstance(session.get_kdf(), KdfNone)` |
| Per-key entries (`Signature key`, `Decryption key`, `Authentication key`) | `{Fingerprint, Touch policy}` for keys present per firmware rules |

### Example
```python
from yubikit.core.smartcard import SmartCardConnection
from yubikit.openpgp import OpenPgpSession
from ykman.openpgp import get_openpgp_info

with yubikey.open_connection(SmartCardConnection) as conn:
    session = OpenPgpSession(conn)
    info = get_openpgp_info(session)
    print(info["OpenPGP version"], info["Application version"])
    print("PIN tries remaining:", info["PIN tries remaining"])
```
```

--------------------------------

### TOTP challenge and OATH code formatting

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.otp.md

Example showing how to create a TOTP challenge and format an OATH code from a raw HMAC response.

```python
# TOTP-style challenge + code formatting for raw HMAC responses
from ykman.otp import format_oath_code, time_challenge
import time

challenge = time_challenge(int(time.time()), 30)
raw = session.backend.send_and_receive(SLOT.ONE, challenge, 20)  # sketch: real API differs
```

--------------------------------

### Get help for ykman oath subcommand

Source: https://github.com/yubico/yubikey-manager/blob/main/README.adoc

Displays detailed help for the oath subcommand. Use this to see options and usage for managing the OATH application.

```bash
ykman oath --help
```

--------------------------------

### Settings.write()

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.settings.md

Atomically writes the settings to a JSON file in the config directory, creating the directory with mode 0o700 if needed.

```APIDOC
## Settings.write()

### Description
Atomically writes the settings to a JSON file in the config directory, creating the directory with mode 0o700 if needed.

### Method
Method

### Parameters
None

### Response
None

```

--------------------------------

### Run unit tests

Source: https://github.com/yubico/yubikey-manager/blob/main/doc/Development.adoc

Run unit tests.

```shell
$ uv run pytest
```

--------------------------------

### YubiOtpSession

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/yubikit.yubiotp.md

The YubiOtpSession class provides methods to configure and interact with the YubiOTP application, including slot programming, configuration updates, NDEF setup, and HMAC-SHA1 challenge-response.

```APIDOC
## YubiOtpSession

### Description
Provides methods to interact with the YubiOTP application on a YubiKey device.

### Constructor

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `connection` | `OtpConnection \| SmartCardConnection` | yes | — | HID OTP or smart card connection; the backend is chosen accordingly |
| `scp_key_params` | `ScpKeyParams \| None` | no | `None` | Only valid with `SmartCardConnection` (`ValueError("SCP can only be used with SmartCardConnection")`) |

With a `SmartCardConnection` the firmware version is read from the OTP AID select response (preferring the MANAGEMENT select version over NFC, taking the max for NEO). Other types raise `TypeError("Unsupported connection type")`.

### Methods

#### `close() -> None`
- **Description**: Closes the session. Deprecated.

#### `version` (property) -> `Version`
- **Description**: Firmware version of the YubiOTP application.

#### `get_serial() -> int`
- **Description**: Reads the device serial number (via `CONFIG_SLOT.DEVICE_SERIAL`).
- **Returns**: `int` - The serial number.

#### `get_config_state() -> ConfigState`
- **Description**: Returns the current slot/configuration state.
- **Returns**: `ConfigState` - The configuration state.

#### `put_configuration(slot: SLOT, configuration: SlotConfiguration, acc_code: bytes | None = None, cur_acc_code: bytes | None = None) -> None`
- **Description**: Programs a slot. Raises `NotSupportedError("This configuration is not supported on this YubiKey version")` if the configuration is unsupported.
- **Parameters**:
  - `slot` (SLOT) - Required - The slot to program.
  - `configuration` (SlotConfiguration) - Required - The configuration to set.
  - `acc_code` (bytes | None) - Optional - Access code.
  - `cur_acc_code` (bytes | None) - Optional - Current access code.

#### `update_configuration(slot: SLOT, configuration: SlotConfiguration, acc_code: bytes | None = None, cur_acc_code: bytes | None = None) -> None`
- **Description**: Updates an existing configuration (update flags only). Raises `NotSupportedError` when the access code would change on firmware 4.3.2–4.3.5.
- **Parameters**:
  - `slot` (SLOT) - Required - The slot to update.
  - `configuration` (SlotConfiguration) - Required - The new configuration.
  - `acc_code` (bytes | None) - Optional - Access code.
  - `cur_acc_code` (bytes | None) - Optional - Current access code.

#### `swap_slots() -> None`
- **Description**: Swaps the two slot configurations.

#### `delete_slot(slot: SLOT, cur_acc_code: bytes | None = None) -> None`
- **Description**: Clears a slot configuration.
- **Parameters**:
  - `slot` (SLOT) - Required - The slot to clear.
  - `cur_acc_code` (bytes | None) - Optional - Current access code.

#### `set_scan_map(scan_map: bytes, cur_acc_code: bytes | None = None) -> None`
- **Description**: Writes the keyboard scancode map (54-byte map per `ykman.scancodes`).
- **Parameters**:
  - `scan_map` (bytes) - Required - The scancode map.
  - `cur_acc_code` (bytes | None) - Optional - Current access code.

#### `set_ndef_configuration(slot: SLOT, uri: str | None = None, cur_acc_code: bytes | None = None, ndef_type: NDEF_TYPE = NDEF_TYPE.URI) -> None`
- **Description**: Writes an NDEF record (URI, or TEXT with `ndef_type`) for NFC tagging. Raises `ValueError("URI payload too large")` when the payload exceeds 54 bytes.
- **Parameters**:
  - `slot` (SLOT) - Required - The slot to configure.
  - `uri` (str | None) - Optional - The URI to write.
  - `cur_acc_code` (bytes | None) - Optional - Current access code.
  - `ndef_type` (NDEF_TYPE) - Optional - The NDEF type (default: `NDEF_TYPE.URI`).

#### `calculate_hmac_sha1(slot: SLOT, challenge: bytes, event: Event | None = None, on_keepalive: Callable[[int], None] | None = None) -> bytes`
- **Description**: Performs HMAC-SHA1 challenge-response (firmware ≥ 2.2). The challenge is padded to 64 bytes. Returns the 20-byte response.
- **Parameters**:
  - `slot` (SLOT) - Required - The slot to use.
  - `challenge` (bytes) - Required - The challenge data.
  - `event` (Event | None) - Optional - Event for cancellation.
  - `on_keepalive` (Callable[[int], None] | None) - Optional - Callback for keepalive.
- **Returns**: `bytes` - The 20-byte HMAC-SHA1 response.
```

--------------------------------

### ScriptingDevice.fido()

Source: https://github.com/yubico/yubikey-manager/blob/main/_autodocs/api-reference/ykman.scripting.md

Opens a FidoConnection to the device, usable as a context manager.

```APIDOC
## ScriptingDevice.fido

### Description
Opens a connection to the FIDO application.

### Method
Method invocation

### Parameters
None

### Response
- **FidoConnection** - A context manager for the FIDO connection.
```
Tokens:
Raw