1 files changed, 127 insertions, 7 deletions
diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 0431e84b5b6..e12fca7ebdd 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -6,12 +6,12 @@
 @chapter Miscellaneous Commands
 
   This chapter contains several brief topics that do not fit anywhere
-else: viewing ``document files'', reading Usenet news, running shell
-commands and shell subprocesses, using a single shared Emacs for
-utilities that expect to run an editor as a subprocess, printing
-hardcopy, sorting text, editing binary files, saving an Emacs session
-for later resumption, following hyperlinks, emulating other editors,
-and various diversions and amusements.
+else: reading Usenet news, viewing PDFs and other such documents, web
+browsing, running shell commands and shell subprocesses, using a
+single shared Emacs for utilities that expect to run an editor as a
+subprocess, printing, sorting text, editing binary files, saving an
+Emacs session for later resumption, recursive editing level, following
+hyperlinks, and various diversions and amusements.
 
 @end iftex
 
@@ -249,6 +249,126 @@ Search forward for articles containing a match for @var{regexp}.
 Exit the summary buffer and return to the group buffer.
 @end table
 
+
+@node Network Security
+@section Network Security
+@cindex network security manager
+@cindex NSM
+@cindex encryption
+@cindex SSL
+@cindex TLS
+@cindex STARTTLS
+
+Whenever Emacs establishes any network connection, it passes the
+established connection to the @dfn{Network Security Manager}
+(@acronym{NSM}).  @acronym{NSM} is responsible for enforcing the
+network security under your control.
+
+@vindex network-security-level
+The @code{network-security-level} variable determines the security
+level that @acronym{NSM} enforces.  If its value is @code{low}, no
+security checks are performed.
+
+If this variable is @code{medium} (which is the default), a number of
+checks will be performed.  If as result @acronym{NSM} determines that
+the network connection might not be trustworthy, it will make you
+aware of that, and will ask you what to do about the network
+connection.
+
+You can decide to register a permanent security exception for an
+unverified connection, a temporary exception, or refuse the connection
+entirely.
+
+Below is a list of the checks done on the @code{medium} level.
+
+@table @asis
+
+@item unable to verify a @acronym{TLS} certificate
+If the connection is a @acronym{TLS}, @acronym{SSL} or
+@acronym{STARTTLS} connection, @acronym{NSM} will check whether
+the certificate used to establish the identity of the server we're
+connecting to can be verified.
+
+While an invalid certificate is often the cause for concern (there
+could be a Man-in-the-Middle hijacking your network connection and
+stealing your password), there may be valid reasons for going ahead
+with the connection anyway.  For instance, the server may be using a
+self-signed certificate, or the certificate may have expired.  It's up
+to you to determine whether it's acceptable to continue with the
+connection.
+
+@item a self-signed certificate has changed
+If you've previously accepted a self-signed certificate, but it has
+now changed, that could mean that the server has just changed the
+certificate, but it might also mean that the network connection has
+been hijacked.
+
+@item previously encrypted connection now unencrypted
+If the connection is unencrypted, but it was encrypted in previous
+sessions, this might mean that there is a proxy between you and the
+server that strips away @acronym{STARTTLS} announcements, leaving the
+connection unencrypted.  This is usually very suspicious.
+
+@item talking to an unencrypted service when sending a password
+When connecting to an @acronym{IMAP} or @acronym{POP3} server, these
+should usually be encrypted, because it's common to send passwords
+over these connections.  Similarly, if you're sending email via
+@acronym{SMTP} that requires a password, you usually want that
+connection to be encrypted.  If the connection isn't encrypted,
+@acronym{NSM} will warn you.
+
+@end table
+
+If @code{network-security-level} is @code{high}, the following checks
+will be made, in addition to the above:
+
+@table @asis
+@item a validated certificate changes the public key
+Servers change their keys occasionally, and that is normally nothing
+to be concerned about.  However, if you are worried that your network
+connections are being hijacked by agencies who have access to pliable
+Certificate Authorities which issue new certificates for third-party
+services, you may want to keep track of these changes.
+
+@item Diffie-Hellman low prime bits
+When doing the public key exchange, the number of ``prime bits''
+should be high to ensure that the channel can't be eavesdropped on by
+third parties.  If this number is too low, you will be warned.
+
+@item @acronym{RC4} stream cipher
+The @acronym{RC4} stream cipher is believed to be of low quality and
+may allow eavesdropping by third parties.
+
+@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3}
+The protocols older than @acronym{TLS1.0} are believed to be
+vulnerable to a variety of attacks, and you may want to avoid using
+these if what you're doing requires higher security.
+@end table
+
+Finally, if @code{network-security-level} is @code{paranoid}, you will
+also be notified the first time @acronym{NSM} sees any new
+certificate.  This will allow you to inspect all the certificates from
+all the connections that Emacs makes.
+
+The following additional variables can be used to control details of
+@acronym{NSM} operation:
+
+@table @code
+@item nsm-settings-file
+@vindex nsm-settings-file
+This is the file where @acronym{NSM} stores details about connections.
+It defaults to @file{~/.emacs.d/network-security.data}.
+
+@item nsm-save-host-names
+@vindex nsm-save-host-names
+By default, host names will not be saved for non-@code{STARTTLS}
+connections.  Instead a host/port hash is used to identify connections.
+This means that one can't casually read the settings file to see what
+servers the user has connected to.  If this variable is @code{t},
+@acronym{NSM} will also save host names in the nsm-settings-file.
+@end table
+
+
 @node Document View
 @section Document Viewing
 @cindex DVI file
@@ -2295,7 +2415,7 @@ the order you choose.
 @cindex vi
 @cindex WordStar
 
-  GNU Emacs can be programmed to emulate (more or less) some other
+  GNU Emacs can be programmed to emulate (more or less) most other
 editors.  Standard facilities can emulate these:
 
 @table @asis