Rename README -> README.md.

1 files changed, 72 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..05b7176
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+<!--- -*- mode: markdown; coding: utf-8 -*- --->
+
+# Mulky IMAP BrowserID Primary
+
+## Introduction
+
+This software provides a simple BrowserID primary (authenticating
+party) based on an existing local IMAP server setup.  Users use their
+IMAP login and password to authenticate themselves as the owner of
+their email address.
+
+The primary is implemented as a set of simple CGI scripts.
+
+
+## Assumptions About Your E-Mail Setup
+
+This software assumes that email addresses can be resolved to user
+names by way of `/etc/aliases` and that the user names provided
+therein are identical to those accepted by your IMAP server for
+purposes of authenticating.
+
+If this is not true for your setup, you will need to hack the source
+code.
+
+
+## Installation
+
+### Prerequisites
+
+The following CPAN modules need to be installed:
+
+ * `CGI`
+ * `CGI::Fast`
+ * `CGI::Session`
+ * `common::sense`
+ * `Crypt::OpenSSL::RSA`
+ * `File::Slurp`
+ * `JSON`
+ * `MIME::Base64`
+ * `Mail::ExpandAliases`
+ * `Mail::IMAPTalk`
+ * `Modern::Perl`
+ * `Time::HiRes`
+
+### Key Setup and jQuery Download
+
+In order to generate an RSA private key and download necessary
+third-party components, run `setup.sh`.
+
+`setup.sh` will also generate a `browserid.json` file and prompt you
+to put it wherever your web server will be able to serve it as
+`/.well-known/browserid`.  **It is very important to do this now**,
+because `browserid.org` will look at that location and *cache* the
+response, even if it is just a 404.
+
+
+## License
+
+Copyright 2012, Matthias Andreas Benkard.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.