ext/userauth/sqlite3userauth.h

   1 /*
   2 ** 2014-09-08
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 **
  13 ** This file contains the application interface definitions for the
  14 ** user-authentication extension feature.
  15 **
  16 ** To compile with the user-authentication feature, append this file to
  17 ** end of an SQLite amalgamation header file ("sqlite3.h"), then add
  18 ** the SQLITE_USER_AUTHENTICATION compile-time option.  See the
  19 ** user-auth.txt file in the same source directory as this file for
  20 ** additional information.
  21 */
  22 #ifdef SQLITE_USER_AUTHENTICATION
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /*
  29 ** If a database contains the SQLITE_USER table, then the
  30 ** sqlite3_user_authenticate() interface must be invoked with an
  31 ** appropriate username and password prior to enable read and write
  32 ** access to the database.
  33 **
  34 ** Return SQLITE_OK on success or SQLITE_ERROR if the username/password
  35 ** combination is incorrect or unknown.
  36 **
  37 ** If the SQLITE_USER table is not present in the database file, then
  38 ** this interface is a harmless no-op returnning SQLITE_OK.
  39 */
  40 int sqlite3_user_authenticate(
  41   sqlite3 *db,           /* The database connection */
  42   const char *zUsername, /* Username */
  43   const char *aPW,       /* Password or credentials */
  44   int nPW                /* Number of bytes in aPW[] */
  45 );
  46
  47 /*
  48 ** The sqlite3_user_add() interface can be used (by an admin user only)
  49 ** to create a new user.  When called on a no-authentication-required
  50 ** database, this routine converts the database into an authentication-
  51 ** required database, automatically makes the added user an
  52 ** administrator, and logs in the current connection as that user.
  53 ** The sqlite3_user_add() interface only works for the "main" database, not
  54 ** for any ATTACH-ed databases.  Any call to sqlite3_user_add() by a
  55 ** non-admin user results in an error.
  56 */
  57 int sqlite3_user_add(
  58   sqlite3 *db,           /* Database connection */
  59   const char *zUsername, /* Username to be added */
  60   const char *aPW,       /* Password or credentials */
  61   int nPW,               /* Number of bytes in aPW[] */
  62   int isAdmin            /* True to give new user admin privilege */
  63 );
  64
  65 /*
  66 ** The sqlite3_user_change() interface can be used to change a users
  67 ** login credentials or admin privilege.  Any user can change their own
  68 ** login credentials.  Only an admin user can change another users login
  69 ** credentials or admin privilege setting.  No user may change their own
  70 ** admin privilege setting.
  71 */
  72 int sqlite3_user_change(
  73   sqlite3 *db,           /* Database connection */
  74   const char *zUsername, /* Username to change */
  75   const char *aPW,       /* New password or credentials */
  76   int nPW,               /* Number of bytes in aPW[] */
  77   int isAdmin            /* Modified admin privilege for the user */
  78 );
  79
  80 /*
  81 ** The sqlite3_user_delete() interface can be used (by an admin user only)
  82 ** to delete a user.  The currently logged-in user cannot be deleted,
  83 ** which guarantees that there is always an admin user and hence that
  84 ** the database cannot be converted into a no-authentication-required
  85 ** database.
  86 */
  87 int sqlite3_user_delete(
  88   sqlite3 *db,           /* Database connection */
  89   const char *zUsername  /* Username to remove */
  90 );
  91
  92 #ifdef __cplusplus
  93 }  /* end of the 'extern "C"' block */
  94 #endif
  95
  96 #endif /* SQLITE_USER_AUTHENTICATION */