Document textsec

* doc/lispref/elisp.texi (Top): Add menu.
* doc/lispref/text.texi (Text): Add menu.
(Suspicious Text): New node.

* lisp/international/textsec-check.el (textsec-check): Adjust doc
string.

1 files changed, 75 insertions, 0 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index b9df66dbdb4..e94b1112d70 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -59,6 +59,7 @@ the character after point.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
 * Checksum/Hash::    Computing cryptographic hashes.
+* Suspicious Text::  Determining whether a string is suspicious.
 * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
 * Database::         Interacting with an SQL database.
 * Parsing HTML/XML:: Parsing HTML and XML.
@@ -4943,6 +4944,80 @@ It should be somewhat more efficient on larger buffers than
 @c according to what we find useful.
 @end defun
 
+@node Suspicious Text
+@section Suspicious Text
+
+Emacs can display data from many external sources, like mail and web
+pages.  Attackers may attempt to confuse the user reading this data by
+using obfuscated @acronym{URL}s or email addresses, and tricking the
+user into visiting a web page they didn't intend to visit, or sending
+an email to the wrong address.
+
+This usually involves using characters from scripts that visually look
+like @acronym{ASCII} characters (i.e., are homoglyphs), but there are
+also other techniques used, like using bidirectional overrides, or
+having an @acronym{HTML} link text that says one thing, while the
+underlying @acronym{URL} points somewhere else.
+
+To help identify these @dfn{suspicious strings}, Emacs provides a
+library to do a number of checks.  (See
+@url{https://www.unicode.org/reports/tr39/} for the rationale behind
+the checks that are available.)  Packages that present data that might
+be suspicious should use this library.
+
+@vindex textsec-check
+@defun textsec-check object type
+This function is the high-level interface function that packages
+should use.  It respects the @code{textsec-check} user option, which
+allows the user to disable the checks.
+
+This function checks @var{object} to see if it looks suspicious when
+interpreted as a thing of @var{type}.  The available types are:
+
+@table @code
+@item domain
+Check whether a domain (e.g., @samp{www.gnu.org} looks suspicious.
+
+@item url
+Check whether an @acronym{URL} (e.g., @samp{http://gnu.org/foo/bar})
+looks suspicious.
+
+@item link
+Check whether an @acronym{HTML} link (e.g., @samp{<a
+href='http://gnu.org'>fsf.org</a>} looks suspicious.  In this case,
+@var{object} should be a @code{cons} cell where the @code{car} is the
+@acronym{URL} and the @code{cdr} is the link text.  The link is deemed
+suspicious if the link text contains a domain name, and that domain
+name points to something other than the @acronym{URL}.
+
+@item email-address
+Check whether an email address (e.g., @samp{foo@@example.org}) looks
+suspicious.
+
+@item local-address
+Check whether the local part of an email address (the bit before the
+@samp{@@} sign) looks suspicious.
+
+@item name
+Check whether a name (used in an email address header) looks suspicious.
+
+@item email-address-header
+Check whether a full RFC2822 email address header (e.g.,
+@samp{=?utf-8?Q?=C3=81?= <foo@@example.com>}) looks suspicious.
+@end table
+
+If @var{object} is suspicious, this function will return a string that
+explains why it is suspicious.  If @var{object} is not suspicious, it
+returns @code{nil}.
+@end defun
+
+If the text is suspicious, the application should mark the suspicious
+text with the @code{textsec-suspicious} face, and make the explanation
+returned by @code{textsec-check} available to the user.  The
+application might also prompt the user before taking any action on a
+suspicious string (like sending an email to a suspicious email
+address).
+
 @node GnuTLS Cryptography
 @section GnuTLS Cryptography
 @cindex MD5 checksum