Authentication Architecture

HMAC-SHA1 Challenge-Response

Yubi AppGate uses the HMAC-SHA1 challenge-response protocol to authenticate your YubiKey. This is the same proven mechanism used in enterprise security, full-disk encryption tools, and password managers.

Here's how a single authentication attempt works:

1. The app generates a cryptographically random challenge (up to 64 bytes).
2. The challenge is sent to the YubiKey over NFC or USB.
3. The YubiKey computes an HMAC-SHA1 using the challenge and the secret stored in its tamper-resistant secure element.
4. The 20-byte response is sent back to the app.
5. The app compares the response against the enrolled identity.
6. If the response matches, authentication succeeds.

Trust On First Use (TOFU) Enrollment

During enrollment, the app sends a random challenge to your YubiKey and records the response. This challenge-response pair becomes the enrolled identity. On subsequent authentication attempts, the app replays the same challenge and verifies that the YubiKey produces the same response.

This is a Trust On First Use model, so the first YubiKey you enroll becomes the trusted key. To switch keys, reset enrollment and re-enroll with a different YubiKey.

All Authentication Is Local

The entire authentication flow happens on your device:

• The challenge is generated locally using java.security.SecureRandom.
• Communication with the YubiKey happens directly over NFC (ISO-DEP / ISO 7816) or USB (CCID smart card interface).
• Response verification is performed on-device.
• No network requests are made during authentication.

No Credentials Stored Remotely

Yubi AppGate does not store any credentials, secrets, or authentication data on remote servers. All enrollment data (the challenge-response pair and slot selection) is stored in the app's private SharedPreferences on your Android device, accessible only to the app itself.

The YubiKey's HMAC-SHA1 shared secret never leaves the hardware key's secure element. The app never has access to the raw secret. It only sends challenges and receives responses.

Transport Security

NFC

The app uses Android's reader mode to communicate with the YubiKey over NFC. It selects the YubiKey's OTP applet via its Application Identifier (AID) and sends the challenge-response APDU directly. No NDEF records are read or written.

USB

Over USB, the app communicates via the CCID (smart card) interface. It powers on the card, selects the OTP applet, and sends the same challenge APDU. USB permission is requested via the standard Android USB host API.

Self-Protection

Once a YubiKey is enrolled, Yubi AppGate protects itself. Opening the app requires YubiKey authentication, which prevents someone from modifying your protection settings without your hardware key.

Uninstall Protection

The optional device administrator mode uses Android's DevicePolicyManager to prevent uninstallation.

Security Considerations

As with any security tool, there are important considerations:

• Physical key loss: If you lose your YubiKey, you can still clear the app's data via Android Settings to remove protection. This is by design, as Android does not allow third-party apps to make the device permanently inaccessible.
• Rooted devices: On a rooted device, any app can potentially access another app's private storage. For maximum security, use Yubi AppGate on a non-rooted device.
• Accessibility service trust: The accessibility service requires user consent. It only observes foreground package names and does not read screen content.
• Locking Android Settings: You can add Android Settings to your protected app list, which prevents anyone from disabling the accessibility service or removing Device Administrator privileges without your YubiKey. This significantly hardens the device, but if your key is lost or destroyed, a full factory reset will be required to regain access to Settings.