33.27 Suspicious Text

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.

Function: textsec-suspicious-p object type

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).