Snapshot of upstream SQLite 3.46.1
[sqlcipher.git] / ext / userauth / user-auth.txt
blob9d6ba2333647960d75a3c64a4ea45fe87b056d4e
1 *********************************** NOTICE ************************************
2 * This extension is deprecated. The SQLite developers do not maintain this    *
3 * extension. At some point in the future, it might disappear from the source  *
4 * tree.                                                                       *
5 *                                                                             *
6 * If you are using this extension and think it should be supported moving     *
7 * forward, visit the SQLite Forum (https://sqlite.org/forum) and argue your   *
8 * case there.                                                                 *
9 *                                                                             *
10 * This deprecation notice was added on 2024-01-22.                            *
11 *******************************************************************************
13 Activate the user authentication logic by including the
14 ext/userauth/userauth.c source code file in the build and
15 adding the -DSQLITE_USER_AUTHENTICATION compile-time option.
16 The ext/userauth/sqlite3userauth.h header file is available to
17 applications to define the interface.
19 When using the SQLite amalgamation, it is sufficient to append
20 the ext/userauth/userauth.c source file onto the end of the
21 amalgamation.
23 The following new APIs are available when user authentication is
24 activated:
26    int sqlite3_user_authenticate(
27      sqlite3 *db,           /* The database connection */
28      const char *zUsername, /* Username */
29      const char *aPW,       /* Password or credentials */
30      int nPW                /* Number of bytes in aPW[] */
31    );
32    
33    int sqlite3_user_add(
34      sqlite3 *db,           /* Database connection */
35      const char *zUsername, /* Username to be added */
36      const char *aPW,       /* Password or credentials */
37      int nPW,               /* Number of bytes in aPW[] */
38      int isAdmin            /* True to give new user admin privilege */
39    );
40    
41    int sqlite3_user_change(
42      sqlite3 *db,           /* Database connection */
43      const char *zUsername, /* Username to change */
44      const void *aPW,       /* Modified password or credentials */
45      int nPW,               /* Number of bytes in aPW[] */
46      int isAdmin            /* Modified admin privilege for the user */
47    );
48    
49    int sqlite3_user_delete(
50      sqlite3 *db,           /* Database connection */
51      const char *zUsername  /* Username to remove */
52    );
54 With this extension, a database can be marked as requiring authentication.
55 By default a database does not require authentication.
57 The sqlite3_open(), sqlite3_open16(), and sqlite3_open_v2() interfaces
58 work as before: they open a new database connection.  However, if the
59 database being opened requires authentication, then attempts to read
60 or write from the database will fail with an SQLITE_AUTH error until 
61 after sqlite3_user_authenticate() has been called successfully.  The 
62 sqlite3_user_authenticate() call will return SQLITE_OK if the 
63 authentication credentials are accepted and SQLITE_ERROR if not.
65 Calling sqlite3_user_authenticate() on a no-authentication-required
66 database connection is a harmless no-op.  
68 If the database is encrypted, then sqlite3_key_v2() must be called first,
69 with the correct decryption key, prior to invoking sqlite3_user_authenticate().
71 To recapitulate: When opening an existing unencrypted authentication-
72 required database, the call sequence is:
74     sqlite3_open_v2()
75     sqlite3_user_authenticate();
76     /* Database is now usable */
78 To open an existing, encrypted, authentication-required database, the
79 call sequence is:
81     sqlite3_open_v2();
82     sqlite3_key_v2();
83     sqlite3_user_authenticate();
84     /* Database is now usable */
86 When opening a no-authentication-required database, the database
87 connection is treated as if it was authenticated as an admin user.
89 When ATTACH-ing new database files to a connection, each newly attached
90 database that is an authentication-required database is checked using
91 the same username and password as supplied to the main database.  If that
92 check fails, then the ATTACH command fails with an SQLITE_AUTH error.
94 The sqlite3_user_add() interface can be used (by an admin user only)
95 to create a new user.  When called on a no-authentication-required
96 database and when A is true, the sqlite3_user_add(D,U,P,N,A) routine
97 converts the database into an authentication-required database and
98 logs in the database connection D as user U with password P,N.
99 To convert a no-authentication-required database into an authentication-
100 required database, the isAdmin parameter must be true.  If
101 sqlite3_user_add(D,U,P,N,A) is called on a no-authentication-required
102 database and A is false, then the call fails with an SQLITE_AUTH error.
104 Any call to sqlite3_user_add() by a non-admin user results in an error.
106 Hence, to create a new, unencrypted, authentication-required database,
107 the call sequence is:
109     sqlite3_open_v2();
110     sqlite3_user_add();
112 And to create a new, encrypted, authentication-required database, the call
113 sequence is:
115     sqlite3_open_v2();
116     sqlite3_key_v2();
117     sqlite3_user_add();
119 The sqlite3_user_delete() interface can be used (by an admin user only)
120 to delete a user.  The currently logged-in user cannot be deleted,
121 which guarantees that there is always an admin user and hence that
122 the database cannot be converted into a no-authentication-required
123 database.
125 The sqlite3_user_change() interface can be used to change a users
126 login credentials or admin privilege.  Any user can change their own
127 password.  Only an admin user can change another users login
128 credentials or admin privilege setting.  No user may change their own 
129 admin privilege setting.
131 The sqlite3_set_authorizer() callback is modified to take a 7th parameter
132 which is the username of the currently logged in user, or NULL for a
133 no-authentication-required database.
135 -----------------------------------------------------------------------------
136 Implementation notes:
138 An authentication-required database is identified by the presence of a
139 new table:
141     CREATE TABLE sqlite_user(
142       uname TEXT PRIMARY KEY,
143       isAdmin BOOLEAN,
144       pw BLOB
145     ) WITHOUT ROWID;
147 The sqlite_user table is inaccessible (unreadable and unwriteable) to
148 non-admin users and is read-only for admin users.  However, if the same
149 database file is opened by a version of SQLite that omits
150 the -DSQLITE_USER_AUTHENTICATION compile-time option, then the sqlite_user
151 table will be readable by anybody and writeable by anybody if
152 the "PRAGMA writable_schema=ON" statement is run first.
154 The sqlite_user.pw field is encoded by a built-in SQL function
155 "sqlite_crypt(X,Y)".  The two arguments are both BLOBs.  The first argument
156 is the plaintext password supplied to the sqlite3_user_authenticate()
157 interface.  The second argument is the sqlite_user.pw value and is supplied
158 so that the function can extract the "salt" used by the password encoder.
159 The result of sqlite_crypt(X,Y) is another blob which is the value that
160 ends up being stored in sqlite_user.pw.  To verify credentials X supplied
161 by the sqlite3_user_authenticate() routine, SQLite runs:
163     sqlite_user.pw == sqlite_crypt(X, sqlite_user.pw)
165 To compute an appropriate sqlite_user.pw value from a new or modified
166 password X, sqlite_crypt(X,NULL) is run.  A new random salt is selected
167 when the second argument is NULL.
169 The built-in version of of sqlite_crypt() uses a simple Ceasar-cypher
170 which prevents passwords from being revealed by searching the raw database
171 for ASCII text, but is otherwise trivally broken.  For better password
172 security, the database should be encrypted using the SQLite Encryption
173 Extension or similar technology.  Or, the application can use the
174 sqlite3_create_function() interface to provide an alternative
175 implementation of sqlite_crypt() that computes a stronger password hash,
176 perhaps using a cryptographic hash function like SHA1.