@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.
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
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{<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}.
+@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?= <foo@@example.com>}) 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
: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")
;;;###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
projects / emacs.git / commitdiff