refactor(core): improve random_delays api

core/embed/bootloader/main.c

@@ -359,7 +359,7 @@ int bootloader_main(void) {
 
   system_init(&rsod_panic_handler);
 
-  rdi_init();
+  random_delays_init();
 
 #if defined TREZOR_MODEL_T
   set_core_clock(CLOCK_180_MHZ);

core/embed/bootloader_ci/main.c

@@ -181,7 +181,7 @@ static secbool check_vendor_header_lock(const vendor_header *const vhdr) {
 int main(void) {
   system_init(&rsod_panic_handler);
 
-  rdi_init();
+  random_delays_init();
 #ifdef USE_TOUCH
   touch_init();
 #endif

core/embed/kernel/main.c

@@ -77,10 +77,10 @@ void drivers_init() {
   tamper_init();
 #endif
 
-  rdi_init();
+  random_delays_init();
 
 #ifdef RDI
-  rdi_start();
+  random_delays_start_rdi();
 #endif
 
 #ifdef SYSTEM_VIEW

core/embed/trezorhal/random_delays.h

@@ -22,17 +22,48 @@
 
 #include <stdint.h>
 
+/*
+Random delay interrupts (RDI) is a contermeasure against side channel attacks.
+It consists of an interrupt handler that is supposed to be called every
+millisecond or so. The handler waits for a random number of cpu ticks that is a
+sample of so called floating mean distribution. That means that the number is
+the sum of two numbers generated uniformly at random in the interval [0, 255].
+The first number is generated freshly for each call of the handler, the other
+number is supposed to be refreshed when the device performs an operation that
+leaks the current state of the execution flow, such as sending or receiving an
+usb packet.
+
+See Differential Power Analysis in the Presence of Hardware Countermeasures by
+Christophe Clavier, Jean-Sebastien Coron, Nora Dabbous and Efficient Use of
+Random Delays in Embedded Software by Michael Tunstall, Olivier Benoit:
+https://link.springer.com/content/pdf/10.1007%2F3-540-44499-8_20.pdf
+https://link.springer.com/content/pdf/10.1007%2F978-3-540-72354-7_3.pdf
+*/
+
 #ifdef KERNEL_MODE
 
-void rdi_init(void);
+// Initializes the random number generator for `wait_random()` and the RDI
+//
+// RDI is stopped by default and can be started by calling
+// `random_delays_start_rdi()`.
+void random_delays_init(void);
 
-void rdi_start(void);
-void rdi_stop(void);
+// Starts the RDI, introducing small random delays every millisecond via
+// systimer callback.
+void random_delays_start_rdi(void);
 
-#endif
+// Stops the RDI
+void random_delays_stop_rdi(void);
 
-void rdi_refresh_session_delay(void);
+// Refreshes the second random number in the floating mean distribution.
+// (see the module description above)
+void random_delays_refresh_rdi(void);
 
+// Waits for a random number (0-255) of CPU ticks.
+//
+// This function is independent of the RDI and can be used in any context.
 void wait_random(void);
 
+#endif  // KERNEL_MODE
+
 #endif  // TREZORHAL_RANDOM_DELAYS_H

core/embed/trezorhal/stm32f4/random_delays.c

@@ -17,24 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/*
-Random delay interrupts (RDI) is a contermeasure against side channel attacks.
-It consists of an interrupt handler that is supposed to be called every
-millisecond or so. The handler waits for a random number of cpu ticks that is a
-sample of so called floating mean distribution. That means that the number is
-the sum of two numbers generated uniformly at random in the interval [0, 255].
-The first number is generated freshly for each call of the handler, the other
-number is supposed to be refreshed when the device performs an operation that
-leaks the current state of the execution flow, such as sending or receiving an
-usb packet.
-
-See Differential Power Analysis in the Presence of Hardware Countermeasures by
-Christophe Clavier, Jean-Sebastien Coron, Nora Dabbous and Efficient Use of
-Random Delays in Embedded Software by Michael Tunstall, Olivier Benoit:
-https://link.springer.com/content/pdf/10.1007%2F3-540-44499-8_20.pdf
-https://link.springer.com/content/pdf/10.1007%2F978-3-540-72354-7_3.pdf
-*/
-
 #include "random_delays.h"
 
 #include <stdatomic.h>
@@ -157,15 +139,15 @@ static void wait(uint32_t delay) {
 // forward declaration
 static void rdi_handler(void *context);
 
-void rdi_init() {
+void random_delays_init() {
   drbg_init();
 
   systimer_t *timer = systimer_create(rdi_handler, NULL);
-  ensure(sectrue * (timer != NULL), "rdi_init failed");
+  ensure(sectrue * (timer != NULL), "random_delays_init failed");
   systimer_set_periodic(timer, 1);
 }
 
-void rdi_start(void) {
+void random_delays_start_rdi(void) {
   ensure(drbg_initialized, NULL);
 
   if (rdi_disabled == sectrue) {  // if rdi disabled
@@ -174,14 +156,14 @@ void rdi_start(void) {
   }
 }
 
-void rdi_stop(void) {
+void random_delays_stop_rdi(void) {
   if (rdi_disabled == secfalse) {  // if rdi enabled
     rdi_disabled = sectrue;
     session_delay = 0;
   }
 }
 
-void rdi_refresh_session_delay(void) {
+void random_delays_refresh_rdi(void) {
   if (rdi_disabled == secfalse)  // if rdi enabled
     refresh_session_delay = true;
 }

core/embed/trezorhal/stm32f4/usb/usb.c

@@ -644,7 +644,7 @@ static uint8_t usb_class_data_in(USBD_HandleTypeDef *dev, uint8_t ep_num) {
   usb_driver_t *drv = &g_usb_driver;
 
 #ifdef RDI
-  rdi_refresh_session_delay();
+  random_delays_refresh_rdi();
 #endif
 
   for (int i = 0; i < USBD_MAX_NUM_INTERFACES; i++) {
@@ -664,7 +664,7 @@ static uint8_t usb_class_data_out(USBD_HandleTypeDef *dev, uint8_t ep_num) {
   usb_driver_t *drv = &g_usb_driver;
 
 #ifdef RDI
-  rdi_refresh_session_delay();
+  random_delays_refresh_rdi();
 #endif
 
   for (int i = 0; i < USBD_MAX_NUM_INTERFACES; i++) {

core/embed/trezorhal/unix/random_delays.c

@@ -19,6 +19,6 @@
 
 #include "random_delays.h"
 
-void wait_random(void) {}
+void random_delays_init(void) {}
 
-void rdi_init(void) {}
+void wait_random(void) {}