bionic (5) libgfshare.5.gz

Provided by: libgfshare-dev_2.0.0-4_amd64 bug

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