Added detailed documentation for all SSKR and SSS functions

Author: aido

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Change log
 
-## [1.7.0] - 2024-03-02
+## [1.7.0] - 2024-03-03
 ### Added
--
+- Added detailed documentation for all SSKR and SSS functions
 
 ### Changed
 - Changed Shamir interpolate function to use `cx_bn_gf2_n_mul()` syscalls

src/sskr/sskr.c

@@ -15,6 +15,20 @@
 
 #define memzero(...) explicit_bzero(__VA_ARGS__)
 
+/**
+ * @brief Validates the length of a secret for SSKR functions.
+ *
+ * @details This function checks if the length of a secret is within the acceptable
+ *          range for use in SSKR. It enforces constraints on the secret length to
+ *          ensure security and compatibility.
+ *
+ * @param[in] len  Length of the secret in bytes.
+ *
+ * @return 0 on success, indicating a valid secret length, or a negative error code on failure:
+ *         - SSKR_ERROR_SECRET_TOO_SHORT: if len is less than SSKR_MIN_STRENGTH_BYTES
+ *         - SSKR_ERROR_SECRET_TOO_LONG: if len is greater than SSKR_MAX_STRENGTH_BYTES
+ *         - SSKR_ERROR_SECRET_LENGTH_NOT_EVEN: if len is not even
+ */
 static int16_t sskr_check_secret_length(uint8_t len) {
     if (len < SSKR_MIN_STRENGTH_BYTES) {
         return SSKR_ERROR_SECRET_TOO_SHORT;
@@ -28,6 +42,21 @@ static int16_t sskr_check_secret_length(uint8_t len) {
     return 0;
 }
 
+/**
+ * @brief Serializes an SSKR shard into a byte array.
+ *
+ * @details This function converts an `sskr_shard_t` structure into a byte array suitable for
+ *          storage or transmission. It packs the shard's metadata (identifier, group/member
+ *          information) and value into a single buffer.
+ *
+ * @param[in]  shard           Pointer to the `sskr_shard_t` structure to be serialized.
+ * @param[out] destination     Pointer to the buffer where the serialized data will be written.
+ * @param[in]  destination_len Length of the `destination` buffer in bytes.
+ *
+ * @return Length of the serialized shard data on success, or a negative error code:
+ *         - SSKR_ERROR_INSUFFICIENT_SPACE: if `destination_len` is not enough to hold the
+ *           serialized data.
+ */
 static int16_t sskr_serialize_shard(const sskr_shard_t *shard,
                                     uint8_t *destination,
                                     uint16_t destination_len) {
@@ -68,6 +97,25 @@ static int16_t sskr_serialize_shard(const sskr_shard_t *shard,
     return shard->value_len + SSKR_METADATA_LENGTH_BYTES;
 }
 
+/**
+ * @brief Deserializes an SSKR shard from a byte array.
+ *
+ * @details This function reconstructs an `sskr_shard_t` structure from a serialized
+ *          byte array created using `sskr_serialize_shard`. It validates the metadata
+ *          and extracts the shard's identifier, group/member information, and value.
+ *
+ * @param[in]  source      Pointer to the serialized shard data.
+ * @param[in]  source_len  Length of the `source` array in bytes.
+ * @param[out] shard       Pointer to an `sskr_shard_t` structure to be populated.
+ *
+ * @return Length of the shard value on success, or a negative error code:
+ *         - SSKR_ERROR_NOT_ENOUGH_SERIALIZED_BYTES: if `source_len` is too short.
+ *         - SSKR_ERROR_INVALID_GROUP_THRESHOLD: if group threshold exceeds group count.
+ *         - SSKR_ERROR_INVALID_RESERVED_BITS: if reserved bits are not zero.
+ *         - SSKR_ERROR_SECRET_TOO_SHORT, SSKR_ERROR_SECRET_TOO_LONG,
+ *           SSKR_ERROR_SECRET_LENGTH_NOT_EVEN (via `sskr_check_secret_length`)
+ *           if the extracted value length is invalid.
+ */
 static int16_t sskr_deserialize_shard(const uint8_t *source,
                                       uint16_t source_len,
                                       sskr_shard_t *shard) {
@@ -102,6 +150,25 @@ static int16_t sskr_deserialize_shard(const uint8_t *source,
     return shard->value_len;
 }
 
+/**
+ * @brief Calculates the total number of shards generated for a given SSKR configuration.
+ *
+ * @details This function determines the total shard count based on the group threshold,
+ *          group descriptors, and their respective member counts. It validates the
+ *          group configuration and enforces constraints to ensure logical consistency.
+ *
+ * @param[in] group_threshold   Minimum number of groups required for secret reconstruction.
+ * @param[in] groups            Pointer to an array of `sskr_group_descriptor_t` structures.
+ * @param[in] groups_len        Number of groups in the `groups` array.
+ *
+ * @return Total number of shards on success, or a negative error code:
+ *         - SSKR_ERROR_INVALID_GROUP_LENGTH: if `groups_len` is less than 1.
+ *         - SSKR_ERROR_INVALID_GROUP_THRESHOLD: if `group_threshold` exceeds `groups_len`.
+ *         - SSKR_ERROR_INVALID_GROUP_COUNT: if any group has a count less than 1.
+ *         - SSKR_ERROR_INVALID_MEMBER_THRESHOLD: if any group's threshold exceeds its count.
+ *         - SSKR_ERROR_INVALID_SINGLETON_MEMBER: if any group with threshold 1 has a count greater
+ *           than 1.
+ */
 int16_t sskr_count_shards(uint8_t group_threshold,
                           const sskr_group_descriptor_t *groups,
                           uint8_t groups_len) {
@@ -131,17 +198,39 @@ int16_t sskr_count_shards(uint8_t group_threshold,
     return shard_count;
 }
 
-//////////////////////////////////////////////////
-// generate shards
-//
-static int16_t sskr_generate_shards(uint8_t group_threshold,
-                                    const sskr_group_descriptor_t *groups,
-                                    uint8_t groups_len,
-                                    const uint8_t *master_secret,
-                                    uint16_t master_secret_len,
-                                    sskr_shard_t *shards,
-                                    uint16_t shards_size,
-                                    unsigned char *(*random_generator)(uint8_t *, size_t)) {
+/**
+ * @brief Internal function to generate SSKR shards from a master secret.
+ *
+ * @details This function performs the core logic of generating a set of shards
+ *          from  a given master secret, using a specific group configuration and a
+ *          random number generator. It's an internal function, not intended for direct
+ *          use by external applications.
+ *
+ * @param[in] group_threshold   Minimum number of groups required for secret reconstruction.
+ * @param[in] groups            Pointer to an array of `sskr_group_descriptor_t` structures.
+ * @param[in] groups_len        Number of groups in the `groups` array.
+ * @param[in] master_secret     Pointer to the master secret to be split.
+ * @param[in] master_secret_len Length of the master secret in bytes.
+ * @param[out] shards           Pointer to an array of `sskr_shard_t` structures to store
+ *                              the generated shards.
+ * @param[in] shards_size       Size of the `shards` array in bytes.
+ * @param[in] random_generator  Pointer to a function that generates random bytes.
+ *
+ * @return Number of shards generated on success, or a negative error code:
+ *         - SSKR_ERROR_INVALID_SECRET_LENGTH: if master secret length is invalid.
+ *         - SSKR_ERROR_INSUFFICIENT_SPACE: if `shards_size` is insufficient.
+ *         - SSKR_ERROR_INVALID_GROUP_THRESHOLD: if `group_threshold` exceeds `groups_len`.
+ *         - Other error codes from `sss_split_secret`.
+ */
+static int16_t sskr_generate_shards_internal(uint8_t group_threshold,
+                                             const sskr_group_descriptor_t *groups,
+                                             uint8_t groups_len,
+                                             const uint8_t *master_secret,
+                                             uint16_t master_secret_len,
+                                             sskr_shard_t *shards,
+                                             uint16_t shards_size,
+                                             unsigned char *(*random_generator)(uint8_t *,
+                                                                                size_t)) {
     int16_t err = sskr_check_secret_length(master_secret_len);
     if (err) {
         return err;
@@ -216,18 +305,15 @@ static int16_t sskr_generate_shards(uint8_t group_threshold,
     return shards_count;
 }
 
-//////////////////////////////////////////////////
-// generate mnemonics
-//
-int16_t sskr_generate(uint8_t group_threshold,
-                      const sskr_group_descriptor_t *groups,
-                      uint8_t groups_len,
-                      const uint8_t *master_secret,
-                      uint16_t master_secret_len,
-                      uint8_t *shard_len,
-                      uint8_t *output,
-                      uint16_t buffer_size,
-                      unsigned char *(*random_generator)(uint8_t *, size_t)) {
+int16_t sskr_generate_shards(uint8_t group_threshold,
+                             const sskr_group_descriptor_t *groups,
+                             uint8_t groups_len,
+                             const uint8_t *master_secret,
+                             uint16_t master_secret_len,
+                             uint8_t *shard_len,
+                             uint8_t *output,
+                             uint16_t buffer_size,
+                             unsigned char *(*random_generator)(uint8_t *, size_t)) {
     int16_t err = sskr_check_secret_length(master_secret_len);
     if (err) {
         return err;
@@ -252,14 +338,14 @@ int16_t sskr_generate(uint8_t group_threshold,
     sskr_shard_t shards[SSS_MAX_SHARE_COUNT * SSKR_MAX_GROUP_COUNT];
 
     // generate shards
-    total_shards = sskr_generate_shards(group_threshold,
-                                        groups,
-                                        groups_len,
-                                        master_secret,
-                                        master_secret_len,
-                                        shards,
-                                        (uint16_t) total_shards,
-                                        random_generator);
+    total_shards = sskr_generate_shards_internal(group_threshold,
+                                                 groups,
+                                                 groups_len,
+                                                 master_secret,
+                                                 master_secret_len,
+                                                 shards,
+                                                 (uint16_t) total_shards,
+                                                 random_generator);
 
     if (total_shards < 0) {
         error = total_shards;
@@ -296,19 +382,29 @@ typedef struct sskr_group_struct {
     uint8_t count;
     uint8_t member_index[SSS_MAX_SHARE_COUNT];
     const uint8_t *value[SSS_MAX_SHARE_COUNT];
-} sskr_group;
+} sskr_group_t;
 
 /**
- * This version of combine shards potentially modifies the shard structures
- * in place, so it is for internal use only, however it provides the implementation
- * for both combine_shards and sskr_combine.
+ * @brief Internal function to combine shards for secret reconstruction.
+ *
+ * @details This function implements the core logic for combining SSKR shards to
+ *          recover the original secret. It potentially modifies shard structures in
+ *          place, making it unsuitable for direct public use. It's the underlying
+ *          implementation for and `sskr_combine_shards`.
+ *
+ * @param[in,out] shards         Pointer to an array of `sskr_shard_t` structures to be combined.
+ * @param[in]     shards_count   Number of shards in the `shards` array.
+ * @param[out]    buffer         Pointer to a buffer for working space and storing the reconstructed
+ *                               secret.
+ * @param[in]     buffer_len     Length of the `buffer` array in bytes.
+ *
+ * @return Length of the reconstructed secret on success, or a negative error code.
+ *         Specific error codes are implementation-dependent, consult implementation details.
  */
-static int16_t sskr_combine_shards_internal(
-    sskr_shard_t *shards,  // array of shard structures
-    uint8_t shards_count,  // number of shards in array
-    uint8_t *buffer,       // working space, and place to return secret
-    uint16_t buffer_len    // total amount of working space
-) {
+static int16_t sskr_combine_shards_internal(sskr_shard_t *shards,
+                                            uint8_t shards_count,
+                                            uint8_t *buffer,
+                                            uint16_t buffer_len) {
     int16_t error = 0;
     uint16_t identifier = 0;
     uint8_t group_threshold = 0;
@@ -319,7 +415,7 @@ static int16_t sskr_combine_shards_internal(
     }
 
     uint8_t next_group = 0;
-    sskr_group groups[SSKR_MAX_GROUP_COUNT];
+    sskr_group_t groups[SSKR_MAX_GROUP_COUNT];
     uint8_t secret_len = 0;
 
     for (uint8_t i = 0; i < shards_count; ++i) {
@@ -359,7 +455,7 @@ static int16_t sskr_combine_shards_internal(
         }
 
         if (!group_found) {
-            sskr_group *g = &groups[next_group];
+            sskr_group_t *g = &groups[next_group];
             g->group_index = shard->group_index;
             g->member_threshold = shard->member_threshold;
             g->count = 1;
@@ -387,7 +483,7 @@ static int16_t sskr_combine_shards_internal(
     uint8_t *group_share = group_shares;
 
     for (uint8_t i = 0; !error && i < (uint8_t) next_group; ++i) {
-        sskr_group *g = &groups[i];
+        sskr_group_t *g = &groups[i];
 
         gx[i] = g->group_index;
         if (g->count < g->member_threshold) {
@@ -437,15 +533,11 @@ static int16_t sskr_combine_shards_internal(
     return secret_len;
 }
 
-/////////////////////////////////////////////////
-// sskr_combine
-
-int16_t sskr_combine(const uint8_t **input_shards,  // array of pointers to 10-bit words
-                     uint8_t shard_len,             // number of bytes in each serialized shard
-                     uint8_t shards_count,          // total number of shards
-                     uint8_t *buffer,               // working space, and place to return secret
-                     uint16_t buffer_len            // total amount of working space
-) {
+int16_t sskr_combine_shards(const uint8_t **input_shards,
+                            uint8_t shard_len,
+                            uint8_t shards_count,
+                            uint8_t *buffer,
+                            uint16_t buffer_len) {
     int16_t result = 0;
 
     if (shards_count == 0) {