New requirements marks and documentation for the authorizer.

FossilOrigin-Name: 3980ea0911b3ad3f86d7a7bdc6503f233315c274f473e18831e13eda2c238eeb

manifest

@@ -1,5 +1,5 @@
-C Improvements\sto\sthe\ssqlite3_set_authorizer()\sdocumentation.
+C New\srequirements\smarks\sand\sdocumentation\sfor\sthe\sauthorizer.
-D 2017-05-11T12:27:21.511
+D 2017-05-11T13:43:57.931
 F Makefile.in 1cc758ce3374a32425e4d130c2fe7b026b20de5b8843243de75f087c0a2661fb
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc 6a8c838220f7c00820e1fc0ac1bccaaa8e5676067e1dbfa1bafa7a4ffecf8ae6
@@ -341,7 +341,7 @@ F sqlite3.pc.in 48fed132e7cb71ab676105d2a4dc77127d8c1f3a
 F src/alter.c 3b23977620ce9662ac54443f65b87ba996e36121
 F src/analyze.c 0d0ccf7520a201d8747ea2f02c92c26e26f801bc161f714f27b9f7630dde0421
 F src/attach.c 8c476f8bd5d2afe11d925f890d30e527e5b0ce43
-F src/auth.c 930b376a9c56998557367e6f7f8aaeac82a2a792
+F src/auth.c 79f96c6f33bf0e5da8d1c282cee5ebb1852bb8a6ccca3e485d7c459b035d9c3c
 F src/backup.c faf17e60b43233c214aae6a8179d24503a61e83b
 F src/bitvec.c 17ea48eff8ba979f1f5b04cc484c7bb2be632f33
 F src/btmutex.c 0e9ce2d56159b89b9bc8e197e023ee11e39ff8ca
@@ -354,7 +354,7 @@ F src/complete.c a3634ab1e687055cd002e11b8f43eb75c17da23e
 F src/ctime.c 47d91a25ad8f199a71a5b1b7b169d6dd0d6e98c5719eca801568798743d1161c
 F src/date.c cc42a41c7422389860d40419a5e3bce5eaf6e7835c3ba2677751dc653550a5c7
 F src/dbstat.c 19ee7a4e89979d4df8e44cfac7a8f905ec89b77d
-F src/delete.c 0d9d5549d42e79ce4d82ff1db1e6c81e36d2f67c
+F src/delete.c 665e705641e5815c3f32d05820d1a5aa630274e568af73f377fdbc614fcf40b4
 F src/expr.c c980b2c9291a12a0f1de1e1e1aaa72c4579ded716e1e3a3ac1c3d898ba0df0a1
 F src/fault.c 460f3e55994363812d9d60844b2a6de88826e007
 F src/fkey.c db65492ae549c3b548c9ef1f279ce1684f1c473b116e1c56a90878cd5dcf968d
@@ -411,7 +411,7 @@ F src/sqliteInt.h aea3aa1b81e0d07d5b1c39b8c5a54a1dc5e4f10136cb63da392aef9eb2a510
 F src/sqliteLimit.h 1513bfb7b20378aa0041e7022d04acb73525de35b80b252f1b83fedb4de6a76b
 F src/status.c a9e66593dfb28a9e746cba7153f84d49c1ddc4b1
 F src/table.c b46ad567748f24a326d9de40e5b9659f96ffff34
-F src/tclsqlite.c 6c2151b6d8d98e183a04466d40df8889c0574d79
+F src/tclsqlite.c c8cf60d0c5411d5e70e7c136470d29dbe760d250f55198b71682c67086524e4a
 F src/test1.c c99f0442918a7a5d5b68a95d6024c211989e6c782c15ced5a558994baaf76a5e
 F src/test2.c 3efb99ab7f1fc8d154933e02ae1378bac9637da5
 F src/test3.c d03f5b5da9a2410b7a91c64b0d3306ed28ab6fee
@@ -526,9 +526,9 @@ F test/attach2.test 0ec5defa340363de6cd50fd595046465e9aaba2d
 F test/attach3.test c59d92791070c59272e00183b7353eeb94915976
 F test/attach4.test 53bf502f17647c6d6c5add46dda6bac8b6f4665c
 F test/attachmalloc.test 3a4bfca9545bfe906a8d2e622de10fbac5b711b0
