summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Roesler <diafygi@gmail.com>2015-01-19 10:01:01 -0800
committerDaniel Roesler <diafygi@gmail.com>2015-01-19 10:01:01 -0800
commit9607deb7b259499725ce1c705a1664199f51881d (patch)
tree1a3672134b12c12c19691862ea6ba3d964c94d7b
parentf6f22e5e2a36cac3bbfb6393910fce636e0788ca (diff)
added how-to-use section and table of contents
-rw-r--r--README.md83
1 files 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