YubiKit Android

The Desktop Module provides concrete implementations of core YubiKit interfaces for desktop Java applications. It enables developers to build desktop software that interacts with YubiKeys via USB (HID and PC/SC) or NFC (via external PC/SC readers like HID Global OMNIKEY).

WARNING: This module is experimental. The API is unstable and subject to change without notice.

The Support Module provides optional functionality for interacting with YubiKey devices, specifically for retrieving device info and device names. For detailed API signatures, refer to the official JavaDoc documentation.

JavaDoc API documentation

The Core module defines the fundamental interfaces for interacting with YubiKeys:

• YubiKeyDevice: Represents a physical YubiKey connected via a transport (e.g., USB or NFC). To interact with it, you must request a connection.
• YubiKeyConnection: Represents an active communication channel. The module defines three specific types: SmartCardConnection, OtpConnection, and FidoConnection. Note that only one connection type may be open at a time.
• ApplicationSession: Represents an open session with a specific application on the YubiKey. Specific implementations of this class are provided in specialized application modules.

The module automatically detects external NFC readers via PC/SC. Any PC/SC terminal that does not have "yubikey" in its name is treated as an NFC reader.

When a YubiKey is tapped on an NFC reader:

• The device appears in listDeviceRecords() with Transport.NFC.
• The fingerprint is the PC/SC terminal name (e.g., "HID Global OMNIKEY 5022 CL 00").
• Constraint: Only SmartCardConnection is supported over the NFC transport.

Decide between the android module's OtpActivity and the yubiotp module based on your requirements:

• Use OtpActivity (from the Android module): If you only need to read an OTP payload via USB or NFC and do not need to configure YubiKey slots or access challenge-response functionality.
• Use the yubiotp module: If you need to program YubiKey slots with credentials (Yubico OTP, OATH-HOTP, HMAC-SHA1 Challenge-Response, or static passwords) or use challenge-response features.

Use the CtapSession class to establish communication with a FIDO application on a YubiKey. CtapSession provides several ways to connect:

• Constructors for specific Fido or SmartCard connections.
• A factory method that accepts a YubiKeyDevice and automatically selects the best available connection type.

This session is required to initialize the WebAuthnClient.

The SDK now uses JSpecify nullness annotations. When using Kotlin generics that interact with SDK types like Result<T, E>, you must ensure that type arguments are non-nullable by specifying <T : Any>.

// Old
fun <T> returnsResult(): Result<T, Throwable> { ... }

// New
fun <T : Any> returnsResult(): Result<T, Throwable> { ... }

Android API Levels

• General Modules: Most YubiKit modules work on Android API 21+.
• FIDO Android UI Module: Requires Android API 23+.

Version Compatibility

• Version 3.0+ is not compatible with Version 2.0.
• Version 2.0+ is not compatible with Version 1.0.

Hardware Support

• The android module supports both USB and NFC connectivity for YubiKeys.

Security

• HTTPS Only: All origins must use HTTPS; HTTP origins are rejected.
• Origin Validation: The module validates that the request origin matches expected patterns.
• PIN Protection: PINs are handled securely and never logged or exposed in plain text.
• Single Request: Only one FIDO operation can be in progress at a time.
• Screen Capture Protection: In non-debug builds, the FIDO UI applies FLAG_SECURE to block screenshots and screen recording.

Threading

All FidoClient operations are suspending functions and must be called from a coroutine context. The module internally manages:

• UI interactions on the main thread.
• NFC/USB communication on background threads.
• Cryptographic operations.
• JSON serialization/deserialization.

The following module renames and functional moves occurred in version 2.0:

• mgmt is now management.
• otp is now yubiotp (specifically for the YubiKey OTP application).
• OtpActivity has moved from otp to the android module.
• YubiKey OTP Application configuration has moved from mgmt to yubiotp via the new YubiOtpSession.
• Exceptions have moved from com.yubico.yubikit.exceptions to the specific packages where they are relevant.