From e22f5c07d8bf514283221f337afb1ef7ca1cd2b8 Mon Sep 17 00:00:00 2001 From: Lars Magne Ingebrigtsen Date: Mon, 24 Nov 2014 18:29:47 +0100 Subject: [PATCH] Moved the Network Security Manager to the Emacs manual * misc.texi (Gnus Summary Buffer): Moved the Network Security Manager stuff here from the lispref manual. --- doc/emacs/ChangeLog | 5 ++ doc/emacs/emacs.texi | 1 + doc/emacs/misc.texi | 103 +++++++++++++++++++++++++++++++++++++ doc/lispref/ChangeLog | 2 + doc/lispref/elisp.texi | 1 - doc/lispref/processes.texi | 103 ------------------------------------- etc/ChangeLog | 4 ++ etc/NEWS | 4 ++ 8 files changed, 119 insertions(+), 104 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index aa9804fa94c..198de4f2636 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,8 @@ +2014-11-24 Lars Magne Ingebrigtsen + + * misc.texi (Gnus Summary Buffer): Move the Network Security + Manager stuff here from the lispref manual. + 2014-11-21 Eli Zaretskii * maintaining.texi (Version Control Systems): Move "@end itemize" diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 702aa64bc25..66b10145e06 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -189,6 +189,7 @@ Advanced Features * Sending Mail:: Sending mail in Emacs. * Rmail:: Reading mail in Emacs. * Gnus:: A flexible mail and news reader. +* Network Security:: Managing the network security. * Document View:: Viewing PDF, PS and DVI files. * EWW:: A web browser in Emacs. * Shell:: Executing shell commands from Emacs. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index af5ced77b52..2295414aa55 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -249,6 +249,109 @@ 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 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}). + +@vindex network-security-level +The @code{network-security-level} variable determines the security +level. If this 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 +connection. + +The user is given the choice of registering a permanent security +exception, a temporary one, or whether to 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, the @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. + +@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. + +@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, the +@acronym{NSM} will warn you. + +@end table + +If @code{network-security-level} is @code{high}, the following checks +will be made: + +@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 +services, you may want to keep track of these changes. +@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 +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. + +@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}. + +@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. +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. +@end table + + @node Document View @section Document Viewing @cindex DVI file diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 57c5c65a96a..b0da266d53a 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -3,6 +3,8 @@ * processes.texi (Network Security): Made into its own section and fleshed out. (Network Security): Mention more NSM variables. + (Processes): Moved the Network Security Manager stuff to the Emacs + manual. 2014-11-23 Lars Magne Ingebrigtsen diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 754140e587c..fa665da34a4 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1299,7 +1299,6 @@ Processes * System Processes:: Accessing other processes running on your system. * Transaction Queues:: Transaction-based communication with subprocesses. * Network:: Opening network connections. -* Network Security:: Managing the network security. * Network Servers:: Network servers let Emacs accept net connections. * Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index c93288f2028..0952cc15f03 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -52,7 +52,6 @@ Processes}. * System Processes:: Accessing other processes running on your system. * Transaction Queues:: Transaction-based communication with subprocesses. * Network:: Opening network connections. -* Network Security:: Managing the network security. * Network Servers:: Network servers let Emacs accept net connections. * Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function @@ -2074,108 +2073,6 @@ The connection type: @samp{plain} or @samp{tls}. @end defun -@node Network Security -@section Network Security -@cindex Network Security Manager -@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}). - -@vindex network-security-level -The @code{network-security-level} variable determines the security -level. If this 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 -connection. - -The user is given the choice of registering a permanent security -exception, a temporary one, or whether to 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, the @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. - -@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. - -@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, the -@acronym{NSM} will warn you. - -@end table - -If @code{network-security-level} is @code{high}, the following checks -will be made: - -@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 -services, you may want to keep track of these changes. -@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 -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. - -@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}. - -@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. -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. -@end table - - @node Network Servers @section Network Servers @cindex network servers diff --git a/etc/ChangeLog b/etc/ChangeLog index 867e4f5f09c..5d616129ad0 100644 --- a/etc/ChangeLog +++ b/etc/ChangeLog @@ -1,3 +1,7 @@ +2014-11-24 Lars Magne Ingebrigtsen + + * NEWS: Mention NSM. + 2014-11-23 Lars Magne Ingebrigtsen * NEWS: Mention `url-request-noninteractive'. diff --git a/etc/NEWS b/etc/NEWS index da2edb66e42..6cad6a37c1b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -49,6 +49,10 @@ Use './configure PKG_CONFIG=/full/name/of/pkg-config' if you need to. * Changes in Emacs 25.1 +** Network security (TLS/SSL certificate validity and the like) is +added via the new Network Security Manager (NSM) and controlled via +the `network-security-level' variable. + ** C-h l now also lists the commands that were run. ** The new M-s M-w key binding uses eww to search the web for the -- 2.39.5