README.SSL

                            Use SSL with PennMUSH
                           Revised: 16 May 2011


As of version 1.7.7p17, PennMUSH supports SSL connections when linked
with the OpenSSL library (http://www.openssl.org). The following
features are supported:

  * Encrypted sessions using SSLv2, SSLv3, and TLSv1 protocols
    with ephemeral Diffie-Hellman keying.
  * Authentication of the server via certificates
  * Authentication of the clients via certificates
  * Use of digest routines in the crytpo library for encrypting
    passwords and the digest() function.

As of version 1.8.4p9, OpenSSL is a required, not just optional
library.

This document explains how to use SSL with PennMUSH, and covers
the following issues:

   I. An SSL overview
   II. Compiling with OpenSSL
   III. Mush configuration overview
   IV. Installing a server certificate (required)
   V. Using client certificates for authentication (optional)
   VI. Legal issues

I. An SSL overview

  When an SSL client connects to an SSL server, it performs a
  "handshake" that looks something like this:

  Client says hello, offers a menu of cipher options
  Server says hello, selects a cipher.
  Server presents its certificate, requests a client certificate
  Client presents a certificate (or not)
  Client and server exchange cryptographic session keys

  The server is identified to the client by a certificate, an encoded
  text that gives the server's name and other attributes and is signed
  by a certifying authority (CA), like Verisign. The client checks
  that the signature is by a CA that it trusts, and may perform other
  validation on the certificate (e.g., checking that the hostname in
  the certificate matches the hostname it's trying to connect to).

  If the client chooses to present a certificate (or is required to by
  the server), the server will likewise attempt to validate it against
  its list of trusted CAs, and may perform other verification.

  Once session keys have been exchanged, the client and server can
  communicate secure from eavesdropping.

II. Compiling with OpenSSL

II.a. What to install

  The configure script distributed with PennMUSH automatically detects
  the OpenSSL libraries (libssl and libcrypto) and sets up the proper
  compiler flags to use them. 

  You can compile the OpenSSL libraries yourself from source code at
  http://www.openssl.org. If you install it through your operating
  system's package management system, you need shared libraries and
  development headers. (Packages with names like openssl, libssl, and
  -dev or -shlibs suffixes are common. Exact names vary from OS to
  OS. You want at least verison 0.9.7.) If OpenSSL gets installed in a
  place that isn't checked by default, you can invoke configure with
  ./configure --with-ssl=/path/to (The path must be the root directory
  of where OpenSSL's include/ and lib/ directories are.)

  OpenSSL can also be compiled on Windows, and you could add its
  libraries to the PennMUSH project file and link it in that way.
  Noltar has done this succesfully; it requires compiling both OpenSSL
  and PennMUSH in /MD (multithread dll) mode.

II.b Persistent SSL connections

  Normally, encrypted connections will be booted when a running game
  restarts, because the internal OpenSSL state cannot be saved to disc
  and restored later. To allow persistant ssl connections via a proxy
  process, pass --enable-ssl_slave to configure when you run it. This
  is experimental code (And thus not enabled by default) and does not
  work on Windows.

  It requires the libevent 2.X library and headers to be
  installed. Get it through your OS's package system or at
  http://monkey.org/~provos/libevent/ . Note that some popular OSes
  only seem to have packages for an older 1.X release of libevent (As
  of p5, Debian and derived distributions like Ubuntu, possibly
  others). You'll have to install libevent2 from source if that's the
  case, and make sure the obsolete native package is removed to avoid
  conflicts.
 
  To use the ssl slave, a full @shutdown and restart of the mush has
  to take place after the mush source has been configured to enable
  it, and compiled. Then players can connect via SSL capable clients
  exactly as they did before, with the only change being that they
  won't get booted on a @shutdown/reboot. It's transparent to the
  player and the game.

  Once the ssl slave proxy becomes more widely tested and debugged, it
  will be enabled by default.

III. Mush configuration overview

  mush.cnf includes five directives that configure the SSL support:

  ssl_port selects the port number for the MUSH to listen for SSL
  connections. Any port number other than the MUSH's ordinary
  listening port can be chosen (subject, of course, to other system
  restrictions on choosing port numbers).

  If left blank, SSL connections will not be enabled. However, other
  parts of the mush, such as the digest() softcode function, and
  password encryption, will still use OpenSSL library routines.

  ssl_private_key_file specifies the name of the file (relative to the
  game/ directory if it's not an absolute path) that contains the MUSH
  server's certificate and private key. See section IV below.

  ssl_ca_file specifies the name of the file that contains
  certificates of trusted certificate authorities. OpenSSL distributes
  a file containing the best known CAs that is suitable for use here.
  If you comment this out, client certificate checking will not be
  performed.

  ssl_require_client_cert is a boolean option that controls whether
  the MUSH server will require clients to present valid (that is,
  signed by a CA for which ssl_ca_file holds a certificate)
  certificates in order to connect. As no mud clients currently do
  this, you probably want it off. See section V below.

  socket_file is the path to a file to use as a unix domain socket
  used for talking to the optional SSL connection proxy.

IV. Installing a server certificate

  SSL support requires that the MUSH present a server certificate
  (except as discussed below).  You must create a file containing the
  certificate and the associated private key (stripped of any
  passphrase protection) and point the ssl_private_key_file directive
  at this file. This file should only be readable by the MUSH account!

  How do you get such a certificate and private key? Here are the
  steps you can use with openssl's command-line tool:

  1. Generate a certificate signing request (mymush.csr) and a private
     key (temp.key). You will be asked to answer several questions.
     Be sure the Common Name you request is your MUSH's hostname:

     $ openssl req -new -out mymush.csr -keyout temp.key -passin pass:foobar

  2. Strip the passphrase off of your private key, leaving you with an
     unpassworded mymush.key file:
 
     $ openssl rsa -in temp.key -out mymush.key -passin pass:foobar
     $ rm temp.key

  3. Send the certificate signing request to a certifying authority to
     have it signed. If the CA needs the private key, send the
     passphrased one. The CA will send you back a certificate which
     you save to a file (mymush.crt)

  4. Concatenate the certificate with the unpassworded private key and
     use this as the ssl_private_key_file:

     $ cat mymush.key >> mymush.crt

  Commercial CAs like Verisign sign certificates for a yearly or
  two-yearly fee that is probably too steep for most MUSH
  Gods. Instead of using a commercial CA, you can generate a
  self-signed certificate by changing step 1 above to:

  $ openssl req -new -x509 -days 3650 -out mymush.crt -keyout temp.key -passin pass:foobar

  A self-signed certificate is free, but clients that attempt to
  validate certificates will fail to validate a self-signed
  certificate unless the user manually installs the certificate in
  their client and configures it to be trusted. How to do that is
  beyond the scope of this document, and highly client-dependent.

  Another option is to skip the use of a certificate altogether.  If
  you don't provide an ssl_private_key_file, the server will only
  accept connections from clients that are willing to use the
  anonymous Diffie-Hellman cipher; it is unknown which clients are
  configured to offer this. This provides clients with no security
  that they are actually connecting to your server, and exposes them
  to a man-in-the-middle attack, but requires no work on your part at
  all.

  Hosting providers or other parties may one day provide CA service to
  PennMUSHes for free. When they do, you'll have to install those CAs'
  certificates in your client as trusted in order to have the server's
  certificate validate, but if a few CAs certify many MUSHes, this is
  efficient.


V. Using client certificates for authentication

  If you provide PennMUSH with a file containing the certificates of
  trusted CAs (using the ssl_ca_file directive in mush.cnf), it will,
  by default, request that clients present certificates when they
  connect.  Clients that do not present certificates will still be
  allowed to connect (unless ssl_require_client_cert is enabled).
 
  Clients that do present certificates must present certificates
  signed by a trusted CA, or they will be disconnected. Both valid and
  invalid certificates are logged (to connect.log and netmush.log,
  respectively).

  If you were really serious about this, you probably would issue your
  own certs and not allow Verisign, etc. certs. You'd probably want to
  have the server validate extra attributes on each client cert, which
  should probably include the player's dbref and creation time. This
  is left as an exercise for the reader for now.

VI. Legal issues

  OpenSSL is used in PennMUSH and may be redistributed with PennMUSH
  under the following license(s):

  OpenSSL License
  ---------------

/* ====================================================================
 * Copyright (c) 1998-2001 The OpenSSL Project.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
 *
 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    openssl-core@openssl.org.
 *
 * 5. Products derived from this software may not be called "OpenSSL"
 *    nor may "OpenSSL" appear in their names without prior written
 *    permission of the OpenSSL Project.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
 *
 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This product includes cryptographic software written by Eric Young
 * (eay@cryptsoft.com).  This product includes software written by Tim
 * Hudson (tjh@cryptsoft.com).
 *
 */

 Original SSLeay License
 -----------------------

/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
 * All rights reserved.
 *
 * This package is an SSL implementation written
 * by Eric Young (eay@cryptsoft.com).
 * The implementation was written so as to conform with Netscapes SSL.
 * 
 * This library is free for commercial and non-commercial use as long as
 * the following conditions are aheared to.  The following conditions
 * apply to all code found in this distribution, be it the RC4, RSA,
 * lhash, DES, etc., code; not just the SSL code.  The SSL documentation
 * included with this distribution is covered by the same copyright terms
 * except that the holder is Tim Hudson (tjh@cryptsoft.com).
 * 
 * Copyright remains Eric Young's, and as such any Copyright notices in
 * the code are not to be removed.
 * If this package is used in a product, Eric Young should be given attribution
 * as the author of the parts of the library used.
 * This can be in the form of a textual message at program startup or
 * in documentation (online or textual) provided with the package.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *    "This product includes cryptographic software written by
 *     Eric Young (eay@cryptsoft.com)"
 *    The word 'cryptographic' can be left out if the rouines from the library
 *    being used are not cryptographic related :-).
 * 4. If you include any Windows specific code (or a derivative thereof) from 
 *    the apps directory (application code) you must include an acknowledgement:
 *    "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
 * 
 * THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * 
 * The licence and distribution terms for any publically available version or
 * derivative of this code cannot be changed.  i.e. this code cannot simply be
 * copied and put under another distribution licence
 * [including the GNU Public Licence.]
 */