Passphrase

Regeln und bewährte Vorgehensweisen für Passphrasen (versteckte Wallets).

Grundbegriffe

• Standard-Wallet = Seed + leere Passphrase; versteckte Wallet = Seed + nicht leere Passphrase (Groß-/Kleinschreibung beachten).
• Jede andere Passphrase erzeugt eine völlig andere Wallet — selbst die Änderung eines einzigen Zeichens.
• Passphrasen lassen sich nicht wiederherstellen; sichern Sie sie zuverlässig.
• Erzwingen Sie die Standard-Wallet durch Setzen von useEmptyPassphrase: true.

Geräteunterstützung

Leiten Sie die Unterstützung für Host- oder Geräteeingabe nicht allein aus einem Modellnamen ab. Lesen Sie getDeviceState, um Gerät, Firmware und aktuellen Status zu bestimmen, und folgen Sie dann der tatsächlichen UI-Anfrage. Die Verfügbarkeit hängt von Gerät, Firmware, SDK und Laufzeit ab.

Speichern Sie gegebenenfalls die Wallet-Bindung (deviceId und passphraseState), keine Firmware-session_id.

Interaktionsablauf

Hardware SDK 1.2.x: searchDevices → getDeviceState → openWalletSession → Adresse / Signieren mit deviceId + passphraseState (oder useEmptyPassphrase: true). Abonnieren Sie UI_EVENT vor dem Öffnen einer Wallet. Siehe Wallet-Sitzungen.

Standard-Wallet

const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error("Device has no wallet identity");
 
const standard = await HardwareSDK.openWalletSession(connectId, { mode: 'standard' });
if (!standard.success) throw new Error(standard.payload.error);
 
await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  useEmptyPassphrase: true,
});

Versteckte Wallet (einmal öffnen, Fingerabdruck wiederverwenden)

import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core';
 
HardwareSDK.on(UI_EVENT, async (message) => {
  if (message.type === UI_REQUEST.REQUEST_PASSPHRASE) {
    await HardwareSDK.uiResponse({
      type: UI_RESPONSE.RECEIVE_PASSPHRASE,
      ...message.payload.responseCorrelation,
      payload: { passphraseOnDevice: true, value: '', save: false },
    });
  }
});
 
const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: 'select-hidden',
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden') {
  throw new Error('A hidden wallet was not opened');
}
const deviceId = opened.payload.deviceId;
const passphraseState = opened.payload.passphraseState;
 
await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState,
});
await HardwareSDK.btcGetAddress(connectId, deviceId, {
  path: "m/84'/0'/0'/0/0",
  coin: 'btc',
  passphraseState,
});

Passphrase-Eingabe auf dem Gerät oder per Software:

// On-device
payload: { passphraseOnDevice: true, value: '' }
 
// Software
payload: { value: userInput, passphraseOnDevice: false, save: false }

Späterer Prozess / Wiederverbindung

Speichern Sie nur deviceId + passphraseState. Speichern Sie die Firmware-session_id nicht dauerhaft. Laden Sie die Bindung und übergeben Sie sie beim nächsten Adress-/Signieraufruf. Core setzt die Sitzung innerhalb dieser Methode fort. openWalletSession hat keinen Fortsetzungsmodus.

import { OpenWalletSessionMode } from '@onekeyfe/hd-core';
 
// Process 1 — after the user selects the hidden wallet
const opened = await HardwareSDK.openWalletSession(connectId, {
  mode: OpenWalletSessionMode.SelectHidden,
});
if (!opened.success) throw new Error(opened.payload.error);
if (opened.payload.walletType !== 'hidden') {
  throw new Error('A hidden wallet was not opened');
}
saveBinding({
  deviceId: opened.payload.deviceId,
  passphraseState: opened.payload.passphraseState,
});
 
// Process 2 — later process, same machine
const { deviceId, passphraseState } = loadBinding();
 
await HardwareSDK.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState,
});

preloadSessionCache ist ein Kompatibilitätseinstieg für alte App-/CLI-Schlüsselbunddatensätze. Neue Integrationen sollten ihn nicht aufrufen und keine session_id speichern.

Wenn das Gerät zwischen Prozessen gesperrt wurde, wird beim ersten geschützten Aufruf erneut die PIN abgefragt. Siehe Wallet-Sitzungen.

Zuerst entsperren (CLI-Muster)

const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
 
if (!state.payload.status.unlocked) {
  await HardwareSDK.deviceUnlock(connectId, {});
}
 
await HardwareSDK.evmGetAddress(connectId, savedDeviceId, {
  path: "m/44'/60'/0'/0/0",
  passphraseState: savedPassphraseState,
});

Sicherheitstipps

• Niemals protokollieren oder dauerhaft speichern: Passphrasen im Klartext.
• Verwenden Sie useEmptyPassphrase: true, um das versehentliche Erstellen einer versteckten Wallet zu verhindern.
• Pro-/Touch-Geräte: Die PIN muss auf dem Gerät eingegeben werden; die Passphrase kann auf dem Gerät oder per Software eingegeben werden.

FAQ

Was passiert, wenn ich meine Passphrase vergesse?

Gelder in der versteckten Wallet sind dauerhaft unzugänglich. Eine vergessene Passphrase lässt sich nicht wiederherstellen. Bewahren Sie stets eine sichere Sicherungskopie auf.

Ist die Passphrase dasselbe wie die PIN?

Nein. Die PIN schützt den physischen Zugriff auf das Gerät. Die Passphrase erzeugt aus demselben Seed eine vollständig andere Wallet. Sie erfüllen unterschiedliche Sicherheitszwecke:

Kann ich mehrere versteckte Wallets haben?

Ja. Jede eindeutige Passphrase erzeugt eine eigene versteckte Wallet. Sie können beliebig viele versteckte Wallets haben — eine pro eindeutiger Passphrase.

Prüft das Gerät meine Passphrase?

Eine neu eingegebene Passphrase kann eine andere Wallet ableiten. Wenn ein späterer Aufruf einen erwarteten passphraseState angibt, prüft das SDK diese Bindung und schlägt bei Abweichung fehl; behandeln Sie eine falsch eingegebene Passphrase nicht als die vorgesehene Wallet.

Was ist der Unterschied zwischen passphraseOnDevice und Software-Eingabe?

• Auf dem Gerät: Die Passphrase wird direkt auf dem Bildschirm/der Tastatur des Hardwaregeräts eingegeben. Sie verlässt das Gerät nie.
• Software-Eingabe: Die Passphrase wird in Ihrer App eingegeben und über das SDK an das Gerät gesendet.

Siehe auch: Gemeinsame Parameter, Ereignisse & UI-Anbindung.

Auf Protocol V1 kann select-hidden eine Standard-Wallet zurückgeben, wenn der Passphrase-Schutz deaktiviert ist. Prüfen Sie walletType vor dem Speichern oder Verwenden von passphraseState.