hmtl: add security section to package comment
Adds a short security considerations paragraph to the package comment
detailing the differences between the parser and tokenizer.
Change-Id: I9e6840b20f82ffc6bc4088fffd6b4eda97550c0a
Reviewed-on: https://go-review.googlesource.com/c/net/+/459676
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>
Run-TryBot: Roland Shoemaker <roland@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
diff --git a/html/doc.go b/html/doc.go
index 822ed42..7a96eae 100644
--- a/html/doc.go
+++ b/html/doc.go
@@ -92,6 +92,21 @@
The relevant specifications include:
https://html.spec.whatwg.org/multipage/syntax.html and
https://html.spec.whatwg.org/multipage/syntax.html#tokenization
+
+# Security Considerations
+
+Care should be taken when parsing and interpreting HTML, whether full documents
+or fragments, within the framework of the HTML specification, especially with
+regard to untrusted inputs.
+
+This package provides both a tokenizer and a parser. Only the parser constructs
+a DOM according to the HTML specification, resolving malformed and misplaced
+tags where appropriate. The tokenizer simply tokenizes the HTML presented to it,
+and as such does not resolve issues that may exist in the processed HTML,
+producing a literal interpretation of the input.
+
+If your use case requires semantically well-formed HTML, as defined by the
+WHATWG specifiction, the parser should be used rather than the tokenizer.
*/
package html // import "golang.org/x/net/html"
