From 21e96ce324f2302ee6fb84d387ceed6911aadd04 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 20 Jan 2022 11:04:41 +0200 Subject: [PATCH] Improve documentation of textsec * lisp/international/textsec-check.el (textsec-check): Doc fixes. * doc/lispref/text.texi (Suspicious Text): Improve wording and indexing. --- doc/lispref/text.texi | 58 +++++++++++++++++------------ etc/NEWS | 4 +- lisp/international/textsec-check.el | 30 +++++++++++---- 3 files changed, 60 insertions(+), 32 deletions(-) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index e94b1112d70..097c1de4449 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -4946,9 +4946,12 @@ It should be somewhat more efficient on larger buffers than @node Suspicious Text @section Suspicious Text +@cindex suspicious text +@cindex insecure text +@cindex security vulnerabilities in 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 + Emacs can display text from many external sources, like email and Web +sites. Attackers may attempt to confuse the user reading this text 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. @@ -4959,11 +4962,13 @@ 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. +@cindex suspicious text strings +To help identify these @dfn{suspicious text strings}, Emacs provides a +library to do a number of checks on text. (See +@url{https://www.unicode.org/reports/tr39/, UTS #39: Unicode Security +Mechanisms} for the rationale behind the checks that are available and +more details about them.) Packages that present data that might be +suspicious should use this library to flag suspicious text on display. @vindex textsec-check @defun textsec-check object type @@ -4971,52 +4976,59 @@ 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: +This function checks @var{object} (whose data type depends on +@var{type}) to see if it looks suspicious when interpreted as a thing +of @var{type}. The available types and the corresponding @var{object} +data types are: @table @code @item domain Check whether a domain (e.g., @samp{www.gnu.org} looks suspicious. +@var{object} should be a string, the domain name. @item url Check whether an @acronym{URL} (e.g., @samp{http://gnu.org/foo/bar}) -looks suspicious. +looks suspicious. @var{object} should be a string, the @acronym{URL} +to check. @item link Check whether an @acronym{HTML} link (e.g., @samp{fsf.org} 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}. +@acronym{URL} string, 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. +suspicious. @var{object} should be a string. @item local-address Check whether the local part of an email address (the bit before the -@samp{@@} sign) looks suspicious. +@samp{@@} sign) looks suspicious. @var{object} should be a string. @item name -Check whether a name (used in an email address header) looks suspicious. +Check whether a name (used in an email address header) looks +suspicious. @var{object} should be a string. @item email-address-header Check whether a full RFC2822 email address header (e.g., @samp{=?utf-8?Q?=C3=81?= }) looks suspicious. +@var{object} should be a string. @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}. +If @var{object} is suspicious, this function returns a string that +explains why it is suspicious. If @var{object} is not suspicious, the +function returns @code{nil}. @end defun +@vindex textsec-suspicious@r{ (face)} 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). +returned by @code{textsec-check} available to the user in some way +(for example, in a tooltip). The application might also prompt the +user for confirmation before taking any action on a suspicious string +(like sending an email to a suspicious email address). @node GnuTLS Cryptography @section GnuTLS Cryptography diff --git a/etc/NEWS b/etc/NEWS index d3abe349f2a..17ddd6bc186 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1023,8 +1023,8 @@ may be used to confuse a user. If non-nil (which is the default), Emacs packages that are vulnerable to attackers trying to confuse the users will use the textsec library to mark suspicious text. For instance shr/eww will mark suspicious -URLs and links, and Gnus will mark suspicious From addresses, and -Message will query the user if the user is sending mail to a +URLs and links, Gnus will mark suspicious From addresses, and +Message mode will query the user if the user is sending mail to a suspicious address. If this variable is nil, these checks aren't performed. diff --git a/lisp/international/textsec-check.el b/lisp/international/textsec-check.el index f61cc82b5b2..e3662e0d85c 100644 --- a/lisp/international/textsec-check.el +++ b/lisp/international/textsec-check.el @@ -29,7 +29,7 @@ :version "29.1") (defcustom textsec-check t - "If non-nil, perform some checks on certain texts. + "If non-nil, perform some security-related checks on text objects. If nil, these checks are disabled." :type 'boolean :version "29.1") @@ -40,14 +40,30 @@ If nil, these checks are disabled." ;;;###autoload (defun textsec-check (object type) - "Test whether OBJECT is suspicious when considered as TYPE. -If OBJECT is suspicious, a string explaining the possible problem -is returned. + "Test whether OBJECT is suspicious for use as TYPE. +If OBJECT is suspicious, return a string explaining the reason +for considering it suspicious, otherwise return nil. -Available types include `url', `link', `domain', `local-address', -`name', `email-address', and `email-address-header'. +Available values of TYPE and corresponding OBJECTs are: -If the `textsec-check' user option is nil, these checks are + `url' -- a URL; OBJECT should be a URL string. + + `link' -- an HTML link; OBJECT should be a cons cell + of the form (URL . LINK-TEXT). + + `domain' -- a Web domain; OBJECT should be a string. + + `local-address' -- the local part of an email address; OBJECT + should be a string. + `name' -- the \"display name\" part of an email address; + OBJECT should be a string. + +`email-address' -- a full email address; OBJECT should be a string. + + `email-address-header' -- a raw email address header in RFC 2822 format; + OBJECT should be a string. + +If the user option `textsec-check' is nil, these checks are disabled, and this function always returns nil." (if (not textsec-check) nil -- 2.39.5