Add hdkey module

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.3] 2026-04-09
+
+### Added
+- Add the support of ZIP32 Sapling, Orchard and Register derivations
+- Add the support of BIP32-like derivation with BLS12-377 curve
+
 ## [0.26.2] 2026-03-26
 
 ### Changed

sdk/bolos_syscalls.h

@@ -283,6 +283,8 @@
 
 #define SYSCALL_nbgl_get_font_ID_IN                                   0x01fa000c
 
+#define SYSCALL_hdkey_derive_ID_IN 0x0a000002
+
 /**********************
  *      TYPEDEFS
  **********************/

src/CMakeLists.txt

@@ -64,6 +64,12 @@ add_library(emu
         bolos/io/sdk/io/src/os_io_seph_ux.c
         bolos/io/sdk/io/src/os_io.c
         bolos/io/mock/src/mock.c
+        bolos/os_hdkey.c
+        bolos/hdkey/src/hdkey.c
+        bolos/hdkey/src/hdkey_validate.c
+        bolos/hdkey/src/hdkey_zip32.c
+        bolos/hdkey/src/hdkey_bip32.c
+        bolos/hdkey/src/hdkey_bls12377.c
         emulate.c
         environment.c
         svc.c)
@@ -75,7 +81,8 @@ bolos/io/sdk/io/include
 bolos/io/sdk/protocol/include
 bolos/io/sdk/lib_stusb/include
 bolos/io/sdk/lib_nfc/include
-bolos)
+bolos/
+bolos/hdkey/include)
 
 add_compile_definitions(emu
 HAVE_BOLOS=1
@@ -107,4 +114,3 @@ else ()
   message(FATAL_ERROR "Unable to identify the compiler!")
 endif ()
 target_link_libraries(launcher PRIVATE emu)
-

src/bolos/cx_utils.c

@@ -316,10 +316,42 @@ uint32_t U4BE(const uint8_t *buf, size_t off)
          (buf[off + 2] << 8) | buf[off + 3];
 }
 
+void U4LE_ENCODE(uint8_t *buf, size_t off, uint32_t value)
+{
+  buf[off + 3] = (value >> 24) & 0xFF;
+  buf[off + 2] = (value >> 16) & 0xFF;
+  buf[off + 1] = (value >> 8) & 0xFF;
+  buf[off + 0] = value & 0xFF;
+}
+
 void cx_memxor(uint8_t *buf1, const uint8_t *buf2, size_t len)
 {
   size_t i;
   for (i = 0; i < len; i++) {
     buf1[i] ^= buf2[i];
   }
 }
+
+/**
+ * @brief Reverse byte order in a buffer.
+ * @param[in, out] buffer Pointer to the buffer to reverse.
+ * @param[in] len Length of the buffer.
+ */
+void cx_swap_bytes(uint8_t *buffer, size_t len)
+{
+  uint8_t t;
+  size_t i = 0;
+  size_t j = len - 1;
+
+  if (buffer == NULL || len <= 1) {
+    return;
+  }
+
+  while (i < j) {
+    t = buffer[i];
+    buffer[i] = buffer[j];
+    buffer[j] = t;
+    i++;
+    j--;
+  }
+}

src/bolos/cx_utils.h

@@ -112,4 +112,6 @@ void U2BE_ENCODE(uint8_t *buf, size_t off, uint32_t value);
 void U4BE_ENCODE(uint8_t *buf, size_t off, uint32_t value);
 uint16_t U2BE(const uint8_t *buf, size_t off);
 uint32_t U4BE(const uint8_t *buf, size_t off);
+void U4LE_ENCODE(uint8_t *buf, size_t off, uint32_t value);
 void cx_memxor(uint8_t *buf1, const uint8_t *buf2, size_t len);
+void cx_swap_bytes(uint8_t *buffer, size_t len);

src/bolos/cxlib.h

@@ -27,6 +27,16 @@
     }                                                                          \
   } while (0)
 
+#define ERROR_CHECK(func, success, ret)                                        \
+  do {                                                                         \
+    error = func;                                                              \
+    if (error != success) {                                                    \
+      error = ret;                                                             \
+      goto end;                                                                \
+    }                                                                          \
+    error = CX_OK;                                                             \
+  } while (0)
+
 #define CX_OK 0x00000000
 
 #define CX_CARRY 0xFFFFFF21