-F test/auth.test 5caf9c6d8ed7b2a5a760b418f5f479bf20f07c9d8be29efa977130816c587089
+F test/auth.test 32ee0e98593c9ea73870d9b0c8e50c2f43371d9fede388c09e9477c6bf5f8aab
 F test/auth2.test 9eb7fce9f34bf1f50d3f366fb3e606be5a2000a1
-F test/auth3.test 0d48b901cf111c14b4b1b5205c7d28f1a278190f
+F test/auth3.test db21405b95257c24d29273b6b31d0efc59e1d337e3d5804ba2d1fd4897b1ae49
 F test/autoanalyze1.test b9cc3f32a990fa56669b668d237c6d53e983554ae80c0604992e18869a0b2dec
 F test/autoinc.test 6ae8fb69c9f656962464ae4e6667045d0dfc3b46
 F test/autoindex1.test 14b63a9f1e405fe6d5bfc8c8d00249c2ebaf13ea
@@ -1579,7 +1579,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 4139953ab528f20fa346409810edcb22adb6c1edc9d22f40b1b077ef842a2441
+P 47629b1911e52445aad8ea969137bddf0019c55b4a4f0de8e77decb6a434c8a2
-R 439d581bae700f41f9bd0f879ef19838
+R 0c6451e367b2cefc9e69fa0621b4d931
 U drh
-Z 3b3b1bb649cf5fdc934ca94a70bf1f6d
+Z 18c2f8082a296f2f15ab41c2498f7cb3

manifest.uuid

@@ -1 +1 @@
-47629b1911e52445aad8ea969137bddf0019c55b4a4f0de8e77decb6a434c8a2
+3980ea0911b3ad3f86d7a7bdc6503f233315c274f473e18831e13eda2c238eeb

src/auth.c

