Debian Codegraph @

www/security.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>Defense Against The Dark Arts</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 <div class=fancy>
119 <div class=nosearch>
120 <div class="fancy_title">
121 Defense Against The Dark Arts
122 </div>
123 </div>
124
125
126
127
128 <h1 id="sqlite_always_validates_its_inputs"><span>1. </span>SQLite Always Validates Its Inputs</h1>
129
130 <p>
131 SQLite should never crash, overflow a buffer, leak memory,
132 or exhibit any other harmful behavior, even when presented with
133 maliciously malformed SQL inputs or database files. SQLite should
134 always detect erroneous inputs and raise an error, not crash or
135 corrupt memory.
136 Any malfunction caused by an SQL input or database file
137 is considered a serious bug and will be promptly addressed when
138 brought to the attention of the SQLite developers. SQLite is
139 extensively fuzz-tested to help ensure that it is resistant
140 to these kinds of errors.
141
142 </p><p>
143 Nevertheless, bugs happen.
144 If you are writing an application that sends untrusted SQL inputs
145 or database files to SQLite, there are additional steps you can take
146 to help reduce the attack surface and
147 prevent zero-day exploits caused by undetected bugs.
148
149 </p><h2 id="untrusted_sql_inputs"><span>1.1. </span>Untrusted SQL Inputs</h2>
150 <p>
151 Applications that accept untrusted SQL inputs should take the following
152 precautions:
153
154 </p><ol>
155 <li><p>
156 Set the <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigdefensive">SQLITE_DBCONFIG_DEFENSIVE</a> flag.
157 This prevents ordinary SQL statements from deliberately corrupting the
158 database file. SQLite should be proof against attacks that involve both
159 malicious SQL inputs and a maliciously corrupted database file at the
160 same time. Nevertheless, denying a script-only attacker access to
161 corrupt database inputs provides an extra layer of defense.
162
163 </p></li><li><p>
164 Reduce the <a href="limits.html">limits</a> that SQLite imposes on inputs. This can help prevent
165 denial of service attacks and other kinds of mischief that can occur
166 as a result of unusually large inputs. You can do this either at compile-time
167 using -DSQLITE_MAX_... options, or at run-time using the
168 <a href="c3ref/limit.html">sqlite3_limit()</a> interface. Most applications can reduce limits
169 dramatically without impacting functionality. The table below
170 provides some suggestions, though exact values will vary depending
171 on the application:
172
173 </p><table border="1" cellspacing="0">
174 <tr><th>Limit Setting</th><th>Default Value</th><th>High-security Value
175 </th></tr><tr><td>LIMIT_LENGTH</td><td align="right">1,000,000,000</td><td align="right">1,000,000
176 </td></tr><tr><td>LIMIT_SQL_LENGTH</td><td align="right">1,000,000,000</td><td align="right">100,000
177 </td></tr><tr><td>LIMIT_COLUMN</td><td align="right">2,000</td><td align="right">100
178 </td></tr><tr><td>LIMIT_EXPR_DEPTH</td><td align="right">1,000</td><td align="right">10
179 </td></tr><tr><td>LIMIT_PARSER_DEPTH</td><td align="right">2,500</td><td align="right">100
180 </td></tr><tr><td>LIMIT_COMPOUND_SELECT</td><td align="right">500</td><td align="right">3
181 </td></tr><tr><td>LIMIT_VDBE_OP</td><td align="right">250,000,000</td><td align="right">25,000
182 </td></tr><tr><td>LIMIT_FUNCTION_ARG</td><td align="right">127</td><td align="right">8
183 </td></tr><tr><td>LIMIT_ATTACH</td><td align="right">10</td><td align="right">0
184 </td></tr><tr><td>LIMIT_LIKE_PATTERN_LENGTH</td><td align="right">50,000</td><td align="right">50
185 </td></tr><tr><td>LIMIT_VARIABLE_NUMBER</td><td align="right">999</td><td align="right">10
186 </td></tr><tr><td>LIMIT_TRIGGER_DEPTH</td><td align="right">1,000</td><td align="right">10
187 </td></tr></table>
188
189 </li><li><p>
190 Consider using the <a href="c3ref/set_authorizer.html">sqlite3_set_authorizer()</a> interface to limit
191 the scope of SQL that will be processed. For example, an application
192 that does not need to change the database schema might add an
193 sqlite3_set_authorizer() callback that causes any CREATE or DROP
194 statement to fail.
195
196 </p></li><li><p>
197 The SQL language is very powerful, and so it is always possible for
198 malicious SQL inputs (or erroneous SQL inputs caused by an application
199 bug) to submit SQL that runs for a very long time. To prevent this
200 from becoming a denial-of-service attack, consider using the
201 <a href="c3ref/progress_handler.html">sqlite3_progress_handler()</a> interface to invoke a callback periodically
202 as each SQL statement runs, and have that callback return non-zero to
203 abort the statement if the statement runs for too long. Alternatively,
204 set a timer in a separate thread and invoke <a href="c3ref/interrupt.html">sqlite3_interrupt()</a> when
205 the timer goes off to prevent the SQL statement from running forever.
206
207 </p></li><li><p>
208 Limit the maximum amount of memory that SQLite will allocate using
209 the <a href="c3ref/hard_heap_limit64.html">sqlite3_hard_heap_limit64()</a> interface. This helps prevent
210 denial-of-service attacks. To find out how much heap space an
211 application actually needs, run the it against typical inputs and
212 then measure the maximum instantaneous memory usage with the
213 <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a> interface. Set the hard heap limit
214 to the maximum observed instantaneous memory usage plus some margin.
215
216 </p></li><li><p>
217 Consider setting the <a href="compile.html#max_allocation_size">SQLITE_MAX_ALLOCATION_SIZE</a> compile-time option
218 to something smaller than its default value of 2147483391 (0x7ffffeff).
219 A value of 100000000 (100 million) or even smaller would not be unreasonable,
220 depending on the application.
221
222 </p></li><li><p>
223 For embedded systems, consider compiling SQLite with the
224 <a href="compile.html#enable_memsys5">-DSQLITE_ENABLE_MEMSYS5</a> option and then providing SQLite with
225 a fixed chunk of memory to use as its heap via the
226 <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>) interface. This will
227 prevent malicious SQL from executing a denial-of-service attack
228 by using an excessive amount of memory. If (say) 5 MB of memory
229 is provided for SQLite to use, once that much has been consumed,
230 SQLite will start returning SQLITE_NOMEM errors rather than
231 soaking up memory needed by other parts of the application.
232 This also sandboxes SQLite's memory so that a write-after-free
233 error in some other part of the application will not cause
234 problems for SQLite, or vice versa.
235
236 <a name="precisionlimit"></a>
237 </p></li><li><p>
238 To control memory usage in the <a href="lang_corefunc.html#printf">printf() SQL function</a>, compile
239 with "<a href="compile.html#printf_precision_limit">-DSQLITE_PRINTF_PRECISION_LIMIT=100000</a>" or some similarly
240 reasonable value.
241 This #define limits the width and precision for %-substitutions in the
242 printf() function, and thus prevents a hostile SQL statement from
243 consuming large amounts of RAM via constructs such as
244 "<tt>printf('%1000000000s','hi')</tt>".
245 </p><p>
246 Note that SQLite uses its built-in printf() internally to help it
247 format the sql column in the <a href="schematab.html">sqlite_schema table</a>. For that reason,
248 no table, index, view, or trigger definition can be much larger than the
249 precision limit. You can set a precision limit of less than 100000,
250 but be careful that whatever precision limit you use is at least as
251 long as the longest CREATE statement in your schema.
252 </p></li>
253
254 </ol>
255
256 <a name="baddb"></a>
257
258 <h2 id="untrusted_sqlite_database_files"><span>1.2. </span>Untrusted SQLite Database Files</h2>
259
260 <p>Applications that read or write SQLite database files of uncertain
261 provenance should take precautions enumerated below.
262
263 </p><p>Even if the application does not deliberately accept database files
264 from untrusted sources, beware of attacks in which a local
265 database file is altered. For best security, any database file which
266 might have ever been writable by an agent in a different security domain
267 should be treated as suspect.
268
269 </p><ol>
270 <li value="9"><p>
271 If the application includes any <a href="appfunc.html">custom SQL functions</a> or
272 <a href="vtab.html#customvtab">custom virtual tables</a> that have side effects or that might leak
273 privileged information, then the application should use one or more
274 of the techniques below to prevent a maliciously crafted database
275 schema from surreptitiously running those SQL functions and/or
276 virtual tables for nefarious purposes:
277 </p><ol type="a">
278 <li> Invoke <a href="c3ref/db_config.html">sqlite3_db_config</a>(db,<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a>,0,0)
279 on each <a href="c3ref/sqlite3.html">database connection</a> as soon as it is opened.
280 </li><li> Run the <a href="pragma.html#pragma_trusted_schema">PRAGMA trusted_schema=OFF</a> statement on each database connection
281 as soon as it is opened.
282 </li><li> Compile SQLite using the <a href="compile.html#trusted_schema">-DSQLITE_TRUSTED_SCHEMA=0</a> compile-time option.
283 </li><li> Disable the surreptitious use of custom SQL functions and virtual tables
284 by setting the <a href="c3ref/c_deterministic.html#sqlitedirectonly">SQLITE_DIRECTONLY</a> flag on all custom SQL functions and
285 the <a href="c3ref/c_vtab_constraint_support.html#sqlitevtabdirectonly">SQLITE_VTAB_DIRECTONLY</a> flag on all custom virtual tables.
286 </li><li> Ensure that custom virtual tables that run SQL statements based
287 on arguments to the CREATE VIRTUAL TABLE statement in the database
288 schema use <a href="c3ref/prepare.html">sqlite3_prepare_v3()</a> with the <a href="c3ref/c_prepare_dont_log.html#sqlitepreparefromddl">SQLITE_PREPARE_FROM_DDL</a>
289 option to prevent bypass of the <a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a>
290 setting in item (9a) above.
291 </li></ol>
292
293 </li><li><p>
294 If the application does not use triggers or views, consider disabling the
295 unused capabilities with:
296 </p><blockquote><pre>
297 <a href="c3ref/db_config.html">sqlite3_db_config</a>(db,<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenabletrigger">SQLITE_DBCONFIG_ENABLE_TRIGGER</a>,0,0);
298 <a href="c3ref/db_config.html">sqlite3_db_config</a>(db,<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableview">SQLITE_DBCONFIG_ENABLE_VIEW</a>,0,0);
299 </pre></blockquote>
300
301 </li></ol>
302
303 <p>
304 If an application is particularly security sensitive, then
305 the following extra layers of defense might be justified.
306 These extra defenses come with performance costs,
307 however, and so may not be appropriate in every situation:
308
309 </p><ol>
310 <li value="11"><p>
311 Run <a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a> or <a href="pragma.html#pragma_quick_check">PRAGMA quick_check</a> on the database
312 as the first SQL statement after opening the database files and
313 prior to running any other SQL statements. Reject and refuse to
314 process any database file containing errors.
315
316 </p></li><li><p>
317 Enable the <a href="pragma.html#pragma_cell_size_check">PRAGMA cell_size_check=ON</a> setting.
318 </p><p>
319
320 </p></li><li><p>
321 Do not enable memory-mapped I/O.
322 In other words, make sure that <a href="pragma.html#pragma_mmap_size">PRAGMA mmap_size=0</a>.
323 </p></li></ol>
324
325
326 <h1 id="summary"><span>2. </span>Summary</h1>
327
328 <p>
329 The precautions above are not required in order to use SQLite safely
330 with potentially hostile inputs.
331 However, they do provide an extra layer of defense against zero-day
332 exploits and are encouraged for applications that pass data from
333 untrusted sources into SQLite.
334 </p><p align="center"><small><i>This page was last updated on 2026-02-26 14:36:36Z </small></i></p>
335