Debian Codegraph @

www/c3ref/set_authorizer.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Compile-Time Authorization Callbacks</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: {authorizer callback} sqlite3_set_authorizer -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Compile-Time Authorization Callbacks</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_set_authorizer(
125 sqlite3*,
126 int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
127 void *pUserData
128 );
129 </pre></blockquote>
130 <p>
131 This routine registers an authorizer callback with a particular
132 <a href="../c3ref/sqlite3.html">database connection</a>, supplied in the first argument.
133 The authorizer callback is invoked as SQL statements are being compiled
134 by <a href="../c3ref/prepare.html">sqlite3_prepare()</a> or its variants <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a>,
135 <a href="../c3ref/prepare.html">sqlite3_prepare_v3()</a>, <a href="../c3ref/prepare.html">sqlite3_prepare16()</a>, <a href="../c3ref/prepare.html">sqlite3_prepare16_v2()</a>,
136 and <a href="../c3ref/prepare.html">sqlite3_prepare16_v3()</a>. At various
137 points during the compilation process, as logic is being created
138 to perform various actions, the authorizer callback is invoked to
139 see if those actions are allowed. The authorizer callback should
140 return <a href="../rescode.html#ok">SQLITE_OK</a> to allow the action, <a href="../c3ref/c_deny.html">SQLITE_IGNORE</a> to disallow the
141 specific action but allow the SQL statement to continue to be
142 compiled, or <a href="../c3ref/c_deny.html">SQLITE_DENY</a> to cause the entire SQL statement to be
143 rejected with an error. If the authorizer callback returns
144 any value other than <a href="../c3ref/c_deny.html">SQLITE_IGNORE</a>, <a href="../rescode.html#ok">SQLITE_OK</a>, or <a href="../c3ref/c_deny.html">SQLITE_DENY</a>
145 then the <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or equivalent call that triggered
146 the authorizer will fail with an error message.</p>
147
148 <p>When the callback returns <a href="../rescode.html#ok">SQLITE_OK</a>, that means the operation
149 requested is ok. When the callback returns <a href="../c3ref/c_deny.html">SQLITE_DENY</a>, the
150 <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or equivalent call that triggered the
151 authorizer will fail with an error message explaining that
152 access is denied.</p>
153
154 <p>The first parameter to the authorizer callback is a copy of the third
155 parameter to the sqlite3_set_authorizer() interface. The second parameter
156 to the callback is an integer <a href="../c3ref/c_alter_table.html">action code</a> that specifies
157 the particular action to be authorized. The third through sixth parameters
158 to the callback are either NULL pointers or zero-terminated strings
159 that contain additional details about the action to be authorized.
160 Applications must always be prepared to encounter a NULL pointer in any
161 of the third through the sixth parameters of the authorization callback.</p>
162
163 <p>If the action code is <a href="../c3ref/c_alter_table.html">SQLITE_READ</a>
164 and the callback returns <a href="../c3ref/c_deny.html">SQLITE_IGNORE</a> then the
165 <a href="../c3ref/stmt.html">prepared statement</a> statement is constructed to substitute
166 a NULL value in place of the table column that would have
167 been read if <a href="../rescode.html#ok">SQLITE_OK</a> had been returned. The <a href="../c3ref/c_deny.html">SQLITE_IGNORE</a>
168 return can be used to deny an untrusted user access to individual
169 columns of a table.
170 When a table is referenced by a <a href="../lang_select.html">SELECT</a> but no column values are
171 extracted from that table (for example in a query like
172 "SELECT count(*) FROM tab") then the <a href="../c3ref/c_alter_table.html">SQLITE_READ</a> authorizer callback
173 is invoked once for that table with a column name that is an empty string.
174 If the action code is <a href="../c3ref/c_alter_table.html">SQLITE_DELETE</a> and the callback returns
175 <a href="../c3ref/c_deny.html">SQLITE_IGNORE</a> then the <a href="../lang_delete.html">DELETE</a> operation proceeds but the
176 <a href="../lang_delete.html#truncateopt">truncate optimization</a> is disabled and all rows are deleted individually.</p>
177
178 <p>An authorizer is used when <a href="../c3ref/prepare.html">preparing</a>
179 SQL statements from an untrusted source, to ensure that the SQL statements
180 do not try to access data they are not allowed to see, or that they do not
181 try to execute malicious statements that damage the database. For
182 example, an application may allow a user to enter arbitrary
183 SQL queries for evaluation by a database. But the application does
184 not want the user to be able to make arbitrary changes to the
185 database. An authorizer could then be put in place while the
186 user-entered SQL is being <a href="../c3ref/prepare.html">prepared</a> that
187 disallows everything except <a href="../lang_select.html">SELECT</a> statements.</p>
188
189 <p>Applications that need to process SQL from untrusted sources
190 might also consider lowering resource limits using <a href="../c3ref/limit.html">sqlite3_limit()</a>
191 and limiting database size using the <a href="../pragma.html#pragma_max_page_count">max_page_count</a> <a href="../pragma.html#syntax">PRAGMA</a>
192 in addition to using an authorizer.</p>
193
194 <p>Only a single authorizer can be in place on a database connection
195 at a time. Each call to sqlite3_set_authorizer overrides the
196 previous call. Disable the authorizer by installing a NULL callback.
197 The authorizer is disabled by default.</p>
198
199 <p>The authorizer callback must not do anything that will modify
200 the database connection that invoked the authorizer callback.
201 Note that <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> and <a href="../c3ref/step.html">sqlite3_step()</a> both modify their
202 database connections for the meaning of "modify" in this paragraph.</p>
203
204 <p>When <a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> is used to prepare a statement, the
205 statement might be re-prepared during <a href="../c3ref/step.html">sqlite3_step()</a> due to a
206 schema change. Hence, the application should ensure that the
207 correct authorizer callback remains in place during the <a href="../c3ref/step.html">sqlite3_step()</a>.</p>
208
209 <p>Note that the authorizer callback is invoked only during
210 <a href="../c3ref/prepare.html">sqlite3_prepare()</a> or its variants. Authorization is not
211 performed during statement evaluation in <a href="../c3ref/step.html">sqlite3_step()</a>, unless
212 as stated in the previous paragraph, sqlite3_step() invokes
213 sqlite3_prepare_v2() to reprepare a statement after a schema change.
214 </p><p>See also lists of
215 <a href="../c3ref/objlist.html">Objects</a>,
216 <a href="../c3ref/constlist.html">Constants</a>, and
217 <a href="../c3ref/funclist.html">Functions</a>.</p>
218