Various tweaks to example documentation & helpers.

Fixed the "starting" URL referenced in README - /whoami does not
exist any more, so following the instructions gave a "Not Found"
error.

Re-ordered the README sections to put things needed most often or
by more users up front; moved things most people will not need to
know towards the end.  (Very little content is new/changed; most
is just rearranged.)

Updated create_key.sh to be more test-friendly, and document how
to deploy newly generated keys; added a pointer to it in README.

2 files changed, 39 insertions, 16 deletions

diff --git a/example/README b/example/README
index 38045535..9be30b5a 100644
--- a/example/README
+++ b/example/README
@@ -2,14 +2,22 @@ This is a very simple setup just to check that all your gear are in order.
 
 The setup consists of one IdP and one SP, in idp2/ and sp-wsgi/ respectively.
 
-(There are alternate IdP and SP configs in idp2_repoze/ and sp-repoze/ that
-are still in flux; do not use them unless you know what you are doing.)
+To run the setup do:
+
+  ./all.sh start
+
+and then use your favourite webbrowser to look at "http://localhost:8087/"
+
+To shut it down do:
+
+  ./all.sh stop
 
 The IdP authenticates users using a dictionary built in to idp2/idp.py;
 look for the dictionary called PASSWD inside that file.
 
 Other metadata about the accounts (names, email addresses, etc) are
-stored in idp2/idp_user.py.
+stored in idp2/idp_user.py.  (Note, not all accounts have all such data
+defined.)
 
 The username:password pairs in PASSWD:
 
@@ -20,18 +28,13 @@ upper:crust
 
 The SP doesn't do anything but show you the information that the IdP sent.
 
-To make it easy, for me :-), both the IdP and the SP uses the same keys.
-
-To run the setup do
-
-./all.sh start
-
-and then use your favourite webbrowser to look at "http://localhost:8087/whoami"
-
 Note, the listeners are all configured to bind to localhost (127.0.0.1) only.
 If you want to be able to connect to them externally, grep "HOST = '127.0.0.1'"
 example/*/*.py and replace 127.0.0.1 with 0.0.0.0 or a specific IP.
 
-./all.sh stop
+To make it easy, for me :-), both the IdP and the SP uses the same keys.
+To generate new keys, run create_key.sh and follow its instructions.
+
+There are alternate IdP and SP configs in idp2_repoze/ and sp-repoze/ that
+are still in flux; do not use them unless you know what you are doing.
 
-will of course stop your IdP and SP.
diff --git a/example/create_key.sh b/example/create_key.sh
index 85696cdb..4929a466 100755
--- a/example/create_key.sh
+++ b/example/create_key.sh
@@ -1,5 +1,25 @@
-openssl genrsa -des3 -out server.key 1024
+#!/bin/bash
+
+cat <<EOF
+
+Generating a new test key and certificate.  To change the defaults offered
+by openssl, edit your openssl.cnf, such as /etc/ssl/openssl.cnf
+
+EOF
+
+openssl genrsa -out server.key 1024
+chmod 600 server.key
 openssl req -new -key server.key -out server.csr
-cp server.key server.key.org
-openssl rsa -in server.key.org -out server.key
 openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
+
+cat <<EOH
+
+Now to enable these new keys, do:
+
+  cp server.key idp2/pki/mykey.pem
+  cp server.crt idp2/pki/mycert.pem
+
+  cp server.key sp-wsgi/pki/mykey.pem
+  cp server.crt sp-wsgi/pki/mycert.pem
+
+EOH