+@node IDNA
+@section IDNA
+@cindex IDNA
+@cindex internationalized domain names
+@cindex non-ascii domain names
+
+Message is a @acronym{IDNA}-compliant posting agent. The user
+generally doesn't have to do anything to make the @acronym{IDNA}
+happen---Message will encode non-@acronym{ASCII} domain names in @code{From},
+@code{To}, and @code{Cc} headers automatically.
+
+Until @acronym{IDNA} becomes more well known, Message queries you
+whether @acronym{IDNA} encoding of the domain name really should
+occur. Some users might not be aware that domain names can contain
+non-@acronym{ASCII} now, so this gives them a safety net if they accidently
+typed a non-@acronym{ASCII} domain name.
+
+@vindex message-use-idna
+The @code{message-use-idna} variable control whether @acronym{IDNA} is
+used. If the variable is @code{nil} no @acronym{IDNA} encoding will
+ever happen, if it is set to the symbol @code{ask} the user will be
+queried (the default), and if set to @code{t} @acronym{IDNA} encoding
+happens automatically.
+
+@findex message-idna-to-ascii-rhs
+If you want to experiment with the @acronym{IDNA} encoding, you can
+invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer
+to have the non-@acronym{ASCII} domain names encoded while you edit the message.
+
+Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU
+Libidn} installed in order to use this functionality.
+
+@node Security
+@section Security
+@cindex Security
+@cindex S/MIME
+@cindex PGP
+@cindex PGP/MIME
+@cindex sign
+@cindex encrypt
+@cindex secure
+
+Using the MML language, Message is able to create digitally signed and
+digitally encrypted messages. Message (or rather MML) currently
+support @acronym{PGP} (RFC 1991), @acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}.
+Instructing MML to perform security operations on a @acronym{MIME} part is
+done using the @kbd{C-c C-m s} key map for signing and the @kbd{C-c
+C-m c} key map for encryption, as follows.
+
+@table @kbd
+
+@item C-c C-m s s
+@kindex C-c C-m s s
+@findex mml-secure-message-sign-smime
+
+Digitally sign current message using @acronym{S/MIME}.
+
+@item C-c C-m s o
+@kindex C-c C-m s o
+@findex mml-secure-message-sign-pgp
+
+Digitally sign current message using @acronym{PGP}.
+
+@item C-c C-m s p
+@kindex C-c C-m s p
+@findex mml-secure-message-sign-pgpmime
+
+Digitally sign current message using @acronym{PGP/MIME}.
+
+@item C-c C-m c s
+@kindex C-c C-m c s
+@findex mml-secure-message-encrypt-smime
+
+Digitally encrypt current message using @acronym{S/MIME}.
+
+@item C-c C-m c o
+@kindex C-c C-m c o
+@findex mml-secure-message-encrypt-pgp
+
+Digitally encrypt current message using @acronym{PGP}.
+
+@item C-c C-m c p
+@kindex C-c C-m c p
+@findex mml-secure-message-encrypt-pgpmime
+
+Digitally encrypt current message using @acronym{PGP/MIME}.
+
+@item C-c C-m C-n
+@kindex C-c C-m C-n
+@findex mml-unsecure-message
+Remove security related MML tags from message.
+
+@end table
+
+These commands do not immediately sign or encrypt the message, they
+merely insert the proper MML secure tag to instruct the MML engine to
+perform that operation when the message is actually sent. They may
+perform other operations too, such as locating and retrieving a
+@acronym{S/MIME} certificate of the person you wish to send encrypted mail
+to. When the mml parsing engine converts your MML into a properly
+encoded @acronym{MIME} message, the secure tag will be replaced with either
+a part or a multipart tag. If your message contains other mml parts,
+a multipart tag will be used; if no other parts are present in your
+message a single part tag will be used. This way, message mode will
+do the Right Thing (TM) with signed/encrypted multipart messages.
+
+@vindex mml-signencrypt-style-alist
+By default, when encrypting a message, Gnus will use the ``signencrypt''
+mode. If you would like to disable this for a particular message,
+give the @code{mml-secure-message-encrypt-*} command a prefix argument. (for
+example, @kbd{C-u C-c C-m c p}). Additionally, by default Gnus will
+separately sign, then encrypt a message which has the mode
+signencrypt. If you would like to change this behavior you can
+customize the @code{mml-signencrypt-style-alist} variable. For
+example:
+
+
+@lisp
+(setq mml-signencrypt-style-alist '(("smime" combined)
+ ("pgp" combined)
+ ("pgpmime" combined)))
+@end lisp
+
+Will cause Gnus to sign and encrypt in one pass, thus generating a
+single signed and encrypted part. Note that combined sign and encrypt
+does not work with all supported OpenPGP implementations (in
+particular, @acronym{PGP} version 2 do not support this).
+
+Since signing and especially encryption often is used when sensitive
+information is sent, you may want to have some way to ensure that your
+mail is actually signed or encrypted. After invoking the above
+sign/encrypt commands, it is possible to preview the raw article by
+using @kbd{C-u C-c RET P} (@code{mml-preview}). Then you can
+verify that your long rant about what your ex-significant other or
+whomever actually did with that funny looking person at that strange
+party the other night, actually will be sent encrypted.
+
+@emph{Note!} Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs
+RFC822 headers. They only operate on the @acronym{MIME} object. Keep this
+in mind before sending mail with a sensitive Subject line.
+
+Actually using the security commands above is not very difficult. At
+least not compared with making sure all involved programs talk with each
+other properly. Thus, we now describe what external libraries or
+programs are required to make things work, and some small general hints.
+
+@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.
+
+The @acronym{S/MIME} support in Message (and MML) require OpenSSL. OpenSSL
+perform 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 @acronym{MIME}
+separators so you may wish to avoid it if you would like to avoid
+being regarded as someone who send strange mail. (Although by sending
+@acronym{S/MIME} messages you've probably already lost that contest.)
+
+To be able to send encrypted mail, a personal certificate is not
+required. Message (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
+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,
+Message (MML) is the first mail agent in the world to support
+retrieving @acronym{S/MIME} certificates from DNS, so you're not
+likely to find very many certificates out there. At least there
+should be one, stored at the domain @code{simon.josefsson.org}. LDAP
+is a more popular method of distributing certificates, support for it
+is planned. (Meanwhile, you can use @code{ldapsearch} from the
+command line to retrieve a certificate into a file and use it.)
+
+As for signing messages, OpenSSL can't perform signing operations
+without some kind of configuration. Especially, you need to tell it
+where your private key and your certificate is stored. MML uses an
+Emacs interface to OpenSSL, aptly named @code{smime.el}, and it
+contain a @code{custom} group used for this configuration. So, try
+@kbd{M-x customize-group RET smime RET} and look around.
+
+Currently there is no support for talking to a CA (or RA) to create
+your own certificate. None is planned either. You need to do this
+manually with OpenSSL or using some other program. I used Netscape
+and got a free @acronym{S/MIME} certificate from one of the big CA's on the
+net. Netscape is able to export your private key and certificate in
+PKCS #12 format. Use OpenSSL to convert this into a plain X.509
+certificate in PEM format as follows.
+
+@example
+$ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem
+@end example
+
+The @file{key+cert.pem} file should be pointed to from the
+@code{smime-keys} variable. You should now be able to send signed mail.
+
+@emph{Note!} Your private key is stored unencrypted in the file, so take
+care in handling it.
+
+@subsection Using PGP/MIME
+
+@acronym{PGP/MIME} requires an external OpenPGP implementation, such
+as @uref{http://www.gnupg.org/, GNU Privacy Guard}. One Emacs
+interface to OpenPGP implementations, PGG (@pxref{Top, ,PGG, pgg, PGG
+Manual}), is included, but Mailcrypt and Florian Weimer's
+@code{gpg.el} are also supported.
+
+@vindex gpg-temp-directory
+Note, if you are using the @code{gpg.el} you must make sure that the
+directory specified by @code{gpg-temp-directory} have permissions
+0700.
+
+Creating your own OpenPGP key is described in detail in the
+documentation of your OpenPGP implementation, so we refer to it.