---
name: "libgfshare"
section: "5"
platform: "linux"
package: "libgfshare"
version: "2.0.0-5"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libgfshare"
---

# libgfshare(5)

Shamir Secret Sharing

## 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)](/gfsplit/1.md), [gfcombine(1)](/gfcombine/1.md), [gfshare(7)](/gfshare/7.md)