Rocco Rutte:
[apps/madmutt.git] / doc / manual.sgml.head
index da82317..eace2af 100644 (file)
@@ -2460,6 +2460,15 @@ ifndef feature_slang 'source ~/.mutt-ng/setup-ncurses'</verb>
 
   <!--}}}--> 
 
 
   <!--}}}--> 
 
+<sect>Obsolete Variables <!--{{{--> 
+
+<p>In the process of ensuring and creating more consistency, many
+variables have been renamed and some of the old names were already
+removed. Please see <ref id="sect_obsolete" name="Obsolete Variables">
+for a complete list.
+
+<!--}}}--> 
+
 <!--}}}--> 
 
 <chapt>Advanced Usage <!--{{{--> 
 <!--}}}--> 
 
 <chapt>Advanced Usage <!--{{{--> 
@@ -3269,21 +3278,37 @@ current message into a whole different thread.
 
 <!--}}}--> 
 
 
 <!--}}}--> 
 
-<sect>Delivery Status Notification (DSN) Support <!--{{{--> 
+<sect>Delivery Status Notification (DSN) Support<label id="dsn"> <!--{{{--> 
 <p>
 
 RFC1894 defines a set of MIME content types for relaying information
 about the status of electronic mail messages.  These can be thought of as
 <p>
 
 RFC1894 defines a set of MIME content types for relaying information
 about the status of electronic mail messages.  These can be thought of as
-``return receipts.'' Berkeley sendmail 8.8.x currently has some command
-line options in which the mail client can make requests as to what type
-of status messages should be returned.
+``return receipts.''
+
+Users can make use of it in one of the following two ways:
 
 
-To support this, there are two variables. <ref id="dsn_notify"
-name="&dollar;dsn&lowbar;notify"> is used to request receipts for
-different results (such as failed message, message delivered, etc.).
-<ref id="dsn_return" name="&dollar;dsn&lowbar;return"> requests how much
-of your message should be returned with the receipt (headers or full
-message).  Refer to the man page on sendmail for more details on DSN.
+<itemize>
+  <item>Berkeley sendmail 8.8.x currently has some command line options
+    in which the mail client can make requests as to what type of status
+    messages should be returned.
+  <item>The SMTP support via libESMTP supports it, too.
+</itemize>
+
+To support this, there are two variables:
+
+<itemize>
+
+  <item><ref id="dsn_notify" name="&dollar;dsn&lowbar;notify"> is used
+    to request receipts for different results (such as failed message,
+    message delivered, etc.).
+
+  <item><ref id="dsn_return" name="&dollar;dsn&lowbar;return"> requests
+    how much of your message should be returned with the receipt
+    (headers or full message).
+
+</itemize>
+
+Please see the reference chapter for possible values.
 
 <!--}}}--> 
 
 
 <!--}}}--> 
 
@@ -3517,7 +3542,11 @@ score !~* =42
 <p>Mutt-ng can be built using a library called ``libESMTP'' which
 provides SMTP functionality. When <tt/configure/ was called with
 <tt/--with-libesmtp/ or the output <tt>muttng -v</tt> contains
 <p>Mutt-ng can be built using a library called ``libESMTP'' which
 provides SMTP functionality. When <tt/configure/ was called with
 <tt/--with-libesmtp/ or the output <tt>muttng -v</tt> contains
-<tt>+USE_LIBESMTP</tt>, this will be or is the case already.
+<tt>+USE_LIBESMTP</tt>, this will be or is the case already. The SMTP
+support includes support for Delivery Status Notification (see <ref
+id="dsn" name="Delivery Status Notification"> section) as well as
+handling the <tt/8BITMIME/ flag controlled via <ref id="use_8bitmime"
+name="&dollar;use&lowbar;8bitmime">.
 
 <p>To enable sending mail directly via SMTP without an MTA such as
 Postfix or SSMTP and the like, simply set the <ref id="smtp_host"
 
 <p>To enable sending mail directly via SMTP without an MTA such as
 Postfix or SSMTP and the like, simply set the <ref id="smtp_host"
@@ -3536,6 +3565,12 @@ the server supports it: for the second case, the connection will fail if
 it doesn't while switching back to unencrypted communication for the
 first one.
 
 it doesn't while switching back to unencrypted communication for the
 first one.
 
