Skip to main content

Passphrase (Core Guide)

Passphrase is used to derive different wallets based on the same set of mnemonic phrases. The key for integrated applications is not to "automate processing", but to clearly distinguish: whether the current request uses a standard wallet, or whether the user enters a Passphrase to enter a hidden wallet.

Key takeaways​

  • A standard wallet is equal to "mnemonic + empty Passphrase".
  • The hidden wallet is equal to "mnemonic + non-empty Passphrase" and is case-sensitive.
  • Passphrase cannot be retrieved and users must back it up accurately; one more space or different case will result in different wallets.
  • If a request explicitly requires a standard wallet, please set useEmptyPassphrase: true.

application behavior​

Applications are generally processed in two ways:

Explicitly use a standard wallet​

When the business process does not require hiding the wallet, directly declare the use of empty Passphrase in the request inputs:

await ukeySdk.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/6'",
  useEmptyPassphrase: true,
});

Respond to Passphrase events​

When the SDK sends UI_REQUEST.REQUEST_PASSPHRASE, the app needs to give the user a clear choice: enter on the device, or enter in the current interface.

// When input stays on-device, the host app never handles the Passphrase.
ukeySdk.uiResponse({
  type: UI_RESPONSE.RECEIVE_PASSPHRASE,
  payload: { passphraseOnDevice: true, value: "" },
});

// Input from the software UI can be cached in the current session if needed.
ukeySdk.uiResponse({
  type: UI_RESPONSE.RECEIVE_PASSPHRASE,
  payload: { value, passphraseOnDevice: false, save: true },
});

Caching and sessions​

  • passphraseState can be read through Get Passphrase status, and then passed to subsequent requests with shared request options.
  • keepSession / initSession can reduce repeated confirmations within the same process, but do not regard it as a long-term preservation mechanism for Passphrase.

Key Notes​

  • Do not print, upload, sync, or long-term save Passphrase.
  • Software input boxes must be masked and the user must clearly know whether session caching is enabled.
  • If the user does not want the host app to touch Passphrase, provide device-side input first.
  • PIN and Passphrase are two types of interactions: UKey Core 26’s PIN must be entered on the device, but Passphrase can still choose to enter it on the device side or software side according to the UX.

See also: shared request options, event configuration.