1.Dd December 19, 2018 2.Dt SQLITE3_SET_AUTHORIZER 3 3.Os 4.Sh NAME 5.Nm sqlite3_set_authorizer 6.Nd Compile-Time Authorization Callbacks 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3_set_authorizer 10.Fa "sqlite3*" 11.Fa "int (*xAuth)(void*,int,const char*,const char*,const char*,const char*)" 12.Fa "void *pUserData " 13.Fc 14.Sh DESCRIPTION 15This routine registers an authorizer callback with a particular database connection, 16supplied in the first argument. 17The authorizer callback is invoked as SQL statements are being compiled 18by sqlite3_prepare() or its variants sqlite3_prepare_v2(), 19sqlite3_prepare_v3(), sqlite3_prepare16(), 20sqlite3_prepare16_v2(), and sqlite3_prepare16_v3(). 21At various points during the compilation process, as logic is being 22created to perform various actions, the authorizer callback is invoked 23to see if those actions are allowed. 24The authorizer callback should return SQLITE_OK to allow the 25action, SQLITE_IGNORE to disallow the specific action 26but allow the SQL statement to continue to be compiled, or SQLITE_DENY 27to cause the entire SQL statement to be rejected with an error. 28If the authorizer callback returns any value other than SQLITE_IGNORE, 29SQLITE_OK, or SQLITE_DENY then the sqlite3_prepare_v2() 30or equivalent call that triggered the authorizer will fail with an 31error message. 32.Pp 33When the callback returns SQLITE_OK, that means the operation 34requested is ok. 35When the callback returns SQLITE_DENY, the sqlite3_prepare_v2() 36or equivalent call that triggered the authorizer will fail with an 37error message explaining that access is denied. 38.Pp 39The first parameter to the authorizer callback is a copy of the third 40parameter to the sqlite3_set_authorizer() interface. 41The second parameter to the callback is an integer action code 42that specifies the particular action to be authorized. 43The third through sixth parameters to the callback are either NULL 44pointers or zero-terminated strings that contain additional details 45about the action to be authorized. 46Applications must always be prepared to encounter a NULL pointer in 47any of the third through the sixth parameters of the authorization 48callback. 49.Pp 50If the action code is SQLITE_READ and the callback returns 51SQLITE_IGNORE then the prepared statement 52statement is constructed to substitute a NULL value in place of the 53table column that would have been read if SQLITE_OK had been 54returned. 55The SQLITE_IGNORE return can be used to deny an untrusted 56user access to individual columns of a table. 57When a table is referenced by a SELECT but no column values are 58extracted from that table (for example in a query like "SELECT count(*) 59FROM tab") then the SQLITE_READ authorizer callback is invoked 60once for that table with a column name that is an empty string. 61If the action code is SQLITE_DELETE and the callback returns 62SQLITE_IGNORE then the DELETE operation proceeds 63but the truncate optimization is disabled and 64all rows are deleted individually. 65.Pp 66An authorizer is used when preparing SQL statements from 67an untrusted source, to ensure that the SQL statements do not try to 68access data they are not allowed to see, or that they do not try to 69execute malicious statements that damage the database. 70For example, an application may allow a user to enter arbitrary SQL 71queries for evaluation by a database. 72But the application does not want the user to be able to make arbitrary 73changes to the database. 74An authorizer could then be put in place while the user-entered SQL 75is being prepared that disallows everything except SELECT 76statements. 77.Pp 78Applications that need to process SQL from untrusted sources might 79also consider lowering resource limits using sqlite3_limit() 80and limiting database size using the max_page_count PRAGMA 81in addition to using an authorizer. 82.Pp 83Only a single authorizer can be in place on a database connection at 84a time. 85Each call to sqlite3_set_authorizer overrides the previous call. 86Disable the authorizer by installing a NULL callback. 87The authorizer is disabled by default. 88.Pp 89The authorizer callback must not do anything that will modify the database 90connection that invoked the authorizer callback. 91Note that sqlite3_prepare_v2() and sqlite3_step() 92both modify their database connections for the meaning of "modify" 93in this paragraph. 94.Pp 95When sqlite3_prepare_v2() is used to prepare a 96statement, the statement might be re-prepared during sqlite3_step() 97due to a schema change. 98Hence, the application should ensure that the correct authorizer callback 99remains in place during the sqlite3_step(). 100.Pp 101Note that the authorizer callback is invoked only during sqlite3_prepare() 102or its variants. 103Authorization is not performed during statement evaluation in sqlite3_step(), 104unless as stated in the previous paragraph, sqlite3_step() invokes 105sqlite3_prepare_v2() to reprepare a statement after a schema change. 106.Sh SEE ALSO 107.Xr sqlite3 3 , 108.Xr sqlite3_stmt 3 , 109.Xr sqlite3_limit 3 , 110.Xr sqlite3_prepare 3 , 111.Xr sqlite3_step 3 , 112.Xr SQLITE_CREATE_INDEX 3 , 113.Xr SQLITE_DENY 3 , 114.Xr SQLITE_OK 3 , 115.Xr SQLITE_CREATE_INDEX 3 116