+<p>Some mail providers require user's to set a particular envelope
+sender, i.e. they allow for only one value which may not be what the
+user wants to send as the <tt/From:/ header. In this case, the variable
+<ref id="smtp_envelope" name="&dollar;smtp&lowbar;envelope"> may be used
+to set the envelope different from the <tt/From:/ header.
+
 <!-- }}} -->
 
 <sect>Managing multiple IMAP/POP/NNTP accounts (OPTIONAL)<label id="account-hook"> <!--{{{--> 
 <!-- }}} -->
 
 <sect>Managing multiple IMAP/POP/NNTP accounts (OPTIONAL)<label id="account-hook"> <!--{{{--> 
@@ -4263,6 +4298,161 @@ muttrc.
 
 <!--}}}--> 
 
 
 <!--}}}--> 
 
+<chapt>Security Considerations <!--{{{--> 
+
+  <p>First of all, mutt-ng contains no security holes included by
+  intention but may contain unknown security holes. As a consequence,
+  please run mutt-ng only with as few permissions as possible.
+
+  <p>Please do not run mutt-ng as the super user.
+
+  <p>When configuring mutt-ng, there're some points to note about secure
+  setups.
+
+  <p>In practice, mutt-ng can be easily made as vulnerable as even the
+  most insecure mail user agents (in their default configuration) just
+  by changing mutt-ng's configuration files: it then can execute
+  arbitrary programs and scripts attached to messages, send out private
+  data on its own, etc. Although this is not believed to the common type
+  of setup, please read this chapter carefully.
+
+  <sect>Passwords <!--{{{--> 
+
+    <p>Although mutt-ng can be told the various passwords for accounts,
+    please never store passwords in configuration files. Besides the
+    fact that the system's operator can always read them, you could
+    forget to replace the actual password with asterisks when reporting
+    a bug or asking for help via, for example, a mailing list so that
+    your mail including your password could be archived by internet
+    search engines, etc. Please never store passwords on disk.
+
+  <!--}}}-->
+
+  <sect>Temporary Files <!--{{{--> 
+
+    <p>Mutt-ng uses many temporary files for viewing messages, verifying
+    digital signatures, etc. The <ref id="umask" name="&dollar;umask">
+    variable can be used to change the default permissions of these
+    files. Please only change it if you really know what you are doing.
+    Also, a different location for these files may be desired which can
+    be changed via the <ref id="tmpdir" name="&dollar;tmpdir"> variable.
+
+  <!--}}}-->
+
+  <sect>Information Leaks <!--{{{--> 
+
+  <sect1>Message-ID: headers <!--{{{--> 
+
+    <p>In the default configuration, mutt-ng will leak some information
+    to the outside world when sending messages: the generation of
+    <tt/Message-ID:/ headers includes a step counter which is increased
+    (and rotated) with every message sent. If you'd like to hide this
+    information probably telling others how many mail you sent in which
+    time, you at least need to remove the <tt/%P/ expando from the
+    default setting of the <ref id="msgid_format"
+    name="&dollar;msgid&lowbar;format"> variable. Please make sure that
+    you really know how local parts of these <tt/Message-ID:/ headers
+    are composed.
+
+  <!--}}}-->
+
+  <sect1>mailto:-style links <!--{{{--> 
+
+    <p>As mutt-ng be can be set up to be the mail client to handle
+    <tt/mailto:/ style links in websites, there're security
+    considerations, too. To keep the old behavior by default, mutt-ng
+    will be strict in interpreting them which means that arbitrary
+    header fields can be embedded in these links which could override
+    existing header fields or attach arbitrary files. This may be
+    problematic if the <ref id="edit_headers"
+    name="&dollar;edit&lowbar;headers"> variable is <em/unset/, i.e. the
+    user doesn't want to see header fields while editing the message.
+
+    <p>For example, following a link like
+
+    <verb>
+mailto:joe@host?Attach=~/.gnupg/secring.gpg</verb>
+
+    will send out the user's private gnupg keyring to <tt/joe@host/ if
+    the user doesn't follow the information on screen carefully
+    enough.
+
+    <p>When <em/unsetting/ the <ref id="strict_mailto"
+    name="&dollar;strict&lowbar;mailto"> variable, mutt-ng will
+
+    <itemize>
+
+      <item>be less strict when interpreting these links by
+        prepending a <tt/X-Mailto-/ string to all header fields
+        embedded in such a link <em/and/
+
+      <item>turn on the <ref id="edit_headers"
+        name="&dollar;edit&lowbar;headers"> variable by
+        force to let the user see all the headers
+        (because they still may leak information.)
+
+    </itemize>
+
+  <!--}}}-->
+
+  <!--}}}-->
+
+  <sect>External applications <!--{{{--> 
+
+    <p>Mutt-ng in many places has to rely on external applications or
+    for convenience supports mechanisms involving external
+    applications.
+
+    <sect1>mailcap <!--{{{--> 
+
+      <p>One of these is the <tt/mailcap/ mechanism as defined by RfC
+      1524. Mutt-ng can be set up to <em/automatically/ execute any
+      given utility as listed in one of the mailcap files (see the
+      <ref id="mailcap_path" name="&dollar;mailcap&lowbar;path">
+      variable for details.) These utilities may have security issues
+      like overriding arbitrary files, contain exploitable bugs or just
+      leak information which is a bad in combination with running them
+      without prompting. When using mutt-ng's autoview mechanism
+      involing use of mailcap files, please make sure that
+
+      <itemize>
+
+        <item>you manually select trustworthy applications with a
+          reasonable calling sequence
+
+        <item>you check the contents of mailcap files from time to time
+          (for example after doing software installations/upgrades)
+
+        <item>you, if you're the system's operator, always keep the
+          software packages involved up-to-date
+
+        <item>you never ever change the default value of the
+          <ref id="mailcap_sanitize"
+          name="&dollar;mailcap&lowbar;sanitize"> variable
+
+      </itemize>
+
+    <!--}}}-->
+
+    <sect1>Other <!--{{{--> 
+
+      <p>Besides the mailcap mechanism, mutt-ng uses a number of other
+      external utilities for operation.
+
+      <p>The same security considerations apply for these as for tools
+      involved via mailcap (for example, mutt-ng is vulnerable to Denial
+      of Service Attacks with compressed folders support if the
+      uncompressed mailbox is too large for the disk it is saved to.)
+
+      <p>As already noted, most of these problems are not built in but
+      caused by wrong configuration, so please check your configuration.
+
+    <!--}}}-->
+
+  <!--}}}-->
+
+<!--}}}-->
+
 <chapt>Reference <!--{{{--> 
 
 <sect>Command line options<label id="commandline"> <!--{{{--> 
 <chapt>Reference <!--{{{--> 
 
 <sect>Command line options<label id="commandline"> <!--{{{--> 
@@ -4497,5 +4687,60 @@ The following are the commands understood by mutt.
 </itemize>
 
 <sect>Configuration variables<label id="variables">
 </itemize>
 
 <sect>Configuration variables<label id="variables">
+
+<p>The following list contains all variables which, in the process of
+providing more consistency, have been renamed and are partially even
+removed already. The left column contains the old synonym variables,
+the right column the full/new name:
+
+<label id="sect_obsolete">
+<tscreen><verb>
+edit_hdrs               edit_headers
+forw_decode             forward_decode
+forw_format             forward_format
+forw_quote              forward_quote
+hdr_format              index_format
+indent_str              indent_string
+mime_fwd                mime_forward
+msg_format              message_format
+pgp_autosign            crypt_autosign
+pgp_autoencrypt         crypt_autoencrypt
+pgp_replyencrypt        crypt_replyencrypt
+pgp_replysign           crypt_replysign
+pgp_replysignencrypted  crypt_replysignencrypted
+pgp_verify_sig          crypt_verify_sig
+pgp_create_traditional  pgp_autoinline
+pgp_auto_traditional    pgp_replyinline
+forw_decrypt            forward_decrypt
+smime_sign_as           smime_default_key
+post_indent_str         post_indent_string
+print_cmd               print_command
+shorten_hierarchy       sidebar_shorten_hierarchy
+ask_followup_to         nntp_ask_followup_to
+ask_x_comment_to        nntp_ask_x_comment_to
+catchup_newsgroup       nntp_catchup
+followup_to_poster      nntp_followup_to_poster
+group_index_format      nntp_group_index_format
+inews                   nntp_inews
+mime_subject            nntp_mime_subject
+news_cache_dir          nntp_cache_dir
+news_server             nntp_host
+newsrc                  nntp_newsrc
+nntp_poll               nntp_mail_check
+pop_checkinterval       pop_mail_check
+post_moderated          nntp_post_moderated
+save_unsubscribed       nntp_save_unsubscribed
+show_new_news           nntp_show_new_news
+show_only_unread        nntp_show_only_unread
+x_comment_to            nntp_x_comment_to
+smtp_auth_username      smtp_user
+smtp_auth_password      smtp_pass
+</verb></tscreen>
+
+The <tt/contrib/ subdirectory contains a script named
+<tt/update-config.pl/ which eases migration.
+
+A complete list of current variables follows.
+
 <p>
 
 <p>