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 );

DESCRIPTION

The gfshare_fill_rand variable must contain a pointer to a function which takes an unsigned char * and an unsigned int and fills the given buffer with the given number of random bytes before calling any of the functions which create or populate contexts.
If you cannot do this with a cryptographically secure mechanism then the library provides the gfshare_bad_idea_but_fill_rand_using_random value which you can put into gfshare_fill_rand and which will use the C library function random() to fill the buffer. You should ensure you call srandom() at least once before using any of the other functions though.

The gfshare_ctx_init_enc() function returns a context object which can be used 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.

The gfshare_ctx_init_dec() function returns a context object which can be used 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 which are numbered in the sharenrs array.

The gfshare_ctx_free() function frees all the memory associated with a gfshare context including the memory belonging to the context itself.

The gfshare_ctx_enc_setsecret() function provides the secret you wish to encode to the context. The secret will be copied into the internal buffer of the library.

The gfshare_ctx_enc_getshare() function extracts a particular share from the context. The share buffer must be preallocated to the size of the shares and the sharenr parameter is an index into the sharenrs array used to initialise the context

The gfshare_ctx_dec_newshares() function informs the decode context of a change in the share numbers available to the context. The number of shares cannot be changed but the sharenrs can be zero to indicate that a particular share is missing currently.

The gfshare_ctx_dec_giveshare() function 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.

The gfshare_ctx_dec_extract() function combines the provided shares to recalculate the secret. 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.

AUTHOR

Written by Daniel Silverstone.

REPORTING BUGS

Report bugs against the libgfshare product on www.launchpad.net.

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.