LIBGFSHARE(5)

💖 LIBGFSHARE 💖

okay bestie, so you know how sometimes you have a secret and you're like "what if I split it into pieces so no single person can spill the whole tea"? that's literally this. this is the libgfshare(5) page — Shamir Secret Sharing in gf(2**8), and it's giving cryptography main character energy. let's go 🦋

---

✨ NAME ✨

gfshare_ctx_init_enc, etc. — Shamir Secret Sharing 🌸

---

✨ SYNOPSIS ✨

#include <libgfshare.h>

gfshare_rand_func_t gfshare_fill_rand;

gfshare_rand_func_t gfshare_bad_idea_but_fill_rand_using_random;

gfshare_ctx *gfshare_ctx_init_enc( unsigned char *sharenrs,
                                   unsigned int   sharecount,
                                   unsigned char  threshold,
                                   unsigned int   size );

gfshare_ctx *gfshare_ctx_init_dec( unsigned char *sharenrs,
                                   unsigned int   sharecount,
                                   unsigned int   size );

void gfshare_ctx_free( gfshare_ctx *ctx );

void gfshare_ctx_enc_setsecret( gfshare_ctx   *ctx,
                                unsigned char *secret );

void gfshare_ctx_enc_getshare( gfshare_ctx   *ctx,
                               unsigned char  sharenr,
                               unsigned char *share );

void gfshare_ctx_dec_newshares( gfshare_ctx   *ctx,
                                unsigned char *sharenrs );

void gfshare_ctx_dec_giveshare( gfshare_ctx   *ctx,
                                unsigned char  sharenr,
                                unsigned char *share );

void gfshare_ctx_dec_extract( gfshare_ctx   *ctx,
                              unsigned char *secretbuf );

look at all those little babies 🥹 every one of them matters, don't skip a single line.

---

🌈 DESCRIPTION 🌈

first things first, the vibe check: the gfshare_fill_rand variable must contain a pointer to a function that takes an unsigned char * and an unsigned int, and fills the given buffer with the given number of random bytes. and you gotta have that set up before you call any of the functions that create or populate contexts. no random, no vibes. periodt.

now. if you literally cannot do that with a cryptographically secure mechanism, the library is like "fine, here's a backup" and gives you the gfshare_bad_idea_but_fill_rand_using_random value, which you can drop into gfshare_fill_rand. it uses the C library function random() to fill the buffer. the name is literally warning you, okay? it's called bad idea for a reason 😭 you should make sure you call srandom() at least once before using any of the other functions though.

---

gfshare_ctx_init_enc() — returns a context object you can use for encoding shares of a secret. the context encodes against sharecount shares, which are numbered in the array sharenrs. the secret is always size bytes long, and the resultant shares will need at least threshold of the shares present for recombination.

⚠️ it is critical that threshold be at least one lower than sharecount. like, do not play with this. bestie I'm begging you.

---

gfshare_ctx_init_dec() — returns a context object you can use to recombine shares to recover a secret. each share and the resulting secret will be size bytes long. the context can be used to recombine sharecount shares, numbered in the sharenrs array. 💜

---

gfshare_ctx_free() — frees all the memory associated with a gfshare context, including the memory belonging to the context itself. she's cleaning up after herself, we love a tidy icon 🎀

---

gfshare_ctx_enc_setsecret() — hands the context the secret you wish to encode. the secret will be copied into the internal buffer of the library. so like, it's yours but also now it's hers. sharing is caring 💅

---

gfshare_ctx_enc_getshare() — extracts a particular share from the context. two things, bestie:

• the share buffer must be preallocated to the size of the shares
• the sharenr parameter is an index into the sharenrs array used to initialise the context

---

gfshare_ctx_dec_newshares() — tells the decode context that the share numbers available to it have changed. heads up though:

• the number of shares cannot be changed
• but the sharenrs can be zero, to indicate that a particular share is missing currently

so it's less "new shares just dropped" and more "here's the updated status of the ones we already knew about" 🙈

---

gfshare_ctx_dec_giveshare() — provides the decode context with a given share. the share number itself was previously provided in a sharenrs array, and the sharenr parameter is the index into that array of the number of the share being provided in the share memory block. iykyk ✨

---

gfshare_ctx_dec_extract() — combines the provided shares to recalculate the secret. the big finale 🎉

and now the serious part, no cap:

• it is recommended that you mlock() the secretbuf before calling this function, so that the recombined secret will never be written to swap. this may help to prevent a malicious party discovering the content of your secret. 💀
• you should also randomise the content of the buffer once you are finished using the recombined secret.

like, clean up your room and definitely clean up your secret. both. do both. 🧹✨

---

💀 ERRORS 💀

any function which can fail for any reason will return NULL on error. that's it, that's the whole error system. check for NULL, bestie. 🫶

---

👑 AUTHOR 👑

written by Daniel Silverstone. iconic. no notes. 🌟

---

🐛 REPORTING BUGS 🐛

report bugs against the libgfshare product on www.launchpad.net. if something's busted, say something, don't just suffer in silence 🫂

---

⭐ COPYRIGHT ⭐

copyright © 2006,2015 Daniel Silverstone.

this is free software. you may redistribute copies of it under the terms of the MIT licence (the COPYRIGHT file in the source distribution).

there is NO WARRANTY, to the extent permitted by law. (yes, all caps, they mean it 😭)

---

🌸 SEE ALSO 🌸

gfsplit(1), gfcombine(1), gfshare(7)

go read those too, they're part of the friend group 💖

---

and that's the whole page bestie! this was libgfshare version 2.0.0, dated June 2015 — shoutout to that era, she's been serving reliable secret-sharing since then and we're obsessed 🎀✨ bye bye, go split some secrets responsibly 💅🦋