PIN Notes

A PIN is a user verification step encountered for most protected operations. The SDK will not pop up a fixed UI on its own, but will tell the application "a PIN is now required" through events, and then the application will decide to display device-side input or software-side blind input.

Core Notes

• UI_REQUEST.REQUEST_PIN is triggered when the device is locked and the current request requires authorization.
• UKey Core 26 requires you to enter the PIN on the device and cannot enter it blindly through the software.
• For models that support software-side PIN, also use device-side input first to prevent the PIN from entering the host application.

Support Table (Software PIN)

The following table is used to determine whether the "Enter on this screen" option can be displayed. Even if the model supports software-side PIN, use "Use device input instead" as the default path.

Device family	Software PIN entry	Device-only entry
UKey Lite 24 / Lite 25	available	no
UKey Core 26	not available	yes

UI Advice

• Show a focused PIN dialog and don't pop up multiple prompts at once.
• The default action is "Use device input instead"; only models that support software-side PINs display "Enter on this screen".
• The software-side PIN uses a fixed 3x3 keyboard, and the interface only displays the mask and does not return the real number.
• Promptly close the PIN dialog box upon receipt of a close event or the end of the protected process.

PIN Map (Software Keyboard)

Software-side keypad layout:

7 8 9
4 5 6
1 2 3

The software keyboard displays the position, and what is sent to the SDK is the mapped value. The following array converts 1..9 on the interface into the order required by the device:

const PIN_KEYPAD_MAP = ["7", "8", "9", "4", "5", "6", "1", "2", "3"];
let mappedPin = "";

function appendMappedPinDigit(slot: number) {
  // slot is the position number the user tapped on the 3x3 keypad
  mappedPin += PIN_KEYPAD_MAP[slot - 1];
}

For instance, the user clicks the software keys 1 and 9, and after mapping, they get 7 and 3, and finally send 73.

Handling PIN Events

import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from "@ukeyfe/hardware-core";

ukeySdk.on(UI_EVENT, (uiEvent) => {
  if (uiEvent.type === UI_REQUEST.REQUEST_PIN) {
    // Preferred path: keep PIN entry on the device.
    ukeySdk.uiResponse({
      type: UI_RESPONSE.RECEIVE_PIN,
      payload: "@@UKEY_INPUT_PIN_IN_DEVICE",
    });

    // Fallback route: only for models that support software-side PIN entry.
    const mappedPin = "73"; // Computed from the keyboard position
    ukeySdk.uiResponse({ type: UI_RESPONSE.RECEIVE_PIN, payload: mappedPin });
  }
});