@@ -216,6 +216,18 @@ int sqlite3AuthCheck(
   if( db->xAuth==0 ){
     return SQLITE_OK;
   }
+
+  /* EVIDENCE-OF: R-43249-19882 The third through sixth parameters to the
+  ** callback are either NULL pointers or zero-terminated strings that
+  ** contain additional details about the action to be authorized.
+  **
+  ** The following testcase() macros show that any of the 3rd through 6th
+  ** parameters can be either NULL or a string. */
+  testcase( zArg1==0 );
+  testcase( zArg2==0 );
+  testcase( zArg3==0 );
+  testcase( pParse->zAuthContext==0 );
+
   rc = db->xAuth(db->pAuthArg, code, zArg1, zArg2, zArg3, pParse->zAuthContext
 #ifdef SQLITE_USER_AUTHENTICATION
                  ,db->auth.zAuthUser

src/delete.c

@@ -350,7 +350,14 @@ void sqlite3DeleteFrom(
   /* Special case: A DELETE without a WHERE clause deletes everything.
   ** It is easier just to erase the whole table. Prior to version 3.6.5,
   ** this optimization caused the row change count (the value returned by 
-  ** API function sqlite3_count_changes) to be set incorrectly.  */
+  ** API function sqlite3_count_changes) to be set incorrectly.
+  **
+  ** The "rcauth==SQLITE_OK" terms is the
+  ** IMPLEMENATION-OF: R-17228-37124 If the action code is SQLITE_DELETE and
+  ** the callback returns SQLITE_IGNORE then the DELETE operation proceeds but
+  ** the truncate optimization is disabled and all rows are deleted
+  ** individually.
+  */
   if( rcauth==SQLITE_OK
    && pWhere==0
    && !bComplex

src/tclsqlite.c

@@ -1033,9 +1033,16 @@ static int auth_callback(
   Tcl_DString str;
   int rc;
   const char *zReply;
+  /* EVIDENCE-OF: R-38590-62769 The first parameter to the authorizer
+  ** callback is a copy of the third parameter to the
+  ** sqlite3_set_authorizer() interface.
+  */
   SqliteDb *pDb = (SqliteDb*)pArg;
   if( pDb->disableAuth ) return SQLITE_OK;
 
+  /* EVIDENCE-OF: R-56518-44310 The second parameter to the callback is an
+  ** integer action code that specifies the particular action to be
+  ** authorized. */
   switch( code ){
     case SQLITE_COPY              : zCode="SQLITE_COPY"; break;
     case SQLITE_CREATE_INDEX      : zCode="SQLITE_CREATE_INDEX"; break;

test/auth.test

@@ -36,12 +36,20 @@ proc_real proc {name arguments script} {
 do_test auth-1.1.1 {
   db close
   set ::DB [sqlite3 db test.db]
+  proc authx {code arg1 arg2 arg3 arg4 args} {return SQLITE_DENY}
   proc auth {code arg1 arg2 arg3 arg4 args} {
     if {$code=="SQLITE_INSERT" && $arg1=="sqlite_master"} {
       return SQLITE_DENY
     }
     return SQLITE_OK
   }
+  db authorizer ::authx
+  # EVIDENCE-OF: R-03993-24285 Only a single authorizer can be in place on
+  # a database connection at a time. Each call to sqlite3_set_authorizer
+  # overrides the previous call.
+  #
+  # The authx authorizer above is overridden by the auth authorizer below
+  # authx is never invoked.
   db authorizer ::auth
   catchsql {CREATE TABLE t1(a,b,c)}
 } {1 {not authorized}}
@@ -60,6 +68,9 @@ do_test auth-1.1.4 {
 do_test auth-1.2 {
   execsql {SELECT name FROM sqlite_master}
 } {}
+# EVIDENCE-OF: R-04452-49349 When the callback returns SQLITE_DENY, the
+# sqlite3_prepare_v2() or equivalent call that triggered the authorizer
+# will fail with an error message explaining that access is denied.
 do_test auth-1.3.1 {
   proc auth {code arg1 arg2 arg3 arg4 args} {
     if {$code=="SQLITE_CREATE_TABLE"} {
@@ -312,6 +323,10 @@ ifcapable attach {
   } {1 {access to two.t2.b is prohibited}}
   execsql {DETACH DATABASE two}
 }
+# EVIDENCE-OF: R-38392-49970 If the action code is SQLITE_READ and the
+# callback returns SQLITE_IGNORE then the prepared statement statement
+# is constructed to substitute a NULL value in place of the table column
+# that would have been read if SQLITE_OK had been returned.
 do_test auth-1.36 {
   proc auth {code arg1 arg2 arg3 arg4 args} {
     if {$code=="SQLITE_READ" && $arg1=="t2" && $arg2=="b"} {
@@ -1606,6 +1621,8 @@ do_test auth-1.248 {
   set ::authargs
 } {COMMIT {} {} {}}
 do_test auth-1.249 {
+  # EVIDENCE-OF: R-52112-44167 Disable the authorizer by installing a NULL
+  # callback.
   db authorizer {}
   catchsql {ROLLBACK}
 } {0 {}}
@@ -2482,6 +2499,12 @@ do_test auth-7.4 {
 # that causes a single SQLITE_READ authorization with a NULL column
 # name.
 #
+# EVIDENCE-OF: R-31520-16302 When a table is referenced by a SELECT but
+# no column values are extracted from that table (for example in a query
+# like "SELECT count(*) FROM tab") then the SQLITE_READ authorizer
+# callback is invoked once for that table with a column name that is an
+# empty string.
+#
 set ::authargs [list]
 do_test auth-8.1 {
   execsql {SELECT count(*) FROM t7}

test/auth3.test

@@ -53,6 +53,10 @@ do_test auth3.1.2 {
   set ::authcode SQLITE_DENY
   catchsql { DELETE FROM t1 }
 } {1 {not authorized}}
+# EVIDENCE-OF: R-64962-58611 If the authorizer callback returns any
+# value other than SQLITE_IGNORE, SQLITE_OK, or SQLITE_DENY then the
+# sqlite3_prepare_v2() or equivalent call that triggered the authorizer
+# will fail with an error message.
 do_test auth3.1.3 {
   set ::authcode SQLITE_INVALID
   catchsql { DELETE FROM t1 }