@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands
@node Network Security
@section Network Security
-@cindex Network Security Manager
+@cindex network security manager
+@cindex NSM
@cindex encryption
@cindex SSL
@cindex TLS
@cindex STARTTLS
-After establishing a network connection, the connection is then passed
-on to the Network Security Manager (@acronym{NSM}).
+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. If this is @code{low}, no security checks are performed.
+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 the @acronym{NSM} determines that the
-network connection might be unsafe, the user is made aware of this,
-and the @acronym{NSM} will ask the user what to do about the network
+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.
-The user is given the choice of registering a permanent security
-exception, a temporary one, or whether to refuse the 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.
@item unable to verify a @acronym{TLS} certificate
If the connection is a @acronym{TLS}, @acronym{SSL} or
-@acronym{STARTTLS} connection, the @acronym{NSM} will check whether
+@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 may
-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 the user to determine
-whether it's acceptable to continue the connection.
+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 either means that the server has just changed the
-certificate, or this might mean that the network connection has been
-hijacked.
+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
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, the
+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:
+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 that issue new certificates for third-party
+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 the @acronym{NSM} sees any new
+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
-@acronym{NSM} details.
+The following additional variables can be used to control details of
+@acronym{NSM} operation:
@table @code
@item nsm-settings-file
@vindex nsm-settings-file
-The @acronym{NSM} stores details on the connections in this file. It
-defaults to @file{~/.emacs.d/network-security.data}.
+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 per non-@code{STARTTLS}
-connection. Instead a host/port hash is used to identify connections.
+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}, host
-names will be saved in the file, too.
+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
A more convenient graphical way to specify the slice is with @kbd{s
m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
-select the slice.
-@c ??? How does this work?
+select the slice. Simply press and hold the left mouse button at the
+upper-left corner of the region you want to have in the slice, then
+move the mouse pointer to the lower-right corner and release the
+button.
The most convenient way is to set the optimal slice by using
BoundingBox information automatically determined from the document by
-typing @kbd{s b} (@code{doc-view-set-slice-using-mouse}).
+typing @kbd{s b} (@code{doc-view-set-slice-from-bounding-box}).
@findex doc-view-reset-slice
To cancel the selected slice, type @kbd{s r}