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 URLs 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 ASCII characters (i.e., are homoglyphs), but there are also other techniques used, like using bidirectional overrides, or having an HTML link text that says one thing, while the underlying URL points somewhere else.
To help identify these suspicious text strings, Emacs provides a library to do a number of checks on text. (See 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.
This function is the high-level interface function that packages
should use. It respects the textsec-check
user option, which
allows the user to disable the checks.
This function checks object (whose data type depends on type) to see if it looks suspicious when interpreted as a thing of type. The available types and the corresponding object data types are:
domain
Check whether a domain (e.g., ‘www.gnu.org’ looks suspicious. object should be a string, the domain name.
url
Check whether an URL (e.g., ‘http://gnu.org/foo/bar’) looks suspicious. object should be a string, the URL to check.
link
Check whether an HTML link (e.g., ‘<a
href='http://gnu.org'>fsf.org</a>’ looks suspicious. In this case,
object should be a cons
cell where the car
is the
URL string, and the 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 URL.
email-address
Check whether an email address (e.g., ‘foo@example.org’) looks suspicious. object should be a string.
local-address
Check whether the local part of an email address (the bit before the ‘@’ sign) looks suspicious. object should be a string.
name
Check whether a name (used in an email address header) looks suspicious. object should be a string.
email-address-header
Check whether a full RFC2822 email address header (e.g., ‘=?utf-8?Q?=C3=81?= <foo@example.com>’) looks suspicious. object should be a string.
If object is suspicious, this function returns a string that
explains why it is suspicious. If object is not suspicious, the
function returns nil
.
If the text is suspicious, the application should mark the suspicious
text with the textsec-suspicious
face, and make the explanation
returned by textsec-suspicious-p
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).