Merge branch 'master' of github.com:keithduncan/iam-ssh-agent

Author: keithduncan

README.md

@@ -5,7 +5,7 @@ permitted ssh identities.
 
 `iam-ssh-agent` is designed to be used in less trusted continuous integration
 environments where you want to use an ssh key to clone source control
-repositories without granting access to the raw key material.
+repositories without providing the raw key material.
 
 `iam-ssh-agent` is split into two components: a binary that binds a unix domain
 socket with the ssh-agent protocol, and a serverless API that uses API Gateway
@@ -26,6 +26,16 @@ For development and testing:
 - [`/client`](client) a node package used for testing the ssh-agent
 implementation and comparing output to other ssh-agent implementations.
 
+## Protocol
+
+By storing the ssh private keys behind a service boundary, and providing an
+authenticated, access controlled signing service, client environments can
+authenticate without access to the ssh private keys.
+
+![](images/protocol.png)
+
+_Generated using https://sequencediagram.org/_
+
 ## Agent
 
 The agent binary should be a near drop-in replacement for existing uses of

images/protocol.png

@@ -0,0 +1,28 @@
+# https://sequencediagram.org
+
+title git clone with iam-ssh-agent
+
+git+ssh clone->(1)github.com:connect
+git+ssh clone(1)<-github.com:publickey auth
+git+ssh clone->(1)iam-ssh-agent binary: list-identities
+note over iam-ssh-agent binary,iam-ssh-agent backend:Requests signed with AWS IAM Credentials
+iam-ssh-agent binary->(1)iam-ssh-agent backend: list-identities
+#iam-ssh-agent backend->(1)DynamoDB: get ssh identities for caller
+#iam-ssh-agent backend(1)<-DynamoDB: identities
+#iam-ssh-agent backend->(1)AWS SSM Parameter Store: get public key parameters
+#iam-ssh-agent backend(1)<-AWS SSM Parameter Store: public key parameters
+iam-ssh-agent binary(1)<-iam-ssh-agent backend: public keys
+git+ssh clone(1)<-iam-ssh-agent binary: public keys
+git+ssh clone->(1)github.com: try public key
+git+ssh clone(1)<-github.com: public key accepted, sign this data
+git+ssh clone->(1)iam-ssh-agent binary: sign-data for public key
+iam-ssh-agent binary->(1)iam-ssh-agent backend: sign-data for public key
+#iam-ssh-agent backend->(1)DynamoDB: get ssh identities for caller
+#iam-ssh-agent backend(1)<-DynamoDB: identities
+#iam-ssh-agent backend->(1)AWS SSM Parameter Store: get + decrypt private key parameter for public key
+#iam-ssh-agent backend(1)<-AWS SSM Parameter Store: private key
+note right of iam-ssh-agent backend: ssh private key doesn't\nleave the service
+iam-ssh-agent binary(1)<-iam-ssh-agent backend: signature
+git+ssh clone(1)<-iam-ssh-agent binary: signature
+git+ssh clone->(1)github.com: signature
+git+ssh clone(1)<-github.com: authenticated