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)

2.0.0                                               June 2015                                      LIBGFSHARE(5)