src/bolos/hdkey/include/hdkey.h

@@ -0,0 +1,65 @@
+/**
+ * @file hdkey.h
+ * @brief This is the public header file for hdkey.c.
+ */
+
+#pragma once
+
+/*********************
+ *      INCLUDES
+ *********************/
+#include "cx.h"
+#include "os_hdkey.h"
+#include "os_result.h"
+#include "os_types.h"
+#include <stddef.h>
+
+/*********************
+ *      DEFINES
+ *********************/
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+/**
+ * @brief HDKEY structure.
+ */
+typedef struct HDKEY_params_s {
+  HDKEY_derive_mode_t mode; // Derivation mode
+  bolos_bool_t
+      from_app;     // True if the caller is an application, false otherwise
+  cx_curve_t curve; // Curve identifier
+  size_t path_len;  // Path length (number of indices)
+  size_t private_key_len;  // Private key length
+  size_t chain_len;        // Chain code length
+  size_t seed_key_len;     // Expanding seed key length
+  const uint32_t *path;    // Pointer to the derivation path buffer
+  uint8_t *private_key;    // Pointer to the private key buffer
+  uint8_t *chain;          // Pointer to the chain buffer
+  const uint8_t *seed_key; // Pointer to the expanding key buffer
+} HDKEY_params_t;
+
+/**********************
+ * STATIC VARIABLES
+ **********************/
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+/**
+ * @brief Internal function for hierarchical deterministic derivation.
+ * @param[in] params Pointer to the HDKEY structure.
+ * @return os_result_t
+ * @retval 0x0000 Success
+ * @retval OS_ERR_ACCESS_DENIED PIN must be validated
+ * @retval OS_ERR_NOT_FOUND Unknown caller identity
+ * @retval OS_ERR_INTEGRITY Integrity check failure
+ * @retval OS_ERR_OVERFLOW Unsupported path length
+ * @retval OS_ERR_BAD_FORMAT Invalid path format
+ * @retval OS_ERR_NOT_IMPLEMENTED Unknown parameter
+ * @retval OS_ERR_FORBIDDEN Forbidden derivation
+ * @retval OS_ERR_CRYPTO_INTERNAL Cryptographic computation failure
+ * @retval OS_ERR_SHORT_BUFFER Buffer overflow
+ * @retval OS_ERR_BAD_PARAM Invalid parameter
+ */
+os_result_t HDKEY_derive(HDKEY_params_t *params);

src/bolos/hdkey/include/hdkey_bip32.h

