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)