Fossil SCM

Improved documentation on the "html", "puts", and "query" TH1 commands.

drh 2025-04-12 17:35 trunk
Commit 41cd8d51ba7ce1a58637ab6c579e5264bc8a713d01d6d84ef5cc4b28e808aba7
Parent 7a85c54bd5217b9…
1 file changed +43 -3
~ www/th1.md
M www/th1.md
+43 -3
--- www/th1.md
+++ www/th1.md
@@ -527,11 +527,23 @@
527527
 <a id="html"></a>TH1 html Command
528528
 -----------------------------------
529529
530530
 * html STRING
531531
532
-Outputs the STRING escaped for HTML.
532
+Outputs the STRING literally. It is assumed that STRING contains
533
+valid HTML, or that if it text then any characters that are
534
+significant to HTML (such as `<`, `>`, `'`, or `&`) have already
535
+been escaped, perhaps by the htmlize command. Use the
536
+[puts](#puts) command to output text that might contain unescaped
537
+HTML markup.
538
+
539
+**Beware of XSS attacks!** If the STRING value to the html command
540
+can be controlled by a hostile user, then he might be able to sneak
541
+in malicious HTML or Javascript which could result in a
542
+cross-site scripting (XSS) attack. Be careful that all text that
543
+in STRING that might come from user input has been sanitized by the
544
+[htmlize](#htmlize) command or similar.
533545
534546
 <a id="htmlize"></a>TH1 htmlize Command
535547
 -----------------------------------------
536548
537549
 * htmlize STRING
@@ -595,12 +607,14 @@
595607
 <a id="puts"></a>TH1 puts Command
596608
 -----------------------------------
597609
598610
 * puts STRING
599611
600
-Outputs the STRING unchanged, where "unchanged" might, depending on
601
-the context, mean "with some characters escaped for HTML."
612
+Outputs STRING. Characters within STRING that have special meaning
613
+in HTML are escaped prior to being output. Thus is it safe for STRING
614
+to be derived from user inputs. See also the [html](#html) command
615
+which behaves similarly except does not escape HTML markup.
602616
603617
 <a id="query"></a>TH1 query Command
604618
 -------------------------------------
605619
606620
 * query ?-nocomplain? SQL CODE
@@ -610,10 +624,36 @@
610624
611625
 In SQL, parameters such as $var are filled in using the value of variable
612626
 "var". Result values are stored in variables with the column name prior
613627
 to each invocation of CODE.
614628
629
+**Beware of SQL injections in the `query` command!**
630
+The SQL argument to the query command should always be literal SQL
631
+text enclosed in {...}. The SQL argument should never be a double-quoted
632
+string or the value of a \$variable, as those constructs can lead to
633
+an SQL Injection attack. If you need to include the values of one or
634
+more TH1 variables as part of the SQL, then put \$variable inside the
635
+{...}. The \$variable keyword will then get passed down into the SQLite
636
+parser which knows to look up the value of \$variable in the TH1 symbol
637
+table. For example:
638
+
639
+~~~
640
+ query {SELECT res FROM tab1 WHERE key=$mykey} {...}
641
+~~~
642
+
643
+SQLite will see the \$mykey token in the SQL and will know to resolve it
644
+to the value of the "mykey" TH1 variable, safely and without the possibility
645
+of SQL injection. The following is unsafe:
646
+
647
+~~~
648
+ query "SELECT res FROM tab1 WHERE key='$mykey'" {...} ;# <-- UNSAFE!
649
+~~~
650
+
651
+In this second example, TH1 does the expansion of `$mykey` prior to passing
652
+the text down into SQLite. So if `$mykey` contains a single-quote character,
653
+followed by additional hostile text, that will result in an SQL injection.
654
+
615655
 <a id="randhex"></a>TH1 randhex Command
616656
 -----------------------------------------
617657
618658
 * randhex N
619659
620660
--- www/th1.md
+++ www/th1.md
@@ -527,11 +527,23 @@
527 <a id="html"></a>TH1 html Command
528 -----------------------------------
529
530 * html STRING
531
532 Outputs the STRING escaped for HTML.
 
 
 
 
 
 
 
 
 
 
 
 
533
534 <a id="htmlize"></a>TH1 htmlize Command
535 -----------------------------------------
536
537 * htmlize STRING
@@ -595,12 +607,14 @@
595 <a id="puts"></a>TH1 puts Command
596 -----------------------------------
597
598 * puts STRING
599
600 Outputs the STRING unchanged, where "unchanged" might, depending on
601 the context, mean "with some characters escaped for HTML."
 
 
602
603 <a id="query"></a>TH1 query Command
604 -------------------------------------
605
606 * query ?-nocomplain? SQL CODE
@@ -610,10 +624,36 @@
610
611 In SQL, parameters such as $var are filled in using the value of variable
612 "var". Result values are stored in variables with the column name prior
613 to each invocation of CODE.
614
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
615 <a id="randhex"></a>TH1 randhex Command
616 -----------------------------------------
617
618 * randhex N
619
620
--- www/th1.md
+++ www/th1.md
@@ -527,11 +527,23 @@
527 <a id="html"></a>TH1 html Command
528 -----------------------------------
529
530 * html STRING
531
532 Outputs the STRING literally. It is assumed that STRING contains
533 valid HTML, or that if it text then any characters that are
534 significant to HTML (such as `<`, `>`, `'`, or `&`) have already
535 been escaped, perhaps by the htmlize command. Use the
536 [puts](#puts) command to output text that might contain unescaped
537 HTML markup.
538
539 **Beware of XSS attacks!** If the STRING value to the html command
540 can be controlled by a hostile user, then he might be able to sneak
541 in malicious HTML or Javascript which could result in a
542 cross-site scripting (XSS) attack. Be careful that all text that
543 in STRING that might come from user input has been sanitized by the
544 [htmlize](#htmlize) command or similar.
545
546 <a id="htmlize"></a>TH1 htmlize Command
547 -----------------------------------------
548
549 * htmlize STRING
@@ -595,12 +607,14 @@
607 <a id="puts"></a>TH1 puts Command
608 -----------------------------------
609
610 * puts STRING
611
612 Outputs STRING. Characters within STRING that have special meaning
613 in HTML are escaped prior to being output. Thus is it safe for STRING
614 to be derived from user inputs. See also the [html](#html) command
615 which behaves similarly except does not escape HTML markup.
616
617 <a id="query"></a>TH1 query Command
618 -------------------------------------
619
620 * query ?-nocomplain? SQL CODE
@@ -610,10 +624,36 @@
624
625 In SQL, parameters such as $var are filled in using the value of variable
626 "var". Result values are stored in variables with the column name prior
627 to each invocation of CODE.
628
629 **Beware of SQL injections in the `query` command!**
630 The SQL argument to the query command should always be literal SQL
631 text enclosed in {...}. The SQL argument should never be a double-quoted
632 string or the value of a \$variable, as those constructs can lead to
633 an SQL Injection attack. If you need to include the values of one or
634 more TH1 variables as part of the SQL, then put \$variable inside the
635 {...}. The \$variable keyword will then get passed down into the SQLite
636 parser which knows to look up the value of \$variable in the TH1 symbol
637 table. For example:
638
639 ~~~
640 query {SELECT res FROM tab1 WHERE key=$mykey} {...}
641 ~~~
642
643 SQLite will see the \$mykey token in the SQL and will know to resolve it
644 to the value of the "mykey" TH1 variable, safely and without the possibility
645 of SQL injection. The following is unsafe:
646
647 ~~~
648 query "SELECT res FROM tab1 WHERE key='$mykey'" {...} ;# <-- UNSAFE!
649 ~~~
650
651 In this second example, TH1 does the expansion of `$mykey` prior to passing
652 the text down into SQLite. So if `$mykey` contains a single-quote character,
653 followed by additional hostile text, that will result in an SQL injection.
654
655 <a id="randhex"></a>TH1 randhex Command
656 -----------------------------------------
657
658 * randhex N
659
660

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button