@@ -0,0 +1,88 @@
+/**
+ * @file hdkey_bip32.h
+ * @brief This is the public header file for hdkey_bip32.c.
+ */
+
+#pragma once
+
+/*********************
+ *      INCLUDES
+ *********************/
+#include "hdkey.h"
+#include "os_result.h"
+
+/*********************
+ *      DEFINES
+ *********************/
+#define HDKEY_BIP32_KEY_LEN         (CX_SHA512_SIZE / 2)
+#define HDKEY_BIP32_ED25519_KEY_LEN (96u)
+#define HDKEY_BIP32_WILDCARD_VALUE  (0x7fffffff)
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+/**
+ * @brief Seed type.
+ */
+typedef enum {
+  HDKEY_BIP32_NVM_SEED, // Seed stored in NVM (default and passphrase seeds: 64
+                        // bytes)
+} hdkey_bip32_seed_type_t;
+
+/**********************
+ * STATIC VARIABLES
+ **********************/
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * @brief Gets the default HMAC key and computes the seed HMAC value.
+ * @param[in] params Pointer to the HDKEY structure.
+ * @param[out] result Pointer to the buffer to write the HMAC value, of length
+ * result_len
+ * @param[in] result_len Result buffer length, must be either 64 bytes or 96
+ * bytes depending on the curve parameter.
+ * @return os_result_t
+ * @retval OS_SUCCESS Success
+ * @retval OS_ERR_BAD_PARAM Invalid parameter
+ */
+os_result_t HDKEY_BIP32_compute_seed_hmac(HDKEY_params_t *params,
+                                          hdkey_bip32_seed_type_t seed,
+                                          uint8_t *result, size_t result_len);
+
+/**
+ * @brief Gets the seed HMAC value.
+ * @param[in] params Pointer to the HDKEY structure.
+ * @param[out] seed_hmac Pointer to the buffer to write the HMAC value, of
+ * length result_len
+ * @param[in] seed_hmac_len Result buffer length, must be either 64 bytes or 96
+ * bytes depending on the curve parameter.
+ * @return os_result_t
+ * @retval OS_SUCCESS Success
+ * @retval OS_ERR_BAD_PARAM Invalid parameter
+ * @retval OS_ERR_ACCESS_DENIED Unknown caller identity
+ */
+os_result_t HDKEY_BIP32_get_seed_hmac(HDKEY_params_t *params,
+                                      uint8_t *seed_hmac, size_t seed_hmac_len);
+
+/**
+ * @brief Recomputes a HMAC value to make sure that the result has the right
+ * format and within curve range. Must be called after
+ * HDKEY_BIP32_compute_seed_hmac for BIP32 derivation.
+ * @param[in] params Pointer to the HDKEY structure.
+ * @param[out] result Pointer to the buffer to write the HMAC value, of length
+ * result_len
+ * @param[in] result_len Result buffer length, must be either 64 bytes or 96
+ * bytes depending on the curve parameter.
+ * @param[in] seed_len Previously computed HMAC value length.
+ * @return os_result_t
+ * @retval OS_SUCCESS Success
+ * @retval OS_ERR_BAD_PARAM Invalid parameter
+ * @retval OS_ERR_CRYPTO_INTERNAL Cryptographic computation failure
+ */
+os_result_t HDKEY_BIP32_compute_seed_hmac_final(HDKEY_params_t *params,
+                                                uint8_t *result,
+                                                size_t result_len,
+                                                size_t seed_len);

src/bolos/hdkey/include/hdkey_bls12377.h

@@ -0,0 +1,43 @@
+/**
+ * @file hdkey_bls12377.h
+ * @brief This is the public header file for hdkey_bls12377.c.
+ */
+
+#pragma once
+
+/*********************
+ *      INCLUDES
+ *********************/
+#include "hdkey.h"
+#include "os_result.h"
+
+/*********************
+ *      DEFINES
+ *********************/
+/**
+ * @brief BLS12377 key length in bytes. Child key length and chain code length
+ * are equal
+ */
+#define HDKEY_BLS12377_KEY_LEN (CX_SHA512_SIZE / 2)
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+
+/**********************
+ * STATIC VARIABLES
+ **********************/
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * @brief BLS12-377 BIP32-like derivation.
+ * @param[in, out] params Pointer to the HDKEY structure.
+ * @return os_result_t
+ * @retval OS_SUCCESS Success
+ * @retval OS_ERR_BAD_PARAM Invalid parameter
+ * @retval OS_ERR_ACCESS_DENIED Unknown caller identity
+ */
+os_result_t HDKEY_BLS12377_derive(HDKEY_params_t *params);

src/bolos/hdkey/include/hdkey_validate.h

@@ -0,0 +1,43 @@
+/**
+ * @file hdkey_validate.h
+ * @brief This is the public header file for hdkey_validate.c.
+ */
+
+#pragma once
+
+/*********************
+ *      INCLUDES
+ *********************/
+#include "hdkey.h"
+#include <stddef.h>
+
+/*********************
+ *      DEFINES
+ *********************/
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+
+/**********************
+ * STATIC VARIABLES
+ **********************/
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * @brief Validates secure context before derivation.
+ * @param[in] params Pointer to the HDKEY structure.
+ * @return os_result_t
+ * @retval OS_SUCCESS Success
+ * @retval OS_ERR_BAD_PARAM Invalid parameter
+ * @retval OS_ERR_NOT_FOUND Unauthorized curve or unknown caller identity
+ * @retval OS_ERR_NOT_IMPLEMENTED Unknown parameter
+ * @retval OS_ERR_FORBIDDEN Unauthorized derivation path
+ * @retval OS_ERR_ACCESS_DENIED PIN must be validated
+ * @retval OS_ERR_BAD_FORMAT Invalid path format
+ * @retval OS_ERR_INTEGRITY Integrity check failure
+ */
+os_result_t HDKEY_VALIDATE_secure_context(HDKEY_params_t *params);