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

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.

ERRORS

       Any function which can fail for any reason will return NULL on error.

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.

SEE ALSO

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