emacs-30 8a0c9c234f1: Document 'trusted-content

[Eli Zaretskii]

branch: emacs-30
commit 8a0c9c234f15a7398d43da154f3463c92f69f9f5
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Document 'trusted-content
    
    * doc/emacs/misc.texi (Host Security): Document 'trusted-content'.
    
    * lisp/files.el (trusted-content): Doc fix.
    
    * etc/NEWS: Mark its entry as "documented".
---
 doc/emacs/misc.texi | 33 +++++++++++++++++++++++++++++++++
 etc/NEWS            |  1 +
 lisp/files.el       |  2 +-
 3 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index d1e8217f579..97a82747bfc 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -277,6 +277,39 @@ trusted and the default checking for these variables is 
irritating,
 you can set @code{enable-local-variables} to @code{:all}.  @xref{Safe
 File Variables}.
 
+@cindex trusted files and directories
+Loading a file of Emacs Lisp code with @code{load-file} or
+@code{load-library} (@pxref{Lisp Libraries}) can execute some of the
+Lisp code in the file being loaded, so you should only load Lisp files
+whose source you trust.  However, some Emacs features can in certain
+situations execute Lisp code even without your explicit command or
+request.  For example, Flymake, the on-the-fly syntax checker for Emacs
+(@pxref{Top,,, flymake, GNU Flymake}), if it is enabled, can
+automatically execute some of the code in a Lisp file you visit as part
+of its syntax-checking job.  Similarly, some completion commands
+(@pxref{Completion}) in buffers visiting Lisp files sometimes need to
+expand Lisp macros for best results.  In these cases, just visiting a
+Lisp file and performing some editing in it could trigger execution of
+Lisp code.  If the visited file came from an untrusted source, it could
+include dangerous or even malicious code that Emacs would execute in
+those situations.
+
+To protect against this, Emacs disables execution of Lisp code by
+Flymake, completion, and some other features, unless the visited file is
+@dfn{trusted}.  It is up to you to specify which files on your system
+should be trusted, by customizing the user option
+@code{trusted-content}.
+
+@defopt trusted-content
+The value of this option is @code{nil} by default, which means no file
+is trusted.  You can customize the variable to be a list of one or more
+names of trusted files and directories.  A file name that ends in a
+slash @file{/} is interpreted as a directory, which means all its files
+and subdirectories are also trusted.  A special value @code{:all} means
+@emph{all} the files and directories on your system should be trusted;
+@strong{this is not recommended}, as it opens a gaping security hole.
+@end defopt
+
 @xref{Security Considerations,,, elisp, The Emacs Lisp Reference
 Manual}, for more information about security considerations when using
 Emacs as part of a larger application.
diff --git a/etc/NEWS b/etc/NEWS
index 8e92cef2bcb..2c3b78a4e2b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -199,6 +199,7 @@ see the variable 'url-request-extra-headers'.
 
 * Changes in Emacs 30.1
 
++++
 ** New user option 'trusted-content' to allow potentially dangerous features.
 This variable lists those files and directories whose content Emacs should
 consider as sufficiently trusted to run any part of the code contained
diff --git a/lisp/files.el b/lisp/files.el
index 0bc787aca31..86eff296459 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -725,7 +725,7 @@ Each element of the list should be a string:
 - If it ends in \"/\", it is considered as a directory name and means that
   Emacs should trust all the files whose name has this directory as a prefix.
 - else it is considered as a file name.
-Use abbreviated file names.  For example, an entry \"~/mycode\" means
+Use abbreviated file names.  For example, an entry \"~/mycode/\" means
 that Emacs will trust all the files in your directory \"mycode\".
 This variable can also be set to `:all', in which case Emacs will trust
 all files, which opens a gaping security hole."