Fix README.

Signed-off-by: Raphaël Barrois <raphael.barrois@polytechnique.org>

1 files changed, 75 insertions, 43 deletions

diff --git a/README b/README
index 3c50572..d20f8ff 100644
--- a/README
+++ b/README
@@ -1,4 +1,6 @@
-                    == Author & Version ==
+Author & Version
+================
+
 YubiServe has been written by Alessio Periloso <mail *at* periloso.it>
 Version 1.0: 21/05/2010
 Version 2.0: 19/11/2010
@@ -7,7 +9,9 @@ Version 3.0: 14/12/2010
 Version 3.1: 24/03/2011
 + Fixed issue #3, #4, #5, #6
 
-                      == Description ==
+
+Description
+===========
 This simple service allows to authenticate Yubikeys and OATH Tokens using
 only a small sqlite database (the mysql support is optional!)
 The code has been released under GNU license (license into LICENSE file)
@@ -17,29 +21,41 @@ The project is divided into two parts:
  - The validation server (yubiserve.py)
 
 
-                       == Installation ==
+Installation
+============
+
 Installation is pretty simple, you just have to install few python packages:
-Under Debian, you can run:
-apt-get install python python-crypto python-openssl
-If you want to add the sqlite support, you should run:
-apt-get install python-sqlite
-Or, if you want to add the mysql support, you should run:
-apt-get install python-mysqldb
-If you chosen the mysql support, you must create a database and create the
+Under Debian, you can run::
+
+  apt-get install python python-crypto python-openssl
+
+If you want to add the sqlite support, you should run::
+
+  apt-get install python-sqlite
+
+Or, if you want to add the mysql support, you should run::
+
+  apt-get install python-mysqldb
+
+If you chose the mysql support, you must create a database and create the
 tables. The mysql dump is at src/dump.mysql.
+
 Then, you have to generate the certificate for ssl validation, so if you don't
 already have a certificate you have to issue the following command to self-sign
-one:
-openssl req -new -x509 -keyout yubiserve.pem -out yubiserve.pem -days 365 -nodes
+one::
 
-A good idea would be taking a look at yubiserve.cfg, to configure the validation server settings.
+  openssl req -new -x509 -keyout yubiserve.pem -out yubiserve.pem -days 365 -nodes
+
+A good idea would be taking a look at ``yubiserve.cfg'', to configure the validation server settings.
 
 After installing the needed packages, you just need to extract the files
 to a directory, add the keys and launch the server (or, if you prefer
 you can launch the server before adding the keys, it doesn't matter).
 
 
-              == The database management tool ==
+The database management tool
+============================
+
 The database management tool helps you to manage keys in the database.
 For detailed help, run the database management tool with ./dbconf.py
 
@@ -49,8 +65,9 @@ server responses.
 Everything is managed through nicknames, to make keys easy to remember
 who belong to.
 
-For example, to add a new yubikey, write:
-./dbconf.py -ya alessio vvkdtkjureru 980a8608b307 f1dc9c6585d600d06f9aae1abea2969e
+For example, to add a new yubikey, write::
+
+  ./dbconf.py -ya alessio vvkdtkjureru 980a8608b307 f1dc9c6585d600d06f9aae1abea2969e
 
 In this example, 'alessio' is the key nickname, 'vvkdtkjureru' is the
 key public identity (the one you can see at the beginning of your OTPs),
@@ -58,42 +75,52 @@ key public identity (the one you can see at the beginning of your OTPs),
 you program your key), and the last parameter is the AES Key.
 
 
-To add a new OATH/HOTP:
-./dbconf.py -ha alessio 4rvn24642402 f03ddacdfebb6396f60d7045f41de68f5c5e1c3f
+To add a new OATH/HOTP::
+
+  ./dbconf.py -ha alessio 4rvn24642402 f03ddacdfebb6396f60d7045f41de68f5c5e1c3f
 
 In this other example, 'alessio' is still the nickname, '4rvn24642402' is
 the public identity of the token (it could be also 1, 2, 'alessio' or
 whatever you want; the Yubico implementation is 12 characters long)
 
 
-To add a new API key:
-./dbconf.py -aa alessio
+To add a new API key::
+
+  ./dbconf.py -aa alessio
 
 When you add a new API key, the configuration tool will return both
 the api key (ex. 'UkxFMnNFNTV4clRYUExSOWlONzQ=') and the API key id
 meant to be used later in your queries to the Yubiserve validation server.
 
 
-             == The Yubiserve Validation Server ==
+The Yubiserve Validation Server
+===============================
+
+
 Understanding how to use the Yubiserve web application is pretty simple.
 You just have to run it (./yubiserve.py) and send your queries through
 HTTP GET connections.
+
 The default listening port is 8000, the default listening ip is 0.0.0.0
 (so you can connect to it from other machines). If you need it to answer
 only from local machine, you can change the ip to 127.0.0.1.
