begriffs open source - libpw/blob - README.md

   1 ### secure password storage library
   2
   3 This library securely stores and validates passwords in a sqlite database. It
   4 can also create and redeem password reset tokens. Its runtime dependencies are
   5 present in the OpenBSD base system. Its build dependencies (meson) are easy to
   6 install.
   7
   8 #### building
   9
  10 ```sh
  11 # install the build system
  12 pkg_add meson ninja
  13
  14 git clone https://dev.begriffs.com/git/libpw
  15 cd libpw
  16
  17 # obtain my meson-wrap project used by the test suite
  18 git submodule update --init
  19
  20 # initialize out-of-source build directory
  21 meson setup build
  22
  23 # build the shared library and tests
  24 meson compile -C build
  25
  26 # run the test suite
  27 meson test -C build
  28 ```
  29
  30 #### usage
  31
  32 TODO: add more details.
  33
  34 ```sh
  35 # create a db with the right schema
  36 sqlite3 passwords.sqlite3 < share/libpw-schema.sql
  37 ```
  38
  39 In C, open the database, and create a libpw password context.
  40
  41 ```c
  42 #include <sqlite3.h>
  43 #include <pw.h>
  44
  45 int main(int argc, char **argv)
  46 {
  47     sqlite3 *db;
  48     pw_context *ctx;
  49
  50     sqlite3_open("passwords.sqlite3", &db);
  51     pw_init_context(db, &ctx);
  52
  53     pw_set(ctx, "root@example.com", "supersecurepass");
  54     // etc
  55 }
  56 ```
  57
  58 For brevity, this snippet has no error checking. See `test/test.c` for more.