PIN Protection

Understanding SatSigner’s PIN-based authentication and encryption system

Overview

SatSigner uses a 4-digit PIN as the primary authentication mechanism to protect your Bitcoin wallet. The PIN serves dual purposes:

1. Authentication - Controls access to the application
2. Encryption key - Derives cryptographic keys to encrypt sensitive data

PIN Security Architecture

Encryption Algorithm

SatSigner implements industry-standard AES-256-CBC encryption for all sensitive data:

• Algorithm: AES (Advanced Encryption Standard)
• Key Size: 256-bit
• Mode: CBC (Cipher Block Chaining)
• Key Derivation: PBKDF2 with SHA-256

Key Derivation Process

The PIN is never stored directly. Instead, it undergoes a secure key derivation process:

// Key derivation function (apps/mobile/utils/crypto.ts:39-40)
pbkdf2Encrypt(pin, salt, 10_000, 256, 'sha256')

Parameters:

• Iterations: 10,000 (computational cost to resist brute-force attacks)
• Output Length: 256 bits
• Hash Function: SHA-256
• Salt: 16-byte random value (unique per installation)

Storage Security

PIN-related data is stored in platform-specific secure enclaves:

• iOS: Keychain (hardware-backed when available)
• Android: SharedPreferences with encryption

All sensitive items are stored using expo-secure-store (apps/mobile/storage/encrypted.ts:1):

// Stored securely:
- PIN_KEY: 'satsigner_pin' (encrypted PIN hash)
- DURESS_PIN_KEY: 'satsigner_duress_pin' (encrypted duress PIN hash)
- SALT_KEY: 'satsigner_salt' (cryptographic salt)

PIN Configuration

Default Settings

// From apps/mobile/config/auth.ts
PIN_SIZE: 4 digits
DEFAULT_PIN_MAX_TRIES: 5 attempts
DEFAULT_LOCK_DELTA_TIME_SECONDS: 30 seconds

Configurable Options

Maximum Attempts:

• Minimum: 3 attempts
• Maximum: 10 attempts
• Default: 5 attempts

After exhausting all attempts, all wallet data is permanently deleted.

Auto-Lock Timer:

• Default: 30 seconds of inactivity
• Customizable per user preference

PIN Setup Process

Initial Setup

When setting up a PIN for the first time (apps/mobile/store/auth.ts:71-76):

1. User enters desired 4-digit PIN
2. System generates a random 16-byte salt
3. PIN is hashed using PBKDF2 (10,000 iterations)
4. Salt and hashed PIN are stored in secure storage
5. Encryption keys are derived for wallet data protection

PIN Validation

Every unlock attempt validates the PIN by:

1. Retrieving the stored salt from secure storage
2. Applying PBKDF2 to the entered PIN with the same salt
3. Comparing the result with the stored hash
4. Granting access only on exact match

Security Lockout

Failed Attempt Handling

The system tracks failed PIN attempts (apps/mobile/app/unlock.tsx:99-108):

const triesLeft = incrementPinTries()
if (triesLeft === 0) {
  deleteAccounts()
  deleteWallets()
  setFirstTime(true)
  setRequiresAuth(false)
  resetPinTries()
}

Data Destruction on Lockout: When PIN attempts are exhausted, all wallet data is immediately and permanently deleted. There is no recovery mechanism if you forget your PIN and exceed the attempt limit.

Auto-Lock Behavior

The application automatically locks when:

• App is sent to background
• Configured idle timeout is reached (default: 30 seconds)
• Device is locked
• App is force-closed

Best Practices

Choosing a Secure PIN

Avoid Common PINs: Do not use easily guessable PINs such as:

• Sequential numbers (1234, 0000)
• Repeated digits (1111, 2222)
• Birthdays or dates
• Common combinations (1212, 2580)

Recommendations:

• Use a random 4-digit combination
• Avoid personal information
• Do not reuse PINs from other services
• Consider enabling a duress PIN for additional security

PIN Change Procedure

When changing your PIN:

1. Enter current PIN - Authentication required
2. Enter new PIN - Choose a strong combination
3. Confirm new PIN - Verify correct entry
4. Re-encryption process - All encrypted data is re-encrypted with the new PIN-derived key

Changing your PIN requires re-encrypting all sensitive wallet data. This process happens automatically and securely in the background.

Data Protected by PIN

The PIN-derived encryption key protects:

• Seed phrases (mnemonics) - BIP39 recovery words
• Private keys - Extended private keys (xprv)
• Passphrases - Optional BIP39 passphrase
• Descriptors - Output descriptors containing key information
• Account secrets - All sensitive account data

Non-sensitive data stored without PIN encryption:

• Public keys and addresses
• Transaction history (without signing capability)
• Account metadata (names, labels)
• Application settings

Technical Implementation

Encryption Flow

// Encrypting sensitive data (apps/mobile/utils/crypto.ts:30-31)
aesEncrypt(text: string, key: string, iv: string) {
  return aesCrypto.encrypt(text, key, iv, 'aes-256-cbc')
}

Components:

• Plaintext: Sensitive data (e.g., mnemonic)
• Key: PIN-derived via PBKDF2
• IV (Initialization Vector): Random 32-character hex string
• Algorithm: AES-256-CBC

Decryption Flow

// Decrypting sensitive data (apps/mobile/utils/crypto.ts:34-35)
aesDecrypt(cipher: string, key: string, iv: string) {
  return aesCrypto.decrypt(cipher, key, iv, 'aes-256-cbc')
}

Decryption requires:

• Correct PIN (for key derivation)
• Original initialization vector (stored with encrypted data)
• Encrypted ciphertext

Threat Model

Protected Against

✓ Physical device theft - PIN required to access ✓ Unauthorized access - Auto-lock on inactivity ✓ Brute-force attacks - PBKDF2 iterations slow down attempts ✓ Data extraction - AES-256 encryption protects data at rest ✓ Memory dumps - Secure storage prevents plaintext exposure

Not Protected Against

✗ Shoulder surfing - Physical observation of PIN entry ✗ Keyloggers - Malware on compromised device ✗ Physical device compromise - Advanced forensic techniques ✗ Weak PIN selection - User choosing guessable PIN

Device Security Dependency: SatSigner’s security relies on the underlying device security. Always keep your device operating system updated and free from malware.

Recovery Considerations

PIN Recovery

There is no PIN recovery mechanism. If you forget your PIN:

1. You have a limited number of attempts (default: 5)
2. Exceeding attempts triggers data deletion
3. You must restore from seed phrase backup

Critical: Always maintain a secure backup of your seed phrases independent of the PIN-protected wallet. See Backup & Recovery for details.

Account Recovery Without PIN

If PIN access is lost:

1. Allow lockout to occur (data will be deleted)
2. Reinstall or reset the application
3. Use “Import Mnemonic” to restore accounts
4. Re-enter seed phrases from secure backup
5. Set a new PIN

Related Topics

• Duress PIN Functionality - Emergency protection mechanism
• Backup & Recovery - Protecting against PIN loss
• Encryption - Technical encryption details
• Seed Management - Protecting your seed phrases