MML Security docs

[Simon Josefsson <sj@extundo.com>]

New additions to message.texi follows.  I'm sure someone with
documentation skills could do wonders with it, so please suggest
improvements.  (I intend to actually read through it when I've
forgotten most of it, so I might find some problems myself.)

I decided that user oriented MML documentation should go into
message.texi, not emacs-mime.texi.

File: message,  Node: Security,  Next: Various Commands,  Prev: MIME,  Up: Commands

Security
========

   Using the MML language, Message is able to create digitally signed
and digitally encrypted messages.  Message (or rather MML) currently
support PGP/MIME and S/MIME.  Instructing MML to perform security
operations on a MIME part is done using the `M-m s' key map for signing
and the `M-m c' key map for encryption, as follows.

`M-m s s'
     Digitally sign current MIME part using S/MIME.

`M-m s p'
     Digitally sign current MIME part using PGP/MIME.

`M-m c s'
     Digitally encrypt current MIME part using S/MIME.

`M-m c p'
     Digitally encrypt current MIME part using PGP/MIME.

   These commands do not immediately sign or encrypt the message, they
merely insert proper MML tags 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 S/MIME certificate of
the person you wish to send encrypted mail to.

   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 `C-u M-m P' (`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.

   _Note!_  Neither PGP/MIME nor S/MIME encrypt/signs RFC822 headers.
They only operate on the 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.

Using S/MIME
------------

   _Note!_  This section assume you have a basic familiarity with
modern cryptography, S/MIME, various PKCS standards, OpenSSL and so on.

   The S/MIME support in Message (and MML) require OpenSSL.  OpenSSL
perform the actual S/MIME sign/encrypt operations.  OpenSSL can be found
at `http://www.openssl.org/'.  OpenSSL 0.9.5a and later should work.
However, version 0.9.5a insert a spurious CR character into 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 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
`M-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 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 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 `simon.josefsson.org'.  LDAP
is a more popular method of distributing certificates, support for it
is planned.  (Meanwhile, you can use `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 `smime.el', and it contain a
`custom' group used for this configuration.  So, try `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 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.

     $ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem

   The `key+cert.pem' file should be pointed to from the `smime-keys'
variable.  You should now be able to send signed mail.

   _Note!_  Your private key is store unencrypted in the file, so take
care in handling it.

Using PGP/MIME
--------------

   PGP/MIME require an external PGP implementation, such as GNU Privacy
Gaurd (`http://www.gnupg.org/'.  It also require a Emacs interface to
it, such as Mailcrypt (available from
`http://www.nb.net/~lbudney/linux/software/mailcrypt.html') or Florian
Weimer's `gpg.el'.

   Creating your own PGP key is described in detail in various PGP
documentation, so we refer to it.