NAME

       gfshare_ctx_init_enc, etc. - Shamir Secret Sharing

SYNOPSIS

       #include <libgfshare.h>

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

1.0.5                                             February 2006                                    LIBGFSHARE(5)