rust/keystore: make bip39 unlocking async

This uses `to_seed_normalized_async(...).await` over
`to_seed_normalized(...)` in bip39 unlocking, propagating the
async/await keywords up the stack.

This commit by itself is not functional yet, as the unlock animation
is still timer-interrupt based, which leads to chaos. The next commit
converts the animation into an async task of its own, not depending on
interrupts.

The bip39 unlock loop is made to yield to the executor in each of the
2048 PBKDF2 stretch rounds. In the simulator however, we don't yield
and finish the computation in a blocking fashion like before, due to a
limitation of the simulator: it does not busy-loop the
mainloop (otherwise CPU would be at 100%), but only when there is an
incoming USB packet, so yielding in BIP39 would make unlocking in the
simulator *very* slow. Running the mainloop quicker in the simulator
does not work well: either CPU load is too high, or unlock is too slow.

Author: benma

src/CMakeLists.txt

@@ -53,7 +53,6 @@ set(DBB-FIRMWARE-USB-SOURCES ${DBB-FIRMWARE-USB-SOURCES} PARENT_SCOPE)
 set(DBB-FIRMWARE-UI-SOURCES
     ${CMAKE_SOURCE_DIR}/src/screen.c
     ${CMAKE_SOURCE_DIR}/src/ui/graphics/graphics.c
-    ${CMAKE_SOURCE_DIR}/src/ui/graphics/lock_animation.c
     ${CMAKE_SOURCE_DIR}/src/ui/ugui/ugui.c
     ${CMAKE_SOURCE_DIR}/src/ui/fonts/font_a_9X9.c
     ${CMAKE_SOURCE_DIR}/src/ui/fonts/font_a_11X10.c
@@ -85,6 +84,7 @@ set(DBB-FIRMWARE-UI-SOURCES
     ${CMAKE_SOURCE_DIR}/src/ui/components/orientation_arrows.c
     ${CMAKE_SOURCE_DIR}/src/ui/components/info_centered.c
     ${CMAKE_SOURCE_DIR}/src/ui/components/lockscreen.c
+    ${CMAKE_SOURCE_DIR}/src/ui/components/unlock_animation.c
     ${CMAKE_SOURCE_DIR}/src/ui/components/menu.c
     ${CMAKE_SOURCE_DIR}/src/ui/components/status.c
     ${CMAKE_SOURCE_DIR}/src/ui/components/image.c

src/rust/bitbox02-rust/src/keystore.rs

@@ -270,6 +270,7 @@ mod tests {
     use bitbox02::testing::{
         TEST_MNEMONIC, mock_memory, mock_unlocked, mock_unlocked_using_mnemonic,
     };
+    use util::bb02_async::block_on;
 
     use bitcoin::secp256k1;
 
@@ -573,7 +574,15 @@ mod tests {
             keystore::lock();
             let seed = &seed[..test.seed_len];
 
-            assert!(keystore::unlock_bip39(SECP256K1, seed, test.mnemonic_passphrase).is_err());
+            assert!(
+                block_on(keystore::unlock_bip39(
+                    SECP256K1,
+                    seed,
+                    test.mnemonic_passphrase,
+                    async || {}
+                ))
+                .is_err()
+            );
 
             bitbox02::securechip::fake_event_counter_reset();
             assert!(keystore::encrypt_and_store_seed(seed, "foo").is_ok());
@@ -582,7 +591,15 @@ mod tests {
             assert!(keystore::is_locked());
 
             bitbox02::securechip::fake_event_counter_reset();
-            assert!(keystore::unlock_bip39(SECP256K1, seed, test.mnemonic_passphrase).is_ok());
+            assert!(
+                block_on(keystore::unlock_bip39(
+                    SECP256K1,
+                    seed,
+                    test.mnemonic_passphrase,
+                    async || {}
+                ))
+                .is_ok()
+            );
             assert_eq!(bitbox02::securechip::fake_event_counter(), 1);
 
             assert!(!keystore::is_locked());

src/rust/bitbox02-rust/src/workflow.rs

@@ -27,6 +27,7 @@ pub mod transaction;
 pub mod trinary_choice;
 pub mod trinary_input_string;
 pub mod unlock;
+pub mod unlock_animation;
 pub mod verify_message;
 
 use alloc::string::String;

src/rust/bitbox02-rust/src/workflow/unlock.rs

@@ -133,9 +133,23 @@ pub async fn unlock_bip39(hal: &mut impl crate::hal::Hal, seed: &[u8]) {
         }
     }
 
-    let result = bitbox02::ui::with_lock_animation(|| {
-        keystore::unlock_bip39(crate::secp256k1::SECP256K1, seed, &mnemonic_passphrase)
-    });
+    let ((), result) = util::bb02_async::join(
+        super::unlock_animation::animate(),
+        keystore::unlock_bip39(
+            crate::secp256k1::SECP256K1,
+            seed,
+            &mnemonic_passphrase,
+            // for the simulator, we don't yield at all, otherwise unlock becomes very slow in the
+            // simulator.
+            #[cfg(feature = "c-unit-testing")]
+            async || {},
+            // we yield every time to keep the processing time per iteration to a minimum.
+            #[cfg(not(feature = "c-unit-testing"))]
+            util::bb02_async::yield_now,
+        ),
+    )
+    .await;
+
     if result.is_err() {
         abort("bip39 unlock failed");
     }

src/rust/bitbox02-rust/src/workflow/unlock_animation.rs

@@ -0,0 +1,27 @@
+// Copyright 2025 Shift Crypto AG
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use crate::bb02_async::option_no_screensaver;
+use core::cell::RefCell;
+
+/// Performs the unlock animation. Its duration is determined by the component render rate, see
+/// unlock_animation.c
+pub async fn animate() {
+    let result = RefCell::new(None as Option<()>);
+    let mut component = bitbox02::ui::unlock_animation_create(|| {
+        *result.borrow_mut() = Some(());
+    });
+    component.screen_stack_push();
+    option_no_screensaver(&result).await
+}

src/rust/bitbox02-sys/build.rs

@@ -67,6 +67,7 @@ const ALLOWLIST_FNS: &[&str] = &[
     "delay_ms",
     "delay_us",
     "empty_create",
+    "unlock_animation_create",
     "keystore_bip39_mnemonic_to_seed",
     "keystore_copy_seed",
     "keystore_copy_bip39_seed",
@@ -85,8 +86,6 @@ const ALLOWLIST_FNS: &[&str] = &[
     "keystore_test_get_retained_bip39_seed_encrypted",
     "label_create",
     "localtime",
-    "lock_animation_start",
-    "lock_animation_stop",
     "memory_set_salt_root",
     "memory_add_noise_remote_static_pubkey",
     "memory_bootloader_hash",
@@ -212,6 +211,7 @@ const BITBOX02_SOURCES: &[&str] = &[
     "src/ui/components/label.c",
     "src/ui/components/left_arrow.c",
     "src/ui/components/lockscreen.c",
+    "src/ui/components/unlock_animation.c",
     "src/ui/components/menu.c",
     "src/ui/components/orientation_arrows.c",
     "src/ui/components/progress.c",
@@ -235,7 +235,6 @@ const BITBOX02_SOURCES: &[&str] = &[
     "src/ui/fonts/password_11X12.c",
     "src/ui/fonts/password_9X9.c",
     "src/ui/graphics/graphics.c",
-    "src/ui/graphics/lock_animation.c",
     "src/ui/oled/sh1107.c",
     "src/ui/oled/ssd1312.c",
     "src/ui/screen_process.c",

src/rust/bitbox02-sys/wrapper.h

@@ -39,11 +39,11 @@
 #include <ui/components/status.h>
 #include <ui/components/trinary_choice.h>
 #include <ui/components/trinary_input_string.h>
+#include <ui/components/unlock_animation.h>
 #include <ui/fonts/font_a_11X10.h>
 #include <ui/fonts/font_a_9X9.h>
 #include <ui/fonts/monogram_5X9.h>
 #include <ui/fonts/password_11X12.h>
-#include <ui/graphics/lock_animation.h>
 #include <ui/oled/oled.h>
 #include <ui/screen_process.h>
 #include <ui/screen_saver.h>

src/rust/bitbox02/src/keystore.rs

@@ -111,14 +111,18 @@ fn unlock_bip39_finalize(bip39_seed: &[u8; 64]) -> Result<(), Error> {
     }
 }
 
-fn derive_bip39_seed(
+async fn derive_bip39_seed(
     secp: &Secp256k1<All>,
     seed: &[u8],
     mnemonic_passphrase: &str,
+    yield_now: impl AsyncFn(),
 ) -> (zeroize::Zeroizing<[u8; 64]>, [u8; 4]) {
     let mnemonic = bip39::Mnemonic::from_entropy_in(bip39::Language::English, seed).unwrap();
-    let bip39_seed: zeroize::Zeroizing<[u8; 64]> =
-        zeroize::Zeroizing::new(mnemonic.to_seed_normalized(mnemonic_passphrase));
+    let bip39_seed: zeroize::Zeroizing<[u8; 64]> = zeroize::Zeroizing::new(
+        mnemonic
+            .to_seed_normalized_async(mnemonic_passphrase, yield_now)
+            .await,
+    );
     let root_fingerprint: [u8; 4] =
         bitcoin::bip32::Xpriv::new_master(bitcoin::NetworkKind::Main, bip39_seed.as_ref())
             .unwrap()
@@ -132,14 +136,16 @@ fn derive_bip39_seed(
 /// of `keystore_copy_seed()`).
 /// `mnemonic_passphrase` is the bip39 passphrase used in the derivation. Use the empty string if no
 /// passphrase is needed or provided.
-pub fn unlock_bip39(
+pub async fn unlock_bip39(
     secp: &Secp256k1<All>,
     seed: &[u8],
     mnemonic_passphrase: &str,
+    yield_now: impl AsyncFn(),
 ) -> Result<(), Error> {
     unlock_bip39_check(seed)?;
 
-    let (bip39_seed, root_fingerprint) = derive_bip39_seed(secp, seed, mnemonic_passphrase);
+    let (bip39_seed, root_fingerprint) =
+        derive_bip39_seed(secp, seed, mnemonic_passphrase, yield_now).await;
 
     unlock_bip39_finalize(bip39_seed.as_slice().try_into().unwrap())?;
 
@@ -279,6 +285,7 @@ mod tests {
     use bitcoin::secp256k1;
 
     use crate::testing::{mock_memory, mock_unlocked_using_mnemonic};
+    use util::bb02_async::block_on;
 
     #[test]
     fn test_secp256k1_sign() {
@@ -442,7 +449,15 @@ mod tests {
             .unwrap();
         assert!(encrypt_and_store_seed(&seed, "password").is_ok());
         assert!(is_locked()); // still locked, it is only unlocked after unlock_bip39.
-        assert!(unlock_bip39(&secp256k1::Secp256k1::new(), &seed, "foo").is_ok());
+        assert!(
+            block_on(unlock_bip39(
+                &secp256k1::Secp256k1::new(),
+                &seed,
+                "foo",
+                async |_idx| {}
+            ))
+            .is_ok()
+        );
         assert!(!is_locked());
         lock();
         assert!(is_locked());
@@ -572,7 +587,12 @@ mod tests {
         let secp = secp256k1::Secp256k1::new();
         for test in tests {
             let seed = hex::decode(test.seed).unwrap();
-            let (bip39_seed, root_fingerprint) = derive_bip39_seed(&secp, &seed, test.passphrase);
+            let (bip39_seed, root_fingerprint) = block_on(derive_bip39_seed(
+                &secp,
+                &seed,
+                test.passphrase,
+                async |_idx| {},
+            ));
             assert_eq!(hex::encode(bip39_seed).as_str(), test.expected_bip39_seed);
             assert_eq!(
                 hex::encode(root_fingerprint).as_str(),
@@ -600,9 +620,17 @@ mod tests {
         assert!(encrypt_and_store_seed(&seed, "password").is_ok());
         assert!(root_fingerprint().is_err());
         // Incorrect seed passed
-        assert!(unlock_bip39(&secp, b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "foo").is_err());
+        assert!(
+            block_on(unlock_bip39(
+                &secp,
+                b"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "foo",
+                async |_idx| {}
+            ))
+            .is_err()
+        );
         // Correct seed passed.
-        assert!(unlock_bip39(&secp, &seed, "foo").is_ok());
+        assert!(block_on(unlock_bip39(&secp, &seed, "foo", async |_idx| {})).is_ok());
         assert_eq!(root_fingerprint(), Ok(vec![0xf1, 0xbc, 0x3c, 0x46]),);
 
         let expected_bip39_seed = hex::decode("2b3c63de86f0f2b13cc6a36c1ba2314fbc1b40c77ab9cb64e96ba4d5c62fc204748ca6626a9f035e7d431bce8c9210ec0bdffc2e7db873dee56c8ac2153eee9a").unwrap();

src/rust/bitbox02/src/testing.rs

@@ -22,7 +22,13 @@ pub fn mock_unlocked_using_mnemonic(mnemonic: &str, passphrase: &str) {
     unsafe {
         bitbox02_sys::keystore_mock_unlocked(seed.as_ptr(), seed.len() as _, core::ptr::null())
     }
-    keystore::unlock_bip39(&bitcoin::secp256k1::Secp256k1::new(), &seed, passphrase).unwrap();
+    util::bb02_async::block_on(keystore::unlock_bip39(
+        &bitcoin::secp256k1::Secp256k1::new(),
+        &seed,
+        passphrase,
+        async || {},
+    ))
+    .unwrap();
 }
 
 pub const TEST_MNEMONIC: &str = "purity concert above invest pigeon category peace tuition hazard vivid latin since legal speak nation session onion library travel spell region blast estate stay";

src/rust/bitbox02/src/ui/ui.rs

@@ -436,13 +436,6 @@ pub fn trinary_input_string_set_input(component: &mut Component, word: &str) {
     }
 }
 
-pub fn with_lock_animation<F: Fn() -> R, R>(f: F) -> R {
-    unsafe { bitbox02_sys::lock_animation_start() };
-    let result = f();
-    unsafe { bitbox02_sys::lock_animation_stop() };
-    result
-}
-
 pub fn screen_stack_pop_all() {
     unsafe {
         bitbox02_sys::ui_screen_stack_pop_all();
@@ -476,3 +469,31 @@ pub fn empty_create<'a>() -> Component<'a> {
         _p: PhantomData,
     }
 }
+
+pub fn unlock_animation_create<'a, F>(on_done: F) -> Component<'a>
+where
+    // Callback must outlive component.
+    F: FnMut() + 'a,
+{
+    unsafe extern "C" fn c_on_done<F2>(param: *mut c_void)
+    where
+        F2: FnMut(),
+    {
+        // The callback is dropped afterwards. This is safe because
+        // this C callback is guaranteed to be called only once.
+        let mut on_done = unsafe { Box::from_raw(param as *mut F2) };
+        on_done();
+    }
+    let component = unsafe {
+        bitbox02_sys::unlock_animation_create(
+            Some(c_on_done::<F>),
+            Box::into_raw(Box::new(on_done)) as *mut _, // passed to c_on_done as `param`.
+        )
+    };
+    Component {
+        component,
+        is_pushed: false,
+        on_drop: None,
+        _p: PhantomData,
+    }
+}