نام (NAME)

libgfshare - قالب پرونده اشتراک‌گذاری راز گالوا فیلد

خلاصه دستور (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)

متغیر gfshare_fill_rand باید حاوی اشاره‌گری به تابعی باشد که یک unsigned char * و یک unsigned int می‌گیرد و بافر داده‌شده را با تعداد بایت‌های تصادفی مشخص پر می‌کند، پیش از آنکه هر یک از توابعی که زمینه‌ها را می‌سازند یا مقداردهی می‌کنند فراخوانی شوند.
اگر نمی‌توانید این کار را با یک سازوکار امن از نظر رمزنگاری انجام دهید، کتابخانه مقدار gfshare_bad_idea_but_fill_rand_using_random را فراهم می‌کند که می‌توانید آن را درون gfshare_fill_rand قرار دهید و از تابع کتابخانه استاندارد C یعنی random() برای پر کردن بافر استفاده خواهد کرد. با این حال، باید اطمینان حاصل کنید که دست‌کم یک بار پیش از استفاده از هر یک از توابع دیگر، srandom() را فراخوانی کرده‌اید.

تابع gfshare_ctx_init_enc() یک شیء زمینه (context) برمی‌گرداند که می‌تواند برای کدگذاری سهم‌های یک راز استفاده شود. زمینه بر اساس sharecount سهم که در آرایه sharenrs شماره‌گذاری شده‌اند کدگذاری می‌کند. راز همیشه طولی به اندازه size بایت دارد و سهم‌های حاصل برای بازترکیب دست‌کم به حضور threshold سهم نیاز خواهند داشت. بسیار حیاتی است که threshold دست‌کم یک واحد کمتر از sharecount باشد.

تابع gfshare_ctx_init_dec() یک شیء زمینه برمی‌گرداند که می‌تواند برای بازترکیب سهم‌ها جهت بازیابی یک راز استفاده شود. هر سهم و راز حاصل طولی برابر با size بایت خواهند داشت. از این زمینه می‌توان برای بازترکیب sharecount سهم که در آرایه sharenrs شماره‌گذاری شده‌اند استفاده کرد.

تابع gfshare_ctx_free() تمام حافظه مرتبط با یک زمینه gfshare، از جمله حافظه متعلق به خود شیء زمینه را آزاد می‌کند.

تابع gfshare_ctx_enc_setsecret() رازی را که می‌خواهید کدگذاری کنید در اختیار زمینه قرار می‌دهد. secret در بافر داخلی کتابخانه کپی خواهد شد.

تابع gfshare_ctx_enc_getshare() یک سهم مشخص را از زمینه استخراج می‌کند. بافر share باید از پیش به اندازه سهم‌ها تخصیص یافته باشد و پارامتر sharenr یک اندیس درون آرایه sharenrs است که برای مقداردهی اولیه زمینه استفاده شده است.

تابع gfshare_ctx_dec_newshares() زمینه رمزگشایی را از تغییر در شماره سهم‌های در دسترس زمینه آگاه می‌کند. تعداد سهم‌ها قابل تغییر نیست، اما sharenrs می‌تواند صفر باشد تا نشان دهد یک سهم خاص در حال حاضر ناموجود است.

تابع gfshare_ctx_dec_giveshare() یک سهم داده‌شده را به زمینه رمزگشایی تحویل می‌دهد. شماره سهم پیش‌تر درون آرایه sharenrs ارائه شده بود و پارامتر sharenr اندیسی به آن آرایه برای شماره سهمی است که در بلوک حافظه share داده شده است.

تابع gfshare_ctx_dec_extract() سهم‌های ارائه‌شده را برای محاسبه مجدد راز ترکیب می‌کند. توصیه می‌شود پیش از فراخوانی این تابع، secretbuf را با mlock() قفل کنید تا راز بازترکیب‌شده هرگز در swap نوشته نشود. این کار به جلوگیری از کشف محتوای راز شما توسط افراد بدخواه کمک می‌کند. همچنین باید پس از اتمام استفاده از راز بازترکیب‌شده، محتوای بافر را تصادفی‌سازی کنید.

خطاها (ERRORS)

هر تابعی که به هر دلیلی با شکست مواجه شود، در صورت بروز خطا NULL برمی‌گرداند.

نویسنده (AUTHOR)

نوشته‌شده توسط Daniel Silverstone.

گزارش باگ‌ها (REPORTING BUGS)

باگ‌ها را برای محصول libgfshare در www.launchpad.net گزارش دهید.

حق نشر (COPYRIGHT)

حق نشر © 2006,2015 Daniel Silverstone.
این یک نرم‌افزار آزاد است. شما می‌توانید نسخه‌هایی از آن را طبق شرایط پروانه MIT (پرونده COPYRIGHT در توزیع منبع) بازتوزیع کنید. هیچ ضمانتی وجود ندارد، تا حدی که قانون اجازه می‌دهد.

همچنین ببینید (SEE ALSO)

gfsplit(1), gfcombine(1), gfshare(7)