+
 The ssl port is by default the next one, so if the http validation server
 answers on port 8000, the ssl will answer on port 8001.
+
 Anyway, everything is easily customizable modifying the yubiserve.py file
 and changing the variables "yubiservePORT" for the HTTP port, "yubiserveSSLPORT"
 for the SSL port, "yubiserveHOST" for the listening ip.
 When you connect to the server (ex. http://192.168.0.1:8000/), it will
 answer with a simple page, asking you Yubico Yubikeys OTPs or OATH/HOTP
 tokens.
+
 The Yubico Yubikey needs only one parameter: the OTP.
 The OATH/HOTP tokens needs two parameters: the OTP itself (6 or 8 digits)
 and the Token Identifier. The token identifier can be any character string
 you prefer, or, according to the standard OATH implementation, the preceding
 string to the OTP. The Yubico implementation follows this standard.
+
 The Yubiserve Validation Server, according to the standard, will try to
 find the Token Identifier preceding the OTP. If the string is found, the
 OTP will be verified according to that string; in case of LCD tokens,
@@ -101,29 +128,31 @@ the string is not automatically added, so you will need to insert your ID
 in the second box to allow the Validation Server to find your own identity.
 
 
-          == Querying the Yubiserve Validation Server ==
+Querying the Yubiserve Validation Server
+========================================
+
 Querying the Yubiserve Validation Server is pretty simple.
 For Yubico Yubikeys, you will need to send a HTTP GET connection to:
 http://<server ip>:<server port>/wsapi/2.0/verify?otp=<your otp>
 ex.: http://192.168.0.1:8000/wsapi/2.0/verify?otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj
 This way you will try to authenticate to it, the simplest way possible.
-The response will be something like:
+The response will be something like::
 
-otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj
-status=OK
-t=2010-11-20T23:54:35
-h=
+  otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj
+  status=OK
+  t=2010-11-20T23:54:35
+  h=
 
 As you can see, the 'h' parameter is not set, and this is because we didn't use
 the signature through API Key. To use it, just add the 'key=<api key id>'
 parameter we had when we added the API Key.
 ex.: http://192.168.0.1:8000/wsapi/2.0/verify?otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj&id=1
-This time the response will be like:
+This time the response will be like::
 
-otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj
-status=OK
-t=2010-11-21T00:00:03
-h=6lrhQPKo1I/RQA1KPnjpuiOvVMc=
+  otp=vvnjbbkvjbcnhiretjvjfebbrdgrjjchdhtbderrdbhj
+  status=OK
+  t=2010-11-21T00:00:03
+  h=6lrhQPKo1I/RQA1KPnjpuiOvVMc=
 
 To check the server signature, check the source code (you will have to do the
 exact same procedure to generate it and then just check if they are equal), or
@@ -139,31 +168,34 @@ So, you will have to query, via HTTP GET, the following address:
 http://<server ip>:<server port>/wsapi/2.0/oathverify?otp=<your otp>&publicid=<token id>
 ex.: http://192.168.0.1:8000/wsapi/2.0/oathverify?otp=80l944311056173483
 ex.: ex.: http://192.168.0.1:8000/wsapi/2.0/oathverify?otp=173483&publicid=80l944311056
+
 Both the examples works the same way: in the first case, the Token Identifier was
 inside the generated OTP (like in Yubico Yubikey implementation), in the second case
 an authentication through a LCD Token was made, so the Yubiserve needed to know who
 the token belonged to, and the publicid parameter was added.
-The response, like Yubico Yubikey queries, is the following:
+The response, like Yubico Yubikey queries, is the following::
 
-otp=80l944311056173483
-status=OK
-t=2010-11-21T00:04:59
-h=
+  otp=80l944311056173483
+  status=OK
+  t=2010-11-21T00:04:59
+  h=
 
 The 'h' parameter is not set, because we didn't specified the API Key id. To use the
 server signature, we will need to add the 'id' parameter, like in the following query:
 ex.: http://192.168.1.2:8000/wsapi/2.0/oathverify?otp=80l944311056173483&id=1
 ex.: http://192.168.0.1:8000/wsapi/2.0/oathverify?otp=173483&publicid=80l944311056&id=1
 
-And this would be the the response:
+And this would be the the response::
+
+  otp=80l944311056173483
+  status=OK
+  t=2010-11-21T00:10:56
+  h=vYoG9Av8uG6OqVkmMFuANi4fyWw=
 
-otp=80l944311056173483
-status=OK
-t=2010-11-21T00:10:56
-h=vYoG9Av8uG6OqVkmMFuANi4fyWw=
 
+Final thoughts
+==============
 
-                                == Final thoughts ==
 That's all. Pretty simple, huh?
 Of course you can add new keys while the server is already running, without needing it
 to restart, and of course multiple queries a time are allowed, that's why the server