Ibis Wallet is a self-custodial Bitcoin wallet. Users hold their own keys. This document describes how secrets are protected, which defenses exist, how to report vulnerabilities, and what is (and is not) in scope.
Security fixes are applied to the latest release on GitHub Releases. Older builds are not backported unless noted in a release.
| Version | Supported |
|---|---|
| Latest release | Yes |
| Older releases | No |
Do not open a public GitHub issue for security-sensitive findings.
Send reports to aeonbtc@proton.me.
- Encrypt with PGP when the finding is sensitive: fingerprint
9A61 2482 4FCC 0EF0 5F3A 8184 C0F0 581E B6C4 E1D6(key). - Include: affected version/build, reproduction steps, impact (funds, privacy, lockout, wipe), and any PoC that does not put third-party funds at risk.
- You will get a reply when the report is received.
Alternatively, open a GitHub Security Advisory (private) when the repository enables them.
Bug bounty program is currently paused due to lack of funds. Reports are welcome and will be acknowledged, but no monetary rewards will be paid until the program resumes.
The paused bounty offered $1,000 BTC for critical vulnerabilities with a practical path to unauthorized loss of user funds (for example remote wallet compromise, seed extraction, or transaction manipulation that steals or permanently destroys funds).
| In scope for bounty (when active) | Out of scope for bounty (may still be acknowledged) |
|---|---|
| Practical theft or permanent loss of funds | Theoretical issues without a realistic exploit path |
| Remote compromise leading to fund loss | UI/UX polish, cosmetic bugs |
| Seed / spend-secret extraction usable offline | Issues requiring physical access + unlocked device + no app lock, without additional privilege escalation |
| Transaction manipulation that steals funds | Issues in third-party servers the user chose (Electrum, explorers, ASP, etc.) unless the client mishandles them in a fund-loss way |
| Dependency CVEs with no practical impact on Ibis | |
| Social engineering, phishing, or user error | |
| Compromised Android OS / rooted device / malware with full device control (baseline threat; see Threat model) | |
| Issues fully recoverable by restoring from off-device seed backup, with no third-party theft (seed backups are expected standard practice for this beta software) |
When the program is active, lower-severity issues that do not lead to fund loss may be fixed without a monetary reward.
- Allow reasonable time for a fix before public disclosure.
- Do not exploit findings against third-party users or mainnet funds you do not control.
- Coordinated disclosure is preferred.
| Layer | Approach |
|---|---|
| Custody | Self-custodial; keys stay on device |
| At rest | EncryptedSharedPreferences + optional session spend-secret wrapping while app lock is enabled |
| App access | Optional PIN and/or biometric lock |
| Coercion | Duress PIN → decoy wallet; optional Wipe PIN; optional auto-wipe |
| Privacy UI | Cloak Mode (calculator disguise); amount privacy toggle |
| Network | No auto-connect until the user selects services; optional built-in Tor; Electrum SSL TOFU |
| OS backup | Disabled; cloud and device-transfer extraction excluded |
| Screen | FLAG_SECURE by default; tapjacking filter |
| Logs | Prefer SecureLog; release ProGuard strips verbose/debug/info Log calls |
| Release | R8 minify + resource shrink; native UniFFI/JNA bindings kept |
Ibis targets experienced Bitcoin users. Features such as cleartext Electrum, custom servers, and remote Lightning credentials assume the user understands the tradeoffs.
| Severity | Area | Fix |
|---|---|---|
| Critical | PSBT signing | Rejects unsafe sighashes (NONE/SINGLE/ANYONECANPAY), fake legacy prevouts, and absurd fees |
| Critical | Silent Payments | RBF no longer reuses a stale BIP-352 output key or burns the payment |
| Critical | Spark backup restore | No longer imports an attacker-controlled on-chain deposit address |
| Critical | Liquid backup restore | Seed wallets re-derive the descriptor instead of trusting the backup |
| High | BOLT12 | Verifies invoice/request signatures and binds the invoice to the reviewed offer and amount |
| High | Electrum | Rejects raw transactions that do not match the requested txid; fixes SegWit txid checks |
| High | Spark exit | CPFP signing validates sighash, outputs, and fee |
| High | Spark multi-send | Resumes safely and blocks retries after an uncertain send |
| High | Liquid swaps | Funding/refund failures can no longer trigger a second payment |
| High | PIN/biometric | PIN rotation is crash-safe, and biometric keys are not deleted on unlock |
Residual risks are documented in Threat model.
Sensitive configuration and secrets live primarily in AndroidX EncryptedSharedPreferences (ibis_secure_prefs):
- Master key: Android Keystore via
MasterKey(AES256_GCM), alias_androidx_security_master_key_ - Pref keys:
AES256_SIV - Pref values:
AES256_GCM
Non-secret settings may use ordinary SharedPreferences (ibis_prefs). Legacy values found only in regular prefs are migrated into encrypted prefs when read.
If EncryptedSharedPreferences creation fails, startup is fail-closed: only a positively identified permanent key invalidation (KeyPermanentlyInvalidatedException chain) deletes the stale prefs file and recreates empty encrypted storage. Any other failure throws SecureStorage.UnavailableException, the app exits, and no prefs or Keystore data is deleted.
While app lock is enabled (PIN or biometric), high-value secrets are stored as spend secrets:
- A random 32-byte session master key is held in memory only while unlocked.
- Each secret is encrypted with AES-256-GCM under that master key (
enc:v1:prefix + Base64(IV ‖ ciphertext)). - The master key is wrapped for unlock methods:
- PIN / duress PIN: PBKDF2-HMAC-SHA256 (150 000 iterations, 16-byte random salt) → wrapping key → AES-GCM wrap
- Biometric: Android Keystore AES key with
setUserAuthenticationRequired(true), wrap viaBiometricPrompt.CryptoObject
Spend-secret keys today: BIP39 mnemonic, WIF private key, BIP39 passphrase, multisig local cosigner material, Liquid CT descriptor, extended private keys (xprv / zprv imports), Lightning macaroon / CLN rune / TLS PEM / NWC URI.
Not session-wrapped (still in EncryptedSharedPreferences when stored there): watch-only xpubs / descriptors / single addresses, multisig public configs, PSBT signing sessions, labels, Electrum cert fingerprints, wallet metadata, and similar non-seed material.
The BDK SQLite wallet database stores the public Descriptor<DescriptorPublicKey> only (bdk_wallet 3.x ChangeSet); it does not persist the xprv/WIF. Spend-capable descriptors are supplied to BDK in memory at load/create time and remain in SecureStorage.
When the app locks, the in-memory master key is zeroed (lockSpendSecretSession). Without a successful unlock, spend secrets cannot be decrypted even if encrypted prefs are readable on a compromised filesystem snapshot that still requires the Keystore path—defense is layered, not absolute (see Threat model).
Disabling app lock (SecurityMethod.NONE) deliberately migrates spend secrets back to EncryptedSharedPreferences values without the session wrap (so the wallet remains usable with no unlock), then zeros the in-memory master key. Encrypted prefs still protect at rest via the Keystore master key. Disabling requires an explicit funds-at-risk confirmation in the Security screen; programmatic callers must pass acknowledgedDowngradeRisk = true.
Biometric Keystore keys use setInvalidatedByBiometricEnrollment(false) so adding/removing fingerprints does not permanently orphan the spend-secret master key. On the unlock/prewarm path, an existing key is never created or deleted; a missing or invalidated key fails with a PIN fallback message and leaves the biometric wrap in place. Only the explicit enrollment path (reached after a successful app unlock) may replace a legacy invalidated key and re-wrap the live master. Biometric is BIOMETRIC_STRONG only (no device-credential fallback on the crypto-bound path).
Enrollment-change handling is fail-closed: the tripwire canary (ibis_biometric_tripwire) reports OK / CHANGED / UNKNOWN. CHANGED blocks the first biometric unlock and sets a one-shot warning (a second attempt after the user has seen the warning may proceed and re-baselines). UNKNOWN (unreadable Keystore) blocks with a retryable error instead of silently proceeding.
Mnemonics, private keys, passphrases, PINs, macaroons, runes, NWC URIs, and similar material must not appear in logs. Prefer SecureLog (debug-only detail; release uses static releaseMessage only). Release builds also strip Log.v / Log.d / Log.i via ProGuard -assumenosideeffects. Remaining Log.w / Log.e call sites should stay free of secrets.
| Method | Behavior |
|---|---|
| None | No app lock (not recommended for mainnet funds) |
| PIN | 4–12 digits |
| Biometric | Fingerprint / face via system BiometricPrompt bound to crypto |
- Algorithm: PBKDF2WithHmacSHA256
- Iterations: 150 000
- Salt: 16 random bytes per PIN
- Compare: constant-time (
MessageDigest.isEqual) - Password buffers cleared after derive
Legacy plaintext PINs (if any) are migrated to hashed form on successful verify and still count toward rate limiting.
PIN rotation writes the new hash, salt, and spend-master wrap in a single synchronous commit. The previous wrap is retained until the first successful unlock after rotation, then deleted. If the current hash matches but its wrap does not (a crash from an older build), the lock screen can request the previous PIN, decrypt the preserved wrap, and atomically re-wrap the live master under the current PIN.
Configurable:
- Disabled
- When minimized
- On screen off
- After 1 minute
- After 5 minutes
On lock: spend-secret session zeroed; L1 wallet unloaded from memory and Electrum disconnected; L2 wallets unloaded; NFC HCE payload cleared and reader/HCE preference released; optional clipboard clear (see Clipboard).
Timed locks use wall-clock background timestamps. A system picker may skip the immediate background lock so in-flight SAF/camera results are not interrupted, but the background instant is recorded and the app locks on resume once the picker grace expires. Screen-off always locks when screen-off locking is enabled. If the picker remains open past the grace period, the app locks; the picker result may be dropped rather than leaving the wallet unlocked.
Optional: require the unlock PIN again before signing/broadcast (and selected Ark lifecycle actions). Uses the existing unlock PIN hash—no separate spend secret. Only available when security method is PIN. In duress mode, spend confirmation accepts the duress PIN only.
Viewing key material and similar sensitive UI paths can require PIN/biometric again via the same unlock method (persona-scoped in duress).
Individual wallets can be flagged locked in metadata. Opening or unlocking a locked wallet requires app PIN/biometric (persona-scoped in duress). This is a UI/session authorization gate, not a second encryption layer over that wallet’s secrets. Authorization expires after 5 minutes and never survives process death; locked wallets are excluded from full-backup export unless freshly authorized this session. Disabling global security clears wallet locks. Requires app security to be enabled before locking a wallet.
isAppSessionUnlocked is process-memory only. Configuration-change recreation can keep the session if the ViewModel survives; process death re-locks. Cloak bypass is session-only and persists across a configuration change after unlock. When cloak is active and not bypassed, the calculator gate is checked before the unlocked-session branch, so a configuration-change recreation cannot skip it.
- Imported PSBTs are signed only when every input uses
SIGHASH_ALLorSIGHASH_DEFAULT;SIGHASH_NONE,SIGHASH_SINGLE, andANYONECANPAYare rejected. - Each
non_witness_utxomust hash to the outpoint being spent. Legacy inputs that provide onlywitness_utxoare rejected because legacy signatures do not commit to the amount. - The signer enforces an absolute fee cap (50,000 sats floor, 10% of input value) and a maximum fee rate (1,000 sat/vB).
- The Spark CPFP signer applies the same sighash rule, validates outputs against wallet/expected/input scripts, and caps the child fee.
- Silent Payment RBF distinguishes missing, corrupt, and known non-SP records; a missing destination record fails closed instead of paying a stale BIP-352 output key.
- BOLT12 fetched invoices are signature-checked, bound to the reviewed offer, checked for expiry, and required to match the requested amount.
- Liquid PSETs are bound to the wallet and load generation that created the unsigned PSET; import/finalize/broadcast rejects a different wallet session.
After 5 failed unlock PIN attempts, exponential backoff lockout applies:
- Base: 30 seconds, doubles per additional failure, capped at 6 doublings
- Failed-attempt counter is shared between the real unlock PIN and wrong guesses; correct duress/wipe entries do not increment it
- Lockout state is written with synchronous
commitso a process kill cannot regress auto-wipe progress
Lockout is enforced with both:
- Wall-clock deadline (
System.currentTimeMillis) - Monotonic duration (
SystemClock.elapsedRealtime)
So changing the device clock or a simple reboot cannot trivially clear the same-boot lockout. After reboot, the monotonic arm is dropped (elapsed resets); only the wall-clock deadline remains—treating a negative elapsed delta as “still locked” would brick the real PIN for the entire uptime.
Special cases (verified before lockout where applicable):
| Input | During lockout |
|---|---|
| Correct duress PIN | Blocked like any other PIN (uniform response — no oracle for which PIN is decoy) |
| Correct wipe PIN | Blocked like any other PIN (uniform response) |
| Correct unlock PIN | Subject to lockout when locked out |
| Biometric failures | OS rate-limits; do not increment the app failed-PIN counter toward auto-wipe |
A reboot combined with clock rollback cannot clear an active rate limit: when a reboot is detected while failed attempts are at/above the threshold, a bounded grace wall deadline (30–120s) is re-armed. The wall deadline always expires, so the real PIN is never bricked.
Purpose: Plausible deniability under coercion.
- User sets a duress PIN (must differ from unlock PIN and wipe PIN) and a decoy wallet seed (optional passphrase / derivation / address type).
- Decoy wallet is created with a generic name (
Wallet), real wallet ID is recorded, then the real wallet remains active until coercion. - Entering the duress PIN on the lock screen silently loads the decoy wallet (
enterDuressMode). - A real PIN (when accepted at the pad, i.e. PIN mode) or biometric (including the hidden control in duress+biometric mode) exits duress and restores the real wallet (
exitDuressMode). - Wallet list: duress mode shows only the decoy; normal mode hides the decoy wallet.
isDuressModeis not a durable user preference across cold start, but if the process dies while the active wallet ID is the decoy, unlock reconciles duress UI filtering from that persisted active ID (so decoy-only listing is restored). An accepted real unlock still exits to the recorded real wallet.- In duress UI, Security hides Duress PIN, Auto-Wipe, and Cloak Mode cards.
- With biometric + duress: PIN pad accepts duress PIN only; real wallet via biometric on a hidden control; biometric auto-cancels after ~2s in that mode.
- Disabling duress deletes decoy L2 data directories (Ark / Spark / Liquid / Lightning node state as applicable) before metadata wipe.
- Full-backup export/import filters the opposite persona’s wallets so dual-wallet setup is not leaked through backup UI.
In a normal session with duress configured, real PIN rotation and biometric enrollment are allowed; they act only on the live real master and skip the isolated decoy. Inside an actual duress session, PIN/security changes remain blocked.
Duress is not a substitute for full-disk encryption, a strong unlock, or operational security under a sophisticated adversary.
Optional thresholds after failed PIN attempts: Disabled / 1 / 3 / 5 / 10.
When failedPinAttempts >= threshold, the app runs a full wipe and kills the process. Hidden in duress mode; faded when no security method is enabled.
Correct duress PIN never increments toward auto-wipe.
Optional dedicated PIN that erases all app data when entered on the lock screen (or, with Cloak Mode, in the calculator via =).
- Same PBKDF2 + salt scheme as unlock PIN
- Must differ from unlock, duress, and cloak unlock codes
- Blocked during lockout like any other PIN (uniform response — no oracle for which PIN is decoy)
- Does not unlock spend secrets
Triggered by auto-wipe, Wipe PIN, or cloak calculator emergency wipe. Steps are isolated so one failure does not skip the rest; residue is verified afterward. The repository wipe is retried once if the first pass reports residue. On completion the process is always killed (Process.killProcess), even on partial wipe.
Typical destructive steps include:
- Disconnect network / unload wallets / prepare L2 wipe hooks
- Delete BDK wallet databases and
filesDirBDK tree - Delete LWK (
lwk/), Spark (spark/), Ark session (cacheDir/ark-session/,cacheDir/ark-session-backups/) trees plus legacyfilesDir/ark/and in-appark_auto_backupresidue - Clear Electrum cache SQLite
- Clear clipboard
- Stop Tor and wipe Tor data (
app_torservice) - Clear encrypted + regular SharedPreferences with
commit = true - Delete SharedPreferences files from disk
- Delete Android Keystore entries: EncryptedSharedPreferences master key, biometric key (
ibis_biometric_key), and biometric enrollment tripwire (ibis_biometric_tripwire) - Reset in-memory wallet state
- Verify residue (prefs files, Keystore aliases, BDK/LWK/Spark/Ark dirs, wallet ids)
Not wiped by design: user-chosen external Ark DB backups (SAF folder). Those are user-owned and may outlive wallet delete / auto-wipe. Seed + ASP mailbox recovery can rebuild VTXO state in a fresh session, but not local movement history and only while the ASP/mailbox is available; the external backup is the durable copy.
Disguises the app as a Calculator:
- Launcher activity-alias swap: Ibis icon ↔ Calculator icon (deferred to next cold start)
- Calculator UI accepts a secret unlock code then
= - Optional Wipe PIN via calculator
= - Recent-apps label shows “Calculator”
- Cloak prefs use synchronous
commitbeforeexitProcessso state survives restart - Restart path: stop Tor, start
MainActivityvia explicit intent, exit process - Cloak unlock code is PBKDF2-hashed like unlock/duress/wipe PINs, with exponential-backoff rate limiting on
=guesses (wrong codes are indistinguishable from locked-out state) - Launcher alias state is OS-visible (
PackageManagercomponent state): a forensic examiner can see which alias is enabled — cloak hides the icon/label from casual view, not frompminspection
Cloak Mode is UI/OS surface deniability, not cryptographic hiding of the APK from a forensic examiner with full disk access.
| Control | Default / notes |
|---|---|
FLAG_SECURE |
On by default (blocks screenshots / screen record / non-secure displays); togglable in Security |
| Tapjacking | window.decorView.filterTouchesWhenObscured = true |
android:allowBackup |
false |
fullBackupContent / data_extraction_rules |
Exclude all domains (root, sharedpref, database, file) from auto-backup, cloud backup, and device transfer |
| Privacy mode | Eye toggle; amounts shown as **** across L1/L2 surfaces, including PSBT/PSET/sign/broadcast review; persisted |
| Clipboard | Defaults to clear when minimized; optional clear on lock / app close; 30s auto-clear for sensitive copies (see Clipboard) |
| Launch surface | LaunchActivity not exported; applies FLAG_SECURE when screenshot prevention is enabled; only launcher aliases reach it and forward to MainActivity |
| Deep links | Exported MainActivity handles bitcoin:, lightning:, liquidnetwork:, liquid: VIEW intents only; external requests require an explicit confirmation before replacing a send draft |
| NFC | No global NDEF_DISCOVERED filter; reader mode only on explicit send/balance screens; receive HCE payload is suspended on pause; ISO-DEP send reads capped at 16 KB |
| Notifications | Wallet activity notifications opt-in (default off) + runtime POST_NOTIFICATIONS where required |
| Keep-alive FGS | Optional connectivity foreground service (dataSync); default off |
| Permissions | INTERNET, network state, optional camera/NFC, notifications, FGS types as declared; camera/NFC hardware required="false" |
Cleartext is permitted at the Android network-security level because users may run LAN Electrum / self-hosted endpoints. The app does not load arbitrary web content. Prefer TLS + TOFU or Tor onion for untrusted networks.
| Component | Exported | Notes |
|---|---|---|
LaunchActivity |
No | Splash/forwarder only |
LauncherDefault / LauncherCalculator |
Yes | Launcher aliases → LaunchActivity |
MainActivity |
Yes | singleTask; payment URI VIEW filters only |
NdefHostApduService |
Yes | Requires BIND_NFC_SERVICE |
ConnectivityForegroundService |
No | dataSync FGS |
TorService |
No | specialUse FGS (tor_anonymity_network) |
- Sensitive copies go through
SecureClipboard: generic clip label,EXTRA_IS_SENSITIVEon Android 13+, auto-clear after 30 seconds - Optional modes: Disabled / On lock / On app close / On lock and close / When minimized
- Default mode is When minimized; existing explicitly stored modes are preserved
- Full wipe always clears the primary clip
The app does not auto-connect to Electrum until the user has selected a server (and has not explicitly disconnected). Fee/price/update HTTP is off until the user enables those sources. Optional notifications and connectivity keep-alive are off by default.
Built-in Tor (no Orbot required). SOCKS typically on 127.0.0.1:9050 (control-reported port if non-default). Electrum, fee/price clients, LN node clients, and selected L2 relays can route via SOCKS with DNS forced through the proxy (SocksProxyHostnameDns / equivalent) to reduce leaks.
Notes:
TorManager.start/stopare synchronized to avoid native races.- Full wipe stops Tor and deletes Tor data.
- Some L2 stacks have limitations (e.g. certain ASP HTTPS paths may not be Tor-routed depending on bindings)—check in-app behavior for the rail you use.
- Clearnet OkHttp paths that are not Tor-routed may use
PreferIpv4Dnsfor reliability (not a privacy feature).
Clearnet Electrum SSL uses TofuTrustManager:
| Case | Behavior |
|---|---|
.onion |
Trust cert (Tor authenticates the onion service); proxy may use a private trust-all factory only when no TOFU manager is attached |
| No stored fingerprint | CertificateFirstUseException → user must approve |
| Fingerprint match | Accept |
| Fingerprint change | CertificateMismatchException → warn (possible MITM) |
Approved fingerprints are stored for later sessions. Raw transaction responses from the Electrum bridge and the transaction cache are parsed with BDK and rejected if their canonical txid does not match the requested txid (SegWit-aware). First-use vs changed-certificate approval is surfaced via CertificateDialog (first-use approval vs MITM-change warning).
- Fee/price/custom explorer base URLs:
ServerUrlValidator(http/https, no credentials/query/fragment, path traversal rejected; host validated without relying on open redirects) - Electrum / Liquid Electrum hosts:
validateHostAndPort - Ark ASP / Esplora:
ArkEndpointValidator— clearnet https only;.onionmay use http (Tor) - Full-backup restore re-validates custom URLs and Ark endpoints; invalid values are skipped
- Ark auto-backup SAF folder URI is not restored across installs (device-local)
Optional sources (mempool.space clearnet/onion, bitview.space, Electrum, custom URL, CoinGecko, Yadio, etc.). Tor-aware HTTP clients use SOCKS and avoid local DNS when Tor is selected. Response bodies are size-capped (InputLimits).
Optional GitHub Releases API poll (AppUpdateService). Default off (welcome/opt-in). Release page URLs opened in a browser are restricted to https://github.com / www.github.com; anything else falls back to the official releases page. Notes length is capped. The downloaded APK is verified for package name, a signing certificate that also signs the installed app (Android enforces the full signer/rotation history at install time), and a strictly newer version before installation. The installer intent is addressed explicitly to the platform package installer (with manifest package queries), not a generic APK-MIME ACTION_VIEW. Users should still verify release artifacts out of band.
When connecting to a remote LND/CLN node:
- No credential-bearing auto-probe: the client uses the configured transport as-is (single candidate). Clearnet credentials are sent only over pinned-cert TLS, or over an explicitly acknowledged insecure transport — never via silent trust-all/plaintext probing. The setup form fails closed before any socket or credential use otherwise.
- Optional PEM pin (and optional mTLS client identity when the paste includes client key+cert)
- Clearnet TLS without a pasted cert fails closed unless the per-host "Allow insecure transport" acknowledgment is set (setup screen; persisted per wallet; never inferred from legacy flags, imports, or backups — pre-fix installs must re-pin or re-acknowledge)
- Clearnet plain HTTP requires the same explicit acknowledgment (setup-screen checkbox); the Test button stays disabled without it
.onionhosts via Tor need neither a cert nor the acknowledgment — Tor authenticates and encrypts the endpoint end-to-end (clearnet-over-Tor stays rejected; empty setup form defaults TLS off and auto-enables it when a clearnet host is typed, until the user touches the toggle)- Hostname verification stays on for all clearnet hosts (including IP literals and localhost) and is skipped only for
.onion; pinning is the integrity control when a cert is supplied. Acknowledged insecure transport uses trust-all and skips hostname verification for that host - Tor: SOCKS + DNS-through-proxy; HTTP/1.1 preferred over Tor
App-level cleartextTrafficPermitted stays enabled because LAN Electrum is an
intentional feature; Lightning Node cleartext is gated one layer up (per-host
acknowledgment + fail-closed clients), so the manifest flag alone cannot leak
macaroons/runes.
LND macaroon, CLN rune, TLS PEM, and NWC URI are spend secrets. Host/port/type may live in regular prefs. Compromise of those credentials is compromise of the remote node’s funds authority—not only the Ibis app sandbox.
NWC URI parsed strictly (nostr+walletconnect://, hex pubkey/secret, wss:// relays only). Payloads use NIP-44 v2 (secp256k1 ECDH + HKDF + ChaCha20 + HMAC-SHA256); legacy NIP-04 decrypt fallback is disabled by default (allowLegacyNip04Fallback = false). Responses are accepted within a 60s window with future-dated events rejected, and duplicate signed responses are ignored (replay guard).
Restored Lightning Node configs always start offline (restoreNeedsConfirm=true) until the user confirms in the Connection screen. The legacy allowInsecureTls backup flag is never restored as true without an explicit acknowledgedInsecure=true in the same backup JSON; the live config mirrors the explicit acknowledgment only. Pre-fix backups must re-pin or re-acknowledge before credentials travel over clearnet again.
Clearnet Esplora may fall back across reachable hosts with a user-visible notice; .onion hosts never fall back to clearnet. Automatic clearnet fallback can be disabled (Ark → Esplora auto-fallback setting, default on) for a fail-closed open that only contacts the configured host.
Incoming ACTION_VIEW intents and NFC reads only accept recognized payment formats (isRecognizedSendInput / payment URI schemes). Unrecognized or oversized payloads are dropped at ingest; recognized payloads carry an origin tag (deep link / NFC / external) for review surfaces. Input is held as pending send state, consumed after unlock, and shown in an explicit confirmation before it can replace a send draft—never auto-broadcast.
Onion explorer links prefer Tor Browser package when available; otherwise standard VIEW intents. Update/release links are sanitized as above.
User-initiated JSON backups can include wallets, settings, labels, and optional servers. The local Bark/Ark session database is intentionally excluded; external encrypted Ark DB backups are a separate, user-owned SAF copy.
- Optional password: AES-256-GCM with PBKDF2-HMAC-SHA256 at 600 000 iterations, random 16-byte salt, 12-byte IV (
CryptoUtils) - Temporary password char arrays used for PBKDF2 are cleared after use (the caller still holds a Java
Stringfor the operation duration) - Unencrypted export is allowed if the user opts out of a password—treat as seed-equivalent
- File reads are capped (
InputLimits.BACKUP_FILE_BYTES) - Labels from external files are sanitized (
BitcoinUtils.sanitizeExternalLabel/ BIP329 path) - Security-screen settings are intentionally excluded from full-backup app settings (PIN/duress/wipe/cloak/auto-wipe/screenshot/clipboard modes are not round-tripped as unlock material)
- Duress persona filtering applies to which wallets appear in backup UI
- Restore validates server hosts/ports and custom URLs; clamps gap limits; skips malformed wallet entries without aborting the whole restore
- Backup-provided Spark on-chain deposit addresses and pending deposits are not restored; the Spark SDK derives a fresh address
- Backup
liquidDescriptoris accepted only for watch-only wallets; seed wallets re-derive and repair - Liquid PSET sessions are bound to the wallet and load generation that created them; import/broadcast reject a different wallet session
- BOLT12 fetched invoices are signature-checked and bound to the reviewed offer and amount
Backups that contain seeds are as sensitive as the wallet itself. Store encrypted backups offline; never commit them to git or cloud sync without encryption you control.
Ark (Bark) state is not fully recoverable from seed alone: mailbox recovery rebuilds VTXOs after a fresh session (while the ASP/mailbox is available) but not local movement history. Encrypted DB backups use:
- Magic
IBARKENC, version byte, 12-byte nonce, AES-GCM ciphertext - Key: HKDF-SHA256 from BIP39 seed (
ibis-ark-backup/ibis-ark-backup-v1) - Wrong seed → authentication failure (treated as wrong wallet)
- Legacy plaintext zip still accepted by unwrap helpers when not encrypted
- External SAF backups survive app wipe by design
- Atomic install of zip payload; auto-backup to user SAF folder when configured
Import sanitizes labels; BIP329 spendable flags only apply to valid Bitcoin outpoint refs (cannot freeze arbitrary garbage strings).
| Rail | Secret / data handling |
|---|---|
| Liquid (LWK) | Seed-derived; Signer in memory; DB under filesDir/lwk/; CT descriptor as spend secret when stored, re-derived for seed wallets and accepted from backup only for watch-only wallets; PSET sessions are wallet-bound; refund detection expects the net swap amount |
| Spark | Seed wallets; SDK data under filesDir/spark/<walletId>; backup deposit address is never restored; CPFP signing validates sighash/outputs/fee; multi-send resumes and journals an uncertain state |
| Ark | Bark session data under cacheDir/ark-session/<walletId> (pre-open safety copies under cacheDir/ark-session-backups/); legacy filesDir/ark trees are scrub-only, never opened; encrypted external DB backups; native handle open/close serialized; offboard/recovery are serialized against unilateral exits; mailbox imports re-check server status; new LN sends are blocked while a prior Ark LN send is pending |
| Lightning Node | Remote auth secrets in SecureStorage; not a local hot LN keystore for NWC/LND/CLN credentials beyond what you paste |
Swaps (Boltz, SideSwap, etc.) involve third-party coordinators—standard swap counterparty and privacy tradeoffs apply. Loopback Tor relays may be used for onion Boltz/Esplora where bindings lack SOCKS.
| Use | Construction |
|---|---|
| EncryptedSharedPreferences | AES-256-GCM values, AES-256-SIV keys, Keystore master |
| Spend secret blob | AES-256-GCM, 12-byte IV, 128-bit tag |
| PIN hash / PIN wrap | PBKDF2-HMAC-SHA256, 150 000 iter, 16-byte salt |
| Backup file password | PBKDF2-HMAC-SHA256, 600 000 iter → AES-256-GCM |
| Ark backup | HKDF-SHA256 → AES-256-GCM |
| Biometric | Keystore AES/CBC/PKCS7, user auth required per use; unlock/prewarm never creates or deletes keys |
| BIP39 | Standard PBKDF2 with "mnemonic" salt (via wallet stack) |
| Electrum seeds | PBKDF2 with "electrum" salt where applicable |
| NWC | NIP-44 v2; legacy NIP-04 AES-CBC fallback disabled by default |
Randomness: SecureRandom for salts, IVs, and spend master keys.
- Receive: HCE NDEF service broadcasts payment URIs only while a receive payload is set; the payload is suspended when the app pauses, restored on resume, and cleared on dispose / lock. Prefer-service while receive screens request it.
- Send: Reader mode only on specific screens; no manifest-wide NFC intercept. Flags:
NFC_A|B|F|V+NO_PLATFORM_SOUNDS(does not skip NDEF check). - Read path: platform cached NDEF, then ISO-DEP Type 4 fallback for HCE peers.
- Payload schemes:
bitcoin:,lightning:,liquidnetwork:,liquid:(text fallback). - NFC hardware is optional (
required="false"); feature off by default in settings.
Treat NFC like showing a QR: anyone who can tap while receive is active can read the invoice/address payload.
External files, QR payloads, and HTTP JSON bodies are size-limited (InputLimits: small/medium/large JSON, backup, tx file, QR payload/parts). Prefer these helpers for new network/file parsers.
- Casual device access when app lock is enabled
- Shoulder surfing of balances (privacy mode,
FLAG_SECURE) - Coercion scenarios where a decoy wallet or wipe is acceptable
- Automated cloud/device backup exfiltration of app data
- Basic screenshot / overlay touch attacks
- Clearnet Electrum cert swap after first approved TOFU pin
- Network observers when Tor is correctly used end-to-end for that path
- Brute-force PIN guessing without rate limit / auto-wipe
- Trivial clipboard lingering of sensitive copies (auto-clear + optional lock/background clear)
- Oversized backup/HTTP/QR inputs via hard caps
- Compromised or rooted Android OS, malicious accessibility services, or device admin malware
- Physical access with chip-off / unlocked bootloader / debug bridges when the device is unlocked or Keystore is extractable
- An already-broken install whose PIN wrap was lost before the atomic-rotation fix, or a biometric-only install whose Keystore key was already invalidated—these require a seed/backup
- Cleartext LAN/HTTP server traffic (address/script-hash visibility and MITM), and Silent Payments scan-key exposure when an SP-capable server is reached over non-loopback/non-onion HTTP
- TOFU first-use MITM and short-PIN offline brute force if secure prefs/Keystore are compromised
- User who disables lock, shares seed, or stores unencrypted backups
- Malicious or compromised Electrum / explorer / ASP / swap / LN node the user chose
- Supply-chain compromise of the APK distribution channel if the user sideloads an unofficial build
- Advanced forensic recovery of wiped flash (auto-wipe is best-effort secure delete of app-owned files, not full-disk crypto erase)
- Traffic analysis when not using Tor, or when a subsystem cannot Tor-route
- Social engineering and $5 wrench attacks beyond duress/wipe features
- Cloak Mode against a forensic examiner who inspects installed packages / APKs
- Optional trust-all TLS to self-hosted LN nodes without a pinned cert
Hardware security modules and air-gapped signing (PSBT / animated QR) remain stronger for large cold storage than a hot phone wallet.
- Prefer official GitHub Releases.
- Build from source: JDK 17 language target,
./gradlew :app:assembleRelease(signing config required for release). The Gradle daemon JVM is auto-provisioned/pinned bygradle/gradle-daemon-jvm.properties; setJAVA_HOMEto Android Studio's JBR for CLI builds. - Min SDK 26; target/compile SDK per project (
app/build.gradle.kts); ABI:armeabi-v7a,arm64-v8a. - Release:
isMinifyEnabled+isShrinkResourceswithproguard-rules.pro(keeps UniFFI/JNA bindings, TOFU types, crypto, Tor, biometric). - Review dependency pins in
gradle/libs.versions.toml. - Do not put secrets in
gradle.propertiescommitted to VCS (e.g. injectSPARK_API_KEYvia env / local property only intoBuildConfig). - In-app update check does not replace verifying APK authenticity out-of-band.
AI-assisted audits are mentioned in the README; they are not a substitute for independent professional review. Most recent public audit note: see README / release tags.
For contributors and automation:
- Never log mnemonics, private keys, passwords, PINs, or LN auth material.
- Use
SecureStoragespend-secret APIs for new seed-equivalent / remote-auth secrets; do not store new spend capability only in regular prefs. - Prefer
SecureLogover rawLogin wallet paths; gate remaining diagnostics onBuildConfig.DEBUGwhere detail is needed. - Sanitize external strings (labels, URLs) before display or persistence.
- Validate URLs before opening in a browser; keep GitHub release URL allowlisting if extending update UI.
- Keep wipe / lockout / cloak writes on critical paths using
commit = truewhen process death follows. - Do not re-enable Android auto-backup or weaken
data_extraction_rules. - New persisted settings that affect security must round-trip in encrypted backup export/import or be explicitly documented as excluded (security-screen secrets stay excluded).
- Bound untrusted IO with
InputLimits/readBytesWithLimit/stringWithLimit. - When changing PIN length, wipe scope, Keystore aliases, backup crypto, Tor defaults, TOFU, or duress, update this file in the same change set.
Security-adjacent pure logic is covered under app/src/test, including: CryptoUtilsTest, ArkBackupCryptoTest, TofuTrustManagerTest, ServerUrlValidatorTest, ArkEndpointValidatorTest, BackupJsonAdaptersTest, NwcUriParserTest, NFC reader-request registry tests.
Ibis Wallet is open source under the MIT License. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND. You are solely responsible for your keys, backups, server choices, and operational security.
When changing security-relevant behavior (PIN parameters, wipe scope, Keystore aliases, backup crypto, Tor defaults, TOFU, duress, exported components, secret classification), update this file in the same change set.