Skip to content

Add PIN prefix anti-phishing verification #86

@kwsantiago

Description

@kwsantiago

Problem

When a user enters their PIN on the device, they have no way to verify they're interacting with genuine firmware vs. a malicious replacement. An attacker with physical access could replace the display/firmware to capture PINs.

Solution: PIN Prefix Words

Production hardware wallets use a technique where entering the first few digits of your PIN displays derived BIP-39 words that only the genuine device with your secret can produce.

User Flow:

  1. User starts PIN entry
  2. After entering 2-4 digits, device displays two BIP-39 words
  3. User verifies words match what they expect (memorized during setup)
  4. If words are wrong → device is compromised, abort
  5. If words match → continue entering full PIN

Implementation:

typedef struct {
    uint8_t prefix[4];        // First 4 PIN digits
    uint8_t prefix_len;       // How many digits entered
} pin_prefix_t;

// Derive anti-phishing words from PIN prefix + device secret
int pin_derive_prefix_words(const pin_prefix_t *prefix, 
                            const uint8_t *device_secret,
                            uint16_t *word1_index,
                            uint16_t *word2_index) {
    uint8_t hmac_out[32];
    
    // HMAC(device_secret, "anti-phishing" || prefix)
    mbedtls_md_hmac(MBEDTLS_MD_SHA256,
                    device_secret, 32,
                    combined_input, input_len,
                    hmac_out);
    
    // Extract two 11-bit word indices (BIP-39 has 2048 words)
    *word1_index = (hmac_out[0] << 3 | hmac_out[1] >> 5) & 0x7FF;
    *word2_index = (hmac_out[1] << 6 | hmac_out[2] >> 2) & 0x7FF;
    
    secure_memzero(hmac_out, sizeof(hmac_out));
    return 0;
}

Display Integration:

Setup Flow:

  1. During first PIN creation, derive and show prefix words
  2. User writes down: "My anti-phishing words are: abandon ability"
  3. On every subsequent unlock, user verifies these words appear

Security Properties

  • Words are deterministic: same prefix + same secret = same words
  • Words change if device secret changes (detects tampering)
  • Words change if PIN prefix changes (different users get different words)
  • Attacker cannot predict words without knowing device secret

Dependencies

Acceptance Criteria

  • HMAC-based word derivation from PIN prefix
  • BIP-39 word list integration (English, 2048 words)
  • Display words after N prefix digits entered
  • Setup flow captures user's expected words
  • Optional: store expected word hash for self-verification

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions