| 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 |
|