@include gnus-overrides.texi
-@setfilename message
+@setfilename message.info
@settitle Message Manual
+@include docstyle.texi
@synindex fn cp
@synindex vr cp
@synindex pg cp
@copying
This file documents Message, the Emacs message composition mode.
-Copyright @copyright{} 1996-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1996--2016 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
@c Adjust ../Makefile.in if you change the following lines:
Message is distributed with Gnus. The Gnus distribution
@c
-corresponding to this manual is Ma Gnus v0.2
+corresponding to this manual is Ma Gnus v0.14
@node Interface
the normal methods for determining the To header will be used.
Each list element should be a cons, where the @sc{car} should be the
-name of a header (e.g. @code{Cc}) and the @sc{cdr} should be the header
-value (e.g. @samp{larsi@@ifi.uio.no}). All these headers will be
+name of a header (e.g., @code{Cc}) and the @sc{cdr} should be the header
+value (e.g., @samp{larsi@@ifi.uio.no}). All these headers will be
inserted into the head of the outgoing mail.
@table @code
@item message-forward-ignored-headers
@vindex message-forward-ignored-headers
-All headers that match this regexp will be deleted when forwarding a message.
+In non-@code{nil}, all headers that match this regexp will be deleted
+when forwarding a message.
+
+@item message-forward-included-headers
+@vindex message-forward-included-headers
+In non-@code{nil}, only headers that match this regexp will be kept
+when forwarding a message.
@item message-make-forward-subject-function
@vindex message-make-forward-subject-function
@end itemize
-Gnus honors the MFT header in other's messages (i.e. while following
+Gnus honors the MFT header in other's messages (i.e., while following
up to someone else's post) and also provides support for generating
sensible MFT headers for outgoing messages as well.
Now you are all set. Just start composing a message as you normally do.
And just send it; as always. Just before the message is sent out, Gnus'
MFT generation thingy kicks in and checks if the message already has a
-MFT field. If there is one, it is left alone. (Except if it's empty -
+MFT field. If there is one, it is left alone. (Except if it's empty;
in that case, the field is removed and is not replaced with an
automatically generated one. This lets you disable MFT generation on a
per-message basis.) If there is none, then the list of recipient
@item C-c C-f t
@kindex C-c C-f t
@findex message-reduce-to-to-cc
-Replace contents of @samp{To} header with contents of @samp{Cc} or
-@samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc}
-header will be used instead.)
+Replace contents of @samp{To} header with contents of @samp{Cc}
+header (or the @samp{Bcc} header, if there is no @samp{Cc} header).
@item C-c C-f w
@kindex C-c C-f w
@cindex encrypt
@cindex secure
-Using the @acronym{MML} language, Message is able to create digitally
-signed and digitally encrypted messages. Message (or rather
-@acronym{MML}) currently support @acronym{PGP} (RFC 1991),
-@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}.
+By default, e-mails are transmitted without any protection around the
+Internet, which implies that they can be read and changed by lots of
+different parties. In particular, they are analyzed under bulk
+surveillance, which violates basic human rights. To defend those
+rights, digital self-defense is necessary (in addition to legal
+changes), and encryption and digital signatures are powerful
+techniques for self-defense. In essence, encryption ensures that
+only the intended recipient will be able to read a message, while
+digital signatures make sure that modifications to messages can be
+detected by the recipient.
+
+Nowadays, there are two major incompatible e-mail encryption
+standards, namely @acronym{OpenPGP} and @acronym{S/MIME}. Both of
+these standards are implemented by the @uref{https://www.gnupg.org/,
+GNU Privacy Guard (GnuPG)}, which needs to be installed as external
+software in addition to GNU Emacs. Before you can start to encrypt,
+decrypt, and sign messages, you need to create a so-called key-pair,
+which consists of a private key and a public key. Your @emph{public} key
+(also known as @emph{certificate}, in particular with @acronym{S/MIME}), is
+used by others (a) to encrypt messages intended for you and (b) to verify
+digital signatures created by you. In contrast, you use your @emph{private}
+key (a) to decrypt messages and (b) to sign messages. (You may want to
+think of your public key as an open safe that you offer to others such
+that they can deposit messages and lock the door, while your private
+key corresponds to the opening combination for the safe.)
+
+Thus, you need to perform the following steps for e-mail encryption,
+typically outside Emacs. See, for example, the
+@uref{https://www.gnupg.org/gph/en/manual.html, The GNU Privacy
+Handbook} for details covering the standard @acronym{OpenPGP} with
+@acronym{GnuPG}.
+@enumerate
+@item
+Install GnuPG.
+@item
+Create a key-pair for your own e-mail address.
+@item
+Distribute your public key, e.g., via upload to key servers.
+@item
+Import the public keys for the recipients to which you want to send
+encrypted e-mails.
+@end enumerate
+
+Whether to use the standard @acronym{OpenPGP} or @acronym{S/MIME} is
+beyond the scope of this documentation. Actually, you can use one
+standard for one set of recipients and the other standard for
+different recipients (depending their preferences or capabilities).
+
+In case you are not familiar with all those acronyms: The standard
+@acronym{OpenPGP} is also called @acronym{PGP} (Pretty Good Privacy).
+The command line tools offered by @acronym{GnuPG} for
+@acronym{OpenPGP} are called @command{gpg} and @command{gpg2}, while
+the one for @acronym{S/MIME} is called @command{gpgsm}. An
+alternative, but discouraged, tool for @acronym{S/MIME} is
+@command{openssl}. To make matters worse, e-mail messages can be
+formed in two different ways with @acronym{OpenPGP}, namely
+@acronym{PGP} (RFC 1991/4880) and @acronym{PGP/MIME} (RFC 2015/3156).
+
+The good news, however, is the following: In GNU Emacs, Message
+supports all those variants, comes with reasonable defaults that can
+be customized according to your needs, and invokes the proper command
+line tools behind the scenes for encryption, decryption, as well as
+creation and verification of digital signatures.
+
+Message uses the @acronym{MML} language for the creation of signed
+and/or encrypted messages as explained in the following.
+
@menu
* Signing and encryption:: Signing and encrypting commands.
* Using S/MIME:: Using S/MIME
-* Using PGP/MIME:: Using PGP/MIME
+* Using OpenPGP:: Using OpenPGP
+* Passphrase caching:: How to cache passphrases
* PGP Compatibility:: Compatibility with older implementations
+* Encrypt-to-self:: Reading your own encrypted messages
+* Bcc Warning:: Do not use encryption with Bcc headers
@end menu
@node Signing and encryption
@node Using S/MIME
@subsection Using S/MIME
-@emph{Note!} This section assume you have a basic familiarity with
-modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and
-so on.
+@acronym{S/MIME} requires an external implementation, such as
+@uref{https://www.gnupg.org/, GNU Privacy Guard} or
+@uref{https://www.openssl.org/, OpenSSL}. The default Emacs interface
+to the S/MIME implementation is EasyPG (@pxref{Top,,EasyPG Assistant
+User's Manual, epa, EasyPG Assistant User's Manual}), which has been
+included in Emacs since version 23 and which relies on the command
+line tool @command{gpgsm} provided by @acronym{GnuPG}. That tool
+implements certificate management, including certificate revocation
+and expiry, while such tasks need to be performed manually, if OpenSSL
+is used.
+
+The choice between EasyPG and OpenSSL is controlled by the variable
+@code{mml-smime-use}, which needs to be set to the value @code{epg}
+for EasyPG. Depending on your version of Emacs that value may be the
+default; if not, you can either customize that variable or place the
+following line in your @file{.emacs} file (that line needs to be
+placed above other code related to message/gnus/encryption):
+
+@lisp
+(require 'epg)
+@end lisp
+
+Moreover, you may want to customize the variables
+@code{mml-default-encrypt-method} and
+@code{mml-default-sign-method} to the string @code{"smime"}.
+
+That's all if you want to use S/MIME with EasyPG, and that's the
+recommended way of using S/MIME with Message.
-The @acronym{S/MIME} support in Message (and @acronym{MML}) require
-OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt
+If you think about using OpenSSL instead of EasyPG, please read the
+BUGS section in the manual for the @command{smime} command coming with
+OpenSSL first. If you still want to use OpenSSL, the following
+applies.
+
+@emph{Note!} The remainder of this section assumes you have a basic
+familiarity with modern cryptography, @acronym{S/MIME}, various PKCS
+standards, OpenSSL and so on.
+
+The @acronym{S/MIME} support in Message (and @acronym{MML}) can use
+OpenSSL@. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt
operations. OpenSSL can be found at @uref{http://www.openssl.org/}.
OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail
addresses from certificates, and it insert a spurious CR character into
required. Message (@acronym{MML}) need a certificate for the person to whom you
wish to communicate with though. You're asked for this when you type
@kbd{C-c C-m c s}. Currently there are two ways to retrieve this
-certificate, from a local file or from DNS. If you chose a local
+certificate, from a local file or from DNS@. If you chose a local
file, it need to contain a X.509 certificate in @acronym{PEM} format.
If you chose DNS, you're asked for the domain name where the
certificate is stored, the default is a good guess. To my belief,
@emph{Note!} Your private key is now stored unencrypted in the file,
so take care in handling it. Storing encrypted keys on the disk are
supported, and Gnus will ask you for a passphrase before invoking
-OpenSSL. Read the OpenSSL documentation for how to achieve this. If
+OpenSSL@. Read the OpenSSL documentation for how to achieve this. If
you use unencrypted keys (e.g., if they are on a secure storage, or if
you are on a secure single user machine) simply press @code{RET} at
the passphrase prompt.
-@node Using PGP/MIME
-@subsection Using PGP/MIME
+@node Using OpenPGP
+@subsection Using OpenPGP
+
+Use of OpenPGP requires an external software, such
+as @uref{https://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
+implementations such as PGP 2.x and PGP 5.x are also supported. The
+default Emacs interface to the PGP implementation is EasyPG
+(@pxref{Top,,EasyPG Assistant User's Manual, epa, EasyPG Assistant
+User's Manual}), but PGG (@pxref{Top, ,PGG, pgg, PGG Manual}) and
+Mailcrypt are also supported. @xref{PGP Compatibility}.
-@acronym{PGP/MIME} requires an external OpenPGP implementation, such
-as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP
-implementations such as PGP 2.x and PGP 5.x are also supported. One
-Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG,
-pgg, PGG Manual}), is included, but Mailcrypt is also supported.
-@xref{PGP Compatibility}.
+As stated earlier, messages encrypted with OpenPGP can be formatted
+according to two different standards, namely @acronym{PGP} or
+@acronym{PGP/MIME}. The variables
+@code{mml-default-encrypt-method} and
+@code{mml-default-sign-method} determine which variant to prefer,
+@acronym{PGP/MIME} by default.
+
+@node Passphrase caching
+@subsection Passphrase caching
@cindex gpg-agent
-Message internally calls GnuPG (the @command{gpg} command) to perform
+Message with EasyPG internally calls GnuPG (the @command{gpg} or
+@command{gpgsm} command) to perform
data encryption, and in certain cases (decrypting or signing for
-example), @command{gpg} requires user's passphrase. Currently the
-recommended way to supply your passphrase to @command{gpg} is to use the
+example), @command{gpg}/@command{gpgsm} requires user's passphrase.
+Currently the recommended way to supply your passphrase is to use the
@command{gpg-agent} program.
-To use @command{gpg-agent} in Emacs, you need to run the following
-command from the shell before starting Emacs.
+In particular, the @command{gpg-agent} program supports passphrase
+caching so that you do not need to enter your passphrase for every
+decryption/sign operation. @xref{Agent Options, , , gnupg, Using the
+GNU Privacy Guard}.
+
+How to use @command{gpg-agent} in Emacs depends on your version of
+GnuPG. With GnuPG version 2.1, @command{gpg-agent} is started
+automatically if necessary. With older versions you may need to run
+the following command from the shell before starting Emacs.
@example
eval `gpg-agent --daemon`
Once your @command{gpg-agent} is set up, it will ask you for a
passphrase as needed for @command{gpg}. Under the X Window System,
you will see a new passphrase input dialog appear. The dialog is
-provided by PIN Entry (the @command{pinentry} command), and as of
-version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a
-single tty. So, if you are using a text console, you may need to put
-a passphrase into gpg-agent's cache beforehand. The following command
-does the trick.
+provided by PIN Entry (the @command{pinentry} command), reasonably
+recent versions of which can also cooperate with Emacs on a text
+console. If that does not work, you may need to put a passphrase into
+gpg-agent's cache beforehand. The following command does the trick.
@example
gpg --use-agent --sign < /dev/null > /dev/null
@end example
-The Lisp variable @code{pgg-gpg-use-agent} controls whether to use
-@command{gpg-agent}. See also @xref{Caching passphrase, , , pgg, The
-PGG Manual}.
-
-
@node PGP Compatibility
@subsection Compatibility with older implementations
If you have imported your old PGP 2.x key into GnuPG, and want to send
signed and encrypted messages to your fellow PGP 2.x users, you'll
discover that the receiver cannot understand what you send. One
-solution is to use PGP 2.x instead (i.e., if you use @code{pgg}, set
+solution is to use PGP 2.x instead (e.g., if you use @code{pgg}, set
@code{pgg-default-scheme} to @code{pgp}). You could also convince your
-fellow PGP 2.x users to convert to GnuPG.
+fellow PGP 2.x users to convert to GnuPG@.
@vindex mml-signencrypt-style-alist
As a final workaround, you can make the sign and encryption work in
two steps; separately sign, then encrypt a message. If you would like
(Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more
information about the problem.)
+@node Encrypt-to-self
+@subsection Encrypt-to-self
+
+By default, messages are encrypted to all recipients (@code{To},
+@code{Cc}, @code{Bcc} headers). Thus, you will not be able to decrypt
+your own messages. To make sure that messages are also encrypted to
+your own key(s), several alternative solutions exist:
+@enumerate
+@item
+Use the @code{encrypt-to} option in the file @file{gpg.conf} (for
+OpenPGP) or @file{gpgsm.conf} (for @acronym{S/MIME} with EasyPG).
+@xref{Invoking GPG, , , gnupg, Using the GNU Privacy Guard}, or
+@xref{Invoking GPGSM, , , gnupg, Using the GNU Privacy Guard}.
+@item
+Include your own e-mail address (for which you created a key-pair)
+among the recipients.
+@item
+Customize the variable @code{mml-secure-openpgp-encrypt-to-self} (for
+OpenPGP) or @code{mml-secure-smime-encrypt-to-self} (for
+@acronym{S/MIME} with EasyPG).
+@end enumerate
+
+@node Bcc Warning
+@subsection Bcc Warning
+
+The @code{Bcc} header is meant to hide recipients of messages.
+However, when encrypted messages are used, the e-mail addresses of all
+@code{Bcc}-headers are given away to all recipients without
+warning, which is a bug, see
+@uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=18718}.
+
+
@node Various Commands
@section Various Commands
Headers in this list that were previously generated by Message will be
deleted before posting. Let's say you post an article. Then you decide
to post it again to some other group, you naughty boy, so you jump back
-to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and
+to the @file{*post-buf*} buffer, edit the @code{Newsgroups} line, and
ship it off again. By default, this variable makes sure that the old
generated @code{Message-ID} is deleted, and a new one generated. If
this isn't done, the entire empire would probably crumble, anarchy would
requires the @acronym{POP}-before-@acronym{SMTP} authentication.
@xref{POP before SMTP, , POP before SMTP, gnus, The Gnus Manual}.
+@cindex X-Message-SMTP-Method
+If you have a complex @acronym{SMTP} setup, and want some messages to
+go via one mail server, and other messages to go through another, you
+can use the @samp{X-Message-SMTP-Method} header. These are the
+supported values:
+
+@table @samp
+@item smtpmail
+
+@example
+X-Message-SMTP-Method: smtp smtp.fsf.org 587
+@end example
+
+This will send the message via @samp{smtp.fsf.org}, using port 587.
+
+@example
+X-Message-SMTP-Method: smtp smtp.fsf.org 587 other-user
+@end example
+
+This is the same as the above, but uses @samp{other-user} as the user
+name when authenticating. This is handy if you have several
+@acronym{SMTP} accounts on the same server.
+
+@item sendmail
+
+@example
+X-Message-SMTP-Method: sendmail
+@end example
+
+This will send the message via the locally installed sendmail/exim/etc
+installation.
+
+@end table
+
@item message-mh-deletable-headers
@vindex message-mh-deletable-headers
Most versions of MH doesn't like being fed messages that contain the
headers in this variable. If this variable is non-@code{nil} (which is
the default), these headers will be removed before mailing when sending
-messages via MH. Set it to @code{nil} if your MH can handle these
+messages via MH@. Set it to @code{nil} if your MH can handle these
headers.
@item message-qmail-inject-program
This should be a list of strings, one string for each argument. It
may also be a function.
-For e.g., if you wish to set the envelope sender address so that bounces
+E.g., if you wish to set the envelope sender address so that bounces
go to the right place or to deal with listserv's usage of that address, you
might set this variable to @code{'("-f" "you@@some.where")}.
created based on the date, time, user name (for the local part) and the
domain part. For the domain part, message will look (in this order) at
@code{message-user-fqdn}, @code{system-name}, @code{mail-host-address}
-and @code{message-user-mail-address} (i.e. @code{user-mail-address})
+and @code{message-user-mail-address} (i.e., @code{user-mail-address})
until a probably valid fully qualified domain name (FQDN) was found.
@item User-Agent
unlikely that you should need to fiddle with this variable at all.
@end table
-@findex yow
@cindex Mime-Version
In addition, you can enter conses into this list. The @sc{car} of this cons
should be a symbol. This symbol's name is the name of the header, and
the @sc{cdr} can either be a string to be entered verbatim as the value of
this header, or it can be a function to be called. This function should
-return a string to be inserted. For instance, if you want to insert
-@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")}
-into the list. If you want to insert a funny quote, you could enter
-something like @code{(X-Yow . yow)} into the list. The function
-@code{yow} will then be called without any arguments.
+take no arguments, and return a string to be inserted. For
+instance, if you want to insert @code{Mime-Version: 1.0}, you should
+enter @code{(Mime-Version . "1.0")} into the list.
If the list contains a cons where the @sc{car} of the cons is
@code{optional}, the @sc{cdr} of this cons will only be inserted if it is
Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes:
@end example
-@c FIXME: Add `message-insert-formatted-citation-line' and
-@c `message-citation-line-format'
+@c FIXME: Add 'message-insert-formatted-citation-line' and
+@c 'message-citation-line-format'.
Point will be at the beginning of the body of the message when this
function is called.
-Note that Gnus provides a feature where clicking on `writes:' hides the
+Note that Gnus provides a feature where clicking on @samp{writes:} hides the
cited text. If you change the citation line too much, readers of your
messages will have to adjust their Gnus, too. See the variable
@code{gnus-cite-attribution-suffix}. @xref{Article Highlighting, ,
@vindex message-fill-column
@cindex auto-fill
Local value for the column beyond which automatic line-wrapping should
-happen for message buffers. If non-nil (the default), also turn on
+happen for message buffers. If non-@code{nil} (the default), also turn on
auto-fill in message buffers.
@item message-signature-separator
@item message-send-mail-hook
@vindex message-send-mail-hook
-Hook run before sending mail messages. This hook is run very late --
+Hook run before sending mail messages. This hook is run very late:
just before the message is actually sent as mail.
@item message-send-news-hook
@vindex message-send-news-hook
-Hook run before sending news messages. This hook is run very late --
+Hook run before sending news messages. This hook is run very late:
just before the message is actually sent as news.
@item message-sent-hook
@table @code
@item nil
Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail
-to whom*, *news on group*, etc.) and continue editing in the existing
+to whom*, *news on group*, etc.)@: and continue editing in the existing
buffer of that name. If there is no such buffer, it will be newly
created.
projects / gnus / blobdiff