Skip to content

Add PIN prefix anti-phishing verification #86

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions