From 16a6fd163bc2ff79c84122edf66538416e28f2f6 Mon Sep 17 00:00:00 2001
From: tgic <farmer1992@gmail.com>
Date: Mon, 8 Dec 2014 16:45:22 +0800
Subject: [PATCH] add ssh public key sign again

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)

diff --git a/README.md b/README.md
index 3a84527d..96e2363c 100644
--- a/README.md
+++ b/README.md
@@ -51,3 +51,100 @@ connect to github.com:22
 $ ssh 0 -p 2222 -l github
 Permission denied (publickey).
 ```
+
+
+## Configuration 
+
+```
+$ sshpiperd -h
+  -h=false: Print help and exit
+  -i="/etc/ssh/ssh_host_rsa_key": Key file for SSH Piper
+  -l="0.0.0.0": Listening Address
+  -p=2222: Listening Port
+  -w="/var/sshpiper": Working Dir
+```
+
+### Files inside `Working Dir`
+
+`Working Dir` is a `/home`-like directory. 
+SSHPiperd read files from `workingdir/[username]/` to know upstream's configuration.
+
+e.g.
+
+```
+workingdir tree
+
+.
+├── github
+│   └── sshpiper_upstream
+└── linode
+    └── sshpiper_upstream
+```
+
+when `ssh sshpiper_host -l github`, 
+sshpiper reads `workingdir/github/sshpiper_upstream` and the connect to the upstream. 
+
+#### User files
+
+ * sshpiper_upstream
+ 
+   one line file `upstream_host:port` e.g. `github.com:22`
+
+ * authorized_keys
+  
+   OpenSSH format `authorized_keys` (see `~/.ssh/authorized_keys`). Used for `publickey sign again(see below)`.
+
+ * id_rsa
+ 
+   RSA key for `publickey sign again(see below)`.
+
+
+#### Publickey sign again
+
+During SSH publickey auth, [RFC 4252 Section 7](http://tools.ietf.org/html/rfc4252#section-7),
+ssh client sign `session_id` and some other data using private key into a signature `sig`.
+This is for server to verify that the connection is from the client not `the man in the middle`.
+
+However, sshpiper actually holds two ssh connection, and it is doing what `the man in the middle` does.
+the two ssh connections' `session_id` will never be the same, because they are hash of the shared secret. [RFC 4253 Section 6.6](http://tools.ietf.org/html/rfc4253#section-6).
+
+
+To support publickey auth, sshpiper will modify the `sig` using a private key (`id_rsa`) in the `workingdir/[username]/`.
+
+How this work
+
+```
++------------+        +------------------------+                       
+|            |        |                        |                       
+|   client   |        |   SSH Piper            |                       
+|   PK_X     +-------->      |                 |                       
+|            |        |      v                 |                       
+|            |        |   Check PK_X           |                       
++------------+        |   in authorized_keys   |                       
+                      |      |                 |                       
+                      |      |                 |     +----------------+
+                      |      v                 |     |                |
+                      |   sign agian           |     |   server       |
+                      |   using PK_Y  +-------------->   check PK_Y   |
+                      |                        |     |                |
+                      |                        |     |                |
+                      +------------------------+     +----------------+
+```
+
+e.g.
+
+on client 
+
+```
+ssh-copy-id -i PK_X test@sshpiper
+```
+
+on ssh piper server
+
+```
+ln -s ~test/.ssh/authorized_keys workingdir/test/authorized_keys
+ssh-keygen -N '' -f workingdir/test/id_rsa  # this is PK_Y
+ssh-copy-id -i workingdir/test/id_rsa test@server
+```
+
+now `ssh test@sshpiper -i -i PK_X`, sshpiper will send `PK_Y` to server instead of `PK_X`.