From 9607deb7b259499725ce1c705a1664199f51881d Mon Sep 17 00:00:00 2001
From: Daniel Roesler <diafygi@gmail.com>
Date: Mon, 19 Jan 2015 10:01:01 -0800
Subject: added how-to-use section and table of contents

---
 README.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 72 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 4aeafae..7152cae 100644
--- a/README.md
+++ b/README.md
@@ -26,14 +26,24 @@ very minimal commands for you to run to complete the requirements. There is only
 one command that needs to be run as root on your server and it is a very simple
 python https server that you can inspect for yourself before you run it.
 
-###Donate
+##Table of Contents
+
+* [Donate](#donate)
+* [Prerequisites](#prerequisites)
+* [How to use the script](#how-to-use-the-script)
+* [Example Use](#example-use)
+* [How to use the signed https certificate](#how-to-use-the-signed-https-certificate)
+* [Demo](#demo)
+* [Feedback/Contributing](#feedbackcontributing)
+
+##Donate
 
 If this script is useful to you, please donate to the EFF. I don't work there,
 but they do fantastic work.
 
 [https://eff.org/donate/](https://eff.org/donate/)
 
-###Prerequisites
+##Prerequisites
 
 * openssl
 * python
@@ -42,9 +52,60 @@ You will also need to transfer the test key and certificate to your server
 temporarily. The command printed out uses `scp` for that, but you can use any
 secure transfer program.
 
-###Example Use
+##How to use the script
+
+You run the script using python and passing in the path to your CSR (i.e.
+`python sign_csr.py /path/to/cert.csr`). The path can be relative or absolute.
+
+When you run the script, it will ask you do do some manual commands. It has to
+ask you to do these because it doesn't know your private key or have access to
+your server. You can edit the manual commands to fit your situation (e.g. if
+your sudo user is different or private key is in a different location).
+
+NOTE: When the script asks you to run these manual commands, you need to run
+them in a separate terminal window. You need to keep the script open while you
+run them. They sign temporary test files that the script created, so if you exit
+or continue the script before you run the commands, those test files will be
+destroyed before they can be used correctly (and you'll have to run the script
+again).
+
+The `test_*` files are temporary files automatically generated by the script and
+will be destroyed when the script stops. They only contain test certificates and
+signatures.
+
+###Help text
+```
+user@hostname:~$ python sign_csr.py --help
+usage: sign_csr.py [-h] csr_path
+
+Get a SSL certificate signed by a Let's Encrypt (ACME) certificate authority and
+output that signed certificate. You do NOT need to run this script on your
+server and this script does not ask for your private key. It will print out
+commands that you need to run with your private key or on your server as root,
+which gives you a chance to review the commands instead of trusting this script.
+
+Prerequisites:
+* openssl
+* python
+
+Example: Generate a key, create a csr, and have it signed.
+--------------
+$ openssl genrsa -out priv.key 4096
+$ openssl req -new -sha256 -key priv.key -out cert.csr
+$ python sign_csr.py cert.csr > signed.crt
+--------------
+
+positional arguments:
+  csr_path    path to certificate signing request
+
+optional arguments:
+  -h, --help  show this help message and exit
+user@hostname:~$ 
+```
 
-**Commands (without output)**
+##Example Use
+
+###Commands (without output)
 ```sh
 #Generate a private key
 openssl genrsa -out priv.key 4096
@@ -62,8 +123,8 @@ python sign_csr.py cert.csr > signed.crt
 cat signed.crt
 ```
 
-**Commands (with full output)**
-```sh
+###Commands (with full output)
+```
 user@hostname:~$ openssl genrsa -out priv.key 4096
 Generating RSA private key, 4096 bit long modulus
 ....................................................................++
@@ -183,8 +244,8 @@ vU193yL7w7n/bMVCw5FO/1t/Ba1xMRxWjPkSaOAk7fVjOjo6M70=
 user@hostname:~$ 
 ```
 
-**Manual Commands** (the stuff the script asked you to do in a 2nd terminal)
-```sh
+###Manual Commands (the stuff the script asked you to do in a 2nd terminal)
+```
 user@hostname:~$ #Step 1: Sign the needed files
 user@hostname:~$ openssl dgst -sha256 -sign priv.key -out test_XhYOdY.msgsig test_vuK3N0.msg
 user@hostname:~$ openssl dgst -sha256 -sign priv.key -out test_Y5jK3k.dersig test_dQe_Zk.der
@@ -217,7 +278,7 @@ user@hostname:~$
 ```
 
 
-###How to use the signed certificate
+##How to use the signed https certificate
 
 The signed https certificate that is output by this script can be used along
 with your private key to run an https server. You just security transfer (using
@@ -245,13 +306,13 @@ server {
 }
 ```
 
-###Demo
+##Demo
 
 Here's a website that is using a certificate signed using `sign_csr.py`:
 
 [https://letsencrypt.daylightpirates.org/](https://letsencrypt.daylightpirates.org/)
 
-###Feedback/Contributing
+##Feedback/Contributing
 
 I'd love to receive feedback, issues, and pull requests to make this script
 better. The script itself, `sign_csr.py`, is less than 300 lines of code, so
-- 
cgit v